one-code-extension 0.1.3 → 0.3.0

package/extensions/workflow/index.ts

@@ -12,20 +12,47 @@
  *
  * Orchestration is opt-in, like Claude Code: the tool description gates it,
  * and the literal keyword "ultracode" in a user message arms the turn via a
- * system reminder.
+ * system reminder (skipped while `/effort ultracode` has the standing block
+ * on — see `effort/`). The keyword is read by pi's `input` event, which only
+ * a prompt sent to an idle session fires; a message queued mid-turn does not
+ * arm (docs/upstream_prs.md #14).
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { recordUsage } from "../lib/usage-bus.ts";
+import { MODEL_UNUSABLE_CHANNEL, type ModelUnusableEvent } from "../lib/model-unusable.ts";
+import { whenAborted } from "../lib/abort.ts";
+import { createTaskNotifier, oneShotNote, sessionOutlivesTurn } from "../lib/notifications.ts";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { ULTRACODE_MODE_CHANNEL } from "../effort/slider.ts";
+import { PERMISSION_STATUS_CHANNEL } from "../permissions/modes.ts";
+import { watchPermissionBridge } from "../permissions/subagent-gate.ts";
+import { watchHookBridge } from "../hooks/subagent-bridge.ts";
 import { applicableSubagentDefault, loadSubagentDefault } from "../subagents/default-model.ts";
-import { discoverSavedWorkflows, findSavedWorkflow } from "./saved-workflows.ts";
+import { discoverSavedWorkflows, findSavedWorkflow, workflowDirs } from "./saved-workflows.ts";
 import { buildRunReport, WorkflowRunManager } from "./run-manager.ts";
-import { ccToolRenderers, customMessageText, notificationComponent } from "../lib/tui-render.ts";
+import {
+	ccToolRenderers,
+	customMessageText,
+	notificationComponent,
+	safeThemeBold,
+	safeThemePaint,
+	truncateLine,
+} from "../lib/tui-render.ts";
 import { WorkflowScriptError } from "./types.ts";
+import {
+	clampViewerState,
+	decodeStatusKey,
+	decodeViewerKey,
+	initialViewerState,
+	planSave,
+	renderViewer,
+	type ViewerRunSnapshot,
+} from "./viewer.ts";
 import { WorkflowWidget } from "./widget.ts";
 
 /**
@@ -39,7 +66,7 @@ const ULTRACODE_REMINDER =
 /**
  * Ported from Claude Code's Workflow tool description, adapted to this harness
  * (runId + follow-up message instead of a task id + task-notification,
- * `/workflows stop` instead of TaskStop, `subagent` as the single-agent
+ * `/workflows stop` instead of TaskStop, `Agent` as the single-agent
  * alternative). The authoring guidance is the substantive part: it is what
  * makes the model reach for pipeline() over barriers and pick sane fan-out
  * sizes, so it is kept rather than trimmed.
@@ -50,10 +77,12 @@ A workflow structures work across many agents — to be comprehensive (decompose
 
 ONLY call this tool when the user has explicitly opted into multi-agent orchestration. Workflows can spawn dozens of agents and consume a large amount of tokens; the user must request that scale, not have it inferred. Explicit opt-in means one of:
 - The user included the keyword "ultracode" in their prompt (you'll see a system-reminder confirming it).
+- Ultracode is on for the session (a system-reminder confirms it), which makes the opt-in standing for every turn until it is turned off.
 - The user directly asked you to run a workflow or use multi-agent orchestration in their own words ("use a workflow", "run a workflow", "fan out agents", "orchestrate this with subagents"). The ask must be in the user's words — a task that would merely benefit from a workflow does not count.
+- The user invoked a skill or slash command whose instructions tell you to call Workflow.
 - The user asked you to run a specific named or saved workflow.
 
-For any other task — even one that would clearly benefit from parallelism — do NOT call this tool. Use the \`subagent\` tool for individual subagents, or briefly describe what a multi-agent workflow could do and ask the user whether to run it.
+For any other task — even one that would clearly benefit from parallelism — do NOT call this tool. Use the \`Agent\` tool for individual subagents, or briefly describe what a multi-agent workflow could do and how much it would roughly cost, and ask the user whether to run it.
 
 When you do call it, the right move is often **hybrid**: scout inline first (list the files, find the targets, scope the diff) to discover the work-list, then call workflow to pipeline over it. You don't need to know the shape before the *task* — only before the *orchestration step*.
 
@@ -89,7 +118,7 @@ Script body hooks:
 - log(message: string): void — emit a progress message to the user.
 - phase(title: string): void — start a new phase; subsequent agent() calls are grouped under it.
 - args: any — the value passed as this tool's \`args\` input, verbatim. Pass arrays/objects as actual JSON values, NOT as a JSON-encoded string.
-- budget: {total: number|null, spent(): number, remaining(): number} — the run's token target from \`tokenBudget\`. \`total\` is null if none was set. The target is a HARD ceiling: once spent() reaches total, further agent() calls throw. Use for dynamic loops: \`while (budget.total && budget.remaining() > 50_000) { ... }\`.
+- budget: {total: number|null, spent(): number, remaining(): number} — the run's output-token target from \`tokenBudget\`, shared with nested workflows. \`total\` is null if none was set. Once spent() reaches total, new and queued agent() calls throw before starting. Already-running agents may finish above the target; this is not a hard cap on provider usage. Use for dynamic loops: \`while (budget.total && budget.remaining() > 50_000) { ... }\`.
 - workflow(nameOrRef: string | {scriptPath: string}, args?: any): Promise<any> — run another workflow inline as a sub-step. Nesting is one level only.
 
 DEFAULT TO pipeline(). Only reach for a barrier (parallel between stages) when you genuinely need ALL prior-stage results together — dedup/merge across the full result set, early-exit on a zero count, or a prompt that references "the other findings". A barrier is NOT justified by "I need to flatten/map/filter first" (do it inside a pipeline stage) or "the stages are conceptually separate".
@@ -165,7 +194,7 @@ const WorkflowParams = Type.Object({
 	tokenBudget: Type.Optional(
 		Type.Integer({
 			minimum: 1000,
-			description: "Hard output-token ceiling for the run, exposed to the script as budget {total, spent(), remaining()}",
+			description: "Output-token target shared by the run and nested workflows. Stops new and queued agents once reached; already-running agents may exceed it. Exposed as budget {total, spent(), remaining()}",
 		}),
 	),
 	sync: Type.Optional(
@@ -174,35 +203,59 @@ const WorkflowParams = Type.Object({
 });
 
 export default function workflowExtension(pi: ExtensionAPI) {
+	// Models the account refused this session (classifier/subagent reports, lib/model-unusable.ts):
+	// workflow agents share the subagent selector, so they resolve around them too.
+	const unusableModels = new Set<string>();
+	pi.events.on(MODEL_UNUSABLE_CHANNEL, (data) => {
+		unusableModels.add((data as ModelUnusableEvent).model);
+	});
+	const notifyTask = createTaskNotifier(pi);
 	const manager = new WorkflowRunManager();
 	let lastCtx: ExtensionContext | undefined;
 	const widget = new WorkflowWidget(manager, () => lastCtx);
 	const deliveredRuns = new Set<string>();
+	let viewerOpen = false;
+
+	// Parent permission bridge for workflow agents' gates — same bridge the
+	// subagent runner uses; see AgentRunnerOptions.getPermissionBridge.
+	const getPermissionBridge = watchPermissionBridge(pi);
+	const getHookBridge = watchHookBridge(pi);
+
+	const openViewer = async (ctx: ExtensionContext, opts?: { height?: "full" | "half"; runIndex?: number }) => {
+		if (viewerOpen) return;
+		viewerOpen = true;
+		try {
+			await openWorkflowViewer(ctx, manager, opts);
+		} finally {
+			viewerOpen = false;
+		}
+	};
 
 	const deliverResult = (runId: string) => {
 		const handle = manager.get(runId);
 		if (!handle || deliveredRuns.has(runId)) return;
 		deliveredRuns.add(runId);
-		pi.sendMessage(
-			{
-				customType: "workflow-result",
-				content: [{ type: "text", text: buildRunReport(handle) }],
-				display: true,
-				details: { runId: handle.runId, name: handle.meta.name, status: handle.status },
-			},
-			{ deliverAs: "followUp", triggerTurn: true },
-		);
+		notifyTask("one-code:workflow-result", buildRunReport(handle), { runId: handle.runId, name: handle.meta.name, status: handle.status });
 	};
 
-	pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) =>
+	pi.registerMessageRenderer("one-code:workflow-result", (message, { expanded }, theme) =>
 		notificationComponent(theme, customMessageText(message.content), expanded),
 	);
 
 	pi.registerTool({
 		name: "workflow",
 		label: "Workflow",
-		...ccToolRenderers<{ name?: string; scriptPath?: string; script?: string; resumeFromRunId?: string }>("Workflow", {
+		...ccToolRenderers<
+			{ name?: string; scriptPath?: string; script?: string; resumeFromRunId?: string },
+			{ runId?: string; background?: boolean }
+		>("Workflow", {
 			title: (a) => a?.name ?? a?.scriptPath ?? (a?.resumeFromRunId ? `resume ${a.resumeFromRunId}` : a?.script ? "inline script" : undefined),
+			// The model-facing start text is instructions, not information — show
+			// the user Claude Code's hint line instead.
+			result: (result, _args, isError) =>
+				!isError && result.details?.background
+					? `Running in background · /workflows to monitor and save · ${result.details.runId ?? ""}`.trimEnd()
+					: undefined,
 		}),
 		description: WORKFLOW_TOOL_DESCRIPTION,
 		promptSnippet: "Run a script that orchestrates many subagents (opt-in ultracode mode)",
@@ -247,12 +300,28 @@ export default function workflowExtension(pi: ExtensionAPI) {
 					cwd: ctx.cwd,
 					sessionDir,
 					defaultModel: ctx.model,
-					configuredDefaultModel: configuredDefault?.spec,
+					configuredDefault,
 					defaultEffort: ctx.thinkingLevel,
+					getPermissionBridge,
+					getHookBridge,
+					// Workflow agents run in their own sessions; their spend reaches the footer only through the bus.
+					onUsage: (cost) => recordUsage(pi, "subagent", { cost: { total: cost } }),
+					unusableModels: () => unusableModels,
+					onModelUnusable: (model, reason) => {
+						if (unusableModels.has(model)) return;
+						unusableModels.add(model);
+						pi.events.emit(MODEL_UNUSABLE_CHANNEL, { model, reason } satisfies ModelUnusableEvent);
+					},
 				});
 				widget.attach(handle);
 
-				if (params.sync) {
+				// One-shot modes (`-p` / `--mode json`) exit when the turn settles:
+				// session_shutdown aborts every run, so a backgrounded workflow never
+				// finished and its promised follow-up never came (LIFECYCLE-REVIEW
+				// M1, measured: no result, no journal). Run it to completion there,
+				// the rule bash and Agent apply, and return the report in the result.
+				const forcedSync = !params.sync && !sessionOutlivesTurn(ctx.mode);
+				if (params.sync || forcedSync) {
 					const onProgress = () => {
 						onUpdate?.({
 							content: [{ type: "text", text: handle.recentEvents.slice(-8).join("\n") || "starting…" }],
@@ -260,17 +329,17 @@ export default function workflowExtension(pi: ExtensionAPI) {
 						});
 					};
 					handle.on("progress", onProgress);
-					const onAbort = () => handle.abort("tool call aborted");
-					signal?.addEventListener("abort", onAbort, { once: true });
+					const unhookAbort = whenAborted(signal, () => handle.abort("tool call aborted"));
 					try {
 						await handle.finished;
 					} finally {
-						signal?.removeEventListener("abort", onAbort);
+						unhookAbort();
 						handle.removeListener("progress", onProgress);
 					}
 					deliveredRuns.add(handle.runId); // sync result goes in the tool result, not a followUp
+					const oneShotPrefix = forcedSync ? `${oneShotNote("workflow")}\n\n` : "";
 					return {
-						content: [{ type: "text", text: buildRunReport(handle) }],
+						content: [{ type: "text", text: `${oneShotPrefix}${buildRunReport(handle)}` }],
 						details: { runId: handle.runId, status: handle.status, scriptPath: handle.scriptPath },
 						isError: handle.status !== "completed",
 					};
@@ -302,14 +371,18 @@ export default function workflowExtension(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("workflows", {
-		description: "List workflow runs and saved workflows; stop or inspect runs",
+		description: "Open the workflow viewer; list, stop, or inspect runs",
 		getArgumentCompletions: (prefix) => {
-			const items = ["stop ", "log "].filter((c) => c.startsWith(prefix));
+			const items = ["stop ", "log ", "list"].filter((c) => c.startsWith(prefix));
 			return items.length ? items.map((c) => ({ value: c, label: c.trim() })) : null;
 		},
 		handler: async (args, ctx) => {
 			lastCtx = ctx;
 			const [action, runId] = args.trim().split(/\s+/);
+			if (!action && ctx.hasUI) {
+				await openViewer(ctx, { height: "full" });
+				return;
+			}
 			if (action === "stop" && runId) {
 				const stopped = manager.abort(runId, "stopped via /workflows");
 				ctx.ui.notify(stopped ? `Stopping ${runId}…` : `No running workflow ${runId}`, stopped ? "info" : "error");
@@ -347,18 +420,260 @@ export default function workflowExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	// While ultracode MODE is on (/effort ultracode) the standing block already
+	// carries the opt-in, so the keyword's single-turn one-shot is skipped: one
+	// instruction for one fact. `input` fires for prompt() only — a message the
+	// user queues while a turn is running (pi's steer()/followUp()) is expanded
+	// without it and does not arm the turn (upstream ask #14; the mode covers it).
+	let ultracodeMode = false;
+	pi.events.on(ULTRACODE_MODE_CHANNEL, (data) => {
+		ultracodeMode = (data as { active?: boolean })?.active === true;
+	});
 	pi.on("input", (event) => {
-		if (/\bultracode\b/i.test(event.text)) {
+		if (!ultracodeMode && /\bultracode\b/i.test(event.text)) {
 			pi.events.emit(REMINDER_CHANNEL, { text: ULTRACODE_REMINDER, scope: "next-turn" });
 		}
 		return undefined;
 	});
 
+	// Down-arrow soft focus for the below-editor status strip (Claude Code's
+	// bottom workflow entry): with the editor focused and empty, ↓ highlights
+	// the newest run's row; ↑/↓ move, enter opens the half-screen viewer, x
+	// stops the run, esc — or typing anything — returns to the editor. The
+	// listener runs before the focused component sees the byte, so every
+	// consume is guarded by "the core editor really has focus" (identity
+	// against the captured baseline) to never steal keys from dialogs.
+	let inputHookRegistered = false;
+	const DOWN_KEYS = new Set(["\x1b[B", "\x1bOB"]);
+	const registerInputHook = (registerCtx: ExtensionContext) => {
+		if (inputHookRegistered || !registerCtx.hasUI) return;
+		inputHookRegistered = true;
+		const leave = () => widget.setFocus(undefined);
+		try {
+			registerCtx.ui.onTerminalInput((data) => {
+				// Session switches replace the ExtensionContext; the hook registers
+				// once, so it must act through the freshest ctx, not its closure.
+				const ctx = lastCtx ?? registerCtx;
+				if (viewerOpen || !widget.rowCount()) {
+					if (widget.focusIndex !== undefined) leave();
+					return undefined;
+				}
+				if (widget.focusIndex === undefined) {
+					if (!DOWN_KEYS.has(data) || !widget.editorFocusedAndIdle(ctx)) return undefined;
+					widget.setFocus(0);
+					return { consume: true };
+				}
+				// Focus moved to a dialog/overlay since the strip took soft focus —
+				// drop it and let the dialog have the key.
+				if (!widget.editorFocused()) {
+					leave();
+					return undefined;
+				}
+				const key = decodeStatusKey(data);
+				if (!key) {
+					leave();
+					return undefined; // typing resumes in the editor, byte included
+				}
+				switch (key) {
+					case "up":
+						if (widget.focusIndex === 0) leave();
+						else widget.setFocus(widget.focusIndex - 1);
+						return { consume: true };
+					case "down":
+						widget.setFocus(Math.min(widget.rowCount() - 1, widget.focusIndex + 1));
+						return { consume: true };
+					case "leave":
+						leave();
+						// While the model streams, esc must still interrupt it — drop the
+						// soft focus and let the byte through; consumed only when idle.
+						return ctx.isIdle() ? { consume: true } : undefined;
+					case "stop": {
+						const run = widget.selectedRun();
+						if (run) manager.abort(run.runId, "stopped from status strip");
+						return { consume: true };
+					}
+					case "open": {
+						const runIndex = widget.focusIndex;
+						leave();
+						void openViewer(ctx, { height: "half", runIndex });
+						return { consume: true };
+					}
+				}
+			});
+		} catch {
+			// Mode without raw terminal input (print/RPC) — the strip is view-only.
+		}
+	};
+
 	pi.on("session_start", (_event, ctx) => {
 		lastCtx = ctx;
+		registerInputHook(ctx);
 	});
 
+	// The permission-mode badge is a below-editor widget too, re-set on every
+	// mode change; setWidget order is last-write order, so re-set the strip
+	// whenever the badge changes to keep it beneath the mode line (CC's order).
+	pi.events.on(PERMISSION_STATUS_CHANNEL, () => widget.refresh());
+
 	pi.on("session_shutdown", () => {
+		// Fires on /clear, /new and /resume too (findings §8): after this the ctx
+		// is invalid, so nothing below may paint on it.
 		manager.abortAll("session ended");
+		widget.dispose();
+		lastCtx = undefined;
+	});
+}
+
+/**
+ * The interactive workflow viewer (Claude Code's /workflows screen). All
+ * layout/key logic is pure in viewer.ts; this component owns only mutable
+ * state, the repaint ticker, and the save-to-.claude/workflows fs work.
+ *
+ * Liveness comes from a 500ms ticker (invalidate + requestRender) instead of
+ * per-RunHandle subscriptions — it also picks up runs that start while the
+ * viewer is open, and the memoized render keeps the per-frame cost at a map
+ * lookup (findings §15).
+ */
+async function openWorkflowViewer(
+	ctx: ExtensionContext,
+	manager: WorkflowRunManager,
+	opts?: { height?: "full" | "half"; runIndex?: number },
+): Promise<void> {
+	await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+		const paint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme) };
+
+		// Newest run first, so the viewer opens on the latest.
+		const snapshots = (): ViewerRunSnapshot[] => manager.snapshots();
+
+		// Full (the /workflows tab) fills the terminal; half (opened from the
+		// status strip) leaves the transcript visible above, like Claude Code.
+		const viewerHeight = (rows: number): number =>
+			opts?.height === "half" ? Math.max(12, Math.min(Math.floor(rows / 2), 30)) : Math.max(12, rows - 2);
+
+		const state = initialViewerState(opts?.runIndex ?? 0);
+		let cache: { width: number; lines: string[] } | undefined;
+		const repaint = () => {
+			cache = undefined;
+			tui.requestRender();
+		};
+		const ticker = setInterval(repaint, 500);
+		ticker.unref?.();
+
+		const save = (runs: ViewerRunSnapshot[]) => {
+			const run = runs[state.runIndex];
+			const handle = run && manager.get(run.runId);
+			if (!handle) return;
+			try {
+				const source = readFileSync(handle.scriptPath, "utf8");
+				const dir = workflowDirs(ctx.cwd, os.homedir()).project;
+				const safeName = run.name.replace(/[^A-Za-z0-9._-]/g, "-");
+				const target = join(dir, `${safeName}.js`);
+				const exists = existsSync(target);
+				const sameContent = exists && readFileSync(target, "utf8") === source;
+				const plan = planSave({ name: safeName, exists, sameContent, confirmed: state.confirmOverwrite });
+				if (plan.action === "write") {
+					mkdirSync(dir, { recursive: true });
+					writeFileSync(target, source, "utf8");
+					state.confirmOverwrite = false;
+				} else if (plan.action === "confirm") {
+					state.confirmOverwrite = true;
+				}
+				state.notice = plan.notice;
+			} catch (error) {
+				state.notice = `save failed: ${(error as Error).message}`;
+				state.confirmOverwrite = false;
+			}
+		};
+
+		return {
+			render: (width: number) => {
+				if (cache?.width === width) return cache.lines;
+				const height = viewerHeight(tui.terminal.rows);
+				const lines = renderViewer({ runs: snapshots(), state, width, height, now: Date.now() }, paint).map(
+					(line) => truncateLine(line, width),
+				);
+				cache = { width, lines };
+				return lines;
+			},
+			handleInput: (data: string) => {
+				const key = decodeViewerKey(data);
+				if (!key) return;
+				const close = () => {
+					clearInterval(ticker);
+					done(null);
+				};
+				if (key.kind === "close") return close();
+				if (key.kind !== "save") {
+					state.notice = undefined;
+					state.confirmOverwrite = false;
+				}
+				switch (key.kind) {
+					case "up":
+					case "down": {
+						const delta = key.kind === "up" ? -1 : 1;
+						if (state.level === "phases") state.phaseCursor += delta;
+						else state.agentCursor += delta;
+						clampViewerState(state, snapshots());
+						state.detailScroll = 0;
+						state.promptExpanded = false;
+						break;
+					}
+					case "enter":
+						// Phases level drills into the phase; agents level toggles the prompt.
+						if (state.level === "phases") {
+							state.level = "agents";
+							state.agentCursor = 0;
+							state.detailScroll = 0;
+							state.promptExpanded = false;
+							clampViewerState(state, snapshots()); // falls back if the phase has no agents
+						} else {
+							state.promptExpanded = !state.promptExpanded;
+						}
+						break;
+					case "back":
+						if (state.level === "agents") {
+							state.level = "phases";
+							state.detailScroll = 0;
+							state.promptExpanded = false;
+							break;
+						}
+						return close();
+					case "pageUp":
+					case "pageDown":
+						// Clamped against the detail's real length at render time.
+						state.detailScroll = Math.max(0, state.detailScroll + (key.kind === "pageUp" ? -8 : 8));
+						break;
+					case "nextRun": {
+						const count = manager.list().length;
+						state.runIndex = count ? (state.runIndex + 1) % count : 0;
+						state.level = "phases";
+						state.phaseCursor = 0;
+						state.agentCursor = 0;
+						state.detailScroll = 0;
+						state.promptExpanded = false;
+						break;
+					}
+					case "stop": {
+						const run = snapshots()[state.runIndex];
+						const stopped = run && manager.abort(run.runId, "stopped from viewer");
+						state.notice = stopped ? `stopping ${run.runId}…` : "workflow is not running";
+						break;
+					}
+					case "save":
+						save(snapshots());
+						break;
+				}
+				repaint();
+			},
+			invalidate: () => {
+				cache = undefined;
+			},
+			// Covers every dismissal path that isn't the user pressing esc while
+			// focused (session end, another overlay taking over) — without it the
+			// ticker outlives the component.
+			dispose: () => {
+				clearInterval(ticker);
+			},
+		};
 	});
 }

