src/ops-types/claims.ts

Functions

None: it only declares types or values.

Imports

It imports no other module of this repo. Imported by src/job-claims-read.ts, src/job-claims.ts, src/portal-claims.ts.

Source

1// ---------------------------------------------------------------------------
2// Claims apart from verified outcomes (migrations/0023_job_claims.sql). The
3// `capsid_admin_read_claims` tool and GET /portal/api/claims return these, from the same readers
4// (src/job-claims-read.ts). Every column is as stored: JSON columns stay JSON text,
5// and NULL stays null, because NULL is not zero.
6
7export type ClaimsAgreement = "agree" | "disagree" | "unclaimed" | "unchecked";
8
9export interface ClaimsFilter {
10  namespace: string | null;
11  // The claiming agent's actor string, e.g. agent:sample-driver.
12  agent: string | null;
13  // ISO 8601, inclusive lower bound and exclusive upper bound on each row's own time
14  // (recorded_at for claims and evaluations, at for touches).
15  since: string | null;
16  until: string | null;
17}
18
19export interface ClaimsAgreementCounts {
20  agree: number;
21  disagree: number;
22  unclaimed: number;
23  unchecked: number;
24}
25
26interface ClaimsTouchSummary {
27  count: number;
28  by_kind: Record<string, number>;
29  by_actor_kind: Record<string, number>;
30  // Over the touches that carry a wait. Null when none does: no wait was measured,
31  // which is not a wait of zero.
32  waits: number;
33  waited_ms_total: number | null;
34  waited_ms_median: number | null;
35}
36
37export interface ClaimsGroup {
38  // Null for touches on a job no agent has made a claim on yet.
39  agent: string | null;
40  namespace: string;
41  // Distinct jobs with a claim, and claim rows.
42  jobs: number;
43  claims: number;
44  // Per evaluation name (pr_merged, prs_opened, ...), the claim-to-verified agreement.
45  evaluations: Record<string, ClaimsAgreementCounts>;
46  touches: ClaimsTouchSummary;
47}
48
49// One ended wait: a touch with a waited_ms, tied to the gate it ended. gate_class is a
50// class of capsid/policy/gates.md (compound commands joined with "+"), "needs_human"
51// when the gate's command matched none or recorded no command, or "unreadable_gate"
52// when the gate row's detail was not the JSON the writer produces.
53export interface ClaimsWaitRow {
54  namespace: string;
55  gate_class: string;
56  // Who ended the wait: human, policy, seat and so on (job_touches.actor_kind).
57  ended_by: string;
58  waits: number;
59  waited_ms_total: number;
60  waited_ms_median: number;
61}
62
63// Cost, tokens and active time for one source, summed over the rows that carried it.
64// Every figure is null when no row carried it, never 0.
65export interface ClaimsUsageTotals {
66  // Jobs (telemetry) or claims (reported) that carried any usage at all.
67  rows: number;
68  cost_usd: number | null;
69  active_seconds: number | null;
70  tokens_input: number | null;
71  tokens_output: number | null;
72  tokens_cache_read: number | null;
73  tokens_cache_creation: number | null;
74}
75
76// Per namespace, the two sources side by side and never added together: telemetry from
77// job_outcomes (src/job-outcomes.ts readJobUsage) and what the agent reported in
78// claim.usage. A job can appear in both, so a sum across them would count it twice.
79export interface ClaimsUsageRow {
80  namespace: string;
81  telemetry: ClaimsUsageTotals;
82  reported: ClaimsUsageTotals;
83}
84
85export interface ClaimsAggregate {
86  filter: ClaimsFilter;
87  groups: ClaimsGroup[];
88  // Ended waits by namespace, gate class and who ended them, longest total first.
89  waits: ClaimsWaitRow[];
90  usage: ClaimsUsageRow[];
91  // Each bounded read that hit its bound, by name. Empty means the answer is whole.
92  truncated: string[];
93}
94
95export interface JobClaimRow {
96  id: number;
97  job_id: string;
98  action: "complete" | "fail" | "block";
99  agent: string;
100  namespace: string;
101  raw: string;
102  prs_opened_urls: string | null;
103  prs_merged_urls: string | null;
104  prs_opened: number | null;
105  prs_merged: number | null;
106  commits: number | null;
107  files_changed: number | null;
108  tests_added: number | null;
109  tests_run: number | null;
110  tests_passed: number | null;
111  tests_failed: number | null;
112  tests_result: string | null;
113  deploy_state: string | null;
114  files_touched: string | null;
115  model_id: string | null;
116  client_name: string | null;
117  client_version: string | null;
118  permission_mode: string | null;
119  capsid_sha: string | null;
120  recorded_at: string;
121}
122
123export interface JobEvaluationRow {
124  id: number;
125  job_id: string;
126  claim_id: number | null;
127  name: string;
128  score_value: number | null;
129  score_label: "pass" | "fail" | "unknown";
130  claimed: string | null;
131  verified: string | null;
132  agreement: ClaimsAgreement;
133  evaluator: "worker" | "model" | "human";
134  evaluator_id: string;
135  explanation: string | null;
136  recorded_at: string;
137}
138
139export interface JobTouchRow {
140  id: number;
141  job_id: string;
142  namespace: string;
143  kind: string;
144  actor: string;
145  actor_kind: string;
146  waited_ms: number | null;
147  detail: string | null;
148  at: string;
149}
150
151export interface ClaimsJob {
152  job: { id: string; namespace: string; title: string; status: string; claimed_by: string | null };
153  // The job_outcomes row as stored, or null when the job has not ended.
154  outcome: Record<string, unknown> | null;
155  // Oldest first, each at most `limit`.
156  claims: JobClaimRow[];
157  evaluations: JobEvaluationRow[];
158  touches: JobTouchRow[];
159  limit: number;
160  truncated: string[];
161}
162
163// GET /portal/api/claims?namespace=&agent=&since=&until=  -> PortalClaimsAggregate
164// GET /portal/api/claims?job=<id>                         -> PortalClaimsJob (404 JSON for no such job)
165// A since or until that is not an ISO time is a text/plain 400.
166export interface PortalClaimsAggregate extends ClaimsAggregate {
167  generated: string;
168}
169
170export interface PortalClaimsJob extends ClaimsJob {
171  generated: string;
172}