pi-subagents 0.17.4 → 0.18.0

package/chain-execution.ts

@@ -40,10 +40,13 @@ import {
 	type WorktreeSetup,
 } from "./worktree.ts";
 import {
+	type ActivityState,
 	type AgentProgress,
 	type ArtifactConfig,
 	type ArtifactPaths,
+	type ControlEvent,
 	type Details,
+	type ResolvedControlConfig,
 	type SingleResult,
 	MAX_CONCURRENCY,
 	resolveChildMaxSubagentDepth,
@@ -82,6 +85,19 @@ interface ParallelChainRunInput {
 	artifactsDir: string;
 	signal?: AbortSignal;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig: ResolvedControlConfig;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	foregroundControl?: {
+		updatedAt: number;
+		currentAgent?: string;
+		currentIndex?: number;
+		currentActivityState?: ActivityState;
+		lastActivityAt?: number;
+		currentTool?: string;
+		currentToolStartedAt?: number;
+		interrupt?: () => boolean;
+	};
 	results: SingleResult[];
 	allProgress: AgentProgress[];
 	chainAgents: string[];
@@ -186,10 +202,25 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 			const outputPath = typeof behavior.output === "string"
 				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(input.chainDir, behavior.output))
 				: undefined;
+			const interruptController = new AbortController();
+			if (input.foregroundControl) {
+				input.foregroundControl.currentAgent = task.agent;
+				input.foregroundControl.currentIndex = input.globalTaskIndex + taskIndex;
+				input.foregroundControl.currentActivityState = undefined;
+				input.foregroundControl.updatedAt = Date.now();
+				input.foregroundControl.interrupt = () => {
+					if (interruptController.signal.aborted) return false;
+					interruptController.abort();
+					input.foregroundControl!.currentActivityState = undefined;
+					input.foregroundControl!.updatedAt = Date.now();
+					return true;
+				};
+			}
 
 			const result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
 				cwd: taskCwd,
 				signal: input.signal,
+				interruptSignal: interruptController.signal,
 				runId: input.runId,
 				index: input.globalTaskIndex + taskIndex,
 				sessionDir: input.sessionDirForIndex(input.globalTaskIndex + taskIndex),
@@ -199,28 +230,46 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				artifactConfig: input.artifactConfig,
 				outputPath,
 				maxSubagentDepth,
+				controlConfig: input.controlConfig,
+				onControlEvent: input.onControlEvent,
+				intercomSessionName: input.childIntercomTarget?.(task.agent, input.globalTaskIndex + taskIndex),
 				modelOverride: effectiveModel,
 				availableModels: input.availableModels,
 				preferredModelProvider: input.ctx.model?.provider,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: input.onUpdate
 					? (progressUpdate) => {
-							const stepResults = progressUpdate.details?.results || [];
-							const stepProgress = progressUpdate.details?.progress || [];
-							input.onUpdate?.({
-								...progressUpdate,
-								details: {
-									mode: "chain",
-									results: input.results.concat(stepResults),
-									progress: input.allProgress.concat(stepProgress),
-									chainAgents: input.chainAgents,
-									totalSteps: input.totalSteps,
-									currentStepIndex: input.stepIndex,
-								},
-							});
+						const stepResults = progressUpdate.details?.results || [];
+						const stepProgress = progressUpdate.details?.progress || [];
+						if (input.foregroundControl && stepProgress.length > 0) {
+							const current = stepProgress[0];
+							input.foregroundControl.currentAgent = task.agent;
+							input.foregroundControl.currentIndex = input.globalTaskIndex + taskIndex;
+							input.foregroundControl.currentActivityState = current?.activityState;
+							input.foregroundControl.lastActivityAt = current?.lastActivityAt;
+							input.foregroundControl.currentTool = current?.currentTool;
+							input.foregroundControl.currentToolStartedAt = current?.currentToolStartedAt;
+							input.foregroundControl.updatedAt = Date.now();
 						}
+						input.onUpdate?.({
+							...progressUpdate,
+							details: {
+								mode: "chain",
+								results: input.results.concat(stepResults),
+								progress: input.allProgress.concat(stepProgress),
+								controlEvents: progressUpdate.details?.controlEvents,
+								chainAgents: input.chainAgents,
+								totalSteps: input.totalSteps,
+								currentStepIndex: input.stepIndex,
+							},
+						});
+					}
 					: undefined,
 			});
