@cat-factory/executor-harness 1.64.4 → 1.68.0

package/src/bootstrap-mode.ts

@@ -0,0 +1,174 @@
+import { opendir } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { AgentJob, AgentResult } from './job.js'
+import type { PiRunStats } from './pi.js'
+import type { RunOptions } from './runner.js'
+import {
+  NEVER_ACTED_CAUSE,
+  agentNeverActed,
+  agentOutputTail,
+  runAgentInWorkspace,
+  withWorkspace,
+} from './pi-workspace.js'
+import { cloneRepo, hasAgentChanges, reinitAndPush } from './git.js'
+import { log } from './logger.js'
+import { agentCapabilities, mergeEffort } from './agent-shared.js'
+
+// ---------------------------------------------------------------------------
+// The repo-BOOTSTRAP mode: adapt a reference architecture (or scaffold from scratch) into a
+// pre-created empty repo and force-push it as a single commit. Extracted from `agent.ts` as a
+// cohesive collaborator — it is a whole MODE with its own push semantics (a separate target repo
+// and a reinitialised history, not a work branch + PR), and it shares only the small agent-run
+// helpers in `agent-shared.ts` with the coding/explore flows.
+// ---------------------------------------------------------------------------
+
+/**
+ * Repo-bootstrap coding flow (the bootstrapper): with a reference architecture, clone it →
+ * the agent adapts it in place per the instructions; without one (`fromScratch`), start from
+ * an empty directory → the agent scaffolds the new service. Either way the result's history
+ * is reset to a single commit and force-pushed to the SEPARATE, pre-created target repo's
+ * default branch. Diverges from the ordinary coding flow in pushing to a different repo with
+ * a reinitialised history rather than a work branch + PR on the cloned repo.
+ */
+export async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<AgentResult> {
+  const { signal } = opts
+  const boot = job.bootstrap!
+  const fromScratch = boot.fromScratch === true
+  const logger = (opts.log ?? log).child({ target: `${boot.target.owner}/${boot.target.name}` })
+  return withWorkspace('boot', async (dir) => {
+    if (!fromScratch) {
+      opts.onPhase?.('clone')
+      logger.info('agent(bootstrap): cloning reference architecture', {
+        reference: `${job.repo.owner}/${job.repo.name}`,
+      })
+      await cloneRepo({
+        repo: { ...job.repo, baseBranch: job.branch },
+        ghToken: job.ghToken,
+        dir,
+        signal,
+      })
+    } else {
+      logger.info('agent(bootstrap): scaffolding from scratch (no reference)')
+    }
+
+    opts.onPhase?.('agent')
+    logger.info('agent(bootstrap): running agent')
+    const { summary, stats, stderrTail, usage, callMetrics, effortReport } =
+      await runAgentInWorkspace(
+        {
+          dir,
+          systemPrompt: job.systemPrompt,
+          userPrompt: job.userPrompt,
+          model: job.model,
+          harness: job.harness,
+          subscriptionToken: job.subscriptionToken,
+          subscriptionBaseUrl: job.subscriptionBaseUrl,
+          ambientAuth: job.ambientAuth,
+          proxyBaseUrl: job.proxyBaseUrl,
+          sessionToken: job.sessionToken,
+          guardLimits: job.guardLimits,
+          ...agentCapabilities(job),
+        },
+        opts,
+      )
+
+    // Guard against a no-op run: Pi can exit cleanly having done nothing (e.g. it never
+    // reached the model), and a force-push would then publish an empty tree — leaving the
+    // run "succeeded" but the repo bare. Fail with a structured error (carrying what the
+    // agent did) instead of pushing nothing.
+    if (!(await producedRepoContent(dir, !fromScratch, signal))) {
+      const error = bootstrapNoOpReason(!fromScratch, stats, summary, stderrTail)
+      logger.error('agent(bootstrap): agent produced no content, refusing to push', { ...stats })
+      return mergeEffort(
+        {
+          summary,
+          stats,
+          error,
+          failureCause: 'agent',
+          ...(usage ? { usage } : {}),
+          ...(callMetrics ? { callMetrics } : {}),
+        },
+        effortReport,
+      )
+    }
+
+    opts.onPhase?.('push')
+    logger.info('agent(bootstrap): pushing bootstrapped contents', { ...stats })
+    // Bootstrap always resets history to one commit + force-pushes (the fresh history
+    // shares no ancestor with whatever boilerplate the new repo was created with).
+    await reinitAndPush({
+      dir,
+      target: boot.target,
+      ghToken: job.ghToken,
+      message: fromScratch
+        ? 'Bootstrap new repository'
+        : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,
+    })
+    logger.info('agent(bootstrap): complete', { defaultBranch: boot.target.defaultBranch })
+    return mergeEffort(
+      {
+        defaultBranch: boot.target.defaultBranch,
+        summary,
+        stats,
+        ...(usage ? { usage } : {}),
+        ...(callMetrics ? { callMetrics } : {}),
+      },
+      effortReport,
+    )
+  })
+}
+
+/**
+ * Whether the bootstrapper actually produced repository content, so a no-op run (the agent
+ * never reached the model / never wrote anything) is failed rather than force-pushed as an
+ * empty repo. With a reference architecture, "produced content" means the agent changed the
+ * clone; scaffolding from scratch, it means at least one file now exists in the working
+ * directory. (The harness writes its prompt context to Pi's global `~/.pi/agent/AGENTS.md`,
+ * never into `dir`, so nothing here needs to be filtered out as harness boilerplate.)
+ */
+export async function producedRepoContent(
+  dir: string,
+  hasReference: boolean,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (hasReference) return hasAgentChanges(dir, signal)
+  return containsAnyFile(dir)
+}
+
+/**
+ * Whether `dir` contains at least one regular file anywhere in its tree, walking
+ * depth-first and stopping at the FIRST file found — so the cost is bounded by how
+ * quickly a file turns up (a scaffold almost always writes a root-level file), not by
+ * the size of the produced tree (a full recursive `readdir` would materialise every
+ * entry before the check).
+ */
+async function containsAnyFile(dir: string): Promise<boolean> {
+  const handle = await opendir(dir)
+  try {
+    for await (const entry of handle) {
+      if (entry.isFile()) return true
+      if (entry.isDirectory() && (await containsAnyFile(join(dir, entry.name)))) return true
+    }
+  } catch {
+    // A directory that vanished mid-walk has nothing to contribute.
+  }
+  return false
+}
+
+/** Human-readable bootstrap no-op reason, embedding what the agent did so the cause is visible. */
+function bootstrapNoOpReason(
+  hasReference: boolean,
+  stats: PiRunStats,
+  summary: string,
+  stderrTail: string | undefined,
+): string {
+  const what = hasReference
+    ? 'made no changes to the reference architecture'
+    : 'scaffolded no files'
+  const cause = agentNeverActed(stats) ? NEVER_ACTED_CAUSE : ''
+  return (
+    `the bootstrapper agent ${what} ` +
+    `(tool calls: ${stats.toolCalls}, assistant output: ${stats.assistantChars} chars).${cause}` +
+    agentOutputTail(stderrTail, summary)
+  )
+}

