@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/subagents.ts

@@ -4,10 +4,7 @@
  * Spawns a separate `pi` process for each subagent invocation,
  * giving it an isolated context window.
  *
- * Supports three modes:
- *   - Single: { agent: "name", task: "..." }
- *   - Parallel: { tasks: [{ agent: "name", task: "..." }, ...] }
- *   - Chain: { chain: [{ agent: "name", task: "... {previous} ..." }, ...] }
+ * Supports blocking single, parallel, chain, workflow, and panel modes.
  *
  * Uses JSON mode to capture structured output from subagents.
  */
@@ -25,10 +22,11 @@ import {
 	formatAgentCatalog,
 	type SubagentSettings,
 } from "./agents.js";
-import { registerSubagentConfigCommand } from "./config-ui.js";
+import { registerSubagentConfigCommand, registerSubagentConfigLifecycle } from "./config-ui.js";
 import { registerSubagentConsult } from "./consult.js";
 import { executeSubagent } from "./execution.js";
 import { registerSubagentInspect } from "./inspect.js";
+import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
 import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
 import type { SubagentDetails } from "./runner.js";
@@ -39,10 +37,12 @@ import {
 	DEFAULT_DELEGATION_CWD_POLICY,
 	inspectSubagentSettings,
 	readSubagentSettings,
+	resolveBlockingMaxParallelTasks,
 } from "./settings.js";
 import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
+	const configOwner = registerSubagentConfigLifecycle(pi);
 	const settings = readSubagentSettings();
 	let currentSettings: SubagentSettings | undefined = settings;
 	let currentCatalog = "";
@@ -80,6 +80,7 @@ export default function (pi: ExtensionAPI) {
 	});
 	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
 	const getBlockingEnabled = () => blockingEnabled;
+	const getMaxParallelTasks = () => resolveBlockingMaxParallelTasks(currentSettings);
 	const getConsultResourcePolicy = () =>
 		currentSettings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
 	const getConsultationCwdPolicy = () =>
