@foldrun/core 2.4.0 → 2.6.0

package/dist/src/otel.js

@@ -0,0 +1,85 @@
+// A run as an OpenTelemetry trace — OTLP/HTTP JSON, the body a collector's
+// /v1/traces takes — so an account's agent runs sit in the tracing it
+// already has (Grafana Tempo, Honeycomb, Datadog, Jaeger, Langfuse…) beside
+// the services they act on. Built from buildTraceTree, the same tree the run
+// page draws: run → step → model call → tool call.
+//
+//   telemetry:
+//     otlp: https://otel.example.com/v1/traces
+//     headers:
+//       authorization: ${OTEL_TOKEN}     # a vault secret, by name
+//
+// In AGENTS.md (the workspace's, else the account's — the block replaces
+// whole, like notify:). Ids are derived from the run and span ids, so a run
+// sent twice is the same trace, not two. No OpenTelemetry SDK: the wire
+// format is small, and a dependency in every runner image is not.
+import crypto from "node:crypto";
+import { buildTraceTree } from "./trace-tree.js";
+export { parseTelemetry, telemetrySecretNames, telemetryHeaders } from "./otel-config.js";
+const attr = (key, v) => {
+    if (v === null || v === undefined || v === "")
+        return [];
+    if (typeof v === "boolean")
+        return [{ key, value: { boolValue: v } }];
+    if (typeof v === "number")
+        return [{ key, value: Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v } }];
+    return [{ key, value: { stringValue: v } }];
+};
+const hex = (s, len) => crypto.createHash("sha256").update(s).digest("hex").slice(0, len);
+const nanos = (msEpoch) => (BigInt(Math.round(msEpoch)) * BigInt(1_000_000)).toString();
+/** OTLP span kinds: INTERNAL, and CLIENT for a call that leaves the platform. */
+const SPAN_KIND = { internal: 1, client: 3 };
+/** The ExportTraceServiceRequest for one run. */
+export function runToOtlp(run, ctx, now = Date.now()) {
+    const tree = buildTraceTree(run, now);
+    const traceId = hex(`foldrun-trace\0${ctx.tenant}\0${ctx.workspace}\0${run.id}`, 32);
+    const spans = [];
+    const visit = (s, parent, inherited) => {
+        const spanId = hex(`${traceId}\0${s.id}`, 16);
+        const start = s.start ?? inherited.start;
+        const end = Math.max(start, s.end ?? s.start ?? now);
+        const step = s.step !== undefined ? run.steps[s.step] : undefined;
+        const agent = s.kind === "step" ? step?.agent : inherited.agent;
+        spans.push({
+            traceId,
+            spanId,
+            ...(parent ? { parentSpanId: parent } : {}),
+            name: s.kind === "run" ? `run ${s.label}` : s.kind === "step" ? `step ${s.label}` : s.kind === "model" ? `chat ${s.model ?? s.label}` : s.kind === "tool" ? `tool ${s.label}` : s.label,
+            kind: s.kind === "model" ? SPAN_KIND.client : SPAN_KIND.internal,
+            startTimeUnixNano: nanos(start),
+            endTimeUnixNano: nanos(end),
+            attributes: [
+                ...attr("foldrun.span.kind", s.kind),
+                ...attr("foldrun.status", s.status),
+                ...(s.kind === "step" ? [...attr("foldrun.agent", agent), ...attr("foldrun.owner", agent ? ctx.owners?.[agent] ?? null : null), ...attr("foldrun.step", s.step)] : []),
+                ...attr("gen_ai.request.model", s.model),
+                ...(s.tokens ? [...attr("gen_ai.usage.input_tokens", s.tokens.input), ...attr("gen_ai.usage.output_tokens", s.tokens.output), ...attr("gen_ai.usage.cache_read_tokens", s.tokens.cacheRead), ...attr("gen_ai.usage.cache_write_tokens", s.tokens.cacheWrite)] : []),
+                ...attr("gen_ai.response.finish_reason", s.stop),
+                ...(typeof s.costUsd === "number" ? attr("foldrun.cost_usd", s.costUsd) : []),
+                ...(s.kind === "tool" ? [...attr("gen_ai.tool.name", s.label), ...attr("gen_ai.tool.call.id", s.call)] : []),
+                ...attr("foldrun.subagent", s.subagent),
+            ],
+            status: s.status === "error" ? { code: 2, ...(s.text ? { message: s.text.slice(0, 500) } : {}) } : { code: 0 },
+        });
+        for (const c of s.children)
+            visit(c, spanId, { start, agent });
+    };
+    visit(tree, null, { start: Date.parse(run.startedAt) || now });
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        ...attr("service.name", "foldrun"),
+                        ...attr("foldrun.account", ctx.tenant),
+                        ...attr("foldrun.workspace", ctx.workspace),
+                        ...attr("foldrun.flow", run.flow),
+                        ...attr("foldrun.run_id", run.id),
+                        ...attr("foldrun.started_by", run.startedBy ?? null),
+                    ],
+                },
+                scopeSpans: [{ scope: { name: "foldrun", ...(ctx.version ? { version: ctx.version } : {}) }, spans }],
+            },
+        ],
+    };
+}

