omnirush 0.8.3 → 0.8.5

package/assets/extensions/omnirush/agents-lib.ts

@@ -14,6 +14,12 @@
 //
 // Children get OMNIRUSH_PARENT_SESSION=<parent session id> in their
 // environment: a child process uploads nothing itself.
+//
+// A child has no wall-clock limit unless the caller sets one: it runs until
+// it is done. The only automatic stop is an inactivity watchdog (no output
+// at all for CHILD_INACTIVITY_MS, longer while a tool runs). AgentManager
+// runs children blocking or in the background and hands finished
+// background results back for delivery to the parent.
 
 import { spawn as nodeSpawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -22,8 +28,25 @@ import { mkdtemp, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
-/** Default per-child wall clock budget. */
-export const CHILD_TIMEOUT_MS = 10 * 60_000;
+/**
+ * Inactivity watchdog default: a child that prints nothing (no model
+ * stream, no tool event) for this long is treated as hung and stopped.
+ * There is no wall-clock limit by default (a child works as long as it
+ * needs); OMNIRUSH_AGENT_INACTIVITY_MINUTES overrides the window and 0
+ * turns the watchdog off.
+ */
+export const CHILD_INACTIVITY_MS = 30 * 60_000;
+/** While a child's tool call runs (a build, a polling `sleep`), its silence window is this many times longer. */
+export const TOOL_INACTIVITY_FACTOR = 4;
+
+/** The watchdog window from the environment (ms; 0 = off). */
+export function childInactivityMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = String(env.OMNIRUSH_AGENT_INACTIVITY_MINUTES ?? "").trim().toLowerCase();
+  if (!raw) return CHILD_INACTIVITY_MS;
+  if (raw === "off" || raw === "0") return 0;
+  const minutes = Number(raw);
+  return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60_000) : CHILD_INACTIVITY_MS;
+}
 /** Grace between SIGTERM and SIGKILL on timeout. */
 export const CHILD_KILL_GRACE_MS = 5_000;
 /** Per-child output cap in the structured result (bytes, UTF-8). */