@@ -89,6 +90,7 @@ export default function (pi: ExtensionAPI) {
 	registerSubagentInspect(pi, {
 		...statefulRuntime,
 		getBlockingEnabled,
+		getMaxParallelTasks,
 		getConsultResourcePolicy,
 		getConsultationCwdPolicy,
 		getDelegationCwdPolicy,
@@ -98,35 +100,61 @@ export default function (pi: ExtensionAPI) {
 			getSettings: () => currentSettings,
 		});
 	}
-	registerSubagentConfigCommand(pi, {
-		...statefulRuntime,
-		getBlockingEnabled,
-		getConsultResourcePolicy,
-		getConsultationCwdPolicy,
-		getDelegationCwdPolicy,
-		setConsultResourcePolicy(value: ConsultResourcePolicy) {
-			currentSettings = {
-				...(currentSettings ?? {}),
-				consult: { ...(currentSettings?.consult ?? {}), resources: value },
-			};
-			refreshConsultCatalog(currentCatalog);
+	registerSubagentConfigCommand(
+		pi,
+		{
+			...statefulRuntime,
+			getBlockingEnabled,
+			getMaxParallelTasks,
+			getConsultResourcePolicy,
+			getConsultationCwdPolicy,
+			getDelegationCwdPolicy,
+			setMaxParallelTasks(value: number) {
+				const previousSettings = currentSettings;
+				currentSettings = {
+					...(currentSettings ?? {}),
+					blocking: { ...(currentSettings?.blocking ?? {}), maxParallelTasks: value },
+				};
+				try {
+					refreshBlockingCatalog(currentCatalog);
+				} catch (applyError) {
+					currentSettings = previousSettings;
+					try {
+						refreshBlockingCatalog(currentCatalog);
+					} catch (rollbackError) {
+						throw new AggregateError(
+							[applyError, rollbackError],
+							"Failed to apply and roll back the parallel-worker limit",
+						);
+					}
+					throw applyError;
+				}
+			},
+			setConsultResourcePolicy(value: ConsultResourcePolicy) {
+				currentSettings = {
+					...(currentSettings ?? {}),
+					consult: { ...(currentSettings?.consult ?? {}), resources: value },
+				};
+				refreshConsultCatalog(currentCatalog);
+			},
+			setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
+				currentSettings = {
+					...(currentSettings ?? {}),
+					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
+				};
+				refreshConsultCatalog(currentCatalog);
+			},
+			setDelegationCwdPolicy(value: DelegationCwdPolicy) {
+				currentSettings = {
+					...(currentSettings ?? {}),
+					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
+				};
+				refreshBlockingCatalog(currentCatalog);
+				statefulRuntime.refreshSettingsGuidance();
+			},
 		},
-		setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
-			currentSettings = {
-				...(currentSettings ?? {}),
-				cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
-			};
-			refreshConsultCatalog(currentCatalog);
-		},
-		setDelegationCwdPolicy(value: DelegationCwdPolicy) {
-			currentSettings = {
-				...(currentSettings ?? {}),
-				cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
-			};
-			refreshBlockingCatalog(currentCatalog);
-			statefulRuntime.refreshSettingsGuidance();
-		},
-	});
+		configOwner,
+	);
 }
 
 function registerBlockingSubagent(
@@ -134,36 +162,70 @@ function registerBlockingSubagent(
 	getSettings: () => SubagentSettings | undefined,
 ): (catalog: string) => void {
 	let catalog = "";
+	const activeControllers = new Set<AbortController>();
+	const activeWork = new Set<Promise<unknown>>();
+	const cancelAndWaitForWork = async (reason: string) => {
+		for (const controller of activeControllers) {
+			controller.abort(new DOMException(reason, "AbortError"));
+		}
+		await Promise.allSettled([...activeWork]);
+	};
+	pi.on("session_start", () => cancelAndWaitForWork("Blocking subagent session replaced"));
+	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
 	const baseDescription = () =>
 		[
 			"Run specialized subagents as a blocking operation with isolated contexts.",
 			"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
-			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
-			"Parallel mode may include an aggregator fan-in step that receives all task outputs. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
+			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
+			"Parallel mode may include an aggregator fan-in step; workflow mode validates dependencies, authority, artifacts, scope conflicts, retries, and hedging before scheduling. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
 			'Default agent scope is "user" (from ~/.pi/agent/agents).',
 			`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.`,
+			`Maximum parallel worker tasks per call: ${resolveBlockingMaxParallelTasks(getSettings())}. Parallel execution starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} workers at once.`,
 			`Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`,
 		].join(" ");
+	const promptGuidelines = () => [
+		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
+		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
+		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
+		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
+		"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
+		"Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
+		"Use panel mode only for consequential review or research that benefits from at least two independent reviewers and one bounded synthesis; agreement is not proof, dissent and blocking objections remain visible, and simple or latency-sensitive work should not use a panel.",
+		'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
+		"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
+		"Set subagent timeoutMs to the shortest realistic work deadline for the task difficulty, just as thinkingLevel should match reasoning difficulty; split oversized tasks instead of extending the deadline merely to compensate for broad scope. Use totalTimeoutMs to cap an entire blocking workflow, idleTimeoutMs for stalled work, and maxTurns or maxToolCalls to stop repeated work without progress. Every budget stop preserves a bounded checkpoint and may make one separately bounded summary attempt.",
+	];
 	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
 		label: "Blocking Subagent",
 		description: appendAgentCatalog(baseDescription(), catalog),
 		promptSnippet:
 			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
-		promptGuidelines: [
-			"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
-			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
-			"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
-			"Use a blocking subagent single, parallel, chain, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
-			"If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the hard max 8, and avoid write-heavy implementation touching the same files or shared state.",
-			"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
-			'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
-			"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
-		],
+		promptGuidelines: promptGuidelines(),
 		parameters: SubagentParams,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			return executeSubagent(toolCallId, params, signal, onUpdate, ctx, getSettings());
+			const lifecycleController = new AbortController();
+			activeControllers.add(lifecycleController);
+			const effectiveSignal = signal
+				? AbortSignal.any([signal, lifecycleController.signal])
+				: lifecycleController.signal;
+			const work = executeSubagent(
+				toolCallId,
+				params,
+				effectiveSignal,
+				onUpdate,
+				ctx,
+				getSettings(),
+			);
+			activeWork.add(work);
+			try {
+				return await work;
+			} finally {
+				activeControllers.delete(lifecycleController);
+				activeWork.delete(work);
+			}
 		},
 
 		renderCall(args, theme) {
@@ -183,6 +245,7 @@ function registerBlockingSubagent(
 	return (nextCatalog: string) => {
 		catalog = nextCatalog;
 		definition.description = appendAgentCatalog(baseDescription(), catalog);
+		definition.promptGuidelines = promptGuidelines();
 		pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
 	};
 }
@@ -198,22 +261,27 @@ export {
 	DEFAULT_CONSULT_RESOURCE_POLICY,
 	DEFAULT_CONSULTATION_CWD_POLICY,
 	DEFAULT_DELEGATION_CWD_POLICY,
+	inspectBlockingParallelLimitSettings,
 	inspectCompletionDeliverySettings,
 	inspectConsultResourceSettings,
 	inspectCwdPolicySettings,
 	inspectDelegationWorkflowSettings,
+	inspectStatefulLimitSettings,
 	inspectSubagentSettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
+	resolveBlockingMaxParallelTasks,
 	resolveSubagentThinkingLevel,
 	sameToolSet,
 	saveSubagentConfig,
 	subagentSettingsFilePath,
 	uniqueToolNames,
 	updateAgentToolsSetting,
+	updateBlockingMaxParallelTasksSetting,
 	updateCompletionDeliverySetting,
 	updateConsultResourceSetting,
 	updateCwdPolicySetting,
 	updateDelegationWorkflowSetting,
+	updateStatefulLimitSetting,
 } from "./settings.js";

package/src/subprocess-transport.ts

@@ -4,11 +4,13 @@ import {
 	type SubagentSettings,
 	type SubagentThinkingLevel,
 } from "./agents.js";
+import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
 import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
 import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
 import { buildStatefulTurnPrompt, resolveStatefulTurnTimeout } from "./stateful-prompt.js";
 import type { SubagentTransport } from "./transport.js";
+import type { TransportProgressCallback, TransportTelemetry } from "./transport-types.js";
 
 export function resolveStatefulSubprocessThinkingLevel(
 	agents: readonly Pick<AgentConfig, "name" | "thinkingLevel">[],
@@ -26,11 +28,30 @@ export class SubprocessTransport implements SubagentTransport {
 
 	constructor(private readonly options: SubprocessTransportOptions = {}) {}
 
-	async runTurn(record: ManagedAgent, task: string, signal: AbortSignal): Promise<TurnOutcome> {
+	async runTurn(
+		record: ManagedAgent,
+		task: string,
+		signal: AbortSignal,
+		onProgress?: TransportProgressCallback,
+	): Promise<TurnOutcome> {
+		const startedAt = Date.now();
+		const starting: TransportTelemetry = {
+			transport: "subprocess",
+			phase: "starting",
+			updatedAt: startedAt,
+			timing: { startedAt, transportStartedAt: startedAt },
+		};
+		onProgress?.(starting);
 		const settings = this.options.getSettings ? this.options.getSettings() : readSubagentSettings();
 		const discovery = discoverAgents(record.cwd, record.agentScope ?? "user", settings);
 		const agent = discovery.agents.find((candidate) => candidate.name === record.agent);
 		const boundedTask = buildStatefulTurnPrompt(record, task);
+		const projectTrust =
+			record.target?.trust.projectTrusted ??
+			(record.agentScope === "project" || record.agentScope === "both");
+		const promptResources = agent?.systemPrompt.trim()
+			? await resolvePiPromptResources(record.cwd, projectTrust)
+			: undefined;
 		const makeDetails = (results: SubagentDetails["results"]): SubagentDetails => ({
 			mode: "single",
 			agentScope: record.agentScope ?? "user",
@@ -46,16 +67,52 @@ export class SubprocessTransport implements SubagentTransport {
 			undefined,
 			signal,
 			resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
-			resolveStatefulTurnTimeout(agent),
+			record.currentTimeoutMs ?? record.timeoutMs ?? resolveStatefulTurnTimeout(agent),
 			undefined,
 			makeDetails,
 			undefined,
 			{
-				projectTrust:
-					record.target?.trust.projectTrusted ??
-					(record.agentScope === "project" || record.agentScope === "both"),
+				projectTrust,
+				...(record.executionPlan ? { tools: record.executionPlan.effectiveTools } : {}),
+				appendSystemPromptPaths: promptResources?.appendSystemPromptPaths,
+				timeoutResultFormat: record.resultFormat,
+				turnLimits: {
+					idleTimeoutMs: record.currentIdleTimeoutMs ?? record.idleTimeoutMs,
+					maxTurns: record.currentMaxTurns ?? record.maxTurns,
+					maxToolCalls: record.currentMaxToolCalls ?? record.maxToolCalls,
+				},
+				resultFormat: record.resultFormat,
+				contract: record.contract,
+				executionPlan: record.executionPlan,
+				displayTask: task,
 			},
 		);
+		const settledAt = Date.now();
+		const telemetry: TransportTelemetry = {
+			...starting,
+			phase: single.aborted ? "interrupted" : single.exitCode === 0 ? "settled" : "failed",
+			failurePhase: single.exitCode === 0 ? undefined : "running",
+			updatedAt: settledAt,
+			timing: {
+				...starting.timing,
+				promptAcceptedAt: single.processStarted ? startedAt : undefined,
+				firstActivityAt: single.messages.length > 0 ? settledAt : undefined,
+				settledAt,
+			},
+			provider: single.actualProvider,
+			model: single.actualModel ?? single.model,
+			thinkingLevel: single.thinkingLevel,
+			usage: {
+				input: single.usage.input,
+				output: single.usage.output,
+				cacheRead: single.usage.cacheRead,
+				cacheWrite: single.usage.cacheWrite,
+				totalTokens: single.usage.totalTokens ?? 0,
+				cost: single.usage.cost,
+				turns: single.usage.turns,
+			},
+		};
+		onProgress?.(telemetry);
 		return {
 			output: getResultFinalOutput(single),
 			exitCode: single.exitCode,
@@ -63,6 +120,8 @@ export class SubprocessTransport implements SubagentTransport {
 			truncated: single.truncated || boundedTask.truncated,
 			error: single.errorMessage || single.stderr || undefined,
 			policy: single.policy,
+			termination: single.termination,
+			telemetry,
 		};
 	}
 }

package/src/supervision.ts

@@ -0,0 +1,103 @@
+import { isResultError, type SingleResult } from "./runner.js";
+
+const HEDGE_LOSER_GRACE_MS = 5_000;
+
+export async function runHedgedAttempt(
+	run: (signal: AbortSignal | undefined) => Promise<SingleResult>,
+	parentSignal: AbortSignal | undefined,
+	hedgeAfterMs: number | undefined,
+	loserGraceMs = HEDGE_LOSER_GRACE_MS,
+): Promise<{ result: SingleResult; hedged: boolean }> {
+	if (hedgeAfterMs === undefined) return { result: await run(parentSignal), hedged: false };
+	const primaryLink = linkedAbortController(parentSignal);
+	const hedgeLink = linkedAbortController(parentSignal);
+	const primaryController = primaryLink.controller;
+	const hedgeController = hedgeLink.controller;
+	let hedgeStarted = false;
+	let hedgePromise: Promise<SingleResult> | undefined;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const primaryPromise = run(primaryController.signal);
+	const primaryTagged = primaryPromise.then((result) => ({ source: "primary" as const, result }));
+	const delayedHedge = new Promise<{ source: "hedge"; result: SingleResult }>((resolve, reject) => {
+		timer = setTimeout(() => {
+			hedgeStarted = true;
+			hedgePromise = run(hedgeController.signal);
+			hedgePromise.then((result) => resolve({ source: "hedge", result }), reject);
+		}, hedgeAfterMs);
+	});
+	try {
+		const first = await Promise.race([primaryTagged, delayedHedge]);
+		if (!isResultError(first.result) || !hedgeStarted || !hedgePromise) {
+			return { result: first.result, hedged: hedgeStarted };
+		}
+		const other = first.source === "primary" ? await hedgePromise : await primaryPromise;
+		return {
+			result: isResultError(other) ? first.result : other,
+			hedged: true,
+		};
+	} finally {
+		if (timer) clearTimeout(timer);
+		primaryController.abort();
+		hedgeController.abort();
+		primaryLink.dispose();
+		hedgeLink.dispose();
+		await settleWithin(
+			[primaryPromise, hedgePromise].filter(
+				(value): value is Promise<SingleResult> => value !== undefined,
+			),
+			loserGraceMs,
+		);
+	}
+}
+
+export function isRetryableResult(result: SingleResult): boolean {
+	if (!isResultError(result)) return false;
+	if (result.outcome) return result.outcome.retryable;
+	return result.aborted === true || result.exitCode !== 0;
+}
+
+export async function supervisionDelay(
+	milliseconds: number,
+	signal: AbortSignal | undefined,
+): Promise<void> {
+	if (milliseconds <= 0 || signal?.aborted) return;
+	await new Promise<void>((resolve) => {
+		let timer: ReturnType<typeof setTimeout>;
+		const finish = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		};
+		timer = setTimeout(finish, milliseconds);
+		signal?.addEventListener("abort", finish, { once: true });
+	});
+}
+
+async function settleWithin(promises: Promise<unknown>[], timeoutMs: number): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		await Promise.race([
+			Promise.allSettled(promises),
+			new Promise<void>((resolve) => {
+				timer = setTimeout(resolve, timeoutMs);
+				timer.unref();
+			}),
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+function linkedAbortController(parentSignal: AbortSignal | undefined): {
+	controller: AbortController;
+	dispose(): void;
+} {
+	const controller = new AbortController();
+	const abort = () => controller.abort();
+	if (parentSignal?.aborted) controller.abort();
+	else parentSignal?.addEventListener("abort", abort, { once: true });
+	return {
+		controller,
+		dispose: () => parentSignal?.removeEventListener("abort", abort),
+	};
+}