package/extensions/workflow/records.ts

@@ -0,0 +1,118 @@
+/**
+ * Per-agent run records (pure): folds the RunProgressEvent stream into
+ * AgentRecord[] so the viewer can show each agent's prompt, model, activity,
+ * and outcome. RunHandle owns one store and applies every recorded event;
+ * timestamps are stamped here at apply time (host side — the vm's Date block
+ * does not apply).
+ */
+
+import type { AgentRecord, RunProgressEvent } from "./types.ts";
+
+/** The per-agent members of the event union (the ones records care about). */
+type AgentEvent = Extract<RunProgressEvent, { callIndex: number }>;
+
+function recordKey(callIndex: number, source?: string): string {
+	return `${source ?? ""}#${callIndex}`;
+}
+
+export const ACTIVITY_CAP = 100;
+export const PREVIEW_CAP = 2000;
+
+/** Human-readable preview of an agent's returned value, hard-capped. */
+export function previewValue(value: unknown, cap = PREVIEW_CAP, truncationMarker = "…"): string {
+	let text: string;
+	if (typeof value === "string") {
+		text = value;
+	} else if (value === undefined) {
+		text = "(no value)";
+	} else {
+		try {
+			text = JSON.stringify(value, null, 2);
+		} catch {
+			text = String(value);
+		}
+	}
+	return text.length > cap ? `${text.slice(0, cap)}${truncationMarker}` : text;
+}
+
+export class AgentRecordStore {
+	// Keyed by (source, callIndex): a nested workflow() child restarts its own
+	// callIndex at 0, so callIndex alone would merge its agents into the parent's.
+	private byKey = new Map<string, AgentRecord>();
+	private order: string[] = [];
+
+	constructor(private readonly now: () => number = () => Date.now()) {}
+
+	/** Records in first-seen order (callIndex order for sequential scripts). */
+	list(): AgentRecord[] {
+		return this.order.map((key) => this.byKey.get(key) as AgentRecord);
+	}
+
+	get(callIndex: number, source?: string): AgentRecord | undefined {
+		return this.byKey.get(recordKey(callIndex, source));
+	}
+
+	apply(event: RunProgressEvent): void {
+		switch (event.type) {
+			case "agentStart": {
+				const record = this.ensure(event);
+				record.status = "running";
+				record.startedAt ??= this.now();
+				record.prompt = event.prompt;
+				break;
+			}
+			case "agentUpdate": {
+				const record = this.ensure(event);
+				if (event.model) record.model = event.model;
+				if (event.tool) {
+					record.activity.push(event.tool);
+					record.toolCalls++;
+					if (record.activity.length > ACTIVITY_CAP) record.activity.shift();
+				}
+				break;
+			}
+			case "agentEnd": {
+				const record = this.ensure(event);
+				record.finishedAt = this.now();
+				if (event.prompt !== undefined) record.prompt ??= event.prompt;
+				if (event.tokens) record.tokens = event.tokens;
+				if (event.cost !== undefined) record.cost = event.cost;
+				if (event.preview !== undefined) record.outcome = event.preview;
+				if (event.replayed) {
+					record.status = "replayed";
+				} else if (event.text) {
+					record.status = "failed";
+					record.error = event.text;
+				} else {
+					record.status = "done";
+				}
+				break;
+			}
+			default:
+				break;
+		}
+	}
+
+	private ensure(event: AgentEvent): AgentRecord {
+		const key = recordKey(event.callIndex, event.source);
+		const record = this.byKey.get(key);
+		if (!record) {
+			const created: AgentRecord = {
+				callIndex: event.callIndex,
+				source: event.source,
+				label: event.label ?? `agent ${event.callIndex + 1}`,
+				phase: event.phase,
+				status: "running",
+				activity: [],
+				toolCalls: 0,
+			};
+			this.byKey.set(key, created);
+			this.order.push(key);
+			return created;
+		}
+		// Later events may carry the label/phase a bare agentUpdate lacked.
+		if (event.label) record.label = event.label;
+		if (event.phase && !record.phase) record.phase = event.phase;
+		return record;
+	}
+}