@dougbots/avenor-pi 0.10.0 → 0.10.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { InspectResult, StatusResult, Supervisor, answerPermissionTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { InspectResult, StatusResult, Supervisor, answerPermissionTool, brokerReceiveTool, brokerReplyTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, workflowCompleteTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
 import { EventBus, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 //#region src/types.d.ts
@@ -118,7 +118,15 @@ interface ExtensionDeps {
   followUpTool: typeof followUpTool;
   inspectTool: typeof inspectTool;
   resultTool: typeof resultTool;
+  brokerReceiveTool: typeof brokerReceiveTool;
+  brokerReplyTool: typeof brokerReplyTool;
   shutdownTool: typeof shutdownTool;
+  workflowStatusTool: typeof workflowStatusTool;
+  workflowWaitTool: typeof workflowWaitTool;
+  workflowInspectTool: typeof workflowInspectTool;
+  workflowEventsTool: typeof workflowEventsTool;
+  workflowCompleteTool: typeof workflowCompleteTool;
+  workflowGateTool: typeof workflowGateTool;
   observeRun: typeof observeRun;
   dial: typeof dial;
   Supervisor: typeof Supervisor;
@@ -141,7 +149,11 @@ declare function isTerminalStatus(status: string | undefined): boolean;
 declare function renderStatusLines(entries: RunStatusEntry[]): string[];
 declare function compactWhitespace(text: string | undefined, limit?: number): string | undefined;
 declare function buildInspectPayload(result: InspectResult): Record<string, unknown>;
-declare function createExtension(deps?: ExtensionDeps): (pi: ExtensionAPI) => Promise<void>;
+interface ExtensionOptions {
+  /** Polling cadence; injectable so tests can drive deterministic ticks. */
+  pollIntervalMs?: number;
+}
+declare function createExtension(deps?: ExtensionDeps, options?: ExtensionOptions): (pi: ExtensionAPI) => Promise<void>;
 declare const _default: (pi: ExtensionAPI) => Promise<void>;
 //#endregion
-export { type AvenorEventBus, type AvenorEventChannel, type AvenorEventMap, type AvenorRunStatus, CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, ExtensionDeps, type PollCompletedPayload, type PollErrorPayload, type PollErrorPayloadInput, type PollErrorSource, type RunTerminalPayload, type RunTerminalPayloadInput, buildCompletionText, buildInspectPayload, compactWhitespace, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, _default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };
+export { type AvenorEventBus, type AvenorEventChannel, type AvenorEventMap, type AvenorRunStatus, CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, ExtensionDeps, ExtensionOptions, type PollCompletedPayload, type PollErrorPayload, type PollErrorPayloadInput, type PollErrorSource, type RunTerminalPayload, type RunTerminalPayloadInput, buildCompletionText, buildInspectPayload, compactWhitespace, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, _default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { Input, Key, Text, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { Supervisor, answerPermissionTool, dial, eventsTool, extractEventText, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection } from "@dougbots/avenor-core";
+import { Supervisor, THINKING_LEVELS, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, dial, eventsTool, extractEventText, followUpTool, inspectTool, observeRun, peersTool, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, workflowCompleteTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createHash } from "node:crypto";
@@ -475,12 +475,12 @@ var RunInspectorOverlay = class {
 function matchingWatchRuns(runs, selector) {
 	const query = selector.trim().toLowerCase();
 	if (!query) return [];
-	const byId = runs.find((run) => run.runId.toLowerCase() === query);
-	if (byId) return [byId];
+	const byId = runs.filter((run) => run.runId.toLowerCase() === query);
+	if (byId.length > 0) return byId;
 	return runs.filter((run) => run.label?.toLowerCase() === query || run.agent?.toLowerCase() === query);
 }
 function watchRunChoice(run) {
-	return `${sanitizeText(run.label ?? run.runId)}${run.agent ? ` · ${sanitizeText(run.agent)}` : ""} · ${sanitizeText(run.runId).slice(0, 8)}`;
+	return `${sanitizeText(run.label ?? run.runId)}${run.agent ? ` · ${sanitizeText(run.agent)}` : ""}${run.supervisorId ? ` · ${sanitizeText(run.supervisorId)}` : ""} · ${sanitizeText(run.runId).slice(0, 8)}`;
 }
 async function selectWatchRun(ctx, runs) {
 	const choices = runs.map(watchRunChoice);
@@ -522,7 +522,20 @@ async function openRunInspector(ctx, options) {
 }
 //#endregion
 //#region src/types.ts
-function findLiveStatusForTrackedRun(run, liveStatuses) {
+/**
+* Find a live status for a tracked run from the unqualified live-status list.
+*
+* `statusTool({})` only describes the current singleton supervisor, so it is
+* authoritative solely for runs that live in the singleton namespace. Runs on
+* another supervisor must be polled through their own supervisor; matching
+* them against this list could correlate a run with a colliding id (for
+* example a shared `rt_1`) owned by a different supervisor.
+*
+* @param singletonScope true when the tracked run belongs to the singleton
+*   supervisor (no explicit socket, or a socket equal to the current instance).
+*/
+function findLiveStatusForTrackedRun(run, liveStatuses, singletonScope) {
+	if (!singletonScope) return void 0;
 	const knownRunIds = new Set([run.runId, run.lastStatus?.run_id].filter((id) => !!id));
 	let runtimeMatch;
 	for (const status of liveStatuses) {
@@ -556,16 +569,18 @@ function formatRunLine(entry) {
 	return `${emoji} ${entry.label} (${entry.agent}) — ${entry.status}${phase}${perm}`;
 }
 /**
-* decideCompletion determines whether to skip, defer, or send the completion
+* decideCompletion determines whether to skip or send the completion
 * steering message for a tracked run that has reached terminal status.
 *
-* The deferral prevents duplication when avenor_result consumes the result
-* in the same turn: if the agent calls avenor_result between the defer and
-* the next tick, the run is deleted from tracking and the send never fires.
+* The message is delivered on the same terminal tick — never deferred to a
+* later cycle — so a run that is the last live one still gets its completion.
+* `blocking` suppresses it while avenor_result is awaiting (it will deliver
+* the result itself and set `consumed`), and `consumed` suppresses it once
+* avenor_result has already returned the result successfully.
 */
 function decideCompletion(run) {
 	if (run.blocking) return "skip";
-	if (!run.completionPending) return "defer";
+	if (run.consumed) return "skip";
 	return "send";
 }
 //#endregion
@@ -1256,11 +1271,44 @@ const defaultDeps = {
 	followUpTool,
 	inspectTool,
 	resultTool,
+	brokerReceiveTool,
+	brokerReplyTool,
 	shutdownTool,
+	workflowStatusTool,
+	workflowWaitTool,
+	workflowInspectTool,
+	workflowEventsTool,
+	workflowCompleteTool,
+	workflowGateTool,
 	observeRun,
 	dial,
 	Supervisor
 };
+let hostPollTimer = null;
+const hostPendingAsks = /* @__PURE__ */ new Map();
+function stopHostAskPoll() {
+	if (hostPollTimer) {
+		clearInterval(hostPollTimer);
+		hostPollTimer = null;
+	}
+}
+async function startHostAskPoll(ctx) {
+	stopHostAskPoll();
+	hostPollTimer = setInterval(async () => {
+		try {
+			const { asks } = await deps.brokerReceiveTool({});
+			for (const ask of asks) {
+				hostPendingAsks.set(ask.message_id, {
+					from_run_id: ask.from_run_id,
+					message_id: ask.message_id
+				});
+				const body = `**📨 Ask from sub-agent** (\`${ask.role && ask.role !== "agent" ? `${ask.from_run_id} (${ask.role})` : ask.from_run_id}\`)\n\n${ask.message}\n\nTo answer, use the intercom tool: avenor_reply({ from_run_id: ${JSON.stringify(ask.from_run_id)}, reply_to_message_id: ${JSON.stringify(ask.message_id)}, message: "..." })`;
+				await ctx.sendUserMessage(body, { deliverAs: "steer" });
+			}
+		} catch (error) {}
+	}, 2e3);
+	hostPollTimer.unref?.();
+}
 function statusSupervisorId(requestedSupervisorId, spawnedSupervisorId) {
 	return requestedSupervisorId ? spawnedSupervisorId : void 0;
 }
@@ -1387,8 +1435,19 @@ function toWatchRunRef(run) {
 		supervisorId: run.supervisorId
 	};
 }
-function createExtension(deps = defaultDeps) {
+/**
+* Namespace a run id by its supervisor so runs on different supervisors can
+* never collide or be correlated, even when they share runtime ids (e.g.
+* `rt_1`). An undefined supervisorId denotes the singleton namespace. The
+* NUL separator cannot appear in socket paths or generated run ids, so the
+* singleton and each explicit supervisor stay disjoint.
+*/
+function trackedRunKey(supervisorId, runId) {
+	return `${supervisorId ?? ""}\u0000${runId}`;
+}
+function createExtension(deps = defaultDeps, options = {}) {
 	return async function(pi) {
+		const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
 		let telemetryGeneration = 0;
 		const trackedRuns = /* @__PURE__ */ new Map();
 		let pollingActive = false;
@@ -1418,8 +1477,9 @@ function createExtension(deps = defaultDeps) {
 			updateWidget(lastStatusEntries);
 		}
 		function upsertTrackedRun(run, status, blocking = false) {
-			const current = trackedRuns.get(run.runId);
-			trackedRuns.set(run.runId, {
+			const key = trackedRunKey(run.supervisorId, run.runId);
+			const current = trackedRuns.get(key);
+			trackedRuns.set(key, {
 				runId: run.runId,
 				agent: run.agent ?? status?.agent ?? current?.agent ?? "unknown",
 				label: run.label ?? status?.label ?? current?.label ?? run.runId,
@@ -1429,9 +1489,29 @@ function createExtension(deps = defaultDeps) {
 				lastStatus: status ?? current?.lastStatus,
 				blocking: current?.blocking ?? blocking,
 				permissionNotified: current?.permissionNotified,
-				completionPending: current?.completionPending
+				consumed: current?.consumed
 			});
 		}
+		/**
+		* Look a run up in the per-supervisor tracking namespace. When a
+		* supervisor is supplied, resolve exactly. Without one, prefer the
+		* singleton namespace and only fall back to a run id walk when it is
+		* unambiguous across supervisors. Duplicate run ids across supervisors
+		* without an explicit supervisor return undefined so callers never bind
+		* flags or telemetry to the wrong supervisor's run.
+		*/
+		function getTrackedRun(runId, supervisorId) {
+			if (supervisorId !== void 0) return trackedRuns.get(trackedRunKey(supervisorId, runId));
+			const singleton = trackedRuns.get(trackedRunKey(void 0, runId));
+			if (singleton) return singleton;
+			let match;
+			for (const run of trackedRuns.values()) {
+				if (run.runId !== runId) continue;
+				if (match) return void 0;
+				match = run;
+			}
+			return match;
+		}
 		async function resolveFinalOutput(run, status) {
 			const preview = finalOutputPreview(status);
 			if (preview) return preview;
@@ -1458,7 +1538,8 @@ function createExtension(deps = defaultDeps) {
 			}
 			const entries = [];
 			for (const run of trackedRuns.values()) {
-				const live = findLiveStatusForTrackedRun(run, liveMap.values());
+				const singletonScope = !run.supervisorId || Boolean(deps.Supervisor.isCurrentInstance?.(run.supervisorId));
+				const live = singletonScope ? findLiveStatusForTrackedRun(run, liveMap.values(), singletonScope) : void 0;
 				if (live) {
 					liveMap.delete(live.run_id);
 					run.lastStatus = live;
@@ -1577,18 +1658,16 @@ function createExtension(deps = defaultDeps) {
 				updateWidget(entries);
 				emitAvenorEvent(pi.events, CHANNEL_POLL_COMPLETED, createPollCompletedPayload(entries, Date.now(), ++telemetryGeneration));
 				for (const entry of entries) {
-					const run = trackedRuns.get(entry.runId);
+					const entryKey = trackedRunKey(entry.supervisorId, entry.runId);
+					const run = trackedRuns.get(entryKey);
 					if (!run) continue;
 					if (isTerminalStatus(entry.status)) {
-						const prevStatus = prevStatuses.get(entry.runId);
-						if (!(prevStatus && isTerminalStatus(prevStatus))) sessionCtx?.ui.notify(`Sub-agent "${entry.label}" finished: ${entry.status}`, entry.status === "done" ? "info" : "warning");
-						if (run.blocking) continue;
-						const action = decideCompletion(run);
-						if (action === "defer") {
-							run.completionPending = true;
+						if (decideCompletion(run) === "skip") {
+							if (run.consumed) trackedRuns.delete(entryKey);
 							continue;
 						}
-						if (action === "skip") 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");
 						const finalOutput = await resolveFinalOutput(run, run.lastStatus);
 						try {
 							pi.sendUserMessage(buildCompletionText({
@@ -1608,7 +1687,7 @@ function createExtension(deps = defaultDeps) {
 							nestedCount: entry.nestedCount,
 							backend: entry.backend
 						}));
-						trackedRuns.delete(entry.runId);
+						trackedRuns.delete(entryKey);
 					} else if (entry.pendingPermission && !run.blocking && !run.permissionNotified) {
 						run.permissionNotified = true;
 						if (run.lastStatus) try {
@@ -1627,7 +1706,7 @@ function createExtension(deps = defaultDeps) {
 						pollingActive = false;
 						console.error("avenor polling loop failed", err);
 					});
-				}, POLL_INTERVAL_MS);
+				}, pollIntervalMs);
 				else {
 					pollingActive = false;
 					updateWidget([]);
@@ -1805,7 +1884,7 @@ function createExtension(deps = defaultDeps) {
 		async function waitForRunByPolling(run, signal, onUpdate) {
 			let firstPoll = true;
 			while (!signal?.aborted) {
-				if (!firstPoll) await sleep(POLL_INTERVAL_MS);
+				if (!firstPoll) await sleep(pollIntervalMs);
 				firstPoll = false;
 				try {
 					const raw = await deps.statusTool({
@@ -1845,9 +1924,12 @@ function createExtension(deps = defaultDeps) {
 			lastStatusEntries = [];
 			pollingErrorCount = 0;
 			pollingErrors.length = 0;
+			startHostAskPoll(ctx);
 		});
 		pi.on("session_shutdown", async () => {
 			await stopPolling();
+			stopHostAskPoll();
+			hostPendingAsks.clear();
 			sessionCtx = null;
 		});
 		pi.on("before_agent_start", async () => {
@@ -1876,7 +1958,7 @@ function createExtension(deps = defaultDeps) {
 		pi.registerTool({
 			name: "avenor_spawn",
 			label: "Avenor Spawn",
-			description: "Dispatch an agent run via avenor. Optional thinking accepts off, minimal, low, medium, high, xhigh, or max; 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.`,
 			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.",
@@ -1983,7 +2065,7 @@ function createExtension(deps = defaultDeps) {
 				});
 				const waitResult = await waitForRun(runRef, signal, onUpdate);
 				if (waitResult.aborted) {
-					trackedRuns.delete(result.run_id);
+					trackedRuns.delete(trackedRunKey(supervisorId, result.run_id));
 					return {
 						content: [{
 							type: "text",
@@ -2009,7 +2091,7 @@ function createExtension(deps = defaultDeps) {
 				};
 				upsertTrackedRun(runRef, status, wait);
 				if (status.status === "waiting") {
-					const tracked = trackedRuns.get(result.run_id);
+					const tracked = getTrackedRun(result.run_id, supervisorId);
 					if (tracked) tracked.permissionNotified = true;
 					return {
 						content: [{
@@ -2043,7 +2125,7 @@ function createExtension(deps = defaultDeps) {
 						status: status.status,
 						backend: status.backend
 					}));
-					trackedRuns.delete(result.run_id);
+					trackedRuns.delete(trackedRunKey(supervisorId, result.run_id));
 					return {
 						content: [{
 							type: "text",
@@ -2142,7 +2224,7 @@ function createExtension(deps = defaultDeps) {
 				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
 			}),
 			async execute(_toolCallId, params, signal) {
-				const tracked = trackedRuns.get(params.run_id);
+				const tracked = getTrackedRun(params.run_id, params.supervisor_id);
 				const previousBlocking = tracked?.blocking;
 				if (tracked) tracked.blocking = true;
 				let completed = false;
@@ -2156,6 +2238,7 @@ function createExtension(deps = defaultDeps) {
 					});
 					completed = result.ready;
 					if (completed) {
+						if (tracked) tracked.consumed = true;
 						emitAvenorEvent(pi.events, CHANNEL_RUN_TERMINAL, createRunTerminalPayload({
 							runId: params.run_id,
 							supervisorId: tracked?.supervisorId ?? params.supervisor_id,
@@ -2164,7 +2247,7 @@ function createExtension(deps = defaultDeps) {
 							agent: tracked?.agent ?? "unknown",
 							status: result.status ?? "done"
 						}));
-						trackedRuns.delete(params.run_id);
+						if (tracked) trackedRuns.delete(trackedRunKey(tracked.supervisorId, tracked.runId));
 					} else if (tracked && result.status === "waiting") tracked.permissionNotified = true;
 					return {
 						content: [{
@@ -2174,7 +2257,7 @@ function createExtension(deps = defaultDeps) {
 						details: result
 					};
 				} finally {
-					if (!completed && tracked && trackedRuns.get(params.run_id) === tracked) tracked.blocking = previousBlocking ?? false;
+					if (!completed && tracked && getTrackedRun(params.run_id, params.supervisor_id) === tracked) tracked.blocking = previousBlocking ?? false;
 				}
 			},
 			renderCall(args, theme, context) {
@@ -2315,6 +2398,96 @@ function createExtension(deps = defaultDeps) {
 				}, theme, context.args);
 			}
 		});
+		pi.registerTool({
+			name: "avenor_ask",
+			label: "Avenor Ask",
+			description: "Ask another agent run a question and block until it replies.",
+			parameters: Type.Object({
+				to_run_id: Type.String({ description: "Target run ID" }),
+				message: Type.String({ description: "Question to ask the other agent" }),
+				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,
+					supervisorId: params.supervisor_id
+				});
+			}
+		});
+		pi.registerTool({
+			name: "avenor_reply",
+			label: "Avenor Reply (host)",
+			description: "Reply to an inbound ask received from a sub-agent. Answer the most recent ask from a given sub-agent, or reply to a specific message_id from avenor_ask.",
+			parameters: Type.Object({
+				from_run_id: Type.Optional(Type.String({ description: "Sub-agent run id to reply to (the asker)" })),
+				reply_to_message_id: Type.Optional(Type.String({ description: "The ask's broker message id to answer specifically" })),
+				message: Type.String({ description: "Your answer" }),
+				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
+			}),
+			async execute(_toolCallId, params) {
+				let fromRunId = params.from_run_id;
+				let messageId = params.reply_to_message_id;
+				if (!messageId) {
+					let match;
+					for (const [, pending] of hostPendingAsks) if (pending.from_run_id === fromRunId && (!match || pending.message_id > match.message_id)) match = pending;
+					if (match) messageId = match.message_id;
+				}
+				if (!fromRunId || !messageId) return {
+					content: [{
+						type: "text",
+						text: "No pending ask found to reply to. Pass from_run_id and/or reply_to_message_id."
+					}],
+					details: { error: true }
+				};
+				await deps.brokerReplyTool({
+					toRunId: fromRunId,
+					replyTo: messageId,
+					message: params.message,
+					supervisorId: params.supervisor_id
+				});
+				hostPendingAsks.delete(messageId);
+				return { content: [{
+					type: "text",
+					text: "Reply sent"
+				}] };
+			}
+		});
+		pi.registerTool({
+			name: "avenor_peers",
+			label: "Avenor Peers",
+			description: "List all connected agent sessions with their status and metadata.",
+			parameters: Type.Object({}),
+			async execute() {
+				const result = await peersTool({});
+				if (result.peers.length === 0) return { content: [{
+					type: "text",
+					text: "No other agent sessions connected."
+				}] };
+				return { content: [{
+					type: "text",
+					text: `**Active sessions:**\n${result.peers.map((p) => {
+						const parts = [p.label ? `${p.label} (${p.run_id})` : p.run_id];
+						const tags = [
+							p.status,
+							p.backend,
+							p.model
+						].filter(Boolean);
+						if (tags.length) parts.push(`[${tags.join(", ")}]`);
+						return `  ${parts.join(" ")}`;
+					}).join("\n")}`
+				}] };
+			}
+		});
+		pi.registerTool({
+			name: "avenor_cancel",
+			label: "Avenor Cancel",
+			description: "Cancel a pending ask by its message ID.",
+			parameters: Type.Object({ message_id: Type.String({ description: "Message ID of the pending ask to cancel" }) }),
+			async execute(_toolCallId, params) {
+				return cancelTool({ messageId: params.message_id });
+			}
+		});
 		pi.registerTool({
 			name: "avenor_events",
 			label: "Avenor Events",
@@ -2359,8 +2532,20 @@ function createExtension(deps = defaultDeps) {
 				force: Type.Optional(Type.Boolean({ description: "Force shutdown instead of graceful" }))
 			}),
 			async execute(_toolCallId, params) {
-				await stopPolling();
-				trackedRuns.clear();
+				const target = params.supervisor_id;
+				const targetIsSingleton = target === void 0 || Boolean(deps.Supervisor.isCurrentInstance?.(target));
+				let removed = 0;
+				for (const [key, run] of trackedRuns) if (targetIsSingleton ? !run.supervisorId || Boolean(deps.Supervisor.isCurrentInstance?.(run.supervisorId)) : run.supervisorId === target) {
+					trackedRuns.delete(key);
+					removed++;
+				}
+				if (removed > 0 && trackedRuns.size === 0) await stopPolling();
+				else if (removed > 0) {
+					pollingActive = false;
+					pollingGeneration++;
+					await pollInFlight?.catch(() => {});
+					startPolling();
+				}
 				const result = await deps.shutdownTool({
 					supervisorId: params.supervisor_id,
 					force: params.force
@@ -2383,6 +2568,173 @@ function createExtension(deps = defaultDeps) {
 				}, theme, context.args);
 			}
 		});
+		pi.registerTool({
+			name: "avenor_workflow_status",
+			label: "Avenor Workflow Status",
+			description: "Get lightweight status for a workflow instance",
+			parameters: Type.Object({
+				workflow_id: Type.String({ description: "Workflow ID" }),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const result = await deps.workflowStatusTool({
+					workflowId: params.workflow_id,
+					supervisorId: params.supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
+		pi.registerTool({
+			name: "avenor_workflow_wait",
+			label: "Avenor Workflow Wait",
+			description: "Wait for a workflow to reach a terminal state or until timeout",
+			parameters: Type.Object({
+				workflow_id: Type.String({ description: "Workflow ID" }),
+				timeout: Type.Optional(Type.String({ description: "Timeout (e.g. 30s, 5m)" })),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const result = await deps.workflowWaitTool({
+					workflowId: params.workflow_id,
+					timeout: params.timeout,
+					supervisorId: params.supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
+		pi.registerTool({
+			name: "avenor_workflow_inspect",
+			label: "Avenor Workflow Inspect",
+			description: "Return the full instance detail for a workflow",
+			parameters: Type.Object({
+				workflow_id: Type.String({ description: "Workflow ID" }),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const result = await deps.workflowInspectTool({
+					workflowId: params.workflow_id,
+					supervisorId: params.supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
+		pi.registerTool({
+			name: "avenor_workflow_events",
+			label: "Avenor Workflow Events",
+			description: "Read log events from a workflow instance's event log",
+			parameters: Type.Object({
+				workflow_id: Type.String({ description: "Workflow ID" }),
+				after_seq: Type.Optional(Type.Number({ description: "Only include events after this sequence number" })),
+				limit: Type.Optional(Type.Number({ description: "Max events to return (default 50)" })),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const result = await deps.workflowEventsTool({
+					workflowId: params.workflow_id,
+					afterSeq: params.after_seq,
+					limit: params.limit,
+					supervisorId: params.supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
+		pi.registerTool({
+			name: "avenor_workflow_complete",
+			label: "Avenor Workflow Complete",
+			description: "Atomically complete a machine/external handoff activation",
+			parameters: Type.Object({
+				workflow_id: Type.String({ description: "Workflow ID" }),
+				node_id: Type.String({ description: "Node ID" }),
+				activation_id: Type.String({ description: "Activation ID" }),
+				attempt_id: Type.String({ description: "Attempt ID" }),
+				lease_id: Type.String({ description: "Lease ID" }),
+				owner_token: Type.String({ description: "Owner token" }),
+				outcome: Type.String({ description: "Outcome" }),
+				outputs: Type.Optional(Type.Unknown({ description: "Outputs" })),
+				artifacts: Type.Optional(Type.Unknown({ description: "Artifacts" })),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const { supervisor_id, ...rest } = params;
+				const result = await deps.workflowCompleteTool({
+					...rest,
+					supervisorId: supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
+		pi.registerTool({
+			name: "avenor_workflow_gate",
+			label: "Avenor Workflow Gate",
+			description: "Record a gate decision on a parked awaiting_gate activation",
+			parameters: Type.Object({
+				workflow_id: Type.String({ description: "Workflow ID" }),
+				node_id: Type.String({ description: "Node ID" }),
+				gate_id: Type.String({ description: "Gate ID" }),
+				activation_id: Type.String({ description: "Activation ID" }),
+				operation: Type.Union([
+					Type.Literal("satisfy"),
+					Type.Literal("reject"),
+					Type.Literal("waive"),
+					Type.Literal("external_result")
+				], { description: "Gate operation" }),
+				actor: Type.Optional(Type.String({ description: "Actor" })),
+				reason: Type.Optional(Type.String({ description: "Reason" })),
+				outcome: Type.Optional(Type.String({ description: "Outcome" })),
+				subject: Type.Optional(Type.Unknown({ description: "Subject" })),
+				poll_id: Type.Optional(Type.String({ description: "Poll ID" })),
+				source: Type.Optional(Type.String({ description: "Source" })),
+				result: Type.Optional(Type.String({ description: "Result" })),
+				response_hash: Type.Optional(Type.String({ description: "Response hash" })),
+				observed_at: Type.Optional(Type.String({ description: "Observed at" })),
+				evidence_ids: Type.Optional(Type.Array(Type.String(), { description: "Evidence IDs" })),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const { supervisor_id, ...rest } = params;
+				const result = await deps.workflowGateTool({
+					...rest,
+					supervisorId: supervisor_id
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details: result
+				};
+			}
+		});
 		pi.registerCommand("avenor-status", {
 			description: "Show status of all avenor runs",
 			handler: async (_args, ctx) => {
@@ -2438,10 +2790,13 @@ function createExtension(deps = defaultDeps) {
 		pi.registerCommand("avenor-cancel", {
 			description: "Cancel a running avenor sub-agent",
 			getArgumentCompletions: (prefix) => {
-				const items = Array.from(trackedRuns.values()).filter((run) => run.label.startsWith(prefix) || run.agent?.startsWith(prefix) || run.runId.startsWith(prefix)).map((run) => ({
-					value: run.runId,
-					label: `${sanitizeText(run.label)} (${sanitizeText(run.agent ?? "roster")}, ${sanitizeText(run.runId).slice(0, 8)})`
-				}));
+				const runs = Array.from(trackedRuns.values());
+				const items = runs.filter((run) => run.label.startsWith(prefix) || run.agent?.startsWith(prefix) || run.runId.startsWith(prefix)).map((run) => {
+					return {
+						value: runs.some((other) => other !== run && other.runId === run.runId) ? `${run.supervisorId ?? ""}::${run.runId}` : run.runId,
+						label: `${sanitizeText(run.label)} (${sanitizeText(run.agent ?? "roster")}, ${sanitizeText(run.runId).slice(0, 8)})`
+					};
+				});
 				return items.length > 0 ? items : null;
 			},
 			handler: async (args, ctx) => {
@@ -2449,8 +2804,11 @@ function createExtension(deps = defaultDeps) {
 					ctx.ui.notify("Usage: /avenor-cancel <run_id>", "warning");
 					return;
 				}
-				const runId = args.trim();
-				const run = trackedRuns.get(runId);
+				const raw = args.trim();
+				const sep = raw.lastIndexOf("::");
+				const supervisorId = sep >= 0 ? raw.slice(0, sep) || void 0 : void 0;
+				const runId = sep >= 0 ? raw.slice(sep + 2) : raw;
+				const run = getTrackedRun(runId, supervisorId);
 				const label = run?.label ?? runId;
 				const runtimeId = run?.runtimeId ?? run?.lastStatus?.runtime_id;
 				if (!runtimeId) {

package/package.json

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