+			if (input.foregroundControl?.currentIndex === input.globalTaskIndex + taskIndex) {
+				input.foregroundControl.interrupt = undefined;
+				input.foregroundControl.updatedAt = Date.now();
+			}
 
 			if (result.exitCode !== 0 && failFast) {
 				aborted = true;
@@ -249,6 +298,19 @@ export interface ChainExecutionParams {
 	includeProgress?: boolean;
 	clarify?: boolean;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig: ResolvedControlConfig;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	foregroundControl?: {
+		updatedAt: number;
+		currentAgent?: string;
+		currentIndex?: number;
+		currentActivityState?: ActivityState;
+		lastActivityAt?: number;
+		currentTool?: string;
+		currentToolStartedAt?: number;
+		interrupt?: () => boolean;
+	};
 	chainSkills?: string[];
 	chainDir?: string;
 	maxSubagentDepth: number;
@@ -286,6 +348,10 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		includeProgress,
 		clarify,
 		onUpdate,
+		onControlEvent,
+		controlConfig,
+		childIntercomTarget,
+		foregroundControl,
 		chainSkills: chainSkillsParam,
 		chainDir: chainDirBase,
 	} = params;
@@ -484,6 +550,10 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					allProgress,
 					chainAgents,
 					totalSteps,
+					controlConfig,
+					onControlEvent,
+					childIntercomTarget,
+					foregroundControl,
 					worktreeSetup,
 					maxSubagentDepth: params.maxSubagentDepth,
 				});
@@ -495,6 +565,23 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 				}
 
