@ashx-j/lunr 0.1.0

package/dist/builtin-extensions/pi-subagents/src/runs/background/subagent-wait.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `subagent_wait` tool: block the current turn until outstanding async runs
+ * or a named remembered detached foreground run finishes.
+ *
+ * Background subagent runs are detached. In an interactive session the parent
+ * can end its turn and Pi will wake it with a completion notification. That
+ * does not work when the parent is a skill that must run to completion, and it
+ * cannot work at all non-interactively (`pi -p ...`), where the run is a single
+ * turn: once the turn ends there is nothing left to receive the notification.
+ *
+ * `subagent_wait` closes that gap. It keeps the turn alive until a tracked async
+ * run for this session reaches a terminal state (complete / failed / paused),
+ * the caller-supplied timeout elapses, or the turn is aborted. Because it awaits
+ * inside the turn, the completion the model was told to wait for is actually
+ * observed before the tool returns.
+ *
+ * By default `subagent_wait` returns as soon as ONE run finishes, so a fleet
+ * manager can use it in a rolling-replacement loop: launch N workers, wait for
+ * the next one to finish, spawn its replacement, then call `subagent_wait`
+ * again — keeping N in flight instead of draining to zero between batches.
+ * Pass `all: true` to block until every tracked async run is terminal, or `id`
+ * to block on one specific async or remembered detached foreground run.
+ *
+ * `subagent_wait` also returns when a run needs attention — not just on
+ * completion. A child that goes idle or blocks for a decision surfaces
+ * `needs_attention` (the same signal Pi shows as a control notice and,
+ * interactively, wakes the parent with). Since `subagent_wait` is used exactly
+ * where there is no next turn to receive that notice, it must break on it too,
+ * or a stuck child would stall the loop until the timeout. Attention runs are
+ * reported so the caller can inspect / nudge / resume / interrupt them.
+ *
+ * Wake mechanism: when given Pi's event bus (`deps.events`), `subagent_wait`
+ * subscribes to the subagent completion/control channels and wakes the instant
+ * any fires, rather than waiting out a fixed poll interval. A poll still runs
+ * on the interval as a reconciliation fallback (crashed runners, missed
+ * events), and the poll is the source of truth for what actually changed — the
+ * event only ends the sleep early. With no bus, `subagent_wait` degrades to pure
+ * polling.
+ */
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { type BackgroundWorkSnapshot } from "../../api/background-work.ts";
+import { type Details, type SubagentState } from "../../shared/types.ts";
+export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
+export interface SubagentWaitParams {
+    /** Optional run id/prefix to wait for. When omitted, waits across every active run in this session. */
+    id?: string;
+    /**
+     * When true, block until EVERY active run in this session (or matching `id`)
+     * is terminal. Default false: return as soon as the first run finishes, so a
+     * fleet manager can spawn a replacement and wait again. Ignored when `id`
+     * targets a single run.
+     */
+    all?: boolean;
+    /** Give up after this many milliseconds. Defaults to 30 minutes. */
+    timeoutMs?: number;
+}
+/** Minimal event-bus surface wait subscribes to (matches pi.events). */
+export interface WaitEventBus {
+    on(channel: string, handler: (data: unknown) => void): () => void;
+}
+export interface SubagentWaitDeps {
+    state: SubagentState;
+    asyncDirRoot?: string;
+    resultsDir?: string;
+    kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+    now?: () => number;
+    pollIntervalMs?: number;
+    /** False makes the tool return immediately without blocking active async runs. */
+    enabled?: boolean;
+    /** Injectable sleep for tests. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Internal auto-drain mode waits through needs-attention states. */
+    stopOnAttention?: boolean;
+    /** Internal auto-drain mode surfaces failed terminal subagent runs as errors. */
+    failOnFailedRuns?: boolean;
+    /** Injectable provider protocol surfaces for deterministic tests. */
+    backgroundWork?: {
+        snapshot(sessionId: string, nowMs: number): BackgroundWorkSnapshot;
+        wakeChannels(): readonly string[];
+    };
+    /**
+     * Optional event bus (pi.events). When provided, wait wakes immediately on a
+     * subagent completion/control event instead of waiting out the poll interval;
+     * the poll then remains as a reconciliation fallback (crashed runners, missed
+     * events). Omit in tests that want pure poll behavior.
+     */
+    events?: WaitEventBus;
+}
+/**
+ * Block until the targeted async or remembered detached foreground run finishes,
+ * the timeout elapses, or the turn is aborted. Resolves with a short
+ * human-readable summary either way.
+ */
+export declare function waitForSubagents(params: SubagentWaitParams, signal: AbortSignal | undefined, deps: SubagentWaitDeps): Promise<AgentToolResult<Details>>;
+//# sourceMappingURL=subagent-wait.d.ts.map

