pi-subagents 0.48.0 → 0.50.0

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

@@ -19,10 +19,12 @@ import { buildChainInstructions, isCheckpointStep, isDynamicParallelStep, isPara
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import type { ContextMode } from "../shared/context-mode.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { resolveNodeExecutable } from "../../shared/node-executable.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV, PROMPT_REDACTED, resolveChildCwd } from "../../shared/utils.ts";
 import { buildModelCandidates, resolveEffectiveSubagentModel, resolveModelCandidate, resolveSubagentModelOverride, type AvailableModelInfo, type ParentModel } from "../shared/model-fallback.ts";
+import { resolveToolTimeoutMs, toolTimeoutFromEnv } from "../shared/tool-timeout.ts";
 import type { ModelScopeConfig } from "../shared/model-scope.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { resolveExpectedWorktreeAgentCwd } from "../shared/worktree.ts";
@@ -37,6 +39,7 @@ import {
 	type AsyncStatus,
 	type ArtifactConfig,
 	type Details,
+	type IntercomBridgeConfig,
 	type JsonSchemaObject,
 	type MaxOutputConfig,
 	type NestedRouteInfo,
@@ -56,6 +59,7 @@ import {
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
 import { nestedResultsPath, nestedSummaryFromAsyncStatus, resolveInheritedNestedRouteFromEnv, resolveNestedParentAddressFromEnv, writeNestedEvent } from "../shared/nested-events.ts";
+import { resultFilePath } from "./result-files.ts";
 import { appendTurnBudgetSystemPrompt, initialTurnBudgetState } from "../shared/turn-budget.ts";
 import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
 import { usageBudgetState } from "../shared/usage-budget.ts";
@@ -172,6 +176,12 @@ interface AsyncChainParams {
 	toolBudget?: ResolvedToolBudget;
 	usageBudget?: UsageBudgetConfig;
 	configToolBudget?: ResolvedToolBudget;
+	/** Optional per-call hard toolTimeoutMs override (highest precedence). */
+	callToolTimeoutMs?: number;
+	/** Global config.toolTimeoutMs (third precedence, after agent frontmatter). */
+	configToolTimeoutMs?: number;
+	/** PI_SUBAGENT_TOOL_TIMEOUT_MS override (lowest precedence). */
+	toolTimeoutMsEnv?: string | undefined;
 	/** Global cap on simultaneously-running subagent tasks within the async run. */
 	globalConcurrencyLimit?: number;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -187,6 +197,8 @@ interface AsyncSingleParams {
 	/** Raw caller-facing goal used only by the started event. */
 	goal?: string;
 	agentConfig: AgentConfig;
+	/** Agent contract before per-run bridge injection, used only for recovery persistence. */
+	recoveryAgentConfig?: AgentConfig;
 	ctx: AsyncExecutionContext;
 	cwd?: string;
 	maxOutput?: MaxOutputConfig;
@@ -214,16 +226,23 @@ interface AsyncSingleParams {
 	worktreeSetupHookTimeoutMs?: number;
 	worktreeBaseDir?: string;
 	controlConfig?: ResolvedControlConfig;
+	intercomBridge?: IntercomBridgeConfig;
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	nestedRoute?: NestedRouteInfo;
 	acceptance?: AcceptanceInput;
 	timeoutMs?: number;
 	absoluteDeadlineAt?: number;
+	/** Optional per-call hard toolTimeoutMs override (highest precedence). */
+	toolTimeoutMs?: number;
 	turnBudget?: { maxTurns: number; graceTurns?: number };
 	toolBudget?: ResolvedToolBudget | ToolBudgetConfig;
 	usageBudget?: UsageBudgetConfig;
 	configToolBudget?: ResolvedToolBudget;
+	/** Global config.toolTimeoutMs (third precedence, after agent frontmatter). */
+	configToolTimeoutMs?: number;
+	/** PI_SUBAGENT_TOOL_TIMEOUT_MS override (lowest precedence). */
+	toolTimeoutMsEnv?: string | undefined;
 	allowZeroToolBudget?: boolean;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	runFanoutBudget?: RunFanoutBudgetDescriptor;
@@ -262,6 +281,12 @@ export interface AsyncRunnerStepBuildParams {
 	validateOutputBindings?: boolean;
 	toolBudget?: ResolvedToolBudget;
 	configToolBudget?: ResolvedToolBudget;
+	/** Optional per-call hard toolTimeoutMs override from the subagent invocation. */
+	callToolTimeoutMs?: number;
+	/** Global config.toolTimeoutMs (third precedence, after agent frontmatter). */
+	configToolTimeoutMs?: number;
+	/** PI_SUBAGENT_TOOL_TIMEOUT_MS override (lowest precedence). */
+	toolTimeoutMsEnv?: string | undefined;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 }
 
@@ -299,27 +324,6 @@ export function isAsyncAvailable(): boolean {
 	return jitiCliPath !== undefined;
 }
 
-function isNodeExecutableName(execPath: string): boolean {
-	const basename = path.basename(execPath).toLowerCase();
-	return basename === "node" || basename === "node.exe" || basename === "nodejs" || basename === "nodejs.exe";
-}
-
-function canUseCurrentNodeExecutable(execPath: string): boolean {
-	try {
-		fs.accessSync(execPath, process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function resolveAsyncRunnerNodeCommand(): string {
-	if (isNodeExecutableName(process.execPath) && canUseCurrentNodeExecutable(process.execPath)) {
-		return process.execPath;
-	}
-	return process.platform === "win32" ? "node.exe" : "node";
-}
-
 export function resolveAsyncRunnerLogPaths(cfg: object): { stdoutPath: string; stderrPath: string } | undefined {
 	const asyncDir = typeof (cfg as { asyncDir?: unknown }).asyncDir === "string"
 		? (cfg as { asyncDir: string }).asyncDir
@@ -486,7 +490,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, onProcessTerminal
 	const launchConfig = { ...cfg, runnerProcessInstanceId };
 	fs.writeFileSync(cfgPath, JSON.stringify(launchConfig));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
-	const nodeCommand = resolveAsyncRunnerNodeCommand();
+	const nodeCommand = resolveNodeExecutable();
 	const launchForStartup = launchConfig as typeof launchConfig & { asyncDir?: unknown; id?: unknown; sessionId?: unknown; revivalLease?: unknown };
 	const launchAsyncDir = typeof launchForStartup.asyncDir === "string" ? launchForStartup.asyncDir : undefined;
 	const launchRunId = typeof launchForStartup.id === "string" ? launchForStartup.id : suffix;
@@ -730,6 +734,13 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const toolBudgetInput = s.toolBudget ?? params.toolBudget ?? a.toolBudget ?? params.configToolBudget;
 		const resolvedToolBudget = validateToolBudgetConfig(toolBudgetInput, s.toolBudget ? "toolBudget" : a.toolBudget ? "agent.toolBudget" : "config.toolBudget");
 		if (resolvedToolBudget.error) throw new AsyncStartValidationError(resolvedToolBudget.error);
+		const resolvedToolTimeout = resolveToolTimeoutMs({
+			callValue: params.callToolTimeoutMs,
+			agentValue: a.defaultToolTimeoutMs,
+			configValue: params.configToolTimeoutMs,
+			envValue: params.toolTimeoutMsEnv ?? toolTimeoutFromEnv(),
+		});
+		if (resolvedToolTimeout.error) throw new AsyncStartValidationError(resolvedToolTimeout.error);
 		const stepCwd = resolveChildCwd(runnerCwd, s.cwd);
 		const instructionCwd = behaviorCwd ?? stepCwd;
 		const readExistenceCwd = behaviorCwd ? stepCwd : instructionCwd;
@@ -843,6 +854,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			sessionFile,
 			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
 			timeoutMs: a.defaultTimeoutMs ?? DEFAULT_ASYNC_TIMEOUT_MS,
+			toolTimeoutMs: resolvedToolTimeout.toolTimeoutMs,
 			waitToolEnabled: params.waitToolEnabled,
 			effectiveAcceptance: resolveEffectiveAcceptance({
 				explicit: s.acceptance,
@@ -1066,6 +1078,9 @@ export function executeAsyncChain(
 		asyncDir,
 		toolBudget: params.toolBudget,
 		configToolBudget: params.configToolBudget,
+		callToolTimeoutMs: params.callToolTimeoutMs,
+		configToolTimeoutMs: params.configToolTimeoutMs,
+		toolTimeoutMsEnv: params.toolTimeoutMsEnv ?? toolTimeoutFromEnv(),
 		capabilityCeiling,
 	});
 	if ("error" in built) {
@@ -1102,7 +1117,7 @@ export function executeAsyncChain(
 			{
 				id,
 				steps,
-				resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(DIRS.results, `${id}.json`),
+				resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : resultFilePath(DIRS.results, id),
 				cwd: runnerCwd,
 				placeholder: "{previous}",
 				maxOutput,
@@ -1251,6 +1266,7 @@ export function executeAsyncChain(
 			workflowGraph,
 			cwd: runnerCwd,
 			asyncDir,
+			...(sessionRoot ? { sessionRoot } : {}),
 			...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}),
 			...(initialTurnBudget ? { turnBudget: initialTurnBudget } : {}),
 			...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}),
@@ -1399,17 +1415,27 @@ export function executeAsyncSingle(
 		? deadlineAt - Date.now()
 		: params.timeoutMs;
 	if (timeoutMs !== undefined && timeoutMs <= 0) return formatAsyncStartError("single", "The source run's absolute deadline expired before recovery could launch.");
+	const resolvedToolTimeout = resolveToolTimeoutMs({
+		callValue: params.toolTimeoutMs,
+		agentValue: agentConfig.defaultToolTimeoutMs,
+		configValue: params.configToolTimeoutMs,
+		envValue: params.toolTimeoutMsEnv ?? toolTimeoutFromEnv(),
+	});
+	if (resolvedToolTimeout.error) return formatAsyncStartError("single", resolvedToolTimeout.error);
+	const toolTimeoutMs = resolvedToolTimeout.toolTimeoutMs;
 	const initialTurnBudget = params.turnBudget ? initialTurnBudgetState(params.turnBudget) : undefined;
 	const initialUsageBudget = usageBudgetState(params.usageBudget, undefined);
 	const resolvedSessionDir = params.sessionDir ?? (sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined);
 	const structuredOutput = params.structuredOutputSchema
 		? createStructuredOutputRuntime(params.structuredOutputSchema, path.join(asyncDir, "structured-output"))
 		: undefined;
-	const modelCandidates = buildModelCandidates(primaryModel, agentConfig.fallbackModels, availableModels, ctx.currentModelProvider, { scope: ctx.modelScope })
-		.flatMap((candidate) => {
-			const resolved = applyThinkingSuffix(candidate, effectiveThinking, params.thinkingOverride !== undefined);
-			return resolved ? [resolved] : [];
-		});
+	const modelCandidates = externalRunner
+		? []
+		: buildModelCandidates(primaryModel, agentConfig.fallbackModels, availableModels, ctx.currentModelProvider, { scope: ctx.modelScope })
+			.flatMap((candidate) => {
+				const resolved = applyThinkingSuffix(candidate, effectiveThinking, params.thinkingOverride !== undefined);
+				return resolved ? [resolved] : [];
+			});
 	const effectiveSystemPrompt = appendTurnBudgetSystemPrompt(systemPrompt, params.turnBudget);
 	const toolPlan = resolvePiLaunchToolPlan({
 		tools: agentConfig.tools,
@@ -1451,6 +1477,7 @@ export function executeAsyncSingle(
 		async: true,
 		agentContract: params.agentContract,
 	});
+	const recoveryAgentConfig = params.recoveryAgentConfig ?? agentConfig;
 	const recoveryDescriptor: SteeringRecoveryDescriptor = {
 		version: 1,
 		launchContractDigest,
@@ -1462,30 +1489,31 @@ export function executeAsyncSingle(
 		...(sessionFile ? { sessionFile } : {}),
 		cwd: runnerCwd,
 		...(model ? { model } : {}),
-		...(agentConfig.fallbackModels ? { fallbackModels: [...agentConfig.fallbackModels] } : {}),
+		...(recoveryAgentConfig.fallbackModels ? { fallbackModels: [...recoveryAgentConfig.fallbackModels] } : {}),
 		...(effectiveThinking ? { thinking: resolveEffectiveThinking(model, effectiveThinking) } : {}),
-		...(agentConfig.tools ? { tools: [...agentConfig.tools] } : {}),
-		...(agentConfig.extensions ? { extensions: [...agentConfig.extensions] } : {}),
-		...(agentConfig.subagentOnlyExtensions ? { subagentOnlyExtensions: [...agentConfig.subagentOnlyExtensions] } : {}),
-		...(agentConfig.mcpDirectTools ? { mcpDirectTools: [...agentConfig.mcpDirectTools] } : {}),
-		...(agentConfig.systemPrompt ? { systemPrompt: agentConfig.systemPrompt } : {}),
-		systemPromptMode: agentConfig.systemPromptMode,
-		inheritProjectContext: agentConfig.inheritProjectContext,
-		inheritSkills: agentConfig.inheritSkills,
+		...(recoveryAgentConfig.tools ? { tools: [...recoveryAgentConfig.tools] } : {}),
+		...(recoveryAgentConfig.extensions ? { extensions: [...recoveryAgentConfig.extensions] } : {}),
+		...(recoveryAgentConfig.subagentOnlyExtensions ? { subagentOnlyExtensions: [...recoveryAgentConfig.subagentOnlyExtensions] } : {}),
+		...(recoveryAgentConfig.mcpDirectTools ? { mcpDirectTools: [...recoveryAgentConfig.mcpDirectTools] } : {}),
+		...(recoveryAgentConfig.systemPrompt ? { systemPrompt: recoveryAgentConfig.systemPrompt } : {}),
+		systemPromptMode: recoveryAgentConfig.systemPromptMode,
+		inheritProjectContext: recoveryAgentConfig.inheritProjectContext,
+		inheritSkills: recoveryAgentConfig.inheritSkills,
 		...(resolvedSkills.length ? { skills: resolvedSkills.map((skill) => skill.name) } : {}),
-		...(agentConfig.skillPath ? { skillPath: [...agentConfig.skillPath] } : {}),
-		...(agentConfig.filePath ? { agentFilePath: agentConfig.filePath } : {}),
-		...(agentConfig.completionGuard !== undefined ? { completionGuard: agentConfig.completionGuard } : {}),
-		...(agentConfig.memory ? { memory: { ...agentConfig.memory } } : {}),
+		...(recoveryAgentConfig.skillPath ? { skillPath: [...recoveryAgentConfig.skillPath] } : {}),
+		...(recoveryAgentConfig.filePath ? { agentFilePath: recoveryAgentConfig.filePath } : {}),
+		...(recoveryAgentConfig.completionGuard !== undefined ? { completionGuard: recoveryAgentConfig.completionGuard } : {}),
+		...(recoveryAgentConfig.memory ? { memory: { ...recoveryAgentConfig.memory } } : {}),
 		...(outputPath ? { outputPath } : {}),
 		outputMode,
 		...(params.structuredOutputSchema ? { structuredOutputSchema: params.structuredOutputSchema } : {}),
 		...(params.acceptance !== undefined ? { acceptance: params.acceptance } : {}),
 		...(controlConfig ? { controlConfig } : {}),
+		...(params.intercomBridge !== undefined ? { intercomBridge: params.intercomBridge } : {}),
 		...(deadlineAt !== undefined ? { absoluteDeadlineAt: deadlineAt } : {}),
 		...(initialTurnBudget ? { initialTurnBudget: { maxTurns: initialTurnBudget.maxTurns, graceTurns: initialTurnBudget.graceTurns } } : {}),
 		...(resolvedToolBudget.budget ? { initialToolBudget: resolvedToolBudget.budget } : {}),
-		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
+		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, recoveryAgentConfig.maxSubagentDepth),
 		...(maxOutput ? { maxOutput } : {}),
 		share: shareEnabled,
 		...(resolvedSessionDir ? { sessionDir: resolvedSessionDir } : {}),
@@ -1546,7 +1574,7 @@ export function executeAsyncSingle(
 				],
 				resultPath: params.parentWorkflowRunId !== undefined && params.revivalLease !== undefined
 					? workflowAwaitedAsyncResultPath(asyncDir)
-					: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(DIRS.results, `${id}.json`),
+					: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : resultFilePath(DIRS.results, id),
 				cwd: runnerCwd,
 				placeholder: "{previous}",
 				maxOutput,
@@ -1565,6 +1593,7 @@ export function executeAsyncSingle(
 				controlConfig,
 				timeoutMs,
 				deadlineAt,
+				toolTimeoutMs,
 				turnBudget: params.turnBudget,
 				toolBudget: params.toolBudget,
 				usageBudget: params.usageBudget,
@@ -1654,6 +1683,7 @@ export function executeAsyncSingle(
 			goal: (params.goal ?? task).trim() ? PROMPT_REDACTED : undefined,
 			cwd: runnerCwd,
 			asyncDir,
+			...(sessionRoot ? { sessionRoot } : {}),
 			launchContractDigest,
 			launchResolvedExtensions,
 			...(params.parentWorkflowRunId ? { parentWorkflowRunId: params.parentWorkflowRunId } : {}),

package/src/runs/background/async-job-tracker.ts

@@ -125,6 +125,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		return {
 			asyncId: run.id,
 			asyncDir: run.asyncDir,
+			toolCallId: run.toolCallId,
 			status: run.state,
 			sessionId: run.sessionId,
 			activityState: run.activityState,
@@ -557,10 +558,13 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		const agents = firstGroupCount && firstGroupCount > 0
 			? rawAgents?.slice(0, firstGroupCount)
 			: rawAgents;
+		const sessionRoot = state.liveAsyncSessionRoots?.get(info.id);
+		state.liveAsyncSessionRoots?.delete(info.id);
 		state.asyncJobs.set(info.id, {
 			asyncId: info.id,
 			asyncDir,
 			...(typeof info.cwd === "string" ? { cwd: path.resolve(info.cwd) } : {}),
+			...(sessionRoot ? { sessionRoot } : {}),
 			status: "queued",
 			pid: typeof info.pid === "number" ? info.pid : undefined,
 			...(typeof info.sessionId === "string" ? { sessionId: info.sessionId } : {}),
@@ -637,6 +641,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		state.asyncJobs.clear();
 		state.fleetJobs?.clear();
 		state.foregroundControls?.clear();
+		state.liveAsyncSessionRoots?.clear();
 		state.lastForegroundControlId = null;
 		state.resultFileCoalescer.clear();
 		if (ctx?.hasUI) {

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

@@ -8,6 +8,7 @@ import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling, ty
 import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
 import { resolveTurnBudgetConfig } from "../shared/turn-budget.ts";
 import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
+import { resultFilePath } from "./result-files.ts";
 
 export interface AsyncResumeParams {
 	id?: string;
@@ -172,7 +173,7 @@ function prefixedRunIds(dir: string, prefix: string, suffix = ""): string[] {
 }
 
 function exactResultPath(resultsDir: string, runId: string): string | null {
-	const resultPath = path.join(resultsDir, `${runId}.json`);
+	const resultPath = resultFilePath(resultsDir, runId);
 	assertInsideRoot(resultsDir, resultPath, "Async result file");
 	return fs.existsSync(resultPath) ? resultPath : null;
 }
@@ -182,10 +183,7 @@ export function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string,
 	if (!requestedId) return [];
 	const asyncRoot = path.resolve(asyncDirRoot);
 	const resultRoot = path.resolve(resultsDir);
-	const matchingIds = [...new Set([
-		...prefixedRunIds(asyncRoot, requestedId),
-		...prefixedRunIds(resultRoot, requestedId, ".json"),
-	])].sort();
+	const matchingIds = prefixedRunIds(asyncRoot, requestedId).sort();
 	return matchingIds.map((id) => {
 		const asyncDir = path.join(asyncRoot, id);
 		assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
@@ -307,7 +305,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		"version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
 		"subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
 		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
-		"artifactsDir", "maxOutput", "controlConfig", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
+		"artifactsDir", "maxOutput", "controlConfig", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
 		"launchResolvedExtensions", "runFanoutBudget",
 	]);
 	for (const field of Object.keys(parsed)) {
@@ -374,6 +372,16 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		if (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);
 		if (!Number.isInteger(artifact.cleanupDays) || (artifact.cleanupDays as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.cleanupDays must be a non-negative integer.`);
 	}
+	if (parsed.intercomBridge !== undefined) {
+		if (!parsed.intercomBridge || typeof parsed.intercomBridge !== "object" || Array.isArray(parsed.intercomBridge)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge must be an object.`);
+		const bridge = parsed.intercomBridge as Record<string, unknown>;
+		for (const field of Object.keys(bridge)) {
+			if (field !== "mode" && field !== "instructionFile" && field !== "resultDelivery") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.${field} is not supported.`);
+		}
+		if (bridge.mode !== undefined && bridge.mode !== "off" && bridge.mode !== "fork-only" && bridge.mode !== "always") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.mode is invalid.`);
+		if (bridge.instructionFile !== undefined && typeof bridge.instructionFile !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.instructionFile must be a string.`);
+		if (bridge.resultDelivery !== undefined && typeof bridge.resultDelivery !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.resultDelivery must be a boolean.`);
+	}
 	if (parsed.controlConfig !== undefined) {
 		if (!parsed.controlConfig || typeof parsed.controlConfig !== "object" || Array.isArray(parsed.controlConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);
 		const control = parsed.controlConfig as Record<string, unknown>;

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

@@ -0,0 +1,277 @@
+import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
+import type { AsyncJobState, AsyncJobStep, NestedRunSummary, NestedStepSummary, SubagentRunMode, SubagentState } from "../../shared/types.ts";
+
+export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
+export const ASYNC_STATUS_SNAPSHOT_VERSION = 1;
+export const ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX = "PI_SUBAGENT_ASYNC_JSON:";
+
+const DEFAULT_MAX_RUNS = 20;
+const DEFAULT_MAX_CHILDREN_PER_NODE = 8;
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_MAX_STRING_LENGTH = 160;
+const DEFAULT_MAX_SERIALIZED_BYTES = 32 * 1024;
+
+export type AsyncStatusSnapshotState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
+export type AsyncStatusSnapshotKind = "subagent" | "workflow" | "step";
+
+export interface AsyncStatusSnapshotActivityV1 {
+	state?: string;
+	currentTool?: string;
+	lastActivityAt?: number;
+	currentToolStartedAt?: number;
+	turnCount?: number;
+	toolCount?: number;
+}
+
+export interface AsyncStatusSnapshotNodeV1 {
+	id: string;
+	kind: AsyncStatusSnapshotKind;
+	label: string;
+	state: AsyncStatusSnapshotState;
+	startedAt?: number;
+	updatedAt?: number;
+	endedAt?: number;
+	activity?: AsyncStatusSnapshotActivityV1;
+	children?: AsyncStatusSnapshotNodeV1[];
+}
+
+export interface AsyncStatusSnapshotCapsV1 {
+	maxRuns: number;
+	maxChildrenPerNode: number;
+	maxDepth: number;
+	maxStringLength: number;
+	maxSerializedBytes: number;
+}
+
+export interface AsyncStatusSnapshotOmittedV1 {
+	runs: number;
+	children: number;
+	byteLimitExceeded: boolean;
+}
+
+export interface AsyncStatusSnapshotV1 {
+	kind: typeof ASYNC_STATUS_SNAPSHOT_KIND;
+	version: typeof ASYNC_STATUS_SNAPSHOT_VERSION;
+	generatedAt: number;
+	caps: AsyncStatusSnapshotCapsV1;
+	omitted: AsyncStatusSnapshotOmittedV1;
+	runs: AsyncStatusSnapshotNodeV1[];
+}
+
+export interface AsyncStatusSnapshotOptions {
+	generatedAt?: number;
+	maxRuns?: number;
+	maxChildrenPerNode?: number;
+	maxDepth?: number;
+	maxStringLength?: number;
+	maxSerializedBytes?: number;
+}
+
+interface BuildContext {
+	caps: AsyncStatusSnapshotCapsV1;
+	omitted: AsyncStatusSnapshotOmittedV1;
+}
+
+function resolveCaps(options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotCapsV1 {
+	return {
+		maxRuns: Math.max(0, Math.floor(options.maxRuns ?? DEFAULT_MAX_RUNS)),
+		maxChildrenPerNode: Math.max(0, Math.floor(options.maxChildrenPerNode ?? DEFAULT_MAX_CHILDREN_PER_NODE)),
+		maxDepth: Math.max(0, Math.floor(options.maxDepth ?? DEFAULT_MAX_DEPTH)),
+		maxStringLength: Math.max(0, Math.floor(options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH)),
+		maxSerializedBytes: Math.max(256, Math.floor(options.maxSerializedBytes ?? DEFAULT_MAX_SERIALIZED_BYTES)),
+	};
+}
+
+function publicText(value: unknown, fallback: string, maxLength: number): string {
+	if (typeof value !== "string") return fallback;
+	const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
+	return truncateDisplayText(normalized || fallback, maxLength);
+}
+
+function publicOptionalText(value: unknown, maxLength: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
+	return normalized ? truncateDisplayText(normalized, maxLength) : undefined;
+}
+
+function publicTime(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function publicCount(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function normalizeState(value: string): AsyncStatusSnapshotState {
+	if (value === "completed") return "complete";
+	if (value === "pending") return "queued";
+	return value as AsyncStatusSnapshotState;
+}
+
+function terminalState(state: AsyncStatusSnapshotState): boolean {
+	return state === "complete" || state === "failed" || state === "paused" || state === "stopped" || state === "rejected";
+}
+
+function kindForMode(mode: SubagentRunMode | undefined): AsyncStatusSnapshotKind {
+	return mode === "workflow" ? "workflow" : "subagent";
+}
+
+function labelForAgents(agents: readonly string[] | undefined, fallback: string, maxLength: number): string {
+	if (!agents?.length) return publicText(fallback, fallback, maxLength);
+	const visible = agents.slice(0, 3).map((agent) => publicText(agent, "agent", maxLength)).join(", ");
+	const suffix = agents.length > 3 ? `, +${agents.length - 3} more` : "";
+	return truncateDisplayText(`${visible}${suffix}`, maxLength);
+}
+
+function activityFor(source: {
+	activityState?: unknown;
+	currentTool?: unknown;
+	lastActivityAt?: unknown;
+	currentToolStartedAt?: unknown;
+	turnCount?: unknown;
+	toolCount?: unknown;
+}, ctx: BuildContext): AsyncStatusSnapshotActivityV1 | undefined {
+	const activity: AsyncStatusSnapshotActivityV1 = {
+		...(typeof source.activityState === "string" ? { state: publicText(source.activityState, "unknown", ctx.caps.maxStringLength) } : {}),
+		...(publicOptionalText(source.currentTool, ctx.caps.maxStringLength) ? { currentTool: publicOptionalText(source.currentTool, ctx.caps.maxStringLength) } : {}),
+		...(publicTime(source.lastActivityAt) !== undefined ? { lastActivityAt: publicTime(source.lastActivityAt) } : {}),
+		...(publicTime(source.currentToolStartedAt) !== undefined ? { currentToolStartedAt: publicTime(source.currentToolStartedAt) } : {}),
+		...(publicCount(source.turnCount) !== undefined ? { turnCount: publicCount(source.turnCount) } : {}),
+		...(publicCount(source.toolCount) !== undefined ? { toolCount: publicCount(source.toolCount) } : {}),
+	};
+	return Object.keys(activity).length ? activity : undefined;
+}
+
+function appendBoundedChildren(children: AsyncStatusSnapshotNodeV1[], source: readonly AsyncStatusSnapshotNodeV1[], ctx: BuildContext): void {
+	const remaining = Math.max(0, ctx.caps.maxChildrenPerNode - children.length);
+	children.push(...source.slice(0, remaining));
+	ctx.omitted.children += Math.max(0, source.length - remaining);
+}
+
+function buildStepNode(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
+	const state = normalizeState(step.status);
+	const updatedAt = publicTime(step.endedAt) ?? publicTime(step.lastActivityAt) ?? publicTime(step.startedAt);
+	const node: AsyncStatusSnapshotNodeV1 = {
+		id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
+		kind: "step",
+		label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
+		state,
+		...(publicTime(step.startedAt) !== undefined ? { startedAt: publicTime(step.startedAt) } : {}),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+		...(terminalState(state) && publicTime(step.endedAt) !== undefined ? { endedAt: publicTime(step.endedAt) } : {}),
+		...(activityFor(step, ctx) ? { activity: activityFor(step, ctx) } : {}),
+	};
+	if (depth < ctx.caps.maxDepth && step.children?.length) {
+		const nested = step.children.map((child, childIndex) => buildNestedNode(child, childIndex, depth + 1, ctx));
+		const bounded: AsyncStatusSnapshotNodeV1[] = [];
+		appendBoundedChildren(bounded, nested, ctx);
+		if (bounded.length) node.children = bounded;
+	} else if (step.children?.length) {
+		ctx.omitted.children += step.children.length;
+	}
+	return node;
+}
+
+function buildNestedNode(child: NestedRunSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
+	const state = normalizeState(child.state);
+	const updatedAt = publicTime(child.lastUpdate) ?? publicTime(child.endedAt) ?? publicTime(child.lastActivityAt) ?? publicTime(child.startedAt);
+	const node: AsyncStatusSnapshotNodeV1 = {
+		id: publicText(child.id, `nested:${index}`, ctx.caps.maxStringLength),
+		kind: kindForMode(child.mode),
+		label: child.agent ? publicText(child.agent, "subagent", ctx.caps.maxStringLength) : labelForAgents(child.agents, child.mode ?? "subagent", ctx.caps.maxStringLength),
+		state,
+		...(publicTime(child.startedAt) !== undefined ? { startedAt: publicTime(child.startedAt) } : {}),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+		...(terminalState(state) && publicTime(child.endedAt) !== undefined ? { endedAt: publicTime(child.endedAt) } : {}),
+		...(activityFor(child, ctx) ? { activity: activityFor(child, ctx) } : {}),
+	};
+	if (depth < ctx.caps.maxDepth) {
+		const nestedSteps = child.steps?.map((step, stepIndex) => buildStepNode(step, stepIndex, depth + 1, ctx)) ?? [];
+		const nestedChildren = child.children?.map((nested, childIndex) => buildNestedNode(nested, childIndex, depth + 1, ctx)) ?? [];
+		const bounded: AsyncStatusSnapshotNodeV1[] = [];
+		appendBoundedChildren(bounded, [...nestedSteps, ...nestedChildren], ctx);
+		if (bounded.length) node.children = bounded;
+	} else {
+		ctx.omitted.children += (child.steps?.length ?? 0) + (child.children?.length ?? 0);
+	}
+	return node;
+}
+
+function buildRunNode(job: AsyncJobState, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
+	const state = normalizeState(job.status);
+	const updatedAt = publicTime(job.updatedAt) ?? publicTime(job.startedAt);
+	const node: AsyncStatusSnapshotNodeV1 = {
+		id: publicText(job.asyncId, "async", ctx.caps.maxStringLength),
+		kind: kindForMode(job.mode),
+		label: labelForAgents(job.agents, job.mode ?? "subagent", ctx.caps.maxStringLength),
+		state,
+		...(publicTime(job.startedAt) !== undefined ? { startedAt: publicTime(job.startedAt) } : {}),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+		...(terminalState(state) && updatedAt !== undefined ? { endedAt: updatedAt } : {}),
+		...(activityFor(job, ctx) ? { activity: activityFor(job, ctx) } : {}),
+	};
+	if (ctx.caps.maxDepth > 0) {
+		const stepChildren = job.steps?.map((step, index) => buildStepNode(step, step.index ?? index, 1, ctx)) ?? [];
+		const nestedChildren = job.nestedChildren?.map((child, index) => buildNestedNode(child, index, 1, ctx)) ?? [];
+		const bounded: AsyncStatusSnapshotNodeV1[] = [];
+		appendBoundedChildren(bounded, [...stepChildren, ...nestedChildren], ctx);
+		if (bounded.length) node.children = bounded;
+	} else {
+		ctx.omitted.children += (job.steps?.length ?? 0) + (job.nestedChildren?.length ?? 0);
+	}
+	return node;
+}
+
+function snapshotBytes(snapshot: AsyncStatusSnapshotV1): number {
+	return Buffer.byteLength(JSON.stringify(snapshot), "utf8");
+}
+
+function enforceByteLimit(snapshot: AsyncStatusSnapshotV1): void {
+	while (snapshot.runs.length > 0 && snapshotBytes(snapshot) > snapshot.caps.maxSerializedBytes) {
+		snapshot.runs.pop();
+		snapshot.omitted.runs += 1;
+		snapshot.omitted.byteLimitExceeded = true;
+	}
+	if (snapshotBytes(snapshot) > snapshot.caps.maxSerializedBytes) snapshot.omitted.byteLimitExceeded = true;
+}
+
+export function buildAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
+	const caps = resolveCaps(options);
+	const ctx: BuildContext = { caps, omitted: { runs: 0, children: 0, byteLimitExceeded: false } };
+	const sorted = [...jobs].sort((left, right) => {
+		const leftUpdated = left.updatedAt ?? left.startedAt ?? 0;
+		const rightUpdated = right.updatedAt ?? right.startedAt ?? 0;
+		return rightUpdated - leftUpdated || left.asyncId.localeCompare(right.asyncId);
+	});
+	ctx.omitted.runs += Math.max(0, sorted.length - caps.maxRuns);
+	const snapshot: AsyncStatusSnapshotV1 = {
+		kind: ASYNC_STATUS_SNAPSHOT_KIND,
+		version: ASYNC_STATUS_SNAPSHOT_VERSION,
+		generatedAt: options.generatedAt ?? Date.now(),
+		caps,
+		omitted: ctx.omitted,
+		runs: sorted.slice(0, caps.maxRuns).map((job) => buildRunNode(job, ctx)),
+	};
+	enforceByteLimit(snapshot);
+	return snapshot;
+}
+
+export function asyncStatusSnapshotJobsForState(state: SubagentState | undefined, sessionId: string | null | undefined): AsyncJobState[] {
+	if (!state || !sessionId || state.currentSessionId !== sessionId) return [];
+	const jobs = new Map<string, AsyncJobState>();
+	for (const job of state.asyncJobs.values()) {
+		if (job.sessionId === sessionId) jobs.set(job.asyncId, job);
+	}
+	for (const job of state.fleetJobs?.values() ?? []) {
+		if (job.sessionId === sessionId && !jobs.has(job.asyncId)) jobs.set(job.asyncId, job);
+	}
+	return [...jobs.values()];
+}
+
+export function buildAsyncStatusSnapshotForState(state: SubagentState | undefined, sessionId: string | null | undefined, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
+	return buildAsyncStatusSnapshot(asyncStatusSnapshotJobsForState(state, sessionId), options);
+}
+
+export function encodeAsyncStatusSnapshotWidget(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): string[] {
+	return [`${ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX}${JSON.stringify(buildAsyncStatusSnapshot(jobs, options))}`];
+}