pi-crew 0.1.24 → 0.1.26

package/src/extension/registration/subagent-helpers.ts

@@ -0,0 +1,70 @@
+import * as fs from "node:fs";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { savePersistedSubagentRecord, type SubagentRecord, type SubagentSpawnOptions } from "../../runtime/subagent-manager.ts";
+
+export function sendFollowUp(pi: ExtensionAPI, content: string): void {
+	const sender = (pi as unknown as { sendMessage?: (message: unknown, options?: unknown) => void }).sendMessage;
+	if (typeof sender !== "function") return;
+	sender.call(pi, { customType: "pi-crew-subagent-notification", content, display: true }, { deliverAs: "followUp", triggerTurn: true });
+}
+
+export function refreshPersistedSubagentRecord(ctx: ExtensionContext | ExtensionCommandContext, record: SubagentRecord): SubagentRecord {
+	if (!record.runId) return record;
+	const loaded = loadRunManifestById(ctx.cwd, record.runId);
+	if (!loaded) return record;
+	if (loaded.manifest.status === "completed" || loaded.manifest.status === "failed" || loaded.manifest.status === "cancelled" || loaded.manifest.status === "blocked") {
+		const refreshed = {
+			...record,
+			status: loaded.manifest.status,
+			error: loaded.manifest.status === "completed" || loaded.manifest.status === "blocked" ? undefined : loaded.manifest.summary,
+			completedAt: loaded.manifest.status === "blocked" ? undefined : record.completedAt ?? Date.now(),
+		};
+		savePersistedSubagentRecord(ctx.cwd, refreshed);
+		return refreshed;
+	}
+	return record;
+}
+
+export function formatSubagentRecord(record: SubagentRecord): string {
+	const duration = record.completedAt ? `${Math.round((record.completedAt - record.startedAt) / 1000)}s` : "running";
+	return [
+		`Agent: ${record.id}`,
+		`Type: ${record.type}`,
+		`Status: ${record.status}`,
+		record.runId ? `Run: ${record.runId}` : undefined,
+		`Description: ${record.description}`,
+		record.model ? `Model: ${record.model}` : undefined,
+		`Duration: ${duration}`,
+		record.error ? `Error: ${record.error}` : undefined,
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+export function readSubagentRunResult(ctx: ExtensionContext | ExtensionCommandContext, record: SubagentRecord): string | undefined {
+	if (!record.runId) return record.result;
+	const loaded = loadRunManifestById(ctx.cwd, record.runId);
+	const task = loaded?.tasks.find((item) => item.resultArtifact) ?? loaded?.tasks[0];
+	const path = task?.resultArtifact?.path;
+	if (!path) return undefined;
+	try {
+		return fs.readFileSync(path, "utf-8").trim();
+	} catch {
+		return undefined;
+	}
+}
+
+export function subagentToolResult(text: string, details: Record<string, unknown> = {}, isError = false) {
+	return { content: [{ type: "text" as const, text }], details, isError };
+}
+
+export function __test__subagentSpawnParams(params: Record<string, unknown>, ctx: Pick<ExtensionContext, "cwd">): SubagentSpawnOptions {
+	return {
+		cwd: ctx.cwd,
+		type: typeof params.subagent_type === "string" && params.subagent_type.trim() ? params.subagent_type.trim() : "executor",
+		description: typeof params.description === "string" && params.description.trim() ? params.description.trim() : "pi-crew subagent",
+		prompt: typeof params.prompt === "string" ? params.prompt : "",
+		background: params.run_in_background === true,
+		model: typeof params.model === "string" && params.model.trim() ? params.model.trim() : undefined,
+		maxTurns: typeof params.max_turns === "number" && Number.isFinite(params.max_turns) ? params.max_turns : undefined,
+	};
+}

package/src/extension/registration/viewers.ts

@@ -0,0 +1,32 @@
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { DurableTranscriptViewer } from "../../ui/transcript-viewer.ts";
+
+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);
+	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);
+	if (!loaded) return false;
+	await ctx.ui.custom<undefined>((_tui, theme, _keybindings, done) => new DurableTranscriptViewer(loaded.manifest, theme, done, taskId), {
+		overlay: true,
+		overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" },
+	});
+	return true;
+}