package/dist/src/outcome.d.ts

@@ -0,0 +1,40 @@
+export type Outcome = "running" | "queued" | "waiting" | "good" | "done" | "quiet" | "blocked" | "bad" | "failed" | "stopped";
+export declare const OUTCOMES: readonly Outcome[];
+/** From the display status (store.runDisplayStatus) and the verdict (store.runVerdict). */
+export declare function outcomeOf(status: string, verdict: string | null | undefined): Outcome;
+/** Still going: not an outcome yet. */
+export declare const isLive: (o: Outcome) => o is "queued" | "running" | "waiting";
+/** Ran to the end without failing — whatever it found. */
+export declare const isCompleted: (o: Outcome) => o is "bad" | "blocked" | "done" | "good" | "quiet";
+/** Over and countable for a rate: completed or failed. A run a person stopped is left out. */
+export declare const isFinished: (o: Outcome) => o is "bad" | "blocked" | "done" | "failed" | "good" | "quiet";
+/** Went wrong or found something wrong: failed, BAD, BLOCKED. */
+export declare const needsAttention: (o: Outcome) => o is "bad" | "blocked" | "failed";
+/** A person has something to do: what needsAttention says, and a run
+ *  waiting on an approval or an answer (Codex review). */
+export declare const needsAction: (o: Outcome) => o is "bad" | "blocked" | "failed" | "waiting";
+/** Completed and reported nothing wrong (GOOD, QUIET, or nothing said). */
+export declare const isSuccess: (o: Outcome) => o is "done" | "good" | "quiet";
+export interface Tally {
+    /** Every run counted, live ones included. */
+    runs: number;
+    /** Running, queued, or waiting on a person. */
+    live: number;
+    /** Waiting on an approval or an answer. */
+    waiting: number;
+    stopped: number;
+    /** Completed + failed: the runs a rate is taken over. */
+    finished: number;
+    /** Ran to the end without failing. */
+    completed: number;
+    failed: number;
+    /** What the completed runs found. */
+    ok: number;
+    quiet: number;
+    blocked: number;
+    bad: number;
+    /** completed / finished, as a whole percent; null with nothing finished. */
+    completedPct: number | null;
+}
+/** The one count of a set of outcomes that every surface shows. */
+export declare function tally(outcomes: Iterable<Outcome>): Tally;

package/dist/src/outcome.js

