pi-crew 0.9.53 → 0.9.55

package/src/ui/render-diff.ts

@@ -0,0 +1,160 @@
+import * as Diff from "diff";
+import type { CrewTheme } from "./theme-adapter.ts";
+import { asCrewTheme } from "./theme-adapter.ts";
+
+interface ParsedDiffLine {
+	prefix: string;
+	lineNum: string;
+	content: string;
+}
+
+interface DiffLineContent {
+	lineNum: string;
+	content: string;
+}
+
+function parseDiffLine(line: string): ParsedDiffLine | null {
+	const match = line.match(/^([+-\s])(\s*\d*)\s(.*)$/);
+	if (!match) return null;
+	return { prefix: match[1], lineNum: match[2], content: match[3] };
+}
+
+export function replaceTabs(text: string): string {
+	return text.replace(/\t/g, "   ");
+}
+
+/**
+ * Minimum similarity (fraction of unchanged chars) required before applying
+ * word-level intra-line diff highlighting. Below this, the two lines are
+ * considered unrelated and rendered plainly to avoid noisy full-line
+ * inverse-video (e.g. an empty line replaced by a large block of code).
+ */
+const WORD_DIFF_MIN_SIM = 0.15;
+
+/**
+ * Compute the similarity between two strings as the fraction of unchanged
+ * characters relative to the longer of the two strings, using word-level
+ * diff to identify the common (unchanged) parts. Returns a value in [0, 1].
+ */
+function computeSimilarity(oldContent: string, newContent: string): number {
+	const wordDiff = Diff.diffWords(oldContent, newContent);
+	let commonChars = 0;
+	for (const part of wordDiff) {
+		if (!part.removed && !part.added) {
+			commonChars += part.value.length;
+		}
+	}
+	const maxLen = Math.max(oldContent.length, newContent.length);
+	if (maxLen === 0) return 1; // both empty -> identical
+	return commonChars / maxLen;
+}
+
+function renderIntraLineDiff(theme: CrewTheme, oldContent: string, newContent: string): { removedLine: string; addedLine: string } {
+	const wordDiff = Diff.diffWords(oldContent, newContent);
+	let removedLine = "";
+	let addedLine = "";
+	let isFirstRemoved = true;
+	let isFirstAdded = true;
+
+	for (const part of wordDiff) {
+		if (part.removed) {
+			let value = part.value;
+			if (isFirstRemoved) {
+				const leadingWs = value.match(/^(\s*)/)?.[1] ?? "";
+				value = value.slice(leadingWs.length);
+				removedLine += leadingWs;
+				isFirstRemoved = false;
+			}
+			if (value) removedLine += theme.inverse?.(value) ?? value;
+		} else if (part.added) {
+			let value = part.value;
+			if (isFirstAdded) {
+				const leadingWs = value.match(/^(\s*)/)?.[1] ?? "";
+				value = value.slice(leadingWs.length);
+				addedLine += leadingWs;
+				isFirstAdded = false;
+			}
+			if (value) addedLine += theme.inverse?.(value) ?? value;
+		} else {
+			removedLine += part.value;
+			addedLine += part.value;
+		}
+	}
+
+	return { removedLine, addedLine };
+}
+
+export interface RenderDiffOptions {
+	filePath?: string;
+	theme?: unknown;
+}
+
+export function renderDiff(diffText: string, options: RenderDiffOptions = {}): string {
+	const theme = asCrewTheme(options.theme);
+	const lines = diffText.split("\n");
+	const result: string[] = [];
+	let i = 0;
+
+	while (i < lines.length) {
+		const line = lines[i] ?? "";
+		const parsed = parseDiffLine(line);
+		if (!parsed) {
+			result.push(theme.fg("toolDiffContext", line));
+			i++;
+			continue;
+		}
+
+		if (parsed.prefix === "-") {
+			const removedLines: DiffLineContent[] = [];
+			while (i < lines.length) {
+				const nextParsed = parseDiffLine(lines[i] ?? "");
+				if (nextParsed?.prefix !== "-") break;
+				removedLines.push({
+					lineNum: nextParsed.lineNum,
+					content: nextParsed.content,
+				});
+				i++;
+			}
+
+			const addedLines: DiffLineContent[] = [];
+			while (i < lines.length) {
+				const nextParsed = parseDiffLine(lines[i] ?? "");
+				if (nextParsed?.prefix !== "+") break;
+				addedLines.push({
+					lineNum: nextParsed.lineNum,
+					content: nextParsed.content,
+				});
+				i++;
+			}
+
+			if (removedLines.length === 1 && addedLines.length === 1) {
+				const oldContent = replaceTabs(removedLines[0]!.content);
+				const newContent = replaceTabs(addedLines[0]!.content);
+				const similarity = computeSimilarity(oldContent, newContent);
+				if (similarity >= WORD_DIFF_MIN_SIM) {
+					const { removedLine, addedLine } = renderIntraLineDiff(theme, oldContent, newContent);
+					result.push(theme.fg("toolDiffRemoved", `-${removedLines[0]!.lineNum} ${removedLine}`));
+					result.push(theme.fg("toolDiffAdded", `+${addedLines[0]!.lineNum} ${addedLine}`));
+				} else {
+					result.push(theme.fg("toolDiffRemoved", `-${removedLines[0]!.lineNum} ${oldContent}`));
+					result.push(theme.fg("toolDiffAdded", `+${addedLines[0]!.lineNum} ${newContent}`));
+				}
+			} else {
+				for (const removed of removedLines) {
+					result.push(theme.fg("toolDiffRemoved", `-${removed.lineNum} ${replaceTabs(removed.content)}`));
+				}
+				for (const added of addedLines) {
+					result.push(theme.fg("toolDiffAdded", `+${added.lineNum} ${replaceTabs(added.content)}`));
+				}
+			}
+		} else if (parsed.prefix === "+") {
+			result.push(theme.fg("toolDiffAdded", `+${parsed.lineNum} ${replaceTabs(parsed.content)}`));
+			i++;
+		} else {
+			result.push(theme.fg("toolDiffContext", ` ${parsed.lineNum} ${replaceTabs(parsed.content)}`));
+			i++;
+		}
+	}
+
+	return result.join("\n");
+}

