pi-crew 0.1.32 → 0.1.34

package/src/ui/overlays/mailbox-detail-overlay.ts

@@ -0,0 +1,122 @@
+import { readDeliveryState, readMailbox, type MailboxMessage } from "../../state/mailbox.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { pad, truncate } from "../../utils/visual.ts";
+import { asCrewTheme, type CrewTheme } from "../theme-adapter.ts";
+
+export type MailboxAction =
+	| { type: "ack"; messageId: string }
+	| { type: "nudge"; agentId?: string }
+	| { type: "compose" }
+	| { type: "ackAll" }
+	| { type: "close" };
+
+export class MailboxDetailOverlay {
+	private readonly runId: string;
+	private readonly cwd: string;
+	private readonly done: (action: MailboxAction | undefined) => void;
+	private readonly theme: CrewTheme;
+	private inbox: MailboxMessage[] = [];
+	private outbox: MailboxMessage[] = [];
+	private side: "inbox" | "outbox" = "inbox";
+	private selected = 0;
+	private expanded = false;
+
+	constructor(opts: { runId: string; cwd: string; done: (action: MailboxAction | undefined) => void; theme?: unknown }) {
+		this.runId = opts.runId;
+		this.cwd = opts.cwd;
+		this.done = opts.done;
+		this.theme = asCrewTheme(opts.theme ?? {});
+		this.refresh();
+	}
+
+	private refresh(): void {
+		const loaded = loadRunManifestById(this.cwd, this.runId);
+		if (!loaded) return;
+		const delivery = readDeliveryState(loaded.manifest).messages;
+		const applyDelivery = (message: MailboxMessage): MailboxMessage => ({ ...message, status: delivery[message.id] ?? message.status });
+		const taskIds = loaded.tasks.map((task) => task.id);
+		this.inbox = [...readMailbox(loaded.manifest, "inbox"), ...taskIds.flatMap((taskId) => readMailbox(loaded.manifest, "inbox", taskId))].map(applyDelivery).reverse();
+		this.outbox = [...readMailbox(loaded.manifest, "outbox"), ...taskIds.flatMap((taskId) => readMailbox(loaded.manifest, "outbox", taskId))].map(applyDelivery).reverse();
+		this.selected = Math.min(this.selected, Math.max(0, this.current().length - 1));
+	}
+
+	private current(): MailboxMessage[] {
+		return this.side === "inbox" ? this.inbox : this.outbox;
+	}
+
+	private selectedMessage(): MailboxMessage | undefined {
+		return this.current()[this.selected];
+	}
+
+	invalidate(): void {
+		this.refresh();
+	}
+
+	render(width: number): string[] {
+		this.refresh();
+		const inner = Math.max(40, width - 4);
+		const col = Math.max(18, Math.floor((inner - 3) / 2));
+		const lines = [
+			this.theme.bold(`Mailbox detail · ${this.runId}`),
+			"Tab side · ↑/↓ select · Enter expand · A ack · N nudge · C compose · X ack all · ESC close",
+			`${pad(this.theme.bold("Inbox"), col)} │ ${pad(this.theme.bold("Outbox"), col)}`,
+		];
+		const max = Math.max(this.inbox.length, this.outbox.length, 1);
+		for (let index = 0; index < Math.min(max, 12); index += 1) {
+			lines.push(`${this.row(this.inbox[index], "inbox", index, col)} │ ${this.row(this.outbox[index], "outbox", index, col)}`);
+		}
+		const selected = this.selectedMessage();
+		if (this.expanded && selected) {
+			lines.push("─".repeat(Math.min(inner, 72)));
+			lines.push(`${selected.from} → ${selected.to}${selected.taskId ? ` (${selected.taskId})` : ""} · ${selected.status}`);
+			lines.push(...selected.body.split(/\r?\n/).map((line) => truncate(line, inner)));
+		}
+		if (!this.inbox.length && !this.outbox.length) lines.push("Mailbox is empty.");
+		return lines.map((line) => truncate(line, inner));
+	}
+
+	private row(message: MailboxMessage | undefined, side: "inbox" | "outbox", index: number, width: number): string {
+		if (!message) return pad("", width);
+		const marker = this.side === side && this.selected === index ? "›" : " ";
+		const status = message.status === "acknowledged" ? "✓" : "!";
+		return pad(truncate(`${marker}${status} ${message.from}->${message.to}: ${message.body.replace(/\s+/g, " ")}`, width), width);
+	}
+
+	handleInput(data: string): void {
+		if (data === "\u001b" || data === "q") {
+			this.done({ type: "close" });
+			return;
+		}
+		if (data === "\t") {
+			this.side = this.side === "inbox" ? "outbox" : "inbox";
+			this.selected = Math.min(this.selected, Math.max(0, this.current().length - 1));
+			return;
+		}
+		if (data === "k" || data === "\u001b[A") {
+			this.selected = Math.max(0, this.selected - 1);
+			return;
+		}
+		if (data === "j" || data === "\u001b[B") {
+			this.selected = Math.min(Math.max(0, this.current().length - 1), this.selected + 1);
+			return;
+		}
+		if (data === "\r" || data === "\n") {
+			this.expanded = !this.expanded;
+			return;
+		}
+		if (data === "A") {
+			const message = this.selectedMessage();
+			if (message) this.done({ type: "ack", messageId: message.id });
+			return;
+		}
+		if (data === "N") {
+			this.done({ type: "nudge", agentId: this.selectedMessage()?.taskId });
+			return;
+		}
+		if (data === "C") {
+			this.done({ type: "compose" });
+			return;
+		}
+		if (data === "X") this.done({ type: "ackAll" });
+	}
+}

