pi-crew 0.9.53 → 0.9.55

package/src/extension/registration/foreground-run-controller.ts

@@ -0,0 +1,238 @@
+/**
+ * Foreground run controller for pi-crew.
+ *
+ * Owns the three helpers consumed by the team-tool / subagent-tools /
+ * team-commands modules:
+ *   • `startForegroundRun` — spawn a foreground team run with watchdog,
+ *     abort signal, and completion-handling (status notification + widget
+ *     refresh + crew.run.* event emission).
+ *   • `abortForegroundRun` — abort a foreground team run by runId.
+ *   • `openLiveSidebar`     — open the per-run live sidebar UI overlay.
+ *
+ * These three are conceptually one unit (all manipulate the same
+ * foreground-team-run controllers + live sidebar state), so they share
+ * a single file.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { loadRunManifestById, updateRunStatus } from "../../state/state-store.ts";
+import { setWorkingIndicator } from "../../ui/pi-ui-compat.ts";
+import { requestPowerbarUpdate } from "../../ui/powerbar-publisher.ts";
+import { updateCrewWidget } from "../../ui/widget/index.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/**
+ * Install the foreground-run controller helpers into the registration
+ * context. Re-call safe — each call rebinds `ctx.startForegroundRun`,
+ * `ctx.abortForegroundRun`, and `ctx.openLiveSidebar` to fresh closures
+ * (the underlying state lives on `ctx`).
+ */
+export function installForegroundRunController(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	ctx.openLiveSidebar = (extCtx, runId) => {
+		void openLiveSidebarImpl(pi, ctx, extCtx, runId);
+	};
+	ctx.startForegroundRun = (extCtx, runner, runId) => startForegroundRunImpl(pi, ctx, extCtx, runner, runId);
+	ctx.abortForegroundRun = (runId) => {
+		const controller = ctx.foregroundTeamRunControllers.get(runId);
+		if (!controller) return false;
+		controller.abort();
+		return true;
+	};
+}
+
+/**
+ * Open the live sidebar for a specific run.
+ *
+ * Defers the actual install to registration/ui.ts via a lazy dynamic
+ * import — only invoked when a sidebar is actually requested, never at
+ * module load.
+ */
+async function openLiveSidebarImpl(
+	pi: ExtensionAPI,
+	ctx: RegistrationContext,
+	extensionCtx: ExtensionContext,
+	runId: string,
+): Promise<void> {
+	// LAZY: registration/ui pulls in transcript-viewer + heavy UI modules.
+	const uiModule = await import("./ui.ts");
+	await uiModule.installLiveSidebar(extensionCtx, runId, ctx.uiState, {
+		pi,
+		widgetState: ctx.widgetState,
+		getManifestCache: ctx.getManifestCache,
+		getRunSnapshotCache: ctx.getRunSnapshotCache,
+		isCleanedUp: () => ctx.cleanedUp,
+		getCurrentCtx: () => ctx.currentCtx,
+	});
+}
+
+/**
+ * Spawn a foreground team run.
+ *
+ * The runner executes on the next macrotask (`setImmediate`) so this
+ * function returns synchronously to Pi. The runner receives an AbortSignal
+ * that fires when:
+ *   • `abortForegroundRun(runId)` is called (e.g., from a tool cancel),
+ *   • `cleanupRuntime()` fires (session shutdown with reason=quit/reload).
+ *
+ * A foreground-watchdog is started per runId to surface hung runs to the
+ * assistant. The .finally block handles: abort propagation, working-message
+ * clearing, status notification, run-completed session entry, and crew.run.*
+ * event emission.
+ */
+function startForegroundRunImpl(
+	pi: ExtensionAPI,
+	ctx: RegistrationContext,
+	extensionCtx: ExtensionContext,
+	runner: (signal?: AbortSignal) => Promise<void>,
+	runId?: string,
+): void {
+	const ownerGeneration = ctx.captureSessionGeneration();
+	const controller = new AbortController();
+	const key = runId ?? Symbol();
+	ctx.foregroundTeamRunControllers.set(key, controller);
+	if (extensionCtx.hasUI) {
+		setWorkingIndicator(extensionCtx, {
+			frames: ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"],
+			intervalMs: 80,
+		});
+		extensionCtx.ui.setWorkingMessage(runId ? `pi-crew foreground run ${runId}...` : "pi-crew foreground run...");
+	}
+	if (runId) {
+		void import("../../runtime/foreground-watchdog.ts")
+			.then(({ startForegroundWatchdog }) => {
+				startForegroundWatchdog({ pi, cwd: extensionCtx.cwd, runId });
+			})
+			.catch((error) => {
+				logInternalError("register.foreground-watchdog-import", error);
+			});
+	}
+	setImmediate(() => {
+		void runner(controller.signal)
+			.catch((error) => {
+				const message = error instanceof Error ? error.message : String(error);
+				if (runId) {
+					try {
+						const loaded = loadRunManifestById(extensionCtx.cwd, runId);
+						if (
+							loaded &&
+							loaded.manifest.status !== "completed" &&
+							loaded.manifest.status !== "failed" &&
+							loaded.manifest.status !== "cancelled" &&
+							loaded.manifest.status !== "blocked"
+						)
+							updateRunStatus(loaded.manifest, "failed", message);
+					} catch (statusError) {
+						logInternalError("register.foreground-run-failure", statusError, `runId=${runId}`);
+					}
+				}
+				if (ctx.isContextCurrent(extensionCtx, ownerGeneration)) {
+					extensionCtx.ui.notify(`pi-crew foreground run failed: ${message}`, "error");
+				} else {
+					logInternalError("register.foreground-run-failure", error, `runId=${runId} context disposed`);
+				}
+			})
+			.finally(() => {
+				ctx.foregroundTeamRunControllers.delete(key);
+				if (runId) {
+					void import("../../runtime/foreground-watchdog.ts")
+						.then(({ stopWatchdog }) => {
+							stopWatchdog(runId);
+						})
+						.catch((error) => logInternalError("register.foreground-watchdog", error, `runId=${runId}`));
+				}
+				const ownerCurrent = ctx.isContextCurrent(extensionCtx, ownerGeneration);
+				if (extensionCtx.hasUI) {
+					try {
+						setWorkingIndicator(extensionCtx);
+						extensionCtx.ui.setWorkingMessage();
+					} catch {
+						/* ignore */
+					}
+				}
+				if (ownerCurrent && runId) {
+					const loaded = loadRunManifestById(extensionCtx.cwd, runId);
+					const status = loaded?.manifest.status ?? "finished";
+					const level = status === "failed" || status === "blocked" ? "error" : status === "cancelled" ? "warning" : "info";
+					extensionCtx.ui.notify(
+						`pi-crew run ${runId} ${status}. Use /team-summary ${runId} or /team-status ${runId}.`,
+						level as "info" | "warning" | "error",
+					);
+					pi.appendEntry("crew:run-completed", {
+						runId,
+						team: loaded?.manifest.team,
+						workflow: loaded?.manifest.workflow,
+						goal: loaded?.manifest.goal,
+						status,
+						taskCount: loaded?.tasks.length,
+						durationMs: loaded?.manifest.createdAt ? Date.now() - new Date(loaded.manifest.createdAt).getTime() : 0,
+						timestamp: Date.now(),
+					});
+					const eventType =
+						status === "completed"
+							? "crew.run.completed"
+							: status === "failed" || status === "blocked"
+								? "crew.run.failed"
+								: status === "cancelled"
+									? "crew.run.cancelled"
+									: undefined;
+					if (eventType) {
+						pi.events?.emit?.(eventType, {
+							runId,
+							team: loaded?.manifest.team,
+							workflow: loaded?.manifest.workflow,
+							status,
+							taskCount: loaded?.tasks.length,
+							goal: loaded?.manifest.goal,
+							durationMs: loaded?.manifest.createdAt ? Date.now() - new Date(loaded.manifest.createdAt).getTime() : 0,
+						});
+					}
+
+					// Emit per-task events so task-level metrics (crew.task.count,
+					// crew.task.duration_ms, crew.task.tokens_total) record actual values.
+					const terminalTaskStatuses = new Set(["completed", "failed", "needs_attention"]);
+					for (const task of loaded?.tasks ?? []) {
+						if (!terminalTaskStatuses.has(task.status)) continue;
+						const taskEventType =
+							task.status === "completed"
+								? "crew.task.completed"
+								: task.status === "failed"
+									? "crew.task.failed"
+									: "crew.task.needs_attention";
+						pi.events?.emit?.(taskEventType, {
+							runId,
+							team: loaded?.manifest.team,
+							workflow: loaded?.manifest.workflow,
+							taskId: task.id,
+							taskCount: loaded?.tasks.length,
+							role: task.role,
+							durationMs:
+								task.startedAt && task.finishedAt
+									? new Date(task.finishedAt).getTime() - new Date(task.startedAt).getTime()
+									: 0,
+							tokens: (task.usage?.input ?? 0) + (task.usage?.output ?? 0),
+						});
+					}
+				}
+				if (ownerCurrent && ctx.currentCtx) {
+					const config = loadConfig(ctx.currentCtx.cwd).config.ui;
+					updateCrewWidget(
+						ctx.currentCtx,
+						ctx.widgetState,
+						config,
+						ctx.getManifestCache(ctx.currentCtx.cwd),
+						ctx.getRunSnapshotCache(ctx.currentCtx.cwd),
+					);
+					requestPowerbarUpdate(
+						pi.events,
+						ctx.currentCtx.cwd,
+						config,
+						ctx.getManifestCache(ctx.currentCtx.cwd),
+						ctx.getRunSnapshotCache(ctx.currentCtx.cwd),
+						ctx.currentCtx,
+						ctx.widgetState.notificationCount ?? 0,
+					);
+				}
+			});
+	});
+}

