@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/runs/background/async-run-discovery.js

@@ -0,0 +1,213 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { RESULTS_DIR } from "../../shared/types.js";
+import { runSynchronously } from "../../shared/cooperative.js";
+import { asyncRunRoots, readAsyncRunRecord } from "./async-resume.js";
+import { getRunMetadataDir, readRunJson } from "../shared/supervisor-questions.js";
+import { findNestedRouteForRootId } from "../shared/nested-events.js";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.js";
+import { validateStatusForSummary } from "./async-status-validation.js";
+import { asyncStatusToSummary } from "./async-status-projection.js";
+import { errorCode, errorMessage, hasText, isRecord } from "./async-value.js";
+function directory(root, entry) {
+    const entryPath = path.join(root, entry);
+    try {
+        return fs.statSync(entryPath).isDirectory();
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return false;
+        }
+        throw new Error(`Failed to inspect async run path '${entryPath}': ${errorMessage(error)}`, {
+            cause: error,
+        });
+    }
+}
+class AsyncRunDiscovery {
+    owners = new Map();
+    discovered = new Set();
+    sessionIds;
+    ownerSessionId;
+    root;
+    options;
+    constructor(root, options) {
+        this.root = root;
+        this.options = options;
+        this.sessionIds = new Set([options.sessionId, options.ownerSessionId].filter(hasText));
+        // A legacy file-path-only query cannot classify native UUID owners as foreign.
+        this.ownerSessionId =
+            options.ownerSessionId ??
+                (hasText(options.sessionId) && !path.isAbsolute(options.sessionId)
+                    ? options.sessionId
+                    : undefined);
+    }
+    *scanRoot(root) {
+        const entries = [];
+        for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+            yield;
+            try {
+                if (entry.isDirectory() || (entry.isSymbolicLink() && directory(root, entry.name))) {
+                    entries.push(entry.name);
+                }
+            }
+            catch (error) {
+                if (this.options.skipInvalid !== true) {
+                    throw error;
+                }
+                this.invalidEntry(path.join(root, entry.name), error);
+            }
+        }
+        return entries;
+    }
+    *candidates(receipts) {
+        const entries = new Set(receipts);
+        for (const root of asyncRunRoots(this.root)) {
+            try {
+                const scanned = yield* this.scanRoot(root);
+                for (const entry of scanned) {
+                    entries.add(entry);
+                }
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT") {
+                    continue;
+                }
+                throw new Error(`Failed to list async runs in '${this.root}': ${errorMessage(error)}`, {
+                    cause: error,
+                });
+            }
+        }
+        return entries;
+    }
+    invalidEntry(entry, error) {
+        console.error(`Skipping invalid async run '${entry}':`, error);
+    }
+    owner(entry) {
+        let owner = this.owners.get(entry);
+        if (!hasText(owner) && hasText(this.ownerSessionId)) {
+            try {
+                const saved = readRunJson(path.join(getRunMetadataDir(entry), "question-owner.json"));
+                if (isRecord(saved) &&
+                    typeof saved.sessionId === "string" &&
+                    saved.sessionId.trim().length > 0) {
+                    owner = saved.sessionId;
+                    this.owners.set(entry, owner);
+                }
+            }
+            catch {
+                // Missing/unusable identity metadata retains the legacy status fallback.
+            }
+        }
+        return owner;
+    }
+    foreignOwner(owner, receipt) {
+        return hasText(owner) && owner !== this.ownerSessionId && !receipt;
+    }
+    authorizedRecord(record, owner, receipt) {
+        const matching = owner !== undefined && owner === this.ownerSessionId;
+        return (this.sessionIds.size === 0 ||
+            receipt ||
+            matching ||
+            this.sessionIds.has(record.status?.sessionId ?? ""));
+    }
+    readEntry(entry, receipt) {
+        if (this.discovered.has(entry)) {
+            return undefined;
+        }
+        const owner = this.owner(entry);
+        if (this.foreignOwner(owner, receipt)) {
+            return undefined;
+        }
+        const record = readAsyncRunRecord(entry, this.root, this.options.resultsDir ?? RESULTS_DIR);
+        const { asyncDir } = record.location;
+        if (!hasText(asyncDir)) {
+            return undefined;
+        }
+        if (!this.authorizedRecord(record, owner, receipt)) {
+            return undefined;
+        }
+        if (this.options.reconcile !== false) {
+            record.status = reconcileAsyncRun(asyncDir, this.options, record).status;
+        }
+        if (record.status) {
+            validateStatusForSummary(record.status, path.join(asyncDir, "status.json"));
+            this.discovered.add(entry);
+        }
+        return record;
+    }
+    *steps() {
+        const receipts = new Set(this.options.receiptRunIds?.());
+        const entries = yield* this.candidates([...receipts]);
+        const records = [];
+        for (const entry of entries) {
+            yield;
+            try {
+                const record = this.readEntry(entry, receipts.has(entry));
+                if (record) {
+                    records.push(record);
+                }
+            }
+            catch (error) {
+                if (this.options.skipInvalid !== true) {
+                    throw error;
+                }
+                this.invalidEntry(entry, error);
+            }
+        }
+        return records;
+    }
+}
+/** Retry new/unpublished runs without retaining payloads or negative ownership facts. */
+export function createAsyncRunDiscovery(asyncDirRoot, options = {}) {
+    const discovery = new AsyncRunDiscovery(asyncDirRoot, options);
+    return Object.assign(() => runSynchronously(discovery.steps()), {
+        steps: () => discovery.steps(),
+    });
+}
+const STATE_RANK = { running: 0, queued: 1, failed: 2, blocked: 2, paused: 2, complete: 3 };
+function summary(record, options) {
+    const { asyncDir } = record.location;
+    const { status } = record;
+    if (!hasText(asyncDir) || !status) {
+        return undefined;
+    }
+    const warnings = [];
+    let children;
+    try {
+        const route = findNestedRouteForRootId(status.runId.length > 0 ? status.runId : path.basename(asyncDir));
+        if (route) {
+            children = reconcileNestedAsyncDescendants(route, options);
+        }
+    }
+    catch (error) {
+        warnings.push(`Nested status unavailable: ${errorMessage(error)}`);
+    }
+    return asyncStatusToSummary(asyncDir, status, warnings, children);
+}
+function allowState(run, states) {
+    return states === undefined || states.includes(run.state);
+}
+export function listAsyncRuns(asyncDirRoot, options = {}) {
+    const runs = [];
+    for (const record of options.records ?? createAsyncRunDiscovery(asyncDirRoot, options)()) {
+        try {
+            const run = summary(record, options);
+            if (run && allowState(run, options.states)) {
+                runs.push(run);
+            }
+        }
+        catch (error) {
+            if (options.skipInvalid !== true) {
+                throw error;
+            }
+            console.error(`Skipping invalid async run '${record.location.resolvedId ?? "unknown"}':`, error);
+        }
+    }
+    runs.sort((a, b) => {
+        const rank = STATE_RANK[a.state] - STATE_RANK[b.state];
+        return rank !== 0
+            ? rank
+            : (b.lastUpdate ?? b.endedAt ?? b.startedAt) - (a.lastUpdate ?? a.endedAt ?? a.startedAt);
+    });
+    return options.limit === undefined ? runs : runs.slice(0, options.limit);
+}

