@foldrun/core 2.1.0 → 2.3.0

package/src/runner.ts

@@ -82,7 +82,8 @@ import {
   listAgents,
   runCost,
 } from "./store.ts";
-import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, type Catalog } from "./catalog.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";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.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;
@@ -2171,7 +2184,7 @@ async function runStep(
     // step on knowledge; unknown ids, presets and offline all pass through
     // to the model call, which stays the authority of last resort.
     let catalog: Catalog | null = null;
-    let tokenPrice: { input: number; output: number } | null = null;
+    let tokenPrice: TokenPrice | null = null;
     // The env this run's model calls actually ride: the workspace's own
     // provider block when one is declared, otherwise the platform's — the
     // "models included" path, where the host env points every run at the
@@ -2197,10 +2210,7 @@ async function runStep(
       const verdict = checkModel(catalog, wireModel, { tools: needsTools });
       // Also what a token costs here, so a step can count its own spend
       // turn by turn against its ceiling instead of learning at the end.
-      const priced = findModel(catalog, wireModel);
-      if (priced && priced.promptPrice != null && priced.completionPrice != null) {
-        tokenPrice = { input: priced.promptPrice, output: priced.completionPrice };
-      }
+      tokenPrice = tokenPriceOf(findModel(catalog, wireModel));
       if (!verdict.ok) {
         push("error", verdict.reason!);
         step.status = "failed";
@@ -2834,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),
@@ -2878,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));
@@ -3080,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

@@ -15,7 +15,7 @@ import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import type { HookInput, McpServerConfig, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
-import { CACHE_READ_MULTIPLIER, CACHE_WRITE_MULTIPLIER } from "./catalog.ts";
+import { costOf, type TokenPrice } from "./catalog.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
 import { spawn } from "node:child_process";
@@ -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. */
@@ -119,7 +122,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. */
@@ -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
@@ -229,29 +232,20 @@ export function knownPrice(model: string | undefined): { input: number; output:
 /**
  * What one assistant turn cost, from the usage the SDK reports. Pure.
  *
- * Cache reads and writes are priced at Anthropic's multipliers
- * (catalog.ts). Counting both at the full input rate — as this did —
+ * 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.
  *
- * 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.
+ * The run record's own cost is repriced from the catalogue afterwards and
+ * stays the authority on the bill. This number exists to stop a runaway
+ * step mid-turn, and wants to be close.
  */
-export function priceTurn(u: Record<string, number | undefined>, price: { input: number; output: number } | null): number {
-  const p = price ?? FALLBACK_PRICE;
-  const fresh = u.input_tokens ?? 0;
-  const written = u.cache_creation_input_tokens ?? 0;
-  const read = u.cache_read_input_tokens ?? 0;
-  const outTok = u.output_tokens ?? 0;
-  return (
-    fresh * p.input +
-    written * p.input * CACHE_WRITE_MULTIPLIER +
-    read * p.input * CACHE_READ_MULTIPLIER +
-    outTok * p.output
-  );
+export function priceTurn(u: Record<string, number | undefined>, price: TokenPrice | null): number {
+  return costOf(usageFromSdk(u), price ?? FALLBACK_PRICE);
 }
 
 /**
@@ -321,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 });
@@ -633,10 +628,10 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   // runs its turns on that model, and pricing them at the parent's put a
   // max sub-agent under a fast parent at a fifth of its cost — against the
   // ceiling and on the bill.
-  const turns = new Map<string, { u: Record<string, number | undefined>; price: { input: number; output: number } | null }>();
+  const turns = new Map<string, { u: Record<string, number | undefined>; price: TokenPrice | null }>();
   let anonymousTurns = 0;
   const specByName = new Map((subagents ?? []).map((s) => [s.name, s]));
-  const priceOf = (message: unknown): { input: number; output: number } | null => {
+  const priceOf = (message: unknown): TokenPrice | null => {
     const parent = (message as { parent_tool_use_id?: string | null }).parent_tool_use_id;
     if (!parent) return opts.price ?? null;
     const declared = specByName.get(delegations.get(parent) ?? "")?.model;
@@ -758,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 } : {}),
           });
@@ -783,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
@@ -950,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;
+}

package/src/tool-output.ts

@@ -0,0 +1,82 @@
+// 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: readonly string[]): boolean {
+  return allowed.includes("Read") || allowed.includes("Grep");
+}
+
+/** 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 function previewOrKeep(
+  text: string,
+  keep: KeepIn | null | undefined,
+  label: string,
+  cap: number = RESULT_PREVIEW_CHARS,
+): string {
+  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.)`
+  );
+}