crysk 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/README.md +27 -23
  2. package/dist/SKILL-1q3658n0.md +74 -0
  3. package/dist/SKILL-25j4q9b8.md +143 -0
  4. package/dist/SKILL-4747bhne.md +143 -0
  5. package/dist/SKILL-4jc3sv23.md +74 -0
  6. package/dist/SKILL-c0492rch.md +540 -0
  7. package/dist/SKILL-d1nzkhhr.md +74 -0
  8. package/dist/SKILL-f8p7kvx0.md +143 -0
  9. package/dist/SKILL-gxd45g38.md +553 -0
  10. package/dist/SKILL-rec41991.md +66 -0
  11. package/dist/SKILL-zze8zj5g.md +536 -0
  12. package/dist/cli.js +24658 -24654
  13. package/dist/index.js +492 -463
  14. package/dist/opencode-ci-qrcv7a99.md +106 -0
  15. package/dist/opencode-ci-rdpcc7xc.md +106 -0
  16. package/dist/opencode-ci-yt0k74t0.md +106 -0
  17. package/dist/workflow-andv2dvm.yml +158 -0
  18. package/package.json +1 -1
  19. package/prompts/default/PROVENANCE.md +1 -0
  20. package/skills/crysk/SKILL.md +6 -6
  21. package/skills/crysk-ci-setup/SKILL.md +32 -33
  22. package/skills/crysk-ci-setup/assets/workflow.yml +5 -10
  23. package/skills/crysk-ci-setup/references/ci-admission.md +5 -5
  24. package/skills/crysk-ci-setup/references/opencode-ci.md +6 -6
  25. package/skills/crysk-loop/SKILL.md +37 -54
  26. package/skills/crysk-pr/SKILL.md +1 -1
  27. package/src/asset-manifest.ts +0 -6
  28. package/src/assets.ts +1 -4
  29. package/src/brand.ts +20 -30
  30. package/src/ci/gates.ts +155 -201
  31. package/src/ci/outcome.ts +4 -31
  32. package/src/ci/platform-limits.ts +135 -0
  33. package/src/ci/platform-report.ts +212 -126
  34. package/src/ci/platform.ts +28 -26
  35. package/src/ci/reporter.ts +25 -26
  36. package/src/ci/review-admission.ts +1 -2
  37. package/src/ci/review-levels.ts +12 -53
  38. package/src/ci/setup.ts +96 -66
  39. package/src/ci/trace-bundle.ts +11 -27
  40. package/src/ci/trace-transcripts.ts +4 -6
  41. package/src/ci/trigger.ts +3 -5
  42. package/src/cli.ts +6 -5
  43. package/src/commands/ci-setup-questions.ts +2 -55
  44. package/src/commands/ci-setup.ts +2 -26
  45. package/src/commands/triage.ts +131 -38
  46. package/src/commands/usage.ts +0 -1
  47. package/src/compare/compare.ts +3 -3
  48. package/src/compare/floor-test.ts +30 -201
  49. package/src/config/config.ts +6 -30
  50. package/src/diversity/accounting.ts +0 -26
  51. package/src/diversity/benchmark.ts +1 -17
  52. package/src/diversity/identity.ts +0 -14
  53. package/src/diversity/pipeline-integration.ts +0 -29
  54. package/src/doctor.ts +3 -6
  55. package/src/execution/claude-session-trace.ts +7 -2
  56. package/src/execution/contracts.ts +15 -9
  57. package/src/execution/harness.ts +165 -187
  58. package/src/execution/spend-limiter.ts +39 -131
  59. package/src/execution/usage-facts.ts +397 -0
  60. package/src/execution/usage-normalized.ts +33 -86
  61. package/src/harness/materiality-judge.ts +0 -5
  62. package/src/harness/pipeline-plan.ts +0 -3
  63. package/src/harness/replay-rows.ts +0 -5
  64. package/src/harness/route-runner.ts +2 -2
  65. package/src/harness/single-step.ts +3 -9
  66. package/src/index.ts +1 -1
  67. package/src/mcp/preflight.ts +2 -2
  68. package/src/model/catalog.ts +1 -3
  69. package/src/model/free-discovery.ts +11 -78
  70. package/src/model/model-name.ts +14 -4
  71. package/src/model/profiles/claude.ts +1 -2
  72. package/src/model/profiles/openai.ts +1 -2
  73. package/src/model/profiles.ts +1 -2
  74. package/src/model/provider-capabilities.ts +16 -55
  75. package/src/model/routing.ts +39 -36
  76. package/src/pr/admission.ts +6 -6
  77. package/src/pr/answered-findings.ts +8 -4
  78. package/src/pr/ci-publish.ts +0 -2
  79. package/src/pr/discovery.ts +4 -25
  80. package/src/pr/plan.ts +40 -121
  81. package/src/pr/pr-status.ts +14 -2
  82. package/src/pr/preflight.ts +15 -12
  83. package/src/pr/publish-outcome.ts +1 -19
  84. package/src/pr/review-pr.ts +10 -47
  85. package/src/pr/target.ts +76 -82
  86. package/src/production-runtime.ts +52 -114
  87. package/src/progress.ts +0 -54
  88. package/src/rereview/prepare.ts +4 -1
  89. package/src/rereview/state.ts +1 -1
  90. package/src/review/boundary.ts +4 -8
  91. package/src/review/drafts.ts +3 -3
  92. package/src/review/findings-conformance.ts +1 -1
  93. package/src/review/findings.ts +0 -4
  94. package/src/review/pipeline.ts +57 -395
  95. package/src/review/preflight.ts +162 -201
  96. package/src/review/prompt-set.ts +0 -2
  97. package/src/review/report.ts +2 -162
  98. package/src/review/review.ts +16 -65
  99. package/src/review/route-preflight.ts +3 -35
  100. package/src/review/run.ts +37 -73
  101. package/src/review/size-gate.ts +3 -3
  102. package/src/review/spec.ts +6 -11
  103. package/src/review/step-runner.ts +4 -4
  104. package/src/runner-authority.ts +10 -9
  105. package/src/security/credential-broker.ts +5 -6
  106. package/src/server/preflight.ts +0 -1
  107. package/src/server/server.ts +17 -6
  108. package/src/store/activity.ts +1 -2
  109. package/src/store/backfill-preflight.ts +0 -3
  110. package/src/store/backfill.ts +0 -1
  111. package/src/store/metrics-preflight.ts +4 -14
  112. package/src/store/metrics.ts +5 -5
  113. package/src/store/preflight.ts +0 -13
  114. package/src/store/store.ts +11 -12
  115. package/src/transport-registry.ts +6 -30
  116. package/src/transports/claude-code-cli.ts +149 -215
  117. package/src/transports/opencode-client.ts +4 -24
  118. package/src/transports/opencode-sdk.ts +17 -112
  119. package/src/triage/plain-reply.ts +37 -0
  120. package/src/ui/activity.ts +1 -6
  121. package/src/ui/config-edit.ts +14 -67
  122. package/src/ui/config.ts +3 -8
  123. package/src/ui/plan.ts +11 -198
  124. package/src/ui/progress.ts +3 -49
  125. package/src/ui/result.ts +18 -77
  126. package/src/ui/review-menu.ts +3 -12
  127. package/src/ui/select.ts +9 -79
  128. package/src/updater.ts +1 -1
  129. package/src/usage.ts +1 -7
  130. package/prompts/default/deep-review-parity.md +0 -152
  131. package/prompts/scout.md +0 -140
  132. package/src/ci/platform-estimate.ts +0 -111
  133. package/src/review/scout.ts +0 -323
