@ashx-j/lunr 0.1.0

package/dist/builtin-extensions/pi-subagents/src/runs/background/async-resume.d.ts

@@ -0,0 +1,64 @@
+import { type AsyncStatus, type SteeringRecoveryDescriptor, type SubagentState } from "../../shared/types.ts";
+import type { AgentConfig } from "../../agents/agents.ts";
+export declare const ASYNC_RESUME_INTERRUPT_SIGNAL: NodeJS.Signals;
+export interface AsyncResumeParams {
+    id?: string;
+    runId?: string;
+    dir?: string;
+    index?: number;
+}
+export interface AsyncResumeDeps {
+    asyncDirRoot?: string;
+    resultsDir?: string;
+    kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+    now?: () => number;
+}
+export interface AsyncResumeOptions {
+    requireSessionFile?: boolean;
+}
+export type AsyncResumeTarget = {
+    kind: "live" | "revive";
+    runId: string;
+    asyncDir?: string;
+    state: AsyncStatus["state"];
+    agent: string;
+    index: number;
+    intercomTarget: string;
+    cwd?: string;
+    sessionFile?: string;
+    model?: string;
+    thinking?: string;
+    recoveryDescriptor?: SteeringRecoveryDescriptor;
+};
+type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+export declare function interruptLiveAsyncResumeTarget(input: {
+    target: AsyncResumeTarget & {
+        kind: "live";
+    };
+    state?: Pick<SubagentState, "asyncJobs">;
+    kill?: KillFn;
+    now?: () => number;
+    resultsDir?: string;
+}): {
+    ok: true;
+    asyncId: string;
+} | {
+    ok: false;
+    message: string;
+};
+export interface AsyncRunLocation {
+    asyncDir: string | null;
+    resultPath: string | null;
+    resolvedId?: string;
+}
+export declare function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string, resultsDir: string): Array<{
+    id: string;
+    location: AsyncRunLocation;
+}>;
+export declare function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot: string, resultsDir: string): AsyncRunLocation;
+export declare function readAsyncRecoveryDescriptor(asyncDir: string | undefined): SteeringRecoveryDescriptor | undefined;
+export declare function resolveAsyncResumeTarget(params: AsyncResumeParams, deps?: AsyncResumeDeps, options?: AsyncResumeOptions): AsyncResumeTarget;
+export declare function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descriptor: SteeringRecoveryDescriptor): AgentConfig;
+export declare function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string): string;
+export {};
+//# sourceMappingURL=async-resume.d.ts.map