@@ -0,0 +1,77 @@
+// A run's outcome, and the one way every surface counts outcomes (FOL-54).
+//
+// A run is read on three separate lines, never folded into one "success":
+//   · execution — did it run to the end without failing? (completed, failed,
+//     stopped by a person, or still live)
+//   · result    — what the work concluded: GOOD, QUIET, BLOCKED, BAD, or
+//     nothing said (done)
+//   · action    — does a person need to do something? (an approval or a
+//     question waiting, a failure, a BLOCKED, a BAD finding)
+//
+// Before this, five surfaces computed five different "success rates" (one
+// counted BAD as success, one counted stopped runs as failures, …), so the
+// same desk read four different percentages. Every page, the API and the
+// CLI now read `tally()`. Pure: no node imports, so the browser can use it.
+export const OUTCOMES = ["running", "queued", "waiting", "good", "done", "quiet", "blocked", "bad", "failed", "stopped"];
+/** From the display status (store.runDisplayStatus) and the verdict (store.runVerdict). */
+export function outcomeOf(status, verdict) {
+    if (status === "running")
+        return "running";
+    if (status === "queued")
+        return "queued";
+    if (status === "awaiting-approval")
+        return "waiting";
+    if (status === "stopped")
+        return "stopped";
+    if (status === "failed")
+        return "failed";
+    switch (verdict) {
+        case "GOOD": return "good";
+        case "QUIET": return "quiet";
+        case "BLOCKED": return "blocked";
+        case "BAD": return "bad";
+        default: return "done";
+    }
+}
+/** Still going: not an outcome yet. */
+export const isLive = (o) => o === "running" || o === "queued" || o === "waiting";
+/** Ran to the end without failing — whatever it found. */
+export const isCompleted = (o) => o === "good" || o === "done" || o === "quiet" || o === "blocked" || o === "bad";
+/** Over and countable for a rate: completed or failed. A run a person stopped is left out. */
+export const isFinished = (o) => isCompleted(o) || o === "failed";
+/** Went wrong or found something wrong: failed, BAD, BLOCKED. */
+export const needsAttention = (o) => o === "failed" || o === "bad" || o === "blocked";
+/** A person has something to do: what needsAttention says, and a run
+ *  waiting on an approval or an answer (Codex review). */
+export const needsAction = (o) => needsAttention(o) || o === "waiting";
+/** Completed and reported nothing wrong (GOOD, QUIET, or nothing said). */
+export const isSuccess = (o) => o === "good" || o === "done" || o === "quiet";
+/** The one count of a set of outcomes that every surface shows. */
+export function tally(outcomes) {
+    const t = { runs: 0, live: 0, waiting: 0, stopped: 0, finished: 0, completed: 0, failed: 0, ok: 0, quiet: 0, blocked: 0, bad: 0, completedPct: null };
+    for (const o of outcomes) {
+        t.runs++;
+        if (isLive(o))
+            t.live++;
+        if (o === "waiting")
+            t.waiting++;
+        if (o === "stopped")
+            t.stopped++;
+        if (isFinished(o))
+            t.finished++;
+        if (isCompleted(o))
+            t.completed++;
+        if (o === "failed")
+            t.failed++;
+        if (o === "good" || o === "done")
+            t.ok++;
+        if (o === "quiet")
+            t.quiet++;
+        if (o === "blocked")
+            t.blocked++;
+        if (o === "bad")
+            t.bad++;
+    }
+    t.completedPct = t.finished ? Math.round((100 * t.completed) / t.finished) : null;
+    return t;
+}

package/dist/src/package.js

@@ -25,7 +25,7 @@
 // claim, the files are what will run.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter, { configMatter } from "./matter.js";
 import { assertSafeName, isEditablePath, listWorkspaceFiles, listWorkspaces, listFlows, parseFlow, readWorkspaceFile, saveWorkspace, blankTemplateFiles, syncBundleFor, notifyWorkspaceChanged, workspaceDir, } from "./store.js";
 import { recordRevision } from "./history.js";
 import { libraryDir, libraryTools } from "./library.js";
