pi-crew 0.9.65 → 0.9.67

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

@@ -0,0 +1,57 @@
+/**
+ * Shared context for extracted `api` operation handlers (H3 phase 1+).
+ *
+ * The `handleApi` function in `src/extension/team-tool/api.ts` was 1222 lines
+ * with 35+ `if (operation === "…")` branches. This file defines the shared
+ * bundle of closure dependencies that each extracted handler receives, so
+ * sibling modules under `src/extension/team-tool/api/<group>.ts` can be
+ * pure-function-shaped without re-establishing the closure.
+ *
+ * Extraction pattern mirrors `merge-gate.ts` (improvement-plan-2026-08-09
+ * phase 5): the extracted module imports its own state/coordination helpers
+ * directly; only the request-scoped values (config, loaded run, params,
+ * extension context) are passed via this context.
+ *
+ * Phase 2 (2026-08-10): added `params` + `ctx` and made handlers async-capable
+ * (several operations await live-agent or runtime resolution).
+ */
+
+import type { TeamToolParamsValue } from "../../../schema/team-tool-schema.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../../state/types.ts";
+import type { PiTeamsToolResult } from "../../tool-result.ts";
+import type { result as resultFn, TeamContext } from "../context.ts";
+import type { paramRequired as paramRequiredFn } from "../param-error.ts";
+
+/** The config record produced by `configRecord(params.config)` in handleApi. */
+export type ApiConfig = Record<string, unknown>;
+
+/** The loaded run snapshot returned by `loadRunManifestById`. */
+export interface ApiLoadedRun {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+}
+
+/**
+ * Bundle of closure-scoped dependencies that handleApi establishes once and
+ * passes to each extracted handler. Adding a field here is cheaper than
+ * growing the closure of a 1200-line function.
+ */
+export interface ApiHandlerContext {
+	cfg: ApiConfig;
+	loaded: ApiLoadedRun;
+	result: typeof resultFn;
+	paramRequired: typeof paramRequiredFn;
+	/** The raw tool params (runId, force, etc.) the caller passed. */
+	params: TeamToolParamsValue;
+	/** The extension TeamContext (cwd, events, metricRegistry, config…). */
+	ctx: TeamContext;
+}
+
+/** Type alias for an extracted operation handler. Async-capable. */
+export type ApiOperationHandler = (ctx: ApiHandlerContext) => PiTeamsToolResult | Promise<PiTeamsToolResult>;
+
+/**
+ * Handler for operations that run BEFORE the runId guard (no loaded run).
+ * Currently: metrics-snapshot, inventory.
+ */
+export type ApiPreHandler = (ctx: Omit<ApiHandlerContext, "loaded">) => PiTeamsToolResult | Promise<PiTeamsToolResult>;

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

@@ -0,0 +1,75 @@
+/**
+ * Extracted `api` operation handlers — heartbeat group (H3 phase 2).
+ *
+ * Extracted from `src/extension/team-tool/api.ts` on 2026-08-10. Behaviour is
+ * byte-identical to the inline `if` blocks they replace.
+ */
+
+import { touchWorkerHeartbeat } from "../../../runtime/heartbeat/worker-heartbeat.ts";
+import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import { appendEvent } from "../../../state/event-log/event-log.ts";
+import { saveRunTasks } from "../../../state/stores/state-store.ts";
+import type { ApiOperationHandler } from "./handler-context.ts";
+
+export const handleWriteHeartbeat: ApiOperationHandler = (hctx) => {
+	const { cfg, loaded, result, paramRequired } = hctx;
+	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(
+			paramRequired(
+				"API write-heartbeat",
+				"config.taskId matching a task id or step id",
+				"{ action: 'api', runId: 'team_...', config: { operation: 'write-heartbeat', taskId: '01_01-agent' } }",
+			),
+			{
+				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,
+		);
+	}
+};
+
+/** Dispatcher map for the heartbeat group. Consumed by handleApi. */
+export const HEARTBEAT_OPERATIONS: Record<string, ApiOperationHandler> = {
+	"write-heartbeat": handleWriteHeartbeat,
+};

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