package/src/ui/pi-ui-compat.ts

@@ -0,0 +1,57 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+export interface WorkingIndicatorOptions {
+	frames?: string[];
+	intervalMs?: number;
+}
+
+type UiContext = Pick<ExtensionContext, "ui">;
+type ExtensionUi = ExtensionContext["ui"];
+type WidgetContent = string[] | ((tui: unknown, theme: unknown) => unknown);
+type WidgetOptions = Parameters<ExtensionUi["setWidget"]>[2];
+type WidgetOptionsWithPersist = WidgetOptions & { persist?: boolean };
+
+type CustomOptions = Parameters<ExtensionUi["custom"]>[1];
+
+type CustomFactory<T> = (
+	tui: unknown,
+	theme: unknown,
+	keybindings: unknown,
+	done: (result: T) => void,
+) => unknown;
+type GenericCustom = <T>(factory: CustomFactory<T>, options?: CustomOptions) => Promise<T>;
+
+function maybeRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+}
+
+export function requestRender(ctx: UiContext): void {
+	requestRenderTarget(ctx.ui);
+}
+
+export function requestRenderTarget(target: unknown): void {
+	const record = maybeRecord(target);
+	const fn = record?.requestRender;
+	if (typeof fn === "function") fn.call(target);
+}
+
+export function setWorkingIndicator(ctx: UiContext, options?: WorkingIndicatorOptions): void {
+	const record = maybeRecord(ctx.ui);
+	const fn = record?.setWorkingIndicator;
+	if (typeof fn === "function") fn.call(ctx.ui, options);
+}
+
+export function setExtensionWidget(ctx: UiContext, key: string, content: WidgetContent | undefined, options?: WidgetOptionsWithPersist): void {
+	const { persist: _persist, ...widgetOptions } = options ?? {};
+	ctx.ui.setWidget(key, content as never, widgetOptions as WidgetOptions);
+}
+
+export function showCustom<T>(ctx: UiContext, factory: CustomFactory<T>, options?: CustomOptions): Promise<T> {
+	const custom = ctx.ui.custom as unknown as GenericCustom;
+	return custom<T>(factory, options);
+}
+
+export function setStatusFallback(ctx: UiContext, key: string, lines: string | readonly string[] | undefined, segment?: string): void {
+	const text = typeof lines === "string" ? lines : lines ? [...lines].join("\n") : undefined;
+	ctx.ui.setStatus(segment ? `${key}:${segment}` : key, text);
+}