@@ -133,10 +156,10 @@ export function buildChildArgs(
  * Write a role's system prompt to a private temp file and run `body`
  * with its path; the file is cleaned up afterwards either way.
  */
-export async function withRolePromptFile(
+export async function withRolePromptFile<T>(
   role: AgentRole,
-  body: (promptFilePath: string) => Promise<ChildResultInput>,
-): Promise<ChildResultInput> {
+  body: (promptFilePath: string) => Promise<T>,
+): Promise<T> {
   let dir: string | null = null;
   try {
     dir = await mkdtemp(path.join(tmpdir(), "omnirush-agent-"));
@@ -157,7 +180,7 @@ export interface ChildTask {
   model?: string;
 }
 
-export type ChildStatus = "completed" | "failed" | "timeout" | "cancelled";
+export type ChildStatus = "completed" | "failed" | "timeout" | "stalled" | "cancelled" | "interrupted";
 
 export interface ChildResult {
   role: AgentRole;
@@ -264,8 +287,25 @@ export function parseChildEvents(stdout: string): ParsedChildEvents {
 export interface SpawnChildOptions {
   cwd: string;
   parentSessionId: string;
+  /**
+   * Explicit wall-clock limit (the tool's `timeout_minutes`). Undefined =
+   * none: a child runs until it is done, stalls (inactivityMs) or is
+   * cancelled.
+   */
   timeoutMs?: number;
-  /** Kill the child when this fires (the tool's cancellation signal). */
+  /**
+   * Inactivity watchdog: a child that prints no event for this long is
+   * treated as hung and killed (status "stalled"). While one of its tools
+   * is running (a long build, a `sleep` poll), the window is
+   * TOOL_INACTIVITY_FACTOR times longer. Default: childInactivityMs(env);
+   * 0 disables the watchdog.
+   */
+  inactivityMs?: number;
+  /**
+   * Kill the child when this fires (cancellation). An abort whose reason is
+   * "interrupted" (the session ended under it) reports status
+   * "interrupted"; any other abort reports "cancelled".
+   */
   signal?: AbortSignal;
   /** Grace between SIGTERM and SIGKILL when killing (default CHILD_KILL_GRACE_MS). */
   killGraceMs?: number;
@@ -273,23 +313,52 @@ export interface SpawnChildOptions {
   now?: () => number;
   /** Progress callback: partial output lines as the child runs. */
   onChildStdout?: (role: AgentRole, chunk: string) => void;
+  /** Every sign of life from the child (any output), with its event types. */
+  onActivity?: (activity: ChildActivity) => void;
   /** The child's session id (a fresh UUID by default). */
   sessionId?: string;
 }
 
+export interface ChildActivity {
+  at: number;
+  /** Assistant messages finished so far. */
+  turns: number;
+  /** Tool calls running right now. */
+  toolsRunning: number;
+}
+
 /**
- * Run ONE child agent to completion (or timeout/cancellation). The
- * child inherits the parent's environment plus OMNIRUSH_PARENT_SESSION.
- * On timeout: SIGTERM, a short grace, then SIGKILL; whatever the child
- * printed so far is kept as the partial result.
+ * The collector reaches the running sub-agents through this global (it must
+ * stop them before its last capture; pi runs its session_shutdown handler
+ * before the agents extension's).
+ */
+export const AGENTS_HOOK = Symbol.for("omnirush.agents");
+export interface AgentsHook {
+  /** Stop every unfinished child (of one session, or all); resolves with them once they exited. */
+  interruptAll(parentSessionId?: string): Promise<Array<{ sessionId: string; id: string; role: string }>>;
+}
+
+/** Reason passed to AbortController.abort() when the session ends under a child. */
+export const INTERRUPTED_REASON = "interrupted";
+
+/**
+ * Run ONE child agent to completion. No wall-clock limit unless the caller
+ * sets timeoutMs; the only automatic kill is the inactivity watchdog (a
+ * child silent for the whole window). The child inherits the parent's
+ * environment plus OMNIRUSH_PARENT_SESSION. On a kill: SIGTERM, a short
+ * grace, then SIGKILL; whatever the child printed so far is kept as the
+ * partial result.
  */
 export async function runChildAgent(
   task: ChildTask,
   options: SpawnChildOptions,
 ): Promise<ChildResult> {
-  const preset = ROLE_PRESETS[task.role] ?? ROLE_PRESETS["general-worker"];
-  const startedAt = (options.now ?? Date.now)();
-  const timeoutMs = Math.max(1_000, options.timeoutMs ?? CHILD_TIMEOUT_MS);
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  const timeoutMs = typeof options.timeoutMs === "number" && options.timeoutMs > 0
+    ? Math.max(1_000, options.timeoutMs)
+    : null;
+  const inactivityMs = options.inactivityMs ?? childInactivityMs();
   const spawnImpl = options.spawnImpl ?? nodeSpawn;
   const sessionId = options.sessionId ?? randomUUID();
 
@@ -300,8 +369,14 @@ export async function runChildAgent(
     return await new Promise<ChildResult>((resolvePromise) => {
       let stdout = "";
       let stderr = "";
+      let pendingLine = "";
       let settled = false;
-      let killedFor: "timeout" | "cancelled" | null = null;
+      let killedFor: "timeout" | "stalled" | "cancelled" | "interrupted" | null = null;
+      let turns = 0;
+      const toolsRunning = new Set<string>();
+      let lastActivity = now();
+      let watchdog: ReturnType<typeof setTimeout> | null = null;
+      let timer: ReturnType<typeof setTimeout> | null = null;
 
       const child = spawnImpl(invocation.command, invocation.args, {
         cwd: options.cwd,
@@ -316,13 +391,12 @@ export async function runChildAgent(
       const finish = (input: ChildResultInput) => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
+        if (timer) clearTimeout(timer);
+        if (watchdog) clearTimeout(watchdog);
         if (options.signal && abortHandler) {
           options.signal.removeEventListener("abort", abortHandler);
         }
-        resolvePromise(
-          buildChildResult(task, input, (options.now ?? Date.now)() - startedAt, sessionId),
-        );
+        resolvePromise(buildChildResult(task, input, now() - startedAt, sessionId));
       };
 
       const killTree = () => {
@@ -340,32 +414,68 @@ export async function runChildAgent(
         }, Math.max(50, options.killGraceMs ?? CHILD_KILL_GRACE_MS)).unref?.();
       };
 
-      const timer = setTimeout(() => {
-        if (settled) return;
-        killedFor = "timeout";
+      const kill = (reason: NonNullable<typeof killedFor>) => {
+        if (settled || killedFor) return;
+        killedFor = reason;
         killTree();
-      }, timeoutMs);
-      timer.unref?.();
+      };
+
+      // The watchdog re-arms on every sign of life; it fires only after a
+      // full window of silence (longer while a tool is running).
+      const armWatchdog = () => {
+        if (!(inactivityMs > 0) || settled || killedFor) return;
+        if (watchdog) clearTimeout(watchdog);
+        const window = toolsRunning.size > 0 ? inactivityMs * TOOL_INACTIVITY_FACTOR : inactivityMs;
+        watchdog = setTimeout(() => kill("stalled"), window);
+        watchdog.unref?.();
+      };
+      const alive = () => {
+        lastActivity = now();
+        armWatchdog();
+        options.onActivity?.({ at: lastActivity, turns, toolsRunning: toolsRunning.size });
+      };
+      armWatchdog();
+
+      if (timeoutMs !== null) {
+        timer = setTimeout(() => kill("timeout"), timeoutMs);
+        timer.unref?.();
+      }
 
       const abortHandler = options.signal
-        ? () => {
-            if (settled) return;
-            killedFor = "cancelled";
-            killTree();
-          }
+        ? () => kill(options.signal?.reason === INTERRUPTED_REASON ? "interrupted" : "cancelled")
         : null;
       if (options.signal && abortHandler) {
         if (options.signal.aborted) abortHandler();
         else options.signal.addEventListener("abort", abortHandler, { once: true });
       }
 
+      // Tool calls in flight and finished turns, from the event lines.
+      const observe = (line: string) => {
+        if (!line.includes('"type"')) return;
+        let event: any;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          return;
+        }
+        if (event?.type === "tool_execution_start" && typeof event.toolCallId === "string") toolsRunning.add(event.toolCallId);
+        else if (event?.type === "tool_execution_end" && typeof event.toolCallId === "string") toolsRunning.delete(event.toolCallId);
+        else if (event?.type === "message_end" && event.message?.role === "assistant") turns += 1;
+      };
+
       child.stdout?.on("data", (chunk: Buffer | string) => {
         const text = String(chunk);
         stdout += text;
+        const lines = (pendingLine + text).split("\n");
+        pendingLine = lines.pop() ?? "";
+        for (const line of lines) observe(line);
+        alive();
         options.onChildStdout?.(task.role, text);
       });
       child.stderr?.on("data", (chunk: Buffer | string) => {
         stderr += String(chunk);
+        if (stderr.length > 256 * 1024) stderr = stderr.slice(-64 * 1024);
+        alive();
       });
       child.on("error", (error: Error) => {
         finish({
@@ -376,26 +486,18 @@ export async function runChildAgent(
           error: `failed to start: ${error.message}`,
         });
       });
-      child.on("close", (code: number | null, signalName: string | null) => {
+      child.on("close", (code: number | null) => {
         const parsed = parseChildEvents(stdout);
-        if (killedFor === "timeout") {
-          finish({
-            exitCode: code,
-            finalText: parsed.finalText,
-            turns: parsed.turns,
-            status: "timeout",
-            error: `timed out after ${Math.round(timeoutMs / 60_000)} min${parsed.finalText ? " — partial result kept" : ""}`,
-          });
-          return;
-        }
-        if (killedFor === "cancelled") {
-          finish({
-            exitCode: code,
-            finalText: parsed.finalText,
-            turns: parsed.turns,
-            status: "cancelled",
-            error: "cancelled by the parent session",
-          });
+        const partial = parsed.finalText ? " — partial result kept" : "";
+        if (killedFor) {
+          const error = killedFor === "timeout"
+            ? `timed out after ${formatMinutes(timeoutMs ?? 0)}${partial}`
+            : killedFor === "stalled"
+              ? `stopped: no activity for ${formatMinutes(toolsRunning.size > 0 ? inactivityMs * TOOL_INACTIVITY_FACTOR : inactivityMs)}${partial}`
+              : killedFor === "interrupted"
+                ? `interrupted: the parent session ended${partial}`
+                : `cancelled by the parent session${partial}`;
+          finish({ exitCode: code, finalText: parsed.finalText, turns: parsed.turns, status: killedFor, error });
           return;
         }
         finish({
@@ -405,12 +507,17 @@ export async function runChildAgent(
           status: code === 0 ? "completed" : "failed",
           ...(code !== 0 && !parsed.finalText && stderr.trim() ? { error: stderr.trim().slice(-500) } : {}),
         });
-        void signalName;
       });
     });
   });
 }
 
+function formatMinutes(ms: number): string {
+  const minutes = ms / 60_000;
+  if (minutes >= 1) return `${Math.round(minutes * 10) / 10} min`;
+  return `${Math.max(1, Math.round(ms / 1000))} s`;
+}
+
 /**
  * Run tasks with a concurrency cap, preserving input order in the
  * results (ports the pi subagent example's mapWithConcurrencyLimit).
@@ -436,14 +543,366 @@ export async function mapWithConcurrency<TIn, TOut>(
 }
 
 /** Structured result text for the parent model (one section per child). */
-export function renderChildResults(results: ChildResult[]): string {
+export function renderChildResults(results: ChildResult[], ids?: readonly string[]): string {
   const succeeded = results.filter((result) => result.status === "completed").length;
-  const sections = results.map((result) => {
+  const sections = results.map((result, index) => {
     const minutes = Math.round((result.durationMs / 60_000) * 10) / 10;
-    const header = `### ${result.role}${result.model ? ` [${result.model}]` : ""} — ${result.status} (${minutes} min${result.outputTruncated ? ", output capped" : ""})`;
+    const header = `### ${ids?.[index] ? `${ids[index]} ` : ""}${result.role}${result.model ? ` [${result.model}]` : ""} — ${result.status} (${minutes} min${result.outputTruncated ? ", output capped" : ""})`;
     const meta: string[] = [`task: ${result.task}`];
     if (result.error) meta.push(`error: ${result.error}`);
     return `${header}\n${meta.join("\n")}\n\n${result.output || "(no output)"}`;
   });
   return `spawn_agents: ${succeeded}/${results.length} completed\n\n${sections.join("\n\n---\n\n")}`;
 }
+
+// --- sub-agent manager: blocking and background dispatch --------------------
+
+export type AgentState = "queued" | "running" | ChildStatus;
+
+/** One sub-agent of a session, running or finished. */
+export interface AgentRecord {
+  /** Short handle the model uses with the agents_* tools ("a1", "a2", ...). */
+  id: string;
+  /** The spawn_agents call it came from ("b1", ...). */
+  batch: string;
+  parentSessionId: string;
+  /** The child's pi session id (its trace is captured under it). */
+  sessionId: string;
+  role: AgentRole;
+  task: string;
+  model?: string;
+  /** Dispatched with wait:false: its result comes back as a message. */
+  background: boolean;
+  /** Background delivery: one message per child, or one per batch. */
+  notify: "each" | "batch";
+  status: AgentState;
+  queuedAt: number;
+  startedAt: number | null;
+  finishedAt: number | null;
+  lastActivityAt: number;
+  turns: number;
+  toolsRunning: number;
+  result: ChildResult | null;
+  /** Its result reached the model (tool result or delivered message). */
+  delivered: boolean;
+  controller: AbortController;
+  done: Promise<ChildResult>;
+}
+
+export type AgentRunner = (
+  task: ChildTask,
+  options: {
+    sessionId: string;
+    parentSessionId: string;
+    signal: AbortSignal;
+    onActivity: (activity: ChildActivity) => void;
+    /** The call's explicit timeout_minutes, if any. */
+    timeoutMs?: number;
+    cwd?: string;
+  },
+) => Promise<ChildResult>;
+
+export interface DispatchOptions {
+  background: boolean;
+  /** Children running at once (default: all of them). */
+  concurrency?: number;
+  notify?: "each" | "batch";
+  /** Blocking calls: the tool's signal cancels the children. */
+  signal?: AbortSignal;
+  /** A child settled (progress updates). */
+  onSettled?: (record: AgentRecord) => void;
+  /** Explicit wall-clock limit per child (none by default). */
+  timeoutMs?: number;
+  /** Workspace the children run in. */
+  cwd?: string;
+}
+
+/**
+ * Tracks every sub-agent of this process per parent session: runs them
+ * (through an injected runner), answers status/wait/result/cancel, and
+ * queues finished background results for delivery back to the parent
+ * (`takeDeliverable`, signalled through `onDeliverable`).
+ */
+export class AgentManager {
+  private readonly runner: AgentRunner;
+  private readonly now: () => number;
+  private readonly onDeliverable: () => void;
+  private readonly bySession = new Map<string, AgentRecord[]>();
+  private waiters: Array<{ records: AgentRecord[]; resolve: () => void }> = [];
+  private changeWaiters: Array<() => void> = [];
+  private readonly resolvers = new Map<AgentRecord, (result: ChildResult) => void>();
+  private nextAgent = 1;
+  private nextBatch = 1;
+
+  constructor(options: { run: AgentRunner; now?: () => number; onDeliverable?: () => void }) {
+    this.runner = options.run;
+    this.now = options.now ?? Date.now;
+    this.onDeliverable = options.onDeliverable ?? (() => undefined);
+  }
+
+  dispatch(
+    parentSessionId: string,
+    tasks: ChildTask[],
+    options: DispatchOptions,
+  ): { batch: string; records: AgentRecord[]; done: Promise<ChildResult[]> } {
+    const batch = `b${this.nextBatch++}`;
+    const list = this.bySession.get(parentSessionId) ?? [];
+    this.bySession.set(parentSessionId, list);
+    const at = this.now();
+    const records = tasks.map((task) => {
+      let resolveDone!: (result: ChildResult) => void;
+      const done = new Promise<ChildResult>((resolve) => { resolveDone = resolve; });
+      const record: AgentRecord = {
+        id: `a${this.nextAgent++}`,
+        batch,
+        parentSessionId,
+        sessionId: randomUUID(),
+        role: task.role,
+        task: task.task,
+        ...(task.model ? { model: task.model } : {}),
+        background: options.background,
+        notify: options.notify ?? "batch",
+        status: "queued",
+        queuedAt: at,
+        startedAt: null,
+        finishedAt: null,
+        lastActivityAt: at,
+        turns: 0,
+        toolsRunning: 0,
+        result: null,
+        // A blocking call returns its results itself.
+        delivered: !options.background,
+        controller: new AbortController(),
+        done,
+      };
+      this.resolvers.set(record, resolveDone);
+      list.push(record);
+      return record;
+    });
+    if (options.signal) {
+      const abort = () => { void this.cancel(records); };
+      if (options.signal.aborted) abort();
+      else options.signal.addEventListener("abort", abort, { once: true });
+    }
+    const concurrency = Math.max(1, Math.floor(options.concurrency ?? records.length));
+    void mapWithConcurrency(records, concurrency, async (record, index) => {
+      // Cancelled while it waited for a slot: it never starts.
+      if (!record.result) await this.start(record, tasks[index], options);
+      options.onSettled?.(record);
+    });
+    return { batch, records, done: Promise.all(records.map((record) => record.done)) };
+  }
+
+  private async start(record: AgentRecord, task: ChildTask, options: DispatchOptions): Promise<void> {
+    record.status = "running";
+    record.startedAt = this.now();
+    record.lastActivityAt = record.startedAt;
+    let result: ChildResult;
+    try {
+      result = await this.runner(task, {
+        sessionId: record.sessionId,
+        parentSessionId: record.parentSessionId,
+        signal: record.controller.signal,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        onActivity: (activity) => {
+          record.lastActivityAt = activity.at;
+          record.turns = activity.turns;
+          record.toolsRunning = activity.toolsRunning;
+        },
+      });
+    } catch (error) {
+      result = buildChildResult(task, {
+        exitCode: null,
+        finalText: "",
+        turns: record.turns,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      }, this.now() - (record.startedAt ?? this.now()), record.sessionId);
+    }
+    this.settle(record, result);
+  }
+
+  private settle(record: AgentRecord, result: ChildResult): void {
+    if (record.result) return;
+    record.result = result;
+    record.status = result.status;
+    record.finishedAt = this.now();
+    record.turns = result.turns;
+    record.toolsRunning = 0;
+    this.resolvers.get(record)?.(result);
+    this.resolvers.delete(record);
+    // Waiters first: what they return is delivered through their tool result.
+    const still: typeof this.waiters = [];
+    for (const waiter of this.waiters) {
+      if (waiter.records.every((candidate) => candidate.result)) {
+        waiter.records.forEach((candidate) => { candidate.delivered = true; });
+        waiter.resolve();
+      } else {
+        still.push(waiter);
+      }
+    }
+    this.waiters = still;
+    const changed = this.changeWaiters;
+    this.changeWaiters = [];
+    changed.forEach((resolve) => resolve());
+    if (record.background && !record.delivered) this.onDeliverable();
+  }
+
+  list(parentSessionId: string): AgentRecord[] {
+    return [...(this.bySession.get(parentSessionId) ?? [])];
+  }
+
+  /** Records by id (or all of the session's when `ids` is empty); unknown ids are listed apart. */
+  resolve(parentSessionId: string, ids: readonly string[] | undefined): { records: AgentRecord[]; unknown: string[] } {
+    const all = this.list(parentSessionId);
+    if (!ids || ids.length === 0 || ids.includes("all")) return { records: all, unknown: [] };
+    const records: AgentRecord[] = [];
+    const unknown: string[] = [];
+    for (const raw of ids) {
+      const id = String(raw).trim();
+      const record = all.find((candidate) => candidate.id === id || candidate.sessionId === id);
+      if (record && !records.includes(record)) records.push(record);
+      else if (!record) unknown.push(id);
+    }
+    return { records, unknown };
+  }
+
+  /** Children not finished yet (queued or running), of one session or of all. */
+  active(parentSessionId?: string): AgentRecord[] {
+    const lists = parentSessionId ? [this.list(parentSessionId)] : [...this.bySession.values()];
+    return lists.flat().filter((record) => !record.result);
+  }
+
+  /** Background results nobody has seen yet, of one session or of all. */
+  hasPending(parentSessionId?: string): boolean {
+    const lists = parentSessionId ? [this.list(parentSessionId)] : [...this.bySession.values()];
+    return lists.flat().some((record) => record.background && !record.delivered);
+  }
+
+  /**
+   * Finished background results ready to go back to the parent, grouped per
+   * delivery (a whole batch, or one child with notify "each"); marked
+   * delivered.
+   */
+  takeDeliverable(parentSessionId?: string): Array<{ parentSessionId: string; records: AgentRecord[] }> {
+    const out: Array<{ parentSessionId: string; records: AgentRecord[] }> = [];
+    const sessions = parentSessionId ? [parentSessionId] : [...this.bySession.keys()];
+    for (const session of sessions) {
+      const records = this.list(session).filter((record) => record.background);
+      const batches = new Map<string, AgentRecord[]>();
+      for (const record of records) batches.set(record.batch, [...(batches.get(record.batch) ?? []), record]);
+      for (const members of batches.values()) {
+        const ready = members.filter((record) => record.result && !record.delivered);
+        if (ready.length === 0) continue;
+        if (members[0].notify === "batch" && members.some((record) => !record.result)) continue;
+        ready.forEach((record) => { record.delivered = true; });
+        out.push({ parentSessionId: session, records: ready });
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Wait until every one of `records` finished, the wait's own limit passed
+   * or `signal` fired (the children keep running then). Finished ones are
+   * marked delivered: the caller returns them.
+   */
+  async wait(records: AgentRecord[], options: { signal?: AbortSignal; timeoutMs?: number } = {}): Promise<void> {
+    if (!records.every((record) => record.result)) {
+      await new Promise<void>((resolve) => {
+        let timer: ReturnType<typeof setTimeout> | null = null;
+        const waiter = {
+          records,
+          resolve: () => {
+            if (timer) clearTimeout(timer);
+            options.signal?.removeEventListener("abort", stop);
+            resolve();
+          },
+        };
+        const stop = () => {
+          this.waiters = this.waiters.filter((candidate) => candidate !== waiter);
+          waiter.resolve();
+        };
+        this.waiters.push(waiter);
+        if (options.timeoutMs && options.timeoutMs > 0) timer = setTimeout(stop, options.timeoutMs);
+        if (options.signal?.aborted) stop();
+        else options.signal?.addEventListener("abort", stop, { once: true });
+      });
+    }
+    records.filter((record) => record.result).forEach((record) => { record.delivered = true; });
+  }
+
+  /** Resolves at the next child that settles. */
+  changed(): Promise<void> {
+    return new Promise((resolve) => this.changeWaiters.push(resolve));
+  }
+
+  /** Stop children (SIGTERM, then SIGKILL) and wait for them to exit. */
+  async cancel(records: AgentRecord[], reason: string = "cancelled", options: { delivered?: boolean } = {}): Promise<void> {
+    const live = records.filter((record) => !record.result);
+    // The caller hands the results over itself: no delivery message.
+    if (options.delivered) live.forEach((record) => { record.delivered = true; });
+    for (const record of live) {
+      record.controller.abort(reason);
+      if (record.startedAt === null) {
+        // Still waiting for a slot: settled here, it never starts.
+        this.settle(record, buildChildResult(record, {
+          exitCode: null,
+          finalText: "",
+          turns: 0,
+          status: reason === INTERRUPTED_REASON ? "interrupted" : "cancelled",
+          error: "cancelled before it started",
+        }, 0, record.sessionId));
+      }
+    }
+    await Promise.all(live.map((record) => record.done));
+  }
+
+  /** The session ends: every unfinished child is interrupted; returns them once they exited. */
+  async interruptAll(parentSessionId?: string): Promise<AgentRecord[]> {
+    const live = this.active(parentSessionId);
+    // Nobody is left to read them.
+    await this.cancel(live, INTERRUPTED_REASON, { delivered: true });
+    return live;
+  }
+}
+
+/** Minutes, rounded for status lines. */
+function minutesOf(ms: number): number {
+  return Math.round((ms / 60_000) * 10) / 10;
+}
+
+/** One status line per sub-agent (agents_status, /agents). */
+export function renderAgentStatus(records: AgentRecord[], now: number = Date.now()): string {
+  if (records.length === 0) return "No sub-agents in this session.";
+  const lines = records.map((record) => {
+    const since = record.startedAt ?? record.queuedAt;
+    const elapsed = minutesOf((record.finishedAt ?? now) - since);
+    const bits = [`${record.id}`, `[${record.status}]`, record.role];
+    if (record.model) bits.push(`[${record.model}]`);
+    bits.push(record.background ? "background" : "blocking");
+    const detail: string[] = [`${elapsed} min`];
+    if (!record.result && record.startedAt) {
+      detail.push(`${record.turns} turns`);
+      if (record.toolsRunning > 0) detail.push("tool running");
+      detail.push(`last activity ${minutesOf(now - record.lastActivityAt)} min ago`);
+    }
+    if (record.result && !record.delivered) detail.push("result not yet read");
+    const task = record.task.length > 80 ? `${record.task.slice(0, 79)}…` : record.task;
+    return `- ${bits.join(" ")} (${detail.join(", ")}) — ${task}`;
+  });
+  const running = records.filter((record) => !record.result).length;
+  return `${records.length} sub-agents, ${running} running:\n${lines.join("\n")}`;
+}
+
+/** The message that brings finished background agents back to the parent. */
+export function renderDelivery(records: AgentRecord[]): string {
+  const results = records.map((record) => record.result).filter((result): result is ChildResult => Boolean(result));
+  const ids = records.map((record) => record.id).join(", ");
+  return [
+    `Background sub-agents finished (${ids}). Their results follow; continue your work with them.`,
+    "",
+    renderChildResults(results, records.map((record) => record.id)),
+  ].join("\n");
+}