@foldrun/core 2.4.0 → 2.6.0

package/dist/src/agent-activity.d.ts

@@ -0,0 +1,5 @@
+import type { RunSummary } from "./store.ts";
+/** Agent name → the ISO time of its latest step that ran. */
+export declare function agentLastRuns(runs: RunSummary[]): Map<string, string>;
+/** Whole days since `iso`, or null for never. */
+export declare function daysSince(iso: string | null | undefined, now?: number): number | null;

package/dist/src/agent-activity.js

@@ -0,0 +1,31 @@
+// When each agent last did anything — the question an account with hundreds
+// of agents has to be able to answer before it can retire the ones nobody
+// uses. Read from the run index (listRunSummaries), so it covers what the
+// install keeps: runs older than its retention are gone, and an agent whose
+// last run was pruned reads as never run.
+/** A step that started counts; one that was skipped or never reached does not. */
+const RAN = new Set(["running", "completed", "failed", "awaiting-approval"]);
+/** Agent name → the ISO time of its latest step that ran. */
+export function agentLastRuns(runs) {
+    const last = new Map();
+    for (const run of runs) {
+        for (const step of run.steps ?? []) {
+            if (!step.agent || !RAN.has(step.status))
+                continue;
+            const at = step.startedAt ?? run.startedAt;
+            if (!at)
+                continue;
+            const prev = last.get(step.agent);
+            if (!prev || at > prev)
+                last.set(step.agent, at);
+        }
+    }
+    return last;
+}
+/** Whole days since `iso`, or null for never. */
+export function daysSince(iso, now = Date.now()) {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? Math.floor((now - t) / 86_400_000) : null;
+}

package/dist/src/agent-import.js

@@ -14,7 +14,7 @@
 // were about somebody else's desk.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import { configMatter } from "./matter.js";
 import { assertSafeName, listWorkspaceFiles, readWorkspaceFile, writeWorkspaceFile, workspaceDir, workspaceTools, listWorkspaces, } from "./store.js";
 import { libraryDir, libraryTools } from "./library.js";
 import { isRuntimeTool, toolEntryName } from "./tool-names.js";