@@ -1,47 +1,43 @@
1
- // D1-08 PR4 (§9.1): the transactional spend reservation ledger. In-memory
2
- // per run, behind an interface whose only stateful operations are CAS
1
+ // D1-08 PR4 (§9.1): the credential fence. An in-memory per-run ledger of
2
+ // reservations, behind an interface whose only stateful operations are CAS
3
3
  // transitions (design decision D7) — so a durable adapter (D1-08f) can
4
4
  // implement `SpendLedger` with zero caller changes.
5
5
  //
6
- // Wiring, corrected 2026-09-02. This header used to say "Not wired into the
7
- // harness yet; that's PR5b, per the design's own tripwire table", and it had
8
- // gone stale on both axes. PR5b landed:
9
- // `StepExecutionHarness.runAttempt` calls `reserve()` before the transport
10
- // and `finalizeReservation` applies the CAS transition `settlementFromUsage`
11
- // names (harness.ts), `runPipeline`'s `collectUnresolvedSpend` gathers the
12
- // terminal `unresolved_remote` reservations into `PipelineResult.unresolved`
13
- // (pipeline.ts), and `renderResult` prints them and marks the run's cost
14
- // figure a floor (ui/result.ts).
6
+ // platform-owned-cost T7 (S12, L7): the ledger no longer holds an amount. It
7
+ // used to reserve dollars, settle them from the provider's reported cost and
8
+ // fence a bucket when a spend could not be resolved (#279). The dollars are
9
+ // gone — the platform prices a run from the facts the engine reports — but the
10
+ // fence never needed an amount: what it protects is "an attempt on a metered
11
+ // credential whose usage the engine could not confirm is a hole in what the
12
+ // platform will price, so no new attempt runs on that credential for the rest
13
+ // of the run". That is kept, driven by usage completeness alone. Two rules
14
+ // that read a dollar figure went with the amount: the metered-zero rule (a
15
+ // metered attempt that produced output tokens and reported $0) and the
16
+ // free-nonzero rule (a free-declared route that reported a priced cost). A
17
+ // token count is not a price, so neither can be decided here any more.
15
18
  //
