@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/dist/builtin/subagents/src/runs/foreground/chain-execution-parallel-step.ts

@@ -0,0 +1,185 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	aggregateParallelOutputs,
+	createParallelDirs,
+	resolveParallelBehaviors,
+	suppressProgressForReadOnlyTask,
+	type ParallelStep,
+	type ParallelTaskResult,
+} from "../../shared/settings.ts";
+import { getSingleResultOutput, resolveChildCwd } from "../../shared/utils.ts";
+import { buildChainSummary } from "../../shared/formatters.ts";
+import {
+	cleanupWorktrees,
+	createWorktrees,
+	findWorktreeTaskCwdConflict,
+	formatWorktreeTaskCwdConflict,
+	type WorktreeSetup,
+} from "../shared/worktree.ts";
+import { outputEntryFromResult } from "../shared/chain-outputs.ts";
+import { validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { buildChainExecutionDetails, buildChainExecutionErrorResult } from "./chain-execution-details.ts";
+import { appendParallelWorktreeSummary, ensureParallelProgressFile, runParallelChainTasks } from "./chain-execution-parallel-runner.ts";
+import type { ChainExecutionMutableState, ChainExecutionResult, ChainRuntimeContext } from "./chain-execution-types.ts";
+
+export async function runStaticParallelChainStep(input: {
+	context: ChainRuntimeContext;
+	state: ChainExecutionMutableState;
+	step: ParallelStep;
+	stepIndex: number;
+	parallelTemplates: string[];
+}): Promise<ChainExecutionResult | undefined> {
+	const { context, state, step, stepIndex, parallelTemplates } = input;
+	const parallelCwd = resolveChildCwd(context.cwd ?? context.ctx.cwd, step.cwd);
+	let worktreeSetup: WorktreeSetup | undefined;
+	if (step.worktree) {
+		const worktreeTaskCwdConflict = findWorktreeTaskCwdConflict(step.parallel, parallelCwd);
+		if (worktreeTaskCwdConflict) {
+			return buildChainExecutionErrorResult(
+				`parallel chain step ${stepIndex + 1}: ${formatWorktreeTaskCwdConflict(worktreeTaskCwdConflict, parallelCwd)}`,
+				context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex }),
+			);
+		}
+		try {
+			worktreeSetup = createWorktrees(parallelCwd, `${context.runId}-s${stepIndex}`, step.parallel.length, {
+				agents: step.parallel.map((task) => task.agent),
+				setupHook: context.params.worktreeSetupHook
+					? { hookPath: context.params.worktreeSetupHook, timeoutMs: context.params.worktreeSetupHookTimeoutMs }
+					: undefined,
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return buildChainExecutionErrorResult(message, context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex }));
+		}
+	}
+
+	try {
+		const agentNames = step.parallel.map((task) => task.agent);
+		const parallelBehaviors = resolveParallelBehaviors(step.parallel, context.agents, stepIndex, context.chainSkills)
+			.map((behavior, taskIndex) => suppressProgressForReadOnlyTask(behavior, parallelTemplates[taskIndex] ?? step.parallel[taskIndex]?.task, context.originalTask));
+		for (let taskIndex = 0; taskIndex < step.parallel.length; taskIndex++) {
+			const behavior = parallelBehaviors[taskIndex]!;
+			const outputPath = typeof behavior.output === "string"
+				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(context.chainDir, behavior.output))
+				: undefined;
+			const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Parallel chain step ${stepIndex + 1} task ${taskIndex + 1} (${step.parallel[taskIndex]!.agent})`);
+			if (validationError) {
+				return buildChainExecutionErrorResult(validationError, context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex + taskIndex }));
+			}
+		}
+		state.progressCreated = ensureParallelProgressFile(context.chainDir, state.progressCreated, parallelBehaviors);
+		createParallelDirs(context.chainDir, stepIndex, step.parallel.length, agentNames);
+
+		const parallelResults = await runParallelChainTasks({
+			step,
+			parallelTemplates,
+			parallelBehaviors,
+			agents: context.agents,
+			stepIndex,
+			availableModels: context.availableModels,
+			chainDir: context.chainDir,
+			prev: state.prev,
+			originalTask: context.originalTask,
+			ctx: context.ctx,
+			intercomEvents: context.intercomEvents,
+			cwd: context.cwd,
+			runId: context.runId,
+			globalTaskIndex: state.globalTaskIndex,
+			sessionDirForIndex: context.sessionDirForIndex,
+			sessionFileForIndex: context.sessionFileForIndex,
+			shareEnabled: context.shareEnabled,
+			artifactConfig: context.artifactConfig,
+			artifactsDir: context.artifactsDir,
+			signal: context.signal,
+			onUpdate: context.onUpdate,
+			results: state.results,
+			allProgress: state.allProgress,
+			outputs: state.outputs,
+			chainAgents: context.chainAgents,
+			chainSteps: context.chainSteps,
+			totalSteps: context.totalSteps,
+			dynamicChildren: state.dynamicChildren,
+			dynamicGroupStatuses: state.dynamicGroupStatuses,
+			controlConfig: context.controlConfig,
+			onControlEvent: context.onControlEvent,
+			childIntercomTarget: context.childIntercomTarget,
+			orchestratorIntercomTarget: context.orchestratorIntercomTarget,
+			foregroundControl: context.foregroundControl,
+			nestedRoute: context.params.nestedRoute,
+			worktreeSetup,
+			maxSubagentDepth: context.params.maxSubagentDepth,
+			workflowStageSubagentGuard: context.params.workflowStageSubagentGuard,
+			runSync: context.executeRunSync,
+		});
+		state.globalTaskIndex += step.parallel.length;
+		for (const result of parallelResults) {
+			state.results.push(result);
+			if (result.progress) state.allProgress.push(result.progress);
+			if (result.artifactPaths) state.allArtifactPaths.push(result.artifactPaths);
+		}
+
+		const interruptedIndexInStep = parallelResults.findIndex((result) => result.interrupted);
+		const interrupted = interruptedIndexInStep >= 0 ? parallelResults[interruptedIndexInStep] : undefined;
+		if (interrupted) {
+			return {
+				content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${interrupted.agent}). Waiting for explicit next action.` }],
+				details: buildChainExecutionDetails(context.makeDetailsInput({
+					currentStepIndex: stepIndex,
+					currentFlatIndex: state.globalTaskIndex - step.parallel.length + interruptedIndexInStep,
+				})),
+			};
+		}
+		const detachedIndexInStep = parallelResults.findIndex((result) => result.detached);
+		const detached = detachedIndexInStep >= 0 ? parallelResults[detachedIndexInStep] : undefined;
+		if (detached) {
+			return {
+				content: [{ type: "text", text: `Chain detached for intercom coordination at step ${stepIndex + 1} (${detached.agent}). Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.` }],
+				details: buildChainExecutionDetails(context.makeDetailsInput({
+					currentStepIndex: stepIndex,
+					currentFlatIndex: state.globalTaskIndex - step.parallel.length + detachedIndexInStep,
+				})),
+			};
+		}
+
+		const failures = parallelResults.map((result, originalIndex) => ({ ...result, originalIndex })).filter((result) => result.exitCode !== 0 && result.exitCode !== -1);
+		if (failures.length > 0) {
+			const failureSummary = failures.map((failure) => `- Task ${failure.originalIndex + 1} (${failure.agent}): ${failure.error || "failed"}`).join("\n");
+			const errorMsg = `Parallel step ${stepIndex + 1} failed:\n${failureSummary}`;
+			const summary = buildChainSummary(context.chainSteps, state.results, context.chainDir, "failed", { index: stepIndex, error: errorMsg });
+			return {
+				content: [{ type: "text", text: summary }],
+				isError: true,
+				details: buildChainExecutionDetails(context.makeDetailsInput({
+					currentStepIndex: stepIndex,
+					currentFlatIndex: state.globalTaskIndex - step.parallel.length + failures[0]!.originalIndex,
+				})),
+			};
+		}
+
+		for (let taskIndex = 0; taskIndex < parallelResults.length; taskIndex++) {
+			const outputName = step.parallel[taskIndex]?.as;
+			if (outputName) state.outputs[outputName] = outputEntryFromResult(parallelResults[taskIndex]!, stepIndex);
+		}
+		const taskResults: ParallelTaskResult[] = parallelResults.map((result, index) => {
+			const outputTarget = parallelBehaviors[index]?.output;
+			const outputTargetPath = typeof outputTarget === "string"
+				? (path.isAbsolute(outputTarget) ? outputTarget : path.join(context.chainDir, outputTarget))
+				: undefined;
+			return {
+				agent: result.agent,
+				taskIndex: index,
+				output: getSingleResultOutput(result),
+				exitCode: result.exitCode,
+				error: result.error,
+				outputTargetPath,
+				outputTargetExists: outputTargetPath ? fs.existsSync(outputTargetPath) : undefined,
+			};
+		});
+		state.prev = aggregateParallelOutputs(taskResults);
+		state.prev = appendParallelWorktreeSummary(state.prev, worktreeSetup, path.join(context.chainDir, "worktree-diffs", `step-${stepIndex}`), agentNames);
+		return undefined;
+	} finally {
+		if (worktreeSetup) cleanupWorktrees(worktreeSetup);
+	}
+}

