@foldrun/core 2.2.0 → 2.4.0

package/src/script-tools.ts

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

package/src/step-exec.ts

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

package/src/store.ts

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

package/src/tokens.ts

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

package/src/tool-output.ts

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