@foldrun/core 2.4.0 → 2.6.0

package/src/store.ts

@@ -31,7 +31,8 @@ import { platform } from "./platform.ts";
 import { toLF, asRaw } from "./eol.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
-import matter from "gray-matter";
+import matter, { frontmatterErrorText, configMatter } from "./matter.ts";
+import { readAgentsMdKeys } from "./agents-md.ts";
 
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
@@ -43,7 +44,7 @@ import matter from "gray-matter";
  * the runtime, and there is nothing to fail to import.
  */
 export function readFrontmatter(file: string): Record<string, unknown> {
-  return matter(fs.readFileSync(file, "utf8")).data as Record<string, unknown>;
+  return configMatter(fs.readFileSync(file, "utf8")).data as Record<string, unknown>;
 }
 import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.ts";
 import { refNames } from "./refs.ts";
@@ -952,6 +953,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
@@ -1020,6 +1027,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;
 }
 
 // Recognised HTTP verbs a tool may declare. Deliberately NOT named
@@ -1355,6 +1366,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
@@ -1467,6 +1481,13 @@ export interface FlowInfo {
    *  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,
@@ -1574,7 +1595,17 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
     .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: Record<string, any> = {};
+      let frontmatterError: string | undefined;
+      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"));
@@ -1592,6 +1623,7 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
         network,
         name,
         description: data.description ?? "",
+        ...resolveOwner(data.owner, workspaceFront.owner, accountFront.owner),
         model: data.model ?? "default",
         effort: data.effort ?? null,
         tools,
@@ -1615,10 +1647,22 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
         ...(() => { 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: string): string {
+  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
@@ -1784,11 +1828,24 @@ export function parseFlow(file: string, raw: string): FlowInfo {
   // 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: Record<string, any> = {};
+  let content: string;
+  let frontError: string | null = null;
+  try {
+    ({ data, content } = configMatter(raw));
+  } catch (err) {
+    frontError = frontmatterErrorText(err);
+    content = bodyAfterFrontmatter(raw);
+  }
   const steps: FlowStep[] = [];
   // Flow-level problems: a malformed step target (below) and unreadable
   // frontmatter enums (before the return). Reported as errors by flow-lint.
   const frontProblems: string[] = [];
+  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;
@@ -1990,6 +2047,7 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     }
   };
   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"]);
@@ -2005,6 +2063,7 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     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),
@@ -2041,6 +2100,7 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     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,
   };
@@ -2380,11 +2440,45 @@ function groupBlocks(blocks: FlowBlock[]): FlowBlock[][] {
 export function listFlows(tenant: string, workspace: string): FlowInfo[] {
   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: string, workspace: string): (flow: FlowInfo) => FlowInfo {
+  let above: { workspace: unknown; account: unknown } | null = 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) };
+  };
+}
+
+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 function resolveOwner(
+  own: unknown,
+  workspace?: unknown,
+  account?: unknown,
+  ownKind: "agent" | "flow" = "agent",
+): { owner: string | null; ownerFrom: OwnerSource | null } {
+  const text = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : null);
+  for (const [v, from] of [[own, ownKind], [workspace, "workspace"], [account, "account"]] as const) {
+    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,
@@ -2395,7 +2489,7 @@ export function readFlow(tenant: string, workspace: string, flowName: string): F
   if (!fs.existsSync(dir)) return null;
   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;
+    if (flow.name === flowName) return flowOwner(tenant, workspace)(flow);
   }
   return null;
 }