package/dist/builtin/subagents/src/runs/foreground/chain-execution-sequential-step.ts

@@ -0,0 +1,229 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { INTERCOM_BRIDGE_MARKER } from "../../intercom/intercom-bridge.ts";
+import { buildChainSummary } from "../../shared/formatters.ts";
+import {
+	buildChainInstructions,
+	removeChainDir,
+	resolveStepBehavior,
+	suppressProgressForReadOnlyTask,
+	type SequentialStep,
+	type StepOverrides,
+} from "../../shared/settings.ts";
+import { getSingleResultOutput, resolveChildCwd } from "../../shared/utils.ts";
+import { normalizeSkillInput } from "../../agents/skills.ts";
+import { resolveChildMaxSubagentDepth } from "../../shared/types.ts";
+import { outputEntryFromResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
+import { currentModelFullId, resolveModelCandidate } from "../shared/model-fallback.ts";
+import { recordRun } from "../shared/run-history.ts";
+import { validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
+import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
+import { buildChainExecutionDetails, buildChainExecutionErrorResult } from "./chain-execution-details.ts";
+import type { BehaviorOverride } from "./chain-clarify.ts";
+import type { ChainExecutionMutableState, ChainExecutionResult, ChainRuntimeContext } from "./chain-execution-types.ts";
+
+export async function runSequentialChainStep(input: {
+	context: ChainRuntimeContext;
+	state: ChainExecutionMutableState;
+	seqStep: SequentialStep;
+	stepIndex: number;
+	stepTemplate: string;
+	tuiOverride?: BehaviorOverride;
+}): Promise<ChainExecutionResult | undefined> {
+	const { context, state, seqStep, stepIndex, stepTemplate, tuiOverride } = input;
+	const agentConfig = context.agents.find((agent) => agent.name === seqStep.agent);
+	if (!agentConfig) {
+		removeChainDir(context.chainDir);
+		return {
+			content: [{ type: "text", text: `Unknown agent: ${seqStep.agent}` }],
+			isError: true,
+			details: buildChainExecutionDetails(context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex })),
+		};
+	}
+
+	const stepOverride: StepOverrides = {
+		output: tuiOverride?.output !== undefined ? tuiOverride.output : seqStep.output,
+		outputMode: seqStep.outputMode,
+		reads: tuiOverride?.reads !== undefined ? tuiOverride.reads : seqStep.reads,
+		progress: tuiOverride?.progress !== undefined ? tuiOverride.progress : seqStep.progress,
+		skills: tuiOverride?.skills !== undefined ? tuiOverride.skills : normalizeSkillInput(seqStep.skill),
+	};
+	const behavior = suppressProgressForReadOnlyTask(
+		resolveStepBehavior(agentConfig, stepOverride, context.chainSkills),
+		stepTemplate,
+		context.originalTask,
+	);
+	const isFirstProgress = behavior.progress && !state.progressCreated;
+	if (isFirstProgress) state.progressCreated = true;
+
+	const templateHasPrevious = stepTemplate.includes("{previous}");
+	const { prefix, suffix } = buildChainInstructions(
+		behavior,
+		context.chainDir,
+		isFirstProgress,
+		templateHasPrevious ? undefined : state.prev,
+	);
+
+	let stepTask = resolveOutputReferences(stepTemplate, state.outputs);
+	stepTask = stepTask.replace(/\{task\}/g, context.originalTask);
+	stepTask = stepTask.replace(/\{previous\}/g, state.prev);
+	stepTask = stepTask.replace(/\{chain_dir\}/g, context.chainDir);
+	const cleanTask = stepTask;
+	stepTask = prefix + stepTask + suffix;
+
+	const effectiveModel =
+		tuiOverride?.model
+		?? (seqStep.model ? resolveModelCandidate(seqStep.model, context.availableModels, context.ctx.model?.provider) : null)
+		?? resolveModelCandidate(agentConfig.model, context.availableModels, context.ctx.model?.provider);
+	const outputPath = typeof behavior.output === "string"
+		? (path.isAbsolute(behavior.output) ? behavior.output : path.join(context.chainDir, behavior.output))
+		: undefined;
+	const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Chain step ${stepIndex + 1} (${seqStep.agent})`);
+	if (validationError) return buildChainExecutionErrorResult(validationError, context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex }));
+
+	const maxSubagentDepth = resolveChildMaxSubagentDepth(context.params.maxSubagentDepth, agentConfig.maxSubagentDepth);
+	const interruptController = new AbortController();
+	if (context.foregroundControl) {
+		context.foregroundControl.currentAgent = seqStep.agent;
+		context.foregroundControl.currentIndex = state.globalTaskIndex;
+		context.foregroundControl.currentActivityState = undefined;
+		context.foregroundControl.updatedAt = Date.now();
+		context.foregroundControl.interrupt = () => {
+			if (interruptController.signal.aborted) return false;
+			interruptController.abort();
+			context.foregroundControl!.currentActivityState = undefined;
+			context.foregroundControl!.updatedAt = Date.now();
+			return true;
+		};
+	}
+
+	const flatIndex = state.globalTaskIndex;
+	const structuredRuntime = seqStep.outputSchema
+		? createStructuredOutputRuntime(seqStep.outputSchema, path.join(context.chainDir, "structured-output"))
+		: undefined;
+	const result = await context.executeRunSync(context.ctx.cwd, context.agents, seqStep.agent, stepTask, {
+		cwd: resolveChildCwd(context.cwd ?? context.ctx.cwd, seqStep.cwd),
+		signal: context.signal,
+		interruptSignal: interruptController.signal,
+		allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
+		intercomEvents: context.intercomEvents,
+		runId: context.runId,
+		index: flatIndex,
+		sessionDir: context.sessionDirForIndex(flatIndex),
+		sessionFile: context.sessionFileForIndex?.(flatIndex),
+		share: context.shareEnabled,
+		artifactsDir: context.artifactConfig.enabled ? context.artifactsDir : undefined,
+		artifactConfig: context.artifactConfig,
+		outputPath,
+		outputMode: behavior.outputMode,
+		maxSubagentDepth,
+		workflowStageSubagentGuard: context.params.workflowStageSubagentGuard,
+		controlConfig: context.controlConfig,
+		onControlEvent: context.onControlEvent,
+		intercomSessionName: context.childIntercomTarget?.(seqStep.agent, flatIndex),
+		orchestratorIntercomTarget: context.orchestratorIntercomTarget,
+		nestedRoute: context.params.nestedRoute,
+		modelOverride: effectiveModel,
+		availableModels: context.availableModels,
+		currentModel: currentModelFullId(context.ctx.model),
+		preferredModelProvider: context.ctx.model?.provider,
+		skills: behavior.skills === false ? [] : behavior.skills,
+		structuredOutput: structuredRuntime,
+		onUpdate: context.onUpdate ? (update) => {
+			const stepResults = update.details?.results || [];
+			const stepProgress = update.details?.progress || [];
+			if (context.foregroundControl && stepProgress.length > 0) {
+				const current = stepProgress[0];
+				context.foregroundControl.currentAgent = seqStep.agent;
+				context.foregroundControl.currentIndex = flatIndex;
+				context.foregroundControl.currentActivityState = current?.activityState;
+				context.foregroundControl.lastActivityAt = current?.lastActivityAt;
+				context.foregroundControl.currentTool = current?.currentTool;
+				context.foregroundControl.currentToolStartedAt = current?.currentToolStartedAt;
+				context.foregroundControl.currentPath = current?.currentPath;
+				context.foregroundControl.turnCount = current?.turnCount;
+				context.foregroundControl.tokens = current?.tokens;
+				context.foregroundControl.toolCount = current?.toolCount;
+				context.foregroundControl.updatedAt = Date.now();
+			}
+			context.onUpdate?.({
+				...update,
+				details: {
+					mode: "chain",
+					results: state.results.concat(stepResults),
+					progress: state.allProgress.concat(stepProgress),
+					controlEvents: update.details?.controlEvents,
+					chainAgents: context.chainAgents,
+					totalSteps: context.totalSteps,
+					currentStepIndex: stepIndex,
+					outputs: state.outputs,
+					workflowGraph: buildWorkflowGraphSnapshot({
+						runId: context.runId,
+						mode: "chain",
+						steps: context.chainSteps,
+						results: state.results.concat(stepResults),
+						currentStepIndex: stepIndex,
+						currentFlatIndex: flatIndex,
+						dynamicChildren: state.dynamicChildren,
+						dynamicGroupStatuses: state.dynamicGroupStatuses,
+					}),
+				},
+			});
+		} : undefined,
+	});
+	if (context.foregroundControl?.currentIndex === flatIndex) {
+		context.foregroundControl.interrupt = undefined;
+		context.foregroundControl.updatedAt = Date.now();
+	}
+	recordRun(seqStep.agent, cleanTask, result.exitCode, result.progressSummary?.durationMs ?? 0);
+
+	state.globalTaskIndex++;
+	state.results.push(result);
+	if (result.progress) state.allProgress.push(result.progress);
+	if (result.artifactPaths) state.allArtifactPaths.push(result.artifactPaths);
+
+	if (result.interrupted) {
+		return {
+			content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${result.agent}). Waiting for explicit next action.` }],
+			details: buildChainExecutionDetails(context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex - 1 })),
+		};
+	}
+	if (result.detached) {
+		return {
+			content: [{ type: "text", text: `Chain detached for intercom coordination at step ${stepIndex + 1} (${result.agent}). Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.` }],
+			details: buildChainExecutionDetails(context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex - 1 })),
+		};
+	}
+	if (result.exitCode !== 0) {
+		const summary = buildChainSummary(context.chainSteps, state.results, context.chainDir, "failed", {
+			index: stepIndex,
+			error: result.error || "Chain failed",
+		});
+		return {
+			content: [{ type: "text", text: summary }],
+			details: buildChainExecutionDetails(context.makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: state.globalTaskIndex - 1 })),
+			isError: true,
+		};
+	}
+
+	if (behavior.output) {
+		try {
+			const expectedPath = path.isAbsolute(behavior.output) ? behavior.output : path.join(context.chainDir, behavior.output);
+			if (!fs.existsSync(expectedPath)) {
+				const dirFiles = fs.readdirSync(context.chainDir);
+				const mdFiles = dirFiles.filter((file) => file.endsWith(".md") && file !== "progress.md");
+				const warning = mdFiles.length > 0
+					? `Agent wrote to different file(s): ${mdFiles.join(", ")} instead of ${behavior.output}`
+					: `Agent did not create expected output file: ${behavior.output}`;
+				result.error = result.error ? `${result.error}\n${warning}` : warning;
+			}
+		} catch {
+			// Ignore validation errors; this diagnostic should not mask successful chain output.
+		}
+	}
+
+	if (seqStep.as) state.outputs[seqStep.as] = outputEntryFromResult(result, stepIndex);
+	state.prev = getSingleResultOutput(result);
+	return undefined;
+}