package/dist/builtin-extensions/pi-subagents/src/runs/background/subagent-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-wait.d.ts","sourceRoot":"","sources":["../../../../../../src/builtin-extensions/pi-subagents/src/runs/background/subagent-wait.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAGN,KAAK,sBAAsB,EAE3B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAQN,KAAK,OAAO,EAEZ,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAS7G,MAAM,WAAW,kBAAkB;IAClC,uGAAuG;IACvG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC5B,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAClE;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,OAAO,CAAC;IAC7D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,cAAc,CAAC,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAAC;QACnE,YAAY,IAAI,SAAS,MAAM,EAAE,CAAC;KAClC,CAAC;IACF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACtB;AA+MD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAuJnC","sourcesContent":["// @ts-nocheck\n/**\n * `subagent_wait` tool: block the current turn until outstanding async runs\n * or a named remembered detached foreground run finishes.\n *\n * Background subagent runs are detached. In an interactive session the parent\n * can end its turn and Pi will wake it with a completion notification. That\n * does not work when the parent is a skill that must run to completion, and it\n * cannot work at all non-interactively (`pi -p ...`), where the run is a single\n * turn: once the turn ends there is nothing left to receive the notification.\n *\n * `subagent_wait` closes that gap. It keeps the turn alive until a tracked async\n * run for this session reaches a terminal state (complete / failed / paused),\n * the caller-supplied timeout elapses, or the turn is aborted. Because it awaits\n * inside the turn, the completion the model was told to wait for is actually\n * observed before the tool returns.\n *\n * By default `subagent_wait` returns as soon as ONE run finishes, so a fleet\n * manager can use it in a rolling-replacement loop: launch N workers, wait for\n * the next one to finish, spawn its replacement, then call `subagent_wait`\n * again — keeping N in flight instead of draining to zero between batches.\n * Pass `all: true` to block until every tracked async run is terminal, or `id`\n * to block on one specific async or remembered detached foreground run.\n *\n * `subagent_wait` also returns when a run needs attention — not just on\n * completion. A child that goes idle or blocks for a decision surfaces\n * `needs_attention` (the same signal Pi shows as a control notice and,\n * interactively, wakes the parent with). Since `subagent_wait` is used exactly\n * where there is no next turn to receive that notice, it must break on it too,\n * or a stuck child would stall the loop until the timeout. Attention runs are\n * reported so the caller can inspect / nudge / resume / interrupt them.\n *\n * Wake mechanism: when given Pi's event bus (`deps.events`), `subagent_wait`\n * subscribes to the subagent completion/control channels and wakes the instant\n * any fires, rather than waiting out a fixed poll interval. A poll still runs\n * on the interval as a reconciliation fallback (crashed runners, missed\n * events), and the poll is the source of truth for what actually changed — the\n * event only ends the sleep early. With no bus, `subagent_wait` degrades to pure\n * polling.\n */\n\nimport type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport {\n\tlistBackgroundWorkWakeChannels,\n\tsnapshotBackgroundWork,\n\ttype BackgroundWorkSnapshot,\n\ttype RegisteredBackgroundWorkItem,\n} from \"../../api/background-work.ts\";\nimport { listAsyncRuns, type AsyncRunSummary } from \"./async-status.ts\";\nimport {\n\tASYNC_DIR,\n\tRESULTS_DIR,\n\tSUBAGENT_ASYNC_COMPLETE_EVENT,\n\tSUBAGENT_FOREGROUND_COMPLETE_EVENT,\n\tSUBAGENT_CONTROL_EVENT,\n\tSUBAGENT_CONTROL_INTERCOM_EVENT,\n\tSUBAGENT_RESULT_INTERCOM_EVENT,\n\ttype Details,\n\ttype ForegroundResumeRun,\n\ttype SubagentState,\n} from \"../../shared/types.ts\";\nimport { formatDuration } from \"../../shared/formatters.ts\";\nexport { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from \"./wait-config.ts\";\n\n/** States that mean a run is still in flight (not yet resolved). */\nconst ACTIVE_STATES: ReadonlyArray<AsyncRunSummary[\"state\"]> = [\"queued\", \"running\"];\n\nconst DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes\nconst MIN_POLL_INTERVAL_MS = 250;\nconst DEFAULT_POLL_INTERVAL_MS = 1000;\n\nexport interface SubagentWaitParams {\n\t/** Optional run id/prefix to wait for. When omitted, waits across every active run in this session. */\n\tid?: string;\n\t/**\n\t * When true, block until EVERY active run in this session (or matching `id`)\n\t * is terminal. Default false: return as soon as the first run finishes, so a\n\t * fleet manager can spawn a replacement and wait again. Ignored when `id`\n\t * targets a single run.\n\t */\n\tall?: boolean;\n\t/** Give up after this many milliseconds. Defaults to 30 minutes. */\n\ttimeoutMs?: number;\n}\n\n/** Minimal event-bus surface wait subscribes to (matches pi.events). */\nexport interface WaitEventBus {\n\ton(channel: string, handler: (data: unknown) => void): () => void;\n}\n\nexport interface SubagentWaitDeps {\n\tstate: SubagentState;\n\tasyncDirRoot?: string;\n\tresultsDir?: string;\n\tkill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;\n\tnow?: () => number;\n\tpollIntervalMs?: number;\n\t/** False makes the tool return immediately without blocking active async runs. */\n\tenabled?: boolean;\n\t/** Injectable sleep for tests. */\n\tsleep?: (ms: number, signal?: AbortSignal) => Promise<void>;\n\t/** Internal auto-drain mode waits through needs-attention states. */\n\tstopOnAttention?: boolean;\n\t/** Internal auto-drain mode surfaces failed terminal subagent runs as errors. */\n\tfailOnFailedRuns?: boolean;\n\t/** Injectable provider protocol surfaces for deterministic tests. */\n\tbackgroundWork?: {\n\t\tsnapshot(sessionId: string, nowMs: number): BackgroundWorkSnapshot;\n\t\twakeChannels(): readonly string[];\n\t};\n\t/**\n\t * Optional event bus (pi.events). When provided, wait wakes immediately on a\n\t * subagent completion/control event instead of waiting out the poll interval;\n\t * the poll then remains as a reconciliation fallback (crashed runners, missed\n\t * events). Omit in tests that want pure poll behavior.\n\t */\n\tevents?: WaitEventBus;\n}\n\n/** Bus channels that indicate a run changed state or needs attention. */\nconst WAKE_CHANNELS = [\n\tSUBAGENT_ASYNC_COMPLETE_EVENT,\n\tSUBAGENT_FOREGROUND_COMPLETE_EVENT,\n\tSUBAGENT_CONTROL_EVENT,\n\tSUBAGENT_CONTROL_INTERCOM_EVENT,\n\tSUBAGENT_RESULT_INTERCOM_EVENT,\n];\n\nfunction defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {\n\treturn new Promise((resolve) => {\n\t\tif (signal?.aborted) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tconst timer = setTimeout(() => {\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve();\n\t\t}, ms);\n\t\tconst onAbort = () => {\n\t\t\tclearTimeout(timer);\n\t\t\tresolve();\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t});\n}\n\n/**\n * Sleep up to `ms`, but wake early if a subagent event fires on the bus (or the\n * turn aborts). Returns when the first of those happens. With no bus this is a\n * plain sleep, so the poll interval alone drives progress.\n */\nfunction waitForWake(ms: number, signal: AbortSignal | undefined, deps: SubagentWaitDeps): Promise<void> {\n\tconst sleep = deps.sleep ?? defaultSleep;\n\tconst events = deps.events;\n\tif (!events) return sleep(ms, signal);\n\tconst providerChannels = deps.backgroundWork?.wakeChannels() ?? listBackgroundWorkWakeChannels();\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tconst unsubs: Array<() => void> = [];\n\t\tconst wakeController = new AbortController();\n\t\tconst done = () => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\twakeController.abort();\n\t\t\tsignal?.removeEventListener(\"abort\", done);\n\t\t\tfor (const u of unsubs) {\n\t\t\t\ttry { u(); } catch { /* best effort */ }\n\t\t\t}\n\t\t\tresolve();\n\t\t};\n\t\tif (signal?.aborted) {\n\t\t\tdone();\n\t\t\treturn;\n\t\t}\n\t\tsignal?.addEventListener(\"abort\", done, { once: true });\n\t\ttry {\n\t\t\tfor (const channel of [...new Set([...WAKE_CHANNELS, ...providerChannels])]) {\n\t\t\t\tunsubs.push(events.on(channel, done));\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tsignal?.removeEventListener(\"abort\", done);\n\t\t\tfor (const unsubscribe of unsubs) {\n\t\t\t\ttry { unsubscribe(); } catch { /* best effort cleanup */ }\n\t\t\t}\n\t\t\treject(error);\n\t\t\treturn;\n\t\t}\n\t\t// Poll-interval fallback so we still reconcile even if no event arrives.\n\t\t// The local signal cancels that fallback timer when an event wakes us first.\n\t\tvoid sleep(ms, wakeController.signal).then(done);\n\t});\n}\n\nfunction matchesId(run: AsyncRunSummary, id: string): boolean {\n\treturn run.id === id || run.id.startsWith(id);\n}\n\nfunction activeDetachedForegroundRuns(params: SubagentWaitParams, deps: SubagentWaitDeps): ForegroundResumeRun[] {\n\tif (!params.id || !deps.state.foregroundRuns) return [];\n\tconst sessionId = deps.state.currentSessionId;\n\tif (!sessionId) return [];\n\treturn [...deps.state.foregroundRuns.values()].filter((run) =>\n\t\t(run.runId === params.id || run.runId.startsWith(params.id!))\n\t\t&& run.sessionId === sessionId\n\t\t&& run.children.some((child) => child.status === \"detached\")\n\t);\n}\n\nfunction summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<number>): string {\n\tconst counts = new Map<string, number>();\n\tfor (const child of run.children) {\n\t\tif (!indices.has(child.index) || child.status === \"detached\") continue;\n\t\tcounts.set(child.status, (counts.get(child.status) ?? 0) + 1);\n\t}\n\treturn [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(\", \");\n}\n\n/** A running run that has flagged it needs the parent's attention. */\nfunction needsAttention(run: AsyncRunSummary): boolean {\n\treturn run.activityState === \"needs_attention\";\n}\n\nfunction backgroundWorkIdentity(item: RegisteredBackgroundWorkItem): string {\n\treturn `${item.provider}\\0${item.sessionId}\\0${item.id}`;\n}\n\nfunction backgroundWorkForSession(deps: SubagentWaitDeps, nowMs: number): BackgroundWorkSnapshot {\n\tconst sessionId = deps.state.currentSessionId;\n\tif (!sessionId) throw new Error(\"subagent_wait requires an active session identity to scope background work safely.\");\n\treturn deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);\n}\n\n/** Queued/running runs from this session, including runs that need attention. */\nfunction activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {\n\tconst asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;\n\tconst resultsDir = deps.resultsDir ?? RESULTS_DIR;\n\tconst runs = listAsyncRuns(asyncDirRoot, {\n\t\tstates: [...ACTIVE_STATES],\n\t\tsessionId: deps.state.currentSessionId ?? undefined,\n\t\tresultsDir,\n\t\tkill: deps.kill,\n\t\tnow: deps.now,\n\t});\n\treturn params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;\n}\n\n/** Runs (from the initial set) currently flagged needs_attention, for reporting. */\nfunction attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps, initialIds: Set<string>): AsyncRunSummary[] {\n\treturn activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));\n}\n\n/** All runs (any state) for this session, for the final summary. */\nfunction allRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {\n\tconst asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;\n\tconst resultsDir = deps.resultsDir ?? RESULTS_DIR;\n\tconst runs = listAsyncRuns(asyncDirRoot, {\n\t\tsessionId: deps.state.currentSessionId ?? undefined,\n\t\tresultsDir,\n\t\tkill: deps.kill,\n\t\tnow: deps.now,\n\t});\n\treturn params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;\n}\n\nfunction summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount = 0): string {\n\tif (runs.length === 0 && providerFinishedCount === 0) return \"\";\n\tconst counts = { complete: 0, failed: 0, paused: 0 } as Record<string, number>;\n\tfor (const run of runs) {\n\t\tif (run.state in counts) counts[run.state] += 1;\n\t}\n\tconst parts: string[] = [];\n\tif (counts.complete) parts.push(`${counts.complete} complete`);\n\tif (counts.failed) parts.push(`${counts.failed} failed`);\n\tif (counts.paused) parts.push(`${counts.paused} paused`);\n\tif (providerFinishedCount > 0) parts.push(`${providerFinishedCount} provider item(s) finished`);\n\treturn parts.join(\", \");\n}\n\nfunction result(text: string, isError = false): AgentToolResult<Details> {\n\treturn {\n\t\tcontent: [{ type: \"text\", text }],\n\t\t...(isError ? { isError: true } : {}),\n\t\tdetails: { mode: \"management\", results: [] },\n\t};\n}\n\nasync function waitForDetachedForegroundRun(\n\trun: ForegroundResumeRun,\n\tsignal: AbortSignal | undefined,\n\tdeps: SubagentWaitDeps,\n\tstartedAt: number,\n\tnow: () => number,\n\tpollIntervalMs: number,\n\ttimeoutMs: number,\n): Promise<AgentToolResult<Details>> {\n\tconst initialDetachedIndices = new Set(run.children.filter((child) => child.status === \"detached\").map((child) => child.index));\n\twhile (true) {\n\t\tif (deps.state.currentSessionId !== run.sessionId) {\n\t\t\treturn result(`Wait stopped because the active session changed while remembered foreground run \"${run.runId}\" was still detached. Return to the originating session to inspect or wait for it.`, true);\n\t\t}\n\t\tconst current = deps.state.foregroundRuns?.get(run.runId);\n\t\tif (!current || current.sessionId !== run.sessionId) {\n\t\t\treturn result(`Remembered foreground run \"${run.runId}\" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);\n\t\t}\n\t\tconst pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === \"detached\");\n\t\tif (pending.length === 0) {\n\t\t\tconst outcome = summarizeForegroundChildren(current, initialDetachedIndices);\n\t\t\treturn result(\n\t\t\t\t`Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run \"${run.runId}\"; done. Outcome: ${outcome || \"no recovered child status\"}. Completion event observed; inspect with subagent({ action: \"status\", id: \"${run.runId}\" }) for recovered output.`,\n\t\t\t);\n\t\t}\n\t\tif (signal?.aborted) {\n\t\t\treturn result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run \"${run.runId}\" remains detached.`, true);\n\t\t}\n\t\tif (now() - startedAt >= timeoutMs) {\n\t\t\treturn result(\n\t\t\t\t`Wait timed out after ${formatDuration(timeoutMs)} with remembered foreground run \"${run.runId}\" still detached. Reply to any pending supervisor request, then call subagent_wait({ id: \"${run.runId}\" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,\n\t\t\t\ttrue,\n\t\t\t);\n\t\t}\n\t\tawait waitForWake(pollIntervalMs, signal, deps);\n\t}\n}\n\n/**\n * Block until the targeted async or remembered detached foreground run finishes,\n * the timeout elapses, or the turn is aborted. Resolves with a short\n * human-readable summary either way.\n */\nexport async function waitForSubagents(\n\tparams: SubagentWaitParams,\n\tsignal: AbortSignal | undefined,\n\tdeps: SubagentWaitDeps,\n): Promise<AgentToolResult<Details>> {\n\tif (deps.enabled === false) {\n\t\treturn result(\"subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background work. Active work keeps going, and you can inspect subagents with subagent({ action: \\\"status\\\" }) or rely on completion notifications.\");\n\t}\n\tif (!deps.state.currentSessionId) {\n\t\treturn result(\"subagent_wait requires an active session identity to scope background work safely.\", true);\n\t}\n\n\tconst now = deps.now ?? Date.now;\n\tconst pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);\n\tconst timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;\n\tconst startedAt = now();\n\tconst waitForAll = params.id ? true : params.all === true;\n\n\tlet active: AsyncRunSummary[];\n\tlet foreground: ForegroundResumeRun[];\n\tlet providerSnapshot: BackgroundWorkSnapshot;\n\ttry {\n\t\tactive = activeRunsForSession(params, deps);\n\t\tforeground = activeDetachedForegroundRuns(params, deps);\n\t\tproviderSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);\n\t} catch (error) {\n\t\treturn result(error instanceof Error ? error.message : String(error), true);\n\t}\n\n\tif (params.id) {\n\t\tconst candidates = [\n\t\t\t...active.map((run) => ({ kind: \"async\" as const, id: run.id, run })),\n\t\t\t...foreground.map((run) => ({ kind: \"foreground\" as const, id: run.runId, run })),\n\t\t];\n\t\tconst exact = candidates.filter((candidate) => candidate.id === params.id);\n\t\tconst matches = exact.length > 0 ? exact : candidates;\n\t\tif (matches.length > 1) {\n\t\t\treturn result(`Ambiguous subagent run id prefix \"${params.id}\" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(\", \")}. Pass a longer id.`, true);\n\t\t}\n\t\tconst selected = matches[0];\n\t\tif (selected?.kind === \"foreground\") {\n\t\t\treturn waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);\n\t\t}\n\t\tactive = selected?.kind === \"async\" ? [selected.run] : [];\n\t}\n\n\tlet providerActive = providerSnapshot.items;\n\tif (active.length === 0 && providerActive.length === 0) {\n\t\treturn result(params.id\n\t\t\t? `No active run matched \"${params.id}\". Nothing to wait for.`\n\t\t\t: \"No active async runs or registered provider work in this session. Nothing to wait for.\");\n\t}\n\tconst waitParams = params.id ? { ...params, id: active[0]!.id } : params;\n\tconst initialAsyncIds = new Set(active.map((run) => run.id));\n\tconst initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));\n\tconst initialProviderNames = new Set(providerActive.map((item) => item.provider));\n\tconst initialCount = initialAsyncIds.size + initialProviderIds.size;\n\tconst stopOnAttention = deps.stopOnAttention !== false;\n\tlet attention = active.filter((run) => needsAttention(run));\n\n\tconst isDone = (): boolean => {\n\t\tif (stopOnAttention && attention.some((run) => initialAsyncIds.has(run.id))) return true;\n\t\tconst activeAsyncIds = new Set(active.map((run) => run.id));\n\t\tconst activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));\n\t\tif (waitForAll) {\n\t\t\treturn [...initialAsyncIds].every((id) => !activeAsyncIds.has(id))\n\t\t\t\t&& [...initialProviderIds].every((id) => !activeProviderIds.has(id));\n\t\t}\n\t\treturn [...initialAsyncIds].some((id) => !activeAsyncIds.has(id))\n\t\t\t|| [...initialProviderIds].some((id) => !activeProviderIds.has(id));\n\t};\n\n\twhile (!isDone()) {\n\t\tconst activeInitialRuns = active.filter((run) => initialAsyncIds.has(run.id));\n\t\tconst activeInitialProviderItems = providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item)));\n\t\tconst stillActive = [\n\t\t\t...activeInitialRuns.map((run) => `${run.id} (${run.state})`),\n\t\t\t...activeInitialProviderItems.map((item) => `${item.provider}/${item.id}`),\n\t\t].join(\", \");\n\t\tif (signal?.aborted) {\n\t\t\treturn result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);\n\t\t}\n\t\tif (now() - startedAt >= timeoutMs) {\n\t\t\treturn result(\n\t\t\t\t`Wait timed out after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call subagent_wait again or inspect subagent status.`,\n\t\t\t\ttrue,\n\t\t\t);\n\t\t}\n\t\ttry {\n\t\t\tawait waitForWake(pollIntervalMs, signal, deps);\n\t\t\tactive = activeRunsForSession(waitParams, deps);\n\t\t\tattention = attentionRunsForSession(waitParams, deps, initialAsyncIds);\n\t\t\tproviderSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());\n\t\t\tfor (const provider of initialProviderNames) {\n\t\t\t\tif (!providerSnapshot.providers.includes(provider)) {\n\t\t\t\t\treturn result(`Background-work provider '${provider}' disappeared while subagent_wait was tracking its active work; completion cannot be confirmed.`, true);\n\t\t\t\t}\n\t\t\t}\n\t\t\tproviderActive = providerSnapshot.items;\n\t\t} catch (error) {\n\t\t\treturn result(error instanceof Error ? error.message : String(error), true);\n\t\t}\n\t}\n\n\tlet terminalSummary: string;\n\tlet finishedAsyncCount: number;\n\tlet failedAsyncCount: number;\n\tconst activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));\n\tconst providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;\n\ttry {\n\t\tconst allNow = allRunsForSession(waitParams, deps);\n\t\tconst terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialAsyncIds.has(run.id));\n\t\tfinishedAsyncCount = terminal.length;\n\t\tfailedAsyncCount = terminal.filter((run) => run.state === \"failed\").length;\n\t\tterminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);\n\t} catch (error) {\n\t\treturn result(error instanceof Error ? error.message : String(error), true);\n\t}\n\n\tconst relevantAttention = attention.filter((run) => initialAsyncIds.has(run.id));\n\tconst attentionNote = relevantAttention.length > 0\n\t\t? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(\", \")} — inspect with subagent({ action: \"status\" }) then nudge/resume/interrupt.`\n\t\t: \"\";\n\tconst stillRunning = active.filter((run) => initialAsyncIds.has(run.id)).length\n\t\t+ providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;\n\tconst elapsed = formatDuration(now() - startedAt);\n\tconst outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : \"\";\n\n\tif (waitForAll) {\n\t\tconst scope = params.id\n\t\t\t? `run \"${params.id}\"`\n\t\t\t: initialProviderIds.size === 0\n\t\t\t\t? `${initialAsyncIds.size} async run(s)`\n\t\t\t\t: `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;\n\t\tconst status = relevantAttention.length > 0 ? \"attention required\" : \"done\";\n\t\treturn result(\n\t\t\t`Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,\n\t\t\tdeps.failOnFailedRuns === true && failedAsyncCount > 0,\n\t\t);\n\t}\n\n\tconst finishedCount = finishedAsyncCount + providerFinishedCount;\n\tconst subject = initialProviderIds.size === 0 ? \"run(s)\" : \"item(s)\";\n\tconst remainder = stillRunning > 0\n\t\t? ` ${stillRunning} ${subject} still in flight — call subagent_wait again to catch the next one.`\n\t\t: relevantAttention.length > 0\n\t\t\t? \" No other work is waitable until attention is handled.\"\n\t\t\t: initialProviderIds.size === 0 ? \" No runs remain in flight.\" : \" No work remains in flight.\";\n\tconst progress = relevantAttention.length > 0 && finishedCount === 0\n\t\t? `${relevantAttention.length} of ${initialCount} ${subject} need attention`\n\t\t: `${finishedCount} of ${initialCount} ${subject} finished`;\n\treturn result(\n\t\t`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,\n\t\tdeps.failOnFailedRuns === true && failedAsyncCount > 0,\n\t);\n}\n"]}