package/dist/runs/background/async-run-location.js

@@ -0,0 +1,135 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatRunIdAmbiguity } from "../shared/run-id-ambiguity.js";
+import { QUESTIONS_DIR, readRunJson } from "../shared/supervisor-questions.js";
+import { readStatus } from "../../shared/utils.js";
+import { isDurableRun } from "./async-result-file.js";
+import { hasText } from "./async-value.js";
+function assertRunId(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value.trim().length === 0) {
+        throw new Error(`${field} must not be empty.`);
+    }
+    if (path.isAbsolute(value) || /[\\/]/.test(value) || value.includes("..")) {
+        throw new Error(`${field} must be an async run id or prefix, not a path.`);
+    }
+    return value;
+}
+function insideRoot(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return relative.length === 0 || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function prefixedRunIds(dir, prefix, suffix = "") {
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(dir)
+        .filter((entry) => entry.startsWith(prefix) && (suffix.length === 0 || entry.endsWith(suffix)))
+        .map((entry) => (suffix.length > 0 ? entry.slice(0, -suffix.length) : entry))
+        .sort();
+}
+export function asyncRunRoots(asyncDirRoot) {
+    return [...new Set([path.resolve(asyncDirRoot), path.resolve(QUESTIONS_DIR)])];
+}
+function exactResultPath(resultsDir, runId) {
+    const resultPath = path.join(resultsDir, `${runId}.json`);
+    if (!insideRoot(resultsDir, resultPath)) {
+        throw new Error(`Async result file must be inside ${path.resolve(resultsDir)}.`);
+    }
+    return fs.existsSync(resultPath) ? resultPath : null;
+}
+function preferredResult(durableResult, resultsDir, runId) {
+    return fs.existsSync(durableResult) ? durableResult : exactResultPath(resultsDir, runId);
+}
+function resolveAsyncRunRecord(runId, asyncDirRoot, resultsDir, readLegacyStatus) {
+    assertRunId(runId, "id");
+    const durableDir = path.join(QUESTIONS_DIR, runId);
+    const legacyDir = path.join(asyncDirRoot, runId);
+    const durableStatus = readStatus(durableDir);
+    const durableResult = path.join(durableDir, "result.json");
+    const durable = isDurableRun(durableStatus) || isDurableRun(readRunJson(path.join(durableDir, "launch.json")));
+    let asyncDir = null;
+    if (durable) {
+        asyncDir = durableDir;
+    }
+    else if (fs.existsSync(legacyDir)) {
+        asyncDir = legacyDir;
+    }
+    else if (durableStatus) {
+        asyncDir = durableDir;
+    }
+    let status = asyncDir === durableDir ? durableStatus : null;
+    if (asyncDir !== durableDir && asyncDir !== null && readLegacyStatus) {
+        status = readStatus(asyncDir);
+    }
+    return {
+        location: {
+            asyncDir,
+            resultPath: preferredResult(durableResult, resultsDir, runId),
+            resolvedId: runId,
+        },
+        status,
+        durable: durable || isDurableRun(status),
+    };
+}
+export function exactAsyncRunLocation(runId, asyncDirRoot, resultsDir) {
+    return resolveAsyncRunRecord(runId, asyncDirRoot, resultsDir, false).location;
+}
+/** Resolve canonical precedence and decode each candidate status once for this pass. */
+export function readAsyncRunRecord(runId, asyncDirRoot, resultsDir) {
+    return resolveAsyncRunRecord(runId, asyncDirRoot, resultsDir, true);
+}
+export function findAsyncRunPrefixMatches(prefix, asyncDirRoot, resultsDir) {
+    const requestedId = assertRunId(prefix, "id");
+    if (!hasText(requestedId)) {
+        return [];
+    }
+    const asyncRoot = path.resolve(asyncDirRoot);
+    const resultRoot = path.resolve(resultsDir);
+    const durableIds = prefixedRunIds(QUESTIONS_DIR, requestedId).filter((id) => ["status.json", "result.json", "launch.json"].some((file) => fs.existsSync(path.join(QUESTIONS_DIR, id, file))));
+    const ids = [
+        ...new Set([
+            ...prefixedRunIds(asyncRoot, requestedId),
+            ...durableIds,
+            ...prefixedRunIds(resultRoot, requestedId, ".json"),
+        ]),
+    ].sort();
+    return ids.map((id) => ({ id, location: exactAsyncRunLocation(id, asyncRoot, resultRoot) }));
+}
+function directoryLocation(params, roots) {
+    const asyncDir = path.resolve(params.dir ?? "");
+    if (!asyncRunRoots(roots.asyncRoot).some((root) => insideRoot(root, asyncDir))) {
+        throw new Error(`Async run directory must be inside ${asyncRunRoots(roots.asyncRoot).join(" or ")}.`);
+    }
+    const resolvedId = roots.requestedId ?? path.basename(asyncDir);
+    if (hasText(roots.requestedId) && roots.requestedId !== path.basename(asyncDir)) {
+        throw new Error(`Async run id '${roots.requestedId}' does not match directory '${path.basename(asyncDir)}'.`);
+    }
+    const location = exactAsyncRunLocation(resolvedId, roots.asyncRoot, roots.resultRoot);
+    const canonical = location.asyncDir !== null &&
+        isDurableRun(readRunJson(path.join(location.asyncDir, "launch.json")));
+    return { ...location, asyncDir: canonical ? location.asyncDir : asyncDir };
+}
+export function resolveAsyncRunLocation(params, asyncDirRoot, resultsDir) {
+    const asyncRoot = path.resolve(asyncDirRoot);
+    const resultRoot = path.resolve(resultsDir);
+    const requestedId = assertRunId(params.id, "id") ?? assertRunId(params.runId, "runId");
+    if (hasText(params.dir)) {
+        return directoryLocation(params, { asyncRoot, resultRoot, requestedId });
+    }
+    if (!hasText(requestedId)) {
+        return { asyncDir: null, resultPath: null };
+    }
+    const direct = exactAsyncRunLocation(requestedId, asyncRoot, resultRoot);
+    if (direct.asyncDir !== null || direct.resultPath !== null) {
+        return direct;
+    }
+    const matches = findAsyncRunPrefixMatches(requestedId, asyncRoot, resultRoot);
+    if (matches.length > 1) {
+        throw new Error(formatRunIdAmbiguity("async", requestedId, matches.map((match) => match.id)));
+    }
+    return matches[0]?.location ?? { asyncDir: null, resultPath: null, resolvedId: requestedId };
+}

package/dist/runs/background/async-run-record.js

@@ -0,0 +1 @@
+export {};

package/dist/runs/background/async-run-repair.js

@@ -0,0 +1,223 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readOutputPage } from "../../shared/journal-reader.js";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { RUNNER_ERROR_LOG_FILE, } from "../../shared/types.js";
+import { isDurableRun, readAsyncResultFileIfExists } from "./async-result-file.js";
+import { errorCode, hasText } from "./async-value.js";
+function childState(overall, child) {
+    if (child === undefined) {
+        return overall;
+    }
+    if (child.success === true) {
+        return "complete";
+    }
+    if (child.interrupted === true) {
+        return "paused";
+    }
+    if (child.acceptance?.status === "blocked" &&
+        (child.exitCode === 0 || child.exitCode === undefined)) {
+        return "blocked";
+    }
+    return child.success === false ? "failed" : overall;
+}
+function clearedActivity() {
+    return {
+        activityState: undefined,
+        currentTool: undefined,
+        currentToolArgs: undefined,
+        currentToolStartedAt: undefined,
+        currentPath: undefined,
+    };
+}
+function childRepairFields(step, child) {
+    const result = child ?? {};
+    return {
+        sessionFile: step.sessionFile ?? result.sessionFile,
+        model: step.model ?? result.model,
+        attemptedModels: step.attemptedModels ?? result.attemptedModels,
+        modelAttempts: step.modelAttempts ?? result.modelAttempts,
+        acceptance: step.acceptance ?? result.acceptance,
+        agentProcessExit: step.agentProcessExit ?? result.agentProcessExit,
+    };
+}
+function repairedOutcome(step, child, state, now) {
+    return {
+        status: state,
+        endedAt: step.endedAt ?? now,
+        durationMs: duration(step, now),
+        exitCode: step.exitCode ?? (state === "failed" ? 1 : 0),
+        error: state === "failed" ? (step.error ?? child?.error) : step.error,
+    };
+}
+function repairedStep(step, child, repair) {
+    if (step.status !== "running" && step.status !== "pending") {
+        return { ...step, ...clearedActivity() };
+    }
+    if (repair.durable && step.status === "pending" && child === undefined) {
+        return { ...step, ...clearedActivity() };
+    }
+    const state = childState(repair.state, child);
+    return {
+        ...step,
+        ...clearedActivity(),
+        ...repairedOutcome(step, child, state, repair.now),
+        ...childRepairFields(step, child),
+    };
+}
+function duration(step, now) {
+    return step.startedAt !== undefined && step.durationMs === undefined
+        ? Math.max(0, now - step.startedAt)
+        : step.durationMs;
+}
+export function terminalStatusFromResult(status, resultPath, now) {
+    const data = readAsyncResultFileIfExists(resultPath);
+    if (!data) {
+        return undefined;
+    }
+    const endedAt = data.timestamp ?? now;
+    const repair = { state: data.terminalState, now: endedAt, durable: isDurableRun(status) };
+    const steps = (status.steps ?? []).map((step, index) => repairedStep(step, data.results?.[index], repair));
+    return {
+        ...status,
+        ...clearedActivity(),
+        state: data.terminalState,
+        lastUpdate: endedAt,
+        endedAt: status.endedAt ?? endedAt,
+        steps,
+    };
+}
+function completedOutput(asyncDir, index) {
+    try {
+        return readOutputPage(path.join(asyncDir, `output-${index}.log`)).text.trim();
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return "";
+        }
+        throw error;
+    }
+}
+const STDERR_BYTES = 16 * 1024;
+// Render untrusted runner stderr without terminal control sequences; preserve tabs/newlines.
+// oxlint-disable-next-line no-control-regex
+const UNSAFE_CONTROL_CHARACTERS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+function runnerStderr(asyncDir) {
+    let fd;
+    try {
+        fd = fs.openSync(path.join(asyncDir, RUNNER_ERROR_LOG_FILE), "r");
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, STDERR_BYTES);
+        const buffer = Buffer.alloc(length);
+        const read = fs.readSync(fd, buffer, 0, length, Math.max(0, size - length));
+        const excerpt = buffer
+            .subarray(0, read)
+            .toString("utf-8")
+            .replace(UNSAFE_CONTROL_CHARACTERS, "�")
+            .trim();
+        if (excerpt.length === 0) {
+            return undefined;
+        }
+        return size > length
+            ? `[runner stderr truncated to last ${length} bytes]\n${excerpt}`
+            : excerpt;
+    }
+    catch {
+        // Missing stderr must not prevent recording the runner's unconfirmed completion.
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // Diagnostics cannot mask recovery if the descriptor was already closed.
+            }
+        }
+    }
+}
+function isNotQueued(value) {
+    return value !== "queued";
+}
+function failedStep(step, now, message) {
+    if (step.status !== "running" && isNotQueued(step.status) && step.status !== "pending") {
+        return { ...step, ...clearedActivity() };
+    }
+    return {
+        ...step,
+        ...clearedActivity(),
+        status: "failed",
+        endedAt: step.endedAt ?? now,
+        durationMs: duration(step, now),
+        exitCode: step.exitCode ?? 1,
+        error: step.error ?? message,
+    };
+}
+function resultChildren(steps, asyncDir, message) {
+    return steps.map((step, index) => {
+        const success = step.status === "complete" || step.status === "completed";
+        return {
+            agent: step.agent,
+            output: success ? completedOutput(asyncDir, index) : message,
+            error: success ? undefined : (step.error ?? message),
+            success,
+            model: step.model,
+            attemptedModels: step.attemptedModels,
+            modelAttempts: step.modelAttempts,
+            sessionFile: step.sessionFile,
+        };
+    });
+}
+function repairResultAgent(status, steps) {
+    return steps.at(status.currentStep ?? 0)?.agent ?? steps.at(0)?.agent ?? "subagent";
+}
+export function buildFailedRepair(status, asyncDir, now, reason) {
+    const runId = status.runId.length > 0 ? status.runId : path.basename(asyncDir);
+    const pid = typeof status.pid === "number" ? status.pid : "unknown";
+    const defaultMessage = `Async runner process ${pid} exited or disappeared before writing a result. Completion is unconfirmed.`;
+    const stderr = hasText(reason) ? undefined : runnerStderr(asyncDir);
+    const message = reason ?? (hasText(stderr) ? `${defaultMessage}\n\nRunner stderr:\n${stderr}` : defaultMessage);
+    const steps = (status.steps?.length ?? 0) > 0
+        ? (status.steps ?? [])
+        : [{ agent: "subagent", status: "running" }];
+    const repairedSteps = steps.map((step) => failedStep(step, now, message));
+    const repairedStatus = {
+        ...status,
+        ...clearedActivity(),
+        state: "failed",
+        lastUpdate: now,
+        endedAt: now,
+        steps: repairedSteps,
+    };
+    return {
+        status: repairedStatus,
+        message,
+        result: {
+            id: runId,
+            agent: repairResultAgent(status, repairedSteps),
+            mode: status.mode,
+            success: false,
+            state: "failed",
+            summary: message,
+            results: resultChildren(repairedSteps, asyncDir, message),
+            exitCode: 1,
+            timestamp: now,
+            durationMs: Math.max(0, now - status.startedAt),
+            asyncDir,
+            sessionId: status.sessionId,
+            cwd: status.cwd,
+            sessionFile: status.sessionFile,
+        },
+    };
+}
+export function writeFailedRepair(asyncDir, status, resultPath, repairOptions) {
+    const repair = buildFailedRepair(status, asyncDir, repairOptions.now, repairOptions.reason);
+    // Result publication precedes status and the journaled repair event.
+    writeAtomicJson(resultPath, repair.result);
+    writeAtomicJson(path.join(asyncDir, "status.json"), repair.status);
+    const eventsPath = path.join(asyncDir, "events.jsonl");
+    fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+    fs.appendFileSync(eventsPath, `${JSON.stringify({ type: "subagent.run.repaired_stale", ts: repairOptions.now, runId: repair.status.runId, pid: status.pid, resultPath, message: repair.message })}\n`, "utf-8");
+    return { status: repair.status, repaired: true, resultPath, message: repair.message };
+}

