pi-crew 0.9.53 → 0.9.55

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

@@ -0,0 +1,50 @@
+/**
+ * Tool registration installer for pi-crew.
+ *
+ * Single entry point that wires every `pi.registerTool(...)` call site
+ * in the extension. Today that means two heavy tools:
+ *   • `team` — the multi-agent orchestration tool (team-tool.ts).
+ *   • subagent tools — agent spawn tool + result-join helpers
+ *     (subagent-tools.ts).
+ *
+ * The actual tool handlers live in `registration/team-tool.ts` and
+ * `registration/subagent-tools.ts` (already extracted); this file is
+ * the orchestrator-level wrapper that calls them with the right deps.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RegistrationContext } from "./registration-types.ts";
+import { registerSubagentTools } from "./subagent-tools.ts";
+import { registerTeamTool } from "./team-tool.ts";
+
+/**
+ * Register all pi-crew tools on the ExtensionAPI.
+ *
+ * Pulls every dependency the underlying tools need off `ctx`. The
+ * orchestrator guarantees those fields are populated before this call
+ * (see registerPiTeams in ../register.ts).
+ */
+export function registerPiTools(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	registerTeamTool(pi, {
+		foregroundControllers: ctx.foregroundControllers,
+		startForegroundRun: ctx.startForegroundRun,
+		abortForegroundRun: ctx.abortForegroundRun,
+		openLiveSidebar: ctx.openLiveSidebar,
+		getManifestCache: ctx.getManifestCache,
+		getRunSnapshotCache: ctx.getRunSnapshotCache,
+		getMetricRegistry: () => ctx.observabilityState.metricRegistry,
+		widgetState: ctx.widgetState,
+		onJsonEvent: (taskId, runId, event) => {
+			const record = event as Record<string, unknown>;
+			const eventType = typeof record.type === "string" ? record.type : undefined;
+			if (eventType) ctx.lifecycleState.overflowTracker?.feedEvent(taskId, runId, eventType);
+		},
+	});
+	registerSubagentTools(pi, ctx.subagentManager, {
+		ownerSessionGeneration: ctx.captureSessionGeneration,
+		// Subagent options only type-check against `unknown` for ctx; cast
+		// back to ExtensionContext since the subagent tool re-validates.
+		startForegroundRun: (subCtx, runner, runId) =>
+			ctx.startForegroundRun(subCtx as Parameters<typeof ctx.startForegroundRun>[0], runner, runId),
+		batchBarrier: ctx.batchBarrier,
+	});
+}

package/src/extension/registration/ui.ts