package/src/ui/powerbar-publisher.ts

@@ -1,94 +1,128 @@
-import * as fs from "node:fs";
-import { listRecentRuns } from "../extension/run-index.ts";
-import type { CrewUiConfig } from "../config/config.ts";
-import { readCrewAgents } from "../runtime/crew-agent-records.ts";
-import { readJsonFileCoalesced } from "../utils/file-coalescer.ts";
-import type { TeamTaskState, TeamRunManifest } from "../state/types.ts";
-import { aggregateUsage } from "../state/usage.ts";
-import { isDisplayActiveRun } from "../runtime/process-status.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import type { ManifestCache } from "../runtime/manifest-cache.ts";
-
-type EventBus = { emit?: (event: string, data: unknown) => void } | undefined;
-
-const TASK_READ_TTL_MS = 200;
-
-function safeEmit(events: EventBus, event: string, data: unknown): void {
-	try {
-		events?.emit?.(event, data);
-	} catch (error) {
-		logInternalError("powerbar.safeEmit", error, `event=${event}`);
-	}
-}
-
-function readTasks(tasksPath: string): TeamTaskState[] {
-	try {
-		const parse = () => {
-			const parsed = JSON.parse(fs.readFileSync(tasksPath, "utf-8"));
-			return Array.isArray(parsed) ? (parsed as TeamTaskState[]) : [];
-		};
-		return readJsonFileCoalesced(tasksPath, TASK_READ_TTL_MS, parse);
-	} catch (error) {
-		logInternalError("powerbar.readTasks", error, tasksPath);
-		return [];
-	}
-}
-
-export function compactTokens(total: number): string {
-	return total >= 1000 ? `${Math.round(total / 1000)}k` : `${total}`;
-}
-
-export function registerPiCrewPowerbarSegments(events: EventBus, config?: CrewUiConfig): void {
-	if (config?.powerbar === false) return;
-	safeEmit(events, "powerbar:register-segment", { id: "pi-crew-active", label: "pi-crew active agents" });
-	safeEmit(events, "powerbar:register-segment", { id: "pi-crew-progress", label: "pi-crew run progress" });
-}
-
-export function updatePiCrewPowerbar(events: EventBus, cwd: string, config?: CrewUiConfig, manifestCache?: ManifestCache): void {
-	if (config?.powerbar === false) return;
-	const runs = manifestCache ? manifestCache.list(20) : listRecentRuns(cwd, 20);
-	const active = runs.map((run) => {
-		let agents: ReturnType<typeof readCrewAgents> = [];
-		try {
-			agents = readCrewAgents(run);
-		} catch (error) {
-			logInternalError("powerbar.readCrewAgents", error, run.runId);
-		}
-		return { run, agents };
-	}).filter((item) => isDisplayActiveRun(item.run, item.agents));
-	if (!active.length) {
-		safeEmit(events, "powerbar:update", { id: "pi-crew-active" });
-		safeEmit(events, "powerbar:update", { id: "pi-crew-progress" });
-		return;
-	}
-	const agents = active.flatMap((item) => item.agents);
-	const tasks = active.flatMap((item) => readTasks(item.run.tasksPath));
-	const running = agents.filter((agent) => agent.status === "running").length;
-	const waiting = tasks.filter((task) => task.status === "queued").length;
-	const completed = tasks.filter((task) => task.status === "completed").length;
-	const total = Math.max(1, tasks.length || agents.length);
-	const usage = aggregateUsage(tasks);
-	const tokenTotal = usage ? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0) : 0;
-	const model = config?.showModel === false ? undefined : agents.find((agent) => agent.model)?.model?.split("/").at(-1);
-	const tokenText = config?.showTokens === false || !tokenTotal ? undefined : compactTokens(tokenTotal);
-	safeEmit(events, "powerbar:update", {
-		id: "pi-crew-active",
-		icon: "⚙",
-		text: `crew ${running}a/${waiting}w`,
-		suffix: [model, tokenText].filter(Boolean).join(" · ") || undefined,
-		color: running ? "accent" : "warning",
-	});
-	safeEmit(events, "powerbar:update", {
-		id: "pi-crew-progress",
-		text: (active[0]?.run as TeamRunManifest)?.team ?? "crew",
-		bar: Math.round((completed / total) * 100),
-		suffix: `${completed}/${total}${tokenText ? ` · ${tokenText}` : ""}`,
-		color: completed === total ? "success" : "accent",
-		barSegments: 8,
-	});
-}
-
-export function clearPiCrewPowerbar(events: EventBus): void {
-	safeEmit(events, "powerbar:update", { id: "pi-crew-active" });
-	safeEmit(events, "powerbar:update", { id: "pi-crew-progress" });
-}
+import * as fs from "node:fs";
+import { listRecentRuns } from "../extension/run-index.ts";
+import type { CrewUiConfig } from "../config/config.ts";
+import { readCrewAgents } from "../runtime/crew-agent-records.ts";
+import { readJsonFileCoalesced } from "../utils/file-coalescer.ts";
+import type { TeamTaskState, TeamRunManifest } from "../state/types.ts";
+import { aggregateUsage } from "../state/usage.ts";
+import { isDisplayActiveRun } from "../runtime/process-status.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import type { ManifestCache } from "../runtime/manifest-cache.ts";
+import type { RunSnapshotCache, RunUiSnapshot } from "./snapshot-types.ts";
+import { notificationBadge } from "./crew-widget.ts";
+
+type EventBus = { emit?: (event: string, data: unknown) => void; listenerCount?: (event: string) => number } | undefined;
+type StatusContext = { hasUI?: boolean; ui?: { setStatus?: (key: string, text: string | undefined) => void } } | undefined;
+
+const TASK_READ_TTL_MS = 200;
+
+function hasPowerbarConsumer(events: EventBus): boolean {
+	try {
+		return (events?.listenerCount?.("powerbar:register-segment") ?? 0) > 0 || (events?.listenerCount?.("powerbar:update") ?? 0) > 0;
+	} catch {
+		return false;
+	}
+}
+
+function setStatusFallback(ctx: StatusContext, text: string | undefined): void {
+	try {
+		if (ctx?.hasUI) ctx.ui?.setStatus?.("pi-crew", text);
+	} catch (error) {
+		logInternalError("powerbar.statusFallback", error);
+	}
+}
+
+function safeEmit(events: EventBus, event: string, data: unknown): void {
+	try {
+		events?.emit?.(event, data);
+	} catch (error) {
+		logInternalError("powerbar.safeEmit", error, `event=${event}`);
+	}
+}
+
+function readTasks(tasksPath: string): TeamTaskState[] {
+	try {
+		const parse = () => {
+			const parsed = JSON.parse(fs.readFileSync(tasksPath, "utf-8"));
+			return Array.isArray(parsed) ? (parsed as TeamTaskState[]) : [];
+		};
+		return readJsonFileCoalesced(tasksPath, TASK_READ_TTL_MS, parse);
+	} catch (error) {
+		logInternalError("powerbar.readTasks", error, tasksPath);
+		return [];
+	}
+}
+
+export function compactTokens(total: number): string {
+	return total >= 1000 ? `${Math.round(total / 1000)}k` : `${total}`;
+}
+
+export function registerPiCrewPowerbarSegments(events: EventBus, config?: CrewUiConfig): void {
+	if (config?.powerbar === false) return;
+	safeEmit(events, "powerbar:register-segment", { id: "pi-crew-active", label: "pi-crew active agents" });
+	safeEmit(events, "powerbar:register-segment", { id: "pi-crew-progress", label: "pi-crew run progress" });
+}
+
+export function updatePiCrewPowerbar(events: EventBus, cwd: string, config?: CrewUiConfig, manifestCache?: ManifestCache, snapshotCache?: RunSnapshotCache, ctx?: StatusContext, notificationCount = 0): void {
+	if (config?.powerbar === false) return;
+	const useStatusFallback = !hasPowerbarConsumer(events);
+	const runs = manifestCache ? manifestCache.list(20) : listRecentRuns(cwd, 20);
+	const active = runs.map((run) => {
+		let snapshot: RunUiSnapshot | undefined;
+		try {
+			snapshot = snapshotCache?.refreshIfStale(run.runId);
+		} catch (error) {
+			logInternalError("powerbar.snapshot", error, run.runId);
+		}
+		if (snapshot) return { run: snapshot.manifest, agents: snapshot.agents, tasks: snapshot.tasks, snapshot };
+		let agents: ReturnType<typeof readCrewAgents> = [];
+		try {
+			agents = readCrewAgents(run);
+		} catch (error) {
+			logInternalError("powerbar.readCrewAgents", error, run.runId);
+		}
+		return { run, agents, tasks: readTasks(run.tasksPath), snapshot };
+	}).filter((item) => isDisplayActiveRun(item.run, item.agents));
+	if (!active.length) {
+		safeEmit(events, "powerbar:update", { id: "pi-crew-active" });
+		safeEmit(events, "powerbar:update", { id: "pi-crew-progress" });
+		if (useStatusFallback) setStatusFallback(ctx, undefined);
+		return;
+	}
+	const agents = active.flatMap((item) => item.agents);
+	const tasks = active.flatMap((item) => item.tasks);
+	const running = agents.filter((agent) => agent.status === "running").length;
+	const waiting = active.reduce((sum, item) => sum + (item.snapshot?.progress.queued ?? item.tasks.filter((task) => task.status === "queued").length), 0);
+	const completed = active.reduce((sum, item) => sum + (item.snapshot?.progress.completed ?? item.tasks.filter((task) => task.status === "completed").length), 0);
+	const total = Math.max(1, active.reduce((sum, item) => sum + (item.snapshot?.progress.total ?? item.tasks.length), 0) || agents.length);
+	const usage = aggregateUsage(tasks);
+	const snapshotTokens = active.reduce((sum, item) => sum + (item.snapshot ? item.snapshot.usage.tokensIn + item.snapshot.usage.tokensOut : 0), 0);
+	const tokenTotal = usage ? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0) : snapshotTokens;
+	const model = config?.showModel === false ? undefined : agents.find((agent) => agent.model)?.model?.split("/").at(-1);
+	const tokenText = config?.showTokens === false || !tokenTotal ? undefined : compactTokens(tokenTotal);
+	const activeText = `crew ${running}a/${waiting}w${notificationBadge(notificationCount)}`;
+	const activeSuffix = [model, tokenText].filter(Boolean).join(" · ") || undefined;
+	const progressSuffix = `${completed}/${total}${tokenText ? ` · ${tokenText}` : ""}`;
+	safeEmit(events, "powerbar:update", {
+		id: "pi-crew-active",
+		icon: "⚙",
+		text: activeText,
+		suffix: activeSuffix,
+		color: running ? "accent" : "warning",
+	});
+	safeEmit(events, "powerbar:update", {
+		id: "pi-crew-progress",
+		text: (active[0]?.run as TeamRunManifest)?.team ?? "crew",
+		bar: Math.round((completed / total) * 100),
+		suffix: progressSuffix,
+		color: completed === total ? "success" : "accent",
+		barSegments: 8,
+	});
+	if (useStatusFallback) setStatusFallback(ctx, `${activeText}${activeSuffix ? ` · ${activeSuffix}` : ""} · ${progressSuffix}`);
+}
+
+export function clearPiCrewPowerbar(events: EventBus, ctx?: StatusContext): void {
+	safeEmit(events, "powerbar:update", { id: "pi-crew-active" });
+	safeEmit(events, "powerbar:update", { id: "pi-crew-progress" });
+	setStatusFallback(ctx, undefined);
+}