@@ -64,7 +64,7 @@ export function importAgent(tenant, from, agent, to, opts = {}) {
         let content = readWorkspaceFile(tenant, from, src);
         const rel = src.slice(`agents/${agent}/`.length);
         if (rel === "agent.md") {
-            front = matter(content).data;
+            front = configMatter(content).data;
             // The folder is the name flows address; a `name:` that disagrees with
             // it is the first thing check would complain about.
             if (name !== agent)

package/dist/src/agent-tools.js

@@ -16,7 +16,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "gray-matter";
+import { configMatter } from "./matter.js";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { resolveModel, resolveEffort } from "./store.js";
@@ -36,7 +36,7 @@ export function gatherConsults(workspaceRoot, names) {
             missing.push(name);
             continue;
         }
-        const parsed = matter(fs.readFileSync(file, "utf8"));
+        const parsed = configMatter(fs.readFileSync(file, "utf8"));
         consults.push({
             name,
             systemPrompt: `${parsed.content.trim()}\n\n` +

package/dist/src/agents-md.d.ts

@@ -1,8 +1,12 @@
+import { keySpan } from "./frontmatter-text.ts";
+export { keySpan };
 /** The frontmatter of a directory's AGENTS.md (or project.md), or {}. */
 export declare function readAgentsMdKeys(dir: string): Record<string, unknown>;
 /** The text of `content` with each key in `patch` replaced (or removed for
  *  null), everything else byte for byte as it was. A file with no
- *  frontmatter gets one. */
+ *  frontmatter gets one. Read back before it is returned (frontmatter-guard
+ *  .ts): an edit that would not parse, would change another key or would
+ *  double one into its block throws UnsafeEditError (409). */
 export declare function patchFrontmatter(content: string, patch: Record<string, unknown | null>): string;
 /** Apply a frontmatter patch to a directory's AGENTS.md, creating the file
  *  when the directory has none. Returns the new content. */

package/dist/src/agents-md.js

@@ -8,7 +8,11 @@
 // else in the file is untouched. Null removes the key.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter, { configMatter } from "./matter.js";
+import { keySpan, dropEmptyBlock } from "./frontmatter-text.js";
+import { guardEdit } from "./frontmatter-guard.js";
+import { JOBS, FOLDABLE } from "./frontmatter-fields.js";
+export { keySpan };
 const FRONT = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n|$)/;
 /** The frontmatter of a directory's AGENTS.md (or project.md), or {}. */
 export function readAgentsMdKeys(dir) {
@@ -17,7 +21,7 @@ export function readAgentsMdKeys(dir) {
         if (!fs.existsSync(file))
             continue;
         try {
-            return (matter(fs.readFileSync(file, "utf8")).data ?? {});
+            return (configMatter(fs.readFileSync(file, "utf8")).data ?? {});
         }
         catch {
             return {};
@@ -34,8 +38,33 @@ function dumpKey(key, value) {
 }
 /** The text of `content` with each key in `patch` replaced (or removed for
  *  null), everything else byte for byte as it was. A file with no
- *  frontmatter gets one. */
+ *  frontmatter gets one. Read back before it is returned (frontmatter-guard
+ *  .ts): an edit that would not parse, would change another key or would
+ *  double one into its block throws UnsafeEditError (409). */
 export function patchFrontmatter(content, patch) {
+    // The guard reads the result folded (matter.ts configMatter), so a patch
+    // that writes a whole job block is checked as the keys it holds: each
+    // field the block may hold may change, and each one it sets reads back.
+    const changed = new Set();
+    const expect = {};
+    for (const [key, value] of Object.entries(patch)) {
+        changed.add(key);
+        const job = JOBS.find((j) => j.name === key)?.name;
+        if (!job) {
+            expect[key] = value;
+            continue;
+        }
+        for (const k of FOLDABLE[job])
+            changed.add(k);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            for (const [k, v] of Object.entries(value))
+                if (FOLDABLE[job].has(k))
+                    expect[k] = v;
+        }
+    }
+    return guardEdit(content, patchFrontmatterText(content, patch), [...changed], expect);
+}
+function patchFrontmatterText(content, patch) {
     const m = content.match(FRONT);
     let open = "---\n";
     let body = "";
@@ -50,22 +79,17 @@ export function patchFrontmatter(content, patch) {
     }
     let lines = body === "" ? [] : body.split("\n");
     for (const [key, value] of Object.entries(patch)) {
-        const at = lines.findIndex((l) => new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`).test(l));
-        let end = at;
-        if (at !== -1) {
-            end = at + 1;
-            // The block continues while lines are indented or blank-inside-block.
-            while (end < lines.length && (/^[ \t]/.test(lines[end]) || lines[end].trim() === ""))
-                end++;
-            // A blank line at the block's foot belongs to what follows.
-            while (end > at + 1 && lines[end - 1].trim() === "")
-                end--;
-        }
-        const replacement = value === null || value === undefined ? [] : dumpKey(key, value);
-        if (at === -1)
+        // Where it is written now — at the top or inside its job block — is
+        // where it is edited; a key written nowhere is added at the top.
+        const where = keySpan(lines, key);
+        const replacement = value === null || value === undefined ? [] : dumpKey(key, value).map((l) => `${where?.indent ?? ""}${l}`);
+        if (!where)
             lines = [...lines, ...replacement];
-        else
-            lines = [...lines.slice(0, at), ...replacement, ...lines.slice(end)];
+        else {
+            lines = [...lines.slice(0, where.at), ...replacement, ...lines.slice(where.end)];
+            if (!replacement.length && where.block !== null)
+                lines = dropEmptyBlock(lines, where.block);
+        }
     }
     const front = lines.length ? `${open}${lines.join("\n")}${close}` : "";
     if (!front)

package/dist/src/alerts.d.ts

@@ -0,0 +1,60 @@
+import type { Outcome } from "./outcome.ts";
+export interface AlertConfig {
+    failureRate?: number;
+    minRuns: number;
+    creditsDay?: number;
+    runMinutes?: number;
+    staleDays?: number;
+    costSpike?: number;
+    runsPerHour?: number;
+    /** Told after a run (platform host-watch.ts), not on the watchdog's tick. */
+    newHost?: boolean;
+}
+/** The config, and what is wrong with it in words (for `foldrun check`). */
+export declare function parseAlerts(raw: unknown): {
+    config: AlertConfig | null;
+    problems: string[];
+};
+export interface AlertFacts {
+    /** Outcomes of the runs started in the last 24 hours. */
+    outcomes: Outcome[];
+    /** Credits are cents: USD charged in the last 24 hours. */
+    chargedUsd: number;
+    /** Runs still going. */
+    live: {
+        id: string;
+        flow: string;
+        startedAt: string;
+    }[];
+    /** For stale_days: each agent, when it last ran (null: not in the runs
+     *  kept), and since when it has existed — an agent added yesterday is not
+     *  stale for never having run. */
+    agents?: {
+        name: string;
+        lastRunAt: string | null;
+        since: string;
+    }[];
+    /** For cost_spike and runs_per_hour: the runs of the last seven days,
+     *  test runs left out. costUsd is what its steps cost. */
+    runs?: {
+        id: string;
+        flow: string;
+        startedAt: string;
+        finishedAt: string | null;
+        costUsd: number;
+    }[];
+}
+export interface Alert {
+    /** What the once-a-day memory is keyed by: the rule, or the rule and run. */
+    key: string;
+    headline: string;
+    detail: string;
+    runId?: string;
+    flow?: string;
+    /** Said once for this key, however long it stays true (a slow run, an
+     *  idle spell); the watchdog's notice memory is pruned after a week, so
+     *  a condition that lasts is said again weekly at most. */
+    once?: boolean;
+}
+/** What crosses its threshold now. */
+export declare function evaluateAlerts(cfg: AlertConfig, facts: AlertFacts, workspace: string, now: number): Alert[];

package/dist/src/alerts.js

@@ -0,0 +1,161 @@
+// `alerts:` — the thresholds a workspace wants to hear about (FOL-72 step 7):
+//
+//   alerts:
+//     failure_rate: 30%     # of its runs that finished in the last 24 hours
+//     min_runs: 5           # …once at least this many have (default 5)
+//     credits_day: 2000     # credits charged in the last 24 hours
+//     run_minutes: 45       # a run still going after this long
+//     stale_days: 30        # an agent that has not run in this many days
+//     cost_spike: 3         # a run that cost this many times its flow's 7-day average
+//     runs_per_hour: 20     # one flow started this many times in an hour
+//     new_host: true        # an agent reached a site it never reached before
+//
+// In AGENTS.md (the workspace's, else the account's). The watchdog evaluates
+// them on its tick and tells `notify:` once per rule a day (a slow run once
+// per run), as event `alert`. Pure: `foldrun check` and the watchdog read the
+// same parse.
+const KEYS = ["failure_rate", "min_runs", "credits_day", "run_minutes", "stale_days", "cost_spike", "runs_per_hour", "new_host"];
+const num = (v) => {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string" && v.trim() && Number.isFinite(Number(v.trim())))
+        return Number(v.trim());
+    return null;
+};
+/** The config, and what is wrong with it in words (for `foldrun check`). */
+export function parseAlerts(raw) {
+    if (raw === undefined || raw === null)
+        return { config: null, problems: [] };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return { config: null, problems: ["alerts: is a block — failure_rate, min_runs, credits_day, run_minutes, stale_days, cost_spike, runs_per_hour, new_host"] };
+    }
+    const o = raw;
+    const problems = [];
+    for (const k of Object.keys(o))
+        if (!KEYS.includes(k))
+            problems.push(`alerts: ${k} — not a threshold; the keys are ${KEYS.join(", ")}`);
+    const cfg = { minRuns: 5 };
+    if (o.failure_rate !== undefined) {
+        const s = String(o.failure_rate).trim();
+        const pct = /^(\d+(?:\.\d+)?)\s*%$/.exec(s);
+        const v = pct ? Number(pct[1]) / 100 : num(o.failure_rate);
+        if (v === null || v <= 0 || v > 1)
+            problems.push(`alerts: failure_rate ${s} — a share of runs, like 30% or 0.3`);
+        else
+            cfg.failureRate = v;
+    }
+    for (const [key, field, min] of [["min_runs", "minRuns", 1], ["credits_day", "creditsDay", 1], ["run_minutes", "runMinutes", 1], ["stale_days", "staleDays", 1], ["cost_spike", "costSpike", 1.5], ["runs_per_hour", "runsPerHour", 2]]) {
+        if (o[key] === undefined)
+            continue;
+        const v = num(o[key]);
+        if (v === null || v < min)
+            problems.push(`alerts: ${key} ${String(o[key])} — a number, at least ${min}`);
+        else
+            cfg[field] = v;
+    }
+    if (o.new_host !== undefined) {
+        if (typeof o.new_host !== "boolean")
+            problems.push(`alerts: new_host ${String(o.new_host)} — true or false`);
+        else if (o.new_host)
+            cfg.newHost = true;
+    }
+    const any = cfg.newHost === true || cfg.failureRate !== undefined || cfg.creditsDay !== undefined || cfg.runMinutes !== undefined || cfg.staleDays !== undefined || cfg.costSpike !== undefined || cfg.runsPerHour !== undefined;
+    return { config: any ? cfg : null, problems };
+}
+/** How few earlier runs a flow needs before its average means anything. */
+const SPIKE_MIN_RUNS = 3;
+/** What crosses its threshold now. */
+export function evaluateAlerts(cfg, facts, workspace, now) {
+    const out = [];
+    if (cfg.failureRate !== undefined) {
+        const finished = facts.outcomes.filter((o) => o === "failed" || o === "good" || o === "done" || o === "quiet" || o === "blocked" || o === "bad");
+        const failed = finished.filter((o) => o === "failed").length;
+        if (finished.length >= cfg.minRuns && failed / finished.length >= cfg.failureRate) {
+            out.push({
+                key: "failure_rate",
+                headline: `⚠ ${workspace}: ${failed} of its last ${finished.length} runs failed`,
+                detail: `${Math.round((100 * failed) / finished.length)}% in the last 24 hours, over the ${Math.round(cfg.failureRate * 100)}% in alerts: failure_rate. Its Issues show what broke.`,
+            });
+        }
+    }
+    if (cfg.creditsDay !== undefined) {
+        const credits = Math.round(facts.chargedUsd * 100);
+        if (credits >= cfg.creditsDay) {
+            out.push({
+                key: "credits_day",
+                headline: `⚠ ${workspace} was charged ${credits.toLocaleString("en")} credits in a day`,
+                detail: `Over the ${cfg.creditsDay.toLocaleString("en")} in alerts: credits_day, in the last 24 hours. Observe shows which flows and agents.`,
+            });
+        }
+    }
+    if (cfg.runMinutes !== undefined) {
+        for (const r of facts.live) {
+            const mins = (now - Date.parse(r.startedAt)) / 60_000;
+            if (mins >= cfg.runMinutes) {
+                out.push({
+                    key: `run_minutes/${r.id}`,
+                    runId: r.id,
+                    flow: r.flow,
+                    headline: `⚠ ${workspace}: ${r.flow} has been running ${Math.round(mins)} minutes`,
+                    detail: `Run ${r.id} is past the ${cfg.runMinutes} minutes in alerts: run_minutes — still going, maybe stuck. Stop it from its page if it is.`,
+                });
+            }
+        }
+    }
+    if (cfg.costSpike !== undefined && facts.runs) {
+        // A run that finished in the last day, against the runs of its flow that
+        // finished before it in the week: once per run.
+        const done = facts.runs.filter((r) => r.finishedAt).sort((a, b) => a.finishedAt.localeCompare(b.finishedAt));
+        for (const r of done) {
+            if (now - Date.parse(r.finishedAt) > 86_400_000)
+                continue;
+            const before = done.filter((o) => o.flow === r.flow && o.id !== r.id && o.finishedAt < r.finishedAt);
+            if (before.length < SPIKE_MIN_RUNS)
+                continue;
+            const mean = before.reduce((n, o) => n + o.costUsd, 0) / before.length;
+            if (mean <= 0 || r.costUsd < cfg.costSpike * mean)
+                continue;
+            out.push({
+                key: `cost_spike/${r.id}`,
+                runId: r.id,
+                flow: r.flow,
+                headline: `${workspace}: a ${r.flow} run cost ${(r.costUsd / mean).toFixed(1)}× its usual`,
+                detail: `Run ${r.id} cost $${r.costUsd.toFixed(2)} against an average of $${mean.toFixed(2)} over its last ${before.length} runs this week — past the ${cfg.costSpike}× in alerts: cost_spike. Its page shows which step spent it.`,
+            });
+        }
+    }
+    if (cfg.runsPerHour !== undefined && facts.runs) {
+        const hour = facts.runs.filter((r) => now - Date.parse(r.startedAt) <= 3_600_000);
+        const byFlow = new Map();
+        for (const r of hour)
+            byFlow.set(r.flow, (byFlow.get(r.flow) ?? 0) + 1);
+        for (const [flow, n] of byFlow) {
+            if (n < cfg.runsPerHour)
+                continue;
+            out.push({
+                key: `runs_per_hour/${flow}`,
+                flow,
+                headline: `${workspace}: ${flow} started ${n} times in an hour`,
+                detail: `Past the ${cfg.runsPerHour} in alerts: runs_per_hour — a loop, a webhook sender retrying, or a schedule written wrong. Its Triggers page shows what started each; throttle: or debounce: caps it, and Settings → Pause stops it now.`,
+            });
+        }
+    }
+    if (cfg.staleDays !== undefined) {
+        for (const a of facts.agents ?? []) {
+            const from = Date.parse(a.lastRunAt ?? a.since);
+            if (!Number.isFinite(from))
+                continue;
+            const days = Math.floor((now - from) / 86_400_000);
+            if (days < cfg.staleDays)
+                continue;
+            out.push({
+                // Keyed by the run it last made, so a run and a new idle spell are news again.
+                key: `stale_days/${a.name}/${a.lastRunAt ?? "never"}`,
+                once: true,
+                headline: `${workspace}: agent ${a.name} has not run in ${days} days`,
+                detail: `${a.lastRunAt ? `Its last step started ${a.lastRunAt.slice(0, 10)}` : "No run kept on record has used it"} — past the ${cfg.staleDays} days in alerts: stale_days. If nothing needs it any more, retire it: delete agents/${a.name}/ and redeploy, so it holds no tools or secrets nobody watches.`,
+            });
+        }
+    }
+    return out;
+}

package/dist/src/browser-pod.js

@@ -169,6 +169,10 @@ export function classifyCall(tool, input, ctx = {}) {
         return { write: false };
     if (server === "foldrun_ask")
         return write("a question to a person");
+    // tools: [peers] — reading the roster changes nothing; a message to a
+    // colleague is said, and a re-run would say it twice.
+    if (server === "foldrun_peers")
+        return name === "peers_list" ? { write: false } : write("a message to a colleague");
     if (server === "foldrun_scripts") {
         if (name !== "web")
             return write(`script ${name}`);

package/dist/src/capture.d.ts

@@ -0,0 +1,23 @@
+import type { CallIo } from "./step-exec.ts";
+/** How much past the cap a step sends, so masking sees a secret whole
+ *  before the cut (a value longer than this is a file secret, which is also
+ *  masked line by line). */
+export declare const CAPTURE_SLACK = 4096;
+/**
+ * What the step's scrub replaces: every secret value it holds → its name,
+ * longest first. An `@file` secret (a key, a certificate) by its content, not
+ * its stored form; a multi-line value also line by line, because a file is
+ * read back a line at a time (the Read tool numbers each); and every value
+ * also as it appears inside JSON, where `"` `\` and newlines are escaped — a
+ * tool's input is JSON. Values under 8 characters are skipped: a two-letter
+ * secret would redact half the language, and anything that short is not one.
+ */
+export declare function redactionsFor(secrets: Record<string, string | undefined>): [string, string][];
+/** Masked, then cut to the cap. */
+export declare function maskCall(text: string, redactSecrets: (text: string) => string): {
+    text: string;
+    cut: boolean;
+};
+export declare function recordCallIo(workspaceRoot: string, runId: string, callId: string, tool: string, io: CallIo, 
+/** The step's own scrub: its resolved secret values → `[redacted:NAME]`. */
+redactSecrets: (text: string) => string): boolean;

package/dist/src/capture.js

@@ -0,0 +1,80 @@
+// A tool call's content, from a step's event to the file beside its run
+// (FOL-54 step 4), masked twice: the step's own secrets by value (the
+// runner's redact, from redactionsFor), then anything shaped like a
+// credential or a private key — a key the agent read from a file or a page
+// is not in the vault, and is still a key. Masked first, cut second, so a
+// secret on the cap's edge is never kept half. Recording never fails the step.
+import { redactText } from "./scan.js";
+import { writeCapturedCall, CAPTURE_CAP } from "./store.js";
+import { isFileValue, fileContent } from "./secrets.js";
+/** How much past the cap a step sends, so masking sees a secret whole
+ *  before the cut (a value longer than this is a file secret, which is also
+ *  masked line by line). */
+export const CAPTURE_SLACK = 4096;
+/**
+ * What the step's scrub replaces: every secret value it holds → its name,
+ * longest first. An `@file` secret (a key, a certificate) by its content, not
+ * its stored form; a multi-line value also line by line, because a file is
+ * read back a line at a time (the Read tool numbers each); and every value
+ * also as it appears inside JSON, where `"` `\` and newlines are escaped — a
+ * tool's input is JSON. Values under 8 characters are skipped: a two-letter
+ * secret would redact half the language, and anything that short is not one.
+ */
+export function redactionsFor(secrets) {
+    const out = new Map();
+    const add = (v, name) => {
+        if (v.length >= 8 && !out.has(v))
+            out.set(v, name);
+    };
+    for (const [name, raw] of Object.entries(secrets)) {
+        if (typeof raw !== "string")
+            continue;
+        for (const v of isFileValue(raw) ? [raw, fileContent(raw)] : [raw]) {
+            add(v, name);
+            add(v.trim(), name);
+            const escaped = JSON.stringify(v).slice(1, -1);
+            if (escaped !== v)
+                add(escaped, name);
+            if (/\r?\n/.test(v.trim())) {
+                for (const line of v.split(/\r?\n/)) {
+                    const l = line.trim();
+                    if (l.length >= 16)
+                        add(l, name);
+                }
+            }
+        }
+    }
+    return [...out.entries()].sort((a, b) => b[0].length - a[0].length);
+}
+// A private key's whole block — scan.ts names a key header and leaves the
+// body, which is right for a finding and wrong for a stored output.
+// Unterminated too: a key cut short, or printed without its END line, is
+// masked to the end of the text.
+const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$(?![\s\S]))/g;
+/** Masked, then cut to the cap. */
+export function maskCall(text, redactSecrets) {
+    const masked = redactText(redactSecrets(text)).replace(PRIVATE_KEY, "[redacted:private key]");
+    return masked.length > CAPTURE_CAP ? { text: masked.slice(0, CAPTURE_CAP), cut: true } : { text: masked, cut: false };
+}
+export function recordCallIo(workspaceRoot, runId, callId, tool, io, 
+/** The step's own scrub: its resolved secret values → `[redacted:NAME]`. */
+redactSecrets) {
+    try {
+        const input = io.input === undefined ? null : maskCall(io.input, redactSecrets);
+        const output = io.output === undefined ? null : maskCall(io.output, redactSecrets);
+        writeCapturedCall(workspaceRoot, runId, {
+            id: callId,
+            tool,
+            // Which part was cut, each on its own: in the sandbox (the whole was
+            // longer than what was sent) or here, after masking.
+            ...(input ? { input: input.text, ...(io.inputChars !== undefined ? { inputChars: io.inputChars } : {}), ...(input.cut || (io.inputChars ?? 0) > io.input.length ? { inputCut: true } : {}) } : {}),
+            ...(output ? { output: output.text, ...(io.outputChars !== undefined ? { outputChars: io.outputChars } : {}), ...(output.cut || (io.outputChars ?? 0) > io.output.length ? { outputCut: true } : {}) } : {}),
+            ...(io.truncated || input?.cut || output?.cut ? { truncated: true } : {}),
+        });
+        return true;
+    }
+    catch (err) {
+        console.error(`[capture] ${tool} (${callId}) for ${runId}:`, err instanceof Error ? err.message : err);
+        return false;
+    }
+}

package/dist/src/compare.d.ts

@@ -0,0 +1,57 @@
+import type { RunRecord } from "./store.ts";
+export interface StepSide {
+    status: string;
+    instruction: string;
+    model?: string;
+    secs: number | null;
+    tokensIn: number;
+    tokensOut: number;
+    modelCalls: number;
+    /** Tool name → how many calls. */
+    tools: Record<string, number>;
+    toolErrors: number;
+    /** The first errors it wrote, each one line. */
+    errors: string[];
+    /** The first line of what it concluded. */
+    said: string | null;
+}
+export interface StepDiff {
+    /** 1-based, as the trace numbers steps. */
+    step: number;
+    agent: string;
+    base: StepSide | null;
+    run: StepSide | null;
+    /** What differs, in words, most telling first; [] when nothing does. */
+    changes: string[];
+}
+export interface RunComparison {
+    base: {
+        id: string;
+        status: string;
+        startedAt: string;
+        revision: string | null;
+    };
+    run: {
+        id: string;
+        status: string;
+        startedAt: string;
+        revision: string | null;
+    };
+    revisionChanged: boolean;
+    /** Files changed between the two revisions; null when that cannot be said. */
+    changedFiles: string[] | null;
+    steps: StepDiff[];
+}
+export declare function compareRuns(base: RunRecord, run: RunRecord, changedFiles?: string[] | null): RunComparison;
+/** The run to compare a run with when none is named: the newest earlier run
+ *  of the same flow that finished well (completed, not BLOCKED or BAD), or
+ *  null. `outcomeOf` is the caller's, so this stays free of the verdict reader. */
+export declare function lastGoodBefore<R extends {
+    id: string;
+    flow: string;
+    startedAt: string;
+}>(runs: R[], run: {
+    id: string;
+    flow: string;
+    startedAt: string;
+}, good: (r: R) => boolean): R | null;