@@ -0,0 +1,242 @@
+/**
+ * Extracted `api` operation handlers — mailbox group (H3 phase 2).
+ *
+ * Extracted from `src/extension/team-tool/api.ts` on 2026-08-10. Behaviour is
+ * byte-identical to the inline `if` blocks they replace.
+ */
+
+import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import {
+	acknowledgeMailboxMessage,
+	appendMailboxMessage,
+	type MailboxDirection,
+	type MailboxMessageKind,
+	readDeliveryState,
+	readMailbox,
+	readMailboxMessage,
+	validateMailbox,
+} from "../../../state/coordination/mailbox.ts";
+import { appendEvent } from "../../../state/event-log/event-log.ts";
+import type { ApiOperationHandler } from "./handler-context.ts";
+
+export const handleReadMailbox: ApiOperationHandler = (hctx) => {
+	const { cfg, loaded, result } = hctx;
+	const direction = cfg.direction === "inbox" || cfg.direction === "outbox" ? (cfg.direction as MailboxDirection) : undefined;
+	const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+	const kind =
+		typeof cfg.kind === "string" && ["message", "steer", "follow-up", "response", "group_join"].includes(cfg.kind)
+			? (cfg.kind as MailboxMessageKind)
+			: undefined;
+	if (taskId && !loaded.tasks.some((task) => task.id === taskId))
+		return result(
+			`API read-mailbox taskId '${taskId}' does not match a run task.`,
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	try {
+		return result(JSON.stringify(readMailbox(loaded.manifest, direction, taskId, kind), 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,
+		);
+	}
+};
+
+export const handleValidateMailbox: ApiOperationHandler = (hctx) => {
+	const { cfg, loaded, result } = hctx;
+	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,
+	);
+};
+
+export const handleReadDelivery: ApiOperationHandler = (hctx) => {
+	const { loaded, result } = hctx;
+	return result(JSON.stringify(readDeliveryState(loaded.manifest), null, 2), {
+		action: "api",
+		status: "ok",
+		runId: loaded.manifest.runId,
+		artifactsRoot: loaded.manifest.artifactsRoot,
+	});
+};
+
+export const handleSendMessage: ApiOperationHandler = (hctx) => {
+	const { cfg, loaded, result, paramRequired, ctx } = hctx;
+	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(
+			paramRequired(
+				"API send-message",
+				"config.body",
+				"{ action: 'api', runId: 'team_...', config: { operation: 'send-message', body: '<message>' } }",
+			),
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	if (taskId && !loaded.tasks.some((task) => task.id === taskId))
+		return result(
+			`API send-message taskId '${taskId}' does not match a run task.`,
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	try {
+		return withRunLockSync(loaded.manifest, () => {
+			const message = appendMailboxMessage(loaded.manifest, {
+				direction,
+				from,
+				to,
+				body,
+				taskId,
+			});
+			// H1 (2026-08-10): informational mailbox event inside a SYNC
+			// run-lock callback. Sync append (byte-identical to pre-extract
+			// api.ts) so consumers reading eventsPath immediately after the
+			// call see the event — async fire-and-forget would race.
+			appendEvent(loaded.manifest.eventsPath, {
+				type: "mailbox.message",
+				runId: loaded.manifest.runId,
+				data: { id: message.id, direction, from, to },
+			});
+			ctx.events?.emit?.("crew.mailbox.message", {
+				runId: loaded.manifest.runId,
+				id: message.id,
+				direction,
+				from,
+				to,
+				taskId,
+				source: "send-message",
+			});
+			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,
+		);
+	}
+};
+
+export const handleAckMessage: ApiOperationHandler = (hctx) => {
+	const { cfg, loaded, result, paramRequired, ctx } = hctx;
+	const messageId = typeof cfg.messageId === "string" ? cfg.messageId : undefined;
+	if (!messageId)
+		return result(
+			paramRequired(
+				"API ack-message",
+				"config.messageId",
+				"{ action: 'api', runId: 'team_...', config: { operation: 'ack-message', messageId: 'msg-1' } }",
+			),
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	try {
+		return withRunLockSync(loaded.manifest, () => {
+			const message = readMailboxMessage(loaded.manifest, messageId);
+			const delivery = acknowledgeMailboxMessage(loaded.manifest, messageId);
+			appendEvent(loaded.manifest.eventsPath, {
+				type: "mailbox.acknowledged",
+				runId: loaded.manifest.runId,
+				data: { messageId },
+			});
+			if (message?.data?.kind === "group_join" && typeof message.data.requestId === "string") {
+				appendEvent(loaded.manifest.eventsPath, {
+					type: "agent.group_join.acknowledged",
+					runId: loaded.manifest.runId,
+					message: "Group join delivery acknowledged via mailbox ack.",
+					data: {
+						requestId: message.data.requestId,
+						messageId,
+						batchId: message.data.batchId,
+						partial: message.data.partial,
+						acknowledgedAt: delivery.updatedAt,
+						acknowledgedBy: "leader",
+					},
+					metadata: { provenance: "api" },
+				});
+			}
+			ctx.events?.emit?.("crew.mailbox.acknowledged", {
+				runId: loaded.manifest.runId,
+				messageId,
+				delivery,
+			});
+			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,
+		);
+	}
+};
+
+/** Dispatcher map for the mailbox group. Consumed by handleApi. */
+export const MAILBOX_OPERATIONS: Record<string, ApiOperationHandler> = {
+	"read-mailbox": handleReadMailbox,
+	"validate-mailbox": handleValidateMailbox,
+	"read-delivery": handleReadDelivery,
+	"send-message": handleSendMessage,
+	"ack-message": handleAckMessage,
+};

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

@@ -0,0 +1,190 @@
+/**
+ * Extracted `api` operation handlers — plan approval group (H3 phase 2).
+ *
+ * Extracted from `src/extension/team-tool/api.ts` on 2026-08-10. Behaviour is
+ * byte-identical to the inline `if` blocks they replace.
+ */
+
+import { terminateLiveAgentsForRun } from "../../../runtime/live-session/live-agent-manager.ts";
+import { currentCrewRole, permissionForRole } from "../../../runtime/role-permission.ts";
+import { withRunLock } from "../../../state/coordination/locks.ts";
+import { appendEvent } from "../../../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasks, updateRunStatus } from "../../../state/stores/state-store.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
+import type { ApiOperationHandler } from "./handler-context.ts";
+
+function canApprovePlan(): { allowed: boolean; reason?: string } {
+	const role = currentCrewRole();
+	if (!role) return { allowed: true };
+	if (permissionForRole(role) === "read_only")
+		return {
+			allowed: false,
+			reason: `Role '${role}' is read-only and cannot approve or cancel plan gates.`,
+		};
+	return { allowed: true };
+}
+
+export const handleApprovePlan: ApiOperationHandler = async (hctx) => {
+	const { loaded, result, ctx } = hctx;
+	const permission = canApprovePlan();
+	if (!permission.allowed)
+		return result(
+			permission.reason ?? "Plan approval is not allowed in this context.",
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	try {
+		return await withRunLock(loaded.manifest, async () => {
+			const current = loadRunManifestById(ctx.cwd, loaded.manifest.runId) ?? loaded; // NOTE: inside withRunLock - consistent read
+			const approval = current.manifest.planApproval;
+			if (!approval?.required || approval.status !== "pending")
+				return result(
+					"Run has no pending plan approval request.",
+					{
+						action: "api",
+						status: "error",
+						runId: loaded.manifest.runId,
+					},
+					true,
+				);
+			const now = new Date().toISOString();
+			const manifest = {
+				...current.manifest,
+				updatedAt: now,
+				planApproval: {
+					...approval,
+					status: "approved" as const,
+					approvedAt: now,
+					updatedAt: now,
+				},
+			};
+			await saveRunManifestAsync(manifest);
+			appendEvent(manifest.eventsPath, {
+				type: "plan.approved",
+				runId: manifest.runId,
+				taskId: approval.planTaskId,
+				message: "Adaptive implementation plan approved; resume the run to execute mutating tasks.",
+				metadata: { provenance: "api" },
+			});
+			return result(JSON.stringify(manifest.planApproval, null, 2), {
+				action: "api",
+				status: "ok",
+				runId: manifest.runId,
+				artifactsRoot: 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,
+		);
+	}
+};
+
+export const handleCancelPlan: ApiOperationHandler = async (hctx) => {
+	const { loaded, result, ctx } = hctx;
+	const permission = canApprovePlan();
+	if (!permission.allowed)
+		return result(
+			permission.reason ?? "Plan approval cancellation is not allowed in this context.",
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	try {
+		return await withRunLock(loaded.manifest, async () => {
+			const current = loadRunManifestById(ctx.cwd, loaded.manifest.runId) ?? loaded; // NOTE: inside withRunLock - consistent read
+			const approval = current.manifest.planApproval;
+			if (!approval?.required || approval.status !== "pending")
+				return result(
+					"Run has no pending plan approval request.",
+					{
+						action: "api",
+						status: "error",
+						runId: loaded.manifest.runId,
+					},
+					true,
+				);
+			const now = new Date().toISOString();
+			const tasks = current.tasks.map((task) =>
+				task.status === "queued" || task.status === "running" || task.status === "waiting"
+					? {
+							...task,
+							status: "cancelled" as const,
+							finishedAt: now,
+							error: "Plan approval was cancelled.",
+						}
+					: task,
+			);
+			let manifest: typeof current.manifest = {
+				...current.manifest,
+				updatedAt: now,
+				planApproval: {
+					...approval,
+					status: "cancelled" as const,
+					cancelledAt: now,
+					updatedAt: now,
+				},
+			};
+			await saveRunManifestAsync(manifest);
+			saveRunTasks(manifest, tasks);
+			appendEvent(manifest.eventsPath, {
+				type: "plan.cancelled",
+				runId: manifest.runId,
+				taskId: approval.planTaskId,
+				message: "Adaptive implementation plan was cancelled.",
+				metadata: { provenance: "api" },
+			});
+			manifest = updateRunStatus(manifest, "cancelled", "Plan approval was cancelled.");
+			void terminateLiveAgentsForRun(manifest.runId, "cancelled", appendEvent, manifest.eventsPath).catch((error) =>
+				logInternalError("team-tool.cancel-plan.terminate", error, `runId=${manifest.runId}`),
+			);
+			return result(
+				JSON.stringify(
+					{
+						planApproval: manifest.planApproval,
+						cancelledTasks: tasks.filter((task) => task.status === "cancelled").map((task) => task.id),
+					},
+					null,
+					2,
+				),
+				{
+					action: "api",
+					status: "ok",
+					runId: manifest.runId,
+					artifactsRoot: 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,
+		);
+	}
+};
+
+/** Dispatcher map for the plan-approval group. Consumed by handleApi. */
+export const PLAN_APPROVAL_OPERATIONS: Record<string, ApiOperationHandler> = {
+	"approve-plan": handleApprovePlan,
+	"cancel-plan": handleCancelPlan,
+};