@foldrun/core 2.3.0 → 2.5.0

package/src/operator.ts

@@ -20,6 +20,23 @@
 //
 // Both leave a trace event with an `operator` field, which the runner turns
 // into step.questions / step.messages on the record.
+//
+// And a third line, between colleagues (20 Oct 2026):
+//
+//   tools: [peers]  the agent gets `peers_list` and `peers_message` — who
+//                   else is running in its parallel group right now, and a
+//                   message to one of them (or all). It lands in the
+//                   sibling's own inbox, so it reaches that model after its
+//                   next tool call, the same door a person's message uses,
+//                   and the sender hears any reply the same way. A step that
+//                   finds mid-way that it needs something a sibling has —
+//                   a file name, a decision, a number — asks for it instead
+//                   of guessing or failing. Nothing waits: the step goes on
+//                   and the answer, if one comes, arrives as context.
+//
+// Peer messages travel the person's inbox with `by` set to `peer:<agent>`,
+// so the reader can tell a colleague from a person without a second store
+// or a second door on the proxy.
 
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
@@ -31,7 +48,33 @@ export type OperatorEvent =
   | { kind: "asked"; id: string; question: string; options?: string[] }
   | { kind: "answered"; id: string; answer: string; by?: string | null }
   | { kind: "unanswered"; id: string }
-  | { kind: "message"; text: string; by?: string | null; at: string };
+  | { kind: "message"; text: string; by?: string | null; at: string }
+  /** A colleague running beside this step sent it a message (tools: [peers]). */
+  | { kind: "peer"; from: string; text: string; at: string }
+  /** This step sent a colleague a message. `to` is the agents it reached. */
+  | { kind: "told"; to: string[]; text: string; at: string };
+
+/** A step running in the same parallel group, as its siblings see it. */
+export interface PeerInfo {
+  /** The sibling's agent name — what `peers_message` is addressed to. */
+  agent: string;
+  /** Its index in run.steps: which inbox a message to it goes to. */
+  step: number;
+  /** The first line of its instruction, so a sibling knows what it is on. */
+  instruction: string;
+}
+
+/** A sibling's address: `agent#step`, the step as the flow numbers it
+ *  (1-based). A fan-out's instances share an agent name, so the bare name
+ *  reaches every instance and the address reaches one. */
+export const peerAddress = (p: { agent: string; step: number }): string => `${p.agent}#${p.step + 1}`;
+/** Does `to` name this sibling? `all`, its agent name, or its address. */
+export const peerMatches = (p: PeerInfo, to: string): boolean => to === "all" || to === p.agent || to === peerAddress(p);
+
+/** `by` on an inbox message from a colleague, not a person: `peer:<address>`. */
+export const PEER_BY_PREFIX = "peer:";
+export const peerOf = (by: string | null | undefined): string | null =>
+  typeof by === "string" && by.startsWith(PEER_BY_PREFIX) ? by.slice(PEER_BY_PREFIX.length) : null;
 
 export interface OperatorMessage {
   text: string;
@@ -49,6 +92,13 @@ export interface OperatorChannel {
   /** Nobody will read this question's answer now (the wait timed out):
    *  stop offering it to people. Best effort; optional for fakes. */
   close?(id: string): Promise<void>;
+  /** tools: [peers] — the siblings this step may message, as the lease
+   *  carries them; empty when the step runs alone. Optional: an older
+   *  proxy, or a fake, has no colleagues to offer. */
+  peers?(): Promise<PeerInfo[]>;
+  /** Leave `text` in the inbox of the sibling named `to` (or of every
+   *  sibling, `"all"`). Resolves with the agents it reached. */
+  tell?(to: string, text: string): Promise<{ to: string[] }>;
 }
 
 export const QUESTION_MAX = 2_000;
@@ -110,6 +160,71 @@ export function httpChannel(egress: string | undefined | null, fetchImpl: typeof
         }),
       );
     },
