@foldrun/core 2.2.0 → 2.3.0

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.2.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/run-container.ts

@@ -186,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;
@@ -672,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
@@ -1184,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 {
@@ -1197,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 } : {}),
@@ -1212,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 &&

package/src/runner.ts

@@ -82,6 +82,7 @@ import {
   listAgents,
   runCost,
 } from "./store.ts";
+import { canReadBack } from "./tool-output.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";
@@ -1049,7 +1050,12 @@ export function agentContext(
   const attached = attachOperations(apis, tenant, path.resolve(agentDir, "..", ".."));
   const apiWarnings = attached.warnings;
   apis.splice(0, apis.length, ...attached.specs);
-  const apiTools = buildApiTools(tenant, apis, workspace);
+  // A long tool result is kept in a file only for an agent that can read it
+  // back (tool-output.ts). The grants are settled further down, after the
+  // tools are built, so the tools ask when they are called.
+  let readsFiles = false;
+  const keepIn = { dir: agentDir, readable: () => readsFiles };
+  const apiTools = buildApiTools(tenant, apis, workspace, undefined, keepIn);
   if (apiTools.promptLines.length) {
     parts.push(`# APIs you can call\n\n${apiTools.promptLines.join("\n")}`);
   }
@@ -1396,6 +1402,7 @@ export function agentContext(
     libraryDir(tenant, "scripts"),
     runtime.interpreters,
     exec,
+    keepIn.readable,
   );
   parts.push(
     `# Clock\n\nToday is ${clockEnv.FOLDRUN_DATE} (${timezone}). Use this date for anything you ` +
@@ -1610,6 +1617,7 @@ export function agentContext(
   const denied: string[] = refNames(front.disallowedTools);
   if (denied.includes("install")) denied.push(INSTALL_TOOL);
   const finalAllowed = allowed.filter((t) => !denied.includes(t));
+  readsFiles = canReadBack(finalAllowed);
 
   return {
     front,
@@ -1784,6 +1792,7 @@ export function recordAttempt(
     status,
     costUsd: step.costUsd,
     tokens: step.tokens ?? null,
+    ...(typeof step.turns === "number" ? { turns: step.turns } : {}),
     computeSecs: step.computeSecs ?? null,
     startedAt: step.podLostTry?.finishedAt ?? startedAt,
     finishedAt: step.finishedAt ?? new Date().toISOString(),
@@ -1797,6 +1806,7 @@ export function recordAttempt(
   step.costUsd = totals.costUsd;
   step.tokens = totals.tokens;
   step.computeSecs = totals.computeSecs;
+  if (totals.turns !== undefined) step.turns = totals.turns;
 }
 
 /** A question an agent asked mid-step goes where approvals go (the
@@ -2030,6 +2040,9 @@ async function runStep(
     } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent }, flowTimezone);
     disposeRuntime = runtime.dispose;
     canActOutward = outward;
+    // Sent again on every turn; with turns and the tools' result sizes, what
+    // a token report reads to say where a step's input went.
+    step.systemPromptChars = systemPrompt.length;
     // A retry that moved the step up a class (an evicted or OOM-killed
     // attempt) wins over the agent's own `size:` for the attempts after.
     const size = step.sizeUp ?? agentSize;
@@ -2831,6 +2844,7 @@ async function runStep(
             status: "lost",
             costUsd: repriced(catalog, wireModel, first.usage ?? null, first.costUsd, push, first.turnsCostUsd),
             tokens: tokensOf(first.usage),
+            ...(typeof first.turns === "number" ? { turns: first.turns } : {}),
             computeSecs: first.timing ? Math.round(first.timing.totalMs) / 1000 : null,
             finishedAt: new Date().toISOString(),
             error: decision.note.slice(0, 500),
@@ -2875,6 +2889,8 @@ async function runStep(
       if (outcome.data !== undefined) step.data = redactData(outcome.data);
       step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push, outcome.turnsCostUsd);
       step.tokens = tokensOf(outcome.usage);
+      step.turns = typeof outcome.turns === "number" ? outcome.turns : null;
+      step.stopReason = outcome.stopReason ?? null;
       step.actual = outcome.res ?? null;
       if (outcome.res?.peakMemBytes || outcome.res?.rxBytes) {
         const mb = (n: number | null) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
@@ -3077,6 +3093,8 @@ async function runStep(
       const stepCost = repriced(catalog, wireModel, outcome.usage, outcome.costUsd, push, outcome.turnsCostUsd);
       step.costUsd = stepCost === null && consultCost === 0 ? null : (stepCost ?? 0) + consultCost;
       step.tokens = tokensOf(outcome.usage);
+      step.turns = typeof outcome.turns === "number" ? outcome.turns : null;
+      step.stopReason = outcome.stopReason ?? null;
       for (const line of apiTools.drainLog()) push("info", `api: ${line}`);
       for (const line of scriptTools.drainLog()) push("info", `script: ${line}`);
     }

package/src/script-tools.ts

@@ -23,6 +23,7 @@ import { runInContainer } from "./container.ts";
 import { hostSafeEnv } from "./host-env.ts";
 import { workspaceLinkEnv } from "./confine.ts";
 import { platform } from "./platform.ts";
+import { previewOrKeep, RESULT_KEEP_CHARS } from "./tool-output.ts";
 
 // A script's only clock is the `timeout:` its own tool.md declares. There
 // was a two-minute default and a ten-minute cap here; both were the
@@ -30,7 +31,9 @@ import { platform } from "./platform.ts";
 // deploy watcher had to be taught to call its tool four times to outlast the
 // cap. The platform orchestrates; it does not decide that.
 const timeoutFor = (spec: ScriptSpec) => (spec.timeout ? spec.timeout * 1000 : undefined);
-const MAX_OUTPUT = 20_000;
+// Collected up to this, then previewed and kept (tool-output.ts): the model
+// sees the head and where the rest is, instead of a cut with the rest gone.
+const MAX_OUTPUT = RESULT_KEEP_CHARS;
 
 export interface ScriptSpec {
   name: string;
@@ -419,6 +422,9 @@ export function buildScriptTools(
   libraryScripts = "",
   interpreters: Record<string, string> = {},
   exec: ExecutionContext | null = null,
+  /** Whether the agent can read files back (Read or Grep): only then is a
+   *  long output kept in a file and previewed (tool-output.ts). */
+  readable: () => boolean = () => false,
 ): ScriptToolResult {
   if (scripts.length === 0) {
     return { server: null, toolNames: [], promptLines: [], drainLog: () => [] };
@@ -453,7 +459,7 @@ export function buildScriptTools(
             `(${Date.now() - started}ms, ${exec?.executor ?? "sandbox"})`,
         );
         return {
-          content: [{ type: "text" as const, text: `exit ${code ?? "error"}\n\n${out}` }],
+          content: [{ type: "text" as const, text: `exit ${code ?? "error"}\n\n${previewOrKeep(out, { dir: agentDir, readable }, spec.name)}` }],
           isError: code !== 0,
         };
       },

package/src/step-exec.ts

@@ -76,6 +76,9 @@ export interface ExecOutcome {
    *  end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal or
    *  model_context_window_exceeded. Null when no result arrived. */
   stopReason?: string | null;
+  /** Model turns the step took (the SDK's num_turns; counted from the
+   *  turns seen when no closing result arrived). */
+  turns?: number;
   /** Set when the step browsed through the account's browser pod from the
    *  slim image (ExecOptions.browserPod): its reconnects, and — when the pod
    *  was lost — why, and what the step had written by then. */
@@ -192,7 +195,7 @@ export type QueryLike = AsyncIterable<unknown> & { interrupt(): Promise<unknown>
 export type QueryFn = (args: { prompt: string; options: Record<string, unknown> }) => QueryLike;
 
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
-export type EventExtra = { call?: string; ms?: number; err?: boolean; effect?: TestEffect; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord };
+export type EventExtra = { call?: string; ms?: number; err?: boolean; bytes?: number; effect?: TestEffect; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord };
 
 /** The tag on every event a failed check writes — `verify:`, `output: json`,
  *  a schema — headline and detail alike. The runner's no-retry rule for
@@ -312,6 +315,7 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   let costUsd: number | null = null;
   let usage: ExecOutcome["usage"] = null;
   let stopReason: string | null = null;
+  let numTurns: number | null = null;
   const texts: string[] = [];
 
   fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
@@ -749,6 +753,9 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
           emit("tool", open.name, {
             call: block.tool_use_id,
             ms: Date.now() - open.at,
+            // How much the result put into the conversation — sent again on
+            // every later turn, so the size is what a token report needs.
+            bytes: toolResultText(block.content).length,
             ...(block.is_error ? { err: true } : {}),
             ...(open.subagent ? { subagent: open.subagent } : {}),
           });
@@ -774,6 +781,7 @@ 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 ("num_turns" in message && typeof message.num_turns === "number") numTurns = message.num_turns;
       if ("usage" in message && message.usage) {
         // 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
@@ -941,6 +949,7 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
     status, result, conclusion, ...(opts.output ? { data } : {}), costUsd, usage,
     ...(mixedModels() ? { turnsCostUsd: turnsTotal() } : {}),
     stopReason,
+    turns: numTurns ?? turns.size,
     ...(pod ? { browserPod: podState } : {}),
   };
 }

package/src/store.ts

@@ -3046,6 +3046,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
@@ -3103,6 +3107,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;
@@ -3118,85 +3124,21 @@ 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 function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs"> {
+export function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns"> {
   const costs = tries.map((t) => t.costUsd).filter((c): c is number => typeof c === "number");
+  const turns = tries.map((t) => t.turns).filter((c): c is number => typeof c === "number");
   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 ? 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 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 { type TokenUsage, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.ts";
+import { sumTokens, type TokenUsage } from "./tokens.ts";
 
 export interface StepRecord {
   agent: string;
@@ -3377,6 +3319,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/src/tokens.ts

@@ -0,0 +1,75 @@
+// 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 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;
+}