+				const interrupted = parallelResults.find((result) => result.interrupted);
+				if (interrupted) {
+					return {
+						content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${interrupted.agent}). Waiting for explicit next action.` }],
+						details: buildChainExecutionDetails({
+							results,
+							includeProgress,
+							allProgress,
+							allArtifactPaths,
+							artifactsDir,
+							chainAgents,
+							totalSteps,
+							currentStepIndex: stepIndex,
+						}),
+					};
+				}
+
 				const failures = parallelResults
 					.map((result, originalIndex) => ({ ...result, originalIndex }))
 					.filter((result) => result.exitCode !== 0 && result.exitCode !== -1);
@@ -603,10 +690,25 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
 				: undefined;
 			const maxSubagentDepth = resolveChildMaxSubagentDepth(params.maxSubagentDepth, agentConfig.maxSubagentDepth);
+			const interruptController = new AbortController();
+			if (foregroundControl) {
+				foregroundControl.currentAgent = seqStep.agent;
+				foregroundControl.currentIndex = globalTaskIndex;
+				foregroundControl.currentActivityState = undefined;
+				foregroundControl.updatedAt = Date.now();
+				foregroundControl.interrupt = () => {
+					if (interruptController.signal.aborted) return false;
+					interruptController.abort();
+					foregroundControl.currentActivityState = undefined;
+					foregroundControl.updatedAt = Date.now();
+					return true;
+				};
+			}
 
 			const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 				cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),
 				signal,
+				interruptSignal: interruptController.signal,
 				runId,
 				index: globalTaskIndex,
 				sessionDir: sessionDirForIndex(globalTaskIndex),
@@ -616,28 +718,46 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				artifactConfig,
 				outputPath,
 				maxSubagentDepth,
+				controlConfig,
+				onControlEvent,
+				intercomSessionName: childIntercomTarget?.(seqStep.agent, globalTaskIndex),
 				modelOverride: effectiveModel,
 				availableModels,
 				preferredModelProvider: ctx.model?.provider,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: onUpdate
 					? (p) => {
-							const stepResults = p.details?.results || [];
-							const stepProgress = p.details?.progress || [];
-							onUpdate({
-								...p,
-								details: {
-									mode: "chain",
-									results: results.concat(stepResults),
-									progress: allProgress.concat(stepProgress),
-									chainAgents,
-									totalSteps,
-									currentStepIndex: stepIndex,
-								},
-							});
+						const stepResults = p.details?.results || [];
+						const stepProgress = p.details?.progress || [];
+						if (foregroundControl && stepProgress.length > 0) {
+							const current = stepProgress[0];
+							foregroundControl.currentAgent = seqStep.agent;
+							foregroundControl.currentIndex = globalTaskIndex;
+							foregroundControl.currentActivityState = current?.activityState;
+							foregroundControl.lastActivityAt = current?.lastActivityAt;
+							foregroundControl.currentTool = current?.currentTool;
+							foregroundControl.currentToolStartedAt = current?.currentToolStartedAt;
+							foregroundControl.updatedAt = Date.now();
 						}
+						onUpdate({
+							...p,
+							details: {
+								mode: "chain",
+								results: results.concat(stepResults),
+								progress: allProgress.concat(stepProgress),
+								controlEvents: p.details?.controlEvents,
+								chainAgents,
+								totalSteps,
+								currentStepIndex: stepIndex,
+							},
+						});
+					}
 					: undefined,
 			});
+			if (foregroundControl?.currentIndex === globalTaskIndex) {
+				foregroundControl.interrupt = undefined;
+				foregroundControl.updatedAt = Date.now();
+			}
 			recordRun(seqStep.agent, cleanTask, r.exitCode, r.progressSummary?.durationMs ?? 0);
 
 			globalTaskIndex++;
@@ -663,6 +783,22 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				}
 			}
 
+			if (r.interrupted) {
+				return {
+					content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${r.agent}). Waiting for explicit next action.` }],
+					details: buildChainExecutionDetails({
+						results,
+						includeProgress,
+						allProgress,
+						allArtifactPaths,
+						artifactsDir,
+						chainAgents,
+						totalSteps,
+						currentStepIndex: stepIndex,
+					}),
+				};
+			}
+
 			if (r.exitCode !== 0) {
 				const summary = buildChainSummary(chainSteps, results, chainDir, "failed", {
 					index: stepIndex,

package/execution.ts

@@ -14,6 +14,7 @@ import {
 import {
 	type AgentProgress,
 	type ArtifactPaths,
+	type ControlEvent,
 	type ModelAttempt,
 	type RunSyncOptions,
 	type SingleResult,
@@ -24,6 +25,14 @@ import {
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "./types.ts";
+import {
+	DEFAULT_CONTROL_CONFIG,
+	buildControlEvent,
+	claimControlNotification,
+	deriveActivityState,
+	shouldEmitControlEvent,
+	shouldNotifyControlEvent,
+} from "./subagent-control.ts";
 import {
 	getFinalOutput,
 	findLatestSessionFile,
@@ -86,6 +95,7 @@ function snapshotResult(result: SingleResult, progress: AgentProgress): SingleRe
 				usage: attempt.usage ? { ...attempt.usage } : undefined,
 			}))
 			: undefined,
+		controlEvents: result.controlEvents ? result.controlEvents.map((event) => ({ ...event })) : undefined,
 		progress,
 		progressSummary: result.progressSummary ? { ...result.progressSummary } : undefined,
 		artifactPaths: result.artifactPaths ? { ...result.artifactPaths } : undefined,
@@ -127,6 +137,7 @@ async function runSingleAttempt(
 		systemPrompt: shared.systemPrompt,
 		mcpDirectTools: agent.mcpDirectTools,
 		promptFileStem: agent.name,
+		intercomSessionName: options.intercomSessionName,
 	});
 
 	const result: SingleResult = {
@@ -140,6 +151,11 @@ async function runSingleAttempt(
 		skills: shared.resolvedSkillNames,
 		skillsWarning: shared.skillsWarning,
 	};
+	const startTime = Date.now();
+	const controlConfig = options.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+	let interruptedByControl = false;
+	const allControlEvents: ControlEvent[] = [];
+	let pendingControlEvents: ControlEvent[] = [];
 
 	const progress: AgentProgress = {
 		index: options.index ?? 0,
@@ -152,11 +168,9 @@ async function runSingleAttempt(
 		toolCount: 0,
 		tokens: 0,
 		durationMs: 0,
-		lastActivityAt: Date.now(),
+		lastActivityAt: startTime,
 	};
 	result.progress = progress;
-
-	const startTime = Date.now();
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 
 	const exitCode = await new Promise<number>((resolve) => {
@@ -173,6 +187,8 @@ async function runSingleAttempt(
 		let detached = false;
 		let intercomStarted = false;
 		let removeAbortListener: (() => void) | undefined;
+		let removeInterruptListener: (() => void) | undefined;
+		let activityTimer: NodeJS.Timeout | undefined;
 
 		const detachForIntercom = () => {
 			detached = true;
@@ -241,18 +257,69 @@ async function runSingleAttempt(
 			settled = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
+			if (activityTimer) {
+				clearInterval(activityTimer);
+				activityTimer = undefined;
+			}
 			unsubscribeIntercomDetach?.();
 			removeAbortListener?.();
+			removeInterruptListener?.();
 			resolve(code);
 		};
 
+		const drainPendingControlEvents = (): ControlEvent[] | undefined => {
+			if (pendingControlEvents.length === 0) return undefined;
+			const events = pendingControlEvents;
+			pendingControlEvents = [];
+			return events;
+		};
+
+		const emittedControlEventKeys = new Set<string>();
+		const emitControlEvent = (event: ControlEvent) => {
+			if (shouldNotifyControlEvent(controlConfig, event) && !claimControlNotification(controlConfig, event, emittedControlEventKeys)) return;
+			allControlEvents.push(event);
+			pendingControlEvents.push(event);
+			options.onControlEvent?.(event);
+		};
+
+		const updateActivityState = (now: number): boolean => {
+			const next = deriveActivityState({
+				config: controlConfig,
+				startedAt: startTime,
+				lastActivityAt: progress.lastActivityAt,
+				now,
+			});
+			if (next === progress.activityState) return false;
+			const previous = progress.activityState;
+			progress.activityState = next;
+			if (shouldEmitControlEvent(controlConfig, previous, next)) {
+				emitControlEvent(buildControlEvent({
+					from: previous,
+					to: next,
+					runId: options.runId,
+					agent: agent.name,
+					index: options.index,
+					ts: now,
+					lastActivityAt: progress.lastActivityAt,
+				}));
+			}
+			return true;
+		};
+
+
 		const emitUpdateSnapshot = (text: string) => {
 			if (!options.onUpdate || processClosed) return;
 			const progressSnapshot = snapshotProgress(progress);
 			const resultSnapshot = snapshotResult(result, progressSnapshot);
+			const controlEvents = drainPendingControlEvents();
 			options.onUpdate({
 				content: [{ type: "text", text }],
-				details: { mode: "single", results: [resultSnapshot], progress: [progressSnapshot] },
+				details: {
+					mode: "single",
+					results: [resultSnapshot],
+					progress: [progressSnapshot],
+					controlEvents,
+				},
 			});
 		};
 
@@ -276,6 +343,7 @@ async function runSingleAttempt(
 			const now = Date.now();
 			progress.durationMs = now - startTime;
 			progress.lastActivityAt = now;
+			updateActivityState(now);
 
 			if (evt.type === "tool_execution_start") {
 				if (options.allowIntercomDetach && evt.toolName === "intercom") {
@@ -336,6 +404,18 @@ async function runSingleAttempt(
 			}
 		};
 
+		if (controlConfig.enabled) {
+			activityTimer = setInterval(() => {
+				if (processClosed || settled || detached) return;
+				const now = Date.now();
+				if (updateActivityState(now)) {
+					progress.durationMs = now - startTime;
+					fireUpdate();
+				}
+			}, 1000);
+			activityTimer.unref?.();
+		}
+
 		let stderrBuf = "";
 
 		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
@@ -400,8 +480,46 @@ async function runSingleAttempt(
 				removeAbortListener = () => options.signal?.removeEventListener("abort", kill);
 			}
 		}
+
+		if (options.interruptSignal) {
+			const interrupt = () => {
+				if (processClosed || detached || settled) return;
+				interruptedByControl = true;
+				progress.status = "running";
+				progress.durationMs = Date.now() - startTime;
+				result.interrupted = true;
+				result.finalOutput = "Interrupted. Waiting for explicit next action.";
+				progress.activityState = undefined;
+				fireUpdate();
+				trySignalChild(proc, "SIGINT");
+				setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					trySignalChild(proc, "SIGTERM");
+				}, 1000).unref?.();
+			};
+			if (options.interruptSignal.aborted) interrupt();
+			else {
+				options.interruptSignal.addEventListener("abort", interrupt, { once: true });
+				removeInterruptListener = () => options.interruptSignal?.removeEventListener("abort", interrupt);
+			}
+		}
 	});
 	result.exitCode = exitCode;
+	if (interruptedByControl) {
+		result.exitCode = 0;
+		result.interrupted = true;
+		result.error = undefined;
+		result.finalOutput = result.finalOutput || "Interrupted. Waiting for explicit next action.";
+		result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
+		progress.activityState = undefined;
+		progress.durationMs = Date.now() - startTime;
+		result.progressSummary = {
+			toolCount: progress.toolCount,
+			tokens: progress.tokens,
+			durationMs: progress.durationMs,
+		};
+		return result;
+	}
 	if (result.detached) {
 		result.exitCode = 0;
 		result.finalOutput = "Detached for intercom coordination.";