+    async peers() {
+      const body = await json(await fetchImpl(`${ep.base}/peers/${ep.token}`, { signal: AbortSignal.timeout(5_000) }));
+      return Array.isArray(body.peers) ? (body.peers as PeerInfo[]) : [];
+    },
+    async tell(to, text) {
+      const body = await json(
+        await fetchImpl(`${ep.base}/peers/${ep.token}/message`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ to, text }),
+          signal: AbortSignal.timeout(10_000),
+        }),
+      );
+      return { to: Array.isArray(body.to) ? (body.to as string[]) : [] };
+    },
+  };
+}
+
+/**
+ * The colleagues' line for steps that run in this process (`foldrun run`
+ * on a laptop, a host without a proxy): one bus per run, an inbox per step,
+ * the same shape the proxy serves. A person has no door here — nobody can
+ * write in from outside — but siblings can still reach each other.
+ */
+export function localPeerBus() {
+  const inboxes = new Map<number, OperatorMessage[]>();
+  /** Steps that have ended: off every roster, and a message to one reaches
+   *  nobody — it would never be read. */
+  const gone = new Set<number>();
+  const live = (siblings: PeerInfo[]) => siblings.filter((p) => !gone.has(p.step));
+  return {
+    /** The step is over (however it ended): nobody can reach it now. */
+    leave(step: number) {
+      gone.add(step);
+      inboxes.delete(step);
+    },
+    /** The channel for one step: who its siblings are, and its own inbox. */
+    channelFor(self: { agent: string; step: number }, siblings: PeerInfo[]): OperatorChannel {
+      return {
+        async ask() {
+          throw new Error("nobody can answer here");
+        },
+        async poll() {
+          return null;
+        },
+        async inbox() {
+          const mine = inboxes.get(self.step) ?? [];
+          inboxes.delete(self.step);
+          return mine;
+        },
+        async peers() {
+          return live(siblings);
+        },
+        async tell(to, text) {
+          const targets = live(siblings).filter((p) => peerMatches(p, to));
+          const at = new Date().toISOString();
+          for (const p of targets) {
+            const list = inboxes.get(p.step) ?? [];
+            list.push({ text: text.slice(0, MESSAGE_MAX), by: PEER_BY_PREFIX + peerAddress(self), at });
+            inboxes.set(p.step, list.slice(-50));
+          }
+          return { to: targets.map(peerAddress) };
+        },
+      };
+    },
   };
 }
 