package/src/claude-call-aggregator.ts

@@ -22,7 +22,8 @@ export interface AggregatedClaudeCall {
   reasoning: string
   stopReason: string | null
   inputTokens: number
-  cachedInputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
   outputTokens: number
   /** The `user` turns carrying this call's tool_result blocks, in arrival order. */
   toolResults: unknown[][]
@@ -95,7 +96,8 @@ export function createClaudeCallAggregator(handlers: {
           reasoning: '',
           stopReason: null,
           inputTokens: 0,
-          cachedInputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
           outputTokens: 0,
           toolResults: [],
           toolUses: 0,
@@ -107,7 +109,8 @@ export function createClaudeCallAggregator(handlers: {
       pending.reasoning += reasoning
       pending.toolUses += toolUses
       pending.inputTokens = Math.max(pending.inputTokens, usage.inputTokens)
-      pending.cachedInputTokens = Math.max(pending.cachedInputTokens, usage.cachedInputTokens)
+      pending.cacheReadTokens = Math.max(pending.cacheReadTokens, usage.cacheReadTokens)
+      pending.cacheWriteTokens = Math.max(pending.cacheWriteTokens, usage.cacheWriteTokens)
       pending.outputTokens = Math.max(pending.outputTokens, usage.outputTokens)
       // A block-split response reports its stop reason on the envelope that carries the end of the
       // message; earlier ones report none. Keep the first non-null rather than the last seen.
@@ -185,7 +188,8 @@ export function createClaudeStreamTelemetry(opts: {
         responseText: redactBody(call.text, opts.secrets),
         reasoningText: redactBody(call.reasoning, opts.secrets),
         inputTokens: call.inputTokens,
-        cachedInputTokens: call.cachedInputTokens,
+        cacheReadTokens: call.cacheReadTokens,
+        cacheWriteTokens: call.cacheWriteTokens,
         outputTokens: call.outputTokens,
         finishReason: call.stopReason,
       })

package/src/claude-stream.ts

@@ -59,19 +59,27 @@ export function claudeAssistantContent(content: unknown[]): {
 
 /**
  * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
- * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
- * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
+ * the cumulative `result` total).
+ *
+ * Anthropic reports all three input classes SEPARATELY and `input_tokens` is already
+ * exclusive of both caches, so the three fields here are orthogonal and additive:
+ * total input = `inputTokens + cacheReadTokens + cacheWriteTokens`. Do NOT re-lump the
+ * reads and the writes — a cache write costs 1.25–2× base input while a read costs ~0.1×,
+ * so a turn that keeps invalidating the prefix and one that rides a warm cache are
+ * indistinguishable once they are summed.
  */
 export function claudeCallUsage(raw: unknown): {
   inputTokens: number
-  cachedInputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
   outputTokens: number
 } {
-  if (!isObject(raw)) return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
-  const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens)
+  if (!isObject(raw))
+    return { inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 }
   return {
-    inputTokens: numberOf(raw.input_tokens) + cached,
-    cachedInputTokens: cached,
+    inputTokens: numberOf(raw.input_tokens),
+    cacheReadTokens: numberOf(raw.cache_read_input_tokens),
+    cacheWriteTokens: numberOf(raw.cache_creation_input_tokens),
     outputTokens: numberOf(raw.output_tokens),
   }
 }

package/src/coding-agent.ts

@@ -1,8 +1,6 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
-import { spawn } from 'node:child_process'
-import { killChildProcess, spawnDetached } from './process.js'
-import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js'
+import { runCapturedCommand } from './captured-command.js'
 import type {
   AgentJob,
   AgentResult,
@@ -11,6 +9,7 @@ import type {
   ReferenceRepoSpec,
   RepoSpec,
   SkillSpec,
+  McpServerSpec,
 } from './job.js'
 import {
   branchAheadOfBase,
@@ -140,12 +139,18 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    */
   reproduction?: ReproductionSpec
   /**
-   * A repo-sourced Claude Skill to make available for this run (a `skill` step, slice 2). Threaded
-   * into {@link runAgentInWorkspace}, which installs it harness-aware: natively under the ISOLATED
-   * `CLAUDE_CONFIG_DIR` for a leased-credential claude-code run, `.cat-context/skill/` for everything
-   * else (Pi, codex, and ambient claude-code, which has no isolated config dir). Absent ⇒ no skill.
+   * The skills to make available for this run — a `skill` step's pick and/or the running kind's
+   * declared playbooks. Threaded into {@link runAgentInWorkspace}, which installs them
+   * harness-aware: natively under the ISOLATED `CLAUDE_CONFIG_DIR` for a leased-credential
+   * claude-code run, `.cat-context/skill/<name>/` for everything else (Pi, codex, and ambient
+   * claude-code, which has no isolated config dir). Absent ⇒ no skills.
    */
-  skill?: SkillSpec
+  skills?: SkillSpec[]
+  /**
+   * Tool servers (MCP) to wire into the agent CLI for this run. Forwarded verbatim — the backend
+   * has already dropped anything this harness cannot serve. Absent ⇒ built-in tools only.
+   */
+  mcpServers?: McpServerSpec[]
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -179,6 +184,8 @@ export interface CodingAgentOutcome {
     exitCode: number
     validationOutputTail?: string
     iteration?: number
+    /** The work-branch HEAD the command was judged against (absent when it could not be read). */
+    headSha?: string
   }
   /**
    * The pre-PR validation loop's LAST attempt (present only when {@link CodingAgentSpec.validationChecks}
@@ -350,7 +357,8 @@ export async function runCodingAgent(
             webToolsGuidance: spec.webToolsGuidance,
             webSearchProxy: spec.webSearchProxy,
             guardLimits: spec.guardLimits,
-            ...(spec.skill ? { skill: spec.skill } : {}),
+            ...(spec.skills?.length ? { skills: spec.skills } : {}),
+            ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
           },
           opts,
         )
@@ -718,7 +726,7 @@ async function finalizeCodingRun(args: {
   // Runs regardless of whether this pass pushed — a no-op iteration must still be able
   // to report that the criterion is (already) met. The harness runs it, never the model.
   if (spec.validation) {
-    outcome.validation = await runRalphValidation(workDir, spec.validation, logger, opts)
+    outcome.validation = await runRalphValidation(dir, workDir, spec.validation, logger, opts)
   }
   // Pre-PR validation: the loop already ran (before this finalize, so a red checkout never
   // reaches the PR-opening caller); attach its verdict for the caller to gate on and for the
@@ -796,22 +804,57 @@ function mergeAgentPasses<T extends Awaited<ReturnType<typeof runAgentInWorkspac
  * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).
  * Overridable via env for tests; defaults to 15 minutes.
  */
-function ralphValidationTimeoutMs(): number {
+export function ralphValidationTimeoutMs(): number {
   const n = Number(process.env.RALPH_VALIDATION_TIMEOUT_MS)
   return Number.isFinite(n) && n > 0 ? Math.floor(n) : 15 * 60_000
 }
 
+/**
+ * How often the Ralph validation feeds the run's inactivity watchdog while its command runs.
+ * The command is exactly the activity-SILENT kind — a full `pnpm test`, a cold install-then-build
+ * — and the harness spawns it ITSELF rather than through the agent, so it emits no activity
+ * events of its own. `JOB_INACTIVITY_MS` (default 10 min) is TIGHTER than the command's own
+ * watchdog ({@link ralphValidationTimeoutMs}, default 15 min), so without this heartbeat any
+ * validation running past 10 minutes aborted the whole iteration as "inactivity" — mislabelling
+ * a healthy test suite as a wedge, and making the 15-minute watchdog unreachable at stock
+ * settings. The two sibling harness-run phases (pre-PR validation, reproduction proof) have
+ * always fed it; this one did not. Overridable via env for tests.
+ */
+export function ralphHeartbeatMs(): number {
+  const n = Number(process.env.RALPH_VALIDATION_HEARTBEAT_MS)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 30_000
+}
+
+/**
+ * Bound on the validation output tail that crosses the wire. Deliberately smaller than
+ * `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`) and equal to the two sibling phases' budgets, for
+ * the same reason: this tail is persisted on the step (and on EVERY iteration of the attempt
+ * log) inside the run's `detail` JSON blob, which is re-serialized on every step-progress write.
+ */
+export const RALPH_VALIDATION_TAIL_CHARS = 4_000
+
 /**
  * Ralph loop: run the programmatic completion command in the checkout and return its exit
- * code plus a bounded, redacted tail of its output. The EXIT CODE is the loop's authoritative
- * done signal (0 = the criterion is met) — computed here by the harness, never self-reported
- * by the model, which is the whole point of a programmatic exit condition. Runs
- * `sh -c <command>` in `cwd`; a watchdog kills the whole process tree on timeout (a hung
- * command counts as a failure so the loop is never blocked), and an aborted run resolves to a
- * non-zero code too. The command runs INSIDE the sandboxed run container (the same trust
- * boundary as the coding agent) — there is no host/backend execution.
+ * code, a bounded + redacted tail of its output, and the work branch's HEAD it ran against.
+ * The EXIT CODE is the loop's authoritative done signal (0 = the criterion is met) — computed
+ * here by the harness, never self-reported by the model, which is the whole point of a
+ * programmatic exit condition. The command runs INSIDE the sandboxed run container (the same
+ * trust boundary as the coding agent) — there is no host/backend execution.
+ *
+ * The spawn itself goes through {@link runCapturedCommand}, the ONE seam for a harness-run
+ * command, rather than the near-verbatim copy this used to be. That copy had drifted in two
+ * ways the seam exists to prevent: it scrubbed secrets AFTER the rolling truncation with no
+ * margin (so a credential straddling the cut lost its `KEY=` prefix and survived redaction as
+ * an unrecognised partial, on a tail that reaches the step, the notification and the SPA), and
+ * it published the full 16k capture where both siblings deliberately bound the wire tail.
+ *
+ * `headSha` is what lets the engine tell a loop that is iterating from one that is merely
+ * repeating: two consecutive failing iterations against an unchanged head means the agent
+ * committed nothing, and the loop is ended early instead of spending the rest of its budget.
+ * Best-effort — a head that cannot be read is simply omitted, and the engine's check fails open.
  */
-async function runRalphValidation(
+export async function runRalphValidation(
+  repoDir: string,
   cwd: string,
   validation: { command: string; iteration?: number },
   logger: Logger,
@@ -821,66 +864,50 @@ async function runRalphValidation(
   exitCode: number
   validationOutputTail?: string
   iteration?: number
+  headSha?: string
 }> {
-  const timeoutMs = ralphValidationTimeoutMs()
   logger.info('coding-agent(ralph): running validation command', {
     iteration: validation.iteration,
   })
-  return new Promise((resolve) => {
-    let out = ''
-    let settled = false
-    const child = spawn('sh', ['-c', validation.command], {
+  // Keep the run's inactivity watchdog fed for the whole command — see `ralphHeartbeatMs`.
+  const heartbeat = setInterval(() => opts.onActivity?.(), ralphHeartbeatMs())
+  heartbeat.unref?.()
+  let captured
+  try {
+    captured = await runCapturedCommand({
       cwd,
-      detached: spawnDetached,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      // The job's own env (see `RunOptions.agentEnv`): a validation command typically installs
-      // before it tests, and this is spawned by the HARNESS rather than the agent, so it does not
-      // otherwise inherit the job's private-registry npmrc pointer on the native path.
-      env: { ...process.env, ...opts.agentEnv },
+      command: validation.command,
+      timeoutMs: ralphValidationTimeoutMs(),
+      reportTailChars: RALPH_VALIDATION_TAIL_CHARS,
+      logLabel: 'coding-agent(ralph): validation',
+      logFields: { iteration: validation.iteration },
+      logger,
+      opts,
     })
-    // Keep only the tail; guard against unbounded buffering on a chatty command.
-    const capture = (chunk: Buffer): void => {
-      out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_CHARS)
-    }
-    child.stdout?.on('data', capture)
-    child.stderr?.on('data', capture)
-    const finish = (exitCode: number): void => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      opts.signal?.removeEventListener('abort', onAbort)
-      const trimmed = out.trim()
-      const tail = trimmed ? redactSecrets(trimmed) : undefined
-      logger.info('coding-agent(ralph): validation finished', {
-        exitCode,
-        iteration: validation.iteration,
-      })
-      resolve({
-        validationPassed: exitCode === 0,
-        exitCode,
-        ...(tail ? { validationOutputTail: tail } : {}),
-        ...(validation.iteration !== undefined ? { iteration: validation.iteration } : {}),
-      })
-    }
-    const timer = setTimeout(() => {
-      logger.warn('coding-agent(ralph): validation command timed out', { timeoutMs })
-      killChildProcess(child, undefined, logger)
-      finish(124) // conventional timeout exit code (a non-zero fail)
-    }, timeoutMs)
-    timer.unref?.()
-    const onAbort = (): void => {
-      killChildProcess(child, undefined, logger)
-      finish(130) // aborted (a non-zero fail)
-    }
-    opts.signal?.addEventListener('abort', onAbort, { once: true })
-    child.on('error', (err) => {
-      logger.warn('coding-agent(ralph): validation command failed to spawn', {
-        error: err instanceof Error ? err.message : String(err),
-      })
-      finish(127) // spawn error / command not found (a non-zero fail)
+  } finally {
+    clearInterval(heartbeat)
+  }
+  // The commit the criterion was judged against. Read AFTER the command so a validation that
+  // itself commits (a formatter check that rewrites files, say) is attributed to what it left.
+  // Best-effort: an unreadable head only costs the engine's no-progress guard, never the
+  // verdict — but it is REPORTED, or a guard that quietly stopped firing leaves no trace.
+  const headSha = await headCommit(repoDir, opts.signal).catch((err: unknown) => {
+    logger.warn('coding-agent(ralph): could not read the work-branch head', {
+      error: err instanceof Error ? err.message : String(err),
     })
-    child.on('close', (code) => finish(code ?? 1))
+    return ''
+  })
+  logger.info('coding-agent(ralph): validation finished', {
+    exitCode: captured.exitCode,
+    iteration: validation.iteration,
   })
+  return {
+    validationPassed: captured.passed,
+    exitCode: captured.exitCode,
+    ...(captured.outputTail ? { validationOutputTail: captured.outputTail } : {}),
+    ...(validation.iteration !== undefined ? { iteration: validation.iteration } : {}),
+    ...(headSha ? { headSha } : {}),
+  }
 }
 
 /** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
@@ -1030,6 +1057,10 @@ export async function runMultiRepoCoding(
           webSearchProxy: job.webSearch,
           guardLimits: job.guardLimits,
           ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
+          // Skills + tool servers apply to a multi-repo run exactly as to a single-repo one: they
+          // are properties of the AGENT KIND, not of the checkout layout.
+          ...(job.skills?.length ? { skills: job.skills } : {}),
+          ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
           multiRepo: true,
         },
         opts,

package/src/inline.ts

@@ -54,10 +54,43 @@ export async function handleInline(job: InlineJob, opts: RunOptions): Promise<In
     return {
       text: outcome.summary,
       finishReason: deriveFinishReason(outcome.callMetrics),
-      ...(outcome.usage ? { usage: outcome.usage } : {}),
+      ...(outcome.usage ? { usage: inlineUsage(outcome.usage, outcome.callMetrics) } : {}),
       ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
     }
   } finally {
     await rm(cwd, { recursive: true, force: true }).catch(() => {})
   }
 }
+
+/**
+ * Split the run's coarse usage into the three orthogonal input classes an {@link InlineResult}
+ * carries. `outcome.usage` is the ROTATION-window weight — every billed input bucket summed —
+ * so the split has to come from the per-call metrics, the only channel that kept the classes
+ * apart. Fresh input is likewise taken from the calls rather than derived by subtraction, so a
+ * CLI whose per-call and cumulative counts disagree can never produce a negative class.
+ *
+ * With no per-call telemetry (an older CLI build that streams nothing) the coarse total is
+ * reported as fresh with both cache classes 0. That is the honest reading: nothing is KNOWN to
+ * have been cached, and inventing a split would be worse than admitting the channel is silent.
+ */
+function inlineUsage(
+  usage: { inputTokens: number; outputTokens: number },
+  calls: HarnessCallMetric[] | undefined,
+): NonNullable<InlineResult['usage']> {
+  if (!calls?.length) {
+    return {
+      inputTokens: usage.inputTokens,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      outputTokens: usage.outputTokens,
+    }
+  }
+  const sum = (pick: (call: HarnessCallMetric) => number): number =>
+    calls.reduce((total, call) => total + pick(call), 0)
+  return {
+    inputTokens: sum((call) => call.inputTokens),
+    cacheReadTokens: sum((call) => call.cacheReadTokens),
+    cacheWriteTokens: sum((call) => call.cacheWriteTokens),
+    outputTokens: usage.outputTokens,
+  }
+}