package/dist/builtin-extensions/pi-subagents/src/runs/background/async-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-resume.d.ts","sourceRoot":"","sources":["../../../../../../src/builtin-extensions/pi-subagents/src/runs/background/async-resume.ts"],"names":[],"mappings":"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","sourcesContent":["// @ts-nocheck\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type SteeringRecoveryDescriptor, type SubagentState } from \"../../shared/types.ts\";\nimport { resolveSubagentIntercomTarget } from \"../../intercom/intercom-bridge.ts\";\nimport type { AgentConfig } from \"../../agents/agents.ts\";\nimport { validateAcceptanceInput } from \"../shared/acceptance.ts\";\nimport { validateToolBudgetConfig } from \"../shared/tool-budget.ts\";\nimport { resolveTurnBudgetConfig } from \"../shared/turn-budget.ts\";\nimport { deliverInterruptRequest } from \"./control-channel.ts\";\nimport { reconcileAsyncRun } from \"./stale-run-reconciler.ts\";\n\nexport const ASYNC_RESUME_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === \"win32\" ? \"SIGBREAK\" : \"SIGUSR2\";\n\nexport interface AsyncResumeParams {\n\tid?: string;\n\trunId?: string;\n\tdir?: string;\n\tindex?: number;\n}\n\nexport interface AsyncResumeDeps {\n\tasyncDirRoot?: string;\n\tresultsDir?: string;\n\tkill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;\n\tnow?: () => number;\n}\n\nexport interface AsyncResumeOptions {\n\trequireSessionFile?: boolean;\n}\n\nexport type AsyncResumeTarget = {\n\tkind: \"live\" | \"revive\";\n\trunId: string;\n\tasyncDir?: string;\n\tstate: AsyncStatus[\"state\"];\n\tagent: string;\n\tindex: number;\n\tintercomTarget: string;\n\tcwd?: string;\n\tsessionFile?: string;\n\tmodel?: string;\n\tthinking?: string;\n\trecoveryDescriptor?: SteeringRecoveryDescriptor;\n};\n\ntype KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;\n\nexport function interruptLiveAsyncResumeTarget(input: {\n\ttarget: AsyncResumeTarget & { kind: \"live\" };\n\tstate?: Pick<SubagentState, \"asyncJobs\">;\n\tkill?: KillFn;\n\tnow?: () => number;\n\tresultsDir?: string;\n}): { ok: true; asyncId: string } | { ok: false; message: string } {\n\tconst asyncId = input.target.runId;\n\tif (!input.target.asyncDir) {\n\t\treturn { ok: false, message: `Async run ${asyncId} is live but does not have an async directory to interrupt.` };\n\t}\n\tconst status = reconcileAsyncRun(input.target.asyncDir, { resultsDir: input.resultsDir, kill: input.kill, now: input.now }).status;\n\tif (!status || status.state !== \"running\" || typeof status.pid !== \"number\") {\n\t\treturn { ok: false, message: `Async run ${asyncId} is live but no interrupt-capable runner pid was found.` };\n\t}\n\ttry {\n\t\tdeliverInterruptRequest({\n\t\t\tasyncDir: input.target.asyncDir,\n\t\t\tpid: status.pid,\n\t\t\tkill: input.kill,\n\t\t\tsignal: ASYNC_RESUME_INTERRUPT_SIGNAL,\n\t\t\tnow: input.now,\n\t\t\tsource: \"async-resume\",\n\t\t});\n\t\tconst tracked = input.state?.asyncJobs.get(asyncId);\n\t\tif (tracked) {\n\t\t\ttracked.activityState = undefined;\n\t\t\ttracked.updatedAt = input.now?.() ?? Date.now();\n\t\t}\n\t\treturn { ok: true, asyncId };\n\t} catch (error) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\treturn { ok: false, message: `Failed to interrupt async run ${asyncId}: ${message}` };\n\t}\n}\n\ninterface AsyncResultFile {\n\tid?: string;\n\trunId?: string;\n\tagent?: string;\n\tmode?: string;\n\tstate?: string;\n\tsuccess?: boolean;\n\tcwd?: string;\n\tsessionFile?: string;\n\tmodel?: string;\n\tthinking?: string;\n\tresults?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string }>;\n}\n\nexport interface AsyncRunLocation {\n\tasyncDir: string | null;\n\tresultPath: string | null;\n\tresolvedId?: string;\n}\n\nfunction getErrorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction ensureObject(value: unknown, source: string): Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new Error(`Async result file '${source}' must contain a JSON object.`);\n\t}\n\treturn value as Record<string, unknown>;\n}\n\nfunction validateOptionalString(value: Record<string, unknown>, field: string, source: string, displayField = field): string | undefined {\n\tconst fieldValue = value[field];\n\tif (fieldValue === undefined) return undefined;\n\tif (typeof fieldValue !== \"string\") throw new Error(`Invalid async result file '${source}': ${displayField} must be a string.`);\n\treturn fieldValue;\n}\n\nfunction validateResultFile(value: unknown, resultPath: string): AsyncResultFile {\n\tconst data = ensureObject(value, resultPath);\n\tconst resultsValue = data.results;\n\tlet results: AsyncResultFile[\"results\"];\n\tif (resultsValue !== undefined) {\n\t\tif (!Array.isArray(resultsValue)) throw new Error(`Invalid async result file '${resultPath}': results must be an array.`);\n\t\tresults = resultsValue.map((entry, index) => {\n\t\t\tconst child = ensureObject(entry, `${resultPath} results[${index}]`);\n\t\t\tconst agent = validateOptionalString(child, \"agent\", resultPath, `results[${index}].agent`);\n\t\t\tconst sessionFile = validateOptionalString(child, \"sessionFile\", resultPath, `results[${index}].sessionFile`);\n\t\t\tconst intercomTarget = validateOptionalString(child, \"intercomTarget\", resultPath, `results[${index}].intercomTarget`);\n\t\t\tconst model = validateOptionalString(child, \"model\", resultPath, `results[${index}].model`);\n\t\t\tconst thinking = validateOptionalString(child, \"thinking\", resultPath, `results[${index}].thinking`);\n\t\t\tconst success = child.success;\n\t\t\tif (success !== undefined && typeof success !== \"boolean\") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);\n\t\t\treturn { agent, sessionFile, intercomTarget, model, thinking, ...(typeof success === \"boolean\" ? { success } : {}) };\n\t\t});\n\t}\n\tconst success = data.success;\n\tif (success !== undefined && typeof success !== \"boolean\") throw new Error(`Invalid async result file '${resultPath}': success must be a boolean.`);\n\treturn {\n\t\tid: validateOptionalString(data, \"id\", resultPath),\n\t\trunId: validateOptionalString(data, \"runId\", resultPath),\n\t\tagent: validateOptionalString(data, \"agent\", resultPath),\n\t\tmode: validateOptionalString(data, \"mode\", resultPath),\n\t\tstate: validateOptionalString(data, \"state\", resultPath),\n\t\tcwd: validateOptionalString(data, \"cwd\", resultPath),\n\t\tsessionFile: validateOptionalString(data, \"sessionFile\", resultPath),\n\t\tmodel: validateOptionalString(data, \"model\", resultPath),\n\t\tthinking: validateOptionalString(data, \"thinking\", resultPath),\n\t\t...(typeof success === \"boolean\" ? { success } : {}),\n\t\t...(results ? { results } : {}),\n\t};\n}\n\nfunction readResultFile(resultPath: string): AsyncResultFile {\n\tlet raw: string;\n\ttry {\n\t\traw = fs.readFileSync(resultPath, \"utf-8\");\n\t} catch (error) {\n\t\tthrow new Error(`Failed to read async result file '${resultPath}': ${getErrorMessage(error)}`, {\n\t\t\tcause: error instanceof Error ? error : undefined,\n\t\t});\n\t}\n\ttry {\n\t\treturn validateResultFile(JSON.parse(raw), resultPath);\n\t} catch (error) {\n\t\tif (error instanceof SyntaxError) {\n\t\t\tthrow new Error(`Failed to parse async result file '${resultPath}': ${getErrorMessage(error)}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t\tthrow error;\n\t}\n}\n\nfunction assertRunId(value: string | undefined, field: \"id\" | \"runId\"): string | undefined {\n\tif (value === undefined) return undefined;\n\tif (value.trim() === \"\") throw new Error(`${field} must not be empty.`);\n\tif (path.isAbsolute(value) || /[\\\\/]/.test(value) || value.includes(\"..\")) {\n\t\tthrow new Error(`${field} must be an async run id or prefix, not a path.`);\n\t}\n\treturn value;\n}\n\nfunction assertInsideRoot(root: string, target: string, label: string): void {\n\tconst rootPath = path.resolve(root);\n\tconst targetPath = path.resolve(target);\n\tconst relative = path.relative(rootPath, targetPath);\n\tif (relative === \"\" || (!relative.startsWith(\"..\") && !path.isAbsolute(relative))) return;\n\tthrow new Error(`${label} must be inside ${rootPath}.`);\n}\n\nfunction prefixedRunIds(dir: string, prefix: string, suffix = \"\"): string[] {\n\tif (!fs.existsSync(dir)) return [];\n\treturn fs.readdirSync(dir)\n\t\t.filter((entry) => entry.startsWith(prefix) && (!suffix || entry.endsWith(suffix)))\n\t\t.map((entry) => suffix ? entry.slice(0, -suffix.length) : entry)\n\t\t.sort();\n}\n\nfunction exactResultPath(resultsDir: string, runId: string): string | null {\n\tconst resultPath = path.join(resultsDir, `${runId}.json`);\n\tassertInsideRoot(resultsDir, resultPath, \"Async result file\");\n\treturn fs.existsSync(resultPath) ? resultPath : null;\n}\n\nexport function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string, resultsDir: string): Array<{ id: string; location: AsyncRunLocation }> {\n\tconst requestedId = assertRunId(prefix, \"id\");\n\tif (!requestedId) return [];\n\tconst asyncRoot = path.resolve(asyncDirRoot);\n\tconst resultRoot = path.resolve(resultsDir);\n\tconst matchingIds = [...new Set([\n\t\t...prefixedRunIds(asyncRoot, requestedId),\n\t\t...prefixedRunIds(resultRoot, requestedId, \".json\"),\n\t])].sort();\n\treturn matchingIds.map((id) => {\n\t\tconst asyncDir = path.join(asyncRoot, id);\n\t\tassertInsideRoot(asyncRoot, asyncDir, \"Async run directory\");\n\t\treturn {\n\t\t\tid,\n\t\t\tlocation: {\n\t\t\t\tasyncDir: fs.existsSync(asyncDir) ? asyncDir : null,\n\t\t\t\tresultPath: exactResultPath(resultRoot, id),\n\t\t\t\tresolvedId: id,\n\t\t\t},\n\t\t};\n\t});\n}\n\nexport function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot: string, resultsDir: string): AsyncRunLocation {\n\tconst asyncRoot = path.resolve(asyncDirRoot);\n\tconst resultRoot = path.resolve(resultsDir);\n\tconst requestedId = assertRunId(params.id, \"id\") ?? assertRunId(params.runId, \"runId\");\n\tif (params.dir) {\n\t\tconst asyncDir = path.resolve(params.dir);\n\t\tassertInsideRoot(asyncRoot, asyncDir, \"Async run directory\");\n\t\tconst resolvedId = requestedId ?? path.basename(asyncDir);\n\t\tif (requestedId && requestedId !== path.basename(asyncDir)) {\n\t\t\tthrow new Error(`Async run id '${requestedId}' does not match directory '${path.basename(asyncDir)}'.`);\n\t\t}\n\t\treturn { asyncDir, resultPath: exactResultPath(resultRoot, resolvedId), resolvedId };\n\t}\n\tif (!requestedId) return { asyncDir: null, resultPath: null };\n\n\tconst directAsyncDir = path.join(asyncRoot, requestedId);\n\tassertInsideRoot(asyncRoot, directAsyncDir, \"Async run directory\");\n\tconst directResultPath = exactResultPath(resultRoot, requestedId);\n\tif (fs.existsSync(directAsyncDir) || directResultPath) {\n\t\treturn {\n\t\t\tasyncDir: fs.existsSync(directAsyncDir) ? directAsyncDir : null,\n\t\t\tresultPath: directResultPath,\n\t\t\tresolvedId: requestedId,\n\t\t};\n\t}\n\n\tconst matching = findAsyncRunPrefixMatches(requestedId, asyncRoot, resultRoot);\n\tif (matching.length === 0) return { asyncDir: null, resultPath: null, resolvedId: requestedId };\n\tif (matching.length > 1) {\n\t\tthrow new Error(`Ambiguous async run id prefix '${requestedId}' matched: ${matching.map((match) => match.id).join(\", \")}. Provide a longer id.`);\n\t}\n\treturn matching[0]!.location;\n}\n\nfunction resultState(result: AsyncResultFile): AsyncStatus[\"state\"] {\n\tif (result.state === \"complete\" || result.state === \"failed\" || result.state === \"paused\" || result.state === \"stopped\" || result.state === \"running\" || result.state === \"queued\") {\n\t\treturn result.state;\n\t}\n\treturn result.success ? \"complete\" : \"failed\";\n}\n\nfunction validateStatusForResume(status: AsyncStatus | null, source: string): void {\n\tif (!status) return;\n\tif (typeof status.runId !== \"string\") throw new Error(`Invalid async status '${source}': runId must be a string.`);\n\tif (status.sessionId !== undefined && typeof status.sessionId !== \"string\") throw new Error(`Invalid async status '${source}': sessionId must be a string.`);\n\tif (status.cwd !== undefined && typeof status.cwd !== \"string\") throw new Error(`Invalid async status '${source}': cwd must be a string.`);\n\tif (status.sessionFile !== undefined && typeof status.sessionFile !== \"string\") throw new Error(`Invalid async status '${source}': sessionFile must be a string.`);\n\tif (status.steps !== undefined) {\n\t\tif (!Array.isArray(status.steps)) throw new Error(`Invalid async status '${source}': steps must be an array.`);\n\t\tstatus.steps.forEach((step, index) => {\n\t\t\tif (!step || typeof step !== \"object\" || Array.isArray(step)) throw new Error(`Invalid async status '${source}': steps[${index}] must be an object.`);\n\t\t\tconst stepRecord = step as Record<string, unknown>;\n\t\t\tif (typeof stepRecord.agent !== \"string\") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);\n\t\t\tif (stepRecord.sessionFile !== undefined && typeof stepRecord.sessionFile !== \"string\") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);\n\t\t\tif (stepRecord.model !== undefined && typeof stepRecord.model !== \"string\") throw new Error(`Invalid async status '${source}': steps[${index}].model must be a string.`);\n\t\t\tif (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== \"string\") throw new Error(`Invalid async status '${source}': steps[${index}].thinking must be a string.`);\n\t\t});\n\t}\n}\n\nexport function readAsyncRecoveryDescriptor(asyncDir: string | undefined): SteeringRecoveryDescriptor | undefined {\n\tif (!asyncDir) return undefined;\n\tconst descriptorPath = path.join(asyncDir, \"recovery-descriptor.json\");\n\tif (!fs.existsSync(descriptorPath)) return undefined;\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(fs.readFileSync(descriptorPath, \"utf-8\"));\n\t} catch (error) {\n\t\tthrow new Error(`Failed to parse async recovery descriptor '${descriptorPath}': ${getErrorMessage(error)}`, { cause: error instanceof Error ? error : undefined });\n\t}\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);\n\tconst parsed = value as Record<string, unknown>;\n\tconst allowedFields = new Set([\n\t\t\"version\", \"sourceRunId\", \"agent\", \"sessionFile\", \"cwd\", \"model\", \"fallbackModels\", \"thinking\", \"tools\", \"extensions\",\n\t\t\"subagentOnlyExtensions\", \"mcpDirectTools\", \"systemPrompt\", \"systemPromptMode\", \"inheritProjectContext\", \"inheritSkills\", \"skills\",\n\t\t\"skillPath\", \"agentFilePath\", \"completionGuard\", \"memory\", \"outputPath\", \"outputMode\", \"acceptance\", \"sessionDir\", \"artifactConfig\",\n\t\t\"artifactsDir\", \"maxOutput\", \"controlConfig\", \"absoluteDeadlineAt\", \"initialTurnBudget\", \"initialToolBudget\", \"maxSubagentDepth\", \"share\",\n\t]);\n\tfor (const field of Object.keys(parsed)) {\n\t\tif (!allowedFields.has(field)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': unknown field '${field}'.`);\n\t}\n\tconst requiredStrings = [\"sourceRunId\", \"agent\", \"cwd\", \"systemPromptMode\", \"outputMode\"] as const;\n\tfor (const field of requiredStrings) {\n\t\tif (typeof parsed[field] !== \"string\" || !(parsed[field] as string).trim()) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);\n\t}\n\tif (parsed.version !== 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': version must be 1.`);\n\tif (parsed.systemPromptMode !== \"append\" && parsed.systemPromptMode !== \"replace\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPromptMode is invalid.`);\n\tif (parsed.outputMode !== \"inline\" && parsed.outputMode !== \"file-only\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': outputMode is invalid.`);\n\tfor (const field of [\"inheritProjectContext\", \"inheritSkills\", \"share\"] as const) {\n\t\tif (typeof parsed[field] !== \"boolean\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a boolean.`);\n\t}\n\tif (!Number.isInteger(parsed.maxSubagentDepth) || (parsed.maxSubagentDepth as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxSubagentDepth must be a non-negative integer.`);\n\tfor (const field of [\"fallbackModels\", \"tools\", \"extensions\", \"subagentOnlyExtensions\", \"mcpDirectTools\", \"skills\", \"skillPath\"] as const) {\n\t\tconst item = parsed[field];\n\t\tif (item !== undefined && (!Array.isArray(item) || item.some((entry) => typeof entry !== \"string\" || !entry.trim()))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must contain non-empty strings.`);\n\t}\n\tif (parsed.systemPrompt !== undefined && typeof parsed.systemPrompt !== \"string\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPrompt must be a string.`);\n\tfor (const field of [\"sessionFile\", \"model\", \"thinking\", \"agentFilePath\", \"outputPath\", \"sessionDir\", \"artifactsDir\"] as const) {\n\t\tif (parsed[field] !== undefined && (typeof parsed[field] !== \"string\" || !(parsed[field] as string).trim())) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);\n\t}\n\tif (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== \"boolean\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);\n\tif (parsed.memory !== undefined) {\n\t\tif (!parsed.memory || typeof parsed.memory !== \"object\" || Array.isArray(parsed.memory)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory must be an object.`);\n\t\tconst memory = parsed.memory as Record<string, unknown>;\n\t\tif ((memory.scope !== \"project\" && memory.scope !== \"user\") || typeof memory.path !== \"string\" || !memory.path.trim()) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory is invalid.`);\n\t}\n\tif (parsed.absoluteDeadlineAt !== undefined && (!Number.isFinite(parsed.absoluteDeadlineAt) || (parsed.absoluteDeadlineAt as number) <= 0)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': absoluteDeadlineAt must be a positive timestamp.`);\n\tif (parsed.initialTurnBudget !== undefined) {\n\t\tconst result = resolveTurnBudgetConfig(parsed.initialTurnBudget, \"recoveryDescriptor.initialTurnBudget\");\n\t\tif (result.error) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);\n\t}\n\tif (parsed.initialToolBudget !== undefined) {\n\t\tconst result = validateToolBudgetConfig(parsed.initialToolBudget, \"recoveryDescriptor.initialToolBudget\");\n\t\tif (result.error) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);\n\t}\n\tif (parsed.maxOutput !== undefined) {\n\t\tif (!parsed.maxOutput || typeof parsed.maxOutput !== \"object\" || Array.isArray(parsed.maxOutput)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxOutput must be an object.`);\n\t\tfor (const field of [\"bytes\", \"lines\"] as const) {\n\t\t\tconst item = (parsed.maxOutput as Record<string, unknown>)[field];\n\t\t\tif (item !== undefined && (!Number.isInteger(item) || (item as number) < 1)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxOutput.${field} must be a positive integer.`);\n\t\t}\n\t}\n\tif (parsed.artifactConfig !== undefined) {\n\t\tif (!parsed.artifactConfig || typeof parsed.artifactConfig !== \"object\" || Array.isArray(parsed.artifactConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig must be an object.`);\n\t\tconst artifact = parsed.artifactConfig as Record<string, unknown>;\n\t\tfor (const field of [\"enabled\", \"includeInput\", \"includeOutput\", \"includeJsonl\", \"includeMetadata\"] as const) {\n\t\t\tif (typeof artifact[field] !== \"boolean\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.${field} must be a boolean.`);\n\t\t}\n\t\tif (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== \"boolean\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);\n\t\tif (!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.`);\n\t}\n\tif (parsed.controlConfig !== undefined) {\n\t\tif (!parsed.controlConfig || typeof parsed.controlConfig !== \"object\" || Array.isArray(parsed.controlConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);\n\t\tconst control = parsed.controlConfig as Record<string, unknown>;\n\t\tif (typeof control.enabled !== \"boolean\") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.enabled must be a boolean.`);\n\t\tfor (const field of [\"needsAttentionAfterMs\", \"activeNoticeAfterMs\", \"failedToolAttemptsBeforeAttention\"] as const) {\n\t\t\tif (!Number.isInteger(control[field]) || (control[field] as number) < 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.${field} must be a positive integer.`);\n\t\t}\n\t\tfor (const field of [\"activeNoticeAfterTurns\", \"activeNoticeAfterTokens\"] as const) {\n\t\t\tif (control[field] !== undefined && (!Number.isInteger(control[field]) || (control[field] as number) < 1)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.${field} must be a positive integer.`);\n\t\t}\n\t\tif (!Array.isArray(control.notifyOn) || control.notifyOn.some((item) => item !== \"active_long_running\" && item !== \"needs_attention\")) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyOn is invalid.`);\n\t\tif (!Array.isArray(control.notifyChannels) || control.notifyChannels.some((item) => item !== \"event\" && item !== \"async\" && item !== \"intercom\")) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyChannels is invalid.`);\n\t}\n\tif (parsed.acceptance !== undefined) {\n\t\tconst errors = validateAcceptanceInput(parsed.acceptance, \"recoveryDescriptor.acceptance\");\n\t\tif (errors.length) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${errors.join(\" \")}`);\n\t}\n\treturn parsed as unknown as SteeringRecoveryDescriptor;\n}\n\nfunction validateResumeSessionFile(runId: string, sessionFile: string): string {\n\tif (path.extname(sessionFile) !== \".jsonl\") throw new Error(`Async run '${runId}' session file must be a .jsonl file: ${sessionFile}`);\n\tconst resolved = path.resolve(sessionFile);\n\tif (!fs.existsSync(resolved)) throw new Error(`Async run '${runId}' session file does not exist: ${sessionFile}`);\n\treturn resolved;\n}\n\nexport function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncResumeDeps = {}, options: AsyncResumeOptions = {}): AsyncResumeTarget {\n\tconst asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;\n\tconst resultsDir = deps.resultsDir ?? RESULTS_DIR;\n\tconst requireSessionFile = options.requireSessionFile ?? true;\n\tconst location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);\n\tif (!location.asyncDir && !location.resultPath) {\n\t\tthrow new Error(\"Async run not found. Provide id or dir.\");\n\t}\n\n\tconst reconciliation = location.asyncDir\n\t\t? reconcileAsyncRun(location.asyncDir, { resultsDir, kill: deps.kill, now: deps.now })\n\t\t: undefined;\n\tconst status = reconciliation?.status ?? null;\n\tvalidateStatusForResume(status, location.asyncDir ? path.join(location.asyncDir, \"status.json\") : \"status.json\");\n\tconst recoveryDescriptor = readAsyncRecoveryDescriptor(location.asyncDir);\n\tconst result = location.resultPath ? readResultFile(location.resultPath) : undefined;\n\tconst runId = status?.runId ?? result?.runId ?? result?.id ?? location.resolvedId ?? (location.asyncDir ? path.basename(location.asyncDir) : \"unknown\");\n\tif (recoveryDescriptor && recoveryDescriptor.sourceRunId !== runId) throw new Error(`Async run '${runId}' has a recovery descriptor for a different source run.`);\n\tconst state = status?.state ?? (result ? resultState(result) : undefined);\n\tif (!state) throw new Error(`Status file not found for async run '${runId}'.`);\n\tif (state === \"stopped\") throw new Error(`Async run '${runId}' was stopped and cannot be resumed. Start a new run instead.`);\n\n\tconst statusSteps = status?.steps ?? [];\n\tconst resultSteps = result?.results ?? [];\n\tconst stepCount = statusSteps.length || resultSteps.length || (result?.agent ? 1 : 0);\n\tconst requestedIndex = params.index;\n\tif (requestedIndex !== undefined && !Number.isInteger(requestedIndex)) throw new Error(`Async run '${runId}' index must be an integer.`);\n\tconst terminalStepStatuses = new Set([\"complete\", \"completed\", \"failed\", \"paused\"]);\n\n\tif (state === \"running\") {\n\t\tif (requestedIndex !== undefined) {\n\t\t\tif (requestedIndex < 0 || requestedIndex >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${requestedIndex} is out of range.`);\n\t\t\tconst selectedStep = statusSteps[requestedIndex];\n\t\t\tif (selectedStep?.status === \"running\") {\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"live\",\n\t\t\t\t\trunId,\n\t\t\t\t\tasyncDir: location.asyncDir ?? undefined,\n\t\t\t\t\tstate,\n\t\t\t\t\tagent: selectedStep.agent,\n\t\t\t\t\tindex: requestedIndex,\n\t\t\t\t\tintercomTarget: resolveSubagentIntercomTarget(runId, selectedStep.agent, requestedIndex),\n\t\t\t\t\tcwd: status?.cwd ?? result?.cwd,\n\t\t\t\t\tsessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,\n\t\t\t\t\tmodel: selectedStep.model,\n\t\t\t\t\tthinking: selectedStep.thinking,\n\t\t\t\t\t...(recoveryDescriptor ? { recoveryDescriptor } : {}),\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (selectedStep?.status === \"pending\") throw new Error(`Async run '${runId}' child ${requestedIndex} is pending and has not started yet. Wait for it to run or complete before resuming.`);\n\t\t\tif (selectedStep && !terminalStepStatuses.has(selectedStep.status)) throw new Error(`Async run '${runId}' child ${requestedIndex} is ${selectedStep.status} and cannot be revived yet.`);\n\t\t} else {\n\t\t\tconst running = statusSteps\n\t\t\t\t.map((step, index) => ({ step, index }))\n\t\t\t\t.filter(({ step }) => step.status === \"running\");\n\t\t\tconst selected = running.length === 1 ? running[0] : undefined;\n\t\t\tif (!selected) {\n\t\t\t\tthrow new Error(`Async run '${runId}' has ${running.length} running children. Provide index to choose one.`);\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tkind: \"live\",\n\t\t\t\trunId,\n\t\t\t\tasyncDir: location.asyncDir ?? undefined,\n\t\t\t\tstate,\n\t\t\t\tagent: selected.step.agent,\n\t\t\t\tindex: selected.index,\n\t\t\t\tintercomTarget: resolveSubagentIntercomTarget(runId, selected.step.agent, selected.index),\n\t\t\t\tcwd: status?.cwd ?? result?.cwd,\n\t\t\t\tsessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,\n\t\t\t\tmodel: selected.step.model,\n\t\t\t\tthinking: selected.step.thinking,\n\t\t\t\t...(recoveryDescriptor ? { recoveryDescriptor } : {}),\n\t\t\t};\n\t\t}\n\t}\n\n\tif (stepCount > 1 && requestedIndex === undefined) {\n\t\tthrow new Error(`Async run '${runId}' has ${stepCount} children. Provide index to choose one.`);\n\t}\n\tconst index = requestedIndex ?? 0;\n\tif (!Number.isInteger(index)) throw new Error(`Async run '${runId}' index must be an integer.`);\n\tif (index < 0 || index >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${index} is out of range.`);\n\tconst agent = statusSteps[index]?.agent ?? resultSteps[index]?.agent ?? result?.agent;\n\tif (!agent) throw new Error(`Could not determine child agent for async run '${runId}'.`);\n\tif (recoveryDescriptor && recoveryDescriptor.agent !== agent) throw new Error(`Async run '${runId}' has a recovery descriptor for '${recoveryDescriptor.agent}', not '${agent}'.`);\n\tconst sessionFile = statusSteps[index]?.sessionFile\n\t\t?? resultSteps[index]?.sessionFile\n\t\t?? (stepCount === 1 ? status?.sessionFile ?? result?.sessionFile : undefined);\n\tif (!sessionFile && requireSessionFile) throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);\n\tconst resolvedSessionFile = sessionFile ? validateResumeSessionFile(runId, sessionFile) : undefined;\n\tconst stepModel = statusSteps[index]?.model ?? resultSteps[index]?.model ?? (stepCount === 1 ? result?.model : undefined);\n\tconst stepThinking = statusSteps[index]?.thinking ?? resultSteps[index]?.thinking ?? (stepCount === 1 ? result?.thinking : undefined);\n\n\treturn {\n\t\tkind: \"revive\",\n\t\trunId,\n\t\tasyncDir: location.asyncDir ?? undefined,\n\t\tstate,\n\t\tagent,\n\t\tindex,\n\t\tintercomTarget: resolveSubagentIntercomTarget(runId, agent, index),\n\t\tcwd: status?.cwd ?? result?.cwd,\n\t\t...(resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {}),\n\t\t...(stepModel ? { model: stepModel } : {}),\n\t\t...(stepThinking ? { thinking: stepThinking } : {}),\n\t\t...(recoveryDescriptor ? { recoveryDescriptor } : {}),\n\t};\n}\n\nexport function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descriptor: SteeringRecoveryDescriptor): AgentConfig {\n\treturn {\n\t\t...agentConfig,\n\t\tmodel: descriptor.model,\n\t\tfallbackModels: descriptor.fallbackModels ? [...descriptor.fallbackModels] : undefined,\n\t\tthinking: descriptor.thinking,\n\t\ttools: descriptor.tools ? [...descriptor.tools] : undefined,\n\t\textensions: descriptor.extensions ? [...descriptor.extensions] : undefined,\n\t\tsubagentOnlyExtensions: descriptor.subagentOnlyExtensions ? [...descriptor.subagentOnlyExtensions] : undefined,\n\t\tmcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,\n\t\tsystemPrompt: descriptor.systemPrompt,\n\t\tsystemPromptMode: descriptor.systemPromptMode,\n\t\tinheritProjectContext: descriptor.inheritProjectContext,\n\t\tinheritSkills: descriptor.inheritSkills,\n\t\tskills: descriptor.skills ? [...descriptor.skills] : undefined,\n\t\tskillPath: descriptor.skillPath ? [...descriptor.skillPath] : undefined,\n\t\tfilePath: descriptor.agentFilePath,\n\t\tcompletionGuard: descriptor.completionGuard,\n\t\tmemory: descriptor.memory ? { ...descriptor.memory } : undefined,\n\t\toutput: descriptor.outputPath,\n\t\ttoolBudget: descriptor.initialToolBudget,\n\t\tmaxSubagentDepth: descriptor.maxSubagentDepth,\n\t};\n}\n\nexport function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string): string {\n\treturn [\n\t\t\"You are reviving a previous subagent conversation.\",\n\t\t\"\",\n\t\t`Original run: ${target.runId}`,\n\t\t`Original agent: ${target.agent}`,\n\t\ttarget.sessionFile ? `Original session file: ${target.sessionFile}` : undefined,\n\t\t\"\",\n\t\t\"Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child process is still alive.\",\n\t\t\"\",\n\t\t\"Follow-up:\",\n\t\tmessage,\n\t].filter((line): line is string => line !== undefined).join(\"\\n\");\n}\n"]}