@@ -214,6 +329,82 @@ export function buildAskTool(opts: {
 /** The granted name of the tool — the same on every path. */
 export const ASK_TOOL = "mcp__foldrun_ask__ask_person";
 
+/** The granted names of the colleagues' tools — the same on every path. */
+export const PEER_TOOLS = ["mcp__foldrun_peers__peers_list", "mcp__foldrun_peers__peers_message"];
+export const PEER_TEXT_MAX = MESSAGE_MAX;
+
+/** The in-sandbox `peers_list` and `peers_message` tools (tools: [peers]).
+ *  `siblings` is what the runner knew at launch: the other steps of this
+ *  step's parallel group. The channel delivers; with none (no proxy and no
+ *  local bus) the tools say so rather than pretend. */
+export function buildPeerTools(opts: { channel: OperatorChannel | null; self: string; siblings: PeerInfo[]; emit: Emit; now?: () => number }) {
+  const text = (t: string) => ({ content: [{ type: "text" as const, text: t }] });
+  const roster = () =>
+    opts.siblings.length
+      ? opts.siblings.map((p) => `- ${peerAddress(p)}: ${p.instruction}`).join("\n")
+      : "Nobody: this step runs alone in its group.";
+  const list = tool(
+    "peers_list",
+    "Who else is running beside you right now — the other steps of your parallel group, each as agent#step with what it is doing. Message one with peers_message, addressed as agent#step (or the bare agent name, which reaches every instance of that agent).",
+    {},
+    async () => {
+      let peers = opts.siblings;
+      try {
+        peers = (await opts.channel?.peers?.()) ?? opts.siblings;
+      } catch {
+        /* the launch-time roster stands */
+      }
+      opts.siblings = peers;
+      return text(`Running beside you in this group:\n${roster()}`);
+    },
+  );
+  const message = tool(
+    "peers_message",
+    "Send a short message to a colleague running beside you in this parallel group — to ask for something it has (a file name, a figure, a decision) or to tell it something it needs. It reaches that agent after its next tool call; any reply reaches you the same way, after your next tool call, so carry on working and check what arrives. Not a way to hand over your work.",
+    {
+      to: z.string().describe("The colleague's address from peers_list (agent#step), its bare agent name (every instance of it), or \"all\" for every sibling"),
+      text: z.string().describe("The complete message — the colleague has not read your context; say who you are, what you need and where to put it"),
+    },
+    async ({ to, text: body }) => {
+      const target = String(to).trim();
+      const msg = String(body).trim().slice(0, PEER_TEXT_MAX);
+      if (!target || !msg) return { ...text("peers_message needs `to` and `text`."), isError: true };
+      if (!opts.siblings.some((p) => peerMatches(p, target))) {
+        return { ...text(`No colleague named "${target}" runs beside you. ${roster()}`), isError: true };
+      }
+      if (!opts.channel?.tell) return { ...text("No line to colleagues here (no proxy): the message was not delivered."), isError: true };
+      let reached: string[];
+      try {
+        ({ to: reached } = await opts.channel.tell(target, msg));
+      } catch (err) {
+        return { ...text(`Could not deliver: ${err instanceof Error ? err.message : String(err)}`), isError: true };
+      }
+      const at = new Date(opts.now?.() ?? Date.now()).toISOString();
+      opts.emit("info", `told ${reached.join(", ") || "nobody"}: ${msg}`, { operator: { kind: "told", to: reached, text: msg, at } });
+      if (!reached.length) return text(`Nobody received it: "${target}" is not running beside you now.`);
+      return text(`Delivered to ${reached.join(", ")}. It reaches them after their next tool call; a reply reaches you after yours.`);
+    },
+  );
+  return {
+    server: createSdkMcpServer({ name: "foldrun_peers", version: "1.0.0", tools: [list, message] }),
+    /** The tools' own functions, for tests. */
+    list: () => list.handler({}, {}),
+    message: (args: { to: string; text: string }) => message.handler(args, {}),
+    toolNames: PEER_TOOLS,
+    promptLines: [peersPromptLine(opts.siblings)],
+  };
+}
+
+/** The line the system prompt gets for tools: [peers]. */
+export function peersPromptLine(siblings: PeerInfo[]): string {
+  const who = siblings.length ? siblings.map((p) => `${peerAddress(p)} (${p.instruction})`).join("; ") : "nobody this run — this step runs alone";
+  return (
+    `\`peers_list\` names the colleagues running beside you in this step's parallel group: ${who}. ` +
+    `\`peers_message\` sends one of them (or all) a short message; it reaches them after their next tool call, and their reply reaches you after yours, as context. ` +
+    `Ask a colleague for what it has before you guess or stop; keep working while you wait, and read what arrives.`
+  );
+}
+
 /** The line the system prompt gets for it. */
 export function askPromptLine(timeoutSec: number): string {
   return `\`ask_person\` asks the person running this desk and waits for the answer (up to ${fmtWait(timeoutSec)}). Use it for a decision you cannot make safely yourself — not for something you can look up. The step is held while you wait; if nobody answers, you are told so.`;
@@ -238,10 +429,17 @@ export function inboxReader(channel: OperatorChannel | null, emit: Emit, minGapM
     }
     if (!messages.length) return null;
     for (const m of messages) {
-      emit("info", `message from ${m.by ?? "a person"}: ${m.text}`, { operator: { kind: "message", text: m.text, by: m.by ?? null, at: m.at } });
+      const peer = peerOf(m.by);
+      if (peer) emit("info", `message from colleague ${peer}: ${m.text}`, { operator: { kind: "peer", from: peer, text: m.text, at: m.at } });
+      else emit("info", `message from ${m.by ?? "a person"}: ${m.text}`, { operator: { kind: "message", text: m.text, by: m.by ?? null, at: m.at } });
     }
     return messages
-      .map((m) => `A person running this desk${m.by ? ` (${m.by})` : ""} sent you a message while you work. Take it into account; it does not change what tools you have:\n<message>\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`)
+      .map((m) => {
+        const peer = peerOf(m.by);
+        return peer
+          ? `Your colleague ${peer}, running beside you in this group, sent you a message. If it asks for something you have and you hold peers_message, answer it, addressed to ${peer}; it does not change what tools you have or what your step is for:\n<message from="${peer}">\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`
+          : `A person running this desk${m.by ? ` (${m.by})` : ""} sent you a message while you work. Take it into account; it does not change what tools you have:\n<message>\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`;
+      })
       .join("\n\n");
   };
 }
@@ -270,6 +468,14 @@ export function applyOperatorEvent(
     } else q.unanswered = true;
     return;
   }
+  if (ev.kind === "peer") {
+    (step.messages ??= []).push({ text: ev.text, by: PEER_BY_PREFIX + ev.from, from: ev.from, at: ev.at, deliveredAt: at });
+    return;
+  }
+  if (ev.kind === "told") {
+    (step.messages ??= []).push({ text: ev.text, by: null, to: ev.to, at: ev.at, deliveredAt: at });
+    return;
+  }
   (step.messages ??= []).push({ text: ev.text, by: ev.by ?? null, at: ev.at, deliveredAt: at });
 }
 