@@ -522,7 +522,14 @@ function safeFront(content) {
     }
 }
 function frontOf(content) {
-    const d = safeFront(content);
+    // An agent's secrets: and tools: may sit in its guardrail: block.
+    let d;
+    try {
+        d = configMatter(content).data;
+    }
+    catch {
+        d = {};
+    }
     const apis = Array.isArray(d.apis) ? d.apis.map((a) => (a && typeof a === "object" ? String(a.name ?? "") : "")) : [];
     const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers) : [];
     const scripts = list(d.scripts);

package/dist/src/platform.d.ts

@@ -14,7 +14,7 @@ export type TriggerAdmission = {
     admit: true;
 } | {
     admit: false;
-    reason: "duplicate" | "throttled" | "quarantined" | "paused" | "debounced";
+    reason: "duplicate" | "throttled" | "quarantined" | "paused" | "halted" | "debounced";
     detail: string;
     firesAt?: number;
 };

package/dist/src/prompt-layers.d.ts

@@ -0,0 +1,30 @@
+import type { PromptLayerRecord } from "./tokens.ts";
+export { promptLayersChanged, promptCacheNote, type PromptLayerRecord } from "./tokens.ts";
+export interface AssembledPrompt {
+    /** The whole prompt, stable layers first. */
+    text: string;
+    layers: PromptLayerRecord[];
+}
+export declare function hashLayer(text: string): string;
+/**
+ * A collector agentContext fills in whatever order it computes its
+ * sections. `add` with the same name twice appends to that layer, so a
+ * section built in two places (the platform's rules) is one layer.
+ */
+export declare class PromptLayers {
+    private readonly order;
+    private readonly text;
+    private readonly dynamic;
+    add(name: string, text: string, opts?: {
+        dynamic?: boolean;
+    }): void;
+    assemble(): AssembledPrompt;
+}
+/**
+ * The key an OpenAI-format provider routes a prompt by (`prompt_cache_key`).
+ * One per agent: every step of an agent opens with the same prefix, and a
+ * key that names the account keeps one tenant's cache from being probed
+ * through another's requests. Hashed, since the names are a person's and
+ * the parameter is capped at 64 characters.
+ */
+export declare function promptCacheKey(tenant: string, workspace: string, agent: string): string;

package/dist/src/prompt-layers.js

