@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/dist/runs/background/async-execution.js

@@ -0,0 +1,676 @@
+/**
+ * Async execution logic for subagent tool
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyThinkingSuffix, SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../shared/pi-args.js";
+import { findDuplicateOutputPath, injectSingleOutputInstruction, materializeAgentDefaultOutputPath, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.js";
+import { buildChainInstructions, createChainDir, isDynamicParallelStep, isParallelStep, resolveChainTemplates, resolveParallelBehaviors, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile } from "../../shared/settings.js";
+import { resolvePiPackageRoot } from "../shared/pi-spawn.js";
+import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.js";
+import { resolveChildCwd } from "../../shared/utils.js";
+import { buildModelCandidates, resolveModelCandidate } from "../shared/model-fallback.js";
+import { resolveEffectiveThinking } from "../../shared/model-info.js";
+import { resolveExpectedWorktreeAgentCwd } from "../shared/worktree.js";
+import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.js";
+import { ChainOutputValidationError, validateChainOutputBindings } from "../shared/chain-outputs.js";
+import { createStructuredOutputRuntime } from "../shared/structured-output.js";
+import { resolveEffectiveAcceptance } from "../shared/acceptance.js";
+import { DEFAULT_MAX_OUTPUT, RESULTS_DIR, RUNNER_ERROR_LOG_FILE, SUBAGENT_ASYNC_STARTED_EVENT, resolveChildMaxSubagentDepth, } from "../../shared/types.js";
+import { nestedResultsPath, resolveInheritedNestedRouteFromEnv, resolveNestedParentAddressFromEnv, writeNestedEvent } from "../shared/nested-events.js";
+import { formatRunAction } from "../../shared/status-format.js";
+import { ensureTempRoot } from "../../shared/temp-root.js";
+import { getRunMetadataDir } from "../shared/supervisor-questions.js";
+const piPackageRoot = resolvePiPackageRoot();
+function usesAgentDefaultOutput(output) {
+    return output === undefined || output === true || output === "true";
+}
+function materializeAsyncDefaultOutput(params) {
+    return materializeAgentDefaultOutputPath({
+        output: params.output,
+        artifactsDir: params.artifactsDir ?? params.asyncDir,
+        runId: params.runId,
+        agent: params.agent,
+        index: params.index,
+    });
+}
+function resolveAsyncOutput(params) {
+    const effectiveOutput = usesAgentDefaultOutput(params.requestedOutput)
+        ? normalizeSingleOutputOverride(true, params.agentDefaultOutput)
+        : normalizeSingleOutputOverride(params.requestedOutput, params.agentDefaultOutput);
+    return usesAgentDefaultOutput(params.requestedOutput)
+        ? materializeAsyncDefaultOutput({ output: effectiveOutput, artifactsDir: params.artifactsDir, asyncDir: params.asyncDir, runId: params.runId, agent: params.agent, index: params.index })
+        : effectiveOutput;
+}
+function withSavedLaunch(step, agent, params, generatedOutputFilename) {
+    return { ...step, launch: {
+            agent, model: step.model, thinking: step.thinking, modelCandidates: step.modelCandidates ?? [],
+            artifacts: params.artifactsDir !== undefined, artifactsDir: params.artifactsDir, share: params.shareEnabled,
+            systemPrompt: step.systemPrompt ?? "", skills: step.skills ?? [], cwd: step.cwd ?? params.ctx.cwd,
+            context: agent.defaultContext ?? "fresh", output: step.outputPath ?? false, outputMode: step.outputMode ?? "inline",
+            ...(generatedOutputFilename ? { generatedOutputFilename } : step.outputPathFromAgentDefault && step.outputPath && typeof agent.output === "string" && !path.isAbsolute(agent.output) ? { generatedOutputFilename: path.basename(agent.output) } : {}),
+            outputSchema: step.structuredOutputSchema, effectiveAcceptance: step.effectiveAcceptance,
+            maxOutput: { ...DEFAULT_MAX_OUTPUT, ...params.maxOutput }, maxSubagentDepth: step.maxSubagentDepth,
+            maxExecutionTimeMs: step.maxExecutionTimeMs, maxTokens: step.maxTokens,
+            controlConfig: params.controlConfig, projectTrust: params.projectTrust, projectTrusted: params.ctx.projectTrusted,
+        } };
+}
+function resolveLaunchModel(agent, modelOverride, availableModels, preferredProvider, savedLaunch) {
+    const primary = modelOverride ?? savedLaunch?.model ?? agent.model;
+    const thinking = savedLaunch?.thinking ?? agent.thinking;
+    const model = applyThinkingSuffix(resolveModelCandidate(primary, availableModels, preferredProvider), thinking);
+    // Only caller selections pin the route; persisted candidates already encode the saved policy.
+    const fallbacks = modelOverride ? [] : savedLaunch?.modelCandidates ?? agent.fallbackModels;
+    return {
+        model,
+        thinking: resolveEffectiveThinking(model, thinking),
+        modelCandidates: buildModelCandidates(primary, fallbacks, availableModels, preferredProvider)
+            .map((candidate) => applyThinkingSuffix(candidate, thinking))
+            .filter((candidate) => typeof candidate === "string"),
+    };
+}
+export function formatAsyncStartedMessage(headline, childSafe = process.env[SUBAGENT_CHILD_ENV] === "1" && process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1") {
+    return [
+        headline,
+        "",
+        "The async run is detached. Do not run sleep timers or polling loops just to wait for it.",
+        "If you have independent work, continue that work. If you have nothing else to do until the async result arrives, end your turn now; Pi will deliver the completion when the run finishes.",
+        `Use ${formatRunAction("status", "...", {}, childSafe)} when you need the current status/result, or to inspect a blocked/stale run. Do not poll just to wait.`,
+    ].join("\n");
+}
+/**
+ * Spawn the async runner process
+ */
+function spawnRunner(cfg, cwd, asyncDir) {
+    try {
+        const cwdStats = fs.statSync(cwd);
+        if (!cwdStats.isDirectory()) {
+            return { error: `cwd is not a directory: ${cwd}` };
+        }
+    }
+    catch {
+        return { error: `cwd does not exist: ${cwd}` };
+    }
+    ensureTempRoot();
+    const cfgPath = path.join(asyncDir, "launch.json");
+    fs.writeFileSync(cfgPath, JSON.stringify({ ...cfg, runtimeVersion: 2 }), { mode: 0o600, flag: "wx" });
+    const runnerDir = path.dirname(fileURLToPath(import.meta.url));
+    const moduleExtension = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+    const launcher = path.join(runnerDir, `subagent-runner-launcher${moduleExtension}`);
+    const runner = path.join(runnerDir, `subagent-runner${moduleExtension}`);
+    const errorLogFd = fs.openSync(path.join(asyncDir, RUNNER_ERROR_LOG_FILE), "a");
+    try {
+        const proc = spawn(process.execPath, [launcher, runner, cfgPath], {
+            cwd,
+            detached: true,
+            stdio: ["ignore", "ignore", errorLogFd],
+        });
+        proc.on("error", (error) => {
+            console.error(`[pi-subagents] async spawn failed: ${error.message}`);
+        });
+        if (typeof proc.pid !== "number") {
+            return { error: `async runner did not produce a pid for cwd: ${cwd}` };
+        }
+        proc.unref();
+        return { pid: proc.pid };
+    }
+    finally {
+        fs.closeSync(errorLogFd);
+    }
+}
+function formatAsyncStartError(mode, message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+        details: { mode, results: [] },
+    };
+}
+const UNAVAILABLE_SUBAGENT_SKILL_ERROR = "Skills not found: pi-subagents";
+class UnavailableSubagentSkillError extends Error {
+}
+class AsyncStartValidationError extends Error {
+}
+/**
+ * Execute a chain asynchronously
+ */
+export function executeAsyncChain(id, params) {
+    const { chain, agents, ctx, cwd, maxOutput, artifactsDir, shareEnabled, sessionRoot, sessionFilesByFlatIndex, maxSubagentDepth, worktreeSetupHook, worktreeSetupHookTimeoutMs, controlConfig, controlIntercomTarget, childIntercomTarget, nestedRoute, } = params;
+    const resultMode = params.resultMode ?? "chain";
+    const chainSkills = params.chainSkills ?? [];
+    const availableModels = params.availableModels;
+    const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
+    const chainDir = resultMode === "chain" ? createChainDir(id, params.chainDir, runnerCwd) : runnerCwd;
+    const firstStep = chain[0];
+    const originalTask = params.task ?? (firstStep
+        ? (isParallelStep(firstStep)
+            ? firstStep.parallel[0]?.task
+            : isDynamicParallelStep(firstStep)
+                ? firstStep.parallel.task
+                : firstStep.task)
+        : undefined);
+    try {
+        validateChainOutputBindings(chain, { maxItems: params.dynamicFanoutMaxItems });
+    }
+    catch (error) {
+        if (error instanceof ChainOutputValidationError)
+            return formatAsyncStartError(resultMode, error.message);
+        throw error;
+    }
+    const workflowGraph = buildWorkflowGraphSnapshot({ runId: id, mode: resultMode, steps: chain });
+    const templates = resolveChainTemplates(chain);
+    for (const s of chain) {
+        const stepAgents = isParallelStep(s)
+            ? s.parallel.map((t) => t.agent)
+            : isDynamicParallelStep(s)
+                ? [s.parallel.agent]
+                : [s.agent];
+        for (const agentName of stepAgents) {
+            if (!agents.find((x) => x.name === agentName)) {
+                return {
+                    content: [{ type: "text", text: `Unknown agent: ${agentName}` }],
+                    isError: true,
+                    details: { mode: resultMode, results: [] },
+                };
+            }
+        }
+    }
+    const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
+    const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
+    const asyncDir = getRunMetadataDir(id);
+    try {
+        fs.mkdirSync(asyncDir, { recursive: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Failed to create async run directory '${asyncDir}': ${message}` }],
+            isError: true,
+            details: { mode: resultMode, results: [] },
+        };
+    }
+    let progressInstructionCreated = false;
+    let outputMaterializationIndex = 0;
+    const buildStepOverrides = (s) => {
+        const stepSkillInput = normalizeSkillInput(s.skill);
+        return {
+            ...(s.output !== undefined ? { output: s.output } : {}),
+            ...(s.outputMode !== undefined ? { outputMode: s.outputMode } : {}),
+            ...(s.reads !== undefined ? { reads: s.reads } : {}),
+            ...(s.progress !== undefined ? { progress: s.progress } : {}),
+            ...(stepSkillInput !== undefined ? { skills: stepSkillInput } : {}),
+        };
+    };
+    const buildSeqStep = (s, sessionFile, behaviorCwd, progressPrecreated = false, resolvedBehavior) => {
+        const a = agents.find((x) => x.name === s.agent);
+        const outputIndex = outputMaterializationIndex++;
+        const stepCwd = resolveChildCwd(runnerCwd, s.cwd);
+        const instructionCwd = behaviorCwd ?? (resultMode === "chain" ? chainDir : stepCwd);
+        const behavior = suppressProgressForReadOnlyTask(resolvedBehavior ?? resolveStepBehavior(a, buildStepOverrides(s), chainSkills), s.task, originalTask);
+        const launchAgent = behavior.skills === false ? { ...a, inheritSkills: false } : a;
+        const outputUsesAgentDefault = usesAgentDefaultOutput(s.output) || s.outputFromAgentDefault === true;
+        const output = outputUsesAgentDefault && resultMode !== "chain"
+            ? materializeAsyncDefaultOutput({ output: behavior.output, artifactsDir, asyncDir, runId: id, agent: s.agent, index: outputIndex })
+            : behavior.output;
+        const skillNames = behavior.skills === false ? [] : behavior.skills;
+        const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(skillNames, stepCwd, ctx.cwd, { projectTrusted: ctx.projectTrusted ?? true });
+        if (missingSkills.includes("pi-subagents"))
+            throw new UnavailableSubagentSkillError(UNAVAILABLE_SUBAGENT_SKILL_ERROR);
+        let systemPrompt = a.systemPrompt?.trim() ?? "";
+        if (resolvedSkills.length > 0) {
+            const injection = buildSkillInjection(resolvedSkills);
+            systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
+        }
+        const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false);
+        const isFirstProgressAgent = behavior.progress && !progressPrecreated && (resultMode !== "chain" || !progressInstructionCreated);
+        if (behavior.progress && resultMode === "chain")
+            progressInstructionCreated = true;
+        const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, instructionCwd, isFirstProgressAgent);
+        const outputPath = resolveSingleOutputPath(output, ctx.cwd, instructionCwd);
+        const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
+        if (validationError)
+            throw new AsyncStartValidationError(validationError);
+        const taskTemplate = s.task ?? "{previous}";
+        const task = injectSingleOutputInstruction(`${readInstructions.prefix}${taskTemplate}${progressInstructions.suffix}`, outputPath);
+        return withSavedLaunch({
+            agent: s.agent,
+            task,
+            phase: s.phase,
+            label: s.label,
+            outputName: s.as,
+            structured: Boolean(s.outputSchema),
+            cwd: stepCwd,
+            ...resolveLaunchModel(a, s.model, availableModels, ctx.currentModelProvider),
+            tools: a.tools,
+            allowSubagents: a.allowSubagents,
+            extensions: a.extensions,
+            mcpDirectTools: a.mcpDirectTools,
+            completionGuard: a.completionGuard,
+            systemPrompt,
+            systemPromptMode: a.systemPromptMode,
+            inheritProjectContext: a.inheritProjectContext,
+            inheritSkills: launchAgent.inheritSkills,
+            skills: resolvedSkills.map((r) => r.name),
+            outputPath,
+            output: behavior.output,
+            outputMode: behavior.outputMode,
+            ...(outputUsesAgentDefault && outputPath && typeof a.output === "string" && !path.isAbsolute(a.output) ? { outputPathFromAgentDefault: true } : {}),
+            sessionFile,
+            maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
+            maxExecutionTimeMs: a.maxExecutionTimeMs,
+            maxTokens: a.maxTokens,
+            effectiveAcceptance: resolveEffectiveAcceptance({ explicit: s.acceptance }),
+            ...(s.outputSchema ? { structuredOutputSchema: s.outputSchema } : {}),
+            ...(s.outputSchema ? { structuredOutput: createStructuredOutputRuntime(s.outputSchema, path.join(asyncDir, "structured-output")) } : {}),
+        }, launchAgent, params);
+    };
+    let flatStepIndex = 0;
+    const nextSessionFile = () => {
+        const sessionFile = sessionFilesByFlatIndex?.[flatStepIndex];
+        flatStepIndex++;
+        return sessionFile;
+    };
+    const takeDynamicSessionFiles = (count) => {
+        if (!sessionFilesByFlatIndex || count <= 0)
+            return undefined;
+        const sessionFiles = sessionFilesByFlatIndex.slice(flatStepIndex, flatStepIndex + count);
+        flatStepIndex += count;
+        return sessionFiles;
+    };
+    let steps;
+    try {
+        steps = chain.map((s, stepIndex) => {
+            if (isParallelStep(s)) {
+                const groupCwd = resolveChildCwd(runnerCwd, s.cwd);
+                const behaviors = resultMode === "chain"
+                    ? resolveParallelBehaviors(s.parallel, agents, stepIndex, chainSkills)
+                    : s.parallel.map((task) => resolveStepBehavior(agents.find((agent) => agent.name === task.agent), buildStepOverrides(task), chainSkills));
+                const parallelBehaviors = behaviors.map((behavior, index) => suppressProgressForReadOnlyTask(behavior, s.parallel[index]?.task, originalTask));
+                const progressPrecreated = resultMode === "chain" && parallelBehaviors.some((behavior) => behavior.progress);
+                if (progressPrecreated) {
+                    if (!s.worktree)
+                        writeInitialProgressFile(chainDir);
+                    progressInstructionCreated = true;
+                }
+                const parallelSteps = s.parallel.map((t, taskIndex) => {
+                    let behaviorCwd;
+                    if (s.worktree && resultMode !== "chain") {
+                        try {
+                            behaviorCwd = resolveExpectedWorktreeAgentCwd(groupCwd, `${id}-s${stepIndex}`, taskIndex);
+                        }
+                        catch {
+                            behaviorCwd = undefined;
+                        }
+                    }
+                    const taskProgressPrecreated = progressPrecreated || (resultMode !== "chain" && parallelBehaviors[taskIndex]?.progress === true && !s.worktree);
+                    if (taskProgressPrecreated && !progressPrecreated) {
+                        const progressCwd = resolveChildCwd(groupCwd, t.cwd);
+                        try {
+                            writeInitialProgressFile(progressCwd);
+                        }
+                        catch (error) {
+                            throw new AsyncStartValidationError(`Failed to initialize progress in '${progressCwd}': ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                    return buildSeqStep({ ...t, task: templates[stepIndex][taskIndex], cwd: resolveChildCwd(groupCwd, t.cwd) }, nextSessionFile(), behaviorCwd, taskProgressPrecreated, parallelBehaviors[taskIndex]);
+                });
+                const duplicateOutputError = findDuplicateOutputPath(parallelSteps);
+                if (duplicateOutputError)
+                    throw new AsyncStartValidationError(duplicateOutputError);
+                return {
+                    parallel: parallelSteps,
+                    cwd: groupCwd,
+                    concurrency: s.concurrency,
+                    failFast: s.failFast,
+                    worktree: s.worktree,
+                };
+            }
+            if (isDynamicParallelStep(s)) {
+                const agent = agents.find((candidate) => candidate.name === s.parallel.agent);
+                const behavior = suppressProgressForReadOnlyTask(resolveStepBehavior(agent, buildStepOverrides(s.parallel), chainSkills), s.parallel.task, originalTask);
+                const progressPrecreated = behavior.progress;
+                if (progressPrecreated) {
+                    writeInitialProgressFile(chainDir);
+                    progressInstructionCreated = true;
+                }
+                const maxItems = s.expand.maxItems ?? params.dynamicFanoutMaxItems ?? 0;
+                return {
+                    expand: s.expand,
+                    parallel: buildSeqStep({ ...s.parallel, task: templates[stepIndex] }, undefined, undefined, progressPrecreated, behavior),
+                    collect: s.collect,
+                    concurrency: s.concurrency,
+                    failFast: s.failFast,
+                    phase: s.phase,
+                    label: s.label,
+                    sessionFiles: takeDynamicSessionFiles(maxItems),
+                };
+            }
+            return buildSeqStep({ ...s, task: templates[stepIndex] }, nextSessionFile());
+        });
+    }
+    catch (error) {
+        if (error instanceof UnavailableSubagentSkillError || error instanceof AsyncStartValidationError)
+            return formatAsyncStartError(resultMode, error.message);
+        throw error;
+    }
+    let childTargetIndex = 0;
+    const childIntercomTargets = childIntercomTarget ? steps.flatMap((step) => {
+        if ("parallel" in step) {
+            if (!Array.isArray(step.parallel)) {
+                return [childIntercomTarget(step.parallel.agent, childTargetIndex++)];
+            }
+            return step.parallel.map((task) => childIntercomTarget(task.agent, childTargetIndex++));
+        }
+        return [childIntercomTarget(step.agent, childTargetIndex++)];
+    }) : undefined;
+    let spawnResult = {};
+    try {
+        spawnResult = spawnRunner({
+            id,
+            steps,
+            chainDir,
+            originalTask,
+            resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(RESULTS_DIR, `${id}.json`),
+            cwd: runnerCwd,
+            placeholder: "{previous}",
+            maxOutput,
+            timeoutMs: params.timeoutMs,
+            artifactsDir,
+            share: shareEnabled,
+            sessionDir: sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined,
+            asyncDir,
+            sessionId: ctx.currentSessionId,
+            rootSessionId: ctx.rootSessionId,
+            piPackageRoot,
+            worktreeSetupHook,
+            worktreeSetupHookTimeoutMs,
+            controlConfig,
+            controlIntercomTarget,
+            childIntercomTargets,
+            resultMode,
+            dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
+            workflowGraph,
+            nestedRoute: nestedRoute ?? inheritedNestedRoute,
+            nestedSelf: inheritedNestedRoute && nestedAddress ? {
+                parentRunId: nestedAddress.parentRunId,
+                parentStepIndex: nestedAddress.parentStepIndex,
+                depth: nestedAddress.depth,
+                path: nestedAddress.path,
+            } : undefined,
+            projectTrust: params.projectTrust,
+        }, runnerCwd, asyncDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': ${message}`);
+    }
+    if (spawnResult.error) {
+        return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': ${spawnResult.error}`);
+    }
+    if (spawnResult.pid) {
+        const firstStep = chain[0];
+        const firstAgents = isParallelStep(firstStep)
+            ? firstStep.parallel.map((t) => t.agent)
+            : isDynamicParallelStep(firstStep)
+                ? [firstStep.parallel.agent]
+                : [firstStep.agent];
+        const parallelGroups = [];
+        const flatAgents = [];
+        let flatStepStart = 0;
+        for (let stepIndex = 0; stepIndex < chain.length; stepIndex++) {
+            const step = chain[stepIndex];
+            if (isParallelStep(step)) {
+                parallelGroups.push({ start: flatStepStart, count: step.parallel.length, stepIndex });
+                flatAgents.push(...step.parallel.map((task) => task.agent));
+                flatStepStart += step.parallel.length;
+            }
+            else if (isDynamicParallelStep(step)) {
+                parallelGroups.push({ start: flatStepStart, count: 1, stepIndex });
+                flatAgents.push(step.parallel.agent);
+                flatStepStart++;
+            }
+            else {
+                flatAgents.push(step.agent);
+                flatStepStart++;
+            }
+        }
+        if (inheritedNestedRoute && nestedAddress) {
+            const now = Date.now();
+            try {
+                writeNestedEvent(inheritedNestedRoute, {
+                    type: "subagent.nested.started",
+                    ts: now,
+                    parentRunId: nestedAddress.parentRunId,
+                    parentStepIndex: nestedAddress.parentStepIndex,
+                    child: {
+                        id,
+                        parentRunId: nestedAddress.parentRunId,
+                        parentStepIndex: nestedAddress.parentStepIndex,
+                        depth: nestedAddress.depth,
+                        path: nestedAddress.path,
+                        asyncDir,
+                        pid: spawnResult.pid,
+                        ownerIntercomTarget: process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME,
+                        leafIntercomTarget: childIntercomTargets?.[0],
+                        intercomTarget: childIntercomTargets?.[0],
+                        ownerState: "live",
+                        mode: resultMode,
+                        state: "running",
+                        agent: firstAgents[0],
+                        agents: flatAgents,
+                        chainStepCount: chain.length,
+                        parallelGroups,
+                        startedAt: now,
+                        lastUpdate: now,
+                    },
+                });
+            }
+            catch (error) {
+                console.error("Failed to emit nested async start event:", error);
+            }
+        }
+        ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
+            id,
+            pid: spawnResult.pid,
+            sessionId: ctx.currentSessionId,
+            mode: resultMode,
+            agent: firstAgents[0],
+            agents: flatAgents,
+            task: isParallelStep(firstStep)
+                ? firstStep.parallel[0]?.task?.slice(0, 50)
+                : isDynamicParallelStep(firstStep)
+                    ? firstStep.parallel.task?.slice(0, 50)
+                    : firstStep.task?.slice(0, 50),
+            chain: chain.map((s) => isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : s.agent),
+            chainStepCount: chain.length,
+            parallelGroups,
+            workflowGraph,
+            cwd: runnerCwd,
+            asyncDir,
+            nestedRoute,
+        });
+    }
+    const chainDesc = chain
+        .map((s) => isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : s.agent)
+        .join(" -> ");
+    return {
+        content: [{ type: "text", text: formatAsyncStartedMessage(`Async ${resultMode}: ${chainDesc} [${id}]`) }],
+        details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir, asyncPid: spawnResult.pid, workflowGraph },
+    };
+}
+/**
+ * Execute a single agent asynchronously
+ */
+export function executeAsyncSingle(id, params) {
+    const { agent, agentConfig, ctx, cwd, maxOutput, artifactsDir, shareEnabled, sessionRoot, sessionFile, maxSubagentDepth, worktreeSetupHook, worktreeSetupHookTimeoutMs, controlConfig, controlIntercomTarget, childIntercomTarget, nestedRoute, } = params;
+    const task = params.task ?? "";
+    const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
+    const skillNames = params.skills === false ? [] : params.skills ?? agentConfig.skills ?? [];
+    const launchAgent = params.skills === false ? { ...agentConfig, inheritSkills: false } : agentConfig;
+    const availableModels = params.availableModels;
+    const { resolved: resolvedSkills, missing: missingSkills } = params.savedLaunch && params.skills === undefined
+        ? { resolved: [], missing: [] }
+        : resolveSkillsWithFallback(skillNames, runnerCwd, ctx.cwd, { projectTrusted: ctx.projectTrusted ?? true });
+    if (missingSkills.includes("pi-subagents"))
+        return formatAsyncStartError("single", UNAVAILABLE_SUBAGENT_SKILL_ERROR);
+    let systemPrompt = params.savedLaunch && params.skills === undefined ? params.savedLaunch.systemPrompt : agentConfig.systemPrompt?.trim() ?? "";
+    if (resolvedSkills.length > 0) {
+        const injection = buildSkillInjection(resolvedSkills);
+        systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
+    }
+    const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
+    const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
+    const asyncDir = getRunMetadataDir(id);
+    try {
+        fs.mkdirSync(asyncDir, { recursive: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Failed to create async run directory '${asyncDir}': ${message}` }],
+            isError: true,
+            details: { mode: "single", results: [] },
+        };
+    }
+    const outputUsesAgentDefault = usesAgentDefaultOutput(params.output) || params.outputFromAgentDefault === true;
+    const agentDefaultOutput = params.generatedOutputFilename ?? agentConfig.output;
+    const effectiveOutput = resolveAsyncOutput({
+        requestedOutput: params.output,
+        agentDefaultOutput,
+        artifactsDir,
+        asyncDir,
+        runId: id,
+        agent,
+        index: 0,
+    });
+    const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd);
+    const outputMode = params.outputMode ?? "inline";
+    const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
+    if (validationError)
+        return formatAsyncStartError("single", validationError);
+    let taskWithOutputInstruction = task;
+    if (params.progress) {
+        writeInitialProgressFile(runnerCwd);
+        taskWithOutputInstruction += buildChainInstructions({ output: false, outputMode: "inline", reads: false, progress: true, skills: false }, runnerCwd, true).suffix;
+    }
+    taskWithOutputInstruction = injectSingleOutputInstruction(taskWithOutputInstruction, outputPath);
+    let spawnResult = {};
+    try {
+        spawnResult = spawnRunner({
+            id,
+            steps: [
+                withSavedLaunch({
+                    agent,
+                    task: taskWithOutputInstruction,
+                    cwd: runnerCwd,
+                    ...resolveLaunchModel(agentConfig, params.modelOverride, availableModels, ctx.currentModelProvider, params.savedLaunch),
+                    tools: agentConfig.tools,
+                    allowSubagents: agentConfig.allowSubagents,
+                    extensions: agentConfig.extensions,
+                    mcpDirectTools: agentConfig.mcpDirectTools,
+                    completionGuard: agentConfig.completionGuard,
+                    systemPrompt,
+                    systemPromptMode: agentConfig.systemPromptMode,
+                    inheritProjectContext: agentConfig.inheritProjectContext,
+                    inheritSkills: launchAgent.inheritSkills,
+                    skills: params.savedLaunch && params.skills === undefined ? params.savedLaunch.skills : resolvedSkills.map((r) => r.name),
+                    outputPath,
+                    outputMode,
+                    ...(outputUsesAgentDefault && outputPath && typeof agentDefaultOutput === "string" && !path.isAbsolute(agentDefaultOutput) ? { outputPathFromAgentDefault: true } : {}),
+                    ...(params.outputSchema ? { structuredOutputSchema: params.outputSchema } : {}),
+                    ...(params.outputSchema ? { structuredOutput: createStructuredOutputRuntime(params.outputSchema, path.join(asyncDir, "structured-output")) } : {}),
+                    sessionFile,
+                    maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
+                    maxExecutionTimeMs: agentConfig.maxExecutionTimeMs,
+                    maxTokens: agentConfig.maxTokens,
+                    effectiveAcceptance: resolveEffectiveAcceptance({ explicit: params.acceptance }),
+                }, launchAgent, params, params.generatedOutputFilename),
+            ],
+            resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(RESULTS_DIR, `${id}.json`),
+            cwd: runnerCwd,
+            placeholder: "{previous}",
+            maxOutput,
+            timeoutMs: params.timeoutMs,
+            artifactsDir,
+            share: shareEnabled,
+            sessionDir: sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined,
+            asyncDir,
+            sessionId: ctx.currentSessionId,
+            rootSessionId: ctx.rootSessionId,
+            piPackageRoot,
+            worktreeSetupHook,
+            worktreeSetupHookTimeoutMs,
+            controlConfig,
+            controlIntercomTarget,
+            childIntercomTargets: childIntercomTarget ? [childIntercomTarget(agent, 0)] : undefined,
+            resultMode: "single",
+            nestedRoute: nestedRoute ?? inheritedNestedRoute,
+            nestedSelf: inheritedNestedRoute && nestedAddress ? {
+                parentRunId: nestedAddress.parentRunId,
+                parentStepIndex: nestedAddress.parentStepIndex,
+                depth: nestedAddress.depth,
+                path: nestedAddress.path,
+            } : undefined,
+            projectTrust: params.projectTrust,
+        }, runnerCwd, asyncDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return formatAsyncStartError("single", `Failed to start async run '${id}': ${message}`);
+    }
+    if (spawnResult.error) {
+        return formatAsyncStartError("single", `Failed to start async run '${id}': ${spawnResult.error}`);
+    }
+    if (spawnResult.pid) {
+        if (inheritedNestedRoute && nestedAddress) {
+            const now = Date.now();
+            try {
+                writeNestedEvent(inheritedNestedRoute, {
+                    type: "subagent.nested.started",
+                    ts: now,
+                    parentRunId: nestedAddress.parentRunId,
+                    parentStepIndex: nestedAddress.parentStepIndex,
+                    child: {
+                        id,
+                        parentRunId: nestedAddress.parentRunId,
+                        parentStepIndex: nestedAddress.parentStepIndex,
+                        depth: nestedAddress.depth,
+                        path: nestedAddress.path,
+                        asyncDir,
+                        pid: spawnResult.pid,
+                        ownerIntercomTarget: process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME,
+                        leafIntercomTarget: childIntercomTarget?.(agent, 0),
+                        intercomTarget: childIntercomTarget?.(agent, 0),
+                        ownerState: "live",
+                        mode: "single",
+                        state: "running",
+                        agent,
+                        agents: [agent],
+                        chainStepCount: 1,
+                        startedAt: now,
+                        lastUpdate: now,
+                    },
+                });
+            }
+            catch (error) {
+                console.error("Failed to emit nested async start event:", error);
+            }
+        }
+        ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
+            id,
+            pid: spawnResult.pid,
+            sessionId: ctx.currentSessionId,
+            mode: "single",
+            agent,
+            task: task?.slice(0, 50),
+            cwd: runnerCwd,
+            asyncDir,
+            nestedRoute,
+        });
+    }
+    return {
+        content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`) }],
+        details: { mode: "single", runId: id, results: [], asyncId: id, asyncDir, asyncPid: spawnResult.pid },
+    };
+}