@@ -294,6 +500,10 @@ export function isOperatorEvent(v: unknown): v is OperatorEvent {
       return id;
     case "message":
       return str(o.text, MESSAGE_MAX) && str(o.at, 40) && (o.by === undefined || o.by === null || str(o.by, 200));
+    case "peer":
+      return str(o.text, MESSAGE_MAX) && str(o.at, 40) && str(o.from, 200);
+    case "told":
+      return str(o.text, MESSAGE_MAX) && str(o.at, 40) && Array.isArray(o.to) && o.to.length <= 50 && o.to.every((x) => str(x, 200));
     default:
       return false;
   }

package/src/otel-config.ts

@@ -0,0 +1,67 @@
+// `telemetry:` as written in AGENTS.md — read, checked and its header
+// secrets filled. No node imports: the dashboard's settings form reads it
+// in the browser. The trace itself is otel.ts.
+
+export interface TelemetryConfig {
+  /** Where the trace is POSTed: the collector's OTLP/HTTP traces URL. */
+  endpoint: string;
+  /** Header name → value; a value written `${NAME}` is a vault secret's name. */
+  headers: Record<string, string>;
+}
+
+const SECRET_REF = /^\$\{([A-Z][A-Z0-9_]{1,63})\}$/;
+const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
+
+/** The block as written, and what is wrong with it in words. */
+export function parseTelemetry(raw: unknown): { config: TelemetryConfig | null; problems: string[] } {
+  if (raw === undefined || raw === null) return { config: null, problems: [] };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { config: null, problems: ["telemetry: is a block — otlp: <https URL of the collector's /v1/traces>, and headers:"] };
+  }
+  const o = raw as Record<string, unknown>;
+  const problems: string[] = [];
+  for (const k of Object.keys(o)) if (k !== "otlp" && k !== "headers") problems.push(`telemetry: ${k} — not a key; the keys are otlp and headers`);
+  const endpoint = typeof o.otlp === "string" ? o.otlp.trim() : "";
+  let url: URL | null = null;
+  try {
+    url = endpoint ? new URL(endpoint) : null;
+  } catch {
+    url = null;
+  }
+  if (!url || url.protocol !== "https:") problems.push(`telemetry: otlp ${endpoint || "(missing)"} — an https:// URL, the collector's OTLP/HTTP traces endpoint (…/v1/traces)`);
+  const headers: Record<string, string> = {};
+  if (o.headers !== undefined) {
+    if (!o.headers || typeof o.headers !== "object" || Array.isArray(o.headers)) problems.push("telemetry: headers is a block of name: value");
+    else {
+      for (const [name, value] of Object.entries(o.headers as Record<string, unknown>)) {
+        if (!HEADER_NAME.test(name)) problems.push(`telemetry: header "${name}" — letters, digits and dashes`);
+        else if (typeof value !== "string" || !value.trim()) problems.push(`telemetry: header ${name} — a value, or \${SECRET_NAME} for one in the vault`);
+        else if (!SECRET_REF.test(value.trim()) && /token|key|secret|auth/i.test(name)) {
+          problems.push(`telemetry: header ${name} is written into the file — put it in the vault (foldrun secrets set NAME) and write \${NAME}`);
+        } else headers[name.toLowerCase()] = value.trim();
+      }
+    }
+  }
+  return { config: problems.length ? null : { endpoint, headers }, problems };
+}
+
+/** The vault secrets a config's headers name. */
+export function telemetrySecretNames(cfg: TelemetryConfig): string[] {
+  return Object.values(cfg.headers).map((v) => SECRET_REF.exec(v)?.[1]).filter((n): n is string => !!n);
+}
+
+/** Header values with each `${NAME}` filled by `lookup`; the names it could not fill. */
+export function telemetryHeaders(cfg: TelemetryConfig, lookup: (name: string) => string | null): { headers: Record<string, string>; missing: string[] } {
+  const headers: Record<string, string> = {};
+  const missing: string[] = [];
+  for (const [k, v] of Object.entries(cfg.headers)) {
+    const ref = SECRET_REF.exec(v)?.[1];
+    if (!ref) headers[k] = v;
+    else {
+      const value = lookup(ref);
+      if (value === null) missing.push(ref);
+      else headers[k] = value;
+    }
+  }
+  return { headers, missing };
+}

package/src/otel.ts