package/src/extension/registration/hook-registration.ts

@@ -0,0 +1,119 @@
+/**
+ * Generic event-hook installer for pi-crew.
+ *
+ * Owns the non-lifecycle `pi.on(...)` subscribers:
+ *   • `tool_call`     — destructive-team-action permission gate.
+ *   • `tool_result`   — per-write validation (catches malformed config at
+ *                       write time, not at next load).
+ *   • `resources_discover` — injects pi-crew skill paths.
+ *
+ * Session-lifecycle hooks (`session_start`, `session_shutdown`,
+ * `session_before_switch`) live in `lifecycle-handlers.ts` because they
+ * are heavy and own the deferred-cleanup + scheduler + render-loop setup.
+ *
+ * Compaction-guard hooks live in `compaction-guard.ts` because they were
+ * already extracted; this file does NOT re-register them.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { asRecord, loadConfig } from "../../config/config.ts";
+import { buildValidationBlocker, extractPathFromInput, validateWrittenFile } from "../../runtime/per-write-validator.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { shouldBlockDestructiveTeamAction } from "../team-tool/destructive-gate.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/**
+ * Register all non-lifecycle event hooks on the ExtensionAPI.
+ *
+ * Safe to call once during `registerPiTeams`. Does not stack idempotency
+ * guards — these hooks are intentionally re-registered on reload (the
+ * orchestrator's `previousRuntimeCleanup` handles cleanup of derived state).
+ */
+export function installPiHooks(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	installResourcesDiscoverHook(pi, ctx);
+	installToolCallHook(pi, ctx);
+	installToolResultHook(pi, ctx);
+}
+
+/**
+ * Phase 11a: Dynamic resource discovery — inject pi-crew skill paths.
+ *
+ * Older Pi versions without `resources_discover` are tolerated (try/catch
+ * around pi.on; missing support is a no-op).
+ */
+function installResourcesDiscoverHook(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	try {
+		pi.on("resources_discover", () => {
+			const sessionCwd = ctx.currentCtx?.cwd ?? process.cwd();
+			const skillDir = path.resolve(sessionCwd, "skills");
+			const extSkillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+			const paths: string[] = [];
+			if (fs.existsSync(extSkillDir)) paths.push(extSkillDir);
+			if (skillDir !== extSkillDir && fs.existsSync(skillDir)) {
+				// Validate skillDir is within sessionCwd to prevent path traversal
+				try {
+					resolveRealContainedPath(sessionCwd, "skills");
+					paths.push(skillDir);
+				} catch {
+					// skillDir outside sessionCwd boundary — skip
+				}
+			}
+			return paths.length > 0 ? { skillPaths: paths } : {};
+		});
+	} catch {
+		/* older Pi without resources_discover */
+	}
+}
+
+/**
+ * Phase 1.4: Permission gate for destructive team actions.
+ *
+ * AGENTS.md requires `confirm: true` for management deletes. We enforce it
+ * at the tool_call boundary so the user gets a clear error rather than
+ * executing a destructive action silently.
+ */
+function installToolCallHook(_pi: ExtensionAPI, _ctx: RegistrationContext): void {
+	_pi.on("tool_call", async (event) => {
+		if (event.toolName !== "team") return;
+		const rawInput = event.input;
+		if (!rawInput || typeof rawInput !== "object") return;
+		const input = asRecord(rawInput);
+		if (!input) return;
+		const action = typeof input.action === "string" ? input.action : undefined;
+		const reason = shouldBlockDestructiveTeamAction(action, input);
+		if (!reason) return;
+		return {
+			block: true as const,
+			reason,
+		};
+	});
+}
+
+/**
+ * T5 (v0.8.5): per-write validation. On write/edit, run a zero-cost
+ * SYNCHRONOUS validator (v1: JSON.parse) and append a 🔴 blocker to the
+ * tool result on failure — catches malformed config the moment it's
+ * written, not at the next load. Latency-safe by construction: no process
+ * spawn, one disk read ONLY for validated extensions, dedup'd by content.
+ * Toggle via runtime.reliability.perWriteValidation (default true).
+ * Process-spawning validators (.js/.sh/.py) are a future opt-in.
+ */
+function installToolResultHook(_pi: ExtensionAPI, _ctx: RegistrationContext): void {
+	_pi.on("tool_result", (event, ctx) => {
+		try {
+			if (event.toolName !== "write" && event.toolName !== "edit") return;
+			if (loadConfig(ctx.cwd).config.reliability?.perWriteValidation === false) return;
+			const filePath = extractPathFromInput(event.input);
+			if (!filePath) return;
+			const result = validateWrittenFile(filePath);
+			if (!result || result.ok) return;
+			return {
+				content: [...event.content, buildValidationBlocker(filePath, result.error ?? "validation failed")],
+			};
+		} catch {
+			// best-effort: never break a tool result
+		}
+	});
+}

