@dougbots/avenor-pi 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { InspectResult, StatusResult, Supervisor, answerPermissionTool, brokerReceiveTool, brokerReplyTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
+import { InspectResult, StatusResult, Supervisor, answerPermissionTool, brokerReceiveTool, brokerReplyTool, dial, eventsTool, followUpTool, inspectTool, killTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
 import { EventBus, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 //#region src/subagent-broker.d.ts
@@ -128,6 +128,7 @@ interface ExtensionDeps {
   brokerReceiveTool: typeof brokerReceiveTool;
   brokerReplyTool: typeof brokerReplyTool;
   shutdownTool: typeof shutdownTool;
+  killTool: typeof killTool;
   workflowStatusTool: typeof workflowStatusTool;
   workflowWaitTool: typeof workflowWaitTool;
   workflowInspectTool: typeof workflowInspectTool;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { Input, Key, Text, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { createHash, randomUUID } from "node:crypto";
-import { Supervisor, THINKING_LEVELS, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, dial, eventsTool, extractEventText, followUpTool, inspectTool, observeRun, peersTool, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
+import { Supervisor, THINKING_LEVELS, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, dial, eventsTool, extractEventText, followUpTool, inspectTool, killTool, observeRun, peersTool, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
 import * as fs from "node:fs";
 import * as path from "node:path";
 //#region src/subagent-broker.ts
@@ -1393,6 +1393,9 @@ function renderWorkflowControllerStatusResult(result, options, theme, args) {
 }
 //#endregion
 //#region src/index.ts
+function asStatusResult(raw) {
+	return raw;
+}
 const POLL_INTERVAL_MS = 3e3;
 const INSPECT_LIMIT = 128;
 const COMPLETION_OUTPUT_CHARS = 600;
@@ -1412,6 +1415,7 @@ const defaultDeps = {
 	brokerReceiveTool,
 	brokerReplyTool,
 	shutdownTool,
+	killTool,
 	workflowStatusTool,
 	workflowWaitTool,
 	workflowInspectTool,
@@ -1597,6 +1601,88 @@ function createExtension(deps = defaultDeps, options = {}) {
 		let pollingErrorCount = 0;
 		const pollingErrors = [];
 		let lastStatusEntries = [];
+		const pendingWaits = /* @__PURE__ */ new Set();
+		function interruptPendingWaits(stop, excludeRunKey) {
+			for (const wait of [...pendingWaits]) {
+				if (wait.runKey === excludeRunKey) continue;
+				pendingWaits.delete(wait);
+				wait.interrupt(stop);
+			}
+		}
+		function registerPendingWait(runKey, interrupt) {
+			const wait = {
+				runKey,
+				interrupt
+			};
+			pendingWaits.add(wait);
+			return wait;
+		}
+		function createInterruptibleWait(runKey, signal) {
+			const controller = new AbortController();
+			let stopped;
+			const onSignalAbort = () => controller.abort();
+			if (signal?.aborted) controller.abort();
+			else signal?.addEventListener("abort", onSignalAbort);
+			const pending = registerPendingWait(runKey, (stop) => {
+				if (controller.signal.aborted) return;
+				stopped = stop;
+				controller.abort();
+			});
+			return {
+				signal: controller.signal,
+				get stopped() {
+					return stopped;
+				},
+				dispose() {
+					pendingWaits.delete(pending);
+					signal?.removeEventListener("abort", onSignalAbort);
+				}
+			};
+		}
+		/** Build the early return for a wait interrupted by a sibling stopping
+		* point. When the awaited run itself has since reached a stopping point
+		* (possible when the caller omitted supervisor_id and the registry key
+		* diverged), deliver its real state instead of an interruption notice. */
+		async function resultAfterInterrupt(params, stop, tracked) {
+			const runId = tracked?.runId ?? params.run_id;
+			const supervisorId = tracked?.supervisorId ?? params.supervisor_id;
+			let current;
+			try {
+				current = asStatusResult(await deps.statusTool({
+					runId,
+					supervisorId,
+					view: "full"
+				}));
+			} catch {}
+			if (current !== void 0 && (isTerminalStatus(current.status) || current.status === "waiting")) try {
+				return {
+					...await deps.resultTool({
+						runId,
+						supervisorId,
+						wait: true,
+						timeout: params.timeout,
+						signal: params.signal
+					}),
+					interrupted_by: {
+						run_id: stop.runId,
+						label: stop.label,
+						status: stop.status
+					}
+				};
+			} catch {}
+			return {
+				run_id: current?.run_id ?? runId,
+				label: current?.label ?? runId,
+				status: current?.status ?? "running",
+				ready: current !== void 0 && isTerminalStatus(current.status),
+				...current?.pending_permission && { pending_permission: current.pending_permission },
+				interrupted_by: {
+					run_id: stop.runId,
+					label: stop.label,
+					status: stop.status
+				}
+			};
+		}
 		const subAgentEnv = options.subAgentEnv !== void 0 ? options.subAgentEnv : readSubAgentEnv();
 		const isSubAgentBrokerMode = subAgentEnv !== null;
 		let subAgentPollTimer = null;
@@ -1714,7 +1800,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 			const liveMap = /* @__PURE__ */ new Map();
 			try {
 				const allLive = await deps.statusTool({});
-				const liveList = Array.isArray(allLive) ? allLive : [allLive];
+				const liveList = "runs" in allLive ? allLive.runs : [allLive];
 				for (const result of liveList) liveMap.set(result.run_id, result);
 			} catch (err) {
 				recordPollingError("singleton-list", "failed to list singleton runs", err);
@@ -1744,11 +1830,10 @@ function createExtension(deps = defaultDeps, options = {}) {
 					continue;
 				}
 				try {
-					const raw = await deps.statusTool({
+					const result = asStatusResult(await deps.statusTool({
 						runId: run.runId,
 						supervisorId: run.supervisorId
-					});
-					const result = Array.isArray(raw) ? raw[0] : raw;
+					}));
 					if (!result) throw new Error("status response was empty");
 					run.lastStatus = result;
 					run.agent = result.agent ?? run.agent;
@@ -1831,7 +1916,10 @@ function createExtension(deps = defaultDeps, options = {}) {
 			const tick = async () => {
 				if (!pollingActive || generation !== pollingGeneration) return;
 				const prevStatuses = /* @__PURE__ */ new Map();
-				for (const [id, run] of trackedRuns) prevStatuses.set(id, run.lastStatus?.status);
+				for (const [id, run] of trackedRuns) prevStatuses.set(id, {
+					status: run.lastStatus?.status,
+					pendingPermission: !!run.lastStatus?.pending_permission
+				});
 				const currentPoll = pollRuns();
 				pollInFlight = currentPoll;
 				const entries = await currentPoll.finally(() => {
@@ -1844,13 +1932,19 @@ function createExtension(deps = defaultDeps, options = {}) {
 					const entryKey = trackedRunKey(entry.supervisorId, entry.runId);
 					const run = trackedRuns.get(entryKey);
 					if (!run) continue;
+					const prevStatus = prevStatuses.get(entryKey);
+					const wasStopped = prevStatus?.status !== void 0 && isTerminalStatus(prevStatus.status) || !!prevStatus?.pendingPermission;
+					if ((entry.pendingPermission || isTerminalStatus(entry.status)) && !wasStopped) interruptPendingWaits({
+						runId: entry.runId,
+						label: entry.label,
+						status: isTerminalStatus(entry.status) ? entry.status : "waiting"
+					}, entryKey);
 					if (isTerminalStatus(entry.status)) {
 						if (decideCompletion(run) === "skip") {
 							if (run.consumed) trackedRuns.delete(entryKey);
 							continue;
 						}
-						const prevStatus = prevStatuses.get(entryKey);
-						if (!(prevStatus && isTerminalStatus(prevStatus))) sessionCtx?.ui.notify(`Sub-agent "${entry.label}" finished: ${entry.status}`, entry.status === "done" ? "info" : "warning");
+						if (!(prevStatus?.status !== void 0 && isTerminalStatus(prevStatus.status))) sessionCtx?.ui.notify(`Sub-agent "${entry.label}" finished: ${entry.status}`, entry.status === "done" ? "info" : "warning");
 						const finalOutput = await resolveFinalOutput(run, run.lastStatus);
 						try {
 							pi.sendUserMessage(buildCompletionText({
@@ -1970,11 +2064,10 @@ function createExtension(deps = defaultDeps, options = {}) {
 				supervisorId: run.supervisorId
 			});
 			try {
-				const rawStatus = await deps.statusTool({
+				const status = asStatusResult(await deps.statusTool({
 					runId: result.run_id,
 					supervisorId: run.supervisorId
-				});
-				const status = Array.isArray(rawStatus) ? rawStatus[0] : rawStatus;
+				}));
 				upsertTrackedRun({
 					runId: result.run_id,
 					label: result.label,
@@ -2052,12 +2145,11 @@ function createExtension(deps = defaultDeps, options = {}) {
 			await observer?.close().catch(() => {});
 			if (outcome === "aborted") return { aborted: true };
 			try {
-				const raw = await deps.statusTool({
-					runId: run.runId,
-					supervisorId: run.supervisorId
-				});
 				return {
-					status: Array.isArray(raw) ? raw[0] : raw,
+					status: asStatusResult(await deps.statusTool({
+						runId: run.runId,
+						supervisorId: run.supervisorId
+					})),
 					aborted: false
 				};
 			} catch {
@@ -2070,11 +2162,10 @@ function createExtension(deps = defaultDeps, options = {}) {
 				if (!firstPoll) await sleep(pollIntervalMs);
 				firstPoll = false;
 				try {
-					const raw = await deps.statusTool({
+					const status = asStatusResult(await deps.statusTool({
 						runId: run.runId,
 						supervisorId: run.supervisorId
-					});
-					const status = Array.isArray(raw) ? raw[0] : raw;
+					}));
 					if (!status) continue;
 					const text = status.pending_permission ? `[blocked] ${run.label ?? run.runId} — permission: ${status.pending_permission.description}` : `${run.label ?? run.runId}${status.phase_label ? ` (${status.phase_label})` : ""}`;
 					onUpdate?.({
@@ -2116,6 +2207,14 @@ function createExtension(deps = defaultDeps, options = {}) {
 			stopSubAgentPoll();
 			hostPendingAsks.clear();
 			subAgentPendingAsks.clear();
+			for (const wait of [...pendingWaits]) {
+				pendingWaits.delete(wait);
+				wait.interrupt({
+					runId: "",
+					status: "shutdown",
+					synthetic: true
+				});
+			}
 			sessionCtx = null;
 		});
 		pi.on("before_agent_start", async () => {
@@ -2144,12 +2243,12 @@ function createExtension(deps = defaultDeps, options = {}) {
 		pi.registerTool({
 			name: "avenor_spawn",
 			label: "Avenor Spawn",
-			description: `Dispatch an agent run via avenor. Optional thinking accepts ${[...THINKING_LEVELS].slice(0, -1).join(", ")}, or ${THINKING_LEVELS[THINKING_LEVELS.length - 1]}; unsupported backends reject explicit values. Blocks by default, showing live progress. Set wait=false for fire-and-forget.`,
+			description: `Dispatch an agent run via avenor. Optional thinking accepts ${[...THINKING_LEVELS].slice(0, -1).join(", ")}, or ${THINKING_LEVELS[THINKING_LEVELS.length - 1]}; unsupported backends reject explicit values. Blocks by default, showing live progress. Set wait=false for fire-and-forget. With several blocking spawns in parallel, the first stopping point (permission or completion) interrupts the other waits.`,
 			promptSnippet: "Dispatch sub-agent runs via avenor (spawn, status, result, inspect, events, follow-up, shutdown)",
 			promptGuidelines: [
 				"Use avenor_spawn to delegate well-defined tasks to sub-agents.",
 				"Use avenor_status (view \"lifecycle\") only to check progress or pending permissions.",
-				"Use avenor_result to retrieve the final result of a sub-agent; it waits by default, but set wait=false for runs that already completed.",
+				"Use avenor_result to retrieve the final result of a sub-agent; it waits by default, but set wait=false for runs that already completed. When awaiting multiple runs, the first stopping point (permission or completion) interrupts the other waits.",
 				"Use avenor_inspect to review a bounded transcript and tool activity from a run.",
 				"Use avenor_events only when you specifically need raw event payloads.",
 				"Use avenor_follow_up to iterate on a completed run.",
@@ -2251,21 +2350,56 @@ function createExtension(deps = defaultDeps, options = {}) {
 						run_id: result.run_id
 					}
 				});
-				const waitResult = await waitForRun(runRef, signal, onUpdate);
+				const blockingWait = createInterruptibleWait(trackedRunKey(supervisorId, result.run_id), signal);
+				let waitResult;
+				try {
+					waitResult = await waitForRun(runRef, blockingWait.signal, onUpdate);
+				} finally {
+					blockingWait.dispose();
+				}
+				let waitStatus = waitResult.status;
 				if (waitResult.aborted) {
-					trackedRuns.delete(trackedRunKey(supervisorId, result.run_id));
-					return {
-						content: [{
-							type: "text",
-							text: `Monitoring of "${label}" (run_id: ${result.run_id}) was interrupted. Use avenor_status or avenor_inspect to check.`
-						}],
-						details: {
-							run_id: result.run_id,
-							...spawnIdentityMetadata(hostParams)
+					const stop = blockingWait.stopped;
+					if (stop && !stop.synthetic) {
+						const probed = asStatusResult(await deps.statusTool({
+							runId: result.run_id,
+							supervisorId
+						}).catch(() => void 0));
+						if (probed && (isTerminalStatus(probed.status) || probed.status === "waiting")) waitStatus = probed;
+						else {
+							const tracked = getTrackedRun(result.run_id, supervisorId);
+							if (tracked) tracked.blocking = false;
+							return {
+								content: [{
+									type: "text",
+									text: `Monitoring of "${label}" (run_id: ${result.run_id}) was interrupted: "${stop.label ?? stop.runId}" reached ${stop.status === "waiting" ? "a permission request" : stop.status}. Handle that first; this run's final result is delivered automatically.`
+								}],
+								details: {
+									run_id: result.run_id,
+									interrupted_by: {
+										run_id: stop.runId,
+										label: stop.label,
+										status: stop.status
+									},
+									...spawnIdentityMetadata(hostParams)
+								}
+							};
 						}
-					};
+					} else {
+						trackedRuns.delete(trackedRunKey(supervisorId, result.run_id));
+						return {
+							content: [{
+								type: "text",
+								text: `Monitoring of "${label}" (run_id: ${result.run_id}) was interrupted. Use avenor_status or avenor_inspect to check.`
+							}],
+							details: {
+								run_id: result.run_id,
+								...spawnIdentityMetadata(hostParams)
+							}
+						};
+					}
 				}
-				const status = waitResult.status;
+				const status = waitStatus;
 				if (!status) return {
 					content: [{
 						type: "text",
@@ -2404,7 +2538,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 		pi.registerTool({
 			name: "avenor_result",
 			label: "Avenor Result",
-			description: "Retrieve the complete final output of a run without transcript or event details. Waits by default; set wait=false to retrieve an already-completed run without blocking.",
+			description: `Retrieve the complete final output of a run without transcript or event details. Waits by default; set wait=false to retrieve an already-completed run without blocking. When several runs are pending, the first stopping point (a permission request or completion on any run) interrupts other blocking waits so they can be handled; re-issue the interrupted wait afterwards.`,
 			parameters: Type.Object({
 				run_id: Type.String({ description: "Run ID or label" }),
 				wait: Type.Optional(Type.Boolean({ description: "Wait for a terminal result (default true); false retrieves the current state without blocking" })),
@@ -2416,14 +2550,21 @@ function createExtension(deps = defaultDeps, options = {}) {
 				const previousBlocking = tracked?.blocking;
 				if (tracked) tracked.blocking = true;
 				let completed = false;
+				const blockingWait = params.wait ?? true ? createInterruptibleWait(trackedRunKey(tracked?.supervisorId ?? params.supervisor_id, tracked?.runId ?? params.run_id), signal) : void 0;
 				try {
-					const result = await deps.resultTool({
-						runId: params.run_id,
-						supervisorId: params.supervisor_id,
-						wait: params.wait,
-						timeout: params.timeout,
-						signal
-					});
+					let result;
+					try {
+						result = await deps.resultTool({
+							runId: params.run_id,
+							supervisorId: params.supervisor_id,
+							wait: params.wait,
+							timeout: params.timeout,
+							signal: blockingWait?.signal ?? signal
+						});
+					} catch (err) {
+						if (!blockingWait?.stopped || blockingWait.stopped.synthetic) throw err;
+						result = await resultAfterInterrupt(params, blockingWait.stopped, tracked);
+					}
 					completed = result.ready;
 					if (completed) {
 						if (tracked) tracked.consumed = true;
@@ -2445,6 +2586,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 						details: result
 					};
 				} finally {
+					blockingWait?.dispose();
 					if (!completed && tracked && getTrackedRun(params.run_id, params.supervisor_id) === tracked) tracked.blocking = previousBlocking ?? false;
 				}
 			},
@@ -2548,11 +2690,10 @@ function createExtension(deps = defaultDeps, options = {}) {
 					supervisorId: params.supervisor_id
 				});
 				try {
-					const rawStatus = await deps.statusTool({
+					const status = asStatusResult(await deps.statusTool({
 						runId: result.run_id,
 						supervisorId: params.supervisor_id
-					});
-					const status = Array.isArray(rawStatus) ? rawStatus[0] : rawStatus;
+					}));
 					upsertTrackedRun({
 						runId: result.run_id,
 						label: result.label,
@@ -2589,16 +2730,18 @@ function createExtension(deps = defaultDeps, options = {}) {
 		pi.registerTool({
 			name: "avenor_ask",
 			label: "Avenor Ask",
-			description: "Ask another agent run a question and block until it replies.",
+			description: "Ask another agent run a question and block until it replies. An optional timeout_ms bounds the wait; a failed ask reports its message_id and whether it is still pending (withdrawable via avenor_cancel) or already withdrawn.",
 			parameters: Type.Object({
 				to_run_id: Type.String({ description: "Target run ID" }),
 				message: Type.String({ description: "Question to ask the other agent" }),
+				timeout_ms: Type.Optional(Type.Integer({ description: "Optional timeout in milliseconds for the ask" })),
 				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
 			}),
 			async execute(_toolCallId, params) {
 				return askTool({
 					toRunId: params.to_run_id,
 					message: params.message,
+					timeoutMs: params.timeout_ms,
 					supervisorId: params.supervisor_id
 				});
 			}
@@ -2789,6 +2932,31 @@ function createExtension(deps = defaultDeps, options = {}) {
 				}, theme, context.args);
 			}
 		});
+		pi.registerTool({
+			name: "avenor_kill",
+			label: "Avenor Kill",
+			description: "Terminate a run without shutting down the supervisor. Other runs and the supervisor itself keep running.",
+			parameters: Type.Object({
+				run_id: Type.String({
+					minLength: 1,
+					description: "Run ID or label to terminate"
+				}),
+				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
+			}),
+			async execute(_toolCallId, params) {
+				const result = await deps.killTool({
+					runId: params.run_id,
+					supervisorId: params.supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
 		pi.registerTool({
 			name: "avenor_workflow_status",
 			label: "Avenor Workflow Status",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-pi",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -35,7 +35,7 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "^0.12.0"
+    "@dougbots/avenor-core": "^0.13.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.74.0",