package/src/ui/render-scheduler.ts

@@ -0,0 +1,103 @@
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface RenderSchedulerEventBus {
+	on?: (event: string, handler: (payload: unknown) => void) => (() => void) | void;
+}
+
+export interface RenderSchedulerOptions {
+	debounceMs?: number;
+	fallbackMs?: number;
+	events?: string[];
+	onInvalidate?: (payload: unknown) => void;
+}
+
+const DEFAULT_EVENTS = [
+	"crew.run.created",
+	"crew.run.completed",
+	"crew.run.failed",
+	"crew.run.cancelled",
+	"crew.subagent.completed",
+	"crew.subagent.failed",
+	"crew.mailbox.updated",
+	"crew.mailbox.message",
+];
+
+export class RenderScheduler {
+	private readonly render: () => void;
+	private readonly onInvalidate?: (payload: unknown) => void;
+	private readonly debounceMs: number;
+	private readonly fallbackMs: number;
+	private debounceTimer: ReturnType<typeof setTimeout> | undefined;
+	private fallbackTimer: ReturnType<typeof setInterval> | undefined;
+	private disposed = false;
+	private lastEventAt = 0;
+	private readonly unsubs: Array<() => void> = [];
+
+	constructor(events: RenderSchedulerEventBus | undefined, render: () => void, options: RenderSchedulerOptions = {}) {
+		this.render = render;
+		this.onInvalidate = options.onInvalidate;
+		this.debounceMs = options.debounceMs ?? 75;
+		this.fallbackMs = options.fallbackMs ?? 750;
+		for (const event of options.events ?? DEFAULT_EVENTS) this.subscribe(events, event);
+		this.fallbackTimer = setInterval(() => this.fallback(), this.fallbackMs);
+		this.fallbackTimer.unref?.();
+	}
+
+	private subscribe(events: RenderSchedulerEventBus | undefined, event: string): void {
+		if (!events?.on) return;
+		const handler = (payload: unknown): void => this.schedule(payload);
+		try {
+			const unsub = events.on(event, handler);
+			if (typeof unsub === "function") this.unsubs.push(unsub);
+		} catch (error) {
+			logInternalError("render-scheduler.subscribe", error, event);
+		}
+	}
+
+	private fallback(): void {
+		if (this.disposed) return;
+		if (Date.now() - this.lastEventAt < this.fallbackMs) return;
+		this.flush();
+	}
+
+	schedule(payload?: unknown): void {
+		if (this.disposed) return;
+		this.lastEventAt = Date.now();
+		try {
+			this.onInvalidate?.(payload);
+		} catch (error) {
+			logInternalError("render-scheduler.invalidate", error);
+		}
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = undefined;
+			this.flush();
+		}, this.debounceMs);
+		this.debounceTimer.unref?.();
+	}
+
+	flush(): void {
+		if (this.disposed) return;
+		try {
+			this.render();
+		} catch (error) {
+			logInternalError("render-scheduler.render", error);
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		if (this.fallbackTimer) clearInterval(this.fallbackTimer);
+		this.debounceTimer = undefined;
+		this.fallbackTimer = undefined;
+		for (const unsub of this.unsubs.splice(0)) {
+			try {
+				unsub();
+			} catch (error) {
+				logInternalError("render-scheduler.unsubscribe", error);
+			}
+		}
+	}
+}

