@foldrun/core 2.3.0 → 2.5.0

package/dist/src/store.d.ts

@@ -282,6 +282,12 @@ export interface ApiSpec {
 export interface AgentInfo {
     name: string;
     description: string;
+    /** `owner:` — the person accountable for this agent: its own, else the
+     *  workspace AGENTS.md's, else the account's. Null when none of the three
+     *  names one. */
+    owner: string | null;
+    /** Which of the three `owner` came from. */
+    ownerFrom: OwnerSource | null;
     model: string;
     /** The other half of model selection. listAgents has always returned it;
      *  the interface did not say so, so every consumer had to re-read the file
@@ -352,6 +358,10 @@ export interface AgentInfo {
     /** Tools this agent declares inline rather than in `tools:` — `apis:`,
      *  `scripts:` and `mcpServers:` names — which a limit may also name. */
     inlineTools: string[];
+    /** agent.md's frontmatter does not parse (bad YAML): the agent is listed
+     *  with defaults and this says why, rather than the listing throwing —
+     *  one broken file once took down every account's worker (20 Oct 2026). */
+    frontmatterError?: string;
 }
 export declare const MODEL_TIERS: Record<string, string>;
 export type Tier = keyof typeof MODEL_TIERS;
@@ -512,6 +522,9 @@ export interface FlowInfo {
      *  overlap) — a default that changed underfoot would surprise every flow
      *  that legitimately runs in parallel. */
     overlap: "skip" | "queue" | null;
+    /** `issues: auto-close`: a run that goes fine closes this flow's open
+     *  issues (FOL-72 step 7). Unset is `stay-open`: a person resolves them. */
+    issues?: "auto-close" | "stay-open";
     /** Where this flow's runs stand in the queue against everyone else's:
      *  "high" is claimed before the round-robin, "low" after it. Adds to the
      *  account's own priority; the account's cap still bounds how many run
@@ -606,6 +619,12 @@ export interface FlowInfo {
      *  and the trace. Read here so a documented, scaffolded field means
      *  something rather than sitting in every file unread. */
     description: string | null;
+    /** `owner:` — the person accountable for this flow: its own, else the
+     *  workspace AGENTS.md's, else the account's. parseFlow sees only the
+     *  file, so it fills the flow's own; listFlows and readFlow add the rest. */
+    owner: string | null;
+    /** Which of the three `owner` came from. */
+    ownerFrom: OwnerSource | null;
     /** Flow-level frontmatter values the parser could not read — a bad
      *  `overlap:`/`priority:`/`catchup:`/`on:`/`signature:`, or a step line
      *  whose `[[target]]` is malformed. Errors, the way a bad step option is,
@@ -621,6 +640,9 @@ export interface AgentAssets {
 }
 export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
 export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
+/** The first line of a YAML parse error, with where it is: what a person
+ *  needs to fix the file, without the parser's excerpt. */
+export declare function frontmatterErrorText(err: unknown): string;
 /** The option keys a step actually has. An indented `word: rest` that is
  *  NOT one of these is a line of the instruction — "Warning: do not
  *  publish" is prose that happens to contain a colon, and it used to be
@@ -748,6 +770,14 @@ export declare const reorderFlowSteps: (raw: string, groups: number[][]) => stri
 export declare const addFlowStep: (raw: string, step: Parameters<typeof addFlowStepLF>[1]) => string;
 export declare const removeFlowStep: (raw: string, index: number) => string;
 export declare function listFlows(tenant: string, workspace: string): FlowInfo[];
+export type OwnerSource = "agent" | "flow" | "workspace" | "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 declare function resolveOwner(own: unknown, workspace?: unknown, account?: unknown, ownKind?: "agent" | "flow"): {
+    owner: string | null;
+    ownerFrom: OwnerSource | 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
  *  runner's budget stamp — do not each re-implement the directory walk. */
@@ -922,6 +952,62 @@ export interface RunEvent {
         reason?: string;
         ms: number;
     };
+    /** Set on a tool event whose content was recorded (FOL-54 step 4): the
+     *  call's input, on the call; its output, on the completion. The content is
+     *  under runs/<run>/calls/<call>.json, secrets masked — readCapturedCall.
+     *  Absent when the workspace says `capture: metadata`, and before 19 Oct
+     *  2026. */
+    captured?: boolean;
+    /** On a tool call: the id of the model call that asked for it (a
+     *  ModelCall's `id`), so the trace can nest it. Since 19 Oct 2026. */
+    inCall?: string;
+}
+/** One model call in a step (FOL-54 step 4): what the model was sent back
+ *  for and what came of it. A step's turns, one by one, where the step
+ *  record had only their sum. */
+export interface ModelCall {
+    /** The provider's message id. */
+    id: string;
+    /** 1, 2, 3 … in the order they came back. */
+    n: number;
+    /** When the response arrived. */
+    at: string;
+    /** From the request going out (the step's start, or the last tool result
+     *  coming back) to the response arriving. */
+    ms: number;
+    model?: string;
+    /** Why the model stopped: end_turn, tool_use, max_tokens, … */
+    stop?: string;
+    /** All input (fresh + cache), as the step's own `tokens` counts it. */
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    /** How many tools it called in this turn. */
+    tools: number;
+    /** Set when a sub-agent (`subagents:`) made the call. */
+    subagent?: string;
+    /** Which attempt of the step made it, from the second on. */
+    attempt?: number;
+}
+/** The most of one tool input or output a run records (FOL-54 step 4). */
+export declare const CAPTURE_CAP: number;
+/** What a recorded tool call took and gave, secrets masked, each part capped. */
+export interface CapturedCall {
+    id: string;
+    tool: string;
+    input?: string;
+    output?: string;
+    /** The whole input's / output's length in characters, before masking and
+     *  the cap; `truncated` says whether the text was cut. */
+    inputChars?: number;
+    outputChars?: number;
+    /** Either part cut; and which. */
+    truncated?: boolean;
+    inputCut?: boolean;
+    outputCut?: boolean;
 }
 /** A question an agent asked a person while its step ran (tools: [ask]). */
 export interface StepQuestion {
@@ -935,12 +1021,18 @@ export interface StepQuestion {
     /** true when the wait ran out with no answer. */
     unanswered?: boolean;
 }
-/** A message a person sent into a running step, and when the agent got it. */
+/** A message a person sent into a running step, and when the agent got it —
+ *  or, with `from`, one a colleague in the same parallel group sent it
+ *  (tools: [peers]); with `to`, one this step sent its colleagues. */
 export interface StepMessage {
     text: string;
     by?: string | null;
     at: string;
     deliveredAt: string;
+    /** The sibling agent that sent it (`by` is `peer:<agent>` then). */
+    from?: string;
+    /** The sibling agents this step sent it to. */
+    to?: string[];
 }
 /** One attempt of a step — see StepRecord.tries. */
 export interface StepAttempt {
@@ -975,8 +1067,8 @@ export interface StepAttempt {
  *  attempt reported the figure — an in-process step rents no sandbox, and
  *  billing reads null as zero, not as "unknown, charge something". */
 export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
-export { type TokenUsage, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.ts";
-import { type TokenUsage } from "./tokens.ts";
+export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
+import { type TokenUsage, type PromptLayerRecord } from "./tokens.ts";
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1060,6 +1152,9 @@ export interface StepRecord {
      *  records from before this existed; readers fall back to the events. */
     startedAt?: string;
     finishedAt?: string;
+    /** Every model call the step made, in order (FOL-54 step 4). Absent before
+     *  19 Oct 2026. */
+    calls?: ModelCall[];
     /** Why a step was skipped, shown in the trace. */
     skipReason?: string;
     /** Evaluator loop, carried from the flow — see FlowStep. `loopRemaining`
@@ -1170,6 +1265,11 @@ export interface StepRecord {
      *  what says where a step's input tokens went. Absent before 18 Oct 2026. */
     turns?: number | null;
     systemPromptChars?: number;
+    /** The system prompt's layers — name, length and hash of each, stable
+     *  ones first, the ones that change between runs marked. Two steps of
+     *  one agent compared layer by layer say why the model's cache missed
+     *  (prompt-layers.ts). Absent before 20 Oct 2026. */
+    promptLayers?: PromptLayerRecord[];
     /** Why the model's last turn ended (end_turn, max_tokens, tool_use…), as
      *  the SDK's closing result says. */
     stopReason?: string | null;
@@ -1237,6 +1337,21 @@ export interface RunRecord {
      *  the agents decided was worth remembering, listed so a person can review
      *  the lesson without diffing the folder. */
     memoryWrites?: string[];
+    /** The workspace's deployed commit when the run was created — which
+     *  version of the files it ran (FOL-54 step 4). Absent for a workspace
+     *  never deployed, and before 19 Oct 2026. */
+    revision?: string | null;
+    /** When a worker first picked the run up: startedAt is when it was
+     *  created, so the gap is its time in the queue. */
+    drivenAt?: string | null;
+    /** A re-run's source (FOL-72 step 6): which run, the 1-based step it
+     *  started from, and the instruction it was given there when a person
+     *  edited it for this re-run alone. */
+    rerunOf?: {
+        run: string;
+        step: number;
+        instruction?: string;
+    };
     /** Who asked for this run, when a person did: their email address. A
      *  schedule, a webhook and a chained flow have no one, and leave it unset.
      *  Kept so a gate can refuse the one approval nobody should be able to
@@ -1259,6 +1374,11 @@ export interface RunRecord {
     approvalLinksUsed?: string[];
     steps: StepRecord[];
 }
+/** Merge one part (the input, on the call; the output, on its completion)
+ *  into the call's file. */
+export declare function writeCapturedCall(workspaceRoot: string, runId: string, part: CapturedCall): void;
+/** One recorded call of a run, or null (not recorded, or not a call). */
+export declare function readCapturedCall(tenant: string, workspace: string, runId: string, callId: string): CapturedCall | null;
 export declare function runFilePath(tenant: string, workspace: string, runId: string): string;
 /**
  * Erase a run from history: its record and the outputs archived under its
@@ -1346,6 +1466,11 @@ export interface RunSummaryStep {
     instruction?: string;
     /** When a parked step last spoke — the moment the banner sorts by. */
     waitingSince?: string;
+    /** For search (FOL-72 step 9): the tools it called, how many of its calls
+     *  errored, and its model. Absent on rows written before 19 Oct 2026. */
+    tools?: string[];
+    toolErrors?: number;
+    model?: string;
     startedAt?: string;
     finishedAt?: string;
 }
@@ -1363,6 +1488,8 @@ export interface RunSummary {
     tags?: string[];
     startedBy?: string | null;
     parkedAt?: string | null;
+    /** The revision it ran (RunRecord.revision), for issues' "since". */
+    revision?: string | null;
     /** A step is parked for a person — what the approvals banner counts. */
     awaitingApproval: boolean;
     steps: RunSummaryStep[];

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 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
@@ -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 } = matter(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,22 @@ 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 } : {}),
         };
     });
 }
+/** The first line of a YAML parse error, with where it is: what a person
+ *  needs to fix the file, without the parser's excerpt. */
+export function frontmatterErrorText(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `frontmatter does not parse — ${msg.split("\n")[0].trim()}. Quote a value that contains a colon followed by a space.`;
+}
+/** 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 +1352,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 } = matter(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 +1614,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 +1629,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 +1665,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 +1976,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 +2019,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 +2639,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 +2656,53 @@ 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";
+// ---------------------------------------------------------------- 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 +2881,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 +2900,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[];