@foldrun/core 2.4.0 → 2.5.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 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";

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 matter from "./matter.js";
 import { getSecret } from "./secrets.js";
 import { noteSecretUse, healthKey } from "./secret-health.js";
 import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider } from "./store.js";

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";
@@ -49,6 +50,8 @@ export interface ContainerStepInput {
     /** `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 +70,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. */
@@ -374,6 +384,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;

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";
@@ -475,7 +475,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 +539,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 +573,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 +595,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 +607,11 @@ try {
     budgetNote: input.budgetNote,
     price: input.price,
     verify: input.verify,
-    verifyEnv: env,
+    verifyEnv: toolEnv,
     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 +1050,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 +1107,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") {

package/dist/src/runner.d.ts

@@ -33,6 +33,46 @@ export declare function slotPool(size: number): {
     acquire: () => Promise<void>;
     release: () => void;
 };
+export declare function markResponding(step: StepRecord): void;
+/**
+ * Is this step's prompt in the cache yet? An entry is readable from the
+ * moment the response to the request that wrote it begins streaming
+ * (Anthropic's prompt-caching docs), which is what `responding` marks.
+ * The first text, tool call or recorded model call says the same a little
+ * later, for an executor that cannot see the stream (the stub, an older
+ * driver). Resolves on the first of those, or when the step is over
+ * without one (a refusal before the first turn, a failed start).
+ */
+export declare function untilFirstReply(step: StepRecord, done: Promise<unknown>, pollMs?: number): Promise<void>;
+/**
+ * Steps of one agent launched together share a prompt prefix — tools and
+ * system prompt — and that is what the model's cache keeps. The cache is
+ * written by the first request that carries a prefix and readable only
+ * once that response has begun, so N copies started at once all write it
+ * and none reads: a fan-out of twenty paid twenty cold prefixes. The gate
+ * lets the first instance of each agent go alone and holds its siblings
+ * until its first response has begun (or it ended); then they all start
+ * and read what it wrote — Claude Code holds a workflow's fan-out the same
+ * way. Not a fixed delay: a sandbox takes seconds to start before its
+ * first model call, so a timer from launch would release the siblings
+ * before there was anything to read. Keyed by agent and model, since a
+ * cache is per model.
+ */
+export declare function warmGate(launching: StepRecord[], pollMs?: number): {
+    /** Claim the step's place — synchronously, before anything awaits, or
+     *  the copies that reach their first await together would all find no
+     *  lead and all go (a `parallel:` pool's acquire was exactly that).
+     *  The first of its agent leads and gets null; a later one gets the
+     *  lead's gate to await before it starts; a lone step gets null too. */
+    claim(step: StepRecord): Promise<void> | null;
+    /** A lead that will not run after all (the run was stopped while it
+     *  waited for a pool slot) still opens its gate — or its siblings,
+     *  which also wake to the stop, would wait on it forever. */
+    release(step: StepRecord): void;
+    /** Run the step; a lead opens its agent's gate on its first reply (or
+     *  its end), whatever else happens to it. */
+    run(step: StepRecord, launch: () => Promise<void>): Promise<void>;
+};
 export interface DiscoveredSkill {
     name: string;
     description: string;
@@ -258,6 +298,8 @@ grantsOnly?: boolean): {
      *  reported by the step, not here, so it lands in the run's trace. */
     clock: ClockChoice;
     systemPrompt: string;
+    /** What the record keeps of each layer of that prompt. */
+    promptLayers: import("./tokens.ts").PromptLayerRecord[];
     allowed: string[];
     disabled: string[];
     unknownTools: string[];
@@ -280,6 +322,7 @@ grantsOnly?: boolean): {
     ask: {
         timeoutSec: number;
     } | null;
+    peers: boolean;
     runtime: {
         log: string[];
         error: string | null;
@@ -328,6 +371,7 @@ grantsOnly?: boolean): {
         maxTokensParam?: "max_tokens" | "max_completion_tokens";
         reasoningEffort?: boolean;
         params?: Record<string, unknown>;
+        cacheKey?: string;
         label?: string;
         egress?: string;
         timezone: string;
@@ -340,6 +384,7 @@ grantsOnly?: boolean): {
         maxTokensParam?: "max_tokens" | "max_completion_tokens";
         reasoningEffort?: boolean;
         params?: Record<string, unknown>;
+        cacheKey?: string;
         label?: string;
         egress?: string;
         timezone: string;
@@ -583,7 +628,13 @@ export interface Reconciliation {
  * outlives any process. A run whose person already answered is not waiting,
  * and is picked back up — see below.
  */
-export declare function reconcileRuns(tenant: string, now?: number, live?: ReadonlySet<string>): Reconciliation[];
+/** Told when a run reconcile closed, or resumed and saw to its end — so the
+ *  platform settles, notifies and chains it as it would a run its worker
+ *  drove (a run closed here had spent tokens, and nobody was charged or
+ *  told). Not told when a resumed run parks again: whatever resumes it next
+ *  goes through the worker. */
+export type ReconcileEnd = (tenant: string, workspace: string, runId: string) => void | Promise<void>;
+export declare function reconcileRuns(tenant: string, now?: number, live?: ReadonlySet<string>, onEnd?: ReconcileEnd): Reconciliation[];
 /**
  * The same, for every account this installation holds.
  *
@@ -591,7 +642,7 @@ export declare function reconcileRuns(tenant: string, now?: number, live?: Reado
  * one hard-coded account left every other account's interrupted runs marked
  * `running` forever, with no process left to finish them.
  */
-export declare function reconcileAllRuns(now?: number, live?: ReadonlySet<string>): Reconciliation[];
+export declare function reconcileAllRuns(now?: number, live?: ReadonlySet<string>, onEnd?: ReconcileEnd): Reconciliation[];
 /**
  * Wait for a run to stop being in progress.
  *