package/dist/runs/background/async-run-summary.js

@@ -0,0 +1 @@
+export {};

package/dist/runs/background/async-single-plan.js

@@ -0,0 +1,105 @@
+import * as path from "node:path";
+import { resolveChildMaxSubagentDepth, } from "../../shared/types.js";
+import { buildChainInstructions, writeInitialProgressFile } from "../../shared/settings.js";
+import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.js";
+import { injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode, } from "../shared/single-output.js";
+import { resolveEffectiveAcceptance } from "../shared/acceptance.js";
+import { createStructuredOutputRuntime } from "../shared/structured-output.js";
+import { agentRuntimeFields, usesAgentDefaultOutput, resolveAsyncOutput, withSavedLaunch, resolveLaunchModel, UNAVAILABLE_SUBAGENT_SKILL_ERROR, UnavailableSubagentSkillError, AsyncStartValidationError, } from "./async-plan.js";
+function singleSkills(params, cwd) {
+    const agent = params.agentConfig;
+    const launchAgent = params.skills === false ? { ...agent, inheritSkills: false } : agent;
+    if (params.savedLaunch && params.skills === undefined) {
+        return {
+            launchAgent,
+            prompt: params.savedLaunch.systemPrompt,
+            skills: params.savedLaunch.skills,
+        };
+    }
+    const names = skillNames(params.skills, agent.skills);
+    const { resolved, missing } = resolveSkillsWithFallback(names, cwd, params.ctx.cwd, {
+        projectTrusted: params.ctx.projectTrusted ?? true,
+    });
+    if (missing.includes("pi-subagents")) {
+        throw new UnavailableSubagentSkillError(UNAVAILABLE_SUBAGENT_SKILL_ERROR);
+    }
+    let prompt = agent.systemPrompt.trim();
+    if (resolved.length > 0) {
+        const injection = buildSkillInjection(resolved);
+        prompt = prompt.length > 0 ? `${prompt}\n\n${injection}` : injection;
+    }
+    return { launchAgent, prompt, skills: resolved.map((skill) => skill.name) };
+}
+function skillNames(explicit, defaults) {
+    return explicit === false ? [] : (explicit ?? defaults ?? []);
+}
+function defaultOutputMarker(output, outputPath, usesDefault) {
+    if (!usesDefault || outputPath === undefined || outputPath.length === 0) {
+        return;
+    }
+    if (typeof output !== "string" || path.isAbsolute(output)) {
+        return;
+    }
+    return true;
+}
+function singleOutput(id, params, cwd, asyncDir) {
+    const defaultOutput = params.generatedOutputFilename ?? params.agentConfig.output;
+    const output = resolveAsyncOutput({
+        requestedOutput: params.output,
+        agentDefaultOutput: defaultOutput,
+        artifactsDir: params.artifactsDir,
+        asyncDir,
+        runId: id,
+        agent: params.agent,
+        index: 0,
+    });
+    const outputPath = resolveSingleOutputPath(output, params.ctx.cwd, cwd);
+    const error = validateFileOnlyOutputMode(params.outputMode ?? "inline", outputPath, `Async single run (${params.agent})`);
+    if (error !== undefined && error.length > 0) {
+        throw new AsyncStartValidationError(error);
+    }
+    let task = params.task ?? "";
+    if (params.progress === true) {
+        writeInitialProgressFile(cwd);
+        task += buildChainInstructions({ output: false, outputMode: "inline", reads: false, progress: true, skills: false }, cwd, true).suffix;
+    }
+    const usesDefault = usesAgentDefaultOutput(params.output) || params.outputFromAgentDefault === true;
+    const outputFromDefault = defaultOutputMarker(defaultOutput, outputPath, usesDefault);
+    return {
+        task: injectSingleOutputInstruction(task, outputPath),
+        outputPath,
+        ...(outputFromDefault === true ? { outputFromDefault: true } : {}),
+    };
+}
+/** Resolves the saved launch, output contract and skill scope for one detached child. */
+export function planAsyncSingle(id, params, workspace) {
+    const agent = params.agentConfig;
+    const skills = singleSkills(params, workspace.cwd);
+    const output = singleOutput(id, params, workspace.cwd, workspace.asyncDir);
+    return withSavedLaunch({
+        ...agentRuntimeFields(agent),
+        agent: params.agent,
+        task: output.task,
+        cwd: workspace.cwd,
+        ...resolveLaunchModel(agent, params.modelOverride, {
+            availableModels: params.availableModels,
+            preferredProvider: params.ctx.currentModelProvider,
+            savedLaunch: params.savedLaunch,
+        }),
+        systemPrompt: skills.prompt,
+        inheritSkills: skills.launchAgent.inheritSkills,
+        skills: [...skills.skills],
+        outputPath: output.outputPath,
+        outputMode: params.outputMode ?? "inline",
+        ...(output.outputFromDefault === true ? { outputPathFromAgentDefault: true } : {}),
+        ...(params.outputSchema
+            ? {
+                structuredOutputSchema: params.outputSchema,
+                structuredOutput: createStructuredOutputRuntime(params.outputSchema, path.join(workspace.asyncDir, "structured-output")),
+            }
+            : {}),
+        sessionFile: params.sessionFile,
+        maxSubagentDepth: resolveChildMaxSubagentDepth(params.maxSubagentDepth, agent.maxSubagentDepth),
+        effectiveAcceptance: resolveEffectiveAcceptance({ explicit: params.acceptance }),
+    }, skills.launchAgent, params, params.generatedOutputFilename);
+}