@foldrun/core 2.0.0 → 2.2.0

package/dist/src/catalog.d.ts

@@ -8,6 +8,13 @@ export interface CatalogModel {
     promptPrice: number | null;
     /** USD per output token. */
     completionPrice: number | null;
+    /** USD per input token read from / written to the prompt cache, when the
+     *  gateway quotes them (OpenRouter's input_cache_read / input_cache_write).
+     *  Models discount their cache differently — GPT-4o reads at half the
+     *  input price, Claude at a tenth — so a quoted price beats any multiplier.
+     *  Absent on catalogues cached before 2.1.1. */
+    cacheReadPrice?: number | null;
+    cacheWritePrice?: number | null;
     /** Can this model make tool calls? Null when the gateway doesn't say. */
     tools: boolean | null;
     /** Does it take a reasoning-depth parameter? (What `effort:` needs.) */
@@ -23,6 +30,8 @@ export interface Catalog {
     fetchedAt: string;
     models: CatalogModel[];
 }
+/** The gateway's /models payload as entries. Exported for its tests. */
+export declare function parseModels(payload: unknown): CatalogModel[];
 /** The cache as it stands, however old — null only when nothing was ever
  *  fetched. Reading never touches the network. */
 export declare function readCatalog(baseUrl: string): Catalog | null;
@@ -83,7 +92,38 @@ export declare function clampEffort(catalog: Catalog | null, modelId: string, ef
 export declare function catalogCost(catalog: Catalog | null, modelId: string, usage: {
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
 }): number | null;
+/** What a token costs on one model: input, output, and — when the gateway
+ *  quotes them — reads from and writes to the prompt cache. */
+export interface TokenPrice {
+    input: number;
+    output: number;
+    cacheRead?: number | null;
+    cacheWrite?: number | null;
+}
+/** A catalogue entry's prices, or null when it has no input/output price. */
+export declare function tokenPriceOf(m: CatalogModel | null | undefined): TokenPrice | null;
+/**
+ * The cost of a set of counts at a price. `inputTokens` is all input; the
+ * cache fields are parts of it. Cached input is priced at the model's own
+ * cache prices when the gateway quotes them, and only otherwise at
+ * Anthropic's multipliers over the input price. Before the counts were
+ * split (18 Oct 2026) every cached token was billed at the full rate.
+ */
+export declare function costOf(usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}, p: TokenPrice): number;
+/** Anthropic's cache multipliers over the input price: a write costs a
+ *  quarter more than fresh input, a read a tenth of it. The fallback when a
+ *  gateway quotes no cache price — for the mid-step ceiling (priceTurn) and
+ *  the record's repricing (catalogCost) alike. */
+export declare const CACHE_WRITE_MULTIPLIER = 1.25;
+export declare const CACHE_READ_MULTIPLIER = 0.1;
 /** Catalogue entries as completion items: price per MTok, context, and the
  *  one capability that decides agent-worthiness. Tool-capable models first —
  *  on an agent platform they are almost always what the author wants. */

package/dist/src/catalog.js

@@ -29,7 +29,8 @@ const TTL_MS = 24 * 60 * 60 * 1000;
 const cacheFile = (baseUrl) => path.join(dataRoot(), "catalog", 
 // One file per endpoint, named legibly: catalog/openrouter.ai.json.
 `${new URL(baseUrl).hostname.replace(/[^a-z0-9.-]/gi, "_")}.json`);
-function parseModels(payload) {
+/** The gateway's /models payload as entries. Exported for its tests. */
+export function parseModels(payload) {
     const data = payload?.data;
     if (!Array.isArray(data))
         return [];
@@ -44,8 +45,14 @@ function parseModels(payload) {
             ? m.supported_parameters.map(String)
             : null;
         const pricing = (m.pricing ?? {});
+        // Unquoted is unknown, not free: Number(null) and Number("") are 0, and
+        // a gateway answering `input_cache_read: null` would have made caching
+        // cost nothing. An explicit "0" stays 0.
         const price = (k) => {
-            const n = Number(pricing[k]);
+            const v = pricing[k];
+            if (v == null || (typeof v === "string" && v.trim() === ""))
+                return null;
+            const n = Number(v);
             return Number.isFinite(n) ? n : null;
         };
         out.push({
@@ -54,6 +61,8 @@ function parseModels(payload) {
             contextLength: Number.isFinite(Number(m.context_length)) ? Number(m.context_length) : null,
             promptPrice: price("prompt"),
             completionPrice: price("completion"),
+            cacheReadPrice: price("input_cache_read"),
+            cacheWritePrice: price("input_cache_write"),
             tools: supported ? supported.includes("tools") : null,
             reasoning: supported ? supported.includes("reasoning") : null,
             efforts: Array.isArray(m.reasoning?.supported_efforts)
@@ -200,8 +209,41 @@ export function catalogCost(catalog, modelId, usage) {
     const m = findModel(catalog, modelId);
     if (!m || m.promptPrice == null || m.completionPrice == null)
         return null;
-    return usage.inputTokens * m.promptPrice + usage.outputTokens * m.completionPrice;
+    return costOf(usage, tokenPriceOf(m));
 }
+/** A catalogue entry's prices, or null when it has no input/output price. */
+export function tokenPriceOf(m) {
+    if (!m || m.promptPrice == null || m.completionPrice == null)
+        return null;
+    return {
+        input: m.promptPrice,
+        output: m.completionPrice,
+        ...(m.cacheReadPrice != null ? { cacheRead: m.cacheReadPrice } : {}),
+        ...(m.cacheWritePrice != null ? { cacheWrite: m.cacheWritePrice } : {}),
+    };
+}
+/**
+ * The cost of a set of counts at a price. `inputTokens` is all input; the
+ * cache fields are parts of it. Cached input is priced at the model's own
+ * cache prices when the gateway quotes them, and only otherwise at
+ * Anthropic's multipliers over the input price. Before the counts were
+ * split (18 Oct 2026) every cached token was billed at the full rate.
+ */
+export function costOf(usage, p) {
+    const read = usage.cacheReadTokens ?? 0;
+    const written = usage.cacheWriteTokens ?? 0;
+    const fresh = Math.max(0, usage.inputTokens - read - written);
+    return (fresh * p.input +
+        written * (p.cacheWrite ?? p.input * CACHE_WRITE_MULTIPLIER) +
+        read * (p.cacheRead ?? p.input * CACHE_READ_MULTIPLIER) +
+        usage.outputTokens * p.output);
+}
+/** Anthropic's cache multipliers over the input price: a write costs a
+ *  quarter more than fresh input, a read a tenth of it. The fallback when a
+ *  gateway quotes no cache price — for the mid-step ceiling (priceTurn) and
+ *  the record's repricing (catalogCost) alike. */
+export const CACHE_WRITE_MULTIPLIER = 1.25;
+export const CACHE_READ_MULTIPLIER = 0.1;
 /** Catalogue entries as completion items: price per MTok, context, and the
  *  one capability that decides agent-worthiness. Tool-capable models first —
  *  on an agent platform they are almost always what the author wants. */

package/dist/src/deploy.d.ts

@@ -97,7 +97,9 @@ export declare function deployIssues(files: DeployFile[]): DeployIssue[];
  */
 export declare function runsInFlight(tenant: string, workspace: string): string[];
 /** What a deploy would do, without doing it. */
-export declare function planDeploy(tenant: string, workspace: string, files: DeployFile[]): DeployPlan;
+export declare function planDeploy(tenant: string, workspace: string, files: DeployFile[], opts?: {
+    keepUntracked?: boolean;
+}): DeployPlan;
 export interface DeployOptions {
     /** The commit these files came from, recorded so the dashboard can show it. */
     commit?: string | null;
@@ -115,6 +117,9 @@ export interface DeployOptions {
      * no window between the check and the swap. Absent: no check, as before.
      */
     expectRemoved?: string[];
+    /** Keep what is not editable source (planDeploy, saveWorkspace): a
+     *  restore takes history's tree, and history tracks source only. */
+    keepUntracked?: boolean;
 }
 /**
  * Deploy a file list to a workspace, if it checks out.

package/dist/src/deploy.js

@@ -20,7 +20,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { saveWorkspace, keptOnDeploy, workspaceDir, listRunSummaries, parseFlow, parseToolDef, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
+import { saveWorkspace, keptOnDeploy, workspaceDir, listRunSummaries, listWorkspaceFiles, parseFlow, parseToolDef, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
 import { lintFlow } from "./flow-lint.js";
 import { refNames } from "./refs.js";
 import matter from "gray-matter";
@@ -438,7 +438,7 @@ export function runsInFlight(tenant, workspace) {
         .map((r) => r.id);
 }
 /** What a deploy would do, without doing it. */
-export function planDeploy(tenant, workspace, files) {
+export function planDeploy(tenant, workspace, files, opts = {}) {
     const dir = workspaceDir(tenant, workspace);
     const shipped = new Map(files.map((f) => [path.normalize(f.path), f.content]));
     const present = new Set();
@@ -480,7 +480,10 @@ export function planDeploy(tenant, workspace, files) {
     // memory, the platform's own files. Reporting these as removals would be
     // a lie, and the alarming kind; one predicate serves both.
     const shippedPaths = new Set(shipped.keys());
-    const removed = [...present].filter((rel) => !shipped.has(rel) && !keptOnDeploy(rel, shippedPaths));
+    // keepUntracked (a restore): what is not editable source stays, as
+    // saveWorkspace keeps it — see its meta.keepUntracked.
+    const tracked = opts.keepUntracked ? new Set(listWorkspaceFiles(tenant, workspace)) : null;
+    const removed = [...present].filter((rel) => !shipped.has(rel) && !keptOnDeploy(rel, shippedPaths) && (!tracked || tracked.has(rel)));
     return {
         files,
         added: added.sort(),
@@ -502,7 +505,7 @@ export function planDeploy(tenant, workspace, files) {
 export function deployWorkspace(tenant, workspace, files, opts = {}) {
     assertSafeName(tenant, "tenant");
     assertSafeName(workspace, "workspace");
-    const plan = planDeploy(tenant, workspace, files);
+    const plan = planDeploy(tenant, workspace, files, { keepUntracked: opts.keepUntracked });
     const blocked = plan.blockedBy.length > 0 && !opts.force;
     if (plan.issues.length > 0 || blocked) {
         return { ...plan, applied: false, commit: null, preserved: 0 };
@@ -514,7 +517,7 @@ export function deployWorkspace(tenant, workspace, files, opts = {}) {
             return { ...plan, applied: false, commit: null, preserved: 0, unexpectedRemovals };
         }
     }
-    const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message });
+    const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message, keepUntracked: opts.keepUntracked });
     const commit = opts.commit ?? null;
     if (commit)
         writeDeployedCommit(tenant, workspace, commit);

package/dist/src/model-credential.js

@@ -60,7 +60,7 @@ export function credentialLine(c) {
 //
 // An account brings its own model key without writing a provider: block:
 // three secrets in the ACCOUNT vault (set from Settings → Model, the API's
-// /api/account/model, or `foldrun model set`). A provider: block at any
+// /api/account/model, or `foldrun account model set`). A provider: block at any
 // level still wins; this is what a step falls to when none names one, before
 // the platform's own credential.
 /** The account vault names the account's own model key lives under. */

package/dist/src/model-env.js

@@ -19,7 +19,7 @@ export class ModelKeyError extends Error {
     }
 }
 export const NO_MODEL_KEY = "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";
 /**
  * `platform` is a function: the caller's own way to build the platform's env
  * (a step's, or the SDK's host env), called only when this account may use

package/dist/src/run-container.d.ts

@@ -1,7 +1,8 @@
 import { type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type ApiSpec, type Effort } from "./store.ts";
-import type { EventExtra } from "./step-exec.ts";
+import type { EventExtra, ExecUsage } from "./step-exec.ts";
+import type { TokenPrice } from "./catalog.ts";
 import { type RuntimeSpec } from "./runtime.ts";
 import { type NetworkLevel } from "./network.ts";
 import type { ScriptSpec } from "./script-tools.ts";
@@ -41,10 +42,7 @@ export interface ContainerStepInput {
      *  step-exec.ts. Values, so the driver can enforce them in the pod. */
     budgetUsd?: number | null;
     budgetNote?: string;
-    price?: {
-        input: number;
-        output: number;
-    } | null;
+    price?: TokenPrice | null;
     verify?: string;
     /** `output: json` — checked inside, where the reply is. */
     output?: "json";
@@ -146,10 +144,7 @@ export interface ContainerStepOutcome {
     /** The parsed JSON of an `output: json` step, crossing back as a value. */
     data?: unknown;
     costUsd: number | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-    } | null;
+    usage?: ExecUsage | null;
     /** Every turn priced at its own model, when sub-agents ran on others —
      *  see ExecOutcome.turnsCostUsd. */
     turnsCostUsd?: number;

package/dist/src/run-container.js

@@ -1068,7 +1068,14 @@ export function parseDriverLine(line) {
                 usage: parsed.usage &&
                     typeof parsed.usage.inputTokens === "number" &&
                     typeof parsed.usage.outputTokens === "number"
-                    ? { inputTokens: parsed.usage.inputTokens, outputTokens: parsed.usage.outputTokens }
+                    ? {
+                        inputTokens: parsed.usage.inputTokens,
+                        outputTokens: parsed.usage.outputTokens,
+                        // A driver from before the split sends neither; zero, not
+                        // unknown, keeps the record's shape one thing.
+                        cacheReadTokens: typeof parsed.usage.cacheReadTokens === "number" ? parsed.usage.cacheReadTokens : 0,
+                        cacheWriteTokens: typeof parsed.usage.cacheWriteTokens === "number" ? parsed.usage.cacheWriteTokens : 0,
+                    }
                     : null,
                 res: parsed.res && typeof parsed.res === "object"
                     ? {

package/dist/src/runner.d.ts

@@ -354,6 +354,8 @@ grantsOnly?: boolean): {
 export declare function repriced(catalog: Catalog | null, model: string, 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
  *  ran on a different model (ExecOutcome.turnsCostUsd). The lump `usage`

package/dist/src/runner.js

@@ -33,8 +33,8 @@ import { ASK_TOOL, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskToo
 import { sendPlainNotification } from "./notify.js";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.js";
 import { refNames } from "./refs.js";
-import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
-import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
+import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf } from "./catalog.js";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
 import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
@@ -1876,8 +1876,12 @@ stepIndex) {
         // 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);
@@ -1890,7 +1894,7 @@ stepIndex) {
             const own = Object.values(providerSecrets).concat(Object.values(providerEnv));
             if (!providerLabel) {
                 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();
                 return;
@@ -1998,10 +2002,7 @@ stepIndex) {
             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";
@@ -2621,7 +2622,7 @@ stepIndex) {
                     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),
@@ -2671,9 +2672,7 @@ stepIndex) {
             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) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
@@ -2870,9 +2869,7 @@ stepIndex) {
             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())

package/dist/src/step-exec.d.ts

@@ -1,11 +1,23 @@
 import { type HookDef, type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
+import { type TokenPrice } from "./catalog.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
 import { type SubagentSpec } from "./subagents.ts";
 import { type Limits } from "./limits.ts";
 import { type BrowserPodOutcome, 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 declare function usageFromSdk(u: Record<string, number | undefined>): ExecUsage;
 export interface ExecOutcome {
     status: "completed" | "failed";
     result: string | null;
@@ -20,11 +32,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
@@ -77,10 +90,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. */
@@ -178,15 +188,19 @@ export declare function knownPrice(model: string | undefined): {
 /**
  * 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 declare function priceTurn(u: Record<string, number | undefined>, price: {
-    input: number;
-    output: number;
-} | null): number;
+export declare function priceTurn(u: Record<string, number | undefined>, price: TokenPrice | null): number;
 /**
  * Each step launched together gets an equal share of what is left of the
  * run's budget: the shares sum to the remainder, so a group cannot end

package/dist/src/step-exec.js

@@ -12,6 +12,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { costOf } from "./catalog.js";
 import { spawn } from "node:child_process";
 import { checkPaths, checkBash, isFilesystemTool, linkWorkspace, workspaceLinkEnv, resolveAgentPath, isWithin } from "./confine.js";
 import { DELEGATE_TOOLS, subagentGuard, toAgentDefinitions } from "./subagents.js";
@@ -19,6 +20,18 @@ import { hostSafeEnv } from "./host-env.js";
 import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.js";
 import { CallCounter, limitKeysFor } from "./limits.js";
 import { classifyCall, podAt, readPodEvents } from "./browser-pod.js";
+/** 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) {
+    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,
+    };
+}
 /** How often the stop flag is read while a step runs. */
 export const STOP_POLL_MS = 2000;
 /** The least a `verify:` gets when the step used up most of its `timeout:` —
@@ -65,32 +78,23 @@ export function knownPrice(model) {
         return null;
     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, price) {
-    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);
+    return costOf(usageFromSdk(u), price ?? FALLBACK_PRICE);
 }
 /**
  * Each step launched together gets an equal share of what is left of the
@@ -639,16 +643,10 @@ async function executeStepInner(opts, runQuery) {
                 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;
-                    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);
                 }
             }
         }
@@ -671,16 +669,18 @@ async function executeStepInner(opts, runQuery) {
     // 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 = { 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") {