@foldrun/core 2.2.0 → 2.4.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/evals.js

@@ -30,7 +30,7 @@
 // Deterministic checks run first and cost nothing. The judge only runs if
 // they pass — no point paying a model to grade output already known to be
 // wrong.
-import { accountModelEnv } from "./model-env.js";
+import { accountModelEnv, withModelEnv } from "./model-env.js";
 import { sdkEnv } from "./step-exec.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -382,7 +382,7 @@ async function judge(rubric, output, model, effort, env) {
     }
     return text.trim();
 }
-async function checkAssertion(assertion, output, agentDir, model, effort, judgeEnv = () => sdkEnv(undefined)) {
+async function checkAssertion(assertion, output, agentDir, model, effort, judgeEnv = () => ({ env: sdkEnv(undefined) })) {
     const hay = output.toLowerCase();
     switch (assertion.type) {
         case "contains": {
@@ -417,14 +417,14 @@ async function checkAssertion(assertion, output, agentDir, model, effort, judgeE
         case "judge": {
             // The judge runs on the account's own model key, never quietly on the
             // platform's: a customer's eval is not the operator's bill.
-            let env;
+            let m;
             try {
-                env = judgeEnv();
+                m = judgeEnv();
             }
             catch (err) {
                 return { assertion, passed: false, detail: `judge not run — ${err instanceof Error ? err.message : String(err)}` };
             }
-            const verdict = await judge(assertion.value, output, model, effort, env);
+            const verdict = await withModelEnv(m, (env) => judge(assertion.value, output, model, effort, env));
             const passed = /^\s*PASS\b/i.test(verdict);
             return { assertion, passed, detail: verdict.slice(0, 300) || "judge returned nothing" };
         }
@@ -495,13 +495,7 @@ export async function runEval(tenant, workspace, info) {
             for (const a of cheap)
                 assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort));
             if (assertions.every((r) => r.passed)) {
-                const judgeEnv = () => {
-                    const m = accountModelEnv(tenant, workspace, () => sdkEnv(undefined));
-                    if (m.format !== "anthropic") {
-                        throw new Error(`this account's provider speaks ${m.format}; a judge needs an Anthropic-format provider`);
-                    }
-                    return m.env;
-                };
+                const judgeEnv = () => accountModelEnv(tenant, workspace, () => sdkEnv(undefined));
                 for (const a of judges)
                     assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort, judgeEnv));
             }

package/dist/src/model-env.d.ts

@@ -1,3 +1,4 @@
+import { type TranslatorSpec } from "./translator.ts";
 /** Refused for want of a usable key; `status` is what an HTTP layer answers. */
 export declare class ModelKeyError extends Error {
     readonly status: number;
@@ -7,11 +8,22 @@ export declare const NO_MODEL_KEY: string;
 /**
  * `platform` is a function: the caller's own way to build the platform's env
  * (a step's, or the SDK's host env), called only when this account may use
- * it. `format` says what the endpoint speaks — a caller with no translator
- * refuses anything but anthropic.
+ * it. `format` says what the endpoint speaks; `translator` is set when it is
+ * not Anthropic's, and `withModelEnv` puts the step's translator in front of
+ * it, so a judge or a draft works on any key a run works on (FOL-16).
  */
 export declare function accountModelEnv(tenant: string, workspace: string, platformEnv: () => Record<string, string | undefined>): {
     env: Record<string, string | undefined>;
     supply: "provider" | "platform";
     format: string;
+    translator: TranslatorSpec | null;
 };
+/**
+ * Run `fn` with the model env, through a translator on this host when the
+ * provider speaks Chat Completions or Responses — the same one a step uses
+ * (runner.ts), started for this call and closed after it.
+ */
+export declare function withModelEnv<T>(m: {
+    env: Record<string, string | undefined>;
+    translator?: TranslatorSpec | null;
+}, fn: (env: Record<string, string | undefined>) => Promise<T>): Promise<T>;

package/dist/src/model-env.js

@@ -10,6 +10,8 @@ import { readAgentsMd } from "./runner.js";
 import { getSecret } from "./secrets.js";
 import { platform } from "./platform.js";
 import { accountModelBlock, isClaudeLoginToken } from "./model-credential.js";
+import { providerPreset } from "./providers.js";
+import { startTranslator, translatorSpecFor } from "./translator.js";
 /** Refused for want of a usable key; `status` is what an HTTP layer answers. */
 export class ModelKeyError extends Error {
     status;
@@ -23,8 +25,9 @@ export const NO_MODEL_KEY = "no model key: this account runs on its own API key,
 /**
  * `platform` is a function: the caller's own way to build the platform's env
  * (a step's, or the SDK's host env), called only when this account may use
- * it. `format` says what the endpoint speaks — a caller with no translator
- * refuses anything but anthropic.
+ * it. `format` says what the endpoint speaks; `translator` is set when it is
+ * not Anthropic's, and `withModelEnv` puts the step's translator in front of
+ * it, so a judge or a draft works on any key a run works on (FOL-16).
  */
 export function accountModelEnv(tenant, workspace, platformEnv) {
     const raw = readAgentsMd(workspaceDir(tenant, workspace))?.data?.provider ??
@@ -34,7 +37,7 @@ export function accountModelEnv(tenant, workspace, platformEnv) {
     if (!spec?.baseUrl) {
         if (!platform.platformKeyAllowed(tenant))
             throw new ModelKeyError(NO_MODEL_KEY);
-        return { env: platformEnv(), supply: "platform", format: "anthropic" };
+        return { env: platformEnv(), supply: "platform", format: "anthropic", translator: null };
     }
     const sub = (text) => text.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => getSecret(tenant, name, workspace)?.value ?? whole);
     const token = sub(spec.token);
@@ -43,15 +46,37 @@ export function accountModelEnv(tenant, workspace, platformEnv) {
     if (!platform.platformKeyAllowed(tenant) && isClaudeLoginToken(token)) {
         throw new ModelKeyError("model key: a Claude login token (sk-ant-oat…) cannot be used here — use an API key from your provider", 422);
     }
+    const headers = Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, sub(v)]));
+    const preset = providerPreset(spec.name);
     return {
-        env: providerEnvFor({
+        env: providerEnvFor({ baseUrl: spec.baseUrl, token, auth: spec.auth, models: spec.models, headers }),
+        supply: "provider",
+        format: spec.format,
+        translator: translatorSpecFor({
+            format: spec.format,
             baseUrl: spec.baseUrl,
             token,
-            auth: spec.auth,
-            models: spec.models,
-            headers: Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, sub(v)])),
+            headers,
+            params: spec.params,
+            name: spec.name,
+            maxTokensParam: preset?.maxTokensParam,
+            reasoningEffort: preset?.reasoningEffort,
         }),
-        supply: "provider",
-        format: spec.format,
     };
 }
+/**
+ * Run `fn` with the model env, through a translator on this host when the
+ * provider speaks Chat Completions or Responses — the same one a step uses
+ * (runner.ts), started for this call and closed after it.
+ */
+export async function withModelEnv(m, fn) {
+    if (!m.translator)
+        return fn(m.env);
+    const t = await startTranslator(m.translator);
+    try {
+        return await fn({ ...m.env, ...t.env });
+    }
+    finally {
+        await t.close();
+    }
+}

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

@@ -145,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;
@@ -366,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,6 +34,7 @@ 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 { 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";
@@ -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;
@@ -2623,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),
@@ -2673,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));
@@ -2870,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