package/src/ui/render-scheduler.ts

@@ -0,0 +1,278 @@
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface RenderSchedulerEventBus {
+	on?: (event: string, handler: (payload: unknown) => void) => (() => void) | void;
+}
+
+export interface RenderSchedulerOptions {
+	debounceMs?: number;
+	/**
+	 * Maximum interval (ms) between auto-refreshes when no event arrives.
+	 * Can be a function returning a dynamic interval — useful to tick fast
+	 * while a run is active (e.g., 160ms aligned with spinner) and slow
+	 * down when idle (e.g., 1000ms) without burning CPU.
+	 */
+	fallbackMs?: number | (() => number);
+	events?: string[];
+	onInvalidate?: (payload: unknown) => void;
+	/**
+	 * 1.9: coalesce `onInvalidate` calls per-runId within this window so that
+	 * bursts of `crew.subagent.completed`-style events touching the same run
+	 * trigger a single cache invalidate instead of N. Set to 0 to disable.
+	 */
+	invalidateCoalesceMs?: number;
+	/**
+	 * R1: maximum number of consecutive catch-up renders the fallback loop
+	 * emits while idle (no real external event) before it stops re-arming.
+	 * Prevents a hung run from rendering forever. A real event resets the
+	 * count and re-arms the loop. Defaults to 8.
+	 */
+	maxIdleFallbackRenders?: number;
+}
+
+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",
+];
+
+/** R4: max exponent for flush re-entrancy backoff (delay = debounceMs * 2^exp). */
+const CAP_BACKOFF_MAX_EXP = 5;
+
+/**
+ * Coordinates UI renders with debounce + fallback polling.
+ *
+ * Critical: uses recursive setTimeout instead of setInterval + a rendering
+ * guard (`rendering` / `pendingRender`) so that when render() takes longer
+ * than the fallback interval, callbacks do NOT pile up and storm the event
+ * loop.  Instead, overlapping schedules are collapsed into a single deferred
+ * re-render.
+ */
+export class RenderScheduler {
+	private readonly render: () => void;
+	private readonly onInvalidate?: (payload: unknown) => void;
+	private readonly debounceMs: number;
+	private readonly fallbackProvider: () => number;
+	private readonly fallbackMs: number;
+	private readonly invalidateCoalesceMs: number;
+	private readonly maxIdleFallbackRenders: number;
+	private debounceTimer: ReturnType<typeof setTimeout> | undefined;
+	private fallbackTimer: ReturnType<typeof setTimeout> | undefined;
+	private invalidateTimer: ReturnType<typeof setTimeout> | undefined;
+	/** runId → most recent payload to forward when the coalesce window flushes. */
+	private invalidateBuffer = new Map<string, unknown>();
+	private disposed = false;
+	private lastEventAt = 0;
+	private rendering = false;
+	private pendingRender = false;
+	/** R1: consecutive idle fallback renders since the last real event. */
+	private idleFallbackRenders = 0;
+	/** R4: consecutive re-entrancy cap-hits — drives exponential backoff. */
+	private consecutiveCapHits = 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;
+		const fallback = options.fallbackMs ?? 750;
+		this.fallbackProvider = typeof fallback === "function" ? fallback : () => fallback;
+		this.fallbackMs = typeof fallback === "number" ? fallback : 750;
+		this.invalidateCoalesceMs = options.invalidateCoalesceMs ?? 50;
+		this.maxIdleFallbackRenders = options.maxIdleFallbackRenders ?? 8;
+		for (const event of options.events ?? DEFAULT_EVENTS) this.subscribe(events, event);
+		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
+		this.fallbackTimer.unref();
+	}
+
+	private currentFallbackMs(): number {
+		try {
+			const value = this.fallbackProvider();
+			return Number.isFinite(value) && value > 0 ? value : 750;
+		} catch (error) {
+			logInternalError("render-scheduler.fallbackProvider", error);
+			return 750;
+		}
+	}
+
+	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);
+		}
+	}
+
+	/** Recursive setTimeout — avoids setInterval timer storms. */
+	private fallbackLoop(): void {
+		if (this.disposed) return;
+		const fallbackMs = this.currentFallbackMs();
+		if (Date.now() - this.lastEventAt < fallbackMs) {
+			// A real external event arrived recently — not idle. Keep polling.
+			this.idleFallbackRenders = 0;
+			this.fallbackTimer = setTimeout(() => this.fallbackLoop(), fallbackMs);
+			this.fallbackTimer.unref();
+			return;
+		}
+		// R1: truly idle (no real event for `fallbackMs`). `lastEventAt` is only
+		// advanced by real external events (schedule()), so this idle check stays
+		// honest — unlike the old code which called schedule() here and thereby
+		// reset lastEventAt, self-perpetuating a ~fallbackMs render loop forever.
+		if (this.idleFallbackRenders >= this.maxIdleFallbackRenders) {
+			// Sustained idleness — stop re-arming so a hung run does not render
+			// forever. A subsequent real event (schedule()) re-arms the loop.
+			this.fallbackTimer = undefined;
+			return;
+		}
+		// Emit one catch-up render WITHOUT advancing lastEventAt (no real event).
+		this.armDebouncedRender();
+		this.idleFallbackRenders += 1;
+		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
+		this.fallbackTimer.unref();
+	}
+
+	schedule(payload?: unknown): void {
+		if (this.disposed) return;
+		this.lastEventAt = Date.now();
+		this.idleFallbackRenders = 0;
+		this.consecutiveCapHits = 0;
+		this.invalidate(payload);
+		this.armDebouncedRender();
+		// R1: if the fallback loop stopped itself after a sustained idle period,
+		// a real event means activity resumed — re-arm the safety-net loop.
+		if (!this.fallbackTimer) {
+			this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
+			this.fallbackTimer.unref();
+		}
+	}
+
+	/**
+	 * Arm (or re-arm) the debounce timer that triggers a single flush. Shared by
+	 * real-event schedules, the fallback path, and the re-entrancy cap drain.
+	 * `delay` lets the cap apply exponential backoff (R4) without touching
+	 * `lastEventAt` or `onInvalidate` (those belong to real external events).
+	 */
+	private armDebouncedRender(delay: number = this.debounceMs): void {
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = undefined;
+			this.flush();
+		}, delay);
+		this.debounceTimer.unref();
+	}
+
+	/**
+	 * 1.9: forward `onInvalidate` immediately when the payload has no `runId`
+	 * (we cannot dedup it). When it carries a runId, buffer the latest payload
+	 * per runId and flush on a coalesce timer so high-frequency event bursts
+	 * (`crew.subagent.completed` for parallel tasks) collapse into one
+	 * invalidate per affected run.
+	 */
+	private invalidate(payload: unknown): void {
+		try {
+			const runId =
+				typeof payload === "object" &&
+				payload !== null &&
+				"runId" in payload &&
+				typeof (payload as { runId: unknown }).runId === "string"
+					? (payload as { runId: string }).runId
+					: undefined;
+			if (runId === undefined || this.invalidateCoalesceMs <= 0) {
+				this.onInvalidate?.(payload);
+				return;
+			}
+			this.invalidateBuffer.set(runId, payload);
+			if (!this.invalidateTimer) {
+				this.invalidateTimer = setTimeout(() => this.flushInvalidate(), this.invalidateCoalesceMs);
+				this.invalidateTimer.unref();
+			}
+		} catch (error) {
+			logInternalError("render-scheduler.invalidate", error);
+		}
+	}
+
+	private flushInvalidate(): void {
+		this.invalidateTimer = undefined;
+		if (this.disposed) {
+			this.invalidateBuffer.clear();
+			return;
+		}
+		const buffered = this.invalidateBuffer;
+		this.invalidateBuffer = new Map();
+		for (const payload of buffered.values()) {
+			try {
+				this.onInvalidate?.(payload);
+			} catch (error) {
+				logInternalError("render-scheduler.invalidate.flush", error);
+			}
+		}
+	}
+
+	/**
+	 * Flush a render.  If a render is already in progress the request is
+	 * collapsed: `pendingRender` is set and the caller that holds
+	 * `rendering==true` will loop one more time after finishing.
+	 */
+	flush(): void {
+		if (this.disposed) return;
+		if (this.rendering) {
+			this.pendingRender = true;
+			return;
+		}
+		this.rendering = true;
+		this.pendingRender = false;
+		let iterations = 0;
+		try {
+			do {
+				this.pendingRender = false;
+				this.render();
+				iterations += 1;
+				// Safety valve: 5 re-renders max per flush to prevent infinite loops
+				// if render() itself calls flush() synchronously.
+			} while (this.pendingRender && !this.disposed && iterations < 5);
+		} catch (error) {
+			logInternalError("render-scheduler.render", error);
+		} finally {
+			this.rendering = false;
+			// R4: if we hit the re-entrancy cap with more work pending, drain it —
+			// but with exponential backoff on consecutive cap-hits so a pathological
+			// render() cannot sustain a tight debounceMs render loop. We re-arm via
+			// armDebouncedRender (not schedule()) so lastEventAt / onInvalidate are
+			// not perturbed by a pure re-entrancy drain.
+			if (iterations >= 5 && this.pendingRender && !this.disposed) {
+				this.consecutiveCapHits += 1;
+				const exp = Math.min(this.consecutiveCapHits - 1, CAP_BACKOFF_MAX_EXP);
+				this.armDebouncedRender(this.debounceMs * 2 ** exp);
+			} else {
+				this.consecutiveCapHits = 0;
+			}
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		if (this.fallbackTimer) clearTimeout(this.fallbackTimer);
+		if (this.invalidateTimer) clearTimeout(this.invalidateTimer);
+		this.debounceTimer = undefined;
+		this.fallbackTimer = undefined;
+		this.invalidateTimer = undefined;
+		this.invalidateBuffer.clear();
+		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,182 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+// Lazy-loaded: team-tool.ts pulls in entire runtime chain.
+import type { handleTeamTool as HandleTeamToolFn } from "../extension/team-tool.ts";
+import type { MetricRegistry } from "../observability/metric-registry.ts";
+
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(
+	params: Parameters<typeof HandleTeamToolFn>[0],
+	ctx: Parameters<typeof HandleTeamToolFn>[1],
+): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+		const mod = await import("../extension/team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
+
+import { isToolError, textFromToolResult } from "../extension/tool-result.ts";
+import { readCrewAgents } from "../runtime/crew-agent-records.ts";
+import { exportDiagnostic } from "../runtime/diagnostic-export.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { MailboxDirection, MailboxMessage } from "../state/mailbox.ts";
+import { loadRunManifestById, saveRunTasks } from "../state/state-store.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); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
+		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,
+	options: { registry?: MetricRegistry } = {},
+): Promise<RunActionResult> {
+	try {
+		const exported = await exportDiagnostic(ctx, runId, options);
+		return {
+			ok: true,
+			message: `Diagnostic exported to ${exported.path}`,
+			data: exported.path,
+		};
+	} catch (error) {
+		return err(error);
+	}
+}
+
+/** @internal */
+function defaultNudgeAgentId(ctx: Pick<ExtensionContext, "cwd">, runId: string): string | undefined {
+	const loaded = loadRunManifestById(ctx.cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
+	if (!loaded) return undefined;
+	return readCrewAgents(loaded.manifest).find((agent) => agent.status === "running" || agent.status === "queued")?.taskId;
+}