pi-subagents 0.25.0 → 0.27.0

package/src/runs/background/async-execution.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
 import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
-import { buildChainInstructions, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
+import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
@@ -20,7 +20,12 @@ import { resolveChildCwd } from "../../shared/utils.ts";
 import { buildModelCandidates, resolveModelCandidate, type AvailableModelInfo } from "../shared/model-fallback.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { resolveExpectedWorktreeAgentCwd } from "../shared/worktree.ts";
+import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
+import { ChainOutputValidationError, validateChainOutputBindings } from "../shared/chain-outputs.ts";
+import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
+import { resolveEffectiveAcceptance } from "../shared/acceptance.ts";
 import {
+	type AcceptanceInput,
 	type ArtifactConfig,
 	type Details,
 	type MaxOutputConfig,
@@ -107,6 +112,7 @@ interface AsyncChainParams {
 	sessionRoot?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
@@ -114,6 +120,7 @@ interface AsyncChainParams {
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	nestedRoute?: NestedRouteInfo;
+	acceptance?: AcceptanceInput;
 }
 
 interface AsyncSingleParams {
@@ -140,6 +147,7 @@ interface AsyncSingleParams {
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	nestedRoute?: NestedRouteInfo;
+	acceptance?: AcceptanceInput;
 }
 
 interface AsyncExecutionResult {
@@ -248,12 +256,25 @@ export function executeAsyncChain(
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
 	const firstStep = chain[0];
 	const originalTask = params.task ?? (firstStep
-		? (isParallelStep(firstStep) ? firstStep.parallel[0]?.task : (firstStep as SequentialStep).task)
+		? (isParallelStep(firstStep)
+			? firstStep.parallel[0]?.task
+			: isDynamicParallelStep(firstStep)
+				? firstStep.parallel.task
+				: (firstStep as SequentialStep).task)
 		: undefined);
+	try {
+		validateChainOutputBindings(chain, { maxItems: params.dynamicFanoutMaxItems });
+	} catch (error) {
+		if (error instanceof ChainOutputValidationError) return formatAsyncStartError(resultMode, error.message);
+		throw error;
+	}
+	const workflowGraph = buildWorkflowGraphSnapshot({ runId: id, mode: resultMode, steps: chain });
 
 	for (const s of chain) {
 		const stepAgents = isParallelStep(s)
 			? s.parallel.map((t) => t.agent)
+			: isDynamicParallelStep(s)
+				? [s.parallel.agent]
 			: [(s as SequentialStep).agent];
 		for (const agentName of stepAgents) {
 			if (!agents.find((x) => x.name === agentName)) {
@@ -316,13 +337,20 @@ export function executeAsyncChain(
 		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd);
 		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
 		if (validationError) throw new AsyncStartValidationError(validationError);
-		const task = injectSingleOutputInstruction(`${readInstructions.prefix}${s.task ?? "{previous}"}${progressInstructions.suffix}`, outputPath);
+		let taskTemplate = s.task ?? "{previous}";
+		taskTemplate = taskTemplate.replace(/\{task\}/g, originalTask ?? "");
+		taskTemplate = taskTemplate.replace(/\{chain_dir\}/g, runnerCwd);
+		const task = injectSingleOutputInstruction(`${readInstructions.prefix}${taskTemplate}${progressInstructions.suffix}`, outputPath);
 
 		const primaryModel = resolveModelCandidate(behavior.model ?? a.model, availableModels, ctx.currentModelProvider);
 		const model = applyThinkingSuffix(primaryModel, a.thinking);
 		return {
 			agent: s.agent,
 			task,
+			phase: s.phase,
+			label: s.label,
+			outputName: s.as,
+			structured: Boolean(s.outputSchema),
 			cwd: stepCwd,
 			model,
 			thinking: resolveEffectiveThinking(model, a.thinking),
@@ -342,6 +370,16 @@ export function executeAsyncChain(
 			outputMode: behavior.outputMode,
 			sessionFile,
 			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
+			effectiveAcceptance: resolveEffectiveAcceptance({
+				explicit: s.acceptance,
+				agentName: s.agent,
+				task: s.task,
+				mode: resultMode,
+				async: true,
+				dynamic: false,
+			}),
+			...(s.outputSchema ? { structuredOutputSchema: s.outputSchema } : {}),
+			...(s.outputSchema ? { structuredOutput: createStructuredOutputRuntime(s.outputSchema, path.join(asyncDir, "structured-output")) } : {}),
 		};
 	};
 
@@ -382,6 +420,24 @@ export function executeAsyncChain(
 					worktree: s.worktree,
 				};
 			}
+			if (isDynamicParallelStep(s)) {
+				const agent = agents.find((candidate) => candidate.name === s.parallel.agent)!;
+				const behavior = suppressProgressForReadOnlyTask(resolveStepBehavior(agent, buildStepOverrides(s.parallel), chainSkills), s.parallel.task, originalTask);
+				const progressPrecreated = behavior.progress;
+				if (progressPrecreated) {
+					writeInitialProgressFile(runnerCwd);
+					progressInstructionCreated = true;
+				}
+				return {
+					expand: s.expand,
+					parallel: buildSeqStep(s.parallel as SequentialStep, undefined, undefined, progressPrecreated, behavior),
+					collect: s.collect,
+					concurrency: s.concurrency,
+					failFast: s.failFast,
+					phase: s.phase,
+					label: s.label,
+				};
+			}
 			return buildSeqStep(s as SequentialStep, nextSessionFile());
 		});
 	} catch (error) {
@@ -391,6 +447,10 @@ export function executeAsyncChain(
 	let childTargetIndex = 0;
 	const childIntercomTargets = childIntercomTarget ? steps.flatMap((step) => {
 		if ("parallel" in step) {
+			if (!Array.isArray(step.parallel)) {
+				childTargetIndex++;
+				return [undefined];
+			}
 			return step.parallel.map((task) => childIntercomTarget(task.agent, childTargetIndex++));
 		}
 		return [childIntercomTarget(step.agent, childTargetIndex++)];
@@ -420,6 +480,8 @@ export function executeAsyncChain(
 				controlIntercomTarget,
 				childIntercomTargets,
 				resultMode,
+				dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
+				workflowGraph,
 				nestedRoute: nestedRoute ?? inheritedNestedRoute,
 				nestedSelf: inheritedNestedRoute && nestedAddress ? {
 					parentRunId: nestedAddress.parentRunId,
@@ -444,6 +506,8 @@ export function executeAsyncChain(
 		const firstStep = chain[0];
 		const firstAgents = isParallelStep(firstStep)
 			? firstStep.parallel.map((t) => t.agent)
+			: isDynamicParallelStep(firstStep)
+				? [firstStep.parallel.agent]
 			: [(firstStep as SequentialStep).agent];
 		const parallelGroups: Array<{ start: number; count: number; stepIndex: number }> = [];
 		const flatAgents: string[] = [];
@@ -454,6 +518,10 @@ export function executeAsyncChain(
 				parallelGroups.push({ start: flatStepStart, count: step.parallel.length, stepIndex });
 				flatAgents.push(...step.parallel.map((task) => task.agent));
 				flatStepStart += step.parallel.length;
+			} else if (isDynamicParallelStep(step)) {
+				parallelGroups.push({ start: flatStepStart, count: 1, stepIndex });
+				flatAgents.push(step.parallel.agent);
+				flatStepStart++;
 			} else {
 				flatAgents.push((step as SequentialStep).agent);
 				flatStepStart++;
@@ -502,12 +570,15 @@ export function executeAsyncChain(
 			agents: flatAgents,
 			task: isParallelStep(firstStep)
 				? firstStep.parallel[0]?.task?.slice(0, 50)
+				: isDynamicParallelStep(firstStep)
+					? firstStep.parallel.task?.slice(0, 50)
 				: (firstStep as SequentialStep).task?.slice(0, 50),
 			chain: chain.map((s) =>
-				isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
+				isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : (s as SequentialStep).agent,
 			),
 			chainStepCount: chain.length,
 			parallelGroups,
+			workflowGraph,
 			cwd: runnerCwd,
 			asyncDir,
 			nestedRoute,
@@ -516,13 +587,13 @@ export function executeAsyncChain(
 
 	const chainDesc = chain
 		.map((s) =>
-			isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
+			isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : (s as SequentialStep).agent,
 		)
 		.join(" -> ");
 
 	return {
 		content: [{ type: "text", text: formatAsyncStartedMessage(`Async ${resultMode}: ${chainDesc} [${id}]`) }],
-		details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir },
+		details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir, workflowGraph },
 	};
 }
 
@@ -618,6 +689,13 @@ export function executeAsyncSingle(
 						outputMode,
 						sessionFile,
 						maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
+						effectiveAcceptance: resolveEffectiveAcceptance({
+							explicit: params.acceptance,
+							agentName: agent,
+							task,
+							mode: "single",
+							async: true,
+						}),
 					},
 				],
 				resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(RESULTS_DIR, `${id}.json`),

package/src/runs/background/async-status.ts

@@ -12,6 +12,10 @@ import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-
 interface AsyncRunStepSummary {
 	index: number;
 	agent: string;
+	label?: string;
+	phase?: string;
+	outputName?: string;
+	structured?: boolean;
 	status: AsyncJobStep["status"];
 	activityState?: ActivityState;
 	lastActivityAt?: number;
@@ -139,6 +143,10 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		return {
 			index,
 			agent: step.agent,
+			...(step.label ? { label: step.label } : {}),
+			...(step.phase ? { phase: step.phase } : {}),
+			...(step.outputName ? { outputName: step.outputName } : {}),
+			...(step.structured ? { structured: step.structured } : {}),
 			status: step.status,
 			...(stepActivityState ? { activityState: stepActivityState } : {}),
 			...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
@@ -259,7 +267,9 @@ function formatActivityFacts(input: { activityState?: ActivityState; lastActivit
 }
 
 function formatStepLine(step: AsyncRunStepSummary): string {
-	const parts = [`${step.index + 1}. ${step.agent}`, step.status];
+	const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+	const phase = step.phase ? `[${step.phase}] ` : "";
+	const parts = [`${step.index + 1}. ${phase}${display}`, step.status];
 	const activity = formatActivityFacts(step);
 	if (activity) parts.push(activity);
 	const modelThinking = formatModelThinking(step.model, step.thinking);

package/src/runs/background/run-status.ts

@@ -49,6 +49,11 @@ function formatResumeGuidance(runId: string | undefined, children: Array<{ agent
 	return "Resume: unavailable; no child session file was persisted.";
 }
 
+function formatAcceptanceFinalizationSummary(finalization: NonNullable<NonNullable<AsyncStatus["steps"]>[number]["acceptance"]>["finalization"] | undefined): string {
+	if (!finalization) return "";
+	return `, finalization: ${finalization.status} after ${finalization.turns.length}/${finalization.maxTurns} turns`;
+}
+
 function stepLineLabel(status: AsyncStatus, index: number): string {
 	const steps = status.steps ?? [];
 	if (status.mode === "parallel") return `Agent ${index + 1}/${steps.length || 1}`;
@@ -217,7 +222,11 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				const modelThinking = formatModelThinking(step.model, step.thinking);
 				const modelText = modelThinking ? ` (${modelThinking})` : "";
 				const errorText = step.error ? `, error: ${step.error}` : "";
-				lines.push(`${stepLineLabel(status, index)}: ${step.agent} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${errorText}`);
+				const finalizationText = formatAcceptanceFinalizationSummary(step.acceptance?.finalization);
+				const acceptanceText = step.acceptance?.status ? `, acceptance: ${step.acceptance.status}${finalizationText}` : "";
+				const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+				const phase = step.phase ? `[${step.phase}] ` : "";
+				lines.push(`${stepLineLabel(status, index)}: ${phase}${display} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${acceptanceText}${errorText}`);
 				lines.push(...formatNestedRunStatusLines(step.children, { indent: "  ", commandHints: true, maxLines: 20 }));
 				const stepOutputPath = path.join(asyncDir, `output-${index}.log`);
 				if (stepOutputPath !== outputPath && fs.existsSync(stepOutputPath)) lines.push(`  Output: ${stepOutputPath}`);