package/dist/builtin-extensions/pi-subagents/src/runs/background/subagent-wait.js

@@ -0,0 +1,387 @@
+// @ts-nocheck
+/**
+ * `subagent_wait` tool: block the current turn until outstanding async runs
+ * or a named remembered detached foreground run finishes.
+ *
+ * Background subagent runs are detached. In an interactive session the parent
+ * can end its turn and Pi will wake it with a completion notification. That
+ * does not work when the parent is a skill that must run to completion, and it
+ * cannot work at all non-interactively (`pi -p ...`), where the run is a single
+ * turn: once the turn ends there is nothing left to receive the notification.
+ *
+ * `subagent_wait` closes that gap. It keeps the turn alive until a tracked async
+ * run for this session reaches a terminal state (complete / failed / paused),
+ * the caller-supplied timeout elapses, or the turn is aborted. Because it awaits
+ * inside the turn, the completion the model was told to wait for is actually
+ * observed before the tool returns.
+ *
+ * By default `subagent_wait` returns as soon as ONE run finishes, so a fleet
+ * manager can use it in a rolling-replacement loop: launch N workers, wait for
+ * the next one to finish, spawn its replacement, then call `subagent_wait`
+ * again — keeping N in flight instead of draining to zero between batches.
+ * Pass `all: true` to block until every tracked async run is terminal, or `id`
+ * to block on one specific async or remembered detached foreground run.
+ *
+ * `subagent_wait` also returns when a run needs attention — not just on
+ * completion. A child that goes idle or blocks for a decision surfaces
+ * `needs_attention` (the same signal Pi shows as a control notice and,
+ * interactively, wakes the parent with). Since `subagent_wait` is used exactly
+ * where there is no next turn to receive that notice, it must break on it too,
+ * or a stuck child would stall the loop until the timeout. Attention runs are
+ * reported so the caller can inspect / nudge / resume / interrupt them.
+ *
+ * Wake mechanism: when given Pi's event bus (`deps.events`), `subagent_wait`
+ * subscribes to the subagent completion/control channels and wakes the instant
+ * any fires, rather than waiting out a fixed poll interval. A poll still runs
+ * on the interval as a reconciliation fallback (crashed runners, missed
+ * events), and the poll is the source of truth for what actually changed — the
+ * event only ends the sleep early. With no bus, `subagent_wait` degrades to pure
+ * polling.
+ */
+import { listBackgroundWorkWakeChannels, snapshotBackgroundWork, } from "../../api/background-work.js";
+import { listAsyncRuns } from "./async-status.js";
+import { ASYNC_DIR, RESULTS_DIR, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_RESULT_INTERCOM_EVENT, } from "../../shared/types.js";
+import { formatDuration } from "../../shared/formatters.js";
+export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig } from "./wait-config.js";
+/** States that mean a run is still in flight (not yet resolved). */
+const ACTIVE_STATES = ["queued", "running"];
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const MIN_POLL_INTERVAL_MS = 250;
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+/** Bus channels that indicate a run changed state or needs attention. */
+const WAKE_CHANNELS = [
+    SUBAGENT_ASYNC_COMPLETE_EVENT,
+    SUBAGENT_FOREGROUND_COMPLETE_EVENT,
+    SUBAGENT_CONTROL_EVENT,
+    SUBAGENT_CONTROL_INTERCOM_EVENT,
+    SUBAGENT_RESULT_INTERCOM_EVENT,
+];
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Sleep up to `ms`, but wake early if a subagent event fires on the bus (or the
+ * turn aborts). Returns when the first of those happens. With no bus this is a
+ * plain sleep, so the poll interval alone drives progress.
+ */
+function waitForWake(ms, signal, deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const events = deps.events;
+    if (!events)
+        return sleep(ms, signal);
+    const providerChannels = deps.backgroundWork?.wakeChannels() ?? listBackgroundWorkWakeChannels();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const unsubs = [];
+        const wakeController = new AbortController();
+        const done = () => {
+            if (settled)
+                return;
+            settled = true;
+            wakeController.abort();
+            signal?.removeEventListener("abort", done);
+            for (const u of unsubs) {
+                try {
+                    u();
+                }
+                catch { /* best effort */ }
+            }
+            resolve();
+        };
+        if (signal?.aborted) {
+            done();
+            return;
+        }
+        signal?.addEventListener("abort", done, { once: true });
+        try {
+            for (const channel of [...new Set([...WAKE_CHANNELS, ...providerChannels])]) {
+                unsubs.push(events.on(channel, done));
+            }
+        }
+        catch (error) {
+            signal?.removeEventListener("abort", done);
+            for (const unsubscribe of unsubs) {
+                try {
+                    unsubscribe();
+                }
+                catch { /* best effort cleanup */ }
+            }
+            reject(error);
+            return;
+        }
+        // Poll-interval fallback so we still reconcile even if no event arrives.
+        // The local signal cancels that fallback timer when an event wakes us first.
+        void sleep(ms, wakeController.signal).then(done);
+    });
+}
+function matchesId(run, id) {
+    return run.id === id || run.id.startsWith(id);
+}
+function activeDetachedForegroundRuns(params, deps) {
+    if (!params.id || !deps.state.foregroundRuns)
+        return [];
+    const sessionId = deps.state.currentSessionId;
+    if (!sessionId)
+        return [];
+    return [...deps.state.foregroundRuns.values()].filter((run) => (run.runId === params.id || run.runId.startsWith(params.id))
+        && run.sessionId === sessionId
+        && run.children.some((child) => child.status === "detached"));
+}
+function summarizeForegroundChildren(run, indices) {
+    const counts = new Map();
+    for (const child of run.children) {
+        if (!indices.has(child.index) || child.status === "detached")
+            continue;
+        counts.set(child.status, (counts.get(child.status) ?? 0) + 1);
+    }
+    return [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(", ");
+}
+/** A running run that has flagged it needs the parent's attention. */
+function needsAttention(run) {
+    return run.activityState === "needs_attention";
+}
+function backgroundWorkIdentity(item) {
+    return `${item.provider}\0${item.sessionId}\0${item.id}`;
+}
+function backgroundWorkForSession(deps, nowMs) {
+    const sessionId = deps.state.currentSessionId;
+    if (!sessionId)
+        throw new Error("subagent_wait requires an active session identity to scope background work safely.");
+    return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
+}
+/** Queued/running runs from this session, including runs that need attention. */
+function activeRunsForSession(params, deps) {
+    const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+    const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+    const runs = listAsyncRuns(asyncDirRoot, {
+        states: [...ACTIVE_STATES],
+        sessionId: deps.state.currentSessionId ?? undefined,
+        resultsDir,
+        kill: deps.kill,
+        now: deps.now,
+    });
+    return params.id ? runs.filter((run) => matchesId(run, params.id)) : runs;
+}
+/** Runs (from the initial set) currently flagged needs_attention, for reporting. */
+function attentionRunsForSession(params, deps, initialIds) {
+    return activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));
+}
+/** All runs (any state) for this session, for the final summary. */
+function allRunsForSession(params, deps) {
+    const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+    const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+    const runs = listAsyncRuns(asyncDirRoot, {
+        sessionId: deps.state.currentSessionId ?? undefined,
+        resultsDir,
+        kill: deps.kill,
+        now: deps.now,
+    });
+    return params.id ? runs.filter((run) => matchesId(run, params.id)) : runs;
+}
+function summarizeTerminalRuns(runs, providerFinishedCount = 0) {
+    if (runs.length === 0 && providerFinishedCount === 0)
+        return "";
+    const counts = { complete: 0, failed: 0, paused: 0 };
+    for (const run of runs) {
+        if (run.state in counts)
+            counts[run.state] += 1;
+    }
+    const parts = [];
+    if (counts.complete)
+        parts.push(`${counts.complete} complete`);
+    if (counts.failed)
+        parts.push(`${counts.failed} failed`);
+    if (counts.paused)
+        parts.push(`${counts.paused} paused`);
+    if (providerFinishedCount > 0)
+        parts.push(`${providerFinishedCount} provider item(s) finished`);
+    return parts.join(", ");
+}
+function result(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        ...(isError ? { isError: true } : {}),
+        details: { mode: "management", results: [] },
+    };
+}
+async function waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs) {
+    const initialDetachedIndices = new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index));
+    while (true) {
+        if (deps.state.currentSessionId !== run.sessionId) {
+            return result(`Wait stopped because the active session changed while remembered foreground run "${run.runId}" was still detached. Return to the originating session to inspect or wait for it.`, true);
+        }
+        const current = deps.state.foregroundRuns?.get(run.runId);
+        if (!current || current.sessionId !== run.sessionId) {
+            return result(`Remembered foreground run "${run.runId}" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);
+        }
+        const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
+        if (pending.length === 0) {
+            const outcome = summarizeForegroundChildren(current, initialDetachedIndices);
+            return result(`Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run "${run.runId}"; done. Outcome: ${outcome || "no recovered child status"}. Completion event observed; inspect with subagent({ action: "status", id: "${run.runId}" }) for recovered output.`);
+        }
+        if (signal?.aborted) {
+            return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run "${run.runId}" remains detached.`, true);
+        }
+        if (now() - startedAt >= timeoutMs) {
+            return result(`Wait timed out after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call subagent_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`, true);
+        }
+        await waitForWake(pollIntervalMs, signal, deps);
+    }
+}
+/**
+ * Block until the targeted async or remembered detached foreground run finishes,
+ * the timeout elapses, or the turn is aborted. Resolves with a short
+ * human-readable summary either way.
+ */
+export async function waitForSubagents(params, signal, deps) {
+    if (deps.enabled === false) {
+        return result("subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background work. Active work keeps going, and you can inspect subagents with subagent({ action: \"status\" }) or rely on completion notifications.");
+    }
+    if (!deps.state.currentSessionId) {
+        return result("subagent_wait requires an active session identity to scope background work safely.", true);
+    }
+    const now = deps.now ?? Date.now;
+    const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;
+    const startedAt = now();
+    const waitForAll = params.id ? true : params.all === true;
+    let active;
+    let foreground;
+    let providerSnapshot;
+    try {
+        active = activeRunsForSession(params, deps);
+        foreground = activeDetachedForegroundRuns(params, deps);
+        providerSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);
+    }
+    catch (error) {
+        return result(error instanceof Error ? error.message : String(error), true);
+    }
+    if (params.id) {
+        const candidates = [
+            ...active.map((run) => ({ kind: "async", id: run.id, run })),
+            ...foreground.map((run) => ({ kind: "foreground", id: run.runId, run })),
+        ];
+        const exact = candidates.filter((candidate) => candidate.id === params.id);
+        const matches = exact.length > 0 ? exact : candidates;
+        if (matches.length > 1) {
+            return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
+        }
+        const selected = matches[0];
+        if (selected?.kind === "foreground") {
+            return waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
+        }
+        active = selected?.kind === "async" ? [selected.run] : [];
+    }
+    let providerActive = providerSnapshot.items;
+    if (active.length === 0 && providerActive.length === 0) {
+        return result(params.id
+            ? `No active run matched "${params.id}". Nothing to wait for.`
+            : "No active async runs or registered provider work in this session. Nothing to wait for.");
+    }
+    const waitParams = params.id ? { ...params, id: active[0].id } : params;
+    const initialAsyncIds = new Set(active.map((run) => run.id));
+    const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+    const initialProviderNames = new Set(providerActive.map((item) => item.provider));
+    const initialCount = initialAsyncIds.size + initialProviderIds.size;
+    const stopOnAttention = deps.stopOnAttention !== false;
+    let attention = active.filter((run) => needsAttention(run));
+    const isDone = () => {
+        if (stopOnAttention && attention.some((run) => initialAsyncIds.has(run.id)))
+            return true;
+        const activeAsyncIds = new Set(active.map((run) => run.id));
+        const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+        if (waitForAll) {
+            return [...initialAsyncIds].every((id) => !activeAsyncIds.has(id))
+                && [...initialProviderIds].every((id) => !activeProviderIds.has(id));
+        }
+        return [...initialAsyncIds].some((id) => !activeAsyncIds.has(id))
+            || [...initialProviderIds].some((id) => !activeProviderIds.has(id));
+    };
+    while (!isDone()) {
+        const activeInitialRuns = active.filter((run) => initialAsyncIds.has(run.id));
+        const activeInitialProviderItems = providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item)));
+        const stillActive = [
+            ...activeInitialRuns.map((run) => `${run.id} (${run.state})`),
+            ...activeInitialProviderItems.map((item) => `${item.provider}/${item.id}`),
+        ].join(", ");
+        if (signal?.aborted) {
+            return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);
+        }
+        if (now() - startedAt >= timeoutMs) {
+            return result(`Wait timed out after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call subagent_wait again or inspect subagent status.`, true);
+        }
+        try {
+            await waitForWake(pollIntervalMs, signal, deps);
+            active = activeRunsForSession(waitParams, deps);
+            attention = attentionRunsForSession(waitParams, deps, initialAsyncIds);
+            providerSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());
+            for (const provider of initialProviderNames) {
+                if (!providerSnapshot.providers.includes(provider)) {
+                    return result(`Background-work provider '${provider}' disappeared while subagent_wait was tracking its active work; completion cannot be confirmed.`, true);
+                }
+            }
+            providerActive = providerSnapshot.items;
+        }
+        catch (error) {
+            return result(error instanceof Error ? error.message : String(error), true);
+        }
+    }
+    let terminalSummary;
+    let finishedAsyncCount;
+    let failedAsyncCount;
+    const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+    const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
+    try {
+        const allNow = allRunsForSession(waitParams, deps);
+        const terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialAsyncIds.has(run.id));
+        finishedAsyncCount = terminal.length;
+        failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
+        terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
+    }
+    catch (error) {
+        return result(error instanceof Error ? error.message : String(error), true);
+    }
+    const relevantAttention = attention.filter((run) => initialAsyncIds.has(run.id));
+    const attentionNote = relevantAttention.length > 0
+        ? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(", ")} — inspect with subagent({ action: "status" }) then nudge/resume/interrupt.`
+        : "";
+    const stillRunning = active.filter((run) => initialAsyncIds.has(run.id)).length
+        + providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;
+    const elapsed = formatDuration(now() - startedAt);
+    const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
+    if (waitForAll) {
+        const scope = params.id
+            ? `run "${params.id}"`
+            : initialProviderIds.size === 0
+                ? `${initialAsyncIds.size} async run(s)`
+                : `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
+        const status = relevantAttention.length > 0 ? "attention required" : "done";
+        return result(`Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`, deps.failOnFailedRuns === true && failedAsyncCount > 0);
+    }
+    const finishedCount = finishedAsyncCount + providerFinishedCount;
+    const subject = initialProviderIds.size === 0 ? "run(s)" : "item(s)";
+    const remainder = stillRunning > 0
+        ? ` ${stillRunning} ${subject} still in flight — call subagent_wait again to catch the next one.`
+        : relevantAttention.length > 0
+            ? " No other work is waitable until attention is handled."
+            : initialProviderIds.size === 0 ? " No runs remain in flight." : " No work remains in flight.";
+    const progress = relevantAttention.length > 0 && finishedCount === 0
+        ? `${relevantAttention.length} of ${initialCount} ${subject} need attention`
+        : `${finishedCount} of ${initialCount} ${subject} finished`;
+    return result(`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`, deps.failOnFailedRuns === true && failedAsyncCount > 0);
+}
+//# sourceMappingURL=subagent-wait.js.map

