@zhuxixi/pi-agent-board 0.3.0

package/src/core/atomic.mjs

@@ -0,0 +1,145 @@
+/**
+ * Atomic + crash-tolerant file helpers used across the extension and the runner.
+ *
+ * Writes go to a temp sibling then `rename()` (atomic on the same filesystem) so a
+ * reader never observes a half-written JSON file. Reads tolerate missing/corrupt files.
+ */
+import { randomBytes } from "node:crypto";
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+
+/** @param {string} dir */
+export function ensureDir(dir) {
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Atomically write a string to `file` (creates parent dirs).
+ * @param {string} file
+ * @param {string} data
+ */
+export function atomicWrite(file, data) {
+	ensureDir(path.dirname(file));
+	const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	writeFileSync(tmp, data, "utf8");
+	renameSync(tmp, file);
+}
+
+/**
+ * Atomically write a value as pretty JSON.
+ * @param {string} file
+ * @param {unknown} value
+ */
+export function atomicWriteJson(file, value) {
+	atomicWrite(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * Read and parse JSON, returning `fallback` when the file is missing or unparseable.
+ * @template T
+ * @param {string} file
+ * @param {T} fallback
+ * @returns {T}
+ */
+export function readJson(file, fallback) {
+	try {
+		if (!existsSync(file)) return fallback;
+		const raw = readFileSync(file, "utf8");
+		if (!raw.trim()) return fallback;
+		return /** @type {T} */ (JSON.parse(raw));
+	} catch {
+		return fallback;
+	}
+}
+
+/**
+ * Append one line (a trailing newline is added) to a log/jsonl file.
+ * @param {string} file
+ * @param {string} line
+ */
+export function appendLine(file, line) {
+	ensureDir(path.dirname(file));
+	appendFileSync(file, line.endsWith("\n") ? line : `${line}\n`, "utf8");
+}
+
+/**
+ * Append one JSON value as a JSONL record.
+ * @param {string} file
+ * @param {unknown} value
+ */
+export function appendJsonl(file, value) {
+	appendLine(file, JSON.stringify(value));
+}
+
+/**
+ * Read a JSONL file into parsed objects, skipping blank/corrupt lines.
+ * @param {string} file
+ * @returns {any[]}
+ */
+export function readJsonl(file) {
+	try {
+		if (!existsSync(file)) return [];
+		const out = [];
+		for (const line of readFileSync(file, "utf8").split("\n")) {
+			const t = line.trim();
+			if (!t) continue;
+			try {
+				out.push(JSON.parse(t));
+			} catch {
+				/* skip corrupt line */
+			}
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Read the newest `limit` JSONL records. Corrupt lines are skipped.
+ * @param {string} file
+ * @param {number} [limit]
+ * @returns {any[]}
+ */
+export function readJsonlTail(file, limit = 50) {
+	const all = readJsonl(file);
+	const n = Math.max(0, Math.floor(Number(limit) || 0));
+	return n > 0 ? all.slice(-n) : all;
+}
+
+/**
+ * Best-effort delete helper used by cleanup actions.
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function removeFile(file) {
+	try {
+		if (!existsSync(file)) return false;
+		unlinkSync(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Read a file's text, returning `fallback` if missing.
+ * @param {string} file
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+export function readText(file, fallback = "") {
+	try {
+		return existsSync(file) ? readFileSync(file, "utf8") : fallback;
+	} catch {
+		return fallback;
+	}
+}

package/src/core/auto-state.mjs

@@ -0,0 +1,320 @@
+/**
+ * Automatic terminal-state classification for finished agent turns.
+ *
+ * The dashboard has three user-facing post-run buckets:
+ *   - needs_input  → agent is waiting on the user
+ *   - idle         → in progress / worth revisiting
+ *   - completed    → done
+ *
+ * This module is pure (no model/network I/O). Runners may feed model JSON into
+ * parseAutoStateModelOutput(); otherwise heuristicAutoState() gives a safe fallback.
+ */
+import { createHash } from "node:crypto";
+import { deriveSummary } from "./derive.mjs";
+import { detectNeedsInput, firstSentence, splitSentences, truncate } from "./heuristics.mjs";
+
+/** @typedef {import("./types.mjs").SemanticState} SemanticState */
+/** @typedef {"needs_input"|"in_progress"|"done"} AutoStateKind */
+/** @typedef {"model"|"heuristic"} AutoStateSource */
+/** @typedef {"high"|"medium"|"low"} AutoStateConfidence */
+
+const AUTO_STATE_KINDS = new Set(["needs_input", "in_progress", "done"]);
+const CONFIDENCES = new Set(["high", "medium", "low"]);
+const DEFAULT_AUTO_STATE_MODEL = "gpt-4o";
+
+/** @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env] */
+export function autoStateEnabled(env = process.env) {
+	const raw = env.AGENT_BOARD_AUTO_STATE ?? env.AGENT_VIEW_AUTO_STATE;
+	return !isOff(raw);
+}
+
+/** @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env] */
+export function autoStateModel(env = process.env) {
+	const configured = env.AGENT_BOARD_AUTO_STATE_MODEL ?? env.AGENT_VIEW_AUTO_STATE_MODEL;
+	if (isOff(configured)) return null;
+	return configured || DEFAULT_AUTO_STATE_MODEL;
+}
+
+/** @param {string|undefined} value */
+function isOff(value) {
+	return typeof value === "string" && /^(0|false|off|no)$/i.test(value.trim());
+}
+
+/** @param {AutoStateKind} kind @returns {SemanticState} */
+export function semanticStateForAutoKind(kind) {
+	switch (kind) {
+		case "needs_input":
+			return "needs_input";
+		case "done":
+			return "completed";
+		default:
+			return "idle";
+	}
+}
+
+/**
+ * Prompt used by runners for the cheap classifier pass.
+ * @param {string} latestAssistantText
+ */
+export function buildAutoStatePrompt(latestAssistantText) {
+	const text = truncate(String(latestAssistantText || "").trim(), 6000);
+	return `Classify the LAST assistant response for a coding-agent dashboard.\n\nChoose exactly one state:\n- needs_input: the assistant asks the user for a decision, clarification, approval, credentials, or is blocked waiting for the user.\n- in_progress: work is partial, next steps remain, verification is pending/failed, or the assistant says it will continue later.\n- done: the requested work is complete, final answer given, no user input required.\n\nReturn ONLY minified JSON with this shape:\n{"state":"needs_input|in_progress|done","confidence":"high|medium|low","reason":"short reason <=18 words","question":"user-facing question or null"}\n\nLast assistant response:\n${text}`;
+}
+
+/**
+ * Parse and normalize model JSON. Returns null if the response is unusable.
+ * @param {string} raw
+ * @param {{ latestAssistantText?: string, now?: number, lastAgentActivityAt?: number|null }} [opts]
+ */
+export function parseAutoStateModelOutput(raw, opts = {}) {
+	const obj = extractJsonObject(raw);
+	if (!obj) return null;
+	const kind = normalizeKind(obj.state ?? obj.kind ?? obj.status);
+	if (!kind) return null;
+	const confidence = normalizeConfidence(obj.confidence);
+	const latest = opts.latestAssistantText ?? "";
+	const nb = detectNeedsInput(latest);
+	const question = kind === "needs_input" ? cleanQuestion(obj.question) || nb.question || latestQuestion(latest) : null;
+	return makeClassification(kind, {
+		source: "model",
+		confidence,
+		reason: cleanReason(obj.reason) || defaultReason(kind),
+		question,
+		now: opts.now,
+		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+		latestAssistantText: latest,
+	});
+}
+
+/**
+ * Conservative fallback classifier. It should be useful, but never clever enough to
+ * overrule strong question/error signals.
+ * @param {string} latestAssistantText
+ * @param {{ now?: number, lastAgentActivityAt?: number|null }} [opts]
+ */
+export function heuristicAutoState(latestAssistantText, opts = {}) {
+	const text = String(latestAssistantText || "").trim();
+	const nb = detectNeedsInput(text);
+	if (nb.needsInput) {
+		return makeClassification("needs_input", {
+			source: "heuristic",
+			confidence: "high",
+			reason: "Assistant asked for user input",
+			question: nb.question,
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+
+	const lower = text.toLowerCase();
+	const pending = hasPendingSignal(lower);
+	const done = hasDoneSignal(lower);
+	if (done && !pending) {
+		return makeClassification("done", {
+			source: "heuristic",
+			confidence: hasStrongDoneSignal(lower) ? "high" : "medium",
+			reason: "Assistant reported the work is complete",
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+	if (pending) {
+		return makeClassification("in_progress", {
+			source: "heuristic",
+			confidence: "medium",
+			reason: "Assistant mentioned remaining work or pending verification",
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
+	return makeClassification("in_progress", {
+		source: "heuristic",
+		confidence: "low",
+		reason: "No clear completion or input signal",
+		now: opts.now,
+		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+		latestAssistantText: text,
+	});
+}
+
+/**
+ * Pick a model classification when valid, otherwise fall back to heuristics.
+ * @param {string} modelOutput
+ * @param {string} latestAssistantText
+ * @param {{ now?: number, lastAgentActivityAt?: number|null }} [opts]
+ */
+export function autoStateFromModelOrHeuristic(modelOutput, latestAssistantText, opts = {}) {
+	return parseAutoStateModelOutput(modelOutput, { latestAssistantText, ...opts }) ?? heuristicAutoState(latestAssistantText, opts);
+}
+
+/**
+ * Mutate a RunStatus with a classification. Returns true if state/metadata changed.
+ * @param {import("./types.mjs").RunStatus} status
+ * @param {import("./types.mjs").AutoStateClassification} classification
+ * @param {number} [now]
+ */
+export function applyAutoStateToStatus(status, classification, now = Date.now()) {
+	if (!classification || status.processState === "alive") return false;
+	if (status.semanticState === "failed" || status.semanticState === "stopped") return false;
+	const nextState = semanticStateForAutoKind(classification.kind);
+	const before = `${status.semanticState}|${status.question ?? ""}|${status.summary ?? ""}|${status.autoState?.source ?? ""}|${status.autoState?.textHash ?? ""}`;
+	status.semanticState = nextState;
+	status.autoState = { ...classification, semanticState: nextState, classifiedAt: now };
+	if (nextState === "needs_input") {
+		status.question = classification.question || detectNeedsInput(status.latestAssistantPreview).question || latestQuestion(status.latestAssistantPreview);
+	} else {
+		status.question = null;
+	}
+	status.summary = deriveSummary(status);
+	const after = `${status.semanticState}|${status.question ?? ""}|${status.summary ?? ""}|${status.autoState?.source ?? ""}|${status.autoState?.textHash ?? ""}`;
+	return before !== after;
+}
+
+/**
+ * Mutate a ViewState with a classification. Returns true if state/metadata changed.
+ * @param {import("./types.mjs").ViewState} state
+ * @param {import("./types.mjs").AutoStateClassification} classification
+ * @param {number} [now]
+ */
+export function applyAutoStateToViewState(state, classification, now = Date.now()) {
+	if (!classification || state.processState === "alive") return false;
+	if (state.semanticState === "failed" || state.semanticState === "stopped") return false;
+	const nextState = semanticStateForAutoKind(classification.kind);
+	const before = `${state.semanticState}|${state.question ?? ""}|${state.summary ?? ""}|${state.autoState?.source ?? ""}|${state.autoState?.textHash ?? ""}`;
+	state.semanticState = nextState;
+	state.needsInput = nextState === "needs_input";
+	state.hasError = nextState === "failed";
+	state.autoState = { ...classification, semanticState: nextState, classifiedAt: now };
+	if (nextState === "needs_input") {
+		state.question = classification.question || detectNeedsInput(state.latestAssistantPreview).question || latestQuestion(state.latestAssistantPreview);
+	} else {
+		state.question = null;
+	}
+	state.error = nextState === "failed" ? state.error : null;
+	state.updatedAt = now;
+	state.summary = deriveSummary({
+		processState: state.processState,
+		semanticState: state.semanticState,
+		currentTool: state.latestTool,
+		question: state.question,
+		error: state.error,
+		latestAssistantPreview: state.latestAssistantPreview,
+	});
+	const after = `${state.semanticState}|${state.question ?? ""}|${state.summary ?? ""}|${state.autoState?.source ?? ""}|${state.autoState?.textHash ?? ""}`;
+	return before !== after;
+}
+
+/**
+ * @param {AutoStateKind} kind
+ * @param {{ source: AutoStateSource, confidence?: AutoStateConfidence, reason?: string, question?: string|null, now?: number, lastAgentActivityAt?: number|null, latestAssistantText?: string }} opts
+ * @returns {import("./types.mjs").AutoStateClassification}
+ */
+function makeClassification(kind, opts) {
+	const now = opts.now ?? Date.now();
+	const semanticState = semanticStateForAutoKind(kind);
+	return {
+		version: 1,
+		kind,
+		semanticState,
+		confidence: opts.confidence ?? "low",
+		source: opts.source,
+		reason: truncate(String(opts.reason || defaultReason(kind)).replace(/\s+/g, " ").trim(), 120),
+		question: opts.question ? truncate(String(opts.question).replace(/\s+/g, " ").trim(), 240) : null,
+		classifiedAt: now,
+		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+		textHash: textHash(opts.latestAssistantText ?? ""),
+	};
+}
+
+/** @param {string} raw */
+function extractJsonObject(raw) {
+	const text = String(raw || "").trim();
+	if (!text) return null;
+	const candidates = [text];
+	const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+	if (fenced) candidates.unshift(fenced[1].trim());
+	const first = text.indexOf("{");
+	const last = text.lastIndexOf("}");
+	if (first >= 0 && last > first) candidates.unshift(text.slice(first, last + 1));
+	for (const candidate of candidates) {
+		try {
+			const parsed = JSON.parse(candidate);
+			if (parsed && typeof parsed === "object") return parsed;
+		} catch {
+			/* try next */
+		}
+	}
+	return null;
+}
+
+/** @param {any} value @returns {AutoStateKind|null} */
+function normalizeKind(value) {
+	const s = String(value ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	if (AUTO_STATE_KINDS.has(s)) return /** @type {AutoStateKind} */ (s);
+	if (["needsinput", "input", "input_required", "requires_input", "awaiting_input", "blocked", "question"].includes(s)) return "needs_input";
+	if (["progress", "ongoing", "continue", "continuing", "partial", "not_done", "todo"].includes(s)) return "in_progress";
+	if (["complete", "completed", "finished", "finish", "success", "resolved"].includes(s)) return "done";
+	return null;
+}
+
+/** @param {any} value @returns {AutoStateConfidence} */
+function normalizeConfidence(value) {
+	const s = String(value ?? "medium").toLowerCase().trim();
+	return CONFIDENCES.has(s) ? /** @type {AutoStateConfidence} */ (s) : "medium";
+}
+
+/** @param {any} value */
+function cleanReason(value) {
+	return String(value ?? "").replace(/\s+/g, " ").trim();
+}
+
+/** @param {any} value */
+function cleanQuestion(value) {
+	const s = String(value ?? "").replace(/\s+/g, " ").trim();
+	if (!s || /^null$/i.test(s) || /^none$/i.test(s)) return null;
+	return s;
+}
+
+/** @param {AutoStateKind} kind */
+function defaultReason(kind) {
+	switch (kind) {
+		case "needs_input":
+			return "Assistant is waiting for user input";
+		case "done":
+			return "Assistant reported completion";
+		default:
+			return "Assistant appears to have more work remaining";
+	}
+}
+
+/** @param {string} text */
+function latestQuestion(text) {
+	const sentences = splitSentences(text);
+	return [...sentences].reverse().find((s) => /\?\s*$/.test(s)) ?? null;
+}
+
+/** @param {string} lower */
+function hasStrongDoneSignal(lower) {
+	return /(^|\b)(done|completed|complete|finished|resolved|all set|implemented|shipped)(\b|[.!])/i.test(lower) || /tests? (pass|passed|passing)/i.test(lower);
+}
+
+/** @param {string} lower */
+function hasDoneSignal(lower) {
+	return hasStrongDoneSignal(lower)
+		|| /\b(final answer|summary:|i'?ve (fixed|updated|added|implemented)|successfully|ready to go)\b/i.test(lower)
+		|| firstSentence(lower).length > 0 && /^done[.!]/i.test(firstSentence(lower));
+}
+
+/** @param {string} lower */
+function hasPendingSignal(lower) {
+	return /\b(todo|next steps?|remaining|still need|need to|not yet|pending|in progress|continue|will continue|i'?ll continue|i will|follow up|not run|couldn'?t run|unable to run|blocked|waiting for)\b/i.test(lower)
+		|| /\btests? (fail|failed|failing|pending|not run|weren'?t run|couldn'?t be run)\b/i.test(lower);
+}
+
+/** @param {string} text */
+function textHash(text) {
+	return createHash("sha1").update(String(text || "")).digest("hex").slice(0, 12);
+}

package/src/core/dashboard-render.mjs

@@ -0,0 +1,10 @@
+/**
+ * Request a differential dashboard repaint.
+ *
+ * Full-screen custom overlays still participate in Pi TUI's line diffing. Passing
+ * `true` here discards that state and clears the terminal before every repaint,
+ * which is visible as flicker on terminals without synchronized-output support.
+ */
+export function requestDashboardRender(tui) {
+	tui.requestRender();
+}

package/src/core/derive.mjs

@@ -0,0 +1,114 @@
+/**
+ * State-machine + summary derivation. Pure functions over a RunStatus.
+ *
+ * Semantic-state rules (plan §9.1):
+ *   while alive:   queued → working (once assistant/tool activity begins)
+ *   clean exit:    needs_input (asked a question) | idle (user can mark completed)
+ *   bad exit:      failed
+ *   user stop:     stopped
+ * Summary priority (plan §9.3): model → active tool → blocker → first sentence → error → fallback.
+ */
+import { firstSentence, truncate } from "./heuristics.mjs";
+
+/** @typedef {import("./types.mjs").RunStatus} RunStatus */
+/** @typedef {import("./types.mjs").SemanticState} SemanticState */
+
+const GENERIC_STATUS_TEXT = {
+	queued: new Set(["Queued"]),
+	working: new Set(["Working", "Working…", "Running", "Running…"]),
+	needs_input: new Set(["Needs input"]),
+	idle: new Set(["Idle", "In Progress"]),
+	completed: new Set(["Completed", "Done"]),
+	failed: new Set(["Failed"]),
+	stopped: new Set(["Stopped"]),
+};
+
+const ALL_GENERIC_STATUS_TEXT = new Set(Object.values(GENERIC_STATUS_TEXT).flatMap((labels) => [...labels]));
+
+/**
+ * Compute the terminal semantic state for a finished run.
+ * @param {{ exitCode:number|null, stopReason:string|null, stoppedByUser:boolean, needsInput:boolean }} p
+ * @returns {SemanticState}
+ */
+export function finalizeSemanticState({ exitCode, stopReason, stoppedByUser, needsInput }) {
+	if (stoppedByUser) return "stopped";
+	const errored = (exitCode != null && exitCode !== 0) || stopReason === "error" || stopReason === "aborted";
+	if (errored) return "failed";
+	if (needsInput) return "needs_input";
+	return "idle";
+}
+
+/**
+ * Fallback status text when no richer summary is available.
+ * @param {SemanticState} state
+ * @returns {string}
+ */
+export function fallbackStatusText(state) {
+	switch (state) {
+		case "queued":
+			return "Queued";
+		case "working":
+			return "Running…";
+		case "needs_input":
+			return "Needs input";
+		case "idle":
+			return "In Progress";
+		case "completed":
+			return "Done";
+		case "failed":
+			return "Failed";
+		case "stopped":
+			return "Stopped";
+		default:
+			return "Unknown";
+	}
+}
+
+/** @param {string|null|undefined} text */
+export function isGenericStatusText(text) {
+	const trimmed = String(text || "").trim();
+	return !trimmed || ALL_GENERIC_STATUS_TEXT.has(trimmed);
+}
+
+/**
+ * Normalize generic fallback summaries to the current display label for a state.
+ * @param {SemanticState} state
+ * @param {string|null|undefined} text
+ */
+export function normalizeGenericStatusText(state, text) {
+	const trimmed = String(text || "").trim();
+	if (!trimmed || GENERIC_STATUS_TEXT[state]?.has(trimmed)) return fallbackStatusText(state);
+	return trimmed;
+}
+
+/**
+ * Heuristic summary for a run (no model). Honors the documented priority order.
+ * @param {RunStatus} status
+ * @param {number} [max] max characters
+ * @returns {string}
+ */
+export function deriveSummary(status, max = 80) {
+	const s = status;
+	// 2. active tool (only while still working)
+	if (s.processState === "alive" && s.currentTool?.name) {
+		// currentTool.summary is precomputed by the reducer; fall back to name.
+		const ct = /** @type {any} */ (s.currentTool);
+		if (typeof ct.summary === "string" && ct.summary) return truncate(ct.summary, max);
+		return truncate(ct.name, max);
+	}
+	// 3. explicit blocker / question
+	if (s.semanticState === "needs_input" && s.question) return truncate(s.question, max);
+	// 5. error (placed above generic preview for failed runs)
+	if (s.semanticState === "failed" && s.error) return truncate(s.error, max);
+	// 4. first sentence of latest assistant output (fall back to full text if the first
+	// sentence is uninformatively short, e.g. "Done.")
+	if (s.latestAssistantPreview) {
+		const fs = firstSentence(s.latestAssistantPreview);
+		const pick = fs.length >= 12 ? fs : s.latestAssistantPreview;
+		return truncate(pick, max);
+	}
+	if (s.question) return truncate(s.question, max);
+	if (s.error) return truncate(s.error, max);
+	// 6. fallback status text
+	return fallbackStatusText(s.semanticState);
+}

package/src/core/diagnostics.mjs

@@ -0,0 +1,109 @@
+/** Diagnostics JSONL helpers for Agent Board rows. */
+import { atomicWrite, appendJsonl, readJsonl, readJsonlTail } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+
+const SECRET_KEY_RE = /token|secret|password|authorization|api[_-]?key/i;
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {Partial<import("./types.mjs").DiagnosticEvent>} patch
+ * @returns {import("./types.mjs").DiagnosticEvent}
+ */
+export function appendDiagnostic(root, viewId, patch = {}) {
+	const event = normalizeDiagnostic(viewId, patch);
+	appendJsonl(P.diagnosticsPath(root, viewId), event);
+	return event;
+}
+
+/** @param {string} root @param {string} viewId @returns {import("./types.mjs").DiagnosticEvent[]} */
+export function readDiagnostics(root, viewId) {
+	return readJsonl(P.diagnosticsPath(root, viewId)).map((e) => normalizeDiagnostic(viewId, e));
+}
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {{ limit?: number }} [opts]
+ * @returns {import("./types.mjs").DiagnosticEvent[]}
+ */
+export function tailDiagnostics(root, viewId, opts = {}) {
+	return readJsonlTail(P.diagnosticsPath(root, viewId), opts.limit ?? 50).map((e) => normalizeDiagnostic(viewId, e));
+}
+
+/** @param {string} root @param {string} viewId */
+export function clearDiagnostics(root, viewId) {
+	atomicWrite(P.diagnosticsPath(root, viewId), "");
+	return { ok: true };
+}
+
+/** @returns {import("./types.mjs").DiagnosticSummary} */
+export function emptyDiagnosticSummary() {
+	return {
+		count: 0,
+		warningCount: 0,
+		errorCount: 0,
+		lastAt: null,
+		lastLevel: null,
+		lastCode: null,
+		lastMessage: null,
+		stalled: false,
+		stallReason: null,
+	};
+}
+
+/** @param {import("./types.mjs").DiagnosticEvent[]} events @returns {import("./types.mjs").DiagnosticSummary} */
+export function summarizeDiagnostics(events) {
+	const summary = emptyDiagnosticSummary();
+	for (const event of events ?? []) {
+		summary.count += 1;
+		if (event.level === "warn") summary.warningCount += 1;
+		if (event.level === "error") summary.errorCount += 1;
+		summary.lastAt = event.at ?? summary.lastAt;
+		summary.lastLevel = event.level ?? summary.lastLevel;
+		summary.lastCode = event.code ?? summary.lastCode;
+		summary.lastMessage = event.message ?? summary.lastMessage;
+		if (event.code === "provider_stall" || event.code === "stalled") {
+			summary.stalled = true;
+			summary.stallReason = String(event.details?.reason ?? event.message ?? "stalled");
+		}
+		if (event.code === "provider_stall_resolved" || event.code === "stall_resolved") {
+			summary.stalled = false;
+			summary.stallReason = null;
+		}
+	}
+	return summary;
+}
+
+/** @param {string} root @param {string} viewId */
+export function readDiagnosticSummary(root, viewId) {
+	return summarizeDiagnostics(readDiagnostics(root, viewId));
+}
+
+/** @param {string} viewId @param {any} patch @returns {import("./types.mjs").DiagnosticEvent} */
+export function normalizeDiagnostic(viewId, patch = {}) {
+	const level = ["info", "warn", "error"].includes(patch.level) ? patch.level : "info";
+	const code = typeof patch.code === "string" && patch.code ? patch.code : "event";
+	return {
+		version: 1,
+		at: Number.isFinite(patch.at) ? patch.at : Date.now(),
+		viewId,
+		runId: typeof patch.runId === "string" ? patch.runId : null,
+		source: typeof patch.source === "string" && patch.source ? patch.source : "service",
+		level,
+		code,
+		message: typeof patch.message === "string" && patch.message ? patch.message : code,
+		details: redactDiagnosticDetails(patch.details ?? {}),
+	};
+}
+
+/** @param {any} value @returns {any} */
+export function redactDiagnosticDetails(value) {
+	if (Array.isArray(value)) return value.map((v) => redactDiagnosticDetails(v));
+	if (!value || typeof value !== "object") return value;
+	const out = {};
+	for (const [key, val] of Object.entries(value)) {
+		out[key] = SECRET_KEY_RE.test(key) ? "[redacted]" : redactDiagnosticDetails(val);
+	}
+	return out;
+}