@@ -48,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. */
@@ -166,6 +169,7 @@ export type EventExtra = {
     call?: string;
     ms?: number;
     err?: boolean;
+    bytes?: number;
     effect?: TestEffect;
     operator?: OperatorEvent;
     subagent?: string;

package/dist/src/step-exec.js

@@ -157,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 });
@@ -615,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 } : {}),
                         });
@@ -642,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
@@ -821,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 } : {}),
     };
 }

package/dist/src/store.d.ts

@@ -893,6 +893,10 @@ export interface RunEvent {
     call?: string;
     ms?: number;
     err?: boolean;
+    /** On a tool completion: the result's length in characters — what it put
+     *  into the conversation, which every later turn sends again. Absent before
+     *  18 Oct 2026. */
+    bytes?: number;
     /** Set on a test run's event that reports what the platform did instead
      *  of the real thing — a refused send, a redirected email, a diverted
      *  state write, a withheld secret. The run page lists these; the text is
@@ -954,6 +958,8 @@ export interface StepAttempt {
     status: "completed" | "failed" | "lost";
     costUsd: number | null;
     tokens: TokenUsage | null;
+    /** Model turns this attempt took; absent before 18 Oct 2026. */
+    turns?: number | null;
     computeSecs: number | null;
     startedAt: string;
     finishedAt: string;
@@ -968,45 +974,9 @@ export interface StepAttempt {
 /** The step's totals across its attempts, from the rows. Null where no
  *  attempt reported the figure — an in-process step rents no sandbox, and
  *  billing reads null as zero, not as "unknown, charge something". */
-export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs">;
-/**
- * The token counts behind a step's cost. `input` is every input token the
- * model saw; `cacheRead` and `cacheWrite` are the part of it the prompt
- * cache served or stored — a read costs a tenth of fresh input, and a usage
- * page wants to say how much of a step's context was re-read rather than
- * re-sent. Steps recorded before 18 Oct 2026 have no cache fields: their
- * `input` is the same total, but how much of it was cached is unknown.
- */
-export interface TokenUsage {
-    input: number;
-    output: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-}
-/** The record's shape from what a step reports (ExecOutcome.usage). */
-export declare function tokensOf(usage: {
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-} | null | undefined): TokenUsage | null;
-/** Field-by-field sum; the cache fields are present in the result whenever
- *  any input had them, so a run of old and new steps still reads whole. */
-export declare function sumTokens(list: readonly TokenUsage[]): TokenUsage;
-/** The share of all input that the prompt cache served, 0–1; null when
- *  there was no input, or the record predates the split and cannot say. */
-export declare function cacheHitRate(t: TokenUsage | null | undefined): number | null;
-/** The cache share over several counts, taking only those that report the
- *  split: a step recorded before it holds its cache traffic inside `input`,
- *  and counting that as uncached would understate the rate. The rule the
- *  Usage page and the CLI's totals follow too. */
-export declare function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null;
-/** A run's token counts, summed over its steps; null when no step reported any. */
-export declare function runTokens(run: {
-    steps: readonly {
-        tokens?: TokenUsage | null;
-    }[];
-}): TokenUsage | null;
+export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
+export { type TokenUsage, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.ts";
+import { type TokenUsage } from "./tokens.ts";
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1195,6 +1165,14 @@ export interface StepRecord {
      *  and not only "how much" — the price of a token changes, the count is
      *  the fact. Absent on steps recorded before this existed. */
     tokens?: TokenUsage | null;
+    /** Model turns, summed across attempts, and the system prompt's length in
+     *  characters — every turn sends it again. With the tool events' `bytes`,
+     *  what says where a step's input tokens went. Absent before 18 Oct 2026. */
+    turns?: number | null;
+    systemPromptChars?: number;
+    /** Why the model's last turn ended (end_turn, max_tokens, tool_use…), as
+     *  the SDK's closing result says. */
+    stopReason?: string | null;
     /** What the sandbox actually touched, against what it reserved: CPU
      *  busy-seconds and peak memory from the pod's own cgroup, bytes on the
      *  wire from /proc/net/dev. Null per-field where the kernel interface