16
- // The second axis, which "wired into the harness" alone would still hide, and
17
- // which held on `dev` until 2026-09-02: no production composition constructed
18
- // a `SpendLedger` at all, so `this.spendLedger` was undefined on every real
19
- // run and none of the above executed. It is composed now —
20
- // `MultiProviderRunner` (production-runtime.ts) holds ONE instance for the
21
- // run, which is what makes `fencedBuckets` below a run-scoped fence rather
22
- // than a per-step no-op.
19
+ // Wiring. `StepExecutionHarness.runAttempt` calls `reserve()` before the
20
+ // transport and `finalizeReservation` applies the CAS transition
21
+ // `settlementFromUsage` names (harness.ts), `runPipeline`'s
22
+ // `collectUnresolvedSpend` gathers the terminal `unresolved_remote`
23
+ // reservations into `PipelineResult.unresolved` (pipeline.ts), and
24
+ // `renderResult` prints them (ui/result.ts). `MultiProviderRunner`
25
+ // (production-runtime.ts) holds ONE instance for the run, which is what makes
26
+ // `fencedBuckets` below a run-scoped fence rather than a per-step no-op.
23
27
  //
24
- // It is composed for METERED bindings only, and that is deliberate rather
25
- // than partial: the guarantee this ledger enforces is about dollars, and
26
- // `MultiProviderRunner.run` carries the full argument. A claude-only run
27
- // therefore records zero reservations, and the absent `reservations` key on
28
- // those steps is the truthful signal, not a gap. `ClaudeCodeRunner`
29
- // (step-runner.ts) stays ledger-free for the same reason.
30
- //
31
- // #182 follow-up: the one exception is a FREE OpenCode binding
28
+ // It is composed for METERED bindings only, plus a FREE OpenCode binding
32
29
  // (`provider_free`), which reserves too even though its capability report says
33
- // subscription. Without a reservation the free-nonzero rule above would be
34
- // dead in production — `finalizeReservation` never runs, so a flipped model
35
- // would keep spending attempts instead of fencing and failing closed. A free
36
- // step that stays free settles 0 and never fences.
30
+ // subscription. A claude-only subscription run therefore records zero
31
+ // reservations, and the absent `reservations` key on those steps is the
32
+ // truthful signal, not a gap. `ClaudeCodeRunner` (step-runner.ts) stays
33
+ // ledger-free for the same reason.
37
34
  //
38
35
  // Two couplings the spec calls out as the easiest to lose across chained
39
36
  // PRs are made TYPE-unreachable here rather than asserted at runtime:
40
37
  // 1. `settle()`'s second argument is narrowed to the "settle" arm of
41
38
  // SettlementDecision — an attempt whose usage completeness isn't
42
- // "complete" can never be handed to `settle()` as a bare number; tsc
43
- // refuses the call before any code runs (spec: "Non-Complete Usage
44
- // Never Settles As A Number").
39
+ // "complete" can never be handed to `settle()`; tsc refuses the call
40
+ // before any code runs (spec: "Non-Complete Usage Never Settles").
45
41
  // 2. `reserve()`'s second argument is a branded ReserveToken that only
46
42
  // `beginStep()` (attempt 1) or `nextCycle()` on a NON-terminal
47
43
  // RetryDisposition can produce. `nextCycle()` returns `undefined` for
@@ -51,101 +47,23 @@
51
47
 
52
48
  import { randomUUID } from "node:crypto";
53
49
  import type { RetryDisposition } from "./failure-policy";
54
- import { type NormalizedUsage, outputTokensKnown } from "./usage-normalized";
50
+ import type { NormalizedUsage } from "./usage-normalized";
55
51
 
56
52
  // ---- Coupling 1: settlement decision ----
57
53
 
58
54
  export type SettlementDecision =
59
- | { readonly kind: "settle"; readonly actualUsd: number }
60
- | {
61
- readonly kind: "unresolved";
62
- readonly knownUsd?: number;
63
- // #182 follow-up: present ONLY on the free-nonzero arm below. The
64
- // harness fail-fasts on it (terminal step failure, no retry); every
65
- // other unresolved arm stays fence-only. Optional and additive so all
66
- // existing producers/consumers keep compiling — tsc is the net.
67
- readonly reason?: "free_nonzero_cost";
68
- };
55
+ | { readonly kind: "settle" }
56
+ | { readonly kind: "unresolved" };
69
57
 
