@foldrun/core 2.1.0 → 2.3.0

package/dist/src/store.d.ts

@@ -893,6 +893,10 @@ export interface RunEvent {
     call?: string;
     ms?: number;
     err?: boolean;
+    /** On a tool completion: the result's length in characters — what it put
+     *  into the conversation, which every later turn sends again. Absent before
+     *  18 Oct 2026. */
+    bytes?: number;
     /** Set on a test run's event that reports what the platform did instead
      *  of the real thing — a refused send, a redirected email, a diverted
      *  state write, a withheld secret. The run page lists these; the text is
@@ -954,6 +958,8 @@ export interface StepAttempt {
     status: "completed" | "failed" | "lost";
     costUsd: number | null;
     tokens: TokenUsage | null;
+    /** Model turns this attempt took; absent before 18 Oct 2026. */
+    turns?: number | null;
     computeSecs: number | null;
     startedAt: string;
     finishedAt: string;
@@ -968,45 +974,9 @@ export interface StepAttempt {
 /** The step's totals across its attempts, from the rows. Null where no
  *  attempt reported the figure — an in-process step rents no sandbox, and
  *  billing reads null as zero, not as "unknown, charge something". */
-export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs">;
-/**
- * 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 declare function tokensOf(usage: {
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-} | null | undefined): TokenUsage | null;
-/** 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 declare function sumTokens(list: readonly TokenUsage[]): TokenUsage;
-/** 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 declare function cacheHitRate(t: TokenUsage | null | undefined): number | 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 declare function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null;
-/** A run's token counts, summed over its steps; null when no step reported any. */
-export declare function runTokens(run: {
-    steps: readonly {
-        tokens?: TokenUsage | null;
-    }[];
-}): TokenUsage | null;
+export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
+export { type TokenUsage, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.ts";
+import { type TokenUsage } from "./tokens.ts";
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1195,6 +1165,14 @@ export interface StepRecord {
      *  and not only "how much" — the price of a token changes, the count is
      *  the fact. Absent on steps recorded before this existed. */
     tokens?: TokenUsage | null;
+    /** Model turns, summed across attempts, and the system prompt's length in
+     *  characters — every turn sends it again. With the tool events' `bytes`,
+     *  what says where a step's input tokens went. Absent before 18 Oct 2026. */
+    turns?: number | null;
+    systemPromptChars?: number;
+    /** Why the model's last turn ended (end_turn, max_tokens, tool_use…), as
+     *  the SDK's closing result says. */
+    stopReason?: string | 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

package/dist/src/store.js

@@ -2573,66 +2573,18 @@ export function flowPatternTemplate(pattern, name, agents) {
  *  billing reads null as zero, not as "unknown, charge something". */
 export function sumAttempts(tries) {
     const costs = tries.map((t) => t.costUsd).filter((c) => typeof c === "number");
+    const turns = tries.map((t) => t.turns).filter((c) => typeof c === "number");
     const toks = tries.map((t) => t.tokens).filter((t) => !!t);
     const secs = tries.map((t) => t.computeSecs).filter((c) => typeof c === "number");
     return {
         costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
         tokens: toks.length ? sumTokens(toks) : null,
         computeSecs: secs.length ? secs.reduce((a, b) => a + b, 0) : null,
+        ...(turns.length ? { turns: turns.reduce((a, b) => a + b, 0) } : {}),
     };
 }
-/** The record's shape from what a step reports (ExecOutcome.usage). */
-export function tokensOf(usage) {
-    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) {
-    const out = { 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) {
-    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) {
-    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) {
-    const toks = run.steps.map((s) => s.tokens).filter((t) => !!t);
-    return toks.length ? sumTokens(toks) : null;
-}
+export { tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.js";
+import { sumTokens } from "./tokens.js";
 export function runFilePath(tenant, workspace, runId) {
     assertSafeName(runId, "run id");
     return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);

package/dist/src/tokens.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function tokensOf(usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+} | null | undefined): TokenUsage | null;
+/** 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 declare function sumTokens(list: readonly TokenUsage[]): TokenUsage;
+/** 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 declare function cacheHitRate(t: TokenUsage | null | undefined): number | 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 declare function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null;
+/** A run's token counts, summed over its steps; null when no step reported any. */
+export declare function runTokens(run: {
+    steps: readonly {
+        tokens?: TokenUsage | null;
+    }[];
+}): TokenUsage | null;

package/dist/src/tokens.js

@@ -0,0 +1,58 @@
+// Token counts and the prompt-cache share, as pure functions over values.
+//
+// No node imports: the dashboard's client components read these (the run
+// page's step chips), and store.ts — fs, path, the tree reader — must never
+// reach a browser bundle (web ae042d6 broke `next build` doing exactly that).
+// store.ts re-exports everything here, so server code imports as before.
+/** The record's shape from what a step reports (ExecOutcome.usage). */
+export function tokensOf(usage) {
+    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) {
+    const out = { 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) {
+    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) {
+    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) {
+    const toks = run.steps.map((s) => s.tokens).filter((t) => !!t);
+    return toks.length ? sumTokens(toks) : null;
+}

package/dist/src/tool-output.d.ts

@@ -0,0 +1,29 @@
+/** What the model sees inline, at most: about 3,000 tokens. */
+export declare const RESULT_PREVIEW_CHARS = 12000;
+/** What a tool's output is collected up to before it is kept — enough for a
+ *  big API page or a long script log, bounded so a runaway stream cannot
+ *  fill the sandbox's memory. */
+export declare const RESULT_KEEP_CHARS = 2000000;
+/** The results folder, relative to the agent's working directory. */
+export declare const RESULTS_DIR = ".cache/results";
+/** What an agent that cannot read files gets: the whole result up to the
+ *  old cut, as before 18 Oct 2026 — a pointer to a file it has no tool to
+ *  open would only lose it the tail. */
+export declare const UNREADABLE_CAP = 20000;
+/** Does a step granted these tools hold one that reads a kept result back? */
+export declare function canReadBack(allowed: readonly string[]): boolean;
+/** Where a long result may be kept: the agent's folder, and whether the agent
+ *  holds a tool to read it back (Read or Grep). Asked per call, because the
+ *  runner builds the tools before it settles the agent's grants. */
+export interface KeepIn {
+    dir: string;
+    readable: () => boolean;
+}
+/**
+ * `text` as the model should see it: unchanged when short; otherwise its
+ * head — cut at a line break when one falls in the last fifth — and where
+ * the whole of it is. `label` names the file (the tool's name). An agent
+ * that cannot read files back, or no folder to keep it in: the whole result
+ * up to UNREADABLE_CAP, as it always was.
+ */
+export declare function previewOrKeep(text: string, keep: KeepIn | null | undefined, label: string, cap?: number): string;

package/dist/src/tool-output.js

@@ -0,0 +1,64 @@
+// A tool result too long to send whole: kept in a file, previewed inline.
+//
+// A tool result stays in the conversation and is sent again on every later
+// turn of the step, so one 20,000-character answer costs its tokens over and
+// over (FOL-28: ~470k input tokens on a 3-line answer). Script and API tools
+// used to cut at 20,000 characters and drop the rest — the model saw a
+// fragment and could not ask for more. Now the whole output is written under
+// the agent's `.cache/results/`, the model gets the head and the path, and
+// reads on with Read (offset/limit) or Grep only if it needs to.
+//
+// `.cache/` is inside the workspace, so the file tools reach it, and is never
+// copied back from a run's sandbox (run-container.ts DENY_BACK_CACHE): a
+// result is the step's working material, not workspace content.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+/** What the model sees inline, at most: about 3,000 tokens. */
+export const RESULT_PREVIEW_CHARS = 12_000;
+/** What a tool's output is collected up to before it is kept — enough for a
+ *  big API page or a long script log, bounded so a runaway stream cannot
+ *  fill the sandbox's memory. */
+export const RESULT_KEEP_CHARS = 2_000_000;
+/** The results folder, relative to the agent's working directory. */
+export const RESULTS_DIR = ".cache/results";
+/** What an agent that cannot read files gets: the whole result up to the
+ *  old cut, as before 18 Oct 2026 — a pointer to a file it has no tool to
+ *  open would only lose it the tail. */
+export const UNREADABLE_CAP = 20_000;
+/** Does a step granted these tools hold one that reads a kept result back? */
+export function canReadBack(allowed) {
+    return allowed.includes("Read") || allowed.includes("Grep");
+}
+/**
+ * `text` as the model should see it: unchanged when short; otherwise its
+ * head — cut at a line break when one falls in the last fifth — and where
+ * the whole of it is. `label` names the file (the tool's name). An agent
+ * that cannot read files back, or no folder to keep it in: the whole result
+ * up to UNREADABLE_CAP, as it always was.
+ */
+export function previewOrKeep(text, keep, label, cap = RESULT_PREVIEW_CHARS) {
+    const whole = () => (text.length > UNREADABLE_CAP ? `${text.slice(0, UNREADABLE_CAP)}\n…[truncated]` : text);
+    if (!keep || !keep.readable())
+        return whole();
+    const agentDir = keep.dir;
+    if (text.length <= cap)
+        return text;
+    let cut = text.lastIndexOf("\n", cap);
+    if (cut < cap * 0.8)
+        cut = cap;
+    const head = text.slice(0, cut);
+    const more = text.length - cut;
+    const name = `${label.replace(/[^A-Za-z0-9_.-]+/g, "_").slice(0, 60)}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}.txt`;
+    const rel = path.posix.join(RESULTS_DIR, name);
+    try {
+        fs.mkdirSync(path.join(agentDir, RESULTS_DIR), { recursive: true });
+        fs.writeFileSync(path.join(agentDir, rel), text);
+    }
+    catch {
+        // Nowhere to keep it: what it would have had before, rather than a tail lost.
+        return whole();
+    }
+    return (`${head}\n…(${more} more characters not shown — the whole result, ${text.length} characters, is in \`${rel}\`. ` +
+        `Read it with offset/limit, or Grep it, if you need what is past this point.)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/api-tools.ts

@@ -18,10 +18,13 @@ import { EGRESS_ENV, viaEgress } from "./egress.ts";
 import { z } from "zod";
 import { createSdkMcpServer, tool, type SdkMcpToolDefinition } from "@anthropic-ai/claude-agent-sdk";
 import type { ApiSpec } from "./store.ts";
+import { previewOrKeep, RESULT_KEEP_CHARS, type KeepIn } from "./tool-output.ts";
 import type { OperationSpec } from "./openapi.ts";
 import { resolveSecrets, materializeSecrets } from "./secrets.ts";
 
-const MAX_BODY_CHARS = 20_000;
+// Collected whole up to this; the model sees a preview and where the rest is
+// kept (tool-output.ts), not a cut with the rest gone.
+const MAX_BODY_CHARS = RESULT_KEEP_CHARS;
 /** MCP tool names are capped; ours also carry the server prefix on the wire. */
 const MAX_TOOL_NAME = 64;
 /** How many typed tools the prompt lists by name before summarising. */
@@ -140,6 +143,8 @@ async function performRequest(
   bucket: TokenBucket | null,
   log: string[],
   req: Request,
+  /** Where a long body is kept, when the agent can read it back (tool-output.ts). */
+  keepIn?: KeepIn,
 ): Promise<ToolReply> {
   const started = Date.now();
   try {
@@ -180,10 +185,11 @@ async function performRequest(
       ...(api.timeout ? { signal: AbortSignal.timeout(api.timeout * 1000) } : {}),
     });
     const text = await res.text();
-    const truncated =
+    const body =
       text.length > MAX_BODY_CHARS
         ? `${text.slice(0, MAX_BODY_CHARS)}\n…[truncated ${text.length - MAX_BODY_CHARS} chars]`
         : text;
+    const truncated = previewOrKeep(body, keepIn, `${api.name}-${req.method.toLowerCase()}`);
 
     log.push(
       `${req.method} ${url.pathname}${url.search ? "?…" : ""} → ${res.status} (${Date.now() - started}ms)${waitNote}`,
@@ -236,6 +242,7 @@ function typedTool(
   env: Record<string, string>,
   bucket: TokenBucket | null,
   log: string[],
+  keepIn?: KeepIn,
 ) {
   const keys = argKeys(op);
   const shape: Record<string, z.ZodTypeAny> = {};
@@ -285,11 +292,11 @@ function typedTool(
       query,
       headers,
       body: typeof values.body === "string" ? values.body : undefined,
-    });
+    }, keepIn);
   });
 }
 
-function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBucket | null, log: string[]) {
+function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBucket | null, log: string[], keepIn?: KeepIn) {
   const typed = api.resolvedOperations?.length
     ? ` Prefer the typed ${api.name}_* tools; this one is the escape hatch for operations they do not cover.`
     : "";
@@ -314,7 +321,7 @@ function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBuc
         query: args.query ?? {},
         headers: {},
         body: args.body,
-      }),
+      }, keepIn),
   );
 }
 
@@ -325,6 +332,9 @@ export function buildApiTools(
   // The runner container passes this: secrets were resolved before the specs
   // crossed the boundary, and there is no vault in there to ask.
   resolved?: { env: Record<string, string | undefined>; missing: string[] },
+  /** Where a body too long to send whole is kept and previewed, when the
+   *  agent can read it back (tool-output.ts). Without it, the old 20k cut. */
+  keepIn?: KeepIn,
 ): ApiToolResult {
   if (apis.length === 0) {
     return { server: null, toolNames: [], owners: {}, methods: {}, missingSecrets: [], promptLines: [], drainLog: () => [] };
@@ -383,11 +393,11 @@ export function buildApiTools(
 
     const typedNames: string[] = [];
     for (const op of ops) {
-      tools.push(typedTool(api, op, env, bucket, log));
+      tools.push(typedTool(api, op, env, bucket, log, keepIn));
       typedNames.push(typedToolName(api.name, op.id));
       methods[`mcp__foldrun_apis__${typedToolName(api.name, op.id)}`] = String(op.method ?? "").toUpperCase();
     }
-    if (withGeneric) tools.push(genericTool(api, env, bucket, log));
+    if (withGeneric) tools.push(genericTool(api, env, bucket, log, keepIn));
 
     const names = [...typedNames, ...(withGeneric ? [`call_${api.name}`] : [])];
     for (const n of names) {

package/src/catalog.ts

@@ -34,6 +34,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.) */
@@ -63,7 +70,8 @@ const cacheFile = (baseUrl: string) =>
     `${new URL(baseUrl).hostname.replace(/[^a-z0-9.-]/gi, "_")}.json`,
   );
 
-function parseModels(payload: unknown): CatalogModel[] {
+/** The gateway's /models payload as entries. Exported for its tests. */
+export function parseModels(payload: unknown): CatalogModel[] {
   const data = (payload as { data?: unknown[] })?.data;
   if (!Array.isArray(data)) return [];
   const out: CatalogModel[] = [];
@@ -75,8 +83,13 @@ function parseModels(payload: unknown): CatalogModel[] {
       ? m.supported_parameters.map(String)
       : null;
     const pricing = (m.pricing ?? {}) as Record<string, unknown>;
+    // 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: string) => {
-      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({
@@ -85,6 +98,8 @@ function parseModels(payload: unknown): CatalogModel[] {
       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 as Record<string, unknown> | undefined)?.supported_efforts)
@@ -249,22 +264,55 @@ export function catalogCost(
 ): number | null {
   const m = findModel(catalog, modelId);
   if (!m || m.promptPrice == null || m.completionPrice == null) return null;
-  // A catalogue quotes one input price; cache traffic is priced off it with
-  // the multipliers every gateway that bills for caching has copied from
-  // Anthropic. Before the counts were split (18 Oct 2026) every cached
-  // token was billed here at the full rate — a long cached step cost ten
-  // times its price on the ledger.
-  // inputTokens is all input; the cache fields are parts of it.
+  return costOf(usage, tokenPriceOf(m)!);
+}
+
+/** 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 function tokenPriceOf(m: CatalogModel | null | undefined): TokenPrice | null {
+  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: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number },
+  p: TokenPrice,
+): number {
   const read = usage.cacheReadTokens ?? 0;
   const written = usage.cacheWriteTokens ?? 0;
   const fresh = Math.max(0, usage.inputTokens - read - written);
-  const input = fresh + written * CACHE_WRITE_MULTIPLIER + read * CACHE_READ_MULTIPLIER;
-  return input * m.promptPrice + usage.outputTokens * m.completionPrice;
+  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. One source for the
- *  mid-step ceiling (priceTurn) and the record's repricing (catalogCost). */
+ *  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;
 

package/src/run-container.ts

@@ -28,6 +28,7 @@ import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { isPlatformPath, type ApiSpec, type Effort } from "./store.ts";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.ts";
 import type { EventExtra, ExecUsage } from "./step-exec.ts";
+import type { TokenPrice } from "./catalog.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET, type RuntimeSpec } from "./runtime.ts";
 import { egressCaSh, type NetworkLevel } from "./network.ts";
@@ -69,7 +70,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";
@@ -185,6 +186,9 @@ export interface ContainerStepOutcome {
   data?: unknown;
   costUsd: number | null;
   usage?: ExecUsage | null;
+  /** Model turns, and why the last one ended — see ExecOutcome. */
+  turns?: number;
+  stopReason?: string | null;
   /** Every turn priced at its own model, when sub-agents ran on others —
    *  see ExecOutcome.turnsCostUsd. */
   turnsCostUsd?: number;
@@ -671,13 +675,18 @@ try {
   // buildApiTools gets an already-resolved environment. verify: gets the
   // container's own environment, whole: it is the boundary, assembled on
   // the host from an allowlist, and the declared secrets are in it.
-  const api = buildApiTools("", input.apis, undefined, { env, missing: [] });
+  // A long result is kept in a file only when the agent can read it back.
+  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)
+  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === "Read" || t === "Grep") };
+  const api = buildApiTools("", input.apis, undefined, { env, missing: [] }, keepIn);
   const script = buildScriptTools(
     agentDir,
     input.scripts,
     { ...env, ...runtime.env },
     "/library/scripts",
     runtime.interpreters,
+    null,
+    keepIn.readable,
   );
   // The translator, when the provider speaks Chat Completions: a loopback
   // server for the length of this step. Its env replaces the endpoint the
@@ -1183,7 +1192,7 @@ export function buildFailureSummary(log: string, opts: { tail?: number; maxLines
 
 export function parseDriverLine(
   line: string,
-): { e: "event"; type: "text" | "tool" | "info" | "error"; text: string; call?: string; ms?: number; err?: boolean; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord } | { e: "done" } & ContainerStepOutcome | null {
+): { e: "event"; type: "text" | "tool" | "info" | "error"; text: string; call?: string; ms?: number; err?: boolean; bytes?: number; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord } | { e: "done" } & ContainerStepOutcome | null {
   const trimmed = line.trim();
   if (!trimmed.startsWith("{")) return null;
   try {
@@ -1196,6 +1205,7 @@ export function parseDriverLine(
         ...(typeof parsed.call === "string" ? { call: parsed.call } : {}),
         ...(typeof parsed.ms === "number" ? { ms: parsed.ms } : {}),
         ...(parsed.err === true ? { err: true } : {}),
+        ...(typeof parsed.bytes === "number" && parsed.bytes >= 0 ? { bytes: parsed.bytes } : {}),
         ...(isOperatorEvent(parsed.operator) ? { operator: parsed.operator } : {}),
         ...(typeof parsed.subagent === "string" && /^[a-z0-9-]{1,64}$/.test(parsed.subagent) ? { subagent: parsed.subagent } : {}),
         ...(parsed.check === true ? { check: true } : {}),
@@ -1211,6 +1221,8 @@ export function parseDriverLine(
         ...("data" in parsed ? { data: parsed.data } : {}),
         costUsd: typeof parsed.costUsd === "number" ? parsed.costUsd : null,
         ...(typeof parsed.turnsCostUsd === "number" ? { turnsCostUsd: parsed.turnsCostUsd } : {}),
+        ...(typeof parsed.turns === "number" && parsed.turns >= 0 ? { turns: parsed.turns } : {}),
+        ...(typeof parsed.stopReason === "string" ? { stopReason: parsed.stopReason.slice(0, 64) } : {}),
         ...(parseBrowserPod(parsed.browserPod) ? { browserPod: parseBrowserPod(parsed.browserPod)! } : {}),
         usage:
           parsed.usage &&