@dougbots/avenor-pi 0.10.4 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { InspectResult, StatusResult, Supervisor, answerPermissionTool, brokerReceiveTool, brokerReplyTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, workflowCompleteTool, 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,6 +1382,15 @@ 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
 const POLL_INTERVAL_MS = 3e3;
@@ -1349,6 +1418,8 @@ const defaultDeps = {
 	workflowEventsTool,
 	workflowCompleteTool,
 	workflowGateTool,
+	workflowControllerStatusTool,
+	workflowReadyTool,
 	observeRun,
 	dial,
 	Supervisor
@@ -2077,12 +2148,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" })),
@@ -2103,7 +2176,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)" }))
@@ -2331,10 +2404,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" }))
 			}),
@@ -2883,6 +2956,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.10.4",
+  "version": "0.12.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -35,7 +35,7 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "^0.10.4"
+    "@dougbots/avenor-core": "^0.12.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.74.0",