70
- // spec: "Non-Complete Usage Never Settles As A Number" — completeness other
71
- // than "complete" is ALWAYS the unresolved arm, carrying whatever cash cost
72
- // is already known (possibly none) rather than inventing a settled number.
73
- // This is the ONLY producer of SettlementDecision.
58
+ // spec: "Non-Complete Usage Never Settles" — completeness other than
59
+ // "complete" is ALWAYS the unresolved arm. This is the ONLY producer of
60
+ // SettlementDecision.
74
61
  export function settlementFromUsage(
75
62
  usage: NormalizedUsage,
76
63
  ): SettlementDecision {
77
- if (usage.completeness !== "complete") {
78
- return { kind: "unresolved", knownUsd: usage.cashCostUsd };
79
- }
80
- if (usage.cashCostUsd === undefined) {
81
- return { kind: "unresolved", knownUsd: undefined };
82
- }
83
- // 2026-09-02, the metered-zero rule: #133's under-reporting failure
84
- // arriving through the other door. #133 caught a metered route REPORTED as
85
- // a subscription and therefore priced at nothing; this catches a metered
86
- // route that reports a NUMBER, and the number is zero.
87
- //
88
- // How a zero gets here: the OpenCode client reads the provider's own cost
89
- // (`asNumber(info.cost)`, opencode-client.ts), and `asNumber` returns 0 for
90
- // 0 rather than undefined — so a provider OpenCode holds no price for, or a
91
- // custom endpoint, produces a COMPLETE usage with `cashCostUsd: 0` and
92
- // `costSource: "provider"`. Every guard above passes it, and it settles as
93
- // a truthful-looking zero wearing the provider's badge.
94
- //
95
- // The credential's billing mode discriminates, never the number: zero cash
96
- // cost IS truthful for a subscription credential (the design's own
97
- // subscription rule), and is not truthful for a metered credential that
98
- // produced output tokens. Both halves are load-bearing — dropping the mode
99
- // test would misfile every free subscription attempt as unresolved and
100
- // fence its bucket; dropping the token test would misfile a metered attempt
101
- // that never reached the provider (`noSessionUsage`, opencode-sdk.ts).
102
- //
103
- // `billingMode: "unknown"` is deliberately NOT covered: it is already a
104
- // blocking preflight result (design doc line 461, enforced by
105
- // `cashCostAccountingValid` in production-runtime.ts), so no such route
106
- // reaches an attempt, and a second weaker enforcement point for a fact the
107
- // gate refuses outright is how the two start disagreeing.
108
- //
109
- // No `knownUsd`: the whole point is that this 0 is not a known cost.
110
- // Carrying it would relocate the same lie into the unresolved arm, where
111
- // `renderResult` would print "$0 known" beside the fenced bucket.
112
- if (
113
- usage.billingMode === "metered" &&
114
- usage.cashCostUsd === 0 &&
115
- (outputTokensKnown(usage.tokens) ?? 0) > 0
116
- ) {
117
- return { kind: "unresolved", knownUsd: undefined };
118
- }
119
- // #182 follow-up, the free-nonzero rule: a model free at probe time can flip
120
- // to metered before/during the attempt, and the attempt then runs
121
- // credentialless under an empty projection. The flip is observable at
122
- // settlement — the transport accumulates provider-reported cost per message
123
- // (opencode-sdk.ts `cashCostUsd`, `costSource: "provider"`), so priced work
124
- // on a free-declared route arrives here as complete usage with cash > 0.
125
- //
126
- // NO output-token gate, unlike metered-zero: any priced work on a
127
- // free-declared route is unaccountable by definition, and cash > 0 already
128
- // implies the provider did priced work. `noSessionUsage` (route-mode stamp +
129
- // cash 0 + empty tokens) still settles 0 below — a free attempt that never
130
- // reached the provider is a truthful zero, not a flip.
131
- //
132
- // `knownUsd` IS carried here — the documented asymmetry with metered-zero,
133
- // which drops it. A metered 0 is an untrusted number wearing the provider's
134
- // badge; a free-route cash figure is the provider's STATED price for work it
135
- // claims to have billed, and the fence (`markUnresolvedRemote`) plus the
136
- // harness fail-fast message both need the figure to name what happened.
137
- if (
138
- usage.billingMode === "free" &&
139
- usage.completeness === "complete" &&
140
- (usage.cashCostUsd ?? 0) > 0
141
- ) {
142
- return {
143
- kind: "unresolved",
144
- knownUsd: usage.cashCostUsd,
145
- reason: "free_nonzero_cost",
146
- };
147
- }
148
- return { kind: "settle", actualUsd: usage.cashCostUsd };
64
+ return usage.completeness === "complete"
65
+ ? { kind: "settle" }
66
+ : { kind: "unresolved" };
149
67
  }
150
68
 
151
69
  // ---- Coupling 2: reserve token ----
@@ -188,7 +106,6 @@ export type SpendReservationState =
188
106
 
189
107
  export interface ReserveSpendInput {
190
108
  readonly bucketId: string;
191
- readonly reservedUsd: number;
192
109
  readonly sessionId: string;
193
110
  readonly attempt: number;
194
111
  }
@@ -198,10 +115,7 @@ export interface SpendReservation {
198
115
  readonly bucketId: string;
199
116
  readonly sessionId: string;
200
117
  readonly attempt: number;
201
- readonly reservedUsd: number;
202
118
  readonly state: SpendReservationState;
203
- readonly settledUsd?: number;
204
- readonly knownUsd?: number;
205
119
  }
206
120
 
207
121
  // spec: "Unresolved bucket blocks the next paid attempt" — thrown by
@@ -265,7 +179,6 @@ export interface SpendLedger {
265
179
  ): Promise<void>;
266
180
  markUnresolvedRemote(
267
181
  reservationId: string,
268
- knownUsd: number | undefined,
269
182
  idempotencyKey: string,
270
183
  ): Promise<void>;