package/dist/builtin/subagents/src/runs/foreground/chain-execution-types.ts

@@ -0,0 +1,194 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@bastani/atomic";
+import type { AgentConfig } from "../../agents/agents.ts";
+import type { ModelInfo } from "../../shared/model-info.ts";
+import type {
+	ChainStep,
+	ParallelStep,
+	ResolvedStepBehavior,
+	ResolvedTemplates,
+} from "../../shared/settings.ts";
+import type {
+	ActivityState,
+	AgentProgress,
+	ArtifactConfig,
+	ArtifactPaths,
+	ControlEvent,
+	Details,
+	IntercomEventBus,
+	NestedRouteInfo,
+	ResolvedControlConfig,
+	SingleResult,
+} from "../../shared/types.ts";
+import type { ChainOutputMap } from "../../shared/types.ts";
+import type { WorktreeSetup } from "../shared/worktree.ts";
+import type { runSync } from "./execution.ts";
+import type { BehaviorOverride } from "./chain-clarify.ts";
+
+export type RunSyncDependency = typeof runSync;
+
+export type ChainForegroundControl = {
+	updatedAt: number;
+	currentAgent?: string;
+	currentIndex?: number;
+	currentActivityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	tokens?: number;
+	toolCount?: number;
+	interrupt?: () => boolean;
+};
+
+export interface ChainExecutionDetailsInput {
+	results: SingleResult[];
+	includeProgress?: boolean;
+	allProgress: AgentProgress[];
+	allArtifactPaths: ArtifactPaths[];
+	artifactsDir: string;
+	chainAgents: string[];
+	chainSteps: ChainStep[];
+	totalSteps: number;
+	currentStepIndex?: number;
+	runId: string;
+	outputs?: ChainOutputMap;
+	currentFlatIndex?: number;
+	dynamicChildren?: Record<number, Array<{ agent: string; label?: string; flatIndex: number; itemKey: string; outputName?: string; structured?: boolean; error?: string }>>;
+	dynamicGroupStatuses?: Record<number, { status: "pending" | "running" | "completed" | "failed" | "paused" | "detached"; error?: string }>;
+}
+
+export interface ChainExecutionParams {
+	chain: ChainStep[];
+	task?: string;
+	agents: AgentConfig[];
+	ctx: ExtensionContext;
+	intercomEvents?: IntercomEventBus;
+	signal?: AbortSignal;
+	runId: string;
+	cwd?: string;
+	shareEnabled: boolean;
+	sessionDirForIndex: (idx?: number) => string | undefined;
+	sessionFileForIndex?: (idx?: number) => string | undefined;
+	artifactsDir: string;
+	artifactConfig: ArtifactConfig;
+	includeProgress?: boolean;
+	clarify?: boolean;
+	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig: ResolvedControlConfig;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	orchestratorIntercomTarget?: string;
+	foregroundControl?: ChainForegroundControl;
+	chainSkills?: string[];
+	chainDir?: string;
+	dynamicFanoutMaxItems?: number;
+	maxSubagentDepth: number;
+	workflowStageSubagentGuard?: boolean;
+	nestedRoute?: NestedRouteInfo;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
+	runSync?: RunSyncDependency;
+}
+
+export interface ChainExecutionResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: Details;
+	isError?: boolean;
+	requestedAsync?: {
+		chain: ChainStep[];
+		chainSkills: string[];
+	};
+}
+
+export interface ParallelChainRunInput {
+	step: ParallelStep;
+	parallelTemplates: string[];
+	parallelBehaviors: ResolvedStepBehavior[];
+	agents: AgentConfig[];
+	stepIndex: number;
+	availableModels: ModelInfo[];
+	chainDir: string;
+	prev: string;
+	originalTask: string;
+	ctx: ExtensionContext;
+	intercomEvents?: IntercomEventBus;
+	cwd?: string;
+	runId: string;
+	globalTaskIndex: number;
+	sessionDirForIndex: (idx?: number) => string | undefined;
+	sessionFileForIndex?: (idx?: number) => string | undefined;
+	shareEnabled: boolean;
+	artifactConfig: ArtifactConfig;
+	artifactsDir: string;
+	signal?: AbortSignal;
+	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig: ResolvedControlConfig;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	orchestratorIntercomTarget?: string;
+	foregroundControl?: ChainForegroundControl;
+	results: SingleResult[];
+	allProgress: AgentProgress[];
+	outputs: ChainOutputMap;
+	chainAgents: string[];
+	chainSteps: ChainStep[];
+	totalSteps: number;
+	dynamicChildren?: ChainExecutionDetailsInput["dynamicChildren"];
+	dynamicGroupStatuses?: ChainExecutionDetailsInput["dynamicGroupStatuses"];
+	worktreeSetup?: WorktreeSetup;
+	maxSubagentDepth: number;
+	workflowStageSubagentGuard?: boolean;
+	nestedRoute?: NestedRouteInfo;
+	runSync: RunSyncDependency;
+}
+
+export interface ChainExecutionMutableState {
+	results: SingleResult[];
+	outputs: ChainOutputMap;
+	dynamicChildren: NonNullable<ChainExecutionDetailsInput["dynamicChildren"]>;
+	dynamicGroupStatuses: NonNullable<ChainExecutionDetailsInput["dynamicGroupStatuses"]>;
+	allProgress: AgentProgress[];
+	allArtifactPaths: ArtifactPaths[];
+	prev: string;
+	globalTaskIndex: number;
+	progressCreated: boolean;
+}
+
+export interface ChainRuntimeContext {
+	params: ChainExecutionParams;
+	agents: AgentConfig[];
+	ctx: ExtensionContext;
+	intercomEvents?: IntercomEventBus;
+	signal?: AbortSignal;
+	runId: string;
+	cwd?: string;
+	shareEnabled: boolean;
+	sessionDirForIndex: (idx?: number) => string | undefined;
+	sessionFileForIndex?: (idx?: number) => string | undefined;
+	artifactsDir: string;
+	artifactConfig: ArtifactConfig;
+	includeProgress?: boolean;
+	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig: ResolvedControlConfig;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	orchestratorIntercomTarget?: string;
+	foregroundControl?: ChainForegroundControl;
+	chainSkills: string[];
+	chainDir: string;
+	availableModels: ModelInfo[];
+	originalTask: string;
+	chainAgents: string[];
+	chainSteps: ChainStep[];
+	totalSteps: number;
+	executeRunSync: RunSyncDependency;
+	makeDetailsInput(overrides?: Pick<Partial<ChainExecutionDetailsInput>, "currentStepIndex" | "currentFlatIndex">): ChainExecutionDetailsInput;
+}
+
+export type ChainClarificationOutcome = {
+	result?: ChainExecutionResult;
+	templates: ResolvedTemplates;
+	tuiBehaviorOverrides?: (BehaviorOverride | undefined)[];
+};