@dougbots/avenor-pi 0.10.3 → 0.11.0

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 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/subagent-broker.d.ts
+interface SubAgentEnv {
+  brokerUrl: string;
+  runId: string;
+  token: string;
+}
+//#endregion
 //#region src/types.d.ts
 interface RunStatusEntry {
   runId: string;
@@ -152,6 +159,8 @@ declare function buildInspectPayload(result: InspectResult): Record<string, unkn
 interface ExtensionOptions {
   /** Polling cadence; injectable so tests can drive deterministic ticks. */
   pollIntervalMs?: number;
+  /** Overrides broker-credential autodetection for sub-agent broker mode (tests). */
+  subAgentEnv?: SubAgentEnv | null;
 }
 declare function createExtension(deps?: ExtensionDeps, options?: ExtensionOptions): (pi: ExtensionAPI) => Promise<void>;
 declare const _default: (pi: ExtensionAPI) => Promise<void>;

package/dist/index.js

@@ -1,9 +1,78 @@
 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 * as fs from "node:fs";
 import * as path from "node:path";
-import { createHash } from "node:crypto";
+//#region src/subagent-broker.ts
+function readSubAgentEnv(env = process.env) {
+	const brokerUrl = env.AVENOR_BROKER_URL ?? "";
+	const runId = env.AVENOR_RUN_ID ?? "";
+	const token = env.AVENOR_BROKER_TOKEN ?? "";
+	if (brokerUrl && runId && token) return {
+		brokerUrl,
+		runId,
+		token
+	};
+	return null;
+}
+/** Parse a broker control message that is an agent_message into an InboundAsk. */
+function parseControlMessage(msg) {
+	if (msg.type !== "agent_message") return null;
+	let payload = msg.payload;
+	if (typeof payload === "string") try {
+		payload = JSON.parse(payload);
+	} catch {
+		return null;
+	}
+	const p = payload;
+	if (!p || typeof p.message !== "string" || !p.message) return null;
+	const messageId = String(p.id ?? "");
+	if (!messageId) return null;
+	const fromRunId = String(p.from_run_id ?? p.from ?? "");
+	if (!fromRunId) return null;
+	return {
+		from_run_id: fromRunId,
+		message_id: messageId,
+		message: p.message
+	};
+}
+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) {
+	const res = await fetchImpl(`${env.brokerUrl}${path}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			run_id: env.runId,
+			token: env.token,
+			...body
+		})
+	});
+	if (!res.ok) throw new Error(`broker ${path}: ${res.status} ${(await res.text()).trim()}`);
+	return res.json();
+}
+/**
+* Resolve which pending ask to answer. Prefers an explicit message id (and its
+* asker); otherwise the most recent pending ask matching fromRunId.
+*/
+function resolveReplyTarget(pending, fromRunId, replyToMessageId) {
+	if (replyToMessageId) {
+		const hit = pending.get(replyToMessageId);
+		if (!hit) return null;
+		const from = fromRunId ?? hit.from_run_id;
+		if (!from) return null;
+		return {
+			from_run_id: from,
+			message_id: replyToMessageId
+		};
+	}
+	let match;
+	for (const [, entry] of pending) if (!fromRunId || entry.from_run_id === fromRunId) match = entry;
+	return match ?? null;
+}
+//#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;
 const TRANSCRIPT_SCROLL_STEP = 4;
@@ -1457,6 +1526,49 @@ function createExtension(deps = defaultDeps, options = {}) {
 		let pollingErrorCount = 0;
 		const pollingErrors = [];
 		let lastStatusEntries = [];
+		const subAgentEnv = options.subAgentEnv !== void 0 ? options.subAgentEnv : readSubAgentEnv();
+		const isSubAgentBrokerMode = subAgentEnv !== null;
+		let subAgentPollTimer = null;
+		let subAgentPollGeneration = 0;
+		const subAgentPendingAsks = /* @__PURE__ */ new Map();
+		function stopSubAgentPoll() {
+			subAgentPollGeneration++;
+			if (subAgentPollTimer) {
+				clearTimeout(subAgentPollTimer);
+				subAgentPollTimer = null;
+			}
+		}
+		async function startSubAgentPoll(ctx) {
+			if (!subAgentEnv) return;
+			stopSubAgentPoll();
+			const generation = subAgentPollGeneration;
+			const intervalMs = options.pollIntervalMs ?? 2e3;
+			let consecutiveFailures = 0;
+			const tick = async () => {
+				try {
+					const msgs = await postBroker(subAgentEnv, "/poll-control", {}) ?? [];
+					if (consecutiveFailures >= 3) console.error("[avenor] sub-agent broker poll recovered");
+					consecutiveFailures = 0;
+					for (const msg of msgs) {
+						const ask = parseControlMessage(msg);
+						if (!ask) continue;
+						subAgentPendingAsks.set(ask.message_id, {
+							from_run_id: ask.from_run_id,
+							message_id: ask.message_id
+						});
+						await ctx.sendUserMessage(formatInboundAskBody(ask), { deliverAs: "steer" });
+					}
+				} catch (error) {
+					consecutiveFailures++;
+					if (consecutiveFailures === 3) console.error("[avenor] sub-agent broker poll failing:", error instanceof Error ? error.message : error);
+				}
+				if (generation !== subAgentPollGeneration) return;
+				subAgentPollTimer = setTimeout(() => void tick(), intervalMs);
+				subAgentPollTimer.unref?.();
+			};
+			subAgentPollTimer = setTimeout(() => void tick(), intervalMs);
+			subAgentPollTimer.unref?.();
+		}
 		function recordPollingError(source, message, error, runId) {
 			pollingErrorCount++;
 			const payload = createPollErrorPayload({
@@ -1925,11 +2037,14 @@ function createExtension(deps = defaultDeps, options = {}) {
 			pollingErrorCount = 0;
 			pollingErrors.length = 0;
 			startHostAskPoll(ctx);
+			startSubAgentPoll(ctx);
 		});
 		pi.on("session_shutdown", async () => {
 			await stopPolling();
 			stopHostAskPoll();
+			stopSubAgentPoll();
 			hostPendingAsks.clear();
+			subAgentPendingAsks.clear();
 			sessionCtx = null;
 		});
 		pi.on("before_agent_start", async () => {
@@ -1962,12 +2077,14 @@ function createExtension(deps = defaultDeps, options = {}) {
 			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 with view \"lifecycle\" only to check progress or pending permissions.",
-				"Use avenor_result to wait for and retrieve a sub-agent final result.",
+				"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_inspect to review a bounded transcript and tool activity from a run.",
-				"Use avenor_events only when raw event payloads are specifically needed.",
+				"Use avenor_events only when you specifically need raw event payloads.",
 				"Use avenor_follow_up to iterate on a completed run.",
-				"Use avenor_shutdown when done delegating work."
+				"Use avenor_shutdown when done delegating work.",
+				"When roster_entry is set, the roster selects agent, model, and backend; do not pass those fields alongside it.",
+				"If a roster spawn fails validation or resolution, do not retry the roster: respawn without roster_file/roster_entry. Direct selectors (agent, model, backend) are optional; omission uses runtime defaults."
 			],
 			parameters: Type.Object({
 				agent: Type.Optional(Type.String({ description: "Optional agent name; omission uses the supplied model or runtime defaults" })),
@@ -1988,7 +2105,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 				], { description: "Thinking level; omission uses the backend default" })),
 				backend: Type.Optional(Type.String({ description: "Backend override (defaults to pi for direct mode)" })),
 				roster_file: Type.Optional(Type.String({ description: "Path to the roster map" })),
-				roster_entry: Type.Optional(Type.String({ description: "Roster entry to select" })),
+				roster_entry: Type.Optional(Type.String({ description: "Roster entry to select. Requires roster_file unless a roster context is configured; disables agent, model, and backend" })),
 				server_url: Type.Optional(Type.String({ description: "Backend server URL" })),
 				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" })),
 				wait: Type.Optional(Type.Boolean({ description: "Block until complete (default true)" }))
@@ -2216,10 +2333,10 @@ function createExtension(deps = defaultDeps, options = {}) {
 		pi.registerTool({
 			name: "avenor_result",
 			label: "Avenor Result",
-			description: "Wait for a run to finish and return its complete final output without transcript or event details.",
+			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.",
 			parameters: Type.Object({
-				run_id: Type.String({ description: "Run ID to await" }),
-				wait: Type.Optional(Type.Boolean({ description: "Wait for a terminal result (default true)" })),
+				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" })),
 				timeout: Type.Optional(Type.String({ description: "Maximum time to wait (e.g. 30s, 5m)" })),
 				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
 			}),
@@ -2426,6 +2543,39 @@ function createExtension(deps = defaultDeps, options = {}) {
 				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
 			}),
 			async execute(_toolCallId, params) {
+				if (isSubAgentBrokerMode && subAgentEnv) {
+					const target = resolveReplyTarget(subAgentPendingAsks, 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 }
+					};
+					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
+							}
+						});
+					} catch (error) {
+						subAgentPendingAsks.set(target.message_id, target);
+						throw error;
+					}
+					return { content: [{
+						type: "text",
+						text: "Reply sent"
+					}] };
+				}
 				let fromRunId = params.from_run_id;
 				let messageId = params.reply_to_message_id;
 				if (!messageId) {

package/package.json

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