@@ -0,0 +1,172 @@
+/**
+ * UI installer (H3 + L2 — Phase 4 of cleanup plan).
+ *
+ * Owns the dashboard / sidebar / powerbar overlay logic that is gated on
+ * the user actually opening the dashboard (autoOpenDashboard flag) or a
+ * foreground run starting.
+ *
+ * Extracted from src/extension/register.ts. State holder is `UiState`;
+ * installer is `installLiveSidebar(ctx, runId, state, deps)`.
+ *
+ * Lazy by construction: the LiveRunSidebar class (and its transcript-viewer
+ * dependency tree) is only loaded when the user opens a sidebar overlay.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { DEFAULT_UI } from "../../config/defaults.ts";
+import type { LiveRunSidebar as LiveRunSidebarType } from "../../ui/live-run-sidebar.ts";
+import { requestRender, setExtensionWidget, showCustom } from "../../ui/pi-ui-compat.ts";
+import {
+	clearPiCrewPowerbar,
+	registerPiCrewPowerbarSegments,
+	requestPowerbarUpdate,
+	resetPowerbarDedupState,
+	updatePiCrewPowerbar,
+} from "../../ui/powerbar-publisher.ts";
+import type { CrewWidgetState } from "../../ui/widget/index.ts";
+import { stopCrewWidget, updateCrewWidget } from "../../ui/widget/index.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+
+/** Cached live-run-sidebar constructor (lazy-loaded on first overlay open). */
+let _cachedLiveRunSidebar: typeof LiveRunSidebarType | undefined;
+async function importLiveRunSidebar(): Promise<typeof LiveRunSidebarType> {
+	if (!_cachedLiveRunSidebar) {
+		// LAZY: defer LiveRunSidebar import until the user opens a sidebar overlay.
+		const mod = await import("../../ui/live-run-sidebar.ts");
+		_cachedLiveRunSidebar = mod.LiveRunSidebar;
+	}
+	return _cachedLiveRunSidebar;
+}
+
+/** Mutable state owned by register.ts. */
+export interface UiState {
+	liveSidebarRunId: string | undefined;
+	dashboardOpened: boolean;
+	/** True while the full RunDashboard overlay (/team-dashboard) is open.
+	 * Checked by the global renderTick to skip crew-widget updates while the
+	 * dashboard obscures the widget (mirrors the liveSidebarRunId gate). */
+	dashboardOpen?: boolean;
+}
+
+/** Dependencies passed in by register.ts. */
+export interface UiDeps {
+	pi: ExtensionAPI;
+	widgetState: CrewWidgetState;
+	getManifestCache: (cwd: string) => ReturnType<typeof import("../../runtime/manifest-cache.ts").createManifestCache>;
+	getRunSnapshotCache: (cwd: string) => ReturnType<typeof import("../../ui/run-snapshot-cache.ts").createRunSnapshotCache>;
+	isCleanedUp: () => boolean;
+	getCurrentCtx: () => ExtensionContext | undefined;
+}
+
+/**
+ * Open the live-run sidebar overlay if autoOpenDashboard is enabled. Gated by
+ * ui.autoOpenDashboard / autoOpenDashboardForForegroundRuns / placement.
+ *
+ * Returns true if the sidebar was opened (or was already open for this runId),
+ * false if gated off.
+ */
+export async function installLiveSidebar(ctx: ExtensionContext, runId: string, state: UiState, deps: UiDeps): Promise<boolean> {
+	const uiConfig = loadConfig(ctx.cwd).config.ui;
+	const autoOpen = uiConfig?.autoOpenDashboard === true;
+	const foregroundAutoOpen = uiConfig?.autoOpenDashboardForForegroundRuns ?? DEFAULT_UI.autoOpenDashboardForForegroundRuns;
+	if (!ctx.hasUI || !autoOpen || !foregroundAutoOpen || (uiConfig?.dashboardPlacement ?? DEFAULT_UI.dashboardPlacement) !== "right") {
+		return false;
+	}
+	if (state.liveSidebarRunId === runId) return true;
+	state.liveSidebarRunId = runId;
+	state.dashboardOpened = true;
+	const widgetPlacement = uiConfig?.widgetPlacement ?? DEFAULT_UI.widgetPlacement;
+	setExtensionWidget(ctx, "pi-crew", undefined, { placement: widgetPlacement });
+	setExtensionWidget(ctx, "pi-crew-active", undefined, { placement: widgetPlacement });
+	deps.widgetState.lastVisibility = "hidden";
+	deps.widgetState.lastPlacement = widgetPlacement;
+	deps.widgetState.lastKey = "pi-crew-active";
+	deps.widgetState.model = undefined;
+	const width = Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth));
+
+	try {
+		const LiveRunSidebar = await importLiveRunSidebar();
+		if (deps.isCleanedUp() || !deps.getCurrentCtx()) return false;
+		void showCustom<undefined>(
+			ctx,
+			(_tui, theme, _keybindings, done) =>
+				new LiveRunSidebar({
+					cwd: ctx.cwd,
+					runId,
+					done,
+					theme,
+					config: uiConfig,
+					snapshotCache: deps.getRunSnapshotCache(ctx.cwd),
+				}),
+			{
+				overlay: true,
+				overlayOptions: {
+					width,
+					minWidth: 40,
+					maxHeight: "100%",
+					anchor: "top-right",
+					offsetX: 0,
+					offsetY: 0,
+					margin: { top: 0, right: 0, bottom: 0, left: 0 },
+					visible: (termWidth: number) => termWidth >= 100,
+				},
+			},
+		).finally(() => {
+			if (state.liveSidebarRunId === runId) state.liveSidebarRunId = undefined;
+			const c = deps.getCurrentCtx();
+			if (!c) return;
+			updateCrewWidget(
+				c,
+				deps.widgetState,
+				loadConfig(c.cwd).config.ui,
+				deps.getManifestCache(c.cwd),
+				deps.getRunSnapshotCache(c.cwd),
+			);
+		});
+		return true;
+	} catch (error) {
+		logInternalError("register.live-sidebar-lazy-import", error);
+		return false;
+	}
+}
+
+/** Clear the powerbar (called on session switch). */
+export function clearDashboardPowerbar(state: UiState, deps: UiDeps): void {
+	const c = deps.getCurrentCtx();
+	if (c) stopCrewWidget(c, deps.widgetState, loadConfig(c.cwd).config.ui);
+	clearPiCrewPowerbar(deps.pi.events);
+	resetPowerbarDedupState();
+	state.dashboardOpened = false;
+}
+
+/** Register powerbar segments for a session. Idempotent. */
+export function registerPowerbarSegments(deps: UiDeps, uiConfig: unknown): void {
+	registerPiCrewPowerbarSegments(deps.pi.events, uiConfig as Parameters<typeof registerPiCrewPowerbarSegments>[1]);
+}
+
+/** Push a powerbar update with current run state. */
+export function pushPowerbarUpdate(ctx: ExtensionContext, deps: UiDeps, notificationCount: number): void {
+	const config = loadConfig(ctx.cwd).config.ui;
+	requestPowerbarUpdate(
+		deps.pi.events,
+		ctx.cwd,
+		config,
+		deps.getManifestCache(ctx.cwd),
+		deps.getRunSnapshotCache(ctx.cwd),
+		ctx,
+		notificationCount,
+	);
+}
+
+/** Initial powerbar update after session_start. */
+export function primePowerbarAndWidget(ctx: ExtensionContext, deps: UiDeps, notificationCount: number): void {
+	const uiConfig = loadConfig(ctx.cwd).config.ui;
+	const cache = deps.getManifestCache(ctx.cwd);
+	updateCrewWidget(ctx, deps.widgetState, uiConfig, cache, deps.getRunSnapshotCache(ctx.cwd));
+	updatePiCrewPowerbar(deps.pi.events, ctx.cwd, uiConfig, cache, deps.getRunSnapshotCache(ctx.cwd), ctx, notificationCount);
+}
+
+/** Force-render the current context (used by sidebar open path). */
+export function requestUiRender(ctx: ExtensionContext): void {
+	requestRender(ctx);
+}

