pi-subagents 0.68.0 → 0.70.0

package/src/runs/background/subagent-wait.js

@@ -0,0 +1,735 @@
+/**
+ * `bg_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.
+ *
+ * `bg_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 `bg_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 `bg_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.
+ *
+ * `bg_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 `bg_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`), `bg_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, `bg_wait` degrades to pure
+ * polling.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { listBackgroundWorkWakeChannels, snapshotBackgroundWork, } from "../../api/background-work.js";
+import { formatAsyncRunList, listAsyncRuns } from "./async-status.js";
+import { DIRS, INTERCOM_DETACH_REQUEST_EVENT, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_RESULT_INTERCOM_EVENT, } from "../../shared/types.js";
+import { nestedRunScope } from "../shared/nested-events.js";
+import { formatDuration, shortenPath } from "../../shared/formatters.js";
+import { toAgentToolUsage } from "../../shared/utils.js";
+import { collectWaitCompletions } from "./wait-completions.js";
+import { formatResumeFirstFailedRunsNote } from "./resume-guidance.js";
+import { formatTimeoutRecoveryLines } from "../shared/mutation-evidence.js";
+export { WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV, 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 = [
+    INTERCOM_DETACH_REQUEST_EVENT,
+    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) {
+    const sessionId = deps.state.currentSessionId;
+    if (!sessionId || !deps.state.foregroundRuns)
+        return [];
+    const runs = [...deps.state.foregroundRuns.values()].filter((run) => run.sessionId === sessionId && run.children.some((child) => child.status === "detached"));
+    if (params.id)
+        return runs.filter((run) => run.runId === params.id || run.runId.startsWith(params.id));
+    return params.all === true ? runs : [];
+}
+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(", ");
+}
+function foregroundChildrenNeedingAttention(run, indices) {
+    return run.children.filter((child) => indices.has(child.index) && child.status === "detached" && child.activityState === "needs_attention" && child.currentTool === "contact_supervisor");
+}
+function formatForegroundAttention(run, children, elapsedMs) {
+    const childList = children.map((child) => `${child.agent}${child.index !== undefined ? `#${child.index}` : ""}`).join(", ");
+    return result(`Waited ${formatDuration(elapsedMs)} for remembered detached foreground run "${run.runId}"; attention required. ${children.length} child run(s) need attention: ${childList}. Reply to any pending supervisor request, then call bg_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`);
+}
+/** A running run that has flagged it needs the parent's attention. */
+function needsAttention(run) {
+    return run.activityState === "needs_attention" || run.steps.some((step) => step.activityState === "needs_attention");
+}
+function hasSupervisorTool(run) {
+    return run.currentTool === "contact_supervisor"
+        || run.currentTool === "intercom"
+        || run.steps.some((step) => step.currentTool === "contact_supervisor" || step.currentTool === "intercom");
+}
+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("bg_wait requires an active session identity to scope background work safely.");
+    return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
+}
+export function waitRunScopes(deps) {
+    return [
+        { asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results },
+        ...(deps.nestedRootRunId ? [nestedRunScope(deps.nestedRootRunId)] : []),
+    ];
+}
+function collectScopedCompletions(terminal, deps, references) {
+    const completions = waitRunScopes(deps).flatMap((scope) => collectWaitCompletions(terminal.filter((run) => path.resolve(path.dirname(run.asyncDir)) === path.resolve(scope.asyncDirRoot)), deps.state, scope.resultsDir, (reference) => references.push(reference)) ?? []);
+    return completions.length ? completions : undefined;
+}
+/** Immediate-session runs only; named lookups can also recover already-terminal results. */
+function runsForSession(params, deps, activeOnly = true) {
+    const runs = waitRunScopes(deps).flatMap(({ asyncDirRoot, resultsDir }) => listAsyncRuns(asyncDirRoot, {
+        states: activeOnly ? [...ACTIVE_STATES] : undefined,
+        sessionId: deps.state.currentSessionId ?? undefined,
+        resultsDir,
+        kill: deps.kill,
+        now: deps.now,
+        includeNested: false,
+        ...(params.id ? { runId: params.id } : {}),
+    }));
+    return params.id ? runs.filter((run) => matchesId(run, params.id)) : runs;
+}
+function activeRunsForSession(params, deps) {
+    return runsForSession(params, deps);
+}
+/** 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));
+}
+/** Exact initial runs in any state, for the final summary. */
+function runsForIds(runIds, deps) {
+    return waitRunScopes(deps).flatMap(({ asyncDirRoot, resultsDir }) => [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
+        sessionId: deps.state.currentSessionId ?? undefined,
+        resultsDir,
+        kill: deps.kill,
+        now: deps.now,
+        includeNested: false,
+        runId,
+        exactRunId: true,
+    })));
+}
+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) {
+        const count = counts[run.state];
+        if (count !== undefined)
+            counts[run.state] = count + 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 completionUsage(completions) {
+    if (!completions?.length)
+        return undefined;
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+    let projected = false;
+    for (const completion of completions) {
+        for (const child of completion.results ?? []) {
+            if (!child.usage || (child.usage.input === 0 && child.usage.output === 0 && child.usage.cacheRead === 0 && child.usage.cacheWrite === 0 && child.usage.cost === 0 && child.usage.turns === 0))
+                continue;
+            projected = true;
+            usage.input += child.usage.input;
+            usage.output += child.usage.output;
+            usage.cacheRead += child.usage.cacheRead;
+            usage.cacheWrite += child.usage.cacheWrite;
+            usage.cost += child.usage.cost;
+            usage.turns += child.usage.turns;
+        }
+    }
+    return projected ? usage : undefined;
+}
+function result(text, isError = false, completions) {
+    const usage = completionUsage(completions);
+    for (const completion of completions ?? []) {
+        if (completion.workflowReceiptPath)
+            text += `\nWorkflow receipt [${completion.runId}]: ${completion.workflowReceiptPath}`;
+    }
+    return {
+        content: [{ type: "text", text }],
+        ...(isError ? { isError: true } : {}),
+        ...(usage ? { usage: toAgentToolUsage(usage) } : {}),
+        details: {
+            mode: "management",
+            results: [],
+            ...(completions && completions.length > 0 ? { completions } : {}),
+        },
+    };
+}
+function formatCompletionRecovery(completions) {
+    const lines = (completions ?? []).flatMap((completion) => (completion.results ?? []).flatMap((child) => formatTimeoutRecoveryLines(child.timeoutRecovery)));
+    return lines.length > 0 ? `\n${lines.join("\n")}` : "";
+}
+function windowElapsedResult(text, activeRunIds, activeProviderItems = []) {
+    return {
+        content: [{ type: "text", text }],
+        details: {
+            mode: "management",
+            results: [],
+            wait: {
+                reason: "window_elapsed",
+                timedOut: true,
+                activeRunIds,
+                activeProviderItems: activeProviderItems.map(({ provider, id }) => ({ provider, id })),
+            },
+        },
+    };
+}
+function supervisorYieldResult(activeRunIds, activeProviderItems = []) {
+    return {
+        content: [{ type: "text", text: "Wait yielded for a pending supervisor request. Background work remains active and will continue after the supervisor reply." }],
+        details: {
+            mode: "management",
+            results: [],
+            wait: {
+                reason: "supervisor_request",
+                timedOut: false,
+                activeRunIds,
+                activeProviderItems: activeProviderItems.map(({ provider, id }) => ({ provider, id })),
+            },
+        },
+    };
+}
+function supervisorYieldForScope(scope, params, deps, nowMs) {
+    try {
+        const activeAsyncIds = new Set(activeRunsForSession(params.id ? { id: params.id } : {}, deps).map((run) => run.id));
+        const activeRunIds = new Set([...scope.asyncRunIds].filter((id) => activeAsyncIds.has(id)));
+        for (const initial of scope.foregroundRuns) {
+            const current = deps.state.foregroundRuns?.get(initial.runId);
+            if (!current || current.sessionId !== initial.sessionId)
+                continue;
+            if (current.children.some((child) => initial.detachedIndices.has(child.index) && child.status === "detached"))
+                activeRunIds.add(initial.runId);
+        }
+        const activeProviderItems = scope.providerIds.size > 0
+            ? backgroundWorkForSession(deps, nowMs).items.filter((item) => scope.providerIds.has(backgroundWorkIdentity(item)))
+            : [];
+        return supervisorYieldResult([...activeRunIds], activeProviderItems);
+    }
+    catch (error) {
+        return result(error instanceof Error ? error.message : String(error), true);
+    }
+}
+/** Build the live status shown while async work keeps bg_wait blocked. */
+function asyncWaitUpdate(runs, providerCount, elapsedMs) {
+    const activity = runs.flatMap((run) => {
+        const activeSteps = run.steps.filter((step) => step.status === "pending" || step.status === "running");
+        if (activeSteps.length === 0) {
+            return [`${run.id}: ${run.state}`];
+        }
+        return activeSteps.map((step) => {
+            const current = step.currentTool ?? (step.status === "pending" ? "queued" : "thinking…");
+            return `${step.agent}: ${current}${step.currentPath ? ` ${shortenPath(step.currentPath)}` : ""}`;
+        });
+    });
+    const headline = [
+        `Waiting ${formatDuration(elapsedMs)} for ${runs.length} async run(s) and ${providerCount} provider item(s).`,
+        ...activity,
+    ].join(" · ");
+    return result([headline, runs.length > 0 ? formatAsyncRunList(runs) : ""].filter(Boolean).join("\n"));
+}
+const TRANSCRIPT_TAIL_BYTES = 128 * 1024;
+const TRANSCRIPT_PREVIEW_LINES = 3;
+const TRANSCRIPT_PREVIEW_WIDTH = 220;
+function compactTranscriptText(value, maxWidth = TRANSCRIPT_PREVIEW_WIDTH) {
+    if (typeof value !== "string")
+        return undefined;
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (!compact)
+        return undefined;
+    return compact.length <= maxWidth ? compact : `${compact.slice(0, Math.max(1, maxWidth - 1))}…`;
+}
+function readTranscriptActivity(transcriptPath) {
+    if (!transcriptPath)
+        return undefined;
+    let fd;
+    try {
+        const stat = fs.statSync(transcriptPath);
+        if (!stat.isFile() || stat.size <= 0)
+            return undefined;
+        const start = Math.max(0, stat.size - TRANSCRIPT_TAIL_BYTES);
+        const length = stat.size - start;
+        const buffer = Buffer.allocUnsafe(length);
+        fd = fs.openSync(transcriptPath, "r");
+        const bytesRead = fs.readSync(fd, buffer, 0, length, start);
+        let lines = buffer.subarray(0, bytesRead).toString("utf-8").split(/\r?\n/);
+        if (start > 0)
+            lines = lines.slice(1); // The first tail line may be partial JSON.
+        let currentTool;
+        let currentToolArgs;
+        let latestAt;
+        const recent = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                continue; // Concurrent append can leave the final line temporarily incomplete.
+            }
+            if (typeof record.ts === "number" && Number.isFinite(record.ts))
+                latestAt = record.ts;
+            if (record.recordType === "tool_start" && typeof record.toolName === "string") {
+                currentTool = record.toolName;
+                currentToolArgs = compactTranscriptText(record.argsPreview, 140);
+                const preview = currentToolArgs ? `${currentTool}: ${currentToolArgs}` : currentTool;
+                recent.push(`tool: ${preview}`);
+                continue;
+            }
+            if (record.recordType === "tool_end") {
+                currentTool = undefined;
+                currentToolArgs = undefined;
+                continue;
+            }
+            if (record.recordType === "message") {
+                if (record.sourceEventType === "initial_prompt" || record.role === "user")
+                    continue;
+                const text = compactTranscriptText(record.text);
+                if (text)
+                    recent.push(`${typeof record.role === "string" ? record.role : "message"}: ${text}`);
+                continue;
+            }
+            if (record.recordType === "stdout" || record.recordType === "stderr") {
+                const text = compactTranscriptText(record.text);
+                if (text)
+                    recent.push(`${record.recordType}: ${text}`);
+            }
+        }
+        return { currentTool, currentToolArgs, latestAt, recent: recent.slice(-TRANSCRIPT_PREVIEW_LINES) };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* best-effort close */ }
+        }
+    }
+}
+function detachedForegroundWaitUpdate(run, pendingIndices, nowMs, elapsedMs) {
+    const lines = [`Waiting for detached foreground run "${run.runId}" · ${formatDuration(elapsedMs)}`];
+    for (const child of run.children) {
+        if (!pendingIndices.has(child.index) || child.status !== "detached")
+            continue;
+        const activity = readTranscriptActivity(child.transcriptPath);
+        const age = activity?.latestAt !== undefined ? ` · activity ${formatDuration(Math.max(0, nowMs - activity.latestAt))} ago` : "";
+        lines.push(`${child.agent} · working after supervisor handoff${age}`);
+        if (activity?.currentTool) {
+            lines.push(`  current: ${activity.currentTool}${activity.currentToolArgs ? `: ${activity.currentToolArgs}` : ""}`);
+        }
+        for (const preview of activity?.recent ?? [])
+            lines.push(`  ${preview}`);
+        if (!activity && child.transcriptPath)
+            lines.push("  live transcript has no new activity yet");
+        if (!child.transcriptPath)
+            lines.push("  live transcript unavailable; waiting for completion event");
+    }
+    return result(lines.join("\n"));
+}
+async function waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield) {
+    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. Reply to any pending supervisor request before resuming or launching a replacement.`, 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);
+        }
+        if (deps.hasPendingSupervisorRequest?.())
+            return supervisorYield();
+        const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
+        const attention = foregroundChildrenNeedingAttention(current, initialDetachedIndices);
+        if (attention.length > 0)
+            return formatForegroundAttention(current, attention, now() - startedAt);
+        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.`);
+        }
+        const updateNow = now();
+        deps.onUpdate?.(detachedForegroundWaitUpdate(current, initialDetachedIndices, updateNow, updateNow - startedAt));
+        if (signal?.aborted) {
+            return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run "${run.runId}" remains detached. Reply to any pending supervisor request before resuming or launching a replacement.`, true);
+        }
+        if (now() - startedAt >= timeoutMs) {
+            return windowElapsedResult(`Wait window elapsed after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call bg_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`, [run.runId]);
+        }
+        await waitForWake(pollIntervalMs, signal, deps);
+    }
+}
+async function waitForSessionDetachedForegroundRuns(runs, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield) {
+    const texts = [];
+    for (const run of runs) {
+        const one = await waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
+        if (one.isError)
+            return one;
+        if (one.details.wait?.reason === "supervisor_request")
+            return one;
+        if (one.details.wait?.reason === "window_elapsed") {
+            const activeRunIds = runs.filter((initial) => {
+                const current = deps.state.foregroundRuns?.get(initial.runId);
+                if (!current || current.sessionId !== initial.sessionId)
+                    return false;
+                return initial.children.some((child) => child.status === "detached"
+                    && current.children.some((candidate) => candidate.index === child.index && candidate.status === "detached"));
+            }).map((activeRun) => activeRun.runId);
+            return windowElapsedResult(one.content.map((part) => part.type === "text" ? part.text : "").join("\n"), activeRunIds);
+        }
+        texts.push(one.content.map((part) => part.type === "text" ? part.text : "").join("\n").trim());
+    }
+    return result(texts.filter(Boolean).join("\n") || `Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run(s); done.`);
+}
+/**
+ * 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("bg_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("bg_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
+        : deps.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const startedAt = now();
+    const sessionId = deps.state.currentSessionId;
+    const waitForAll = params.id ? true : params.all === true;
+    if (params.nonBlocking && !params.id) {
+        return result("Non-blocking wait subscriptions require id so the registration can bind one exact run identity.", true);
+    }
+    if (params.nonBlocking && params.all) {
+        return result("nonBlocking cannot be combined with all; subscribe to one exact run id.", true);
+    }
+    let active;
+    let foreground;
+    let providerSnapshot;
+    try {
+        active = runsForSession(params, deps, !params.id);
+        foreground = activeDetachedForegroundRuns(params, deps).map((run) => ({
+            ...run,
+            children: run.children.map((child) => ({ ...child })),
+        }));
+        providerSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);
+    }
+    catch (error) {
+        return result(error instanceof Error ? error.message : String(error), true);
+    }
+    let selectedForeground;
+    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} runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
+        }
+        const selected = matches[0];
+        if (selected?.kind === "async" && !ACTIVE_STATES.includes(selected.run.state)) {
+            try {
+                const references = [];
+                const completions = collectScopedCompletions([selected.run], deps, references);
+                return result(`Run "${selected.id}" is terminal. Outcome: ${summarizeTerminalRuns([selected.run])}.${formatCompletionRecovery(completions)}${references.length ? `\n${references.join("\n")}` : ""}`, deps.failOnFailedRuns === true && (selected.run.state === "failed" || selected.run.state === "partial"), completions);
+            }
+            catch (error) {
+                return result(error instanceof Error ? error.message : String(error), true);
+            }
+        }
+        if (selected && params.nonBlocking) {
+            if (!deps.subscribe) {
+                return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking bg_wait calls.", true);
+            }
+            try {
+                const registration = deps.subscribe({ targetKind: selected.kind, runId: selected.id, requestedId: params.id, timeoutMs });
+                return result(`Armed wait subscription ${registration.token} for exact ${selected.kind} run ${selected.id}. Returning immediately; this session will be woken on completion, failure, attention, reconciliation failure, or timeout. Inspect armed subscriptions with subagent({ action: "status" }).`);
+            }
+            catch (error) {
+                return result(error instanceof Error ? error.message : String(error), true);
+            }
+        }
+        selectedForeground = selected?.kind === "foreground" ? selected.run : undefined;
+        active = selected?.kind === "async" ? [selected.run] : [];
+    }
+    let providerActive = providerSnapshot.items;
+    const scopedForeground = selectedForeground ? [selectedForeground] : params.id ? [] : foreground;
+    const initialAsyncIds = new Set(active.map((run) => run.id));
+    const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+    const initialScope = {
+        asyncRunIds: initialAsyncIds,
+        foregroundRuns: scopedForeground.map((run) => ({
+            runId: run.runId,
+            sessionId: run.sessionId,
+            detachedIndices: new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index)),
+        })),
+        providerIds: initialProviderIds,
+    };
+    const supervisorYield = () => supervisorYieldForScope(initialScope, params, deps, now());
+    if (selectedForeground) {
+        return waitForDetachedForegroundRun(selectedForeground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
+    }
+    if (active.length === 0 && providerActive.length === 0) {
+        if (waitForAll && !params.id && foreground.length > 0) {
+            return waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
+        }
+        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 initialProviderNames = new Set(providerActive.map((item) => item.provider));
+    const initialCount = initialAsyncIds.size + initialProviderIds.size;
+    const stopOnAttention = params.stopOnAttention ?? deps.stopOnAttention !== false;
+    let attention = active.filter((run) => needsAttention(run));
+    let supervisorBarrier = false;
+    const isDone = () => {
+        if (deps.hasPendingSupervisorRequest?.()) {
+            supervisorBarrier = true;
+            return true;
+        }
+        if (attention.some((run) => initialAsyncIds.has(run.id) && (stopOnAttention || hasSupervisorTool(run))))
+            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(", ");
+        deps.onUpdate?.(asyncWaitUpdate(activeInitialRuns, activeInitialProviderItems.length, now() - startedAt));
+        if (signal?.aborted) {
+            return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);
+        }
+        if (now() - startedAt >= timeoutMs) {
+            return windowElapsedResult(`Wait window elapsed after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call bg_wait again or inspect subagent status.`, activeInitialRuns.map((run) => run.id), activeInitialProviderItems);
+        }
+        try {
+            await waitForWake(pollIntervalMs, signal, deps);
+            if (deps.state.currentSessionId !== sessionId)
+                return result("Wait stopped because the active session changed.", true);
+            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 bg_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);
+        }
+    }
+    if (supervisorBarrier) {
+        return supervisorYield();
+    }
+    let terminalSummary;
+    let finishedAsyncCount;
+    let failedAsyncCount;
+    let completions;
+    let resumeGuidance = "";
+    const references = [];
+    const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
+    const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
+    try {
+        const allNow = runsForIds(initialAsyncIds, 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" || run.state === "partial").length;
+        terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
+        resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
+        completions = collectScopedCompletions(terminal, deps, references);
+    }
+    catch (error) {
+        return result(error instanceof Error ? error.message : String(error), true);
+    }
+    const relevantAttention = attention.filter((run) => initialAsyncIds.has(run.id));
+    const supervisorAttentionHint = relevantAttention.some(hasSupervisorTool)
+        ? " Reply to any pending supervisor request. If subagent_supervisor({ action: \"pending\" }) is empty, check intercom({ action: \"pending\" }) because an external intercom tool may own the request."
+        : "";
+    const attentionNote = relevantAttention.length > 0
+        ? ` ${relevantAttention.length} run(s) need attention: ${relevantAttention.map((run) => run.id).join(", ")} —${supervisorAttentionHint} inspect with subagent({ action: "status" }) then steer a top-level live async child, resume a paused/completed/failed child, or interrupt explicitly.`
+        : "";
+    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}.` : "";
+    const recoveryNote = formatCompletionRecovery(completions) + (references.length ? `\n${references.join("\n")}\n` : "");
+    if (waitForAll) {
+        const foregroundResult = !params.id && foreground.length > 0 && relevantAttention.length === 0
+            ? await waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield)
+            : undefined;
+        if (foregroundResult?.isError)
+            return foregroundResult;
+        if (foregroundResult?.details.wait?.reason === "supervisor_request")
+            return foregroundResult;
+        if (foregroundResult?.details.wait?.reason === "window_elapsed")
+            return foregroundResult;
+        const foregroundNote = foregroundResult
+            ? `\n${foregroundResult.content.map((part) => part.type === "text" ? part.text : "").join("\n")}`
+            : "";
+        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}${recoveryNote}${resumeGuidance}${attentionNote}${foregroundNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`, (deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0), completions);
+    }
+    const finishedCount = finishedAsyncCount + providerFinishedCount;
+    const subject = initialProviderIds.size === 0 ? "run(s)" : "item(s)";
+    const remainder = stillRunning > 0
+        ? ` ${stillRunning} ${subject} still in flight — call bg_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}${recoveryNote}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`, (deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0), completions);
+}
+//# sourceMappingURL=subagent-wait.js.map