@foldrun/core 2.1.0 → 2.3.0

package/dist/src/api-tools.d.ts

@@ -1,5 +1,6 @@
 import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import type { ApiSpec } from "./store.ts";
+import { type KeepIn } from "./tool-output.ts";
 export declare function secretsUsedByApi(api: ApiSpec): string[];
 /**
  * A token bucket: `count` tokens, refilled at `perSec`. `take()` resolves
@@ -43,4 +44,7 @@ export interface ApiToolResult {
 export declare function buildApiTools(tenant: string, apis: ApiSpec[], workspace?: string, resolved?: {
     env: Record<string, string | undefined>;
     missing: string[];
-}): ApiToolResult;
+}, 
+/** 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;

package/dist/src/api-tools.js

@@ -16,8 +16,11 @@ import crypto from "node:crypto";
 import { EGRESS_ENV, viaEgress } from "./egress.js";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { previewOrKeep, RESULT_KEEP_CHARS } from "./tool-output.js";
 import { resolveSecrets, materializeSecrets } from "./secrets.js";
-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. */
@@ -92,7 +95,9 @@ export function typedToolName(apiName, opId) {
  * the truncation, the log line. Typed and generic tools differ only in how
  * they arrive at a Request.
  */
-async function performRequest(api, env, bucket, log, req) {
+async function performRequest(api, env, bucket, log, req, 
+/** Where a long body is kept, when the agent can read it back (tool-output.ts). */
+keepIn) {
     const started = Date.now();
     try {
         const waited = bucket ? await bucket.take() : 0;
@@ -133,9 +138,10 @@ async function performRequest(api, env, bucket, log, req) {
             ...(api.timeout ? { signal: AbortSignal.timeout(api.timeout * 1000) } : {}),
         });
         const text = await res.text();
-        const truncated = text.length > MAX_BODY_CHARS
+        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}`);
         return {
             content: [{ type: "text", text: `HTTP ${res.status} ${res.statusText}\n\n${truncated}` }],
@@ -177,7 +183,7 @@ function argKeys(op) {
     }
     return out;
 }
-function typedTool(api, op, env, bucket, log) {
+function typedTool(api, op, env, bucket, log, keepIn) {
     const keys = argKeys(op);
     const shape = {};
     for (const [key, p] of keys)
@@ -229,10 +235,10 @@ function typedTool(api, op, env, bucket, log) {
             query,
             headers,
             body: typeof values.body === "string" ? values.body : undefined,
-        });
+        }, keepIn);
     });
 }
-function genericTool(api, env, bucket, log) {
+function genericTool(api, env, bucket, log, keepIn) {
     const typed = api.resolvedOperations?.length
         ? ` Prefer the typed ${api.name}_* tools; this one is the escape hatch for operations they do not cover.`
         : "";
@@ -252,12 +258,15 @@ function genericTool(api, env, bucket, log) {
         query: args.query ?? {},
         headers: {},
         body: args.body,
-    }));
+    }, keepIn));
 }
 export function buildApiTools(tenant, apis, workspace, 
 // The runner container passes this: secrets were resolved before the specs
 // crossed the boundary, and there is no vault in there to ask.
-resolved) {
+resolved, 
+/** 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) {
     if (apis.length === 0) {
         return { server: null, toolNames: [], owners: {}, methods: {}, missingSecrets: [], promptLines: [], drainLog: () => [] };
     }
@@ -302,12 +311,12 @@ resolved) {
         }
         const typedNames = [];
         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));
+            tools.push(genericTool(api, env, bucket, log, keepIn));
         const names = [...typedNames, ...(withGeneric ? [`call_${api.name}`] : [])];
         for (const n of names) {
             toolNames.push(`mcp__foldrun_apis__${n}`);

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;
@@ -86,9 +95,33 @@ export declare function catalogCost(catalog: Catalog | null, modelId: string, us
     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. 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 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

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,21 +209,39 @@ export function catalogCost(catalog, modelId, usage) {
     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));
+}
+/** 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);
-    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;
 /** Catalogue entries as completion items: price per MTok, context, and the

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

@@ -2,6 +2,7 @@ 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, 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";
@@ -147,6 +145,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;
@@ -368,6 +369,7 @@ export declare function parseDriverLine(line: string): {
     call?: string;
     ms?: number;
     err?: boolean;
+    bytes?: number;
     operator?: OperatorEvent;
     subagent?: string;
     check?: boolean;

package/dist/src/run-container.js

@@ -536,13 +536,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
@@ -1049,6 +1054,7 @@ export function parseDriverLine(line) {
                 ...(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 } : {}),
@@ -1064,6 +1070,8 @@ export function parseDriverLine(line) {
                 ...("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 &&
                     typeof parsed.usage.inputTokens === "number" &&

package/dist/src/runner.js

@@ -34,7 +34,8 @@ 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, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
-import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
+import { canReadBack } from "./tool-output.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";
@@ -920,7 +921,12 @@ grantsOnly = false) {
     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")}`);
     }