271
184
  }
@@ -280,7 +193,6 @@ export interface UnresolvedSpend {
280
193
  readonly step: string;
281
194
  readonly bucketId: string;
282
195
  readonly reservationId: string;
283
- readonly knownUsd?: number;
284
196
  }
285
197
 
286
198
  type TerminalOperationKind =
@@ -318,7 +230,6 @@ export class InMemorySpendLedger implements SpendLedger {
318
230
  bucketId: input.bucketId,
319
231
  sessionId: input.sessionId,
320
232
  attempt: input.attempt,
321
- reservedUsd: input.reservedUsd,
322
233
  state: "reserved",
323
234
  };
324
235
  this.reservations.set(reservation.reservationId, { reservation });
@@ -327,7 +238,7 @@ export class InMemorySpendLedger implements SpendLedger {
327
238
 
328
239
  async settle(
329
240
  reservationId: string,
330
- decision: Extract<SettlementDecision, { kind: "settle" }>,
241
+ _decision: Extract<SettlementDecision, { kind: "settle" }>,
331
242
  idempotencyKey: string,
332
243
  ): Promise<void> {
333
244
  this.transition(
@@ -337,7 +248,6 @@ export class InMemorySpendLedger implements SpendLedger {
337
248
  (reservation) => ({
338
249
  ...reservation,
339
250
  state: "settled",
340
- settledUsd: decision.actualUsd,
341
251
  }),
342
252
  );
343
253
  }
@@ -359,7 +269,6 @@ export class InMemorySpendLedger implements SpendLedger {
359
269
 
360
270
  async markUnresolvedRemote(
361
271
  reservationId: string,
362
- knownUsd: number | undefined,
363
272
  idempotencyKey: string,
364
273
  ): Promise<void> {
365
274
  const applied = this.transition(
@@ -369,7 +278,6 @@ export class InMemorySpendLedger implements SpendLedger {
369
278
  (reservation) => ({
370
279
  ...reservation,
371
280
  state: "unresolved_remote",
372
- knownUsd,
373
281
  }),
374
282
  );
375
283
  if (applied) {
@@ -0,0 +1,397 @@
1
+ import path from "node:path";
2
+ import {
3
+ SESSION_LINE_OMITTED,
4
+ SESSION_TRUNCATED,
5
+ } from "./claude-session-trace";
6
+ import type { NormalizedTokens, UsageBillingMode } from "./usage-normalized";
7
+
8
+ // What one attempt measured per model request, with no dollar anywhere: the engine's side of the
9
+ // platform's `usage_facts` report (odd/tasks/platform-owned-cost-contract.md, section 3). The platform
10
+ // prices these; the engine only reads them where the provider wrote them.
11
+ //
12
+ // WHY at attempt settlement and not in the report step: the Claude CLI's per-model summary
13
+ // (`modelUsage`) is in its stdout, which nothing keeps, and the session copy and the OpenCode capture
14
+ // are only certain to exist while the harness still holds the attempt. So the harness extracts here,
15
+ // writes one `usage.<step>.attempt<n>.json` per attempt, and pipeline.json carries them; the report
16
+ // step only copies numbers out of pipeline.json.
17
+
18
+ // Disjoint token counts, in the platform's order: uncached input, cache read, cache write at the
19
+ // provider's default lifetime, cache write for one hour, visible output, reasoning.
20
+ export type UsageCounts = readonly [
21
+ number,
22
+ number,
23
+ number,
24
+ number,
25
+ number,
26
+ number,
27
+ ];
28
+
29
+ // The provider's own per-model totals for an attempt (the Claude CLI's `modelUsage`), already split
30
+ // into UsageCounts.
31
+ export interface ModelUsageCounts {
32
+ readonly model: string;
33
+ readonly counts: UsageCounts;
34
+ }
35
+
36
+ export type UsageFactCredential = "api" | "subscription" | "free";
37
+
38
+ // The contract's gap reasons this engine emits.
39
+ export type UsageGapReason =
40
+ | "no_session" // the Claude session copy is missing or failed
41
+ | "line_omitted" // a session line was over the copy's caps
42
+ | "truncated" // the session copy hit its size cap
43
+ | "no_readback" // the OpenCode capture or its readback is missing
44
+ | "no_summary"; // the Claude CLI printed no `modelUsage` (killed, timed out, unparseable)
45
+
46
+ // [provider, model, ...UsageCounts]: the model exactly as the provider reported it.
47
+ export type UsageFactEntry = readonly [
48
+ string,
49
+ string,
50
+ number,
51
+ number,
52
+ number,
53
+ number,
54
+ number,
55
+ number,
56
+ ];
57
+
58
+ export interface AttemptUsageFacts {
59
+ readonly attempt: number;
60
+ readonly credential: UsageFactCredential;
61
+ // One per model request, in the order the provider answered.
62
+ readonly requests: readonly UsageFactEntry[];
63
+ // What the provider's own totals count beyond the requests, per model. Absent when nothing is.
64
+ readonly remainders?: readonly UsageFactEntry[];
65
+ // Why some requests could not be read. Absent when none were lost.
66
+ readonly gaps?: readonly UsageGapReason[];
67
+ }
68
+
69
+ export function usageFactsPath(
70
+ outPath: string,
71
+ stepName: string,
72
+ attempt: number,
73
+ ): string {
74
+ return path.join(
75
+ path.dirname(outPath),
76
+ `usage.${stepName}.attempt${attempt}.json`,
77
+ );
78
+ }
79
+
80
+ // The credential an attempt ran on, from the billing mode its transport stamped on its usage. An
81
+ // attempt's own mode is never `unknown` today (only a sum of disagreeing attempts is); such an
82
+ // attempt would name no credential, so it reports no facts rather than a guessed one.
83
+ export function credentialOfBillingMode(
84
+ mode: UsageBillingMode,
85
+ ): UsageFactCredential | undefined {
86
+ switch (mode) {
87
+ case "metered":
88
+ return "api";
89
+ case "subscription":
90
+ return "subscription";
91
+ case "free":
92
+ return "free";
93
+ default:
94
+ return undefined;
95
+ }
96
+ }
97
+
98
+ function isRecord(value: unknown): value is Record<string, unknown> {
99
+ return typeof value === "object" && value !== null && !Array.isArray(value);
100
+ }
101
+
102
+ // A token count as the platform accepts it: a non-negative integer.
103
+ function tokens(value: unknown): number {
104
+ return typeof value === "number" && Number.isFinite(value) && value > 0
105
+ ? Math.round(value)
106
+ : 0;
107
+ }
108
+
109
+ function nonEmpty(value: unknown): string | undefined {
110
+ return typeof value === "string" && value.trim() !== "" ? value : undefined;
111
+ }
112
+
113
+ // The Claude CLI counts thinking inside its output and the one-hour write inside its total write, so
114
+ // both are split out here. A figure that names no split leaves it all in the default leaf.
115
+ export function claudeUsageCounts(input: {
116
+ uncached: unknown;
117
+ cacheRead: unknown;
118
+ cacheWriteTotal: unknown;
119
+ cacheWrite1h: unknown;
120
+ cacheWrite5m: unknown;
121
+ output: unknown;
122
+ thinking: unknown;
123
+ }): UsageCounts {
124
+ const write1h = tokens(input.cacheWrite1h);
125
+ const writeTotal =
126
+ typeof input.cacheWriteTotal === "number"
127
+ ? tokens(input.cacheWriteTotal)
128
+ : tokens(input.cacheWrite5m) + write1h;
129
+ const thinking = tokens(input.thinking);
130
+ return [
131
+ tokens(input.uncached),
132
+ tokens(input.cacheRead),
133
+ Math.max(0, writeTotal - write1h),
134
+ write1h,
135
+ Math.max(0, tokens(input.output) - thinking),
136
+ thinking,
137
+ ];
138
+ }
139
+
140
+ // The requests of one Claude session copy (execution/claude-session-trace.ts), read a line at a
141
+ // time: the copy can be 64 MiB and several hunters settle at once, so it is never held whole. The
142
+ // CLI writes one line per content block of a message, each with the message's final usage, so a
143
+ // message id is one request, kept at its first position. A message with no usage at all (a CLI
144
+ // placeholder) is not a request: it bills nothing and would name a model nobody prices.
145
+ async function claudeSessionRequests(
146
+ lines: AsyncIterable<string> | Iterable<string>,
147
+ ): Promise<{
148
+ requests: ModelUsageCounts[];
149
+ gaps: UsageGapReason[];
150
+ }> {
151
+ const byId = new Map<string, ModelUsageCounts>();
152
+ const requests: ModelUsageCounts[] = [];
153
+ const gaps = new Set<UsageGapReason>();
154
+ for await (const line of lines) {
155
+ // Most lines are prompts and tool results; only these can name usage or a marker.
156
+ if (!line.includes('"usage"') && !line.includes('"crysk"')) continue;
157
+ let parsed: unknown;
158
+ try {
159
+ parsed = JSON.parse(line);
160
+ } catch {
161
+ continue;
162
+ }
163
+ if (!isRecord(parsed)) continue;
164
+ if (parsed.crysk === SESSION_LINE_OMITTED) gaps.add("line_omitted");
165
+ if (parsed.crysk === SESSION_TRUNCATED) gaps.add("truncated");
166
+ if (parsed.type !== "assistant" || !isRecord(parsed.message)) continue;
167
+ const { id, model, usage } = parsed.message;
168
+ const modelId = nonEmpty(model);
169
+ if (modelId === undefined || !isRecord(usage)) continue;
170
+ const creation = isRecord(usage.cache_creation) ? usage.cache_creation : {};
171
+ const details = isRecord(usage.output_tokens_details)
172
+ ? usage.output_tokens_details
173
+ : {};
174
+ const counts = claudeUsageCounts({
175
+ uncached: usage.input_tokens,
176
+ cacheRead: usage.cache_read_input_tokens,
177
+ cacheWriteTotal: usage.cache_creation_input_tokens,
178
+ cacheWrite1h: creation.ephemeral_1h_input_tokens,
179
+ cacheWrite5m: creation.ephemeral_5m_input_tokens,
180
+ output: usage.output_tokens,
181
+ thinking: details.thinking_tokens,
182
+ });
183
+ if (counts.every((n) => n === 0)) continue;
184
+ const request = { model: modelId, counts };
185
+ const key = nonEmpty(id);
186
+ if (key === undefined) {
187
+ requests.push(request);
188
+ continue;
189
+ }
190
+ const seen = byId.get(key);
191
+ if (seen === undefined) {
192
+ byId.set(key, request);
193
+ requests.push(request);
194
+ } else {
195
+ // Same message, later line: its usage replaces the earlier one in place.
196
+ requests[requests.indexOf(seen)] = request;
197
+ byId.set(key, request);
198
+ }
199
+ }
200
+ return { requests, gaps: [...gaps] };
201
+ }
202
+
203
+ function sumCounts(rows: readonly UsageCounts[]): UsageCounts {
204
+ const total = [0, 0, 0, 0, 0, 0];
205
+ for (const row of rows) for (let i = 0; i < 6; i++) total[i] += row[i] ?? 0;
206
+ return total as unknown as UsageCounts;
207
+ }
208
+
209
+ // What a total counts beyond the requests of the same model, leaf by leaf, never negative. The two
210
+ // split leaves (write: default and one hour; output: visible and reasoning) are compared on their
211
+ // sum first, so a total that does not split them (an older CLI) is not read as a missing split.
212
+ function beyond(total: UsageCounts, seen: UsageCounts): UsageCounts {
213
+ const over = (a: number, b: number) => Math.max(0, a - b);
214
+ const pair = (
215
+ defaultLeaf: number,
216
+ splitLeaf: number,
217
+ ): readonly [number, number] => {
218
+ const all = over(
219
+ total[defaultLeaf] + total[splitLeaf],
220
+ seen[defaultLeaf] + seen[splitLeaf],
221
+ );
222
+ const split = Math.min(all, over(total[splitLeaf], seen[splitLeaf]));
223
+ return [all - split, split];
224
+ };
225
+ const [write, write1h] = pair(2, 3);
226
+ const [output, reasoning] = pair(4, 5);
227
+ return [
228
+ over(total[0], seen[0]),
229
+ over(total[1], seen[1]),
230
+ write,
231
+ write1h,
232
+ output,
233
+ reasoning,
234
+ ];
235
+ }
236
+
237
+ function entry(provider: string, row: ModelUsageCounts): UsageFactEntry {
238
+ return [provider, row.model, ...row.counts];
239
+ }
240
+
241
+ function facts(
242
+ base: { attempt: number; credential: UsageFactCredential },
243
+ requests: readonly UsageFactEntry[],
244
+ remainders: readonly UsageFactEntry[],
245
+ gaps: readonly UsageGapReason[],
246
+ ): AttemptUsageFacts {
247
+ return {
248
+ attempt: base.attempt,
249
+ credential: base.credential,
250
+ requests,
251
+ ...(remainders.length === 0 ? {} : { remainders }),
252
+ ...(gaps.length === 0 ? {} : { gaps }),
253
+ };
254
+ }
255
+
256
+ // One Claude CLI attempt: its requests from the session copy's lines (undefined when the copy is
257
+ // missing), and the CLI's per-model summary (undefined when the CLI printed none) for what the copy
258
+ // lost or never had: a side model the CLI ran outside the conversation, a line over the copy's caps.
259
+ export async function claudeAttemptUsageFacts(input: {
260
+ attempt: number;
261
+ credential: UsageFactCredential;
262
+ provider: string;
263
+ session: AsyncIterable<string> | Iterable<string> | undefined;
264
+ summary: readonly ModelUsageCounts[] | undefined;
265
+ }): Promise<AttemptUsageFacts> {
266
+ const read =
267
+ input.session === undefined
268
+ ? { requests: [], gaps: ["no_session" as const] }
269
+ : await claudeSessionRequests(input.session);
270
+ const remainders: UsageFactEntry[] = [];
271
+ for (const total of input.summary ?? []) {
272
+ const seen = sumCounts(
273
+ read.requests.filter((r) => r.model === total.model).map((r) => r.counts),
274
+ );
275
+ const counts = beyond(total.counts, seen);
276
+ if (counts.some((n) => n > 0)) {
277
+ remainders.push(entry(input.provider, { model: total.model, counts }));
278
+ }
279
+ }
280
+ return facts(
281
+ input,
282
+ read.requests.map((r) => entry(input.provider, r)),
283
+ remainders,
284
+ input.summary === undefined ? [...read.gaps, "no_summary"] : read.gaps,
285
+ );
286
+ }
287
+
288
+ // The newest readback of an OpenCode capture (transports/opencode-evidence.ts): the session's
289
+ // messages as OpenCode returned them, final per message, where the stream's per-message figures
290
+ // can still grow. One request per assistant message, none skipped, in the order the trace makes
291
+ // its turns of them (ci/trace-transcripts.ts `openCodeConversation`), so a request's index is its
292
+ // turn's. `complete` is the readback's own `coverage`, the same test the evidence classifier uses.
293
+ // Undefined when the capture holds no readback.
294
+ function openCodeReadback(
295
+ capture: string,
296
+ route: { provider: string; model: string },
297
+ ): { requests: UsageFactEntry[]; complete: boolean } | undefined {
298
+ let parsed: unknown;
299
+ try {
300
+ parsed = JSON.parse(capture);
301
+ } catch {
302
+ return undefined;
303
+ }
304
+ const records =
305
+ isRecord(parsed) && Array.isArray(parsed.records)
306
+ ? parsed.records.filter(isRecord)
307
+ : [];
308
+ const readbacks = records.filter((record) => record.kind === "readback");
309
+ const readback = readbacks
310
+ .filter(
311
+ (record) => isRecord(record.data) && Array.isArray(record.data.messages),
312
+ )
313
+ .at(-1);
314
+ if (readback === undefined || !isRecord(readback.data)) return undefined;
315
+ // The newest readback of any shape decides, as in the evidence classifier: when the transport
316
+ // recorded a later one it could not read (`coverage: "unknown"`, no message array), the older
317
+ // array is kept for its requests but is no longer the session's whole.
318
+ const newest = readbacks.at(-1) === readback;
319
+ const requests: UsageFactEntry[] = [];
320
+ for (const message of (readback.data.messages as unknown[]).filter(
321
+ isRecord,
322
+ )) {
323
+ const info = isRecord(message.info) ? message.info : message;
324
+ if (info.role !== "assistant") continue;
325
+ const t = isRecord(info.tokens) ? info.tokens : {};
326
+ const cache = isRecord(t.cache) ? t.cache : {};
327
+ // OpenCode's leaves are disjoint and its one cache write has no lifetime.
328
+ requests.push([
329
+ nonEmpty(info.providerID) ?? route.provider,
330
+ nonEmpty(info.modelID) ?? route.model,
331
+ tokens(t.input),
332
+ tokens(cache.read),
333
+ tokens(cache.write),
334
+ 0,
335
+ tokens(t.output),
336
+ tokens(t.reasoning),
337
+ ]);
338
+ }
339
+ return {
340
+ requests,
341
+ complete: newest && readback.data.coverage === "complete",
342
+ };
343
+ }
344
+
345
+ // One OpenCode attempt: one request per assistant message of its capture's newest readback. The
346
+ // readback is trusted whole only when it covers the session and the capture itself is complete
347
+ // (the evidence classifier's two tests): an incomplete capture can have dropped a newer readback,
348
+ // leaving an older one newest. Otherwise the requests read are kept, and what the attempt's
349
+ // streamed totals count beyond them stands in as one remainder under its route, with a
350
+ // `no_readback` gap whenever the readback is missing or something was beyond it. An attempt with
351
+ // no capture and no totals reached no session and reports nothing. The contract's `evicted` gap is
352
+ // not emitted: the transport's per-message cap applies to its streamed map, which these facts
353
+ // never read.
354
+ export function openCodeAttemptUsageFacts(input: {
355
+ attempt: number;
356
+ credential: UsageFactCredential;
357
+ route: { provider: string; model: string };
358
+ // The transport's capture (TransportOutcome.diagnosticEvidence).
359
+ capture:
360
+ | { readonly status: string; readonly redactedJson: string }
361
+ | undefined;
362
+ totals: NormalizedTokens;
363
+ }): AttemptUsageFacts | undefined {
364
+ const readback =
365
+ input.capture === undefined
366
+ ? undefined
367
+ : openCodeReadback(input.capture.redactedJson, input.route);
368
+ if (readback?.complete === true && input.capture?.status === "complete") {
369
+ return facts(input, readback.requests, [], []);
370
+ }
371
+ const t = input.totals;
372
+ const totals: UsageCounts = [
373
+ tokens(t.inputUncached) + tokens(t.inputOther),
374
+ tokens(t.inputCacheRead),
375
+ tokens(t.inputCacheWrite),
376
+ 0,
377
+ tokens(t.outputVisible) + tokens(t.outputOther),
378
+ tokens(t.outputReasoning),
379
+ ];
380
+ if (input.capture === undefined && totals.every((n) => n === 0)) {
381
+ return undefined;
382
+ }
383
+ const requests = readback?.requests ?? [];
384
+ const counts = beyond(
385
+ totals,
386
+ sumCounts(requests.map((r) => r.slice(2) as unknown as UsageCounts)),
387
+ );
388
+ const lost = counts.some((n) => n > 0);
389
+ return facts(
390
+ input,
391
+ requests,
392
+ lost
393
+ ? [entry(input.route.provider, { model: input.route.model, counts })]
394
+ : [],
395
+ readback === undefined || lost ? ["no_readback"] : [],
396
+ );
397
+ }