@dougbots/avenor-pi 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { InspectResult, StatusResult, Supervisor, answerPermissionTool, attachOwner, 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
@@ -139,6 +139,7 @@ interface ExtensionDeps {
   workflowReadyTool: typeof workflowReadyTool;
   observeRun: typeof observeRun;
   dial: typeof dial;
+  attachOwner: typeof attachOwner;
   Supervisor: typeof Supervisor;
 }
 declare function statusSupervisorId(requestedSupervisorId: string | undefined, spawnedSupervisorId: string): string | undefined;

package/dist/index.js

@@ -1,10 +1,12 @@
 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, killTool, 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, attachOwner, brokerReceiveTool, brokerReplyTool, cancelTool, dial, eventsTool, extractEventText, extractReplyMessage, followUpTool, formatAskFailure, inspectTool, killTool, normalizeAskTimeoutMs, 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
+/** Deadline for a cleanup call whose caller's own deadline has already expired. */
+const ASK_CLEANUP_TIMEOUT_MS = 5e3;
 function readSubAgentEnv(env = process.env) {
 	const brokerUrl = env.AVENOR_BROKER_URL ?? "";
 	const runId = env.AVENOR_RUN_ID ?? "";
@@ -40,17 +42,46 @@ function parseControlMessage(msg) {
 function formatInboundAskBody(ask) {
 	return `**📨 Inbound ask**${ask.from_run_id ? ` from \`${ask.from_run_id}\`` : ""}\n\n${ask.message}\n\nTo answer, use avenor_reply({ reply_to_message_id: ${JSON.stringify(ask.message_id)}, message: "..." }).`;
 }
-async function postBroker(env, path, body, fetchImpl = fetch) {
+/** A broker HTTP response error, so callers can classify by status instead of
+* matching digits in the request text. */
+var BrokerHttpError = class extends Error {
+	status;
+	constructor(path, status, body) {
+		super(`broker ${path}: ${status} ${body}`);
+		this.name = "BrokerHttpError";
+		this.status = status;
+	}
+};
+/** Build the `/send` body for one agent_message, as the broker child tools do. */
+function buildAgentMessage(fields) {
+	return {
+		from_run_id: fields.fromRunId,
+		to_run_id: fields.toRunId,
+		type: "agent_message",
+		payload: {
+			id: fields.messageId,
+			from: fields.fromRunId,
+			from_run_id: fields.fromRunId,
+			to_run_id: fields.toRunId,
+			message: fields.message,
+			role: fields.role,
+			...fields.expectsReply ? { expects_reply: true } : {},
+			...fields.replyTo !== void 0 ? { reply_to: fields.replyTo } : {}
+		}
+	};
+}
+async function postBroker(env, path, body, fetchImpl = fetch, signal) {
 	const res = await fetchImpl(`${env.brokerUrl}${path}`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({
+			...body,
 			run_id: env.runId,
-			token: env.token,
-			...body
-		})
+			token: env.token
+		}),
+		...signal ? { signal } : {}
 	});
-	if (!res.ok) throw new Error(`broker ${path}: ${res.status} ${(await res.text()).trim()}`);
+	if (!res.ok) throw new BrokerHttpError(path, res.status, (await res.text()).trim());
 	return res.json();
 }
 /**
@@ -72,6 +103,143 @@ function resolveReplyTarget(pending, fromRunId, replyToMessageId) {
 	for (const [, entry] of pending) if (!fromRunId || entry.from_run_id === fromRunId) match = entry;
 	return match ?? null;
 }
+function combineSignals(...signals) {
+	const active = signals.filter((signal) => signal !== void 0);
+	if (active.length === 0) return void 0;
+	if (active.length === 1) return active[0];
+	return AbortSignal.any(active);
+}
+function describeFailure(error) {
+	if (error instanceof Error) {
+		if (error.name === "TimeoutError") return "timed out";
+		if (error.name === "AbortError") return "cancelled";
+		return error.message || error.name;
+	}
+	return String(error);
+}
+/**
+* Withdraw a pending ask through the broker as this run. The broker's own error
+* propagates so a caller reporting to a model shows its exact text.
+*/
+async function withdrawPendingAsk(env, messageId, fetchImpl = fetch) {
+	await postBroker(env, "/cancel_message", { cancel_message_id: messageId }, fetchImpl, AbortSignal.timeout(ASK_CLEANUP_TIMEOUT_MS));
+}
+/**
+* Withdraw a pending ask and classify whether the edge may still exist on the
+* broker: true means the cleanup could not be confirmed, false means it is gone.
+*/
+async function withdrawAsk(env, messageId, fetchImpl) {
+	try {
+		await withdrawPendingAsk(env, messageId, fetchImpl);
+		return false;
+	} catch (error) {
+		if (error instanceof BrokerHttpError) return error.status !== 404;
+		return true;
+	}
+}
+/** Fetch causes for a dial that never opened, so no request reached the broker. */
+const NEVER_REACHED_CODES = new Set([
+	"ECONNREFUSED",
+	"ConnectionRefused",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"ERR_INVALID_URL"
+]);
+/**
+* Whether a fetch failure carries only dial-level causes, so no request was
+* carried to the broker and no ask edge can exist. Undici aggregates one error
+* per dialled address, so every attempt must have failed at the dial.
+*/
+function dialNeverOpened(error, depth = 0) {
+	if (depth > 5 || error === null || error === void 0) return false;
+	const node = error;
+	if (typeof node.code === "string" && NEVER_REACHED_CODES.has(node.code)) return true;
+	if (Array.isArray(node.errors) && node.errors.length > 0) return node.errors.every((cause) => dialNeverOpened(cause, depth + 1));
+	return dialNeverOpened(node.cause, depth + 1);
+}
+/** Whether the failure came from a caller or timeout abort, not from the wire. */
+function abortedBeforeResponse(error, depth = 0) {
+	if (depth > 5 || error === null || error === void 0) return false;
+	const node = error;
+	if (node.name === "AbortError" || node.name === "TimeoutError") return true;
+	if (Array.isArray(node.errors) && node.errors.some((cause) => abortedBeforeResponse(cause, depth + 1))) return true;
+	return abortedBeforeResponse(node.cause, depth + 1);
+}
+/** Deadline for the reachability probe, short enough to precede a cleanup. */
+const BROKER_PROBE_TIMEOUT_MS = 250;
+/**
+* Whether the broker still answers HTTP at all. The endpoint is unauthenticated
+* and any response counts, so a live broker that rejects the request is still
+* reachable. Only a dial that never opened means the broker is gone: the
+* probe's own deadline, a reset, and every other transport failure are
+* inconclusive, so a slow broker that already processed the send still counts
+* as reachable and the caller withdraws rather than calling the ask gone.
+*/
+async function brokerReachable(env, fetchImpl) {
+	try {
+		await fetchImpl(`${env.brokerUrl}/health`, { signal: AbortSignal.timeout(BROKER_PROBE_TIMEOUT_MS) });
+		return true;
+	} catch (error) {
+		return !dialNeverOpened(error);
+	}
+}
+/**
+* Whether a failed send provably never reached the broker, mirroring the host's
+* rule: a dial that never opened or an unusable broker address carries no
+* request, and a send that drew no HTTP response while the broker no longer
+* accepts a dial cannot have left its edge in a broker that is gone. An HTTP
+* response, a reset, or an abort against a broker that answers at all may have
+* been processed and still needs a withdraw.
+*/
+async function sendNeverReachedBroker(error, env, fetchImpl) {
+	if (error instanceof BrokerHttpError) return false;
+	if (dialNeverOpened(error)) return true;
+	if (abortedBeforeResponse(error)) return false;
+	return !await brokerReachable(env, fetchImpl);
+}
+/**
+* Ask another run through the inherited broker as this run, then wait for the
+* correlated reply. A failed send, wait, timeout, or abort withdraws the ask
+* and reports its message id plus whether it is still pending, matching the
+* host-side ask tool's contract.
+*/
+async function askViaBroker(env, args, fetchImpl = fetch) {
+	const messageId = randomUUID();
+	const role = args.role ?? "agent";
+	const timeoutMs = normalizeAskTimeoutMs(args.timeoutMs);
+	const signal = combineSignals(args.signal, timeoutMs !== void 0 ? AbortSignal.timeout(timeoutMs) : void 0);
+	const fail = async (detail) => {
+		const pending = await withdrawAsk(env, messageId, fetchImpl);
+		throw new Error(formatAskFailure(messageId, pending, detail));
+	};
+	try {
+		await postBroker(env, "/send", buildAgentMessage({
+			fromRunId: env.runId,
+			toRunId: args.toRunId,
+			messageId,
+			message: args.message,
+			role,
+			expectsReply: true
+		}), fetchImpl, signal);
+	} catch (error) {
+		if (await sendNeverReachedBroker(error, env, fetchImpl)) throw new Error(formatAskFailure(messageId, false, `send ask: ${describeFailure(error)}`));
+		return fail(`send ask: ${describeFailure(error)}`);
+	}
+	let reply;
+	try {
+		reply = await postBroker(env, "/wait_reply", { waiting_for: messageId }, fetchImpl, signal);
+	} catch (error) {
+		return fail(`wait for reply: ${describeFailure(error)}`);
+	}
+	const record = reply && typeof reply === "object" ? reply : {};
+	return {
+		reply: extractReplyMessage(record),
+		from_run_id: record.from_run_id ?? ""
+	};
+}
 //#endregion
 //#region src/watch.ts
 const ANSI_PATTERN = /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
@@ -1426,33 +1594,9 @@ const defaultDeps = {
 	workflowReadyTool,
 	observeRun,
 	dial,
+	attachOwner,
 	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;
 }
@@ -1695,7 +1839,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 				subAgentPollTimer = null;
 			}
 		}
-		async function startSubAgentPoll(ctx) {
+		async function startSubAgentPoll() {
 			if (!subAgentEnv) return;
 			stopSubAgentPoll();
 			const generation = subAgentPollGeneration;
@@ -1704,6 +1848,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 			const tick = async () => {
 				try {
 					const msgs = await postBroker(subAgentEnv, "/poll-control", {}) ?? [];
+					if (generation !== subAgentPollGeneration) return;
 					if (consecutiveFailures >= 3) console.error("[avenor] sub-agent broker poll recovered");
 					consecutiveFailures = 0;
 					for (const msg of msgs) {
@@ -1713,7 +1858,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 							from_run_id: ask.from_run_id,
 							message_id: ask.message_id
 						});
-						await ctx.sendUserMessage(formatInboundAskBody(ask), { deliverAs: "steer" });
+						pi.sendUserMessage(formatInboundAskBody(ask), { deliverAs: "steer" });
 					}
 				} catch (error) {
 					consecutiveFailures++;
@@ -1726,6 +1871,40 @@ function createExtension(deps = defaultDeps, options = {}) {
 			subAgentPollTimer = setTimeout(() => void tick(), intervalMs);
 			subAgentPollTimer.unref?.();
 		}
+		let hostPollTimer = null;
+		let hostPollGeneration = 0;
+		const hostPendingAsks = /* @__PURE__ */ new Map();
+		function stopHostAskPoll() {
+			hostPollGeneration++;
+			if (hostPollTimer) {
+				clearTimeout(hostPollTimer);
+				hostPollTimer = null;
+			}
+		}
+		function startHostAskPoll() {
+			stopHostAskPoll();
+			const generation = hostPollGeneration;
+			const intervalMs = options.pollIntervalMs ?? 2e3;
+			const tick = async () => {
+				try {
+					const { asks } = await deps.brokerReceiveTool({});
+					if (generation !== hostPollGeneration) return;
+					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: "..." })`;
+						pi.sendUserMessage(body, { deliverAs: "steer" });
+					}
+				} catch {}
+				if (generation !== hostPollGeneration) return;
+				hostPollTimer = setTimeout(() => void tick(), intervalMs);
+				hostPollTimer.unref?.();
+			};
+			hostPollTimer = setTimeout(() => void tick(), intervalMs);
+			hostPollTimer.unref?.();
+		}
 		function recordPollingError(source, message, error, runId) {
 			pollingErrorCount++;
 			const payload = createPollErrorPayload({
@@ -2010,7 +2189,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 			}
 			async function withClient(run, work) {
 				if (!run.supervisorId || deps.Supervisor.isCurrentInstance(run.supervisorId)) return work((await deps.Supervisor.get()).getClient());
-				const client = await deps.dial(run.supervisorId);
+				const client = await deps.attachOwner(run.supervisorId);
 				try {
 					return await work(client);
 				} finally {
@@ -2198,15 +2377,15 @@ function createExtension(deps = defaultDeps, options = {}) {
 			lastStatusEntries = [];
 			pollingErrorCount = 0;
 			pollingErrors.length = 0;
-			startHostAskPoll(ctx);
-			startSubAgentPoll(ctx);
+			if (!isSubAgentBrokerMode) startHostAskPoll();
+			startSubAgentPoll();
 		});
 		pi.on("session_shutdown", async () => {
-			await stopPolling();
 			stopHostAskPoll();
 			stopSubAgentPoll();
 			hostPendingAsks.clear();
 			subAgentPendingAsks.clear();
+			await stopPolling();
 			for (const wait of [...pendingWaits]) {
 				pendingWaits.delete(wait);
 				wait.interrupt({
@@ -2735,15 +2914,27 @@ function createExtension(deps = defaultDeps, options = {}) {
 				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" }))
+				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path (ignored in a Pi sub-agent, which asks through its inherited broker)" }))
 			}),
-			async execute(_toolCallId, params) {
-				return askTool({
+			async execute(_toolCallId, params, signal) {
+				const result = isSubAgentBrokerMode && subAgentEnv ? await askViaBroker(subAgentEnv, {
+					toRunId: params.to_run_id,
+					message: params.message,
+					timeoutMs: params.timeout_ms,
+					signal
+				}) : await askTool({
 					toRunId: params.to_run_id,
 					message: params.message,
 					timeoutMs: params.timeout_ms,
 					supervisorId: params.supervisor_id
 				});
+				return {
+					content: [{
+						type: "text",
+						text: `Reply from ${result.from_run_id || params.to_run_id}:\n${result.reply}`
+					}],
+					details: result
+				};
 			}
 		});
 		pi.registerTool({
@@ -2766,23 +2957,19 @@ function createExtension(deps = defaultDeps, options = {}) {
 						}],
 						details: { error: true }
 					};
+					const generation = subAgentPollGeneration;
 					subAgentPendingAsks.delete(target.message_id);
 					try {
-						await postBroker(subAgentEnv, "/send", {
-							from_run_id: subAgentEnv.runId,
-							to_run_id: target.from_run_id,
-							type: "agent_message",
-							payload: {
-								id: randomUUID(),
-								from_run_id: subAgentEnv.runId,
-								to_run_id: target.from_run_id,
-								message: params.message,
-								role: "agent",
-								reply_to: target.message_id
-							}
-						});
+						await postBroker(subAgentEnv, "/send", buildAgentMessage({
+							fromRunId: subAgentEnv.runId,
+							toRunId: target.from_run_id,
+							messageId: randomUUID(),
+							message: params.message,
+							role: "agent",
+							replyTo: target.message_id
+						}));
 					} catch (error) {
-						subAgentPendingAsks.set(target.message_id, target);
+						if (generation === subAgentPollGeneration) subAgentPendingAsks.set(target.message_id, target);
 						throw error;
 					}
 					return { content: [{
@@ -2790,27 +2977,27 @@ function createExtension(deps = defaultDeps, options = {}) {
 						text: "Reply sent"
 					}] };
 				}
-				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 {
+				const target = resolveReplyTarget(hostPendingAsks, params.from_run_id, params.reply_to_message_id);
+				if (!target) 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);
+				const generation = hostPollGeneration;
+				hostPendingAsks.delete(target.message_id);
+				try {
+					await deps.brokerReplyTool({
+						toRunId: target.from_run_id,
+						replyTo: target.message_id,
+						message: params.message,
+						supervisorId: params.supervisor_id
+					});
+				} catch (error) {
+					if (generation === hostPollGeneration) hostPendingAsks.set(target.message_id, target);
+					throw error;
+				}
 				return { content: [{
 					type: "text",
 					text: "Reply sent"
@@ -2849,7 +3036,24 @@ function createExtension(deps = defaultDeps, options = {}) {
 			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 });
+				if (isSubAgentBrokerMode && subAgentEnv) {
+					await withdrawPendingAsk(subAgentEnv, params.message_id);
+					return {
+						content: [{
+							type: "text",
+							text: `Cancelled ${params.message_id}`
+						}],
+						details: { cancelled: true }
+					};
+				}
+				const result = await cancelTool({ messageId: params.message_id });
+				return {
+					content: [{
+						type: "text",
+						text: `Cancelled ${params.message_id}`
+					}],
+					details: result
+				};
 			}
 		});
 		pi.registerTool({

package/package.json

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