pi-subagents 0.69.0 → 0.70.0

package/src/runs/background/subagent-wait.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `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 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_DEFAULT_TIMEOUT_MS_ENV, 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;
+    /** Arm a durable exact-run wake subscription and return immediately. Requires id. */
+    nonBlocking?: boolean;
+    /**
+     * When true, block until EVERY active run in this session (or matching `id`)
+     * is terminal. Default false: return when the first tracked run or provider
+     * item finishes or needs attention. Ignored when `id` targets a single run.
+     */
+    all?: boolean;
+    /** Give up after this many milliseconds. Defaults to waitTool.defaultTimeoutMs, then 30 minutes. */
+    timeoutMs?: number;
+    /** False keeps a blocking wait open through idle attention; supervisor/contact requests still stop the wait. */
+    stopOnAttention?: boolean;
+}
+/** 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;
+    /** Stream live wait status into Pi's pending tool row. */
+    onUpdate?: (result: AgentToolResult<Details>) => void;
+    asyncDirRoot?: string;
+    resultsDir?: string;
+    /** Root from the child's validated inherited route, not a tool argument. */
+    nestedRootRunId?: 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;
+    /** Configured blocking window used when the call omits timeoutMs. */
+    defaultTimeoutMs?: number;
+    /** 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;
+    /** Internal auto-drain mode surfaces actionable attention as an error. */
+    failOnAttention?: boolean;
+    /** Durable owned supervisor-request barrier used by headless auto-drain. */
+    hasPendingSupervisorRequest?: () => boolean;
+    /** Arm a durable exact-target wait subscription in a long-lived interactive runtime. */
+    subscribe?: (input: {
+        targetKind: "async" | "foreground";
+        runId: string;
+        requestedId: string;
+        timeoutMs: number;
+    }) => {
+        token: string;
+        expiresAt: number;
+    };
+    /** 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;
+}
+export declare function waitRunScopes(deps: Pick<SubagentWaitDeps, "asyncDirRoot" | "resultsDir" | "nestedRootRunId">): Array<{
+    asyncDirRoot: string;
+    resultsDir: string;
+}>;
+/**
+ * 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/src/runs/background/subagent-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-wait.d.ts","sourceRoot":"","sources":["../../../../src/runs/background/subagent-wait.ts"],"names":[],"mappings":"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"}