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

package/dist/builtin/subagents/src/shared/types.ts

@@ -1,978 +1,13 @@
 /**
- * Type definitions for the subagent extension
+ * Type definitions for the subagent extension.
+ *
+ * This module remains the stable public import path and re-exports the
+ * focused sibling modules that hold the concrete type groups and helpers.
  */
 
-import * as os from "node:os";
-import * as path from "node:path";
-import type { Message } from "@earendil-works/pi-ai";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { FSWatcher } from "node:fs";
-import type { ExtensionContext } from "@bastani/atomic";
-import { APP_NAME, getEnvValue, WORKFLOW_STAGE_SUBAGENT_GUARD_ENV } from "@bastani/atomic";
-
-const ENV_PREFIX = APP_NAME.toUpperCase();
-const SUBAGENT_MAX_DEPTH_ENV = `${ENV_PREFIX}_SUBAGENT_MAX_DEPTH`;
-const SUBAGENT_DEPTH_ENV = `${ENV_PREFIX}_SUBAGENT_DEPTH`;
-export { WORKFLOW_STAGE_SUBAGENT_GUARD_ENV };
-
-// ============================================================================
-// Basic Types
-// ============================================================================
-
-export interface MaxOutputConfig {
-	bytes?: number;
-	lines?: number;
-}
-
-export type OutputMode = "inline" | "file-only";
-
-export type JsonSchemaObject = Record<string, unknown>;
-
-export interface ChainOutputMapEntry {
-	text: string;
-	structured?: unknown;
-	agent: string;
-	stepIndex: number;
-}
-
-export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
-
-export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "detached";
-
-export interface WorkflowGraphNode {
-	id: string;
-	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
-	agent?: string;
-	phase?: string;
-	label: string;
-	status: WorkflowNodeStatus;
-	flatIndex?: number;
-	stepIndex?: number;
-	children?: WorkflowGraphNode[];
-	dynamic?: {
-		sourceOutput: string;
-		sourcePath: string;
-		itemName: string;
-		maxItems?: number;
-		collectAs?: string;
-	};
-	itemKey?: string;
-	outputName?: string;
-	structured?: boolean;
-	error?: string;
-}
-
-export interface WorkflowGraphSnapshot {
-	runId: string;
-	mode: "chain" | "parallel" | "single";
-	phases: Array<{ title: string; nodeIds: string[] }>;
-	nodes: WorkflowGraphNode[];
-	currentNodeId?: string;
-}
-
-export interface SavedOutputReference {
-	path: string;
-	bytes: number;
-	lines: number;
-	message: string;
-}
-
-interface TruncationResult {
-	text: string;
-	truncated: boolean;
-	originalBytes?: number;
-	originalLines?: number;
-	artifactPath?: string;
-}
-
-export interface Usage {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	cost: number;
-	turns: number;
-}
-
-export interface TokenUsage {
-	input: number;
-	output: number;
-	total: number;
-}
-
-export type ActivityState = "active_long_running" | "needs_attention";
-export type ControlEventType = "active_long_running" | "needs_attention";
-export type ControlNotificationChannel = "event" | "async" | "intercom";
-
-export interface ControlConfig {
-	enabled?: boolean;
-	needsAttentionAfterMs?: number;
-	activeNoticeAfterMs?: number;
-	activeNoticeAfterTurns?: number;
-	activeNoticeAfterTokens?: number;
-	failedToolAttemptsBeforeAttention?: number;
-	notifyOn?: ControlEventType[];
-	notifyChannels?: ControlNotificationChannel[];
-}
-
-export interface ResolvedControlConfig {
-	enabled: boolean;
-	needsAttentionAfterMs: number;
-	activeNoticeAfterMs: number;
-	activeNoticeAfterTurns?: number;
-	activeNoticeAfterTokens?: number;
-	failedToolAttemptsBeforeAttention: number;
-	notifyOn: ControlEventType[];
-	notifyChannels: ControlNotificationChannel[];
-}
-
-export interface ControlEvent {
-	type: ControlEventType;
-	from?: ActivityState;
-	to: ActivityState;
-	ts: number;
-	agent: string;
-	index?: number;
-	runId: string;
-	nestedRunId?: string;
-	nestingPath?: NestedRunAddress["path"];
-	message: string;
-	reason?: "idle" | "active_long_running" | "tool_failures" | "time_threshold" | "turn_threshold" | "token_threshold";
-	turns?: number;
-	tokens?: number;
-	toolCount?: number;
-	currentTool?: string;
-	currentToolDurationMs?: number;
-	currentPath?: string;
-	elapsedMs?: number;
-	recentFailureSummary?: string;
-}
-
-export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached";
-export type SubagentRunMode = "single" | "parallel" | "chain";
-
-export type PublicNestedStepSummary = Pick<
-	NestedStepSummary,
-	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error"
-> & {
-	children?: PublicNestedRunSummary[];
-};
-
-export type PublicNestedRunSummary = Pick<
-	NestedRunSummary,
-	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "totalTokens" | "startedAt" | "endedAt" | "lastUpdate" | "error"
-> & {
-	steps?: PublicNestedStepSummary[];
-	children?: PublicNestedRunSummary[];
-};
-
-export interface SubagentResultIntercomChild {
-	agent: string;
-	status: SubagentResultStatus;
-	summary: string;
-	index?: number;
-	artifactPath?: string;
-	sessionPath?: string;
-	intercomTarget?: string;
-	children?: PublicNestedRunSummary[];
-}
-
-export interface SubagentResultIntercomPayload {
-	to: string;
-	message: string;
-	requestId?: string;
-	runId: string;
-	mode: SubagentRunMode;
-	status: SubagentResultStatus;
-	summary: string;
-	source: "foreground" | "async";
-	children: SubagentResultIntercomChild[];
-	asyncId?: string;
-	asyncDir?: string;
-	chainSteps?: number;
-	agent?: string;
-	index?: number;
-	artifactPath?: string;
-	sessionPath?: string;
-}
-
-// ============================================================================
-// Progress Tracking
-// ============================================================================
-
-export interface AgentProgress {
-	index: number;
-	agent: string;
-	status: "pending" | "running" | "completed" | "failed" | "detached";
-	activityState?: ActivityState;
-	task: string;
-	skills?: string[];
-	lastActivityAt?: number;
-	currentTool?: string;
-	currentToolArgs?: string;
-	currentToolStartedAt?: number;
-	currentPath?: string;
-	recentTools: Array<{ tool: string; args: string; endMs: number }>;
-	recentOutput: string[];
-	toolCount: number;
-	turnCount?: number;
-	tokens: number;
-	durationMs: number;
-	error?: string;
-	failedTool?: string;
-}
-
-export interface ToolCallSummary {
-	text: string;
-	expandedText: string;
-}
-
-interface ProgressSummary {
-	toolCount: number;
-	tokens: number;
-	durationMs: number;
-}
-
-// ============================================================================
-// Results
-// ============================================================================
-
-export interface ModelAttempt {
-	model: string;
-	reasoningLevel?: string;
-	success: boolean;
-	exitCode?: number | null;
-	error?: string;
-	usage?: Usage;
-}
-
-export interface SingleResult {
-	agent: string;
-	task: string;
-	exitCode: number;
-	detached?: boolean;
-	detachedReason?: string;
-	interrupted?: boolean;
-	messages?: Message[];
-	usage: Usage;
-	model?: string;
-	fastMode?: boolean;
-	attemptedModels?: string[];
-	modelAttempts?: ModelAttempt[];
-	controlEvents?: ControlEvent[];
-	error?: string;
-	sessionFile?: string;
-	skills?: string[];
-	skillsWarning?: string;
-	progress?: AgentProgress;
-	progressSummary?: ProgressSummary;
-	toolCalls?: ToolCallSummary[];
-	artifactPaths?: ArtifactPaths;
-	truncation?: TruncationResult;
-	finalOutput?: string;
-	outputMode?: OutputMode;
-	savedOutputPath?: string;
-	outputReference?: SavedOutputReference;
-	outputSaveError?: string;
-	structuredOutput?: unknown;
-	structuredOutputPath?: string;
-	structuredOutputSchemaPath?: string;
-}
-
-export interface Details {
-	mode: SubagentRunMode | "management";
-	runId?: string;
-	context?: "fresh" | "fork";
-	results: SingleResult[];
-	controlEvents?: ControlEvent[];
-	asyncId?: string;
-	asyncDir?: string;
-	progress?: AgentProgress[];
-	progressSummary?: ProgressSummary;
-	artifacts?: {
-		dir: string;
-		files: ArtifactPaths[];
-	};
-	truncation?: {
-		truncated: boolean;
-		originalBytes?: number;
-		originalLines?: number;
-		artifactPath?: string;
-	};
-	// Chain metadata for observability
-	chainAgents?: string[];      // Agent names in order, e.g., ["scout", "planner"]
-	totalSteps?: number;         // Total steps in chain
-	currentStepIndex?: number;   // 0-indexed current step (for running chains)
-	workflowGraph?: WorkflowGraphSnapshot;
-	outputs?: ChainOutputMap;
-}
-
-// Upstream AgentToolResult omits the runtime isError flag that subagent tool results still emit/read.
-export type SubagentToolResult = AgentToolResult<Details> & { isError?: boolean };
-
-// ============================================================================
-// Artifacts
-// ============================================================================
-
-export interface ArtifactPaths {
-	inputPath: string;
-	outputPath: string;
-	jsonlPath: string;
-	metadataPath: string;
-}
-
-export interface ArtifactConfig {
-	enabled: boolean;
-	includeInput: boolean;
-	includeOutput: boolean;
-	includeJsonl: boolean;
-	includeMetadata: boolean;
-	cleanupDays: number;
-}
-
-// ============================================================================
-// Async Execution
-// ============================================================================
-
-export interface AsyncParallelGroupStatus {
-	start: number;
-	count: number;
-	stepIndex: number;
-}
-
-export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused";
-export type NestedOwnerState = "live" | "gone" | "unknown";
-
-export interface NestedRunAddress {
-	id: string;
-	parentRunId: string;
-	parentStepIndex?: number;
-	parentAgent?: string;
-	depth: number;
-	path: Array<{ runId: string; stepIndex?: number; agent?: string }>;
-}
-
-export interface NestedStepSummary {
-	agent: string;
-	status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
-	sessionFile?: string;
-	activityState?: ActivityState;
-	lastActivityAt?: number;
-	currentTool?: string;
-	currentToolStartedAt?: number;
-	currentPath?: string;
-	turnCount?: number;
-	toolCount?: number;
-	startedAt?: number;
-	endedAt?: number;
-	error?: string;
-	children?: NestedRunSummary[];
-}
-
-export interface NestedRunSummary extends NestedRunAddress {
-	asyncDir?: string;
-	pid?: number;
-	sessionId?: string;
-	sessionFile?: string;
-	intercomTarget?: string;
-	ownerIntercomTarget?: string;
-	leafIntercomTarget?: string;
-	ownerState?: NestedOwnerState;
-	controlInbox?: string;
-	capabilityToken?: string;
-	mode?: SubagentRunMode;
-	state: NestedRunState;
-	agent?: string;
-	agents?: string[];
-	currentStep?: number;
-	chainStepCount?: number;
-	parallelGroups?: AsyncParallelGroupStatus[];
-	steps?: NestedStepSummary[];
-	children?: NestedRunSummary[];
-	activityState?: ActivityState;
-	lastActivityAt?: number;
-	currentTool?: string;
-	currentToolStartedAt?: number;
-	currentPath?: string;
-	turnCount?: number;
-	toolCount?: number;
-	totalTokens?: TokenUsage;
-	startedAt?: number;
-	endedAt?: number;
-	lastUpdate?: number;
-	error?: string;
-}
-
-export interface NestedRouteInfo {
-	rootRunId: string;
-	eventSink: string;
-	controlInbox: string;
-	capabilityToken: string;
-}
-
-export interface AsyncStartedEvent {
-	id?: string;
-	asyncDir?: string;
-	pid?: number;
-	sessionId?: string;
-	mode?: SubagentRunMode;
-	agent?: string;
-	agents?: string[];
-	chain?: string[];
-	chainStepCount?: number;
-	parallelGroups?: AsyncParallelGroupStatus[];
-	workflowGraph?: WorkflowGraphSnapshot;
-	nestedRoute?: NestedRouteInfo;
-}
-
-export interface AsyncStatus {
-	runId: string;
-	sessionId?: string;
-	mode: SubagentRunMode;
-	state: "queued" | "running" | "complete" | "failed" | "paused";
-	activityState?: ActivityState;
-	lastActivityAt?: number;
-	currentTool?: string;
-	currentToolStartedAt?: number;
-	currentPath?: string;
-	turnCount?: number;
-	toolCount?: number;
-	startedAt: number;
-	endedAt?: number;
-	lastUpdate?: number;
-	pid?: number;
-	cwd?: string;
-	currentStep?: number;
-	chainStepCount?: number;
-	parallelGroups?: AsyncParallelGroupStatus[];
-	workflowGraph?: WorkflowGraphSnapshot;
-	steps?: Array<{
-		agent: string;
-		phase?: string;
-		label?: string;
-		outputName?: string;
-		structured?: boolean;
-		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
-		children?: NestedRunSummary[];
-		sessionFile?: string;
-		activityState?: ActivityState;
-		lastActivityAt?: number;
-		currentTool?: string;
-		currentToolArgs?: string;
-		currentToolStartedAt?: number;
-		currentPath?: string;
-		recentTools?: Array<{ tool: string; args: string; endMs: number }>;
-		recentOutput?: string[];
-		turnCount?: number;
-		toolCount?: number;
-		startedAt?: number;
-		endedAt?: number;
-		durationMs?: number;
-		exitCode?: number | null;
-		tokens?: TokenUsage;
-		skills?: string[];
-		model?: string;
-		thinking?: string;
-		fastMode?: boolean;
-		attemptedModels?: string[];
-		modelAttempts?: ModelAttempt[];
-		error?: string;
-		structuredOutput?: unknown;
-		structuredOutputPath?: string;
-		structuredOutputSchemaPath?: string;
-	}>;
-	sessionDir?: string;
-	outputFile?: string;
-	totalTokens?: TokenUsage;
-	sessionFile?: string;
-	outputs?: ChainOutputMap;
-}
-
-export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
-	index?: number;
-};
-
-export interface AsyncJobState {
-	asyncId: string;
-	asyncDir: string;
-	status: "queued" | "running" | "complete" | "failed" | "paused";
-	pid?: number;
-	sessionId?: string;
-	activityState?: ActivityState;
-	lastActivityAt?: number;
-	currentTool?: string;
-	currentToolStartedAt?: number;
-	currentPath?: string;
-	turnCount?: number;
-	toolCount?: number;
-	mode?: SubagentRunMode;
-	agents?: string[];
-	currentStep?: number;
-	chainStepCount?: number;
-	parallelGroups?: AsyncParallelGroupStatus[];
-	steps?: AsyncJobStep[];
-	stepsTotal?: number;
-	runningSteps?: number;
-	completedSteps?: number;
-	hasParallelGroups?: boolean;
-	activeParallelGroup?: boolean;
-	startedAt?: number;
-	updatedAt?: number;
-	sessionDir?: string;
-	outputFile?: string;
-	totalTokens?: TokenUsage;
-	sessionFile?: string;
-	controlEventCursor?: number;
-	nestedRoute?: NestedRouteInfo;
-	nestedChildren?: NestedRunSummary[];
-}
-
-export interface ForegroundResumeChild {
-	agent: string;
-	index: number;
-	sessionFile?: string;
-	status: SubagentResultStatus;
-}
-
-export interface ForegroundResumeRun {
-	runId: string;
-	mode: SubagentRunMode;
-	cwd: string;
-	updatedAt: number;
-	children: ForegroundResumeChild[];
-}
-
-export interface SubagentState {
-	baseCwd: string;
-	currentSessionId: string | null;
-	asyncJobs: Map<string, AsyncJobState>;
-	foregroundRuns?: Map<string, ForegroundResumeRun>;
-	foregroundControls: Map<string, {
-		runId: string;
-		mode: SubagentRunMode;
-		startedAt: number;
-		updatedAt: number;
-		currentAgent?: string;
-		currentIndex?: number;
-		currentActivityState?: ActivityState;
-		lastActivityAt?: number;
-		currentTool?: string;
-		currentToolStartedAt?: number;
-		currentPath?: string;
-		turnCount?: number;
-		tokens?: number;
-		toolCount?: number;
-		nestedRoute?: NestedRouteInfo;
-		nestedChildren?: NestedRunSummary[];
-		interrupt?: () => boolean;
-	}>;
-	lastForegroundControlId: string | null;
-	pendingForegroundControlNotices?: Map<string, ReturnType<typeof setTimeout>>;
-	cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
-	lastUiContext: ExtensionContext | null;
-	poller: NodeJS.Timeout | null;
-	completionSeen: Map<string, number>;
-	watcher: FSWatcher | null;
-	watcherRestartTimer: ReturnType<typeof setTimeout> | null;
-	resultFileCoalescer: {
-		schedule(file: string, delayMs?: number): boolean;
-		clear(): void;
-	};
-}
-
-// ============================================================================
-// Display
-// ============================================================================
-
-export type DisplayItem =
-	| { type: "text"; text: string }
-	| { type: "tool"; name: string; args: Record<string, unknown> };
-
-// ============================================================================
-// Error Handling
-// ============================================================================
-
-export interface ErrorInfo {
-	hasError: boolean;
-	exitCode?: number;
-	errorType?: string;
-	details?: string;
-}
-
-export interface IntercomEventBus {
-	on(channel: string, handler: (data: unknown) => void): () => void;
-	emit(channel: string, data: unknown): void;
-}
-
-export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
-export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
-export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
-export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
-export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
-export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
-export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
-export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
-
-// ============================================================================
-// Execution Options
-// ============================================================================
-
-export interface RunSyncOptions {
-	cwd?: string;
-	signal?: AbortSignal;
-	interruptSignal?: AbortSignal;
-	allowIntercomDetach?: boolean;
-	intercomEvents?: IntercomEventBus;
-	onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
-	onControlEvent?: (event: ControlEvent) => void;
-	controlConfig?: ResolvedControlConfig;
-	intercomSessionName?: string;
-	orchestratorIntercomTarget?: string;
-	maxOutput?: MaxOutputConfig;
-	artifactsDir?: string;
-	artifactConfig?: ArtifactConfig;
-	runId: string;
-	index?: number;
-	sessionDir?: string;
-	sessionFile?: string;
-	share?: boolean;
-	outputPath?: string;
-	outputMode?: OutputMode;
-	maxSubagentDepth?: number;
-	workflowStageSubagentGuard?: boolean;
-	nestedRoute?: NestedRouteInfo;
-	/** Override the agent's default model (format: "provider/id" or just "id") */
-	modelOverride?: string;
-	/** Registry models available for heuristic bare-model resolution */
-	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
-	/** Current parent-session provider to prefer for ambiguous bare model ids */
-	preferredModelProvider?: string;
-	/** Current parent-session model to try after configured fallback models */
-	currentModel?: string;
-	/** Skills to inject (overrides agent default if provided) */
-	skills?: string[];
-	structuredOutput?: {
-		schema: JsonSchemaObject;
-		schemaPath: string;
-		outputPath: string;
-	};
-}
-
-export type IntercomBridgeMode = "off" | "fork-only" | "always";
-
-export interface IntercomBridgeConfig {
-	mode?: IntercomBridgeMode;
-	instructionFile?: string;
-}
-
-interface TopLevelParallelConfig {
-	maxTasks?: number;
-	concurrency?: number;
-}
-
-interface ExtensionChainConfig {
-	dynamicFanout?: {
-		maxItems?: number;
-	};
-}
-
-export interface ExtensionConfig {
-	asyncByDefault?: boolean;
-	forceTopLevelAsync?: boolean;
-	defaultSessionDir?: string;
-	maxSubagentDepth?: number;
-	control?: ControlConfig;
-	parallel?: TopLevelParallelConfig;
-	chain?: ExtensionChainConfig;
-	worktreeSetupHook?: string;
-	worktreeSetupHookTimeoutMs?: number;
-	intercomBridge?: IntercomBridgeConfig;
-}
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
-	bytes: 200 * 1024,
-	lines: 5000,
-};
-
-export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
-	enabled: true,
-	includeInput: true,
-	includeOutput: true,
-	includeJsonl: false,
-	includeMetadata: true,
-	cleanupDays: 7,
-};
-
-function sanitizeTempScopeSegment(value: string): string {
-	const sanitized = value
-		.trim()
-		.replace(/[^A-Za-z0-9._-]+/g, "-")
-		.replace(/^-+|-+$/g, "");
-	return sanitized || "unknown";
-}
-
-export function resolveTempScopeId(options?: {
-	env?: NodeJS.ProcessEnv;
-	getuid?: (() => number) | undefined;
-	userInfo?: (() => { username?: string | null }) | undefined;
-	homedir?: (() => string) | undefined;
-}): string {
-	const env = options?.env ?? process.env;
-	const getuid = options && Object.hasOwn(options, "getuid")
-		? options.getuid
-		: process.getuid?.bind(process);
-	if (typeof getuid === "function") {
-		return `uid-${getuid()}`;
-	}
-
-	for (const key of ["USERNAME", "USER", "LOGNAME"] as const) {
-		const value = env[key];
-		if (value) return `user-${sanitizeTempScopeSegment(value)}`;
-	}
-
-	const userInfo = options && Object.hasOwn(options, "userInfo")
-		? options.userInfo
-		: os.userInfo;
-	try {
-		const username = userInfo?.().username;
-		if (username) return `user-${sanitizeTempScopeSegment(username)}`;
-	} catch {
-		// Fall through to home-directory-based scoping.
-	}
-
-	const homedir = env.USERPROFILE ?? env.HOME;
-	if (homedir) return `home-${sanitizeTempScopeSegment(homedir)}`;
-
-	const resolveHomedir = options && Object.hasOwn(options, "homedir")
-		? options.homedir
-		: os.homedir;
-	try {
-		const fallbackHomedir = resolveHomedir?.();
-		if (fallbackHomedir) return `home-${sanitizeTempScopeSegment(fallbackHomedir)}`;
-	} catch {
-		// Fall through to the last-resort shared scope.
-	}
-
-	return "shared";
-}
-
-const MAX_PARALLEL = 8;
-export const MAX_CONCURRENCY = 4;
-export const TEMP_ROOT_DIR = path.join(os.tmpdir(), `${APP_NAME}-subagents-${resolveTempScopeId()}`);
-export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
-export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
-export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
-export const TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
-export const WIDGET_KEY = "subagent-async";
-export const SLASH_RESULT_TYPE = "subagent-slash-result";
-export const SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
-export const SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
-export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
-export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
-export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
-export const POLL_INTERVAL_MS = 250;
-export const MAX_WIDGET_JOBS = 4;
-export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "create", "update", "delete", "status", "interrupt", "resume", "doctor"] as const;
-
-export const DEFAULT_FORK_PREAMBLE =
-	"You are a delegated subagent running from a fork of the parent session. " +
-	"Treat the inherited conversation as reference-only context, not a live thread to continue. " +
-	"Do not continue or answer prior messages as if they are waiting for a reply. " +
-	"Your sole job is to execute the task below and return a focused result for that task using your tools.";
-
-function normalizeTopLevelParallelValue(value: unknown): number | undefined {
-	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
-	if (!Number.isInteger(parsed) || parsed < 1) return undefined;
-	return parsed;
-}
-
-export function resolveTopLevelParallelMaxTasks(value: unknown): number {
-	return normalizeTopLevelParallelValue(value) ?? MAX_PARALLEL;
-}
-
-export function resolveTopLevelParallelConcurrency(
-	override: unknown,
-	configValue: unknown,
-): number {
-	return normalizeTopLevelParallelValue(override)
-		?? normalizeTopLevelParallelValue(configValue)
-		?? MAX_CONCURRENCY;
-}
-
-export function getAsyncConfigPath(suffix: string): string {
-	return path.join(TEMP_ROOT_DIR, `async-cfg-${suffix}.json`);
-}
-
-export function wrapForkTask(task: string, preamble?: string | false): string {
-	if (preamble === false) return task;
-	const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
-	const wrappedPrefix = `${effectivePreamble}\n\nTask:\n`;
-	if (task.startsWith(wrappedPrefix)) return task;
-	return `${wrappedPrefix}${task}`;
-}
-
-// ============================================================================
-// Recursion Depth Guard
-// ============================================================================
-
-export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
-	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
-	if (!Number.isInteger(parsed) || parsed < 0) return undefined;
-	return parsed;
-}
-
-export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
-	return normalizeMaxSubagentDepth(getEnvValue(SUBAGENT_MAX_DEPTH_ENV))
-		?? normalizeMaxSubagentDepth(configMaxDepth)
-		?? DEFAULT_SUBAGENT_MAX_DEPTH;
-}
-
-export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDepth?: number): number {
-	const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
-	const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
-	return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
-}
-
-export function hasWorkflowStageSubagentGuard(): boolean {
-	return getEnvValue(WORKFLOW_STAGE_SUBAGENT_GUARD_ENV) === "1";
-}
-
-export function isWorkflowStageOrchestrationContext(ctx: Pick<ExtensionContext, "orchestrationContext">): boolean {
-	return ctx.orchestrationContext?.kind === "workflow-stage";
-}
-
-export function resolveWorkflowStageMaxSubagentDepth(
-	ctx: Pick<ExtensionContext, "orchestrationContext">,
-	configMaxDepth?: number,
-): number {
-	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
-	return isWorkflowStageOrchestrationContext(ctx)
-		// Workflow stages use the same two-hop default as main chat. A 0-depth
-		// constraint still preserves one child-subagent hop so configured workflow
-		// stages can delegate at least once.
-		? Math.min(maxDepth, Math.max(1, ctx.orchestrationContext?.constraints.maxSubagentDepth ?? 1))
-		: maxDepth;
-}
-
-export interface SubagentDepthPolicy {
-	maxSubagentDepth: number;
-	workflowStageSubagentGuard: boolean;
-}
-
-export function resolveSubagentDepthPolicy(
-	ctx: Pick<ExtensionContext, "orchestrationContext">,
-	configMaxDepth?: number,
-): SubagentDepthPolicy {
-	return {
-		maxSubagentDepth: resolveWorkflowStageMaxSubagentDepth(ctx, configMaxDepth),
-		workflowStageSubagentGuard: isWorkflowStageOrchestrationContext(ctx),
-	};
-}
-
-function workflowStageSubagentDepthMessage(depth: number, maxDepth: number, action: "call" | "resume" = "call"): string {
-	return `Nested subagent ${action} blocked (depth=${depth}, max=${maxDepth}). Sub-agents inside workflow stages are running at the maximum nesting depth.`;
-}
-
-export function subagentDepthBlockedMessage(
-	depth: number,
-	maxDepth: number,
-	options?: { action?: "call" | "resume"; workflowStageGuard?: boolean },
-): string {
-	const action = options?.action ?? "call";
-	if (options?.workflowStageGuard) {
-		return workflowStageSubagentDepthMessage(depth, maxDepth, action);
-	}
-	if (action === "resume") {
-		return `Nested subagent resume blocked (depth=${depth}, max=${maxDepth}). Complete the follow-up directly instead.`;
-	}
-	return `Nested subagent call blocked (depth=${depth}, max=${maxDepth}). ` +
-		"You are running at the maximum subagent nesting depth. " +
-		"Complete your current task directly without delegating to further subagents.";
-}
-
-export interface SubagentDepthCheck {
-	blocked: boolean;
-	depth: number;
-	maxDepth: number;
-	workflowStageGuard: boolean;
-}
-
-export function checkSubagentDepth(configMaxDepth?: number): SubagentDepthCheck {
-	const depth = Number(getEnvValue(SUBAGENT_DEPTH_ENV) ?? "0");
-	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
-	const blocked = Number.isFinite(depth) && depth >= maxDepth;
-	return { blocked, depth, maxDepth, workflowStageGuard: hasWorkflowStageSubagentGuard() };
-}
-
-export function getSubagentDepthEnv(maxDepth?: number, options?: { workflowStageSubagentGuard?: boolean }): Record<string, string> {
-	const parentDepth = Number(getEnvValue(SUBAGENT_DEPTH_ENV) ?? "0");
-	// Preserve an inherited workflow-stage marker for descendants; callers that
-	// mutate process.env in tests must clear it to avoid intentional propagation.
-	const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
-	return {
-		[SUBAGENT_DEPTH_ENV]: String(nextDepth),
-		[SUBAGENT_MAX_DEPTH_ENV]: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
-		...(options?.workflowStageSubagentGuard || hasWorkflowStageSubagentGuard()
-			? { [WORKFLOW_STAGE_SUBAGENT_GUARD_ENV]: "1" }
-			: {}),
-	};
-}
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-function formatBytes(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
-export function truncateOutput(
-	output: string,
-	config: Required<MaxOutputConfig>,
-	artifactPath?: string,
-): TruncationResult {
-	const lines = output.split("\n");
-	const bytes = Buffer.byteLength(output, "utf-8");
-
-	if (bytes <= config.bytes && lines.length <= config.lines) {
-		return { text: output, truncated: false };
-	}
-
-	let truncatedLines = lines;
-	if (lines.length > config.lines) {
-		truncatedLines = lines.slice(0, config.lines);
-	}
-
-	let result = truncatedLines.join("\n");
-	if (Buffer.byteLength(result, "utf-8") > config.bytes) {
-		let low = 0;
-		let high = result.length;
-		while (low < high) {
-			const mid = Math.floor((low + high + 1) / 2);
-			if (Buffer.byteLength(result.slice(0, mid), "utf-8") <= config.bytes) {
-				low = mid;
-			} else {
-				high = mid - 1;
-			}
-		}
-		result = result.slice(0, low);
-	}
-
-	const keptLines = result.split("\n").length;
-	const marker = `[TRUNCATED: showing first ${keptLines} of ${lines.length} lines, ${formatBytes(Buffer.byteLength(result))} of ${formatBytes(bytes)}${artifactPath ? ` - full output at ${artifactPath}` : ""}]\n`;
-
-	return {
-		text: marker + result,
-		truncated: true,
-		originalBytes: bytes,
-		originalLines: lines.length,
-		artifactPath,
-	};
-}
+export * from "./types-results.ts";
+export * from "./types-async.ts";
+export * from "./types-config.ts";
+export * from "./types-runtime.ts";
+export * from "./types-depth.ts";
+export * from "./types-output.ts";