@@ -1254,7 +1260,7 @@ grantsOnly = false) {
         // (/workspace/agents/<agent>) do not carry the name.
         FOLDRUN_WORKSPACE: workspace,
         ...clockEnv,
-    }, libraryDir(tenant, "scripts"), runtime.interpreters, exec);
+    }, libraryDir(tenant, "scripts"), runtime.interpreters, exec, keepIn.readable);
     parts.push(`# Clock\n\nToday is ${clockEnv.FOLDRUN_DATE} (${timezone}). Use this date for anything you ` +
         `write or check — it is the workspace's calendar, not the container's clock.`);
     if (scriptTools.promptLines.length) {
@@ -1462,6 +1468,7 @@ grantsOnly = false) {
     if (denied.includes("install"))
         denied.push(INSTALL_TOOL);
     const finalAllowed = allowed.filter((t) => !denied.includes(t));
+    readsFiles = canReadBack(finalAllowed);
     return {
         front,
         clockEnv,
@@ -1621,6 +1628,7 @@ reattach = false) {
         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(),
@@ -1634,6 +1642,8 @@ reattach = false) {
     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
  *  workspace's notify:, `awaiting-approval` events), with the way to answer. */
@@ -1842,6 +1852,9 @@ stepIndex) {
         const { front, clockEnv, clock, systemPrompt, allowed, disabled, apiTools, scriptTools, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, retiredTools, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size: agentSize, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, searchChoice, fetchChoice, actionChoices, web, language, region, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, ask, translator, fallbackTranslator, outward, } = 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;
@@ -2002,10 +2015,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";
@@ -2626,6 +2636,7 @@ stepIndex) {
                         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),
@@ -2676,6 +2687,8 @@ stepIndex) {
                 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) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
@@ -2873,6 +2886,8 @@ stepIndex) {
             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())

package/dist/src/script-tools.d.ts

@@ -88,4 +88,7 @@ export declare function resolveRunPath(agentDir: string, run: string, libraryScr
  * have been.
  */
 export declare function scriptArgShape(args: Record<string, string>): Record<string, z.ZodTypeAny>;
-export declare function buildScriptTools(agentDir: string, scripts: ScriptSpec[], env: Record<string, string>, libraryScripts?: string, interpreters?: Record<string, string>, exec?: ExecutionContext | null): ScriptToolResult;
+export declare function buildScriptTools(agentDir: string, scripts: ScriptSpec[], env: Record<string, string>, libraryScripts?: string, interpreters?: Record<string, string>, exec?: ExecutionContext | 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): ScriptToolResult;

package/dist/src/script-tools.js

@@ -22,13 +22,16 @@ import { runInContainer } from "./container.js";
 import { hostSafeEnv } from "./host-env.js";
 import { workspaceLinkEnv } from "./confine.js";
 import { platform } from "./platform.js";
+import { previewOrKeep, RESULT_KEEP_CHARS } from "./tool-output.js";
 // 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
 // platform's opinion about how long a person's script may take, and the
 // 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) => (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 function parseScripts(raw) {
     if (!Array.isArray(raw))
         return [];
@@ -339,7 +342,10 @@ export function scriptArgShape(args) {
     }
     return shape;
 }
-export function buildScriptTools(agentDir, scripts, env, libraryScripts = "", interpreters = {}, exec = null) {
+export function buildScriptTools(agentDir, scripts, env, libraryScripts = "", interpreters = {}, exec = 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 = () => false) {
     if (scripts.length === 0) {
         return { server: null, toolNames: [], promptLines: [], drainLog: () => [] };
     }
@@ -364,7 +370,7 @@ export function buildScriptTools(agentDir, scripts, env, libraryScripts = "", in
             log.push(`${spec.name}(${shown}) → exit ${code ?? "error"} ` +
                 `(${Date.now() - started}ms, ${exec?.executor ?? "sandbox"})`);
             return {
-                content: [{ type: "text", text: `exit ${code ?? "error"}\n\n${out}` }],
+                content: [{ type: "text", text: `exit ${code ?? "error"}\n\n${previewOrKeep(out, { dir: agentDir, readable }, spec.name)}` }],
                 isError: code !== 0,
             };
         });

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

@@ -1,6 +1,7 @@
 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";
@@ -47,6 +48,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. */
@@ -89,10 +93,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. */
@@ -168,6 +169,7 @@ export type EventExtra = {
     call?: string;
     ms?: number;
     err?: boolean;
+    bytes?: number;
     effect?: TestEffect;
     operator?: OperatorEvent;
     subagent?: string;
@@ -190,21 +192,19 @@ export declare function knownPrice(model: string | undefined): {
 /**
  * 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 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,7 +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 { CACHE_READ_MULTIPLIER, CACHE_WRITE_MULTIPLIER } from "./catalog.js";
+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";
@@ -81,27 +81,20 @@ export function knownPrice(model) {
 /**
  * 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, 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
@@ -164,6 +157,7 @@ async function executeStepInner(opts, runQuery) {
     let costUsd = null;
     let usage = null;
     let stopReason = null;
+    let numTurns = null;
     const texts = [];
     fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
     fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
@@ -622,6 +616,9 @@ async function executeStepInner(opts, runQuery) {
                         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 } : {}),
                         });
@@ -649,6 +646,8 @@ 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 ("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
@@ -828,6 +827,7 @@ async function executeStepInner(opts, runQuery) {
         status, result, conclusion, ...(opts.output ? { data } : {}), costUsd, usage,
         ...(mixedModels() ? { turnsCostUsd: turnsTotal() } : {}),
         stopReason,
+        turns: numTurns ?? turns.size,
         ...(pod ? { browserPod: podState } : {}),
     };
 }