@@ -0,0 +1,77 @@
+// The system prompt in layers, ordered for the model's prompt cache.
+//
+// Every provider caches a prompt by its prefix: a request whose opening
+// bytes match one it has seen reads the model's work on them instead of
+// paying for it again, and a byte that differs invalidates everything
+// after it. agentContext used to join its sections in the order it
+// computed them, which put the memory index, the state file list and the
+// clock — the three things that change between runs — in the middle.
+//
+// This collector keeps the sections apart by how often they change and
+// assembles them stable first, dynamic last: what Anthropic does for
+// Claude Code ("static content first, dynamic content last"). The prompt
+// still goes to the SDK as one string, cached as one block. The Agent
+// SDK's SYSTEM_PROMPT_DYNAMIC_BOUNDARY would split it, but the CLI honours
+// the marker only when it talks to api.anthropic.com directly — a step
+// behind the egress proxy got one block anyway (live check, 20 Oct 2026;
+// claude-code issue #102518) — and where it does split, it sends the
+// stable half with the CLI's "global" cache scope, which is not a scope to
+// put an account's own prose in. So no marker.
+//
+// Each layer is also hashed, and the hashes ride on the step record
+// (`promptLayers`). A step whose cache writes are high can then say which
+// layer changed since the agent's last step — "memory changed" — instead
+// of leaving a person to diff two 40k-character prompts.
+import crypto from "node:crypto";
+// The record's shape and the readers' comparison live in tokens.ts, which
+// has no node imports and is what the dashboard's client bundle reads.
+export { promptLayersChanged, promptCacheNote } from "./tokens.js";
+const SEP = "\n\n";
+export function hashLayer(text) {
+    return crypto.createHash("sha256").update(text).digest("hex").slice(0, 12);
+}
+/**
+ * A collector agentContext fills in whatever order it computes its
+ * sections. `add` with the same name twice appends to that layer, so a
+ * section built in two places (the platform's rules) is one layer.
+ */
+export class PromptLayers {
+    order = [];
+    text = new Map();
+    dynamic = new Set();
+    add(name, text, opts = {}) {
+        if (!text)
+            return;
+        if (!this.text.has(name)) {
+            this.order.push(name);
+            this.text.set(name, []);
+        }
+        this.text.get(name).push(text);
+        if (opts.dynamic)
+            this.dynamic.add(name);
+    }
+    assemble() {
+        const parts = [];
+        const layers = [];
+        const take = (names, isDynamic) => {
+            for (const name of names) {
+                const joined = this.text.get(name).join(SEP);
+                parts.push(joined);
+                layers.push({ name, chars: joined.length, hash: hashLayer(joined), ...(isDynamic ? { stable: false } : {}) });
+            }
+        };
+        take(this.order.filter((n) => !this.dynamic.has(n)), false);
+        take(this.order.filter((n) => this.dynamic.has(n)), true);
+        return { text: parts.join(SEP), layers };
+    }
+}
+/**
+ * The key an OpenAI-format provider routes a prompt by (`prompt_cache_key`).
+ * One per agent: every step of an agent opens with the same prefix, and a
+ * key that names the account keeps one tenant's cache from being probed
+ * through another's requests. Hashed, since the names are a person's and
+ * the parameter is capped at 64 characters.
+ */
+export function promptCacheKey(tenant, workspace, agent) {
+    return `fr-${crypto.createHash("sha256").update(`${tenant}\u0000${workspace}\u0000${agent}`).digest("hex").slice(0, 32)}`;
+}

package/dist/src/provider-health.js

@@ -20,7 +20,7 @@
 import { accountModelBlock } from "./model-credential.js";
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import { configMatter } from "./matter.js";
 import { getSecret } from "./secrets.js";
 import { noteSecretUse, healthKey } from "./secret-health.js";
 import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider } from "./store.js";