package/src/extension/result-watcher.ts

@@ -1,89 +1,98 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { createFileCoalescer } from "../utils/file-coalescer.ts";
-
-export interface ResultWatcherEvents {
-	emit(event: string, data: unknown): void;
-}
-
-export interface ResultWatcherHandle {
-	start(): void;
-	prime(): void;
-	stop(): void;
-}
-
-export interface ResultWatcherOptions {
-	eventName?: string;
-	completionTtlMs?: number;
-}
-
-function readJson(filePath: string): unknown | undefined {
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
-	} catch {
-		return undefined;
-	}
-}
-
-function completionKey(payload: unknown, file: string): string {
-	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return `file:${file}`;
-	const obj = payload as Record<string, unknown>;
-	const id = [obj.runId, obj.sessionId, obj.id, obj.status].filter((entry): entry is string => typeof entry === "string" && entry.length > 0).join(":");
-	return id || `file:${file}`;
-}
-
-export function createResultWatcher(events: ResultWatcherEvents, resultsDir: string, eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result"): ResultWatcherHandle {
-	const options = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
-	const eventName = options.eventName ?? "pi-crew:run-result";
-	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
-	const seen = new Map<string, number>();
-	let watcher: fs.FSWatcher | undefined;
-	let restartTimer: ReturnType<typeof setTimeout> | undefined;
-	const coalescer = createFileCoalescer((file) => {
-		const filePath = path.join(resultsDir, file);
-		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
-		const payload = readJson(filePath);
-		if (payload !== undefined) {
-			const now = Date.now();
-			for (const [key, expiresAt] of seen) if (expiresAt <= now) seen.delete(key);
-			const key = completionKey(payload, file);
-			if (!seen.has(key)) {
-				seen.set(key, now + completionTtlMs);
-				events.emit(eventName, payload);
-			}
-		}
-		try { fs.unlinkSync(filePath); } catch {}
-	}, 50);
-	const scheduleRestart = () => {
-		if (restartTimer) clearTimeout(restartTimer);
-		restartTimer = setTimeout(() => {
-			restartTimer = undefined;
-			try { handle.start(); } catch {}
-		}, 3000);
-		restartTimer.unref?.();
-	};
-	const handle: ResultWatcherHandle = {
-		start() {
-			fs.mkdirSync(resultsDir, { recursive: true });
-			watcher?.close();
-			watcher = fs.watch(resultsDir, (event, file) => {
-				if (event !== "rename" || !file) return;
-				coalescer.schedule(file.toString());
-			});
-			watcher.on("error", scheduleRestart);
-			watcher.unref?.();
-		},
-		prime() {
-			if (!fs.existsSync(resultsDir)) return;
-			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
-		},
-		stop() {
-			watcher?.close();
-			watcher = undefined;
-			if (restartTimer) clearTimeout(restartTimer);
-			restartTimer = undefined;
-			coalescer.clear();
-		},
-	};
-	return handle;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "../utils/completion-dedupe.ts";
+import { closeWatcher, watchWithErrorHandler } from "../utils/fs-watch.ts";
+import { createFileCoalescer } from "../utils/file-coalescer.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;
+}
+
+const RESULT_WATCHER_RESTART_MS = 3000;
+
+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 seen = getGlobalSeenMap("pi-crew.result-watcher");
+	let watcher: fs.FSWatcher | null | undefined;
+	let restartTimer: ReturnType<typeof setTimeout> | undefined;
+	const coalescer = createFileCoalescer((file) => {
+		const filePath = path.join(resultsDir, file);
+		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
+		const payload = readJson(filePath);
+		if (payload !== undefined) {
+			const key = buildCompletionKey(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 scheduleRestart = () => {
+		if (restartTimer) clearTimeout(restartTimer);
+		restartTimer = setTimeout(() => {
+			restartTimer = undefined;
+			try {
+				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() {
+			fs.mkdirSync(resultsDir, { recursive: true });
+			if (watcher) closeWatcher(watcher);
+			watcher = watch(resultsDir, (event, fileName) => {
+				if (event !== "rename" || !fileName) return;
+				coalescer.schedule(fileName.toString());
+			}, scheduleRestart);
+			watcher?.unref?.();
+		},
+		prime() {
+			if (!fs.existsSync(resultsDir)) return;
+			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+		},
+		stop() {
+			if (restartTimer) clearTimeout(restartTimer);
+			restartTimer = undefined;
+			closeWatcher(watcher);
+			watcher = undefined;
+			coalescer.clear();
+		},
+	};
+	return handle;
+}

package/src/extension/team-tool/api.ts

@@ -0,0 +1,276 @@
+import * as fs from "node:fs";
+import { loadConfig } from "../../config/config.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { saveRunTasks, loadRunManifestById } from "../../state/state-store.ts";
+import { withRunLockSync } from "../../state/locks.ts";
+import { canTransitionTaskStatus, isTeamTaskStatus } from "../../state/contracts.ts";
+import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../state/task-claims.ts";
+import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, readMailbox, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
+import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log.ts";
+import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
+import { probeLiveSessionRuntime } from "../../runtime/live-session-runtime.ts";
+import { touchWorkerHeartbeat } from "../../runtime/worker-heartbeat.ts";
+import { agentEventsPath, agentOutputPath, readCrewAgentEvents, readCrewAgentEventsCursor, readCrewAgentStatus, readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { buildAgentDashboard, readAgentOutput } from "../../runtime/agent-observability.ts";
+import { readForegroundControlStatus, writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
+import { listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../runtime/live-agent-manager.ts";
+import { appendLiveAgentControlRequest } from "../../runtime/live-agent-control.ts";
+import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../../runtime/live-control-realtime.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { configRecord, result, type TeamContext } from "./context.ts";
+
+export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	if (!params.runId) return result("API requires runId.", { action: "api", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "api", status: "error" }, true);
+	const cfg = configRecord(params.config);
+	const operation = typeof cfg.operation === "string" ? cfg.operation : "read-manifest";
+	if (operation === "read-manifest") {
+		return result(JSON.stringify(loaded.manifest, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "list-tasks") {
+		return result(JSON.stringify(loaded.tasks, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-task") {
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const task = loaded.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+		if (!task) return result("API read-task requires config.taskId matching a task id or step id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		return result(JSON.stringify(task, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-events") {
+		const sinceSeq = typeof cfg.sinceSeq === "number" ? cfg.sinceSeq : undefined;
+		const limit = typeof cfg.limit === "number" ? cfg.limit : undefined;
+		const payload = sinceSeq !== undefined || limit !== undefined
+			? readEventsCursor(loaded.manifest.eventsPath, { sinceSeq, limit })
+			: { events: readEvents(loaded.manifest.eventsPath), nextSeq: undefined, total: undefined };
+		return result(JSON.stringify(payload, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "runtime-capabilities") {
+		const loadedConfig = loadConfig(ctx.cwd);
+		return result(JSON.stringify(await resolveCrewRuntime(loadedConfig.config), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "probe-live-session") {
+		return result(JSON.stringify(await probeLiveSessionRuntime(), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "list-agents") {
+		return result(JSON.stringify(readCrewAgents(loaded.manifest), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "get-agent-result") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
+		if (!agent) return result("API get-agent-result requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const task = loaded.tasks.find((item) => item.id === agent.taskId);
+		const text = task?.resultArtifact && fs.existsSync(task.resultArtifact.path) ? fs.readFileSync(task.resultArtifact.path, "utf-8") : JSON.stringify(agent, null, 2);
+		return result(text, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-agent-status") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agent = agentId ? readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId) : undefined;
+		const status = agent ? readCrewAgentStatus(loaded.manifest, agent.taskId) ?? agent : undefined;
+		if (!status) return result("API read-agent-status requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		return result(JSON.stringify(status, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-agent-events") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agents = readCrewAgents(loaded.manifest);
+		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
+		if (!agent) return result("API read-agent-events requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const sinceSeq = typeof cfg.sinceSeq === "number" ? cfg.sinceSeq : undefined;
+		const limit = typeof cfg.limit === "number" ? cfg.limit : undefined;
+		const payload = sinceSeq !== undefined || limit !== undefined
+			? readCrewAgentEventsCursor(loaded.manifest, agent.taskId, { sinceSeq, limit })
+			: { path: agentEventsPath(loaded.manifest, agent.taskId), events: readCrewAgentEvents(loaded.manifest, agent.taskId) };
+		return result(JSON.stringify(payload, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-agent-transcript") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agents = readCrewAgents(loaded.manifest);
+		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
+		if (!agent) return result("API read-agent-transcript requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const transcriptPath = agent.transcriptPath && fs.existsSync(agent.transcriptPath) ? agent.transcriptPath : agentOutputPath(loaded.manifest, agent.taskId);
+		const text = fs.existsSync(transcriptPath) ? fs.readFileSync(transcriptPath, "utf-8") : "";
+		return result(text || `(no transcript at ${transcriptPath})`, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-agent-output") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agents = readCrewAgents(loaded.manifest);
+		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
+		if (!agent) return result("API read-agent-output requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const maxBytes = typeof cfg.maxBytes === "number" ? cfg.maxBytes : undefined;
+		return result(JSON.stringify(readAgentOutput(loaded.manifest, agent.taskId, maxBytes), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "agent-dashboard") {
+		return result(buildAgentDashboard(loaded.manifest).text, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "foreground-status") {
+		return result(JSON.stringify(readForegroundControlStatus(loaded.manifest, loaded.tasks), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "foreground-interrupt") {
+		const reason = typeof cfg.reason === "string" && cfg.reason.trim() ? cfg.reason.trim() : undefined;
+		return result(JSON.stringify(writeForegroundInterruptRequest(loaded.manifest, reason), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "nudge-agent") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
+		if (!agent) return result("API nudge-agent requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const messageText = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : "Please report your current status, blocker, or smallest next step.";
+		const message = appendMailboxMessage(loaded.manifest, { direction: "inbox", from: "leader", to: agent.taskId, taskId: agent.taskId, body: messageText });
+		appendEvent(loaded.manifest.eventsPath, { type: "agent.nudged", runId: loaded.manifest.runId, taskId: agent.taskId, message: messageText, data: { agentId: agent.id, mailboxMessageId: message.id } });
+		return result(JSON.stringify({ agentId: agent.id, mailboxMessage: message }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "list-live-agents") {
+		return result(JSON.stringify(listLiveAgents().filter((agent) => agent.runId === loaded.manifest.runId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "steer-agent" || operation === "stop-agent" || operation === "resume-agent" || operation === "interrupt-agent") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		if (!agentId) return result(`API ${operation} requires config.agentId.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const message = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : undefined;
+		const prompt = typeof cfg.prompt === "string" && cfg.prompt.trim() ? cfg.prompt.trim() : message;
+		try {
+			if (operation === "steer-agent") return result(JSON.stringify(await steerLiveAgent(agentId, message ?? "Please report current status and wrap up if possible."), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			if (operation === "resume-agent") {
+				if (!prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+				return result(JSON.stringify(await resumeLiveAgent(agentId, prompt), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			}
+			return result(JSON.stringify(await stopLiveAgent(agentId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		} catch (error) {
+			const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
+			if (!agent) {
+				const err = error instanceof Error ? error.message : String(error);
+				return result(err, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			}
+			if (operation === "resume-agent" && !prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: agent.taskId, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" ? prompt : message });
+			publishLiveControlRealtime(request);
+			ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
+			appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, realtime: true } });
+			return result(JSON.stringify({ queued: true, request }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		}
+	}
+	if (operation === "read-mailbox") {
+		const direction = cfg.direction === "inbox" || cfg.direction === "outbox" ? cfg.direction as MailboxDirection : undefined;
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		return result(JSON.stringify(readMailbox(loaded.manifest, direction, taskId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "validate-mailbox") {
+		const report = validateMailbox(loaded.manifest, { repair: cfg.repair === true });
+		return result(JSON.stringify(report, null, 2), { action: "api", status: report.issues.some((issue) => issue.level === "error") && cfg.repair !== true ? "error" : "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot }, report.issues.some((issue) => issue.level === "error") && cfg.repair !== true);
+	}
+	if (operation === "read-delivery") {
+		return result(JSON.stringify(readDeliveryState(loaded.manifest), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "send-message") {
+		const direction = cfg.direction === "outbox" ? "outbox" : "inbox";
+		const from = typeof cfg.from === "string" && cfg.from.trim() ? cfg.from.trim() : "api";
+		const to = typeof cfg.to === "string" && cfg.to.trim() ? cfg.to.trim() : "leader";
+		const body = typeof cfg.body === "string" && cfg.body.trim() ? cfg.body : undefined;
+		const taskId = typeof cfg.taskId === "string" && cfg.taskId.trim() ? cfg.taskId.trim() : undefined;
+		if (!body) return result("API send-message requires config.body.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const message = appendMailboxMessage(loaded.manifest, { direction, from, to, body, taskId });
+				appendEvent(loaded.manifest.eventsPath, { type: "mailbox.message", runId: loaded.manifest.runId, data: { id: message.id, direction, from, to } });
+				return result(JSON.stringify(message, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
+	}
+	if (operation === "ack-message") {
+		const messageId = typeof cfg.messageId === "string" ? cfg.messageId : undefined;
+		if (!messageId) return result("API ack-message requires config.messageId.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const delivery = acknowledgeMailboxMessage(loaded.manifest, messageId);
+				appendEvent(loaded.manifest.eventsPath, { type: "mailbox.acknowledged", runId: loaded.manifest.runId, data: { messageId } });
+				return result(JSON.stringify(delivery, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
+	}
+	if (operation === "read-heartbeat") {
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const task = loaded.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+		if (!task) return result("API read-heartbeat requires config.taskId matching a task id or step id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		return result(JSON.stringify(task.heartbeat ?? null, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "claim-task") {
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const owner = typeof cfg.owner === "string" ? cfg.owner : "api";
+		const task = loaded.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+		if (!task) return result("API claim-task requires config.taskId matching a task id or step id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const updatedTask = claimTask(task, owner);
+				const tasks = loaded.tasks.map((item) => item.id === task.id ? updatedTask : item);
+				saveRunTasks(loaded.manifest, tasks);
+				appendEvent(loaded.manifest.eventsPath, { type: "task.claimed", runId: loaded.manifest.runId, taskId: task.id, data: { owner, token: updatedTask.claim?.token, leasedUntil: updatedTask.claim?.leasedUntil } });
+				return result(JSON.stringify(updatedTask.claim, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
+	}
+	if (operation === "release-task-claim") {
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const owner = typeof cfg.owner === "string" ? cfg.owner : undefined;
+		const token = typeof cfg.token === "string" ? cfg.token : undefined;
+		const task = loaded.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+		if (!task || !owner || !token) return result("API release-task-claim requires config.taskId, config.owner, and config.token.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const updatedTask = releaseTaskClaim(task, owner, token);
+				const tasks = loaded.tasks.map((item) => item.id === task.id ? updatedTask : item);
+				saveRunTasks(loaded.manifest, tasks);
+				appendEvent(loaded.manifest.eventsPath, { type: "task.claim_released", runId: loaded.manifest.runId, taskId: task.id, data: { owner } });
+				return result(JSON.stringify(updatedTask, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
+	}
+	if (operation === "transition-task-status") {
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const owner = typeof cfg.owner === "string" ? cfg.owner : undefined;
+		const token = typeof cfg.token === "string" ? cfg.token : undefined;
+		const to = cfg.status;
+		const task = loaded.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+		if (!task || !owner || !token || !isTeamTaskStatus(to)) return result("API transition-task-status requires config.taskId, config.owner, config.token, and valid config.status.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		if (!canTransitionTaskStatus(task.status, to)) return result(`Invalid task status transition: ${task.status} -> ${to}`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const updatedTask = transitionClaimedTaskStatus(task, owner, token, to);
+				const tasks = loaded.tasks.map((item) => item.id === task.id ? updatedTask : item);
+				saveRunTasks(loaded.manifest, tasks);
+				appendEvent(loaded.manifest.eventsPath, { type: "task.status_transitioned", runId: loaded.manifest.runId, taskId: task.id, data: { owner, status: to } });
+				return result(JSON.stringify(updatedTask, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
+	}
+	if (operation === "write-heartbeat") {
+		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const task = loaded.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+		if (!task) return result("API write-heartbeat requires config.taskId matching a task id or step id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const heartbeat = touchWorkerHeartbeat(task.heartbeat ?? { workerId: task.id, lastSeenAt: new Date().toISOString() }, { alive: typeof cfg.alive === "boolean" ? cfg.alive : undefined });
+				const tasks = loaded.tasks.map((item) => item.id === task.id ? { ...item, heartbeat } : item);
+				saveRunTasks(loaded.manifest, tasks);
+				appendEvent(loaded.manifest.eventsPath, { type: "worker.heartbeat", runId: loaded.manifest.runId, taskId: task.id, data: { ...heartbeat } });
+				return result(JSON.stringify(heartbeat, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		}
+	}
+	return result(`Unknown API operation: ${operation}`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+}

package/src/extension/team-tool/config-patch.ts

@@ -0,0 +1,36 @@
+import { effectiveAutonomousConfig, parseConfig, type PiTeamsAutonomousConfig, type PiTeamsConfig } from "../../config/config.ts";
+
+export function autonomousPatchFromConfig(config: unknown): PiTeamsAutonomousConfig {
+	const rootPatch = parseConfig(config).autonomous;
+	if (rootPatch) return rootPatch;
+	return parseConfig({ autonomous: config }).autonomous ?? {};
+}
+
+export function configPatchFromConfig(config: unknown): PiTeamsConfig {
+	return parseConfig(config);
+}
+
+export function effectiveRunConfig(base: PiTeamsConfig, rawOverride: unknown): PiTeamsConfig {
+	const patch = parseConfig(rawOverride);
+	return {
+		...base,
+		...patch,
+		limits: patch.limits ? { ...(base.limits ?? {}), ...patch.limits } : base.limits,
+		runtime: patch.runtime ? { ...(base.runtime ?? {}), ...patch.runtime } : base.runtime,
+		control: patch.control ? { ...(base.control ?? {}), ...patch.control } : base.control,
+		worktree: patch.worktree ? { ...(base.worktree ?? {}), ...patch.worktree } : base.worktree,
+	};
+}
+
+export function formatAutonomyStatus(config: PiTeamsAutonomousConfig | undefined, pathValue: string, updated: boolean): string {
+	const effective = effectiveAutonomousConfig(config);
+	return [
+		updated ? "Updated pi-crew autonomous mode." : "pi-crew autonomous mode:",
+		`Path: ${pathValue}`,
+		`Profile: ${effective.profile}`,
+		`Enabled: ${effective.enabled}`,
+		`Inject policy: ${effective.injectPolicy}`,
+		`Prefer async for long tasks: ${effective.preferAsyncForLongTasks}`,
+		`Allow worktree suggestion: ${effective.allowWorktreeSuggestion}`,
+	].join("\n");
+}