@@ -3068,6 +3162,60 @@ export interface RunEvent {
   /** Set on the line a hook wrote — a deny, a rewrite, context, a failure
    *  (hooks.ts). The run page and the Hooks page read these. */
   hook?: { hook: string; event: string; did: string; tool?: string; 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 const CAPTURE_CAP = 64 * 1024;
+
+/** 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]). */
@@ -3083,12 +3231,18 @@ export interface StepQuestion {
   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. */
@@ -3137,8 +3291,17 @@ export function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" |
   };
 }
 
-export { type TokenUsage, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens } from "./tokens.ts";
-import { sumTokens, type TokenUsage } from "./tokens.ts";
+export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
+import { sumTokens, type TokenUsage, type PromptLayerRecord } from "./tokens.ts";
+
+/** 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: { rescueOf?: string; instruction?: string | null }): boolean {
+  return !!step.rescueOf || (step.instruction ?? "").includes(RESCUE_MARKER);
+}
 
 export interface StepRecord {
   agent: string;
@@ -3211,6 +3374,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`
@@ -3290,6 +3456,13 @@ export interface StepRecord {
    *  actually executed in. Carried steps provide context and are never
    *  billed again — the original run's ledger line already paid for them. */
   carriedFrom?: string;
+  /** Set on an on-fail rescue record (runner.ts rescueStep): the agent of the
+   *  failed step it took over. A rescue is not a step of the flow: a resumed
+   *  drive must not launch it as one of its group, and a re-run must not
+   *  copy it as work (21 Oct 2026: one rerun carried 77 fixers as pending
+   *  steps). Records written before this field are recognised by their
+   *  instruction's `<rescue>` block instead — see isRescueRecord. */
+  rescueOf?: string;
   /**
    * Sandbox seconds this step rented, and how many of them were cold start.
    * Set only on the isolated path — an in-process step rents nothing, so
@@ -3324,6 +3497,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;
@@ -3392,6 +3570,17 @@ 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
@@ -3415,6 +3604,50 @@ export interface RunRecord {
   steps: StepRecord[];
 }
 
+// ---------------------------------------------------------------- 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: string, runId: string, callId: string): string | null {
+  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: string, runId: string, part: CapturedCall): void {
+  const file = capturedCallFile(workspaceRoot, runId, part.id);
+  if (!file) return;
+  let prev: Partial<CapturedCall> = {};
+  try {
+    prev = JSON.parse(fs.readFileSync(file, "utf8")) as CapturedCall;
+  } catch {
+    /* the first part */
+  }
+  const next: CapturedCall = { ...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: string, workspace: string, runId: string, callId: string): CapturedCall | null {
+  const file = capturedCallFile(workspaceDir(tenant, workspace), runId, callId);
+  if (!file) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as CapturedCall;
+  } catch {
+    return null;
+  }
+}
+
 export function runFilePath(tenant: string, workspace: string, runId: string) {
   assertSafeName(runId, "run id");
   return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);
@@ -3619,6 +3852,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;
 }
@@ -3637,6 +3875,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[];
@@ -3680,6 +3920,7 @@ export function summarizeRun(run: RunRecord): RunSummary {
     ...(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;
@@ -3698,11 +3939,29 @@ export function summarizeRun(run: RunRecord): RunSummary {
         ...(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: StepRecord): { tools?: string[]; toolErrors?: number; model?: string } {
+  const tools = new Set<string>();
+  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: RunSummary): RunRecord {
   const { awaitingApproval: _awaiting, ...run } = s;

package/src/tokens.ts

@@ -73,3 +73,71 @@ export function runTokens(run: { steps: readonly { tokens?: TokenUsage | null }[
   const toks = run.steps.map((s) => s.tokens).filter((t): t is TokenUsage => !!t);
   return toks.length ? sumTokens(toks) : 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 function promptLayersChanged(prev: readonly PromptLayerRecord[] | null | undefined, next: readonly PromptLayerRecord[] | null | undefined): string[] {
+  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: string[] = [];
+  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: readonly { agent: string; tokens?: TokenUsage | null; promptLayers?: readonly PromptLayerRecord[] | null }[],
+  index: number,
+): string | null {
+  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/src/tool-names.ts

@@ -52,7 +52,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. */

package/src/tool-programs.ts

@@ -16,7 +16,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.ts";
 import { parseRuntime } from "./runtime.ts";
 
 import { workspaceDir, workspaceTools, type ToolDef } from "./store.ts";