@foldrun/core 2.4.0 → 2.6.0

package/dist/src/store.js

@@ -27,7 +27,8 @@ import { recordRevision, registerTreeReader } from "./history.js";
 import { dataRoot, singleWorkspace, singleAccountRoot, entriesNoFollow } from "./paths.js";
 import { platform } from "./platform.js";
 import { toLF, asRaw } from "./eol.js";
-import matter from "gray-matter";
+import matter, { frontmatterErrorText, configMatter } from "./matter.js";
+import { readAgentsMdKeys } from "./agents-md.js";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
  * for the CLI: `foldrun probe` used to import gray-matter itself, which is
@@ -38,7 +39,7 @@ import matter from "gray-matter";
  * the runtime, and there is nothing to fail to import.
  */
 export function readFrontmatter(file) {
-    return matter(fs.readFileSync(file, "utf8")).data;
+    return configMatter(fs.readFileSync(file, "utf8")).data;
 }
 import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.js";
 import { refNames } from "./refs.js";
@@ -1118,7 +1119,18 @@ export function listAgents(tenant, workspace) {
         .filter((n) => fs.existsSync(path.join(dir, n, "agent.md")))
         .sort()
         .map((name) => {
-        const { data } = matter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8"));
+        // One agent whose YAML does not parse is that agent's problem, not
+        // the account's: listed with defaults and the reason, never thrown
+        // out of a listing every page, the scheduler and the worker's boot
+        // read.
+        let data = {};
+        let frontmatterError;
+        try {
+            ({ data } = configMatter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8")));
+        }
+        catch (err) {
+            frontmatterError = frontmatterErrorText(err);
+        }
         const tools = refNames(data.tools);
         const actions = webConfig(data, { ...accountFront, ...workspaceFront }).actions;
         const readsWeb = tools.includes("web") && (!actions || actions.some((a) => a === "fetch" || a === "browse"));
@@ -1141,6 +1153,7 @@ export function listAgents(tenant, workspace) {
             network,
             name,
             description: data.description ?? "",
+            ...resolveOwner(data.owner, workspaceFront.owner, accountFront.owner),
             model: data.model ?? "default",
             effort: data.effort ?? null,
             tools,
@@ -1164,9 +1177,19 @@ export function listAgents(tenant, workspace) {
             ...(() => { const l = readLimits(data.limits); return { limits: l.limits, limitProblems: l.problems }; })(),
             networkProblems: networkProblems(data.network),
             inlineTools: inlineToolNames(data),
+            ...(frontmatterError ? { frontmatterError } : {}),
         };
     });
 }
+// Kept here for callers that import it from the store; it lives in matter.ts
+// so the scanner can use it without the store.
+export { frontmatterErrorText };
+/** The body of a file whose frontmatter would not parse: what follows the
+ *  closing fence, so a flow's steps can still be read and shown. */
+function bodyAfterFrontmatter(raw) {
+    const m = raw.match(/^---\n[\s\S]*?\n---[ \t]*(?:\n|$)/);
+    return m ? raw.slice(m[0].length) : raw;
+}
 // A step targets an agent — `[[writer]]` — or another flow — `[[flow:digest]]`,
 // which is how one flow triggers another.
 // `(\S.*|)` rather than `(.*)`: the instruction either starts with a
@@ -1326,11 +1349,26 @@ export function parseFlow(file, raw) {
     // every line kept its "\r", which STEP_RE's `.` will not match. Read it as
     // LF; the line count, and so every step's `line`, is the same.
     raw = raw.replace(/\r\n/g, "\n");
-    const { data, content } = matter(raw);
+    // Frontmatter that does not parse is a flow-level problem (an error in
+    // check), not a throw: listFlows feeds every workspace listing, the
+    // scheduler and the worker's boot. With no frontmatter read the flow is
+    // manual, so a broken schedule never fires.
+    let data = {};
+    let content;
+    let frontError = null;
+    try {
+        ({ data, content } = configMatter(raw));
+    }
+    catch (err) {
+        frontError = frontmatterErrorText(err);
+        content = bodyAfterFrontmatter(raw);
+    }
     const steps = [];
     // Flow-level problems: a malformed step target (below) and unreadable
     // frontmatter enums (before the return). Reported as errors by flow-lint.
     const frontProblems = [];
+    if (frontError)
+        frontProblems.push(frontError);
     // Frontmatter is stripped by matter(), so add it back to keep line numbers
     // pointing at the real file rather than the body.
     const offset = raw.slice(0, raw.length - content.length).split("\n").length - 1;
@@ -1573,6 +1611,7 @@ export function parseFlow(file, raw) {
         }
     };
     badEnum("overlap", data.overlap, ["skip", "queue"]);
+    badEnum("issues", data.issues, ["stay-open", "auto-close"]);
     badEnum("priority", data.priority, ["high", "normal", "low"]);
     badEnum("catchup", data.catchup, ["none", "last"]);
     badEnum("on", data.on, ["completed", "failed", "blocked", "any"]);
@@ -1587,6 +1626,7 @@ export function parseFlow(file, raw) {
         model: data.model ?? null,
         effort: data.effort ?? null,
         overlap: data.overlap === "skip" || data.overlap === "queue" ? data.overlap : null,
+        ...(data.issues === "auto-close" || data.issues === "stay-open" ? { issues: data.issues } : {}),
         live: data.live === true,
         priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : null,
         budget: runBudget(data.budget),
@@ -1622,6 +1662,7 @@ export function parseFlow(file, raw) {
         approvers: approverList(data.approvers),
         approveWithin: durationOf(data.approve_within),
         description: typeof data.description === "string" ? data.description.trim() || null : null,
+        ...resolveOwner(data.owner, undefined, undefined, "flow"),
         frontProblems,
         steps,
     };
@@ -1932,11 +1973,38 @@ export function listFlows(tenant, workspace) {
     const dir = path.join(workspaceDir(tenant, workspace), "flows");
     if (!fs.existsSync(dir))
         return [];
+    const owned = flowOwner(tenant, workspace);
     return fs
         .readdirSync(dir)
         .filter((f) => f.endsWith(".md"))
         .sort()
-        .map((f) => parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8")));
+        .map((f) => owned(parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8"))));
+}
+/** A flow with its owner filled from the workspace and account when its own
+ *  file names none. */
+function flowOwner(tenant, workspace) {
+    let above = null;
+    return (flow) => {
+        if (flow.owner)
+            return flow;
+        above ??= {
+            workspace: readAgentsMdKeys(workspaceDir(tenant, workspace)).owner,
+            account: readAgentsMdKeys(accountDir(tenant)).owner,
+        };
+        return { ...flow, ...resolveOwner(undefined, above.workspace, above.account) };
+    };
+}
+/** `owner:` down the cascade: the file's own, the workspace AGENTS.md's, the
+ *  account's. A blank or non-string value is no value. `own` is labelled
+ *  "agent" or "flow" by the caller's kind; here it is whichever is given. */
+export function resolveOwner(own, workspace, account, ownKind = "agent") {
+    const text = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
+    for (const [v, from] of [[own, ownKind], [workspace, "workspace"], [account, "account"]]) {
+        const t = text(v);
+        if (t)
+            return { owner: t, ownerFrom: from };
+    }
+    return { owner: null, ownerFrom: null };
 }
 /** One flow of a workspace by name, or null. The same read listFlows makes,
  *  named so callers that want a single flow — the approval rules, the
@@ -1948,7 +2016,7 @@ export function readFlow(tenant, workspace, flowName) {
     for (const f of fs.readdirSync(dir).filter((f) => f.endsWith(".md"))) {
         const flow = parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8"));
         if (flow.name === flowName)
-            return flow;
+            return flowOwner(tenant, workspace)(flow);
     }
     return null;
 }
@@ -2568,6 +2636,8 @@ export function flowPatternTemplate(pattern, name, agents) {
             return FLOW_TEMPLATE(name, a(0, "my-agent"));
     }
 }
+/** The most of one tool input or output a run records (FOL-54 step 4). */
+export const CAPTURE_CAP = 64 * 1024;
 /** 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". */
@@ -2583,8 +2653,60 @@ export function sumAttempts(tries) {
         ...(turns.length ? { turns: turns.reduce((a, b) => a + b, 0) } : {}),
     };
 }
-export { tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.js";
+export { tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.js";
 import { sumTokens } from "./tokens.js";
+/** The marker rescueStep puts in a rescue's instruction; how a rescue record
+ *  written before `rescueOf` existed is still recognised. */
+export const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
+/** Is this record an on-fail rescue rather than a step of the flow? */
+export function isRescueRecord(step) {
+    return !!step.rescueOf || (step.instruction ?? "").includes(RESCUE_MARKER);
+}
+// ---------------------------------------------------------------- captured calls
+//
+// What each tool call took and gave (FOL-54 step 4), beside the run under
+// runs/<run>/calls/<call>.json — out of the run record, which every list
+// and every page reads whole, and gone with the run (deleteRun removes
+// runs/<run>/). The runner writes them, secrets already masked.
+const SAFE_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+function capturedCallFile(workspaceRoot, runId, callId) {
+    if (!SAFE_ID.test(runId) || !SAFE_ID.test(callId) || callId.startsWith(".") || runId.startsWith("."))
+        return null;
+    return path.join(workspaceRoot, "runs", runId, "calls", `${callId}.json`);
+}
+/** Merge one part (the input, on the call; the output, on its completion)
+ *  into the call's file. */
+export function writeCapturedCall(workspaceRoot, runId, part) {
+    const file = capturedCallFile(workspaceRoot, runId, part.id);
+    if (!file)
+        return;
+    let prev = {};
+    try {
+        prev = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        /* the first part */
+    }
+    const next = { ...prev, ...part, truncated: Boolean(prev.truncated || part.truncated) || undefined };
+    if (!next.truncated)
+        delete next.truncated;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next));
+    fs.renameSync(tmp, file);
+}
+/** One recorded call of a run, or null (not recorded, or not a call). */
+export function readCapturedCall(tenant, workspace, runId, callId) {
+    const file = capturedCallFile(workspaceDir(tenant, workspace), runId, callId);
+    if (!file)
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
 export function runFilePath(tenant, workspace, runId) {
     assertSafeName(runId, "run id");
     return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);
@@ -2763,6 +2885,7 @@ export function summarizeRun(run) {
         ...(run.tags?.length ? { tags: run.tags } : {}),
         ...(run.startedBy ? { startedBy: run.startedBy } : {}),
         ...(run.parkedAt ? { parkedAt: run.parkedAt } : {}),
+        ...(run.revision ? { revision: run.revision } : {}),
         awaitingApproval: run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event"),
         steps: run.steps.map((s) => {
             const error = s.status === "failed" ? s.events.filter((e) => e.type === "error").at(-1)?.text : undefined;
@@ -2781,10 +2904,30 @@ export function summarizeRun(run) {
                 ...(s.status === "awaiting-approval" ? { instruction: s.instruction, waitingSince: s.events.at(-1)?.t ?? run.startedAt } : {}),
                 ...(s.startedAt ? { startedAt: s.startedAt } : {}),
                 ...(s.finishedAt ? { finishedAt: s.finishedAt } : {}),
+                ...searchFacts(s),
             };
         }),
     };
 }
+/** What a step's row carries for search: the tools it called (once each),
+ *  how many tool calls errored, and its model. */
+function searchFacts(s) {
+    const tools = new Set();
+    let errors = 0;
+    for (const e of s.events) {
+        if (e.type !== "tool")
+            continue;
+        if (e.ms == null)
+            tools.add(e.text);
+        else if (e.err)
+            errors++;
+    }
+    return {
+        ...(tools.size ? { tools: [...tools].slice(0, 40) } : {}),
+        ...(errors ? { toolErrors: errors } : {}),
+        ...(s.model ? { model: s.model } : {}),
+    };
+}
 /** A RunRecord with the shape a list reads and nothing else — see listAllRuns. */
 export function runFromSummary(s) {
     const { awaitingApproval: _awaiting, ...run } = s;

package/dist/src/tokens.d.ts

@@ -36,3 +36,41 @@ export declare function runTokens(run: {
         tokens?: TokenUsage | null;
     }[];
 }): TokenUsage | null;
+/**
+ * One layer of a step's system prompt as the record keeps it — no text,
+ * only what tells two steps' prompts apart. The layers are assembled in
+ * prompt-layers.ts; this is the shape the run page and the CLI read.
+ */
+export interface PromptLayerRecord {
+    name: string;
+    chars: number;
+    /** First 12 hex characters of the layer's SHA-256. */
+    hash: string;
+    /** False for a layer that changes between runs (memory, state, clock),
+     *  placed after the cache boundary. Omitted when true. */
+    stable?: false;
+}
+/**
+ * Which layers differ between two steps' prompts, by name: changed, added
+ * or removed. Empty when the prompts are the same, or either step has no
+ * layers on record.
+ */
+export declare function promptLayersChanged(prev: readonly PromptLayerRecord[] | null | undefined, next: readonly PromptLayerRecord[] | null | undefined): string[];
+/** A step that wrote this share of its input to the cache, or more, gets a
+ *  note saying why. Below it the cache did its job: a step's turns each
+ *  write their new tail, which is a few percent of a long step's input. */
+export declare const CACHE_WRITE_NOTE_SHARE = 0.2;
+/**
+ * Why a step's prompt cache missed, in one line, or null when it did not:
+ * the share of input written to the cache, and what differed from the same
+ * agent's previous step in the run — "memory, clock changed since step 2".
+ * The agent's first step in a run writes its prefix whatever happens, and
+ * says so; the same prompt written again means the entry had expired
+ * (five minutes on an API key) or siblings started before it was readable.
+ * Steps without layers on record (before 20 Oct 2026) get no note.
+ */
+export declare function promptCacheNote(steps: readonly {
+    agent: string;
+    tokens?: TokenUsage | null;
+    promptLayers?: readonly PromptLayerRecord[] | null;
+}[], index: number): string | null;

package/dist/src/tokens.js

@@ -56,3 +56,60 @@ export function runTokens(run) {
     const toks = run.steps.map((s) => s.tokens).filter((t) => !!t);
     return toks.length ? sumTokens(toks) : null;
 }
+/**
+ * Which layers differ between two steps' prompts, by name: changed, added
+ * or removed. Empty when the prompts are the same, or either step has no
+ * layers on record.
+ */
+export function promptLayersChanged(prev, next) {
+    if (!prev || !next)
+        return [];
+    const before = new Map(prev.map((l) => [l.name, l.hash]));
+    const after = new Map(next.map((l) => [l.name, l.hash]));
+    const out = [];
+    for (const [name, hash] of after)
+        if (before.get(name) !== hash)
+            out.push(name);
+    for (const name of before.keys())
+        if (!after.has(name))
+            out.push(name);
+    return out;
+}
+/** A step that wrote this share of its input to the cache, or more, gets a
+ *  note saying why. Below it the cache did its job: a step's turns each
+ *  write their new tail, which is a few percent of a long step's input. */
+export const CACHE_WRITE_NOTE_SHARE = 0.2;
+/**
+ * Why a step's prompt cache missed, in one line, or null when it did not:
+ * the share of input written to the cache, and what differed from the same
+ * agent's previous step in the run — "memory, clock changed since step 2".
+ * The agent's first step in a run writes its prefix whatever happens, and
+ * says so; the same prompt written again means the entry had expired
+ * (five minutes on an API key) or siblings started before it was readable.
+ * Steps without layers on record (before 20 Oct 2026) get no note.
+ */
+export function promptCacheNote(steps, index) {
+    const step = steps[index];
+    if (!step?.promptLayers)
+        return null;
+    const t = step.tokens;
+    if (!t || t.cacheWrite === undefined || !(t.input > 0))
+        return null;
+    const share = t.cacheWrite / t.input;
+    if (share < CACHE_WRITE_NOTE_SHARE)
+        return null;
+    const head = `${Math.round(share * 100)}% of input written to the cache`;
+    let prev = -1;
+    for (let j = index - 1; j >= 0; j--) {
+        if (steps[j].agent === step.agent && steps[j].promptLayers) {
+            prev = j;
+            break;
+        }
+    }
+    if (prev < 0)
+        return `${head} — the agent's first step in this run`;
+    const changed = promptLayersChanged(steps[prev].promptLayers, step.promptLayers);
+    if (!changed.length)
+        return `${head} — the same prompt as step ${prev + 1}; the entry had expired or was still being written`;
+    return `${head} — ${changed.join(", ")} changed since step ${prev + 1}`;
+}

package/dist/src/tool-names.js

@@ -47,7 +47,7 @@ export const BUILTIN_TOOLS = new Set([
 /** The platform's own groups, served in-process rather than by the SDK.
  *  `install` is granted to every agent anyway (install-tool.ts); naming it is
  *  accepted so a file that says so is not flagged. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask", "install"]);
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask", "peers", "install"]);
 /** Would this name resolve to something the runtime provides? Built-ins win a
  *  clash, so a tool file of the same name is shadowed rather than granted. */
 export function isRuntimeTool(name) {

package/dist/src/tool-programs.js

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { builtinModules } from "node:module";
-import matter from "gray-matter";
+import matter from "./matter.js";
 import { parseRuntime } from "./runtime.js";
 import { workspaceDir, workspaceTools } from "./store.js";
 import { libraryDir, libraryTools } from "./library.js";

package/dist/src/trace-tree.d.ts

@@ -0,0 +1,40 @@
+import type { RunRecord } from "./store.ts";
+export type SpanKind = "run" | "step" | "model" | "tool" | "error";
+export type SpanStatus = "ok" | "error" | "running" | "waiting" | "skipped" | "pending";
+export interface TraceSpan {
+    /** Stable within the run: "run", "s2", "s2/m3", "s2/t:<call>", "s2/e5". */
+    id: string;
+    kind: SpanKind;
+    /** What the line says: the flow, the agent, the model, the tool. */
+    label: string;
+    /** Epoch ms; null when the record does not say. */
+    start: number | null;
+    end: number | null;
+    status: SpanStatus;
+    /** Model and step spans: tokens (input is all input, as on the record). */
+    tokens?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    /** Step spans: the provider's token cost, USD. */
+    costUsd?: number | null;
+    model?: string;
+    /** Model spans: why it stopped. */
+    stop?: string;
+    /** Tool spans: the call id, and whether its input and output were recorded. */
+    call?: string;
+    captured?: boolean;
+    /** Error spans and failed tools: the words. */
+    text?: string;
+    subagent?: string;
+    /** Index into run.steps, on a step and everything under it. */
+    step?: number;
+    children: TraceSpan[];
+}
+export declare function buildTraceTree(run: RunRecord, now?: number): TraceSpan;
+/** The ids from the root to the first thing that went wrong — what the
+ *  view opens on; [] when nothing did. A failed tool beats the step's error
+ *  line, which beats the failed step itself. */
+export declare function failurePath(root: TraceSpan): string[];

package/dist/src/trace-tree.js

@@ -0,0 +1,156 @@
+// A run as one tree (FOL-72 step 5): run → step → model call → tool call,
+// each with when it started and ended, what it cost in tokens and how it
+// ended — the waterfall every agent-tracing tool opens on. Built from the
+// run record alone (steps, step.calls, the paired tool events), so the run
+// page, GET …/runs/<id>/trace and `foldrun report --tree` read one function.
+//
+// A tool call nests under the model call that asked for it: its event names
+// the call (`inCall`) since 19 Oct 2026; older records are matched by time,
+// to the last model call that answered before the tool started. Pure: no
+// node imports, so the browser can use it.
+const ms = (iso) => {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isNaN(t) ? null : t;
+};
+function stepStatus(s) {
+    if (s.status === "completed")
+        return "ok";
+    if (s.status === "failed")
+        return "error";
+    if (s.status === "running")
+        return "running";
+    if (s.status === "awaiting-approval")
+        return "waiting";
+    if (s.status === "skipped")
+        return "skipped";
+    return "pending";
+}
+/** Tool events paired: the call's start, its duration, whether it erred. */
+function toolCalls(events) {
+    const byCall = new Map();
+    const out = [];
+    for (const e of events) {
+        if (e.type !== "tool")
+            continue;
+        if (e.call && e.ms != null && byCall.has(e.call)) {
+            const open = byCall.get(e.call);
+            open.end = (open.start ?? ms(e.t) ?? 0) + e.ms;
+            open.err ||= e.err === true;
+            open.captured ||= e.captured === true;
+            continue;
+        }
+        const c = { e, start: ms(e.t), end: null, err: e.err === true, captured: e.captured === true };
+        if (e.call)
+            byCall.set(e.call, c);
+        out.push(c);
+    }
+    return out;
+}
+function modelSpan(c, step) {
+    const at = ms(c.at);
+    return {
+        id: `s${step}/m${c.attempt && c.attempt > 1 ? `${c.attempt}.` : ""}${c.n}`,
+        kind: "model",
+        label: c.model ?? "model",
+        // The request went out `ms` before the response began arriving.
+        start: at !== null ? at - c.ms : null,
+        end: at,
+        status: "ok",
+        tokens: c.tokens,
+        ...(c.model ? { model: c.model } : {}),
+        ...(c.stop ? { stop: c.stop } : {}),
+        ...(c.subagent ? { subagent: c.subagent } : {}),
+        step,
+        children: [],
+    };
+}
+function stepSpan(s, i, now) {
+    const first = s.events[0] ? ms(s.events[0].t) : null;
+    const last = s.events.length ? ms(s.events[s.events.length - 1].t) : null;
+    const status = stepStatus(s);
+    const span = {
+        id: `s${i}`,
+        kind: "step",
+        label: s.agent,
+        start: ms(s.startedAt) ?? first,
+        end: ms(s.finishedAt) ?? (status === "running" ? now : last),
+        status,
+        ...(s.tokens ? { tokens: { input: s.tokens.input, output: s.tokens.output, cacheRead: s.tokens.cacheRead ?? 0, cacheWrite: s.tokens.cacheWrite ?? 0 } } : {}),
+        costUsd: s.costUsd ?? null,
+        ...(s.model ? { model: s.model } : {}),
+        step: i,
+        children: [],
+    };
+    const models = (s.calls ?? []).map((c) => ({ c, span: modelSpan(c, i) }));
+    const byId = new Map(models.map((m) => [m.c.id, m.span]));
+    const homeOf = (e, start) => {
+        if (e.inCall && byId.has(e.inCall))
+            return byId.get(e.inCall);
+        // Older records: the last model call (of the same agent) that answered
+        // before the tool started.
+        const same = models.filter((m) => (m.c.subagent ?? null) === (e.subagent ?? null) && m.span.end !== null && start !== null && m.span.end <= start + 50);
+        return same.length ? same[same.length - 1].span : span;
+    };
+    for (const t of toolCalls(s.events)) {
+        const home = homeOf(t.e, t.start);
+        const tool = {
+            id: `s${i}/t:${t.e.call ?? `${t.start}`}`,
+            kind: "tool",
+            label: t.e.text,
+            start: t.start,
+            end: t.end ?? (status === "running" ? now : t.start),
+            status: t.err ? "error" : t.end === null && status === "running" ? "running" : "ok",
+            ...(t.e.call ? { call: t.e.call } : {}),
+            ...(t.captured ? { captured: true } : {}),
+            ...(t.e.subagent ? { subagent: t.e.subagent } : {}),
+            step: i,
+            children: [],
+        };
+        home.children.push(tool);
+    }
+    // A model call lasts until the last tool it asked for has finished.
+    for (const m of models) {
+        const ends = m.span.children.map((c) => c.end).filter((x) => x !== null);
+        if (ends.length && m.span.end !== null)
+            m.span.end = Math.max(m.span.end, ...ends);
+    }
+    span.children.push(...models.map((m) => m.span));
+    // Errors, as leaves: why the step failed, read without opening the trace.
+    s.events.forEach((e, k) => {
+        if (e.type !== "error")
+            return;
+        span.children.push({ id: `s${i}/e${k}`, kind: "error", label: "error", start: ms(e.t), end: ms(e.t), status: "error", text: e.text, step: i, children: [] });
+    });
+    span.children.sort((a, b) => (a.start ?? Infinity) - (b.start ?? Infinity));
+    return span;
+}
+export function buildTraceTree(run, now = Date.now()) {
+    const status = run.status === "completed" ? "ok" : run.status === "failed" ? "error" : run.status === "awaiting-approval" ? "waiting" : run.status === "queued" ? "pending" : "running";
+    return {
+        id: "run",
+        kind: "run",
+        label: run.flow,
+        start: ms(run.startedAt),
+        end: ms(run.finishedAt) ?? (status === "running" || status === "waiting" ? now : null),
+        status,
+        children: run.steps.map((s, i) => stepSpan(s, i, now)),
+    };
+}
+/** The ids from the root to the first thing that went wrong — what the
+ *  view opens on; [] when nothing did. A failed tool beats the step's error
+ *  line, which beats the failed step itself. */
+export function failurePath(root) {
+    let best = null;
+    const rank = (s) => (s.kind === "tool" ? 3 : s.kind === "error" ? 2 : s.kind === "step" ? 1 : 0);
+    const walk = (s, path) => {
+        const here = [...path, s.id];
+        if (s.status === "error" && s.kind !== "run" && (!best || rank(s) > best.rank))
+            best = { path: here, rank: rank(s) };
+        for (const c of s.children)
+            walk(c, here);
+    };
+    walk(root, []);
+    return best ? best.path : [];
+}

package/dist/src/translator.d.ts

@@ -28,6 +28,11 @@ export interface TranslatorSpec {
     /** The provider block's `params:` — merged into the outgoing body after
      *  the translation, so a file can set what this format does not model. */
     params?: Record<string, unknown>;
+    /** `prompt_cache_key` for an endpoint that routes its prompt cache by
+     *  one (OpenAI, Mistral): the same key for every request that shares a
+     *  prefix — one per agent (prompt-layers.ts). Unset where the preset
+     *  does not say the parameter is understood. */
+    cacheKey?: string;
     /** How the endpoint is named in the trace. */
     label?: string;
     /** The step's egress lease, when the sandbox must not hold the key: the
@@ -77,6 +82,7 @@ export declare function toChatCompletions(req: Json, opts: {
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     reasoningEffort?: boolean;
     stream: boolean;
+    cacheKey?: string;
     /** Merged in last, so the file wins over the translation. */
     params?: Record<string, unknown>;
 }, drop?: Dropped): Json;
@@ -93,6 +99,7 @@ export declare function toChatCompletions(req: Json, opts: {
 export declare function toResponses(req: Json, opts: {
     reasoningEffort?: boolean;
     stream: boolean;
+    cacheKey?: string;
     params?: Record<string, unknown>;
 }, drop?: Dropped): Json;
 /** A finished Chat Completion as an Anthropic message. Pure. */
@@ -173,5 +180,6 @@ export declare function translatorSpecFor(spec: {
     name?: string | null;
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     reasoningEffort?: boolean;
+    cacheKey?: string;
 }): TranslatorSpec | null;
 export {};

package/dist/src/translator.js

@@ -123,6 +123,8 @@ function imagePart(block) {
  */
 export function toChatCompletions(req, opts, drop = dropped()) {
     const out = { model: req.model, stream: opts.stream };
+    if (opts.cacheKey)
+        out.prompt_cache_key = opts.cacheKey;
     const messages = [];
     const system = textOf(req.system);
     if (system)
@@ -285,6 +287,8 @@ export function toChatCompletions(req, opts, drop = dropped()) {
  */
 export function toResponses(req, opts, drop = dropped()) {
     const out = { model: req.model, stream: opts.stream, store: false };
+    if (opts.cacheKey)
+        out.prompt_cache_key = opts.cacheKey;
     const system = textOf(req.system);
     if (system)
         out.instructions = system;
@@ -904,8 +908,8 @@ export async function startTranslator(spec) {
             const drop = dropped();
             const responses = spec.wire === "responses";
             const outbound = responses
-                ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop)
-                : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop);
+                ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, cacheKey: spec.cacheKey, stream }, drop)
+                : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, cacheKey: spec.cacheKey, stream }, drop);
             for (const line of drop.lines())
                 if (!log.includes(line))
                     log.push(line);
@@ -1051,6 +1055,7 @@ export function translatorSpecFor(spec) {
         params: spec.params,
         maxTokensParam: spec.maxTokensParam,
         reasoningEffort: spec.reasoningEffort,
+        ...(spec.cacheKey ? { cacheKey: spec.cacheKey } : {}),
         label: spec.name ? `${spec.name} (${spec.baseUrl})` : spec.baseUrl,
     };
 }