package/src/ui/run-action-dispatcher.ts

@@ -0,0 +1,107 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { handleTeamTool } from "../extension/team-tool.ts";
+import { isToolError, textFromToolResult } from "../extension/tool-result.ts";
+import { loadRunManifestById, saveRunTasks } from "../state/state-store.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { readCrewAgents } from "../runtime/crew-agent-records.ts";
+import { exportDiagnostic } from "../runtime/diagnostic-export.ts";
+import type { MailboxDirection, MailboxMessage } from "../state/mailbox.ts";
+
+export interface RunActionResult {
+	ok: boolean;
+	message: string;
+	data?: unknown;
+}
+
+function okFromTool(result: Awaited<ReturnType<typeof handleTeamTool>>): RunActionResult {
+	return { ok: !isToolError(result), message: textFromToolResult(result), data: result };
+}
+
+function err(error: unknown): RunActionResult {
+	return { ok: false, message: error instanceof Error ? error.message : String(error) };
+}
+
+async function dispatchApi(ctx: ExtensionContext, runId: string, config: Record<string, unknown>): Promise<RunActionResult> {
+	try {
+		return okFromTool(await handleTeamTool({ action: "api", runId, config }, ctx));
+	} catch (error) {
+		return err(error);
+	}
+}
+
+function parseMailboxMessages(text: string): MailboxMessage[] {
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((item): item is MailboxMessage => Boolean(item) && typeof item === "object" && !Array.isArray(item) && typeof (item as { id?: unknown }).id === "string");
+	} catch {
+		return [];
+	}
+}
+
+export function dispatchMailboxAck(ctx: ExtensionContext, runId: string, messageId: string): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "ack-message", messageId });
+}
+
+export function dispatchMailboxNudge(ctx: ExtensionContext, runId: string, agentId: string, message: string): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "nudge-agent", agentId, message });
+}
+
+export function dispatchMailboxCompose(ctx: ExtensionContext, runId: string, payload: { from: string; to: string; body: string; taskId?: string; direction: MailboxDirection }): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "send-message", ...payload });
+}
+
+export async function dispatchMailboxAckAll(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	const listed = await dispatchApi(ctx, runId, { operation: "read-mailbox", direction: "inbox" });
+	if (!listed.ok) return listed;
+	const messages = parseMailboxMessages(listed.message).filter((message) => message.status !== "acknowledged");
+	let count = 0;
+	for (const message of messages) {
+		const acked = await dispatchMailboxAck(ctx, runId, message.id);
+		if (!acked.ok) return { ok: false, message: `Acknowledged ${count}/${messages.length}; failed ${message.id}: ${acked.message}` };
+		count += 1;
+	}
+	return { ok: true, message: `Acknowledged ${count} messages.`, data: { count } };
+}
+
+export function dispatchHealthRecovery(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "foreground-interrupt", reason: "operator health recovery" });
+}
+
+export async function dispatchKillStaleWorkers(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	try {
+		const loaded = loadRunManifestById(ctx.cwd, runId);
+		if (!loaded) return { ok: false, message: `Run '${runId}' not found.` };
+		const currentMs = Date.now();
+		const staleMs = 60_000;
+		const now = new Date(currentMs).toISOString();
+		let count = 0;
+		const tasks = loaded.tasks.map((task) => {
+			if ((task.status !== "running" && task.status !== "queued") || !task.heartbeat || task.heartbeat.alive === false) return task;
+			const lastSeenMs = Date.parse(task.heartbeat.lastSeenAt);
+			if (!Number.isFinite(lastSeenMs) || currentMs - lastSeenMs <= staleMs) return task;
+			count += 1;
+			return { ...task, heartbeat: { ...task.heartbeat, alive: false, lastSeenAt: now } };
+		});
+		saveRunTasks(loaded.manifest, tasks);
+		appendEvent(loaded.manifest.eventsPath, { type: "worker.kill_stale", runId, message: `Marked ${count} stale worker heartbeat(s) dead.`, data: { count } });
+		return { ok: true, message: `Marked ${count} stale worker heartbeat(s) dead.`, data: { count } };
+	} catch (error) {
+		return err(error);
+	}
+}
+
+export async function dispatchDiagnosticExport(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	try {
+		const exported = await exportDiagnostic(ctx, runId);
+		return { ok: true, message: `Diagnostic exported to ${exported.path}`, data: exported.path };
+	} catch (error) {
+		return err(error);
+	}
+}
+
+export function defaultNudgeAgentId(ctx: Pick<ExtensionContext, "cwd">, runId: string): string | undefined {
+	const loaded = loadRunManifestById(ctx.cwd, runId);
+	if (!loaded) return undefined;
+	return readCrewAgents(loaded.manifest).find((agent) => agent.status === "running" || agent.status === "queued")?.taskId;
+}