@foldrun/core 2.2.0 → 2.4.0

package/dist/src/store.js

@@ -2573,66 +2573,18 @@ export function flowPatternTemplate(pattern, name, agents) {
  *  billing reads null as zero, not as "unknown, charge something". */
 export function sumAttempts(tries) {
     const costs = tries.map((t) => t.costUsd).filter((c) => typeof c === "number");
+    const turns = tries.map((t) => t.turns).filter((c) => typeof c === "number");
     const toks = tries.map((t) => t.tokens).filter((t) => !!t);
     const secs = tries.map((t) => t.computeSecs).filter((c) => typeof c === "number");
     return {
         costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
         tokens: toks.length ? sumTokens(toks) : null,
         computeSecs: secs.length ? secs.reduce((a, b) => a + b, 0) : null,
+        ...(turns.length ? { turns: turns.reduce((a, b) => a + b, 0) } : {}),
     };
 }
-/** The record's shape from what a step reports (ExecOutcome.usage). */
-export function tokensOf(usage) {
-    if (!usage)
-        return null;
-    return {
-        input: usage.inputTokens,
-        output: usage.outputTokens,
-        cacheRead: usage.cacheReadTokens ?? 0,
-        cacheWrite: usage.cacheWriteTokens ?? 0,
-    };
-}
-/** Field-by-field sum; the cache fields are present in the result whenever
- *  any input had them, so a run of old and new steps still reads whole. */
-export function sumTokens(list) {
-    const out = { input: 0, output: 0 };
-    for (const t of list) {
-        out.input += t.input;
-        out.output += t.output;
-        if (t.cacheRead !== undefined || t.cacheWrite !== undefined) {
-            out.cacheRead = (out.cacheRead ?? 0) + (t.cacheRead ?? 0);
-            out.cacheWrite = (out.cacheWrite ?? 0) + (t.cacheWrite ?? 0);
-        }
-    }
-    return out;
-}
-/** The share of all input that the prompt cache served, 0–1; null when
- *  there was no input, or the record predates the split and cannot say. */
-export function cacheHitRate(t) {
-    if (!t || t.cacheRead === undefined)
-        return null;
-    return t.input > 0 ? Math.min(1, t.cacheRead / t.input) : null;
-}
-/** The cache share over several counts, taking only those that report the
- *  split: a step recorded before it holds its cache traffic inside `input`,
- *  and counting that as uncached would understate the rate. The rule the
- *  Usage page and the CLI's totals follow too. */
-export function measuredHitRate(list) {
-    let read = 0;
-    let all = 0;
-    for (const t of list) {
-        if (!t || t.cacheRead === undefined)
-            continue;
-        read += t.cacheRead;
-        all += t.input;
-    }
-    return all > 0 ? read / all : null;
-}
-/** A run's token counts, summed over its steps; null when no step reported any. */
-export function runTokens(run) {
-    const toks = run.steps.map((s) => s.tokens).filter((t) => !!t);
-    return toks.length ? sumTokens(toks) : null;
-}
+export { tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.js";
+import { sumTokens } from "./tokens.js";
 export function runFilePath(tenant, workspace, runId) {
     assertSafeName(runId, "run id");
     return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);

package/dist/src/tokens.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The token counts behind a step's cost. `input` is every input token the
+ * model saw; `cacheRead` and `cacheWrite` are the part of it the prompt
+ * cache served or stored — a read costs a tenth of fresh input, and a usage
+ * page wants to say how much of a step's context was re-read rather than
+ * re-sent. Steps recorded before 18 Oct 2026 have no cache fields: their
+ * `input` is the same total, but how much of it was cached is unknown.
+ */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** The record's shape from what a step reports (ExecOutcome.usage). */
+export declare function tokensOf(usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+} | null | undefined): TokenUsage | null;
+/** Field-by-field sum; the cache fields are present in the result whenever
+ *  any input had them, so a run of old and new steps still reads whole. */
+export declare function sumTokens(list: readonly TokenUsage[]): TokenUsage;
+/** The share of all input that the prompt cache served, 0–1; null when
+ *  there was no input, or the record predates the split and cannot say. */
+export declare function cacheHitRate(t: TokenUsage | null | undefined): number | null;
+/** The cache share over several counts, taking only those that report the
+ *  split: a step recorded before it holds its cache traffic inside `input`,
+ *  and counting that as uncached would understate the rate. The rule the
+ *  Usage page and the CLI's totals follow too. */
+export declare function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null;
+/** A run's token counts, summed over its steps; null when no step reported any. */
+export declare function runTokens(run: {
+    steps: readonly {
+        tokens?: TokenUsage | null;
+    }[];
+}): TokenUsage | null;

package/dist/src/tokens.js

@@ -0,0 +1,58 @@
+// Token counts and the prompt-cache share, as pure functions over values.
+//
+// No node imports: the dashboard's client components read these (the run
+// page's step chips), and store.ts — fs, path, the tree reader — must never
+// reach a browser bundle (web ae042d6 broke `next build` doing exactly that).
+// store.ts re-exports everything here, so server code imports as before.
+/** The record's shape from what a step reports (ExecOutcome.usage). */
+export function tokensOf(usage) {
+    if (!usage)
+        return null;
+    return {
+        input: usage.inputTokens,
+        output: usage.outputTokens,
+        cacheRead: usage.cacheReadTokens ?? 0,
+        cacheWrite: usage.cacheWriteTokens ?? 0,
+    };
+}
+/** Field-by-field sum; the cache fields are present in the result whenever
+ *  any input had them, so a run of old and new steps still reads whole. */
+export function sumTokens(list) {
+    const out = { input: 0, output: 0 };
+    for (const t of list) {
+        out.input += t.input;
+        out.output += t.output;
+        if (t.cacheRead !== undefined || t.cacheWrite !== undefined) {
+            out.cacheRead = (out.cacheRead ?? 0) + (t.cacheRead ?? 0);
+            out.cacheWrite = (out.cacheWrite ?? 0) + (t.cacheWrite ?? 0);
+        }
+    }
+    return out;
+}
+/** The share of all input that the prompt cache served, 0–1; null when
+ *  there was no input, or the record predates the split and cannot say. */
+export function cacheHitRate(t) {
+    if (!t || t.cacheRead === undefined)
+        return null;
+    return t.input > 0 ? Math.min(1, t.cacheRead / t.input) : null;
+}
+/** The cache share over several counts, taking only those that report the
+ *  split: a step recorded before it holds its cache traffic inside `input`,
+ *  and counting that as uncached would understate the rate. The rule the
+ *  Usage page and the CLI's totals follow too. */
+export function measuredHitRate(list) {
+    let read = 0;
+    let all = 0;
+    for (const t of list) {
+        if (!t || t.cacheRead === undefined)
+            continue;
+        read += t.cacheRead;
+        all += t.input;
+    }
+    return all > 0 ? read / all : null;
+}
+/** A run's token counts, summed over its steps; null when no step reported any. */
+export function runTokens(run) {
+    const toks = run.steps.map((s) => s.tokens).filter((t) => !!t);
+    return toks.length ? sumTokens(toks) : null;
+}

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

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

package/dist/src/tool-output.js

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

package/package.json

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

package/src/api-tools.ts

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

package/src/evals.ts

@@ -31,7 +31,8 @@
 // they pass — no point paying a model to grade output already known to be
 // wrong.
 
-import { accountModelEnv } from "./model-env.ts";
+import { accountModelEnv, withModelEnv } from "./model-env.ts";
+import type { TranslatorSpec } from "./translator.ts";
 import { sdkEnv } from "./step-exec.ts";
 import fs from "node:fs";
 import path from "node:path";
@@ -515,7 +516,7 @@ async function checkAssertion(
   agentDir: string,
   model: string,
   effort: Effort | null,
-  judgeEnv: () => Record<string, string | undefined> = () => sdkEnv(undefined),
+  judgeEnv: () => { env: Record<string, string | undefined>; translator?: TranslatorSpec | null } = () => ({ env: sdkEnv(undefined) }),
 ): Promise<AssertionResult> {
   const hay = output.toLowerCase();
   switch (assertion.type) {
@@ -550,13 +551,13 @@ async function checkAssertion(
     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: Record<string, string | undefined>;
+      let m: ReturnType<typeof judgeEnv>;
       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" };
     }
@@ -639,13 +640,7 @@ export async function runEval(
       const judges = testCase.expect.filter((a) => a.type === "judge");
       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));
       } else {
         for (const a of judges) {

package/src/model-env.ts

@@ -11,6 +11,8 @@ import { readAgentsMd } from "./runner.ts";
 import { getSecret } from "./secrets.ts";
 import { platform } from "./platform.ts";
 import { accountModelBlock, isClaudeLoginToken } from "./model-credential.ts";
+import { providerPreset } from "./providers.ts";
+import { startTranslator, translatorSpecFor, type TranslatorSpec } from "./translator.ts";
 
 /** Refused for want of a usable key; `status` is what an HTTP layer answers. */
 export class ModelKeyError extends Error {
@@ -28,14 +30,20 @@ export const NO_MODEL_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: string,
   workspace: string,
   platformEnv: () => Record<string, string | undefined>,
-): { env: Record<string, string | undefined>; supply: "provider" | "platform"; format: string } {
+): {
+  env: Record<string, string | undefined>;
+  supply: "provider" | "platform";
+  format: string;
+  translator: TranslatorSpec | null;
+} {
   const raw =
     (readAgentsMd(workspaceDir(tenant, workspace))?.data?.provider as Record<string, unknown> | undefined) ??
     (readAgentsMd(accountDir(tenant))?.data?.provider as Record<string, unknown> | undefined) ??
@@ -43,7 +51,7 @@ export function accountModelEnv(
   const spec = parseProvider(raw);
   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: string) =>
     text.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => getSecret(tenant, name, workspace)?.value ?? whole);
@@ -52,15 +60,39 @@ export function accountModelEnv(
   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<T>(
+  m: { env: Record<string, string | undefined>; translator?: TranslatorSpec | null },
+  fn: (env: Record<string, string | undefined>) => Promise<T>,
+): Promise<T> {
+  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/src/run-container.ts

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

package/src/runner.ts

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