@@ -168,7 +168,7 @@ function cheapestModel(spec) {
 }
 function frontmatterOf(file) {
     try {
-        return (matter(fs.readFileSync(file, "utf8")).data ?? {});
+        return (configMatter(fs.readFileSync(file, "utf8")).data ?? {});
     }
     catch {
         return {};

package/dist/src/providers.d.ts

@@ -20,6 +20,11 @@ export interface ProviderPreset {
      *  Off means the translator drops thinking rather than send a parameter
      *  the endpoint would reject. */
     reasoningEffort?: boolean;
+    /** Whether the endpoint takes `prompt_cache_key` — a hint that requests
+     *  with the same key share a prompt prefix, so its cache can be routed
+     *  to. Only set where the parameter is documented; an endpoint that does
+     *  not know it may refuse the request. */
+    promptCacheKey?: boolean;
     /** One line a person should read before relying on it. */
     note?: string;
     /** A tool loop was driven through this endpoint from this runtime. */

package/dist/src/providers.js

@@ -222,7 +222,7 @@ export const PROVIDERS = [
         note: "base_url is your server (default :8000). Start it with --enable-auto-tool-choice and a --tool-call-parser or no tool loop closes." },
     // ------------------------------------------- Chat-Completions, translated
     { name: "openai", title: "OpenAI", format: "openai", baseUrl: "https://api.openai.com/v1", auth: "bearer", verified: true,
-        maxTokensParam: "max_completion_tokens", reasoningEffort: true,
+        maxTokensParam: "max_completion_tokens", reasoningEffort: true, promptCacheKey: true,
         note: "Reached over Chat Completions, which OpenAI keeps supporting; the Responses API is not spoken here, so a reasoning model's reasoning does not carry across tool calls.", search: "openai" },
     { name: "gemini", title: "Google Gemini", format: "openai", baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai", auth: "bearer",
         note: "Google's OpenAI-compatible route. Unknown parameters are ignored silently; reasoning cannot be switched off on the newest models." },
@@ -230,7 +230,7 @@ export const PROVIDERS = [
         maxTokensParam: "max_completion_tokens", reasoningEffort: true },
     { name: "groq", title: "Groq", format: "openai", baseUrl: "https://api.groq.com/openai/v1", auth: "bearer",
         maxTokensParam: "max_completion_tokens", reasoningEffort: true },
-    { name: "mistral", title: "Mistral", format: "openai", baseUrl: "https://api.mistral.ai/v1", auth: "bearer" },
+    { name: "mistral", title: "Mistral", format: "openai", baseUrl: "https://api.mistral.ai/v1", auth: "bearer", promptCacheKey: true },
     { name: "together", title: "Together AI", format: "openai", baseUrl: "https://api.together.ai/v1", auth: "bearer" },
     { name: "cerebras", title: "Cerebras", format: "openai", baseUrl: "https://api.cerebras.ai/v1", auth: "bearer",
         maxTokensParam: "max_completion_tokens", reasoningEffort: true },

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

@@ -1,7 +1,8 @@
+import type { PeerInfo } from "./operator.ts";
 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 ApiSpec, type Effort, type ModelCall } from "./store.ts";
+import type { CallIo, EventExtra, ExecUsage } from "./step-exec.ts";
 import type { TokenPrice } from "./catalog.ts";
 import { type RuntimeSpec } from "./runtime.ts";
 import { type NetworkLevel } from "./network.ts";
@@ -44,11 +45,16 @@ export interface ContainerStepInput {
     budgetNote?: string;
     price?: TokenPrice | null;
     verify?: string;
+    /** The model `verify: judge:` grades with (the workspace's `judge:`). */
+    judgeModel?: string;
+    judgeEffort?: string;
     /** `output: json` — checked inside, where the reply is. */
     output?: "json";
     /** `schema:` and `max_turns:`, resolved host-side — see ExecOptions. */
     schema?: Record<string, unknown> | boolean;
     maxTurns?: number;
+    /** `capture:` resolved host-side (FOL-54 step 4) — see ExecOptions. */
+    capture?: "metadata" | "full";
     /** `limits:` resolved host-side, and the SDK-name → foldrun-name map the
      *  count reads (limits.ts) — enforced in the pod by the same hook. */
     limits?: Record<string, number>;
@@ -67,6 +73,13 @@ export interface ContainerStepInput {
     ask?: {
         timeoutSec: number;
     };
+    /** tools: [peers] — this step's agent and the other steps of its
+     *  parallel group, gathered host-side at launch. The driver rebuilds the
+     *  colleagues' tools in here over the lease's /peers door. */
+    peers?: {
+        self: string;
+        siblings: PeerInfo[];
+    };
     /** A Chat-Completions provider: the driver starts the runtime's translator
      *  on loopback and points the SDK at it. Null or absent: the env's
      *  ANTHROPIC_BASE_URL is spoken to directly. */
@@ -275,6 +288,8 @@ export declare function runtimeCacheMount(tenant: string | undefined): {
     source: string;
     target: string;
 } | null;
+/** The runner container's entrypoint, as JS text: written into the image as driver.mjs, so it must be plain JS — a TypeScript cast here broke every step on v2026.10.21.5 (tests/run-container.test.ts checks it). */
+export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
 /** The uv release copied into the image. Pinned: a floating uv is a floating
  *  resolver, and the runtime cache is keyed on the declaration, not on it. */
 export declare const UV_VERSION = "0.11.25";
@@ -374,6 +389,10 @@ export declare function parseDriverLine(line: string): {
     subagent?: string;
     check?: boolean;
     hook?: HookRecord;
+    io?: CallIo;
+    turn?: ModelCall;
+    inCall?: string;
+    responding?: true;
 } | ({
     e: "done";
 } & ContainerStepOutcome) | null;
@@ -401,6 +420,10 @@ export interface RunInContainerArgs {
      *  without it, "stop" could only mean "stop after this step", and a
      *  browser step has fifteen minutes left to spend. */
     runId?: string;
+    /** Whether a person has stopped the run, read from the record. A step that
+     *  waits for room before its sandbox exists asks this, since there is no
+     *  sandbox yet for the stop to destroy. */
+    stopRequested?: () => boolean;
     /** The reservation class — which limits this step's sandbox holds. */
     size?: "small" | "large" | "heavy";
     /** Re-attach to a sandbox a previous driver started, instead of creating

package/dist/src/run-container.js

@@ -23,7 +23,7 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { isPlatformPath } from "./store.js";
+import { CAPTURE_CAP, isPlatformPath } from "./store.js";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.js";
 import { isFileValue, fileContent } from "./secrets.js";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
@@ -410,7 +410,8 @@ export function runtimeCacheMount(tenant) {
     return { source, target: RUNTIME_CACHE };
 }
 // ---------- the runner image ----------
-const DRIVER = `// The runner container's entrypoint. Reads one step, executes it with the
+/** The runner container's entrypoint, as JS text: written into the image as driver.mjs, so it must be plain JS — a TypeScript cast here broke every step on v2026.10.21.5 (tests/run-container.test.ts checks it). */
+export const DRIVER = `// The runner container's entrypoint. Reads one step, executes it with the
 // same core the server uses, speaks JSONL on stdout, exits.
 import fs from "node:fs";
 const input = JSON.parse(fs.readFileSync("/opt/runner/job/input.json", "utf8"));
@@ -475,7 +476,7 @@ try {
   const { buildScriptTools } = await import("@foldrun/core/script-tools");
   const { buildConsultTools } = await import("@foldrun/core/agent-tools");
   const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import("@foldrun/core/context-tools");
-  const { httpChannel, buildAskTool, inboxReader } = await import("@foldrun/core/operator");
+  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import("@foldrun/core/operator");
   const { startTranslator } = await import("@foldrun/core/translator");
   const { prepareRuntime } = await import("@foldrun/core/runtime");
   const { materializeFileSecrets } = await import("@foldrun/core/secret-files");
@@ -539,11 +540,18 @@ try {
   // 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);
+  // A declared secret named like a model variable crosses as
+  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own
+  // settings, and the agent's API and script tools and verify: get the value
+  // back under the name it declared. Built here, after the runtime and any
+  // mid-step install have added their paths to env.
+  const toolEnv = { ...env };
+  for (const [k, v] of Object.entries(env)) if (k.startsWith("FOLDRUN_DECLARED_")) toolEnv[k.slice("FOLDRUN_DECLARED_".length)] = v;
+  const api = buildApiTools("", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);
   const script = buildScriptTools(
     agentDir,
     input.scripts,
-    { ...env, ...runtime.env },
+    toolEnv,
     "/library/scripts",
     runtime.interpreters,
     null,
@@ -566,6 +574,7 @@ try {
   // ask_person when tools: [ask], and the run's inbox after every tool call.
   const channel = httpChannel(env.FOLDRUN_EGRESS);
   const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };
+  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };
   const inbox = channel ? inboxReader(channel, emit) : undefined;
 
   mark("tools");
@@ -587,6 +596,7 @@ try {
       ...(history.server ? { foldrun_history: history.server } : {}),
       ...(desks.server ? { foldrun_desks: desks.server } : {}),
       ...(ask.server ? { foldrun_ask: ask.server } : {}),
+      ...(peers.server ? { foldrun_peers: peers.server } : {}),
       ...(install.server ? { foldrun_install: install.server } : {}),
       ...input.mcpServers,
     },
@@ -598,10 +608,13 @@ try {
     budgetNote: input.budgetNote,
     price: input.price,
     verify: input.verify,
-    verifyEnv: env,
+    verifyEnv: toolEnv,
+    ...(typeof input.judgeModel === "string" ? { judgeModel: input.judgeModel } : {}),
+    ...(typeof input.judgeEffort === "string" ? { judgeEffort: input.judgeEffort } : {}),
     output: input.output,
     schema: input.schema,
     maxTurns: input.maxTurns,
+    ...(input.capture === "metadata" || input.capture === "full" ? { capture: input.capture } : {}),
     ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),
     ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),
     // Slim browsing: the platform put this step on the slim image to browse
@@ -1040,6 +1053,44 @@ export function buildFailureSummary(log, opts = {}) {
     return `${head}\n--- the last ${tail} characters of the build log ---\n${log.slice(-tail)}`;
 }
 // ---------- running one step ----------
+const num = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
+/** A tool call's content from the sandbox, as far as it is well-formed and
+ *  within the cap; anything else is dropped (FOL-54 step 4). */
+function callIoOf(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    // The cap plus the slack the runner masks inside before it cuts.
+    const text = (x) => (typeof x === "string" ? x.slice(0, CAPTURE_CAP + 4096) : undefined);
+    const io = {
+        ...(text(o.input) !== undefined ? { input: text(o.input) } : {}),
+        ...(text(o.output) !== undefined ? { output: text(o.output) } : {}),
+        ...(typeof o.inputChars === "number" ? { inputChars: num(o.inputChars) } : {}),
+        ...(typeof o.outputChars === "number" ? { outputChars: num(o.outputChars) } : {}),
+        ...(o.truncated === true ? { truncated: true } : {}),
+    };
+    return io.input !== undefined || io.output !== undefined ? io : null;
+}
+/** One model call from the sandbox, well-formed or dropped. */
+function modelCallOf(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const t = (o.tokens ?? {});
+    if (typeof o.id !== "string" || !o.id || o.id.length > 128 || typeof o.at !== "string" || Number.isNaN(Date.parse(o.at)))
+        return null;
+    return {
+        id: o.id,
+        n: Math.max(1, Math.floor(num(o.n))),
+        at: o.at,
+        ms: num(o.ms),
+        ...(typeof o.model === "string" ? { model: o.model.slice(0, 128) } : {}),
+        ...(typeof o.stop === "string" ? { stop: o.stop.slice(0, 64) } : {}),
+        tokens: { input: num(t.input), output: num(t.output), cacheRead: num(t.cacheRead), cacheWrite: num(t.cacheWrite) },
+        tools: Math.floor(num(o.tools)),
+        ...(typeof o.subagent === "string" && /^[a-z0-9-]{1,64}$/.test(o.subagent) ? { subagent: o.subagent } : {}),
+    };
+}
 export function parseDriverLine(line) {
     const trimmed = line.trim();
     if (!trimmed.startsWith("{"))
@@ -1059,6 +1110,10 @@ export function parseDriverLine(line) {
                 ...(typeof parsed.subagent === "string" && /^[a-z0-9-]{1,64}$/.test(parsed.subagent) ? { subagent: parsed.subagent } : {}),
                 ...(parsed.check === true ? { check: true } : {}),
                 ...(isHookRecord(parsed.hook) ? { hook: parsed.hook } : {}),
+                ...(callIoOf(parsed.io) ? { io: callIoOf(parsed.io) } : {}),
+                ...(typeof parsed.inCall === "string" && parsed.inCall.length <= 128 ? { inCall: parsed.inCall } : {}),
+                ...(modelCallOf(parsed.turn) ? { turn: modelCallOf(parsed.turn) } : {}),
+                ...(parsed.responding === true ? { responding: true } : {}),
             };
         }
         if (parsed.e === "done") {