package/dist/builtin-extensions/pi-subagents/src/runs/background/subagent-wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-wait.js","sourceRoot":"","sources":["../../../../../../src/builtin-extensions/pi-subagents/src/runs/background/subagent-wait.ts"],"names":[],"mappings":"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","sourcesContent":["// @ts-nocheck\n/**\n * `subagent_wait` tool: block the current turn until outstanding async runs\n * or a named remembered detached foreground run finishes.\n *\n * Background subagent runs are detached. In an interactive session the parent\n * can end its turn and Pi will wake it with a completion notification. That\n * does not work when the parent is a skill that must run to completion, and it\n * cannot work at all non-interactively (`pi -p ...`), where the run is a single\n * turn: once the turn ends there is nothing left to receive the notification.\n *\n * `subagent_wait` closes that gap. It keeps the turn alive until a tracked async\n * run for this session reaches a terminal state (complete / failed / paused),\n * the caller-supplied timeout elapses, or the turn is aborted. Because it awaits\n * inside the turn, the completion the model was told to wait for is actually\n * observed before the tool returns.\n *\n * By default `subagent_wait` returns as soon as ONE run finishes, so a fleet\n * manager can use it in a rolling-replacement loop: launch N workers, wait for\n * the next one to finish, spawn its replacement, then call `subagent_wait`\n * again — keeping N in flight instead of draining to zero between batches.\n * Pass `all: true` to block until every tracked async run is terminal, or `id`\n * to block on one specific async or remembered detached foreground run.\n *\n * `subagent_wait` also returns when a run needs attention — not just on\n * completion. A child that goes idle or blocks for a decision surfaces\n * `needs_attention` (the same signal Pi shows as a control notice and,\n * interactively, wakes the parent with). Since `subagent_wait` is used exactly\n * where there is no next turn to receive that notice, it must break on it too,\n * or a stuck child would stall the loop until the timeout. Attention runs are\n * reported so the caller can inspect / nudge / resume / interrupt them.\n *\n * Wake mechanism: when given Pi's event bus (`deps.events`), `subagent_wait`\n * subscribes to the subagent completion/control channels and wakes the instant\n * any fires, rather than waiting out a fixed poll interval. A poll still runs\n * on the interval as a reconciliation fallback (crashed runners, missed\n * events), and the poll is the source of truth for what actually changed — the\n * event only ends the sleep early. With no bus, `subagent_wait` degrades to pure\n * polling.\n */\n\nimport type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport {\n\tlistBackgroundWorkWakeChannels,\n\tsnapshotBackgroundWork,\n\ttype BackgroundWorkSnapshot,\n\ttype RegisteredBackgroundWorkItem,\n} from \"../../api/background-work.ts\";\nimport { listAsyncRuns, type AsyncRunSummary } from \"./async-status.ts\";\nimport {\n\tASYNC_DIR,\n\tRESULTS_DIR,\n\tSUBAGENT_ASYNC_COMPLETE_EVENT,\n\tSUBAGENT_FOREGROUND_COMPLETE_EVENT,\n\tSUBAGENT_CONTROL_EVENT,\n\tSUBAGENT_CONTROL_INTERCOM_EVENT,\n\tSUBAGENT_RESULT_INTERCOM_EVENT,\n\ttype Details,\n\ttype ForegroundResumeRun,\n\ttype SubagentState,\n} from \"../../shared/types.ts\";\nimport { formatDuration } from \"../../shared/formatters.ts\";\nexport { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from \"./wait-config.ts\";\n\n/** States that mean a run is still in flight (not yet resolved). */\nconst ACTIVE_STATES: ReadonlyArray<AsyncRunSummary[\"state\"]> = [\"queued\", \"running\"];\n\nconst DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes\nconst MIN_POLL_INTERVAL_MS = 250;\nconst DEFAULT_POLL_INTERVAL_MS = 1000;\n\nexport interface SubagentWaitParams {\n\t/** Optional run id/prefix to wait for. When omitted, waits across every active run in this session. */\n\tid?: string;\n\t/**\n\t * When true, block until EVERY active run in this session (or matching `id`)\n\t * is terminal. Default false: return as soon as the first run finishes, so a\n\t * fleet manager can spawn a replacement and wait again. Ignored when `id`\n\t * targets a single run.\n\t */\n\tall?: boolean;\n\t/** Give up after this many milliseconds. Defaults to 30 minutes. */\n\ttimeoutMs?: number;\n}\n\n/** Minimal event-bus surface wait subscribes to (matches pi.events). */\nexport interface WaitEventBus {\n\ton(channel: string, handler: (data: unknown) => void): () => void;\n}\n\nexport interface SubagentWaitDeps {\n\tstate: SubagentState;\n\tasyncDirRoot?: string;\n\tresultsDir?: string;\n\tkill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;\n\tnow?: () => number;\n\tpollIntervalMs?: number;\n\t/** False makes the tool return immediately without blocking active async runs. */\n\tenabled?: boolean;\n\t/** Injectable sleep for tests. */\n\tsleep?: (ms: number, signal?: AbortSignal) => Promise<void>;\n\t/** Internal auto-drain mode waits through needs-attention states. */\n\tstopOnAttention?: boolean;\n\t/** Internal auto-drain mode surfaces failed terminal subagent runs as errors. */\n\tfailOnFailedRuns?: boolean;\n\t/** Injectable provider protocol surfaces for deterministic tests. */\n\tbackgroundWork?: {\n\t\tsnapshot(sessionId: string, nowMs: number): BackgroundWorkSnapshot;\n\t\twakeChannels(): readonly string[];\n\t};\n\t/**\n\t * Optional event bus (pi.events). When provided, wait wakes immediately on a\n\t * subagent completion/control event instead of waiting out the poll interval;\n\t * the poll then remains as a reconciliation fallback (crashed runners, missed\n\t * events). Omit in tests that want pure poll behavior.\n\t */\n\tevents?: WaitEventBus;\n}\n\n/** Bus channels that indicate a run changed state or needs attention. */\nconst WAKE_CHANNELS = [\n\tSUBAGENT_ASYNC_COMPLETE_EVENT,\n\tSUBAGENT_FOREGROUND_COMPLETE_EVENT,\n\tSUBAGENT_CONTROL_EVENT,\n\tSUBAGENT_CONTROL_INTERCOM_EVENT,\n\tSUBAGENT_RESULT_INTERCOM_EVENT,\n];\n\nfunction defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {\n\treturn new Promise((resolve) => {\n\t\tif (signal?.aborted) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tconst timer = setTimeout(() => {\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve();\n\t\t}, ms);\n\t\tconst onAbort = () => {\n\t\t\tclearTimeout(timer);\n\t\t\tresolve();\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t});\n}\n\n/**\n * Sleep up to `ms`, but wake early if a subagent event fires on the bus (or the\n * turn aborts). Returns when the first of those happens. With no bus this is a\n * plain sleep, so the poll interval alone drives progress.\n */\nfunction waitForWake(ms: number, signal: AbortSignal | undefined, deps: SubagentWaitDeps): Promise<void> {\n\tconst sleep = deps.sleep ?? defaultSleep;\n\tconst events = deps.events;\n\tif (!events) return sleep(ms, signal);\n\tconst providerChannels = deps.backgroundWork?.wakeChannels() ?? listBackgroundWorkWakeChannels();\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tconst unsubs: Array<() => void> = [];\n\t\tconst wakeController = new AbortController();\n\t\tconst done = () => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\twakeController.abort();\n\t\t\tsignal?.removeEventListener(\"abort\", done);\n\t\t\tfor (const u of unsubs) {\n\t\t\t\ttry { u(); } catch { /* best effort */ }\n\t\t\t}\n\t\t\tresolve();\n\t\t};\n\t\tif (signal?.aborted) {\n\t\t\tdone();\n\t\t\treturn;\n\t\t}\n\t\tsignal?.addEventListener(\"abort\", done, { once: true });\n\t\ttry {\n\t\t\tfor (const channel of [...new Set([...WAKE_CHANNELS, ...providerChannels])]) {\n\t\t\t\tunsubs.push(events.on(channel, done));\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tsignal?.removeEventListener(\"abort\", done);\n\t\t\tfor (const unsubscribe of unsubs) {\n\t\t\t\ttry { unsubscribe(); } catch { /* best effort cleanup */ }\n\t\t\t}\n\t\t\treject(error);\n\t\t\treturn;\n\t\t}\n\t\t// Poll-interval fallback so we still reconcile even if no event arrives.\n\t\t// The local signal cancels that fallback timer when an event wakes us first.\n\t\tvoid sleep(ms, wakeController.signal).then(done);\n\t});\n}\n\nfunction matchesId(run: AsyncRunSummary, id: string): boolean {\n\treturn run.id === id || run.id.startsWith(id);\n}\n\nfunction activeDetachedForegroundRuns(params: SubagentWaitParams, deps: SubagentWaitDeps): ForegroundResumeRun[] {\n\tif (!params.id || !deps.state.foregroundRuns) return [];\n\tconst sessionId = deps.state.currentSessionId;\n\tif (!sessionId) return [];\n\treturn [...deps.state.foregroundRuns.values()].filter((run) =>\n\t\t(run.runId === params.id || run.runId.startsWith(params.id!))\n\t\t&& run.sessionId === sessionId\n\t\t&& run.children.some((child) => child.status === \"detached\")\n\t);\n}\n\nfunction summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<number>): string {\n\tconst counts = new Map<string, number>();\n\tfor (const child of run.children) {\n\t\tif (!indices.has(child.index) || child.status === \"detached\") continue;\n\t\tcounts.set(child.status, (counts.get(child.status) ?? 0) + 1);\n\t}\n\treturn [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(\", \");\n}\n\n/** A running run that has flagged it needs the parent's attention. */\nfunction needsAttention(run: AsyncRunSummary): boolean {\n\treturn run.activityState === \"needs_attention\";\n}\n\nfunction backgroundWorkIdentity(item: RegisteredBackgroundWorkItem): string {\n\treturn `${item.provider}\\0${item.sessionId}\\0${item.id}`;\n}\n\nfunction backgroundWorkForSession(deps: SubagentWaitDeps, nowMs: number): BackgroundWorkSnapshot {\n\tconst sessionId = deps.state.currentSessionId;\n\tif (!sessionId) throw new Error(\"subagent_wait requires an active session identity to scope background work safely.\");\n\treturn deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);\n}\n\n/** Queued/running runs from this session, including runs that need attention. */\nfunction activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {\n\tconst asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;\n\tconst resultsDir = deps.resultsDir ?? RESULTS_DIR;\n\tconst runs = listAsyncRuns(asyncDirRoot, {\n\t\tstates: [...ACTIVE_STATES],\n\t\tsessionId: deps.state.currentSessionId ?? undefined,\n\t\tresultsDir,\n\t\tkill: deps.kill,\n\t\tnow: deps.now,\n\t});\n\treturn params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;\n}\n\n/** Runs (from the initial set) currently flagged needs_attention, for reporting. */\nfunction attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps, initialIds: Set<string>): AsyncRunSummary[] {\n\treturn activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));\n}\n\n/** All runs (any state) for this session, for the final summary. */\nfunction allRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {\n\tconst asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;\n\tconst resultsDir = deps.resultsDir ?? RESULTS_DIR;\n\tconst runs = listAsyncRuns(asyncDirRoot, {\n\t\tsessionId: deps.state.currentSessionId ?? undefined,\n\t\tresultsDir,\n\t\tkill: deps.kill,\n\t\tnow: deps.now,\n\t});\n\treturn params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;\n}\n\nfunction summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount = 0): string {\n\tif (runs.length === 0 && providerFinishedCount === 0) return \"\";\n\tconst counts = { complete: 0, failed: 0, paused: 0 } as Record<string, number>;\n\tfor (const run of runs) {\n\t\tif (run.state in counts) counts[run.state] += 1;\n\t}\n\tconst parts: string[] = [];\n\tif (counts.complete) parts.push(`${counts.complete} complete`);\n\tif (counts.failed) parts.push(`${counts.failed} failed`);\n\tif (counts.paused) parts.push(`${counts.paused} paused`);\n\tif (providerFinishedCount > 0) parts.push(`${providerFinishedCount} provider item(s) finished`);\n\treturn parts.join(\", \");\n}\n\nfunction result(text: string, isError = false): AgentToolResult<Details> {\n\treturn {\n\t\tcontent: [{ type: \"text\", text }],\n\t\t...(isError ? { isError: true } : {}),\n\t\tdetails: { mode: \"management\", results: [] },\n\t};\n}\n\nasync function waitForDetachedForegroundRun(\n\trun: ForegroundResumeRun,\n\tsignal: AbortSignal | undefined,\n\tdeps: SubagentWaitDeps,\n\tstartedAt: number,\n\tnow: () => number,\n\tpollIntervalMs: number,\n\ttimeoutMs: number,\n): Promise<AgentToolResult<Details>> {\n\tconst initialDetachedIndices = new Set(run.children.filter((child) => child.status === \"detached\").map((child) => child.index));\n\twhile (true) {\n\t\tif (deps.state.currentSessionId !== run.sessionId) {\n\t\t\treturn result(`Wait stopped because the active session changed while remembered foreground run \"${run.runId}\" was still detached. Return to the originating session to inspect or wait for it.`, true);\n\t\t}\n\t\tconst current = deps.state.foregroundRuns?.get(run.runId);\n\t\tif (!current || current.sessionId !== run.sessionId) {\n\t\t\treturn result(`Remembered foreground run \"${run.runId}\" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);\n\t\t}\n\t\tconst pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === \"detached\");\n\t\tif (pending.length === 0) {\n\t\t\tconst outcome = summarizeForegroundChildren(current, initialDetachedIndices);\n\t\t\treturn result(\n\t\t\t\t`Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run \"${run.runId}\"; done. Outcome: ${outcome || \"no recovered child status\"}. Completion event observed; inspect with subagent({ action: \"status\", id: \"${run.runId}\" }) for recovered output.`,\n\t\t\t);\n\t\t}\n\t\tif (signal?.aborted) {\n\t\t\treturn result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run \"${run.runId}\" remains detached.`, true);\n\t\t}\n\t\tif (now() - startedAt >= timeoutMs) {\n\t\t\treturn result(\n\t\t\t\t`Wait timed out after ${formatDuration(timeoutMs)} with remembered foreground run \"${run.runId}\" still detached. Reply to any pending supervisor request, then call subagent_wait({ id: \"${run.runId}\" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,\n\t\t\t\ttrue,\n\t\t\t);\n\t\t}\n\t\tawait waitForWake(pollIntervalMs, signal, deps);\n\t}\n}\n\n/**\n * Block until the targeted async or remembered detached foreground run finishes,\n * the timeout elapses, or the turn is aborted. Resolves with a short\n * human-readable summary either way.\n */\nexport async function waitForSubagents(\n\tparams: SubagentWaitParams,\n\tsignal: AbortSignal | undefined,\n\tdeps: SubagentWaitDeps,\n): Promise<AgentToolResult<Details>> {\n\tif (deps.enabled === false) {\n\t\treturn result(\"subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background work. Active work keeps going, and you can inspect subagents with subagent({ action: \\\"status\\\" }) or rely on completion notifications.\");\n\t}\n\tif (!deps.state.currentSessionId) {\n\t\treturn result(\"subagent_wait requires an active session identity to scope background work safely.\", true);\n\t}\n\n\tconst now = deps.now ?? Date.now;\n\tconst pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);\n\tconst timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;\n\tconst startedAt = now();\n\tconst waitForAll = params.id ? true : params.all === true;\n\n\tlet active: AsyncRunSummary[];\n\tlet foreground: ForegroundResumeRun[];\n\tlet providerSnapshot: BackgroundWorkSnapshot;\n\ttry {\n\t\tactive = activeRunsForSession(params, deps);\n\t\tforeground = activeDetachedForegroundRuns(params, deps);\n\t\tproviderSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);\n\t} catch (error) {\n\t\treturn result(error instanceof Error ? error.message : String(error), true);\n\t}\n\n\tif (params.id) {\n\t\tconst candidates = [\n\t\t\t...active.map((run) => ({ kind: \"async\" as const, id: run.id, run })),\n\t\t\t...foreground.map((run) => ({ kind: \"foreground\" as const, id: run.runId, run })),\n\t\t];\n\t\tconst exact = candidates.filter((candidate) => candidate.id === params.id);\n\t\tconst matches = exact.length > 0 ? exact : candidates;\n\t\tif (matches.length > 1) {\n\t\t\treturn result(`Ambiguous subagent run id prefix \"${params.id}\" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(\", \")}. Pass a longer id.`, true);\n\t\t}\n\t\tconst selected = matches[0];\n\t\tif (selected?.kind === \"foreground\") {\n\t\t\treturn waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);\n\t\t}\n\t\tactive = selected?.kind === \"async\" ? [selected.run] : [];\n\t}\n\n\tlet providerActive = providerSnapshot.items;\n\tif (active.length === 0 && providerActive.length === 0) {\n\t\treturn result(params.id\n\t\t\t? `No active run matched \"${params.id}\". Nothing to wait for.`\n\t\t\t: \"No active async runs or registered provider work in this session. Nothing to wait for.\");\n\t}\n\tconst waitParams = params.id ? { ...params, id: active[0]!.id } : params;\n\tconst initialAsyncIds = new Set(active.map((run) => run.id));\n\tconst initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));\n\tconst initialProviderNames = new Set(providerActive.map((item) => item.provider));\n\tconst initialCount = initialAsyncIds.size + initialProviderIds.size;\n\tconst stopOnAttention = deps.stopOnAttention !== false;\n\tlet attention = active.filter((run) => needsAttention(run));\n\n\tconst isDone = (): boolean => {\n\t\tif (stopOnAttention && attention.some((run) => initialAsyncIds.has(run.id))) return true;\n\t\tconst activeAsyncIds = new Set(active.map((run) => run.id));\n\t\tconst activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));\n\t\tif (waitForAll) {\n\t\t\treturn [...initialAsyncIds].every((id) => !activeAsyncIds.has(id))\n\t\t\t\t&& [...initialProviderIds].every((id) => !activeProviderIds.has(id));\n\t\t}\n\t\treturn [...initialAsyncIds].some((id) => !activeAsyncIds.has(id))\n\t\t\t|| [...initialProviderIds].some((id) => !activeProviderIds.has(id));\n\t};\n\n\twhile (!isDone()) {\n\t\tconst activeInitialRuns = active.filter((run) => initialAsyncIds.has(run.id));\n\t\tconst activeInitialProviderItems = providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item)));\n\t\tconst stillActive = [\n\t\t\t...activeInitialRuns.map((run) => `${run.id} (${run.state})`),\n\t\t\t...activeInitialProviderItems.map((item) => `${item.provider}/${item.id}`),\n\t\t].join(\", \");\n\t\tif (signal?.aborted) {\n\t\t\treturn result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);\n\t\t}\n\t\tif (now() - startedAt >= timeoutMs) {\n\t\t\treturn result(\n\t\t\t\t`Wait timed out after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call subagent_wait again or inspect subagent status.`,\n\t\t\t\ttrue,\n\t\t\t);\n\t\t}\n\t\ttry {\n\t\t\tawait waitForWake(pollIntervalMs, signal, deps);\n\t\t\tactive = activeRunsForSession(waitParams, deps);\n\t\t\tattention = attentionRunsForSession(waitParams, deps, initialAsyncIds);\n\t\t\tproviderSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());\n\t\t\tfor (const provider of initialProviderNames) {\n\t\t\t\tif (!providerSnapshot.providers.includes(provider)) {\n\t\t\t\t\treturn result(`Background-work provider '${provider}' disappeared while subagent_wait was tracking its active work; completion cannot be confirmed.`, true);\n\t\t\t\t}\n\t\t\t}\n\t\t\tproviderActive = providerSnapshot.items;\n\t\t} catch (error) {\n\t\t\treturn result(error instanceof Error ? error.message : String(error), true);\n\t\t}\n\t}\n\n\tlet terminalSummary: string;\n\tlet finishedAsyncCount: number;\n\tlet failedAsyncCount: number;\n\tconst activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));\n\tconst providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;\n\ttry {\n\t\tconst allNow = allRunsForSession(waitParams, deps);\n\t\tconst terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialAsyncIds.has(run.id));\n\t\tfinishedAsyncCount = terminal.length;\n\t\tfailedAsyncCount = terminal.filter((run) => run.state === \"failed\").length;\n\t\tterminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);\n\t} catch (error) {\n\t\treturn result(error instanceof Error ? error.message : String(error), true);\n\t}\n\n\tconst relevantAttention = attention.filter((run) => initialAsyncIds.has(run.id));\n\tconst attentionNote = relevantAttention.length > 0\n\t\t? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(\", \")} — inspect with subagent({ action: \"status\" }) then nudge/resume/interrupt.`\n\t\t: \"\";\n\tconst stillRunning = active.filter((run) => initialAsyncIds.has(run.id)).length\n\t\t+ providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;\n\tconst elapsed = formatDuration(now() - startedAt);\n\tconst outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : \"\";\n\n\tif (waitForAll) {\n\t\tconst scope = params.id\n\t\t\t? `run \"${params.id}\"`\n\t\t\t: initialProviderIds.size === 0\n\t\t\t\t? `${initialAsyncIds.size} async run(s)`\n\t\t\t\t: `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;\n\t\tconst status = relevantAttention.length > 0 ? \"attention required\" : \"done\";\n\t\treturn result(\n\t\t\t`Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,\n\t\t\tdeps.failOnFailedRuns === true && failedAsyncCount > 0,\n\t\t);\n\t}\n\n\tconst finishedCount = finishedAsyncCount + providerFinishedCount;\n\tconst subject = initialProviderIds.size === 0 ? \"run(s)\" : \"item(s)\";\n\tconst remainder = stillRunning > 0\n\t\t? ` ${stillRunning} ${subject} still in flight — call subagent_wait again to catch the next one.`\n\t\t: relevantAttention.length > 0\n\t\t\t? \" No other work is waitable until attention is handled.\"\n\t\t\t: initialProviderIds.size === 0 ? \" No runs remain in flight.\" : \" No work remains in flight.\";\n\tconst progress = relevantAttention.length > 0 && finishedCount === 0\n\t\t? `${relevantAttention.length} of ${initialCount} ${subject} need attention`\n\t\t: `${finishedCount} of ${initialCount} ${subject} finished`;\n\treturn result(\n\t\t`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,\n\t\tdeps.failOnFailedRuns === true && failedAsyncCount > 0,\n\t);\n}\n"]}