pi-subagents 0.25.0 → 0.28.0

package/src/runs/foreground/subagent-executor.ts

@@ -21,6 +21,7 @@ import {
 	writeInitialProgressFile,
 	getStepAgents,
 	isParallelStep,
+	isDynamicParallelStep,
 	resolveStepBehavior,
 	suppressProgressForReadOnlyTask,
 	taskDisallowsFileUpdates,
@@ -52,6 +53,7 @@ import { resolveSubagentRunId, type ResolvedSubagentRunId } from "../background/
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { inspectSubagentStatus } from "../background/run-status.ts";
 import { applyForceTopLevelAsyncOverride } from "../background/top-level-async.ts";
+import { validateAcceptanceInput } from "../shared/acceptance.ts";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -63,6 +65,7 @@ import {
 } from "../shared/worktree.ts";
 import {
 	type AgentProgress,
+	type AcceptanceInput,
 	type ArtifactConfig,
 	type ArtifactPaths,
 	type ControlConfig,
@@ -103,6 +106,7 @@ interface TaskParam {
 	progress?: boolean;
 	model?: string;
 	skill?: string | string[] | boolean;
+	acceptance?: AcceptanceInput;
 }
 
 export interface SubagentParamsLike {
@@ -117,6 +121,8 @@ export interface SubagentParamsLike {
 	chain?: ChainStep[];
 	tasks?: TaskParam[];
 	concurrency?: number;
+	timeoutMs?: number;
+	maxRuntimeMs?: number;
 	worktree?: boolean;
 	context?: "fresh" | "fork";
 	async?: boolean;
@@ -134,6 +140,7 @@ export interface SubagentParamsLike {
 	outputMode?: "inline" | "file-only";
 	agentScope?: unknown;
 	chainDir?: string;
+	acceptance?: AcceptanceInput;
 }
 
 interface ExecutorDeps {
@@ -164,6 +171,7 @@ interface ExecutionContextData {
 	artifactsDir: string;
 	backgroundRequestedWhileClarifying: boolean;
 	effectiveAsync: boolean;
+	foregroundTimeoutMs?: number;
 	controlConfig: ResolvedControlConfig;
 	intercomBridge: IntercomBridgeState;
 	nestedRoute?: NestedRouteInfo;
@@ -245,7 +253,7 @@ function rememberForegroundRun(state: SubagentState, input: { runId: string; mod
 		children: input.results.map((result, index) => ({
 			agent: result.agent,
 			index,
-			status: resolveSubagentResultStatus({ exitCode: result.exitCode, interrupted: result.interrupted, detached: result.detached }),
+			status: resolveSubagentResultStatus({ exitCode: result.exitCode, interrupted: result.interrupted, detached: result.detached, timedOut: result.timedOut }),
 			...(result.sessionFile ? { sessionFile: result.sessionFile } : {}),
 		})),
 	});
@@ -711,6 +719,7 @@ async function emitForegroundResultIntercom(input: {
 			exitCode: result.exitCode,
 			interrupted: result.interrupted,
 			detached: result.detached,
+			timedOut: result.timedOut,
 		}),
 		summary: resultSummaryForIntercom(result),
 		index,
@@ -756,6 +765,51 @@ async function maybeBuildForegroundIntercomReceipt(input: {
 	};
 }
 
+function validationErrorResult(mode: Details["mode"], text: string): AgentToolResult<Details> {
+	return { content: [{ type: "text", text }], isError: true, details: { mode, results: [] } };
+}
+
+function resolveForegroundTimeoutMs(params: SubagentParamsLike): { timeoutMs?: number; error?: string } {
+	const rawTimeout = (params as { timeoutMs?: unknown }).timeoutMs;
+	const rawMaxRuntime = (params as { maxRuntimeMs?: unknown }).maxRuntimeMs;
+	for (const [name, value] of [["timeoutMs", rawTimeout], ["maxRuntimeMs", rawMaxRuntime]] as const) {
+		if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+			return { error: `${name} must be a positive integer.` };
+		}
+	}
+	if (rawTimeout !== undefined && rawMaxRuntime !== undefined && rawTimeout !== rawMaxRuntime) {
+		return { error: "timeoutMs and maxRuntimeMs are aliases; provide only one or use identical values." };
+	}
+	const timeoutMs = rawTimeout ?? rawMaxRuntime;
+	return timeoutMs === undefined ? {} : { timeoutMs };
+}
+
+function validateAcceptanceForExecution(params: SubagentParamsLike): AgentToolResult<Details> | null {
+	const topLevelErrors = validateAcceptanceInput(params.acceptance);
+	if (topLevelErrors.length > 0) return validationErrorResult("single", topLevelErrors.join(" "));
+	for (const [index, task] of (params.tasks ?? []).entries()) {
+		const errors = validateAcceptanceInput(task.acceptance, `tasks[${index}].acceptance`);
+		if (errors.length > 0) return validationErrorResult("parallel", errors.join(" "));
+	}
+	for (const [stepIndex, step] of (params.chain ?? []).entries()) {
+		if (isParallelStep(step)) {
+			if (Object.hasOwn(step, "acceptance")) return validationErrorResult("chain", `chain[${stepIndex}].acceptance is not supported on static parallel groups; set acceptance on each parallel task.`);
+			for (const [taskIndex, task] of step.parallel.entries()) {
+				const errors = validateAcceptanceInput(task.acceptance, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`);
+				if (errors.length > 0) return validationErrorResult("chain", errors.join(" "));
+			}
+		} else if (isDynamicParallelStep(step)) {
+			if (Object.hasOwn(step, "acceptance")) return validationErrorResult("chain", `chain[${stepIndex}].acceptance is not supported on dynamic fanout groups; set acceptance on chain[${stepIndex}].parallel.acceptance for each materialized child.`);
+			const errors = validateAcceptanceInput(step.parallel.acceptance, `chain[${stepIndex}].parallel.acceptance`);
+			if (errors.length > 0) return validationErrorResult("chain", errors.join(" "));
+		} else {
+			const stepErrors = validateAcceptanceInput(step.acceptance, `chain[${stepIndex}].acceptance`);
+			if (stepErrors.length > 0) return validationErrorResult("chain", stepErrors.join(" "));
+		}
+	}
+	return null;
+}
+
 function validateExecutionInput(
 	params: SubagentParamsLike,
 	agents: AgentConfig[],
@@ -764,6 +818,9 @@ function validateExecutionInput(
 	hasSingle: boolean,
 	allowClarifyTaskPrompt: boolean,
 ): AgentToolResult<Details> | null {
+	const acceptanceError = validateAcceptanceForExecution(params);
+	if (acceptanceError) return acceptanceError;
+
 	if (Number(hasChain) + Number(hasTasks) + Number(hasSingle) !== 1) {
 		return {
 			content: [
@@ -777,6 +834,9 @@ function validateExecutionInput(
 		};
 	}
 
+	const timeoutResolution = resolveForegroundTimeoutMs(params);
+	if (timeoutResolution.error) return validationErrorResult(getRequestedModeLabel(params), timeoutResolution.error);
+
 	if (hasSingle && params.agent && !agents.find((agent) => agent.name === params.agent)) {
 		return {
 			content: [{ type: "text", text: `Unknown agent: ${params.agent}` }],
@@ -816,6 +876,12 @@ function validateExecutionInput(
 					details: { mode: "chain" as const, results: [] },
 				};
 			}
+		} else if (isDynamicParallelStep(firstStep)) {
+			return {
+				content: [{ type: "text", text: "First step in chain cannot be dynamic fanout; expand.from requires a prior structured named output" }],
+				isError: true,
+				details: { mode: "chain" as const, results: [] },
+			};
 		} else if (!(firstStep as SequentialStep).task && !params.task && !allowClarifyTaskPrompt) {
 			return {
 				content: [{ type: "text", text: "First step in chain must have a task" }],
@@ -977,6 +1043,10 @@ function collectChainSessionFiles(
 			}
 			continue;
 		}
+		if (isDynamicParallelStep(step)) {
+			sessionFiles.push(undefined);
+			continue;
+		}
 		sessionFiles.push(sessionFileForIndex(flatIndex));
 		flatIndex++;
 	}
@@ -995,6 +1065,15 @@ function wrapChainTasksForFork(chain: ChainStep[], context: SubagentParamsLike["
 				})),
 			};
 		}
+		if (isDynamicParallelStep(step)) {
+			return {
+				...step,
+				parallel: {
+					...step.parallel,
+					task: wrapForkTask(step.parallel.task ?? "{previous}"),
+				},
+			};
+		}
 		const sequential = step as SequentialStep;
 		return {
 			...sequential,
@@ -1082,6 +1161,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			...(task.outputMode !== undefined ? { outputMode: task.outputMode } : {}),
 			...(task.reads !== undefined && task.reads !== true ? { reads: task.reads } : {}),
 			...(task.progress !== undefined ? { progress: task.progress } : {}),
+			...(task.acceptance !== undefined ? { acceptance: task.acceptance } : {}),
 		}));
 		return executeAsyncChain(id, {
 			chain: [{
@@ -1129,6 +1209,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			sessionRoot,
 			chainSkills,
 			sessionFilesByFlatIndex: collectChainSessionFiles(chain, sessionFileForIndex),
+			dynamicFanoutMaxItems: deps.config.chain?.dynamicFanout?.maxItems,
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
@@ -1179,6 +1260,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			controlIntercomTarget,
 			childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(agent, index) : undefined,
 			nestedRoute,
+			acceptance: params.acceptance,
 		});
 	}
 
@@ -1228,12 +1310,14 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		onUpdate,
 		onControlEvent,
 		controlConfig,
+		...(data.foregroundTimeoutMs !== undefined ? { timeoutMs: data.foregroundTimeoutMs } : {}),
 		childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(runId, agent, index) : undefined,
 		orchestratorIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
 		foregroundControl,
 		nestedRoute: foregroundControl?.nestedRoute,
 		chainSkills,
 		chainDir: params.chainDir,
+		dynamicFanoutMaxItems: deps.config.chain?.dynamicFanout?.maxItems,
 		maxSubagentDepth: currentMaxSubagentDepth,
 		worktreeSetupHook: deps.config.worktreeSetupHook,
 		worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
@@ -1269,6 +1353,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			sessionRoot,
 			chainSkills: chainResult.requestedAsync.chainSkills,
 			sessionFilesByFlatIndex: collectChainSessionFiles(asyncChain, sessionFileForIndex),
+			dynamicFanoutMaxItems: deps.config.chain?.dynamicFanout?.maxItems,
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
@@ -1282,7 +1367,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 	const chainDetails = chainResult.details ? compactForegroundDetails({ ...chainResult.details, runId }) : undefined;
 	if (foregroundControl) updateForegroundNestedProjection(foregroundControl);
 	if (chainDetails) rememberForegroundRun(deps.state, { runId, mode: "chain", cwd: effectiveCwd, results: chainDetails.results });
-	const intercomReceipt = chainDetails && !chainDetails.results.some((result) => result.interrupted || result.detached)
+	const intercomReceipt = chainDetails && !chainDetails.results.some((result) => result.interrupted || result.detached || result.timedOut)
 		? await maybeBuildForegroundIntercomReceipt({
 			pi: deps.pi,
 			intercomBridge: data.intercomBridge,
@@ -1317,6 +1402,8 @@ interface ForegroundParallelRunInput {
 	artifactConfig: ArtifactConfig;
 	artifactsDir: string;
 	maxOutput?: MaxOutputConfig;
+	timeoutMs?: number;
+	timeoutAt?: number;
 	paramsCwd: string;
 	maxSubagentDepths: number[];
 	availableModels: ModelInfo[];
@@ -1469,6 +1556,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			cwd: taskCwd,
 			signal: input.signal,
 			interruptSignal: interruptController.signal,
+			...(input.timeoutMs !== undefined && input.timeoutAt !== undefined ? { timeoutMs: input.timeoutMs, timeoutAt: input.timeoutAt } : {}),
 			allowIntercomDetach: agentConfig?.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 			intercomEvents: input.intercomEvents,
 			runId: input.runId,
@@ -1482,6 +1570,8 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			outputPath,
 			outputMode: behavior?.outputMode,
 			maxSubagentDepth: input.maxSubagentDepths[index],
+			maxExecutionTimeMs: agentConfig?.maxExecutionTimeMs,
+			maxTokens: agentConfig?.maxTokens,
 			controlConfig: input.controlConfig,
 			onControlEvent: input.onControlEvent,
 			intercomSessionName: input.childIntercomTarget?.(task.agent, index),
@@ -1491,6 +1581,8 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			availableModels: input.availableModels,
 			preferredModelProvider: input.ctx.model?.provider,
 			skills: effectiveSkills === false ? [] : effectiveSkills,
+			acceptance: task.acceptance,
+			acceptanceContext: { mode: "parallel" },
 				onUpdate: input.onUpdate
 					? (progressUpdate) => {
 						const stepResults = progressUpdate.details?.results || [];
@@ -1680,6 +1772,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 					...(behaviorOverrides[i]?.outputMode !== undefined ? { outputMode: behaviorOverrides[i]!.outputMode } : {}),
 					...(behaviorOverrides[i]?.reads !== undefined ? { reads: behaviorOverrides[i]!.reads } : {}),
 					...(progress !== undefined ? { progress } : {}),
+					...(t.acceptance !== undefined ? { acceptance: t.acceptance } : {}),
 				};
 			});
 			return executeAsyncChain(id, {
@@ -1746,6 +1839,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			}
 		}
 
+		const timeoutAt = data.foregroundTimeoutMs !== undefined ? Date.now() + data.foregroundTimeoutMs : undefined;
 		const results = await runForegroundParallelTasks({
 			tasks,
 			taskTexts,
@@ -1760,6 +1854,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			artifactConfig,
 			artifactsDir,
 			maxOutput: params.maxOutput,
+			...(data.foregroundTimeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: data.foregroundTimeoutMs, timeoutAt } : {}),
 			paramsCwd: effectiveCwd,
 			availableModels,
 			modelOverrides,
@@ -1787,6 +1882,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 		}
 
+		const timedOut = results.find((result) => result.timedOut);
 		const interrupted = results.find((result) => result.interrupted);
 		const details = compactForegroundDetails({
 			mode: "parallel",
@@ -1796,6 +1892,13 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			artifacts: allArtifactPaths.length ? { dir: artifactsDir, files: allArtifactPaths } : undefined,
 		});
 		rememberForegroundRun(deps.state, { runId, mode: "parallel", cwd: effectiveCwd, results: details.results });
+		if (timedOut) {
+			return {
+				content: [{ type: "text", text: `Parallel run timed out (${timedOut.agent}): ${timedOut.error ?? "timeout expired"}` }],
+				details,
+				isError: true,
+			};
+		}
 		if (interrupted) {
 			return {
 				content: [{ type: "text", text: `Parallel run paused after interrupt (${interrupted.agent}). Waiting for explicit next action.` }],
@@ -2026,10 +2129,12 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		}
 		: undefined;
 
+	const timeoutAt = data.foregroundTimeoutMs !== undefined ? Date.now() + data.foregroundTimeoutMs : undefined;
 	const r = await runSync(ctx.cwd, agents, params.agent!, task, {
 		cwd: effectiveCwd,
 		signal,
 		interruptSignal: interruptController.signal,
+		...(data.foregroundTimeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: data.foregroundTimeoutMs, timeoutAt } : {}),
 		allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 		intercomEvents: deps.pi.events,
 		runId,
@@ -2042,6 +2147,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		outputPath,
 		outputMode: effectiveOutputMode,
 		maxSubagentDepth,
+		maxExecutionTimeMs: agentConfig.maxExecutionTimeMs,
+		maxTokens: agentConfig.maxTokens,
 		onUpdate: forwardSingleUpdate,
 		controlConfig,
 		onControlEvent,
@@ -2053,6 +2160,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		availableModels,
 		preferredModelProvider: currentProvider,
 		skills: effectiveSkills,
+		acceptance: params.acceptance,
+		acceptanceContext: { mode: "single" },
 	});
 	if (foregroundControl?.currentIndex === 0) {
 		foregroundControl.interrupt = undefined;
@@ -2092,7 +2201,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	});
 	rememberForegroundRun(deps.state, { runId, mode: "single", cwd: effectiveCwd, results: details.results });
 
-	if (!r.detached && !r.interrupted) {
+	if (!r.detached && !r.interrupted && !r.timedOut) {
 		if (foregroundControl) updateForegroundNestedProjection(foregroundControl);
 		const intercomReceipt = await maybeBuildForegroundIntercomReceipt({
 			pi: deps.pi,
@@ -2118,6 +2227,14 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		};
 	}
 
+	if (r.timedOut) {
+		return {
+			content: [{ type: "text", text: `Run timed out (${params.agent}): ${r.error ?? "timeout expired"}` }],
+			details,
+			isError: true,
+		};
+	}
+
 	if (r.interrupted) {
 		return {
 			content: [{ type: "text", text: `Run paused after interrupt (${params.agent}). Waiting for explicit next action.` }],
@@ -2345,6 +2462,11 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const requestedAsync = effectiveParams.async ?? deps.asyncByDefault;
 		const backgroundRequestedWhileClarifying = (hasChain || hasTasks) && requestedAsync && effectiveParams.clarify === true;
 		const effectiveAsync = requestedAsync && effectiveParams.clarify !== true;
+		const foregroundTimeout = resolveForegroundTimeoutMs(effectiveParams);
+		if (foregroundTimeout.error) return buildRequestedModeError(effectiveParams, foregroundTimeout.error);
+		if (effectiveAsync && foregroundTimeout.timeoutMs !== undefined) {
+			return buildRequestedModeError(effectiveParams, "timeoutMs/maxRuntimeMs only applies to foreground subagent runs. Omit async:true or use action:'interrupt' for background runs.");
+		}
 		const controlConfig = resolveControlConfig(deps.config.control, effectiveParams.control);
 
 		const artifactConfig: ArtifactConfig = {
@@ -2396,6 +2518,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			artifactsDir,
 			backgroundRequestedWhileClarifying,
 			effectiveAsync,
+			...(foregroundTimeout.timeoutMs !== undefined ? { foregroundTimeoutMs: foregroundTimeout.timeoutMs } : {}),
 			controlConfig,
 			intercomBridge,
 			nestedRoute,