@@ -0,0 +1,100 @@
+// 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 type { RunRecord } from "./store.ts";
+import { buildTraceTree, type TraceSpan } from "./trace-tree.ts";
+
+export { parseTelemetry, telemetrySecretNames, telemetryHeaders, type TelemetryConfig } from "./otel-config.ts";
+
+type AttrValue = { stringValue: string } | { intValue: string } | { doubleValue: number } | { boolValue: boolean };
+type Attr = { key: string; value: AttrValue };
+
+const attr = (key: string, v: string | number | boolean | null | undefined): Attr[] => {
+  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: string, len: number) => crypto.createHash("sha256").update(s).digest("hex").slice(0, len);
+const nanos = (msEpoch: number) => (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 } as const;
+
+export interface TraceContext {
+  tenant: string;
+  workspace: string;
+  /** Agent name → its owner (owner: …), stamped on its step spans. */
+  owners?: Record<string, string | null>;
+  /** The platform version, as the instrumentation scope's. */
+  version?: string;
+}
+
+/** The ExportTraceServiceRequest for one run. */
+export function runToOtlp(run: RunRecord, ctx: TraceContext, 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: unknown[] = [];
+  const visit = (s: TraceSpan, parent: string | null, inherited: { start: number; agent?: string }) => {
+    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/src/outcome.ts

@@ -0,0 +1,90 @@
+// 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 type Outcome = "running" | "queued" | "waiting" | "good" | "done" | "quiet" | "blocked" | "bad" | "failed" | "stopped";
+
+export const OUTCOMES: readonly Outcome[] = ["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: string, verdict: string | null | undefined): Outcome {
+  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: Outcome) => o === "running" || o === "queued" || o === "waiting";
+/** Ran to the end without failing — whatever it found. */
+export const isCompleted = (o: Outcome) => 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: Outcome) => isCompleted(o) || o === "failed";
+/** Went wrong or found something wrong: failed, BAD, BLOCKED. */
+export const needsAttention = (o: Outcome) => 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: Outcome) => needsAttention(o) || o === "waiting";
+/** Completed and reported nothing wrong (GOOD, QUIET, or nothing said). */
+export const isSuccess = (o: Outcome) => o === "good" || o === "done" || o === "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 function tally(outcomes: Iterable<Outcome>): Tally {
+  const t: Tally = { 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/src/package.ts

@@ -26,7 +26,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 import {
   assertSafeName,
   isEditablePath,

package/src/platform.ts

@@ -29,7 +29,7 @@ export type Edition = "self-hosted" | "hosted";
  *  told, because a silent drop reads exactly like a broken hook. */
 export type TriggerAdmission =
   | { admit: true }
-  | { admit: false; reason: "duplicate" | "throttled" | "quarantined" | "paused" | "debounced"; detail: string; firesAt?: number };
+  | { admit: false; reason: "duplicate" | "throttled" | "quarantined" | "paused" | "halted" | "debounced"; detail: string; firesAt?: number };
 
 export interface PlatformHooks {
   /** Is this a hosted install? The ONE question every commercial surface —

package/src/prompt-layers.ts

@@ -0,0 +1,90 @@
+// 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";
+import type { PromptLayerRecord } from "./tokens.ts";
+
+// 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, type PromptLayerRecord } from "./tokens.ts";
+
+export interface AssembledPrompt {
+  /** The whole prompt, stable layers first. */
+  text: string;
+  layers: PromptLayerRecord[];
+}
+
+const SEP = "\n\n";
+
+export function hashLayer(text: string): string {
+  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 {
+  private readonly order: string[] = [];
+  private readonly text = new Map<string, string[]>();
+  private readonly dynamic = new Set<string>();
+
+  add(name: string, text: string, opts: { dynamic?: boolean } = {}): void {
+    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(): AssembledPrompt {
+    const parts: string[] = [];
+    const layers: PromptLayerRecord[] = [];
+    const take = (names: string[], isDynamic: boolean) => {
+      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: string, workspace: string, agent: string): string {
+  return `fr-${crypto.createHash("sha256").update(`${tenant}\u0000${workspace}\u0000${agent}`).digest("hex").slice(0, 32)}`;
+}

package/src/provider-health.ts

@@ -21,7 +21,7 @@
 import { accountModelBlock } from "./model-credential.ts";
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 import { getSecret } from "./secrets.ts";
 import { noteSecretUse, healthKey } from "./secret-health.ts";
 import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider, type ProviderSpec } from "./store.ts";