@jaybeeuu/agent-cortex 1.20.0 → 1.38.1

package/extensions/subagent/index.ts

@@ -20,6 +20,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
+import { waitForAgents } from "./wait.ts";
 import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -1019,6 +1020,16 @@ export default function (pi: ExtensionAPI) {
 		cwd: string;
 	}
 
+	interface ReadAgentDetails {
+		agentId: string;
+		error?: string;
+		status?: string;
+		exitCode?: number;
+		usage?: UsageStats;
+		model?: string;
+		stopReason?: string;
+	}
+
 	const backgroundRuns = new Map<string, BackgroundRun>();
 
 	pi.registerTool({
@@ -1027,7 +1038,7 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Spawn a background sub-agent with the given prompt and return an agent ID immediately. " +
 			"This is the ONLY tool for spawning subagents — do not use bash or any other tool. " +
-			"Use the read_agent tool to retrieve the result when ready. " +
+			"Use wait_for_agents to block until results are ready, or read_agent to check a specific agent. " +
 			"Compatible with Copilot CLI's task/read_agent subagent model.",
 		parameters: Type.Object({
 			prompt: Type.String({ description: "Task prompt for the sub-agent to execute" }),
@@ -1050,43 +1061,48 @@ export default function (pi: ExtensionAPI) {
 
 			const entry: BackgroundRun = {
 				result: null,
-				promise: (async () => {
-					try {
-						const agents = [backgroundAgent, ...discoverAgents(ctx.cwd, "user").agents];
-						const result = await runSingleAgent(
-							cwd,
-							agents,
-							"background-agent",
-							params.prompt,
-							cwd,
-							undefined,
-							signal,
-							undefined,
-							(results: SingleResult[]) => ({
-								mode: "single" as const,
-								agentScope: "user" as AgentScope,
-								projectAgentsDir: null,
-								results,
-							}),
-						);
-						entry.result = result;
-					} catch (err) {
-						entry.result = {
-							agent: "background-agent",
-							agentSource: "user",
-							task: params.prompt,
-							exitCode: 1,
-							messages: [],
-							stderr: String(err),
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-						};
-					}
-				})(),
+				promise: Promise.resolve(),
 				startTime: Date.now(),
 				prompt: params.prompt,
 				cwd,
 			};
 
+			const run = (async () => {
+				try {
+					const agents = [backgroundAgent, ...discoverAgents(ctx.cwd, "user").agents];
+					const result = await runSingleAgent(
+						cwd,
+						agents,
+						"background-agent",
+						params.prompt,
+						cwd,
+						undefined,
+						signal,
+						undefined,
+						(results: SingleResult[]) => ({
+							mode: "single" as const,
+							agentScope: "user" as AgentScope,
+							projectAgentsDir: null,
+							results,
+						}),
+					);
+					entry.result = result;
+				} catch (err) {
+					entry.result = {
+						agent: "background-agent",
+						agentSource: "user",
+						task: params.prompt,
+						exitCode: 1,
+						messages: [],
+						stderr: String(err),
+						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+					};
+				}
+			})();
+			// Attach the real run promise after construction so the run's completion
+			// (entry.result committed before the promise settles) is what waiters race on.
+			entry.promise = run;
+
 			backgroundRuns.set(agentId, entry);
 
 			return {
@@ -1096,6 +1112,73 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "wait_for_agents",
+		label: "Wait for Background Agents",
+		description:
+			"Block until at least one background sub-agent spawned with the task tool completes. " +
+			"Takes an array of agentIds and an optional timeout; returns the results of every agent " +
+			"that has completed, and STILL RUNNING for agents that have not. " +
+			"Preserves parallelism: dispatch several tasks, then wait_for_agents returns as soon as " +
+			"any of them finishes. Use read_agent as a fallback to re-read a specific result.",
+		parameters: Type.Object({
+			agentIds: Type.Array(Type.String({ description: "Agent IDs returned by the task tool to wait on" })),
+			timeout: Type.Optional(
+				Type.Number({
+					description:
+						"Maximum seconds to block (default 120) before returning STILL RUNNING for unfinished agents",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const timeoutSeconds = params.timeout ?? 120;
+			const outcome = await waitForAgents(
+				(agentId) => backgroundRuns.get(agentId),
+				params.agentIds,
+				{ timeoutMs: timeoutSeconds * 1000, signal },
+			);
+
+			const lines: string[] = [];
+			if (outcome.aborted) lines.push("(aborted)");
+			if (outcome.timedOut) lines.push(`(timed out after ${timeoutSeconds}s)`);
+			if (lines.length > 0) lines.push("");
+
+			for (const { agentId, result } of outcome.completed) {
+				lines.push(`### ${agentId} — completed`);
+				lines.push(truncateParallelOutput(getResultOutput(result)));
+				lines.push("");
+			}
+			if (outcome.running.length > 0) {
+				lines.push(`### STILL RUNNING (${outcome.running.length})`);
+				lines.push(outcome.running.map((id) => `- ${id}`).join("\n"));
+				lines.push("");
+			}
+			if (outcome.notFound.length > 0) {
+				lines.push(`### NOT FOUND (${outcome.notFound.length})`);
+				lines.push(outcome.notFound.map((id) => `- ${id}`).join("\n"));
+			}
+
+			const summary = `completed: ${outcome.completed.length}, still running: ${outcome.running.length}, not found: ${outcome.notFound.length}`;
+			const body = lines.join("\n").trim();
+			return {
+				content: [{ type: "text", text: body ? `${summary}\n\n${body}` : summary }],
+				details: {
+					agentIds: params.agentIds,
+					completed: outcome.completed.map(({ agentId, result }) => ({
+						agentId,
+						exitCode: result.exitCode,
+						stopReason: result.stopReason,
+						output: truncateParallelOutput(getResultOutput(result)),
+					})),
+					running: outcome.running,
+					notFound: outcome.notFound,
+					timedOut: outcome.timedOut,
+					aborted: outcome.aborted,
+				},
+			};
+		},
+	});
+
 	pi.registerTool({
 		name: "read_agent",
 		label: "Read Background Agent Output",
@@ -1107,31 +1190,34 @@ export default function (pi: ExtensionAPI) {
 		}),
 		async execute(_toolCallId, params) {
 			const entry = backgroundRuns.get(params.agentId);
+			const details: ReadAgentDetails = {
+				agentId: params.agentId,
+				error: !entry ? "not found" : undefined,
+				status: entry && !entry.result ? "running" : undefined,
+				exitCode: entry?.result?.exitCode,
+				usage: entry?.result?.usage,
+				model: entry?.result?.model,
+				stopReason: entry?.result?.stopReason,
+			};
+
 			if (!entry) {
 				return {
 					content: [{ type: "text", text: `ERROR: No agent found with ID "${params.agentId}"` }],
-					details: { error: "not found", agentId: params.agentId },
+					details,
 				};
 			}
 
 			if (entry.result) {
-				const output = getResultOutput(entry.result);
 				return {
-					content: [{ type: "text", text: output }],
-					details: {
-						agentId: params.agentId,
-						exitCode: entry.result.exitCode,
-						usage: entry.result.usage,
-						model: entry.result.model,
-						stopReason: entry.result.stopReason,
-					},
+					content: [{ type: "text", text: getResultOutput(entry.result) }],
+					details,
 				};
 			}
 
-			// Still running — check if the promise is still active
+			// Still running — the wait_for_agents tool can block until it finishes.
 			return {
 				content: [{ type: "text", text: "STILL RUNNING" }],
-				details: { status: "running", agentId: params.agentId },
+				details,
 			};
 		},
 	});

package/extensions/subagent/node_modules/.bin/pi

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+else
+  exec node  "$basedir/../@earendil-works/pi-coding-agent/dist/cli.js" "$@"
+fi

package/extensions/subagent/node_modules/.bin/pi-ai

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-ai/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-ai/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/@earendil-works+pi-ai@0.78.1_ws@8.21.0_zod@4.4.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@earendil-works/pi-ai/dist/cli.js" "$@"
+else
+  exec node  "$basedir/../@earendil-works/pi-ai/dist/cli.js" "$@"
+fi

package/extensions/subagent/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/extensions/subagent/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/extensions/subagent/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/extensions/subagent/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@agent-cortex/subagent-tools",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm wait.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typebox": "^1.1.38",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/subagent/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/extensions/subagent/wait.test.ts

@@ -0,0 +1,202 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { waitForAgents, type BackgroundEntry } from "./wait.ts";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+interface Deferred {
+	promise: Promise<void>;
+	resolve: () => void;
+}
+
+function deferred(): Deferred {
+	let resolve!: () => void;
+	const promise = new Promise<void>((res) => {
+		resolve = res;
+	});
+	return { promise, resolve };
+}
+
+/**
+ * A background-run ledger matching the extension's `backgroundRuns` map:
+ * each entry holds a result (null while running) and a promise that resolves
+ * when the run finishes. `finish` mirrors the real run path — result is set
+ * before the promise settles.
+ */
+function makeLedger() {
+	const entries = new Map<string, { entry: BackgroundEntry<string>; done: Deferred }>();
+
+	const spawn: () => string = () => {
+		const agentId = `agent-${entries.size + 1}`;
+		const done = deferred();
+		const entry: BackgroundEntry<string> = {
+			result: null,
+			promise: done.promise,
+		};
+		entries.set(agentId, { entry, done });
+		return agentId;
+	};
+
+	const finish = async (agentId: string, result: string): Promise<void> => {
+		const run = entries.get(agentId);
+		if (!run) throw new Error(`no run for ${agentId}`);
+		// Match production ordering: result committed before the promise settles.
+		run.entry.result = result;
+		run.done.resolve();
+		await delay(0);
+	};
+
+	const finishLater = (agentId: string, result: string, ms: number): void => {
+		const run = entries.get(agentId);
+		if (!run) throw new Error(`no run for ${agentId}`);
+		void delay(ms).then(() => finish(agentId, result));
+	};
+
+	const get = (agentId: string): BackgroundEntry<string> | undefined => entries.get(agentId)?.entry;
+
+	return { spawn, finish, finishLater, get };
+}
+
+// ─── waitForAgents ────────────────────────────────────────────────────────────
+
+describe("waitForAgents", () => {
+	it("returns immediately with the result when an agent already completed", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn();
+		ledger.finishLater(agentId, "done", 1);
+		await delay(15);
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.completed, [{ agentId, result: "done" }]);
+		assert.deepEqual(outcome.running, []);
+		assert.deepEqual(outcome.notFound, []);
+		assert.equal(outcome.timedOut, false);
+		assert.equal(outcome.aborted, false);
+	});
+
+	it("returns immediately when an agent id has no tracked run", async () => {
+		const ledger = makeLedger();
+		const runningId = ledger.spawn();
+
+		const outcome = await waitForAgents(ledger.get, [runningId, "agent-unknown"], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.notFound, ["agent-unknown"]);
+		assert.deepEqual(outcome.running, [runningId]);
+		assert.deepEqual(outcome.completed, []);
+		assert.equal(outcome.timedOut, false);
+	});
+
+	it("returns the first completion while slower agents stay running", async () => {
+		const ledger = makeLedger();
+		const fastId = ledger.spawn();
+		const slowId = ledger.spawn();
+		ledger.finishLater(fastId, "fast result", 10);
+
+		const outcome = await waitForAgents(ledger.get, [fastId, slowId], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.completed, [{ agentId: fastId, result: "fast result" }]);
+		assert.deepEqual(outcome.running, [slowId]);
+		assert.equal(outcome.timedOut, false);
+	});
+
+	it("returns the agent that finished first when completions stagger", async () => {
+		const ledger = makeLedger();
+		const a = ledger.spawn();
+		const b = ledger.spawn();
+		ledger.finishLater(b, "bee", 10);
+		ledger.finishLater(a, "aye", 40);
+
+		const outcome = await waitForAgents(ledger.get, [a, b], { timeoutMs: 1000 });
+		assert.deepEqual(
+			outcome.completed.map((c) => ({ id: c.agentId, result: c.result })),
+			[{ id: b, result: "bee" }],
+		);
+		assert.deepEqual(outcome.running, [a]);
+	});
+
+	it("preserves request order when several agents already completed", async () => {
+		const ledger = makeLedger();
+		const a = ledger.spawn();
+		const b = ledger.spawn();
+		await ledger.finish(a, "aye");
+		await ledger.finish(b, "bee");
+
+		const outcome = await waitForAgents(ledger.get, [a, b], { timeoutMs: 1000 });
+		assert.deepEqual(
+			outcome.completed.map((c) => ({ id: c.agentId, result: c.result })),
+			[
+				{ id: a, result: "aye" },
+				{ id: b, result: "bee" },
+			],
+		);
+		assert.deepEqual(outcome.running, []);
+	});
+
+	it("marks still-running agents STILL RUNNING when the timeout elapses with no completion", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn(); // never finishes
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 30 });
+		assert.deepEqual(outcome.completed, []);
+		assert.deepEqual(outcome.running, [agentId]);
+		assert.equal(outcome.timedOut, true);
+		assert.equal(outcome.aborted, false);
+	});
+
+	it("can wait again on the same still-running id and pick up its later result", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn();
+		ledger.finishLater(agentId, "eventually", 60);
+
+		const first = await waitForAgents(ledger.get, [agentId], { timeoutMs: 20 });
+		assert.deepEqual(first.completed, []);
+		assert.deepEqual(first.running, [agentId]);
+		assert.equal(first.timedOut, true);
+
+		const second = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000 });
+		assert.deepEqual(second.completed, [{ agentId, result: "eventually" }]);
+		assert.deepEqual(second.running, []);
+		assert.equal(second.timedOut, false);
+	});
+
+	it("returns immediately when the abort signal already fired", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn(); // never finishes
+		const controller = new AbortController();
+		controller.abort();
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000, signal: controller.signal });
+		assert.deepEqual(outcome.completed, []);
+		assert.deepEqual(outcome.running, [agentId]);
+		assert.equal(outcome.timedOut, false);
+		assert.equal(outcome.aborted, true);
+	});
+
+	it("stops waiting when the abort signal fires mid-wait instead of timing out", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn(); // never finishes
+		const controller = new AbortController();
+		setTimeout(() => controller.abort(), 20);
+		const started = Date.now();
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000, signal: controller.signal });
+		assert.deepEqual(outcome.completed, []);
+		assert.deepEqual(outcome.running, [agentId]);
+		assert.equal(outcome.timedOut, false);
+		assert.equal(outcome.aborted, true);
+		assert.ok(Date.now() - started < 500, "returns on abort rather than waiting out the timeout");
+	});
+
+	it("applies no timeout when all requested agents resolve", async () => {
+		const ledger = makeLedger();
+		const agentId = ledger.spawn();
+		ledger.finishLater(agentId, "done", 20);
+
+		const outcome = await waitForAgents(ledger.get, [agentId], { timeoutMs: 1000 });
+		assert.deepEqual(outcome.completed, [{ agentId, result: "done" }]);
+		assert.equal(outcome.timedOut, false);
+	});
+});