package/src/extension/registration/viewers.ts

@@ -0,0 +1,121 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { listLiveAgents } from "../../runtime/live-agent-manager.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { LiveConversationOverlay } from "../../ui/live-conversation-overlay.ts";
+import { asCrewTheme } from "../../ui/theme-adapter.ts";
+// Lazy-loaded: DurableTranscriptViewer is 658ms — only needed for /crew transcript command
+import type { DurableTranscriptViewer as DurableTranscriptViewerType } from "../../ui/transcript-viewer.ts";
+
+let _cachedViewer: typeof DurableTranscriptViewerType | undefined;
+let _viewerPromise: Promise<typeof DurableTranscriptViewerType> | undefined;
+async function getViewer(): Promise<typeof DurableTranscriptViewerType> {
+	if (_cachedViewer) return _cachedViewer;
+	if (!_viewerPromise) {
+		_viewerPromise = import("../../ui/transcript-viewer.ts").then((mod) => {
+			_cachedViewer = mod.DurableTranscriptViewer;
+			return mod.DurableTranscriptViewer;
+		});
+	}
+	return _viewerPromise;
+}
+
+export async function selectAgentTask(
+	ctx: ExtensionCommandContext,
+	runId: string | undefined,
+	taskId?: string,
+): Promise<{ runId: string; taskId?: string } | undefined> {
+	if (!runId) return undefined;
+	if (taskId) return { runId, taskId };
+	const loaded = loadRunManifestById(ctx.cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	if (!loaded) return { runId };
+	const agents = readCrewAgents(loaded.manifest);
+	if (ctx.hasUI && agents.length > 1) {
+		const choice = await ctx.ui.select(
+			"Select pi-crew agent",
+			agents.map((agent) => `${agent.taskId} ${agent.role}→${agent.agent} [${agent.status}]`),
+		);
+		return { runId, taskId: choice?.split(" ")[0] };
+	}
+	return { runId, taskId: agents[0]?.taskId };
+}
+
+export async function openTranscriptViewer(
+	ctx: ExtensionCommandContext,
+	initialRunId: string | undefined,
+	initialTaskId?: string,
+): Promise<boolean> {
+	const selected = await selectAgentTask(ctx, initialRunId, initialTaskId);
+	if (!selected) return false;
+	const runId = selected.runId;
+	const taskId = selected.taskId;
+	if (!runId || !ctx.hasUI) return false;
+	const loaded = loadRunManifestById(ctx.cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	if (!loaded) return false;
+	const uiConfig = loadConfig(ctx.cwd).config.ui;
+	const DurableTranscriptViewer = await getViewer();
+	await ctx.ui.custom<undefined>(
+		(_tui, theme, _keybindings, done) =>
+			new DurableTranscriptViewer(loaded.manifest, theme, done, taskId, {
+				maxTailBytes: uiConfig?.transcriptTailBytes,
+			}),
+		{
+			overlay: true,
+			overlayOptions: {
+				width: "90%",
+				maxHeight: "85%",
+				anchor: "center",
+			},
+		},
+	);
+	return true;
+}
+
+/** R2: Open live conversation overlay for a running live-session agent. */
+export async function openLiveConversation(
+	ctx: ExtensionCommandContext,
+	initialRunId: string | undefined,
+	initialTaskId?: string,
+): Promise<boolean> {
+	const selected = await selectAgentTask(ctx, initialRunId, initialTaskId);
+	if (!selected || !ctx.hasUI) return false;
+	const liveAgents = listLiveAgents();
+	const handle = liveAgents.find((h) => h.runId === selected.runId && (selected.taskId ? h.taskId === selected.taskId : true));
+	if (!handle) return false;
+	const theme = asCrewTheme({});
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	await ctx.ui.custom<undefined>(
+		(tui: any, _theme: any, _keybindings: any, done: (result: undefined) => void) => {
+			const columns = tui?.terminal?.columns ?? 80;
+			const rows = tui?.terminal?.rows ?? 24;
+			const overlay = new LiveConversationOverlay(handle, theme, columns, rows);
+			return {
+				render(width: number) {
+					return overlay.render(width);
+				},
+				handleInput(data: string) {
+					if (data === "\x1b" || data === "q") {
+						overlay.close();
+						done(undefined);
+					}
+				},
+				invalidate() {
+					/* overlay polls */
+				},
+				dispose() {
+					overlay.dispose();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: {
+				width: "90%",
+				maxHeight: "85%",
+				anchor: "center",
+			},
+		},
+	);
+	return true;
+}

package/src/extension/registration/wire-cross-extension.ts

@@ -0,0 +1,37 @@
+/**
+ * Cross-extension wiring helper.
+ *
+ * Two small wires:
+ *   • wireRpc — the in-process pi-crew RPC handle (other modules in
+ *     the same extension can subscribe via `pi.events`).
+ *   • wireGlobalRegistry — the cross-extension crew global registry,
+ *     lazily loaded from team-tool.ts (heavy module) and installed under
+ *     `globalThis[Symbol.for("pi-crew:registry")]` so peer extensions
+ *     (e.g., pi-subagents3) can discover pi-crew at runtime.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerPiCrewRpc } from "../cross-extension-rpc.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/** Install both wires on the registration context. */
+export function installCrossExtensionWiring(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	// Wire the in-process RPC handle.
+	const getPiEvents = (): Parameters<typeof registerPiCrewRpc>[0] | undefined => {
+		if (pi && typeof pi === "object" && "events" in pi) {
+			return (pi as { events?: Parameters<typeof registerPiCrewRpc>[0] }).events;
+		}
+		return undefined;
+	};
+	ctx.rpcHandle = registerPiCrewRpc(getPiEvents(), () => ctx.currentCtx);
+
+	// Install the cross-extension crew global registry. Lazy import keeps
+	// team-tool.ts (which pulls in the entire runtime chain) out of the
+	// cold-start module graph.
+	void import("../team-tool.ts").then(({ installCrewGlobalRegistry }) => {
+		const manifestCacheForRegistry = ctx.getManifestCache(ctx.currentCtx?.cwd ?? process.cwd());
+		installCrewGlobalRegistry({
+			manifestCache: manifestCacheForRegistry,
+			cwdProvider: () => ctx.currentCtx?.cwd ?? process.cwd(),
+		});
+	});
+}

package/src/extension/result-watcher.ts

@@ -0,0 +1,139 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "../utils/completion-dedupe.ts";
+import { createFileCoalescer } from "../utils/file-coalescer.ts";
+import { closeWatcher, watchWithErrorHandler } from "../utils/fs-watch.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface ResultWatcherEvents {
+	emit(event: string, data: unknown): void;
+}
+
+export interface ResultWatcherHandle {
+	start(): void;
+	prime(): void;
+	stop(): void;
+}
+
+interface ResultWatcherDependencies {
+	watch?: typeof watchWithErrorHandler;
+}
+
+export interface ResultWatcherOptions extends ResultWatcherDependencies {
+	eventName?: string;
+	completionTtlMs?: number;
+	isCurrent?: () => boolean;
+}
+
+const RESULT_WATCHER_RESTART_MS = 3000;
+const RESULT_WATCHER_POLL_MS = 1000;
+
+function shouldFallBackToPolling(error: unknown): boolean {
+	const code = error && typeof error === "object" ? (error as { code?: unknown }).code : undefined;
+	return code === "EMFILE" || code === "ENOSPC" || code === "EPERM";
+}
+
+function readJson(filePath: string): unknown | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	} catch (error) {
+		logInternalError("result-watcher.parse", error, `filePath=${filePath}`);
+		return undefined;
+	}
+}
+
+export function createResultWatcher(
+	events: ResultWatcherEvents,
+	resultsDir: string,
+	eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result",
+): ResultWatcherHandle {
+	const options: ResultWatcherOptions = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
+	const eventName = options.eventName ?? "pi-crew:run-result";
+	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
+	const watch = options.watch ?? watchWithErrorHandler;
+	const isCurrent = options.isCurrent ?? (() => true);
+	const seen = getGlobalSeenMap("pi-crew.result-watcher");
+	let watcher: fs.FSWatcher | null | undefined;
+	let restartTimer: ReturnType<typeof setTimeout> | undefined;
+	let pollTimer: ReturnType<typeof setInterval> | undefined;
+	const coalescer = createFileCoalescer((file) => {
+		if (!isCurrent()) return;
+		const filePath = path.join(resultsDir, file);
+		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
+		const payload = readJson(filePath);
+		if (payload === undefined) {
+			coalescer.schedule(file, RESULT_WATCHER_POLL_MS);
+			return;
+		}
+		const key = buildCompletionKey(
+			payload && typeof payload === "object" && !Array.isArray(payload) ? (payload as Record<string, unknown>) : {},
+			`file:${file}`,
+		);
+		if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
+			events.emit(eventName, payload);
+		}
+		try {
+			fs.unlinkSync(filePath);
+		} catch (error) {
+			logInternalError("result-watcher.unlink", error, `filePath=${filePath}`);
+		}
+	}, 50);
+	const poll = () => {
+		if (!isCurrent() || !fs.existsSync(resultsDir)) return;
+		for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+	};
+	const startPolling = () => {
+		if (pollTimer) return;
+		pollTimer = setInterval(poll, RESULT_WATCHER_POLL_MS);
+		pollTimer.unref();
+		poll();
+	};
+	const stopPolling = () => {
+		if (pollTimer) clearInterval(pollTimer);
+		pollTimer = undefined;
+	};
+	const scheduleRestart = (error?: unknown) => {
+		if (shouldFallBackToPolling(error)) startPolling();
+		if (restartTimer) clearTimeout(restartTimer);
+		restartTimer = setTimeout(() => {
+			restartTimer = undefined;
+			try {
+				if (!isCurrent()) return;
+				fs.mkdirSync(resultsDir, { recursive: true });
+				handle.start();
+			} catch (error) {
+				logInternalError("result-watcher.restart", error, `resultsDir=${resultsDir}`);
+			}
+		}, RESULT_WATCHER_RESTART_MS);
+		restartTimer.unref();
+	};
+	const handle: ResultWatcherHandle = {
+		start() {
+			if (!isCurrent()) return;
+			fs.mkdirSync(resultsDir, { recursive: true });
+			if (watcher) closeWatcher(watcher);
+			watcher = watch(
+				resultsDir,
+				(event, fileName) => {
+					if (event !== "rename" || !fileName) return;
+					coalescer.schedule(fileName.toString());
+				},
+				scheduleRestart,
+			);
+			if (watcher) stopPolling();
+			watcher?.unref();
+		},
+		prime() {
+			poll();
+		},
+		stop() {
+			if (restartTimer) clearTimeout(restartTimer);
+			restartTimer = undefined;
+			closeWatcher(watcher);
+			watcher = undefined;
+			stopPolling();
+			coalescer.clear();
+		},
+	};
+	return handle;
+}