package/src/extension/registration/lazy-configurers.ts

@@ -0,0 +1,124 @@
+/**
+ * Lazy lifecycle/observability configurers for pi-crew.
+ *
+ * These three small functions wire up the heavy runtime subsystems on
+ * the first session_start. They are kept as LAZY dynamic imports because:
+ *   • `./registration/lifecycle.ts` pulls in notification-router + sink
+ *     (~10 KB + heavy deps),
+ *   • `./registration/observability.ts` pulls in HeartbeatWatcher +
+ *     metric stack (~12 KB + heavy deps).
+ *
+ * Pre-loading them at register-time would force every cold start of
+ * pi-crew to pay the cost even if the user never opens a session.
+ *
+ * The orchestrator (`register.ts`) installs these via
+ * `installLazyConfigurers`, which binds them as `ctx.configureNotifications`,
+ * `ctx.configureObservability`, `ctx.configureDeliveryCoordinator`. The
+ * session_start handler invokes them via the context — see
+ * `lifecycle-handlers.ts`.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { reconcileAllStaleRuns } from "../../runtime/crash-recovery.ts";
+import { appendDeadletter } from "../../runtime/deadletter.ts";
+import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs } from "../../runtime/pi-args.ts";
+import { reconcileOrphanedTempWorkspaces } from "../../runtime/stale-reconciler.ts";
+import { requestPowerbarUpdate } from "../../ui/powerbar-publisher.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+import { sendAgentWakeUp, sendFollowUp } from "./subagent-helpers.ts";
+
+/**
+ * Bind the three lazy configurers onto the registration context. After
+ * this call:
+ *   • `ctx.configureNotifications(ctx)` fires the registration/lifecycle
+ *     install with the bound deps bag.
+ *   • `ctx.configureObservability(ctx)` fires the registration/observability
+ *     install (metric registry, OTLP exporter, heartbeat watcher).
+ *   • `ctx.configureDeliveryCoordinator()` wires the delivery coordinator
+ *     + overflow tracker (no dynamic import — already loaded by the
+ *     registration/lifecycle module).
+ */
+export function installLazyConfigurers(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	ctx.configureNotifications = (extCtx: ExtensionContext): void => {
+		void configureNotificationsImpl(pi, ctx, extCtx);
+	};
+	ctx.configureObservability = (extCtx: ExtensionContext): void => {
+		void configureObservabilityImpl(pi, ctx, extCtx);
+	};
+	ctx.configureDeliveryCoordinator = (): void => {
+		void configureDeliveryCoordinatorImpl(pi, ctx);
+	};
+}
+
+/**
+ * Lazy-load registration/lifecycle.ts and wire its notifications system.
+ *
+ * The deps bag is built once-per-call (cheap — just object literals) so
+ * every session_start cycle gets a fresh closure that reads the latest
+ * `ctx.currentCtx` and caches.
+ */
+async function configureNotificationsImpl(pi: ExtensionAPI, ctx: RegistrationContext, extCtx: ExtensionContext): Promise<void> {
+	try {
+		// LAZY: registration/lifecycle is heavy (notification-router + sink)
+		const lifecycleModule = await import("./lifecycle.ts");
+		await lifecycleModule.configureNotifications(extCtx, ctx.lifecycleState, {
+			pi,
+			widgetState: ctx.widgetState,
+			getCurrentCtx: () => ctx.currentCtx,
+			getManifestCache: ctx.getManifestCache,
+			getRunSnapshotCache: ctx.getRunSnapshotCache,
+			requestPowerbarUpdate,
+		});
+	} catch (error) {
+		logInternalError("register.configureNotifications", error);
+	}
+}
+
+/**
+ * Lazy-load registration/observability.ts and wire its metric stack.
+ *
+ * In addition to the metric registry / OTLP exporter, this is where the
+ * stale-reconcile and orphan-temp-dir timers are installed — see
+ * registration/observability.ts for details.
+ */
+async function configureObservabilityImpl(pi: ExtensionAPI, ctx: RegistrationContext, extCtx: ExtensionContext): Promise<void> {
+	try {
+		// LAZY: registration/observability is heavy (HeartbeatWatcher + metric stack)
+		const observabilityModule = await import("./observability.ts");
+		await observabilityModule.configureObservability(extCtx, ctx.observabilityState, {
+			pi,
+			getManifestCache: ctx.getManifestCache,
+			notifyOperator: ctx.notifyOperator,
+			isCleanedUp: () => ctx.cleanedUp,
+			reconcileStaleRuns: (cwd, cache) => reconcileAllStaleRuns(cwd, cache),
+			reconcileOrphanedTempWorkspaces: (now, opts) => reconcileOrphanedTempWorkspaces(now, opts),
+			cleanupOrphanTempDirs,
+			cleanupLegacyOrphanTempDirs,
+			appendDeadletter: (manifest, entry) => appendDeadletter(manifest, entry as Parameters<typeof appendDeadletter>[1]),
+			importCrashRecovery: ctx.importCrashRecovery,
+		});
+	} catch (error) {
+		logInternalError("register.configureObservability", error);
+	}
+}
+
+/**
+ * Wire delivery coordinator + overflow tracker. Uses the
+ * registration/lifecycle module's configureDeliveryCoordinator helper.
+ * No dynamic import needed — lifecycle is already loaded by configureNotifications.
+ */
+async function configureDeliveryCoordinatorImpl(pi: ExtensionAPI, ctx: RegistrationContext): Promise<void> {
+	try {
+		// LAZY: lifecycle.ts may not be loaded yet if configureNotifications hasn't fired.
+		const lifecycleModule = await import("./lifecycle.ts");
+		await lifecycleModule.configureDeliveryCoordinator(ctx.lifecycleState, {
+			pi,
+			observabilityState: ctx.observabilityState,
+			notifyOperator: ctx.notifyOperator,
+			sendFollowUp,
+			sendAgentWakeUp,
+		});
+	} catch (error) {
+		logInternalError("register.configureDeliveryCoordinator", error);
+	}
+}