@dougbots/avenor-pi 0.11.0 → 0.12.1

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, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
+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 { EventBus, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 //#region src/subagent-broker.d.ts
@@ -134,6 +134,8 @@ interface ExtensionDeps {
   workflowEventsTool: typeof workflowEventsTool;
   workflowCompleteTool: typeof workflowCompleteTool;
   workflowGateTool: typeof workflowGateTool;
+  workflowControllerStatusTool: typeof workflowControllerStatusTool;
+  workflowReadyTool: typeof workflowReadyTool;
   observeRun: typeof observeRun;
   dial: typeof dial;
   Supervisor: typeof Supervisor;

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, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool } 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, 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
@@ -1230,6 +1230,66 @@ function shutdownLines(details, args, expanded) {
 		...paths.length > CLEANUP_ITEMS ? [itemMarker(paths.length - CLEANUP_ITEMS)] : []
 	];
 }
+function controllerLeaderLine(leader) {
+	if (!leader) return "Leader: none";
+	const owner = leader.is_this_process === true ? "this process" : `other owner (${scalar(leader.owner_id)})`;
+	const expires = optionalScalar(leader.expires_at);
+	return `Leader: ${owner}${expires ? ` — lease expires ${expires}` : ""}`;
+}
+function controllerStatusLines(details, args, expanded) {
+	const status = asRecord(details);
+	if (!status || !stringValue(status.controller_id) || !stringValue(status.desired_state)) return void 0;
+	const controllerId = selected(status, "controller_id", args.controller_id);
+	const desiredState = selected(status, "desired_state");
+	const inflight = numberValue(status.inflight) ?? 0;
+	const maxInflight = numberValue(status.max_inflight);
+	const blocked = asRecord(status.capacity_blocked);
+	const blockedDetail = blocked ? optionalScalar(blocked.detail) : void 0;
+	const lines = [`Controller: ${controllerId} — ${desiredState}`, controllerLeaderLine(asRecord(status.leader))];
+	const candidates = numberValue(status.candidate_count);
+	if (candidates !== void 0) lines.push(`Candidates: ${candidates} (advisory)`);
+	lines.push(`In-flight: ${inflight}${maxInflight !== void 0 ? ` of ${maxInflight}` : ""}`);
+	const lastReconcile = optionalScalar(status.last_reconcile);
+	if (lastReconcile) lines.push(`Last reconcile: ${lastReconcile}`);
+	if (blocked) lines.push(`Capacity blocked: ${selected(blocked, "source")}${blockedDetail ? ` — ${blockedDetail}` : ""}`);
+	const nextPoll = optionalScalar(status.next_poll_at);
+	if (nextPoll) lines.push(`Next external poll: ${nextPoll}`);
+	lines.push(desiredState === "disabled" ? `Guidance: Run \`avenor workflow controller enable ${controllerId}\` to start dispatch and polling.` : `Guidance: Call avenor_workflow_controller_status without controller_id to review all controllers.`);
+	if (!expanded) return lines;
+	const supervisor = stringValue(args.supervisor_id) ? scalar(args.supervisor_id) : "singleton";
+	return [
+		...lines,
+		`Supervisor: ${supervisor}`,
+		...maxInflight !== void 0 ? [`Max in-flight: ${maxInflight}`] : [],
+		...optionalNumber(status.revision) !== void 0 ? [`Revision: ${optionalNumber(status.revision)}`] : [],
+		...optionalNumber(status.owner_epoch) !== void 0 ? [`Owner epoch: ${optionalNumber(status.owner_epoch)}`] : []
+	];
+}
+function controllerListLines(details, args, expanded) {
+	const result = asRecord(details);
+	if (!result || !Array.isArray(result.controllers) || result.controllers.some((controller) => !asRecord(controller))) return void 0;
+	const controllers = result.controllers.map((controller) => controller);
+	stringValue(args.supervisor_id) && scalar(args.supervisor_id);
+	if (controllers.length === 0) return ["No workflow controllers configured."];
+	const displayed = controllers.slice(0, STATUS_ROWS);
+	const lines = [
+		`Workflow controllers — ${controllers.length}`,
+		...displayed.map(controllerListRow),
+		...controllers.length > displayed.length ? [itemMarker(controllers.length - displayed.length)] : []
+	];
+	if (!expanded) return lines;
+	for (const controller of displayed) {
+		const leader = asRecord(controller.leader);
+		const ownerEpoch = leader ? numberValue(leader.owner_epoch) : void 0;
+		lines.push(`${selected(controller, "controller_id")}:`, controllerLeaderLine(leader), ...ownerEpoch !== void 0 ? [`Owner epoch: ${ownerEpoch}`] : []);
+	}
+	return lines;
+}
+function controllerListRow(controller) {
+	const leader = asRecord(controller.leader);
+	const owner = leader ? leader.is_this_process === true ? "this process" : `other owner (${scalar(leader.owner_id)})` : "none";
+	return `${selected(controller, "controller_id")} — ${selected(controller, "desired_state")} — leader: ${owner}`;
+}
 function render(tool, result, options, theme, build) {
 	try {
 		return linesText(options.isPartial ? partial(result) : build() ?? fallback(tool), theme);
@@ -1322,8 +1382,20 @@ function renderEventsResult(result, options, theme, args) {
 function renderShutdownResult(result, options, theme, args) {
 	return render("shutdown", result, options, theme, () => shutdownLines(result.details, args, options.expanded));
 }
+function renderWorkflowControllerStatusCall(args, theme) {
+	const pieces = stringValue(args.controller_id) ? [`avenor_workflow_controller_status controller_id ${quoted(args.controller_id)}`] : ["avenor_workflow_controller_status (all controllers)"];
+	const supervisor = optionalQuoted(args.supervisor_id);
+	if (supervisor) pieces.push(`supervisor_id ${supervisor}`);
+	return linesText([pieces.join(" ")], theme);
+}
+function renderWorkflowControllerStatusResult(result, options, theme, args) {
+	return render("workflow controller status", result, options, theme, () => controllerStatusLines(result.details, args, options.expanded) ?? controllerListLines(result.details, args, options.expanded));
+}
 //#endregion
 //#region src/index.ts
+function asStatusResult(raw) {
+	return raw;
+}
 const POLL_INTERVAL_MS = 3e3;
 const INSPECT_LIMIT = 128;
 const COMPLETION_OUTPUT_CHARS = 600;
@@ -1349,6 +1421,8 @@ const defaultDeps = {
 	workflowEventsTool,
 	workflowCompleteTool,
 	workflowGateTool,
+	workflowControllerStatusTool,
+	workflowReadyTool,
 	observeRun,
 	dial,
 	Supervisor
@@ -1526,6 +1600,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;
@@ -1643,7 +1799,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);
@@ -1673,11 +1829,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;
@@ -1760,7 +1915,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(() => {
@@ -1773,13 +1931,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({
@@ -1899,11 +2063,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,
@@ -1981,12 +2144,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 {
@@ -1999,11 +2161,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?.({
@@ -2045,6 +2206,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 () => {
@@ -2073,12 +2242,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.",
@@ -2180,21 +2349,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",
@@ -2333,7 +2537,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" })),
@@ -2345,14 +2549,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;
@@ -2374,6 +2585,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;
 				}
 			},
@@ -2477,11 +2689,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,
@@ -2518,16 +2729,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
 				});
 			}
@@ -2885,6 +3098,45 @@ function createExtension(deps = defaultDeps, options = {}) {
 				};
 			}
 		});
+		pi.registerTool({
+			name: "avenor_workflow_controller_status",
+			label: "Avenor Workflow Controller Status",
+			description: "Show workflow controller status. With controller_id, returns that controller's full status; without it, lists all controllers with summary state. Create, enable, and disable are CLI-only (avenor workflow controller ...).",
+			parameters: Type.Object({
+				controller_id: Type.Optional(Type.String({ description: "Controller ID; omit to list all controllers" })),
+				supervisor_id: Type.Optional(Type.String({ description: "Supervisor ID for multi-supervisor mode" }))
+			}),
+			async execute(_toolCallId, params) {
+				const result = await deps.workflowControllerStatusTool({
+					controllerId: params.controller_id,
+					supervisorId: params.supervisor_id
+				});
+				const details = { ...result };
+				if (params.controller_id) try {
+					const ready = await deps.workflowReadyTool({
+						controllerId: params.controller_id,
+						supervisorId: params.supervisor_id
+					});
+					if (Array.isArray(ready.candidates)) details.candidate_count = ready.candidates.length;
+				} catch {}
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					}],
+					details
+				};
+			},
+			renderCall(args, theme, context) {
+				return renderWorkflowControllerStatusCall(context.args, theme);
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				return renderWorkflowControllerStatusResult(result, {
+					expanded,
+					isPartial
+				}, theme, context.args);
+			}
+		});
 		pi.registerCommand("avenor-status", {
 			description: "Show status of all avenor runs",
 			handler: async (_args, ctx) => {

package/package.json

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