@foldrun/core 2.0.0 → 2.2.0

package/src/runner.ts

@@ -75,13 +75,14 @@ import {
   type StepRecord,
   type StepAttempt,
   sumAttempts,
+  tokensOf,
   parseSchemaText,
   STORAGE_DIR,
   adoptLegacyVersionKey,
   listAgents,
   runCost,
 } from "./store.ts";
-import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, type Catalog } from "./catalog.ts";
+import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf, type Catalog, type TokenPrice } from "./catalog.ts";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.ts";
 import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
@@ -1712,7 +1713,7 @@ async function publishPublicDir(
 export function repriced(
   catalog: Catalog | null,
   model: string,
-  usage: { inputTokens: number; outputTokens: number } | null,
+  usage: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number } | null,
   sdkCost: number | null,
   push: (type: "info" | "error", text: string) => void,
   /** The step's turns each priced at its own model — set when a sub-agent
@@ -2064,8 +2065,12 @@ async function runStep(
     // that names a provider uses its own; otherwise the platform's (in a
     // run container) or this process's — never a login that just happens
     // to be on the machine (model-credential.ts).
-    const credential = providerLabel ? null : resolveModelCredential(isolatedRun() ? platformModelEnv() : process.env);
-    step.credential = credential ? credential.label : `provider: ${providerLabel}`;
+    // An account refused the platform's credential (below) is never shown
+    // running on it: the record said "Claude login token" on a step that
+    // was then refused for having no key (FOL-14, 18 Oct 2026).
+    const noKey = !providerLabel && !platform.platformKeyAllowed(tenant);
+    const credential = providerLabel || noKey ? null : resolveModelCredential(isolatedRun() ? platformModelEnv() : process.env);
+    step.credential = credential ? credential.label : noKey ? "none — this account has no model key" : `provider: ${providerLabel}`;
     if (credential) {
       const line = credentialLine(credential);
       push(line.type, line.text);
@@ -2080,7 +2085,7 @@ async function runStep(
         push(
           "error",
           `no model key: this account runs on its own API key, and none is set. Add one in Settings → Model ` +
-            `(or \`foldrun model set <provider> --key …\`), or write a provider: block in AGENTS.md`,
+            `(or \`foldrun account model set <provider> --key …\`), or write a provider: block in AGENTS.md`,
         );
         step.status = "failed";
         save();
@@ -2166,7 +2171,7 @@ async function runStep(
     // step on knowledge; unknown ids, presets and offline all pass through
     // to the model call, which stays the authority of last resort.
     let catalog: Catalog | null = null;
-    let tokenPrice: { input: number; output: number } | null = null;
+    let tokenPrice: TokenPrice | null = null;
     // The env this run's model calls actually ride: the workspace's own
     // provider block when one is declared, otherwise the platform's — the
     // "models included" path, where the host env points every run at the
@@ -2192,10 +2197,7 @@ async function runStep(
       const verdict = checkModel(catalog, wireModel, { tools: needsTools });
       // Also what a token costs here, so a step can count its own spend
       // turn by turn against its ceiling instead of learning at the end.
-      const priced = findModel(catalog, wireModel);
-      if (priced && priced.promptPrice != null && priced.completionPrice != null) {
-        tokenPrice = { input: priced.promptPrice, output: priced.completionPrice };
-      }
+      tokenPrice = tokenPriceOf(findModel(catalog, wireModel));
       if (!verdict.ok) {
         push("error", verdict.reason!);
         step.status = "failed";
@@ -2828,7 +2830,7 @@ async function runStep(
           step.podLostTry = {
             status: "lost",
             costUsd: repriced(catalog, wireModel, first.usage ?? null, first.costUsd, push, first.turnsCostUsd),
-            tokens: first.usage ? { input: first.usage.inputTokens, output: first.usage.outputTokens } : null,
+            tokens: tokensOf(first.usage),
             computeSecs: first.timing ? Math.round(first.timing.totalMs) / 1000 : null,
             finishedAt: new Date().toISOString(),
             error: decision.note.slice(0, 500),
@@ -2872,9 +2874,7 @@ async function runStep(
       if (outcome.status === "failed" && outcome.reason) push("error", `sandbox ended: ${outcome.reason}`);
       if (outcome.data !== undefined) step.data = redactData(outcome.data);
       step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push, outcome.turnsCostUsd);
-      step.tokens = outcome.usage
-        ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
-        : null;
+      step.tokens = tokensOf(outcome.usage);
       step.actual = outcome.res ?? null;
       if (outcome.res?.peakMemBytes || outcome.res?.rxBytes) {
         const mb = (n: number | null) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
@@ -3076,9 +3076,7 @@ async function runStep(
       const consultCost = consultTools.drainCost();
       const stepCost = repriced(catalog, wireModel, outcome.usage, outcome.costUsd, push, outcome.turnsCostUsd);
       step.costUsd = stepCost === null && consultCost === 0 ? null : (stepCost ?? 0) + consultCost;
-      step.tokens = outcome.usage
-        ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
-        : null;
+      step.tokens = tokensOf(outcome.usage);
       for (const line of apiTools.drainLog()) push("info", `api: ${line}`);
       for (const line of scriptTools.drainLog()) push("info", `script: ${line}`);
     }

package/src/step-exec.ts

@@ -15,6 +15,7 @@ import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import type { HookInput, McpServerConfig, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
+import { costOf, type TokenPrice } from "./catalog.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
 import { spawn } from "node:child_process";
@@ -25,6 +26,26 @@ import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-sc
 import { CallCounter, limitKeysFor, type Limits } from "./limits.ts";
 import { classifyCall, podAt, readPodEvents, type BrowserPodOutcome, type CallKind, type ClassifyContext } from "./browser-pod.ts";
 
+export interface ExecUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+/** The four counts from one SDK usage object (snake_case, as the API
+ *  reports it). The API counts fresh input apart from the cache's; here
+ *  `inputTokens` is all of it, as it always was on the record, and the
+ *  cache fields say how much of that the cache served or stored. */
+export function usageFromSdk(u: Record<string, number | undefined>): ExecUsage {
+  return {
+    inputTokens: (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0),
+    outputTokens: u.output_tokens ?? 0,
+    cacheReadTokens: u.cache_read_input_tokens ?? 0,
+    cacheWriteTokens: u.cache_creation_input_tokens ?? 0,
+  };
+}
+
 export interface ExecOutcome {
   status: "completed" | "failed";
   result: string | null;
@@ -39,8 +60,12 @@ export interface ExecOutcome {
   costUsd: number | null;
   /** Token counts off the SDK's result message. costUsd is priced from
    *  Anthropic's table, which is wrong for a routed model — these are the
-   *  raw numbers a caller with a gateway's own prices can reprice from. */
-  usage: { inputTokens: number; outputTokens: number } | null;
+   *  raw numbers a caller with a gateway's own prices can reprice from.
+   *  `inputTokens` is every input token; `cacheReadTokens` and
+   *  `cacheWriteTokens` are the part of it the prompt cache served or
+   *  stored, so a usage page can say how much of a step's context was
+   *  re-read for a tenth of the price. */
+  usage: ExecUsage | null;
   /** Set only when some turns ran on a different model from the step's — a
    *  sub-agent with its own `model:`. The sum of every turn, each priced at
    *  its own model. `usage` above is one lump and cannot be repriced at the
@@ -94,7 +119,7 @@ export interface ExecOptions {
   /** Price per token for the model, when the catalogue knows it, so spend
    *  can be counted turn by turn instead of learned at the end. Without it
    *  the step prices its turns from the SDK's own running total. */
-  price?: { input: number; output: number } | null;
+  price?: TokenPrice | null;
   /** A check the step must pass to count as done: a shell command that must
    *  exit 0, or an eval-style assertion (`contains: x`, `not-contains: x`,
    *  `matches: re`, `file: path`, `judge: sentence`) — see checkVerify. */
@@ -201,35 +226,23 @@ export function knownPrice(model: string | undefined): { input: number; output:
   return KNOWN_PRICES.find(([re]) => re.test(model))?.[1] ?? null;
 }
 
-/** Anthropic's cache multipliers, and the shape every gateway that bills
- *  for caching at all has copied: a write costs a quarter more than fresh
- *  input, a read a tenth of it. Counting both at the full input rate — as
- *  this did — makes a long cached prompt read about ten times its price,
- *  which on a ceiling is not "the honest direction to be wrong in", it is
- *  a step killed for spending money it never spent. */
-const CACHE_WRITE_MULTIPLIER = 1.25;
-const CACHE_READ_MULTIPLIER = 0.1;
-
 /**
  * What one assistant turn cost, from the usage the SDK reports. Pure.
  *
- * A gateway whose cache is priced differently is over- or under-counted
- * here by that difference alone; the run record's own cost is repriced
- * from the catalogue afterwards and stays the authority on the bill. This
- * number exists to stop a runaway step mid-turn, and wants to be close.
+ * Cache reads and writes are priced at the model's own cache prices when
+ * the catalogue quotes them, else at Anthropic's multipliers (costOf in
+ * catalog.ts, the same arithmetic the record is repriced with). Counting
+ * both at the full input rate — as this did —
+ * makes a long cached prompt read about ten times its price, which on a
+ * ceiling is not "the honest direction to be wrong in", it is a step
+ * killed for spending money it never spent.
+ *
+ * The run record's own cost is repriced from the catalogue afterwards and
+ * stays the authority on the bill. This number exists to stop a runaway
+ * step mid-turn, and wants to be close.
  */
-export function priceTurn(u: Record<string, number | undefined>, price: { input: number; output: number } | null): number {
-  const p = price ?? FALLBACK_PRICE;
-  const fresh = u.input_tokens ?? 0;
-  const written = u.cache_creation_input_tokens ?? 0;
-  const read = u.cache_read_input_tokens ?? 0;
-  const outTok = u.output_tokens ?? 0;
-  return (
-    fresh * p.input +
-    written * p.input * CACHE_WRITE_MULTIPLIER +
-    read * p.input * CACHE_READ_MULTIPLIER +
-    outTok * p.output
-  );
+export function priceTurn(u: Record<string, number | undefined>, price: TokenPrice | null): number {
+  return costOf(usageFromSdk(u), price ?? FALLBACK_PRICE);
 }
 
 /**
@@ -611,10 +624,10 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   // runs its turns on that model, and pricing them at the parent's put a
   // max sub-agent under a fast parent at a fifth of its cost — against the
   // ceiling and on the bill.
-  const turns = new Map<string, { u: Record<string, number | undefined>; price: { input: number; output: number } | null }>();
+  const turns = new Map<string, { u: Record<string, number | undefined>; price: TokenPrice | null }>();
   let anonymousTurns = 0;
   const specByName = new Map((subagents ?? []).map((s) => [s.name, s]));
-  const priceOf = (message: unknown): { input: number; output: number } | null => {
+  const priceOf = (message: unknown): TokenPrice | null => {
     const parent = (message as { parent_tool_use_id?: string | null }).parent_tool_use_id;
     if (!parent) return opts.price ?? null;
     const declared = specByName.get(delegations.get(parent) ?? "")?.model;
@@ -762,17 +775,10 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
       stopReason = "stop_reason" in message && typeof message.stop_reason === "string" ? message.stop_reason : null;
       if ("usage" in message && message.usage) {
-        const u = message.usage as unknown as Record<string, number | undefined>;
-        usage = {
-          // Cache traffic is input the provider still bills (at its own
-          // rates); folding it into the input count over-approximates for
-          // gateways with cheaper cache reads, which errs on the honest side.
-          inputTokens:
-            (u.input_tokens ?? 0) +
-            (u.cache_creation_input_tokens ?? 0) +
-            (u.cache_read_input_tokens ?? 0),
-          outputTokens: u.output_tokens ?? 0,
-        };
+        // Cache reads and writes counted beside the input total: with only
+        // the total (until 18 Oct 2026) the hit rate could not be read and
+        // the catalogue repriced every cached token at the full rate.
+        usage = usageFromSdk(message.usage as unknown as Record<string, number | undefined>);
       }
     }
   }
@@ -790,16 +796,18 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   // died — means no total from the SDK. The turns it did take were billed by
   // the provider all the same, so the step's cost is their sum.
   if (costUsd === null && turns.size) {
-    let input = 0;
-    let output = 0;
+    const summed: ExecUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
     let priced = 0;
     for (const { u: t, price } of turns.values()) {
-      input += (t.input_tokens ?? 0) + (t.cache_creation_input_tokens ?? 0) + (t.cache_read_input_tokens ?? 0);
-      output += t.output_tokens ?? 0;
+      const one = usageFromSdk(t);
+      summed.inputTokens += one.inputTokens;
+      summed.outputTokens += one.outputTokens;
+      summed.cacheReadTokens += one.cacheReadTokens;
+      summed.cacheWriteTokens += one.cacheWriteTokens;
       priced += priceTurn(t, price);
     }
     costUsd = priced;
-    usage ??= { inputTokens: input, outputTokens: output };
+    usage ??= summed;
     emit("info", `cost from ${turns.size} model turn${turns.size === 1 ? "" : "s"}: $${priced.toFixed(4)} — the step ended before the model's closing total`);
   }
   if (ended === "timeout") {

package/src/store.ts

@@ -369,7 +369,14 @@ export function saveWorkspace(
   files: DeployFile[],
   /** Attribution for the revision this save records. A deploy passes the
    *  commit, which becomes the revision's id. */
-  meta: ChangeMeta & { commit?: string | null } = {},
+  meta: ChangeMeta & {
+    commit?: string | null;
+    /** Keep every file that is not editable source — what an agent wrote
+     *  into its own folder at run time (a browser profile, a PDF it
+     *  downloaded). A restore sets it: history holds source, so a file it
+     *  never tracked is not one a restore may take away. */
+    keepUntracked?: boolean;
+  } = {},
 ) {
   if (files.length > 500) throw new Error("too many files");
   for (const f of files) {
@@ -424,8 +431,6 @@ export function saveWorkspace(
   // about it. Before this, every deploy silently erased everything the agents
   // had learned.
   const shipped = new Set(files.map((f) => path.normalize(f.path)));
-  const isAgentOwned = (rel: string) => keptOnDeploy(rel, shipped);
-
   // What is there now, for the revision: every editable file's content
   // before this save replaces the tree.
   const before = new Map<string, string>();
@@ -439,6 +444,8 @@ export function saveWorkspace(
     }
   }
 
+  const isAgentOwned = (rel: string) => keptOnDeploy(rel, shipped) || (meta.keepUntracked === true && !before.has(rel) && !shipped.has(rel));
+
   const snapshot = fs.existsSync(dir) ? fs.mkdtempSync(path.join(dataRoot(), ".keep-")) : null;
   const preserved: string[] = [];
   if (snapshot) {
@@ -446,9 +453,13 @@ export function saveWorkspace(
       const rel = String(entry).split(path.sep).join("/");
       const from = path.join(dir, rel);
       try {
-        if (!fs.statSync(from).isFile() || !isAgentOwned(rel)) continue;
+        // lstat, never stat: a link is never followed. An agent folder's link
+        // to a file outside the workspace was copied in as that file's
+        // contents — on a restore with keepUntracked, any such link
+        // (Codex, 18 Oct 2026).
+        if (!fs.lstatSync(from).isFile() || !isAgentOwned(rel)) continue;
       } catch {
-        continue; // a broken link or a file that vanished mid-deploy
+        continue; // a file that vanished mid-deploy
       }
       const to = path.join(snapshot, rel);
       fs.mkdirSync(path.dirname(to), { recursive: true });
@@ -3091,7 +3102,7 @@ export interface StepAttempt {
    *  of its own (image slim), before the full go's. */
   status: "completed" | "failed" | "lost";
   costUsd: number | null;
-  tokens: { input: number; output: number } | null;
+  tokens: TokenUsage | null;
   computeSecs: number | null;
   startedAt: string;
   finishedAt: string;
@@ -3109,15 +3120,84 @@ export interface StepAttempt {
  *  billing reads null as zero, not as "unknown, charge something". */
 export function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs"> {
   const costs = tries.map((t) => t.costUsd).filter((c): c is number => typeof c === "number");
-  const toks = tries.map((t) => t.tokens).filter((t): t is { input: number; output: number } => !!t);
+  const toks = tries.map((t) => t.tokens).filter((t): t is TokenUsage => !!t);
   const secs = tries.map((t) => t.computeSecs).filter((c): c is number => typeof c === "number");
   return {
     costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
-    tokens: toks.length ? toks.reduce((a, b) => ({ input: a.input + b.input, output: a.output + b.output }), { input: 0, output: 0 }) : null,
+    tokens: toks.length ? sumTokens(toks) : null,
     computeSecs: secs.length ? secs.reduce((a, b) => a + b, 0) : null,
   };
 }
 
+/**
+ * The token counts behind a step's cost. `input` is every input token the
+ * model saw; `cacheRead` and `cacheWrite` are the part of it the prompt
+ * cache served or stored — a read costs a tenth of fresh input, and a usage
+ * page wants to say how much of a step's context was re-read rather than
+ * re-sent. Steps recorded before 18 Oct 2026 have no cache fields: their
+ * `input` is the same total, but how much of it was cached is unknown.
+ */
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+/** The record's shape from what a step reports (ExecOutcome.usage). */
+export function tokensOf(usage: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number } | null | undefined): TokenUsage | null {
+  if (!usage) return null;
+  return {
+    input: usage.inputTokens,
+    output: usage.outputTokens,
+    cacheRead: usage.cacheReadTokens ?? 0,
+    cacheWrite: usage.cacheWriteTokens ?? 0,
+  };
+}
+
+/** Field-by-field sum; the cache fields are present in the result whenever
+ *  any input had them, so a run of old and new steps still reads whole. */
+export function sumTokens(list: readonly TokenUsage[]): TokenUsage {
+  const out: TokenUsage = { input: 0, output: 0 };
+  for (const t of list) {
+    out.input += t.input;
+    out.output += t.output;
+    if (t.cacheRead !== undefined || t.cacheWrite !== undefined) {
+      out.cacheRead = (out.cacheRead ?? 0) + (t.cacheRead ?? 0);
+      out.cacheWrite = (out.cacheWrite ?? 0) + (t.cacheWrite ?? 0);
+    }
+  }
+  return out;
+}
+
+/** The share of all input that the prompt cache served, 0–1; null when
+ *  there was no input, or the record predates the split and cannot say. */
+export function cacheHitRate(t: TokenUsage | null | undefined): number | null {
+  if (!t || t.cacheRead === undefined) return null;
+  return t.input > 0 ? Math.min(1, t.cacheRead / t.input) : null;
+}
+
+/** The cache share over several counts, taking only those that report the
+ *  split: a step recorded before it holds its cache traffic inside `input`,
+ *  and counting that as uncached would understate the rate. The rule the
+ *  Usage page and the CLI's totals follow too. */
+export function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null {
+  let read = 0;
+  let all = 0;
+  for (const t of list) {
+    if (!t || t.cacheRead === undefined) continue;
+    read += t.cacheRead;
+    all += t.input;
+  }
+  return all > 0 ? read / all : null;
+}
+
+/** A run's token counts, summed over its steps; null when no step reported any. */
+export function runTokens(run: { steps: readonly { tokens?: TokenUsage | null }[] }): TokenUsage | null {
+  const toks = run.steps.map((s) => s.tokens).filter((t): t is TokenUsage => !!t);
+  return toks.length ? sumTokens(toks) : null;
+}
+
 export interface StepRecord {
   agent: string;
   instruction: string;
@@ -3296,7 +3376,7 @@ export interface StepRecord {
   /** Token counts behind costUsd, kept so usage reports can say "how many"
    *  and not only "how much" — the price of a token changes, the count is
    *  the fact. Absent on steps recorded before this existed. */
-  tokens?: { input: number; output: number } | null;
+  tokens?: TokenUsage | null;
   /** What the sandbox actually touched, against what it reserved: CPU
    *  busy-seconds and peak memory from the pod's own cgroup, bytes on the
    *  wire from /proc/net/dev. Null per-field where the kernel interface
@@ -3577,7 +3657,7 @@ export interface RunSummaryStep {
   group: number;
   status: StepRecord["status"];
   costUsd: number | null;
-  tokens?: { input: number; output: number } | null;
+  tokens?: TokenUsage | null;
   computeSecs?: number | null;
   skipReason?: string;
   /** The last error event, for a failed step — what runFailure reads. */

package/src/tool-loop.ts

@@ -34,9 +34,12 @@ export interface LoopTool {
 }
 
 export interface LoopUsage {
-  /** Everything sent, cache reads and writes included. */
+  /** Everything sent, cache reads and writes included; the two cache
+   *  fields say how much of it the prompt cache served or stored. */
   inputTokens: number;
   outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
   costUsd: number;
 }
 
@@ -221,6 +224,8 @@ export async function runToolLoop(o: LoopOptions): Promise<LoopResult> {
         usage = {
           inputTokens: models.reduce((n, m) => n + (m.inputTokens ?? 0) + (m.cacheReadInputTokens ?? 0) + (m.cacheCreationInputTokens ?? 0), 0),
           outputTokens: models.reduce((n, m) => n + (m.outputTokens ?? 0), 0),
+          cacheReadTokens: models.reduce((n, m) => n + (m.cacheReadInputTokens ?? 0), 0),
+          cacheWriteTokens: models.reduce((n, m) => n + (m.cacheCreationInputTokens ?? 0), 0),
           costUsd,
         };
         if (message.subtype === "success") {

package/src/translator.ts

@@ -22,7 +22,9 @@
 // and their results, streaming — and drops what a Chat-Completions endpoint
 // has no word for (cache_control, top_k, server-side tools, thinking on
 // endpoints that lack reasoning_effort). Anything dropped is said once in
-// the run trace. The translation is pure functions over JSON so the tests
+// the run trace. Those endpoints cache prompt prefixes on their own side;
+// the cached share they report comes back as cache_read_input_tokens, so a
+// step's record says how much of its context was re-read. The translation is pure functions over JSON so the tests
 // can drive every mapping without a network; the server around them is a
 // few dozen lines.
 
@@ -37,6 +39,34 @@ import { captureRefusalHeaders, isRefusalStatus, refusalLine } from "./refusal.t
 
 type Json = Record<string, unknown>;
 
+/**
+ * An OpenAI-shaped usage object as Anthropic's: fresh input, cached input,
+ * output. Both OpenAI shapes count the cached part INSIDE the prompt total
+ * (Chat's prompt_tokens_details.cached_tokens, Responses'
+ * input_tokens_details.cached_tokens; DeepSeek says prompt_cache_hit_tokens),
+ * so it is taken out of input here or the step would count it twice.
+ */
+export function anthropicUsage(u: Json | undefined, wire: TranslatorWire): { input: number; cached: number; output: number } {
+  if (!u) return { input: 0, cached: 0, output: 0 };
+  const total = Number((wire === "chat" ? u.prompt_tokens : u.input_tokens) ?? 0);
+  const details = (wire === "chat" ? u.prompt_tokens_details : u.input_tokens_details) as Json | undefined;
+  const raw = Number(details?.cached_tokens ?? u.prompt_cache_hit_tokens ?? 0);
+  const cached = Number.isFinite(raw) ? Math.max(0, Math.min(raw, total)) : 0;
+  return {
+    input: total - cached,
+    cached,
+    output: Number((wire === "chat" ? u.completion_tokens : u.output_tokens) ?? 0),
+  };
+}
+
+function usageBlock(u: { input: number; cached: number; output: number } | null): Json {
+  return {
+    input_tokens: u?.input ?? 0,
+    output_tokens: u?.output ?? 0,
+    ...(u && u.cached > 0 ? { cache_read_input_tokens: u.cached } : {}),
+  };
+}
+
 export type TranslatorWire = "chat" | "responses";
 
 export interface TranslatorSpec {
@@ -493,10 +523,7 @@ export function fromChatCompletion(res: Json, requestedModel: string, stopSequen
     content,
     stop_reason: stop.reason,
     stop_sequence: stop.sequence,
-    usage: {
-      input_tokens: Number(usage.prompt_tokens ?? 0),
-      output_tokens: Number(usage.completion_tokens ?? 0),
-    },
+    usage: usageBlock(anthropicUsage(usage, "chat")),
   };
 }
 
@@ -515,7 +542,7 @@ export class StreamTranslator {
   private tools = new Map<number, { block: number; argsSeen: boolean }>();
   /** The last choice's stop fields: finish_reason and any matched stop. */
   private finish: Json = {};
-  private usage: { input: number; output: number } | null = null;
+  private usage: { input: number; cached: number; output: number } | null = null;
   private id = `msg_${crypto.randomBytes(8).toString("hex")}`;
   private readonly model: string;
   private readonly stops: string[];
@@ -561,7 +588,7 @@ export class StreamTranslator {
     const out = this.start(chunk);
     const u = chunk.usage as Json | undefined;
     if (u && (u.prompt_tokens !== undefined || u.completion_tokens !== undefined)) {
-      this.usage = { input: Number(u.prompt_tokens ?? 0), output: Number(u.completion_tokens ?? 0) };
+      this.usage = anthropicUsage(u, "chat");
     }
     const choice = ((chunk.choices as Json[] | undefined) ?? [])[0];
     if (!choice) return out;
@@ -650,7 +677,7 @@ export class StreamTranslator {
       this.event("message_delta", {
         type: "message_delta",
         delta: { stop_reason: stop.reason, stop_sequence: stop.sequence },
-        usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+        usage: usageBlock(this.usage),
       }),
     );
     out.push(this.event("message_stop", { type: "message_stop" }));
@@ -691,10 +718,7 @@ export function fromResponses(res: Json, requestedModel: string): Json {
     content,
     stop_reason: stop,
     stop_sequence: null,
-    usage: {
-      input_tokens: Number(usage.input_tokens ?? 0),
-      output_tokens: Number(usage.output_tokens ?? 0),
-    },
+    usage: usageBlock(anthropicUsage(usage, "responses")),
   };
 }
 
@@ -710,7 +734,7 @@ export class ResponsesStreamTranslator {
   private nextIndex = 0;
   /** Responses output_index → Anthropic block index and kind. */
   private blocks = new Map<number, { block: number; kind: "text" | "tool"; argsSeen: boolean }>();
-  private usage: { input: number; output: number } | null = null;
+  private usage: { input: number; cached: number; output: number } | null = null;
   private incomplete: string | null = null;
   private sawTool = false;
   private sawRefusal = false;
@@ -812,7 +836,7 @@ export class ResponsesStreamTranslator {
     if (type === "response.completed" || type === "response.incomplete" || type === "response.failed") {
       const r = (ev.response as Json | undefined) ?? {};
       const u = r.usage as Json | undefined;
-      if (u) this.usage = { input: Number(u.input_tokens ?? 0), output: Number(u.output_tokens ?? 0) };
+      if (u) this.usage = anthropicUsage(u, "responses");
       const reason = (r.incomplete_details as Json | undefined)?.reason;
       if (typeof reason === "string") this.incomplete = reason;
       return out;
@@ -834,7 +858,7 @@ export class ResponsesStreamTranslator {
       this.event("message_delta", {
         type: "message_delta",
         delta: { stop_reason: reason, stop_sequence: null },
-        usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+        usage: usageBlock(this.usage),
       }),
     );
     out.push(this.event("message_stop", { type: "message_stop" }));