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

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-single.ts

@@ -0,0 +1,320 @@
+import { randomUUID } from "node:crypto";
+import { APP_NAME } from "@bastani/atomic";
+import { ChainClarifyComponent, type ChainClarifyResult } from "./chain-clarify.ts";
+import { currentModelFullId, resolveModelCandidate } from "../shared/model-fallback.ts";
+import { toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
+import { recordRun } from "../shared/run-history.ts";
+import { getSingleResultOutput, compactForegroundDetails } from "../../shared/utils.ts";
+import { updateForegroundNestedProjection } from "../shared/nested-events.ts";
+import { resolveStepBehavior } from "../../shared/settings.ts";
+import {
+	INTERCOM_BRIDGE_MARKER,
+	resolveSubagentIntercomTarget,
+} from "../../intercom/intercom-bridge.ts";
+import {
+	finalizeSingleOutput,
+	injectSingleOutputInstruction,
+	normalizeSingleOutputOverride,
+	resolveSingleOutputPath,
+	validateFileOnlyOutputMode,
+} from "../shared/single-output.ts";
+import {
+	resolveChildMaxSubagentDepth,
+	resolveSubagentDepthPolicy,
+	wrapForkTask,
+	type AgentProgress,
+	type ArtifactPaths,
+	type SubagentToolResult,
+} from "../../shared/types.ts";
+import type { ExecutionContextData, ResolvedExecutorDeps } from "./subagent-executor-types.ts";
+import { createForegroundControlNotifier, maybeBuildForegroundIntercomReceipt, rememberForegroundRun } from "./subagent-executor-status.ts";
+
+export async function runSinglePath(data: ExecutionContextData, deps: ResolvedExecutorDeps): Promise<SubagentToolResult> {
+	const {
+		params,
+		effectiveCwd,
+		agents,
+		ctx,
+		signal,
+		runId,
+		sessionDirForIndex,
+		sessionFileForIndex,
+		shareEnabled,
+		artifactConfig,
+		artifactsDir,
+		onUpdate,
+		sessionRoot,
+		controlConfig,
+	} = data;
+	const onControlEvent = createForegroundControlNotifier(data, deps);
+	const childIntercomTarget = data.intercomBridge.active ? resolveSubagentIntercomTarget(runId, params.agent!, 0) : undefined;
+	const allProgress: AgentProgress[] = [];
+	const allArtifactPaths: ArtifactPaths[] = [];
+	const agentConfig = agents.find((a) => a.name === params.agent);
+	if (!agentConfig) {
+		return {
+			content: [{ type: "text", text: `Unknown agent: ${params.agent}` }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+
+	const currentProvider = ctx.model?.provider;
+	const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map(toModelInfo);
+	let task = params.task ?? "";
+	let modelOverride: string | undefined = resolveModelCandidate(
+		(params.model as string | undefined) ?? agentConfig.model,
+		availableModels,
+		currentProvider,
+	);
+	let skillOverride: string[] | false | undefined = normalizeSkillInput(params.skill);
+	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
+	let effectiveOutput = normalizeSingleOutputOverride(rawOutput, agentConfig.output);
+	const effectiveOutputMode = params.outputMode ?? "inline";
+	const depthPolicy = resolveSubagentDepthPolicy(ctx, deps.config.maxSubagentDepth);
+	const currentMaxSubagentDepth = depthPolicy.maxSubagentDepth;
+	const workflowStageSubagentGuard = depthPolicy.workflowStageSubagentGuard;
+	const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
+
+	if (params.clarify === true && ctx.hasUI) {
+		const behavior = resolveStepBehavior(agentConfig, { output: effectiveOutput, skills: skillOverride });
+		const availableSkills = discoverAvailableSkills(effectiveCwd);
+
+		const result = await ctx.ui.custom<ChainClarifyResult>(
+			(tui, theme, _kb, done) =>
+				new ChainClarifyComponent(
+					tui, theme,
+					[agentConfig],
+					[task],
+					task,
+					undefined,
+					[behavior],
+					availableModels,
+					currentProvider,
+					availableSkills,
+					done,
+					"single",
+				),
+			{ overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } },
+		);
+
+		if (!result || !result.confirmed) {
+			return { content: [{ type: "text", text: "Cancelled" }], details: { mode: "single", results: [] } };
+		}
+
+		task = result.templates[0]!;
+		const override = result.behaviorOverrides[0];
+		if (override?.model) modelOverride = override.model;
+		if (override?.output !== undefined) effectiveOutput = normalizeSingleOutputOverride(override.output, agentConfig.output);
+		if (override?.skills !== undefined) skillOverride = override.skills;
+
+		if (result.runInBackground) {
+			if (!deps.runtime.isAsyncAvailable()) {
+				return {
+					content: [{ type: "text", text: `Background mode requires upstream jiti for TypeScript execution but it could not be found. Ensure the ${APP_NAME}-subagents package dependencies are installed.` }],
+					isError: true,
+					details: { mode: "single" as const, results: [] },
+				};
+			}
+			const id = randomUUID();
+			const asyncCtx = {
+				pi: deps.pi,
+				cwd: ctx.cwd,
+				currentSessionId: deps.state.currentSessionId!,
+				currentModelProvider: ctx.model?.provider,
+				currentModel: currentModelFullId(ctx.model),
+			};
+			return deps.runtime.executeAsyncSingle(id, {
+				agent: params.agent!,
+				task: params.context === "fork" ? wrapForkTask(task) : task,
+				agentConfig,
+				ctx: asyncCtx,
+				availableModels,
+				cwd: effectiveCwd,
+				maxOutput: params.maxOutput,
+				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
+				artifactConfig,
+				shareEnabled,
+				sessionRoot,
+				sessionFile: sessionFileForIndex(0),
+				skills: skillOverride === false ? [] : skillOverride,
+				output: effectiveOutput,
+				outputMode: effectiveOutputMode,
+				modelOverride,
+				maxSubagentDepth,
+				workflowStageSubagentGuard,
+				worktreeSetupHook: deps.config.worktreeSetupHook,
+				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				controlConfig,
+				controlIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+				childIntercomTarget: data.intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(id, agent, index) : undefined,
+			});
+		}
+	}
+
+	if (params.context === "fork") {
+		task = wrapForkTask(task);
+	}
+	const cleanTask = task;
+	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, effectiveCwd);
+	const validationError = validateFileOnlyOutputMode(effectiveOutputMode, outputPath, `Single run (${params.agent})`);
+	if (validationError) {
+		return { content: [{ type: "text", text: validationError }], isError: true, details: { mode: "single", results: [] } };
+	}
+	task = injectSingleOutputInstruction(task, outputPath);
+
+	let effectiveSkills: string[] | undefined;
+	if (skillOverride === false) {
+		effectiveSkills = [];
+	} else {
+		effectiveSkills = skillOverride;
+	}
+	const interruptController = new AbortController();
+	const foregroundControl = deps.state.foregroundControls.get(runId);
+	if (foregroundControl) {
+		foregroundControl.currentAgent = params.agent;
+		foregroundControl.currentIndex = 0;
+		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 forwardSingleUpdate = onUpdate
+		? (update: SubagentToolResult) => {
+			if (foregroundControl) {
+				const firstProgress = update.details?.progress?.[0];
+				foregroundControl.currentAgent = params.agent;
+				foregroundControl.currentIndex = firstProgress?.index ?? 0;
+				foregroundControl.currentActivityState = firstProgress?.activityState;
+				foregroundControl.lastActivityAt = firstProgress?.lastActivityAt;
+				foregroundControl.currentTool = firstProgress?.currentTool;
+				foregroundControl.currentToolStartedAt = firstProgress?.currentToolStartedAt;
+				foregroundControl.currentPath = firstProgress?.currentPath;
+				foregroundControl.turnCount = firstProgress?.turnCount;
+				foregroundControl.tokens = firstProgress?.tokens;
+				foregroundControl.toolCount = firstProgress?.toolCount;
+				foregroundControl.updatedAt = Date.now();
+			}
+			onUpdate(update);
+		}
+		: undefined;
+
+	const r = await deps.runtime.runSync(ctx.cwd, agents, params.agent!, task, {
+		cwd: effectiveCwd,
+		signal,
+		interruptSignal: interruptController.signal,
+		allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
+		intercomEvents: deps.pi.events,
+		runId,
+		sessionDir: sessionDirForIndex(0),
+		sessionFile: sessionFileForIndex(0),
+		share: shareEnabled,
+		artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
+		artifactConfig,
+		maxOutput: params.maxOutput,
+		outputPath,
+		outputMode: effectiveOutputMode,
+		maxSubagentDepth,
+		workflowStageSubagentGuard,
+		onUpdate: forwardSingleUpdate,
+		controlConfig,
+		onControlEvent,
+		intercomSessionName: childIntercomTarget,
+		orchestratorIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+		nestedRoute: foregroundControl?.nestedRoute,
+		index: 0,
+		modelOverride,
+		availableModels,
+		preferredModelProvider: currentProvider,
+		currentModel: currentModelFullId(ctx.model),
+		skills: effectiveSkills,
+	});
+	if (foregroundControl?.currentIndex === 0) {
+		foregroundControl.interrupt = undefined;
+		foregroundControl.currentActivityState = r.progress?.activityState;
+		foregroundControl.lastActivityAt = r.progress?.lastActivityAt;
+		foregroundControl.currentTool = r.progress?.currentTool;
+		foregroundControl.currentToolStartedAt = r.progress?.currentToolStartedAt;
+		foregroundControl.currentPath = r.progress?.currentPath;
+		foregroundControl.turnCount = r.progress?.turnCount;
+		foregroundControl.tokens = r.progress?.tokens;
+		foregroundControl.toolCount = r.progress?.toolCount;
+		foregroundControl.updatedAt = Date.now();
+	}
+	recordRun(params.agent!, cleanTask, r.exitCode, r.progressSummary?.durationMs ?? 0);
+
+	if (r.progress) allProgress.push(r.progress);
+	if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
+
+	const fullOutput = getSingleResultOutput(r);
+	const finalizedOutput = finalizeSingleOutput({
+		fullOutput,
+		truncatedOutput: r.truncation?.text,
+		outputPath,
+		outputMode: r.outputMode,
+		exitCode: r.exitCode,
+		savedPath: r.savedOutputPath,
+		outputReference: r.outputReference,
+		saveError: r.outputSaveError,
+	});
+	const details = compactForegroundDetails({
+		mode: "single",
+		runId,
+		results: [r],
+		progress: params.includeProgress ? allProgress : undefined,
+		artifacts: allArtifactPaths.length ? { dir: artifactsDir, files: allArtifactPaths } : undefined,
+		truncation: r.truncation,
+	});
+	rememberForegroundRun(deps.state, { runId, mode: "single", cwd: effectiveCwd, results: details.results });
+
+	if (!r.detached && !r.interrupted) {
+		if (foregroundControl) updateForegroundNestedProjection(foregroundControl);
+		const intercomReceipt = await maybeBuildForegroundIntercomReceipt({
+			pi: deps.pi,
+			intercomBridge: data.intercomBridge,
+			runId,
+			mode: "single",
+			details,
+			...(foregroundControl?.nestedChildren?.length ? { nestedChildren: foregroundControl.nestedChildren } : {}),
+		});
+		if (intercomReceipt) {
+			return {
+				content: [{ type: "text", text: intercomReceipt.text }],
+				details: intercomReceipt.details,
+				...(r.exitCode !== 0 ? { isError: true } : {}),
+			};
+		}
+	}
+
+	if (r.detached) {
+		return {
+			content: [{ type: "text", text: `Detached for intercom coordination: ${params.agent}. Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.` }],
+			details,
+		};
+	}
+
+	if (r.interrupted) {
+		return {
+			content: [{ type: "text", text: `Run paused after interrupt (${params.agent}). Waiting for explicit next action.` }],
+			details,
+		};
+	}
+
+	if (r.exitCode !== 0)
+		return {
+			content: [{ type: "text", text: r.error || "Failed" }],
+			details,
+			isError: true,
+		};
+	return {
+		content: [{ type: "text", text: finalizedOutput.displayOutput || "(no output)" }],
+		details,
+	};
+}

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-status.ts

@@ -0,0 +1,207 @@
+import type { ExtensionAPI } from "@bastani/atomic";
+import { compactForegroundDetails, getSingleResultOutput } from "../../shared/utils.ts";
+import {
+	attachNestedChildrenToResultChildren,
+	buildSubagentResultIntercomPayload,
+	deliverSubagentResultIntercomEvent,
+	formatSubagentResultReceipt,
+	resolveSubagentResultStatus,
+	stripDetailsOutputsForIntercomReceipt,
+} from "../../intercom/result-intercom.ts";
+import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
+import { formatControlIntercomMessage, formatControlNoticeMessage, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
+import { updateForegroundNestedProjection } from "../shared/nested-events.ts";
+import {
+	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_CONTROL_INTERCOM_EVENT,
+	type ControlEvent,
+	type Details,
+	type NestedRunSummary,
+	type SingleResult,
+	type SubagentRunMode,
+	type SubagentState,
+	type SubagentToolResult,
+} from "../../shared/types.ts";
+import { resolveSubagentIntercomTarget, type IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
+import type { ExecutorDeps, ExecutionContextData, ForegroundControl } from "./subagent-executor-types.ts";
+
+export function getForegroundControl(state: SubagentState, runId: string | undefined): ForegroundControl | undefined {
+	if (runId) return state.foregroundControls.get(runId);
+	if (state.lastForegroundControlId) {
+		const latest = state.foregroundControls.get(state.lastForegroundControlId);
+		if (latest) return latest;
+	}
+	let newest: ForegroundControl | undefined;
+	for (const control of state.foregroundControls.values()) {
+		if (!newest || control.updatedAt > newest.updatedAt) newest = control;
+	}
+	return newest;
+}
+
+function formatForegroundActivity(control: ForegroundControl): string | undefined {
+	const facts: string[] = [];
+	if (control.currentTool && control.currentToolStartedAt) facts.push(`tool ${control.currentTool} for ${Math.floor(Math.max(0, Date.now() - control.currentToolStartedAt) / 1000)}s`);
+	else if (control.currentTool) facts.push(`tool ${control.currentTool}`);
+	if (control.currentPath) facts.push(`path ${control.currentPath}`);
+	if (control.turnCount !== undefined) facts.push(`${control.turnCount} turns`);
+	if (control.tokens !== undefined) facts.push(`${control.tokens} tokens`);
+	if (control.toolCount !== undefined) facts.push(`${control.toolCount} tools`);
+	if (!control.lastActivityAt) {
+		if (control.currentActivityState === "needs_attention") return ["needs attention", ...facts].join(" | ");
+		if (control.currentActivityState === "active_long_running") return ["active but long-running", ...facts].join(" | ");
+		return facts.length ? facts.join(" | ") : undefined;
+	}
+	const seconds = Math.floor(Math.max(0, Date.now() - control.lastActivityAt) / 1000);
+	if (control.currentActivityState === "needs_attention") return [`no activity for ${seconds}s`, ...facts].join(" | ");
+	if (control.currentActivityState === "active_long_running") return [`active but long-running; last activity ${seconds}s ago`, ...facts].join(" | ");
+	return [`active ${seconds}s ago`, ...facts].join(" | ");
+}
+
+export function foregroundStatusResult(control: ForegroundControl): SubagentToolResult {
+	let nestedWarning: string | undefined;
+	try {
+		updateForegroundNestedProjection(control);
+	} catch (error) {
+		nestedWarning = `Nested status unavailable: ${error instanceof Error ? error.message : String(error)}`;
+	}
+	const activity = formatForegroundActivity(control);
+	const lines = [
+		`Run: ${control.runId}`,
+		"State: running",
+		`Mode: ${control.mode}`,
+		control.currentAgent ? `Current: ${control.currentAgent}${control.currentIndex !== undefined ? ` step ${control.currentIndex + 1}` : ""}` : undefined,
+		activity ? `Activity: ${activity}` : undefined,
+	].filter((line): line is string => Boolean(line));
+	lines.push(...formatNestedRunStatusLines(control.nestedChildren, { indent: "", commandHints: true, maxLines: 20 }));
+	if (nestedWarning) lines.push(`Warning: ${nestedWarning}`);
+	return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "management", results: [] } };
+}
+
+export function rememberForegroundRun(state: SubagentState, input: { runId: string; mode: "single" | "parallel" | "chain"; cwd: string; results: SingleResult[] }): void {
+	state.foregroundRuns ??= new Map();
+	state.foregroundRuns.set(input.runId, {
+		runId: input.runId,
+		mode: input.mode,
+		cwd: input.cwd,
+		updatedAt: Date.now(),
+		children: input.results.map((result, index) => ({
+			agent: result.agent,
+			index,
+			status: resolveSubagentResultStatus({ exitCode: result.exitCode, interrupted: result.interrupted, detached: result.detached }),
+			...(result.sessionFile ? { sessionFile: result.sessionFile } : {}),
+		})),
+	});
+	while (state.foregroundRuns.size > 50) {
+		const oldest = [...state.foregroundRuns.values()].sort((left, right) => left.updatedAt - right.updatedAt)[0];
+		if (!oldest) break;
+		state.foregroundRuns.delete(oldest.runId);
+	}
+}
+
+export function emitControlNotification(input: {
+	pi: ExtensionAPI;
+	controlConfig: ExecutionContextData["controlConfig"];
+	intercomBridge: IntercomBridgeState;
+	event: ControlEvent;
+}): void {
+	if (!shouldNotifyControlEvent(input.controlConfig, input.event)) return;
+	const childIntercomTarget = input.intercomBridge.active
+		? resolveSubagentIntercomTarget(input.event.runId, input.event.agent, input.event.index)
+		: undefined;
+	const payload = {
+		event: input.event,
+		source: "foreground" as const,
+		childIntercomTarget,
+		noticeText: formatControlNoticeMessage(input.event, childIntercomTarget),
+	};
+	if (input.controlConfig.notifyChannels.includes("event")) {
+		input.pi.events.emit(SUBAGENT_CONTROL_EVENT, payload);
+	}
+	if (input.event.type !== "active_long_running" && input.controlConfig.notifyChannels.includes("intercom") && input.intercomBridge.active && input.intercomBridge.orchestratorTarget) {
+		input.pi.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
+			...payload,
+			to: input.intercomBridge.orchestratorTarget,
+			message: formatControlIntercomMessage(input.event, childIntercomTarget),
+		});
+	}
+}
+
+export function createForegroundControlNotifier(data: Pick<ExecutionContextData, "controlConfig" | "intercomBridge">, deps: Pick<ExecutorDeps, "pi">): (event: ControlEvent) => void {
+	return (event) => emitControlNotification({
+		pi: deps.pi,
+		controlConfig: data.controlConfig,
+		intercomBridge: data.intercomBridge,
+		event,
+	});
+}
+
+function resultSummaryForIntercom(result: SingleResult): string {
+	const output = getSingleResultOutput(result);
+	if (result.exitCode !== 0 && result.error) {
+		return output ? `${result.error}\n\nOutput:\n${output}` : result.error;
+	}
+	return output || result.error || "(no output)";
+}
+
+async function emitForegroundResultIntercom(input: {
+	pi: ExtensionAPI;
+	intercomBridge: IntercomBridgeState;
+	runId: string;
+	mode: SubagentRunMode;
+	results: SingleResult[];
+	chainSteps?: number;
+	nestedChildren?: NestedRunSummary[];
+}): Promise<ReturnType<typeof buildSubagentResultIntercomPayload> | null> {
+	if (!input.intercomBridge.active || !input.intercomBridge.orchestratorTarget) return null;
+	const children = input.results.flatMap((result, index) => result.detached ? [] : [{
+		agent: result.agent,
+		status: resolveSubagentResultStatus({
+			exitCode: result.exitCode,
+			interrupted: result.interrupted,
+			detached: result.detached,
+		}),
+		summary: resultSummaryForIntercom(result),
+		index,
+		artifactPath: result.artifactPaths?.outputPath,
+		sessionPath: result.sessionFile,
+		intercomTarget: resolveSubagentIntercomTarget(input.runId, result.agent, index),
+	}]);
+	if (children.length === 0) return null;
+	const payload = buildSubagentResultIntercomPayload({
+		to: input.intercomBridge.orchestratorTarget,
+		runId: input.runId,
+		mode: input.mode,
+		source: "foreground",
+		children: attachNestedChildrenToResultChildren(input.runId, children, input.nestedChildren),
+		...(typeof input.chainSteps === "number" ? { chainSteps: input.chainSteps } : {}),
+	});
+	const delivered = await deliverSubagentResultIntercomEvent(input.pi.events, payload);
+	if (!delivered) return null;
+	return payload;
+}
+
+export async function maybeBuildForegroundIntercomReceipt(input: {
+	pi: ExtensionAPI;
+	intercomBridge: IntercomBridgeState;
+	runId: string;
+	mode: SubagentRunMode;
+	details: Details;
+	nestedChildren?: NestedRunSummary[];
+}): Promise<{ text: string; details: Details } | null> {
+	const payload = await emitForegroundResultIntercom({
+		pi: input.pi,
+		intercomBridge: input.intercomBridge,
+		runId: input.runId,
+		mode: input.mode,
+		results: input.details.results,
+		...(typeof input.details.totalSteps === "number" ? { chainSteps: input.details.totalSteps } : {}),
+		...(input.nestedChildren?.length ? { nestedChildren: input.nestedChildren } : {}),
+	});
+	if (!payload) return null;
+	return {
+		text: formatSubagentResultReceipt({ mode: input.mode, runId: input.runId, payload }),
+		details: stripDetailsOutputsForIntercomReceipt(input.details),
+	};
+}
+
+export { compactForegroundDetails };

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-types.ts

@@ -0,0 +1,121 @@
+import type { ExtensionAPI, ExtensionContext } from "@bastani/atomic";
+import type { AgentConfig, AgentScope } from "../../agents/agents.ts";
+import type { IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
+import type { ModelInfo } from "../../shared/model-info.ts";
+import type { ArtifactConfig, ControlConfig, MaxOutputConfig, NestedRouteInfo, ResolvedControlConfig, SubagentState, SubagentToolResult, SUBAGENT_ACTIONS } from "../../shared/types.ts";
+import type { ChainStep } from "../../shared/settings.ts";
+import type { executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable } from "../background/async-execution.ts";
+import type { runSync } from "./execution.ts";
+
+export interface TaskParam {
+	agent: string;
+	task: string;
+	cwd?: string;
+	count?: number;
+	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
+	reads?: string[] | boolean;
+	progress?: boolean;
+	model?: string;
+	skill?: string | string[] | boolean;
+}
+
+export interface SubagentParamsLike {
+	action?: (typeof SUBAGENT_ACTIONS)[number];
+	id?: string;
+	runId?: string;
+	dir?: string;
+	index?: number;
+	agent?: string;
+	task?: string;
+	message?: string;
+	chainName?: string;
+	config?: unknown;
+	chain?: ChainStep[];
+	tasks?: TaskParam[];
+	concurrency?: number;
+	worktree?: boolean;
+	context?: "fresh" | "fork";
+	async?: boolean;
+	clarify?: boolean;
+	share?: boolean;
+	control?: ControlConfig;
+	sessionDir?: string;
+	cwd?: string;
+	maxOutput?: MaxOutputConfig;
+	artifacts?: boolean;
+	includeProgress?: boolean;
+	model?: string;
+	skill?: string | string[] | boolean;
+	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
+	agentScope?: string;
+	chainDir?: string;
+}
+
+export interface SubagentExecutorRuntimeDeps {
+	runSync: typeof runSync;
+	executeAsyncChain: typeof executeAsyncChain;
+	executeAsyncSingle: typeof executeAsyncSingle;
+	isAsyncAvailable: typeof isAsyncAvailable;
+	formatAsyncStartedMessage: typeof formatAsyncStartedMessage;
+}
+
+export interface ExecutorDeps {
+	pi: ExtensionAPI;
+	state: SubagentState;
+	config: import("../../shared/types.ts").ExtensionConfig;
+	asyncByDefault: boolean;
+	tempArtifactsDir: string;
+	getSubagentSessionRoot: (parentSessionFile: string | null) => string;
+	expandTilde: (p: string) => string;
+	discoverAgents: (cwd: string, scope: AgentScope) => { agents: AgentConfig[] };
+	allowMutatingManagementActions?: boolean;
+	runtime?: Partial<SubagentExecutorRuntimeDeps>;
+}
+
+export interface ResolvedExecutorDeps extends Omit<ExecutorDeps, "runtime"> {
+	runtime: SubagentExecutorRuntimeDeps;
+}
+
+export interface ExecutionContextData {
+	params: SubagentParamsLike;
+	effectiveCwd: string;
+	ctx: ExtensionContext;
+	signal: AbortSignal;
+	onUpdate?: (r: SubagentToolResult) => void;
+	agents: AgentConfig[];
+	runId: string;
+	shareEnabled: boolean;
+	sessionRoot: string;
+	sessionDirForIndex: (idx?: number) => string;
+	sessionFileForIndex: (idx?: number) => string | undefined;
+	artifactConfig: ArtifactConfig;
+	artifactsDir: string;
+	backgroundRequestedWhileClarifying: boolean;
+	effectiveAsync: boolean;
+	controlConfig: ResolvedControlConfig;
+	intercomBridge: IntercomBridgeState;
+	nestedRoute?: NestedRouteInfo;
+}
+
+export interface PreparedExecutionContext {
+	effectiveParams: SubagentParamsLike;
+	effectiveCwd: string;
+	runId: string;
+	hasChain: boolean;
+	hasTasks: boolean;
+	hasSingle: boolean;
+	foregroundMode: "single" | "parallel" | "chain";
+	execData: ExecutionContextData;
+	foregroundControl?: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
+	writeNestedForegroundEvent: (type: "subagent.nested.started" | "subagent.nested.completed", result?: SubagentToolResult) => void;
+}
+
+export interface ExecutionContextBuildResult {
+	prepared?: PreparedExecutionContext;
+	error?: SubagentToolResult;
+}
+
+export type ForegroundControl = SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
+export type AvailableModelInfo = ModelInfo;