@dougbots/avenor-pi 0.4.0 → 0.5.0

package/README.md

@@ -112,7 +112,9 @@ Available tools for LLM sub-agent management:
 | Tool | Description |
 |---|---|
 | `avenor_spawn` | Dispatch an agent run (blocking or fire-and-forget). Accepts `agent` (optional, maps to a named profile in `agents.json`), `model`, `prompt`, and `dir`. |
-| `avenor_status` | Get status of a run or all runs |
+| `avenor_status` | Get status of a run or all runs; use `view="lifecycle"` for compact progress and permission checks |
+| `avenor_result` | Wait for a run and return its bounded final output without transcript details |
+| `avenor_inspect` | Review a bounded transcript, tool activity, permissions, and final output |
 | `avenor_answer_permission` | Answer a pending permission request |
 | `avenor_follow_up` | Resume a completed run with a follow-up message |
 | `avenor_events` | Read events from a run |
@@ -154,18 +156,20 @@ If you don't need a named profile, `model` alone is sufficient — no agent conf
 **Blocking (default):**
 ```
 1. avenor_spawn            →  tool call shows live progress, blocks until done
-2. tool call returns       →  structured result with status + session_id
-3. avenor_events           →  inspect detailed output
-4. avenor_follow_up        →  optionally iterate
-5. avenor_shutdown         →  clean up when finished
+2. tool call returns       →  completion preview with status + session_id
+3. avenor_result           →  retrieve the bounded final output when needed
+4. avenor_inspect          →  inspect transcript and tool details when needed
+5. avenor_follow_up        →  optionally iterate
+6. avenor_shutdown         →  clean up when finished
 ```
 
 **Parallel / fire-and-forget (`wait=false`):**
 ```
 1. avenor_spawn × N        →  each returns run_id immediately
 2. (status widget updates) →  persistent widget shows all active runs
-3. /avenor-watch <id>      →  open live event feed for a specific run
-4. avenor_events           →  inspect output when done
+3. avenor_status           →  optional compact lifecycle/permission check
+4. avenor_result           →  wait for and retrieve each final output
+5. /avenor-watch <id>      →  open live diagnostics for a specific run
 ```
 
 ## Dependencies

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { InspectResult, StatusResult, Supervisor, answerPermissionTool, dial, eventsTool, followUpTool, inspectTool, observeRun, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { InspectResult, StatusResult, Supervisor, answerPermissionTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
 import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 //#region src/types.d.ts
@@ -21,6 +21,7 @@ interface ExtensionDeps {
   answerPermissionTool: typeof answerPermissionTool;
   followUpTool: typeof followUpTool;
   inspectTool: typeof inspectTool;
+  resultTool: typeof resultTool;
   shutdownTool: typeof shutdownTool;
   observeRun: typeof observeRun;
   dial: typeof dial;

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, followUpTool, inspectTool, observeRun, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { Supervisor, answerPermissionTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
 //#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;
@@ -469,22 +469,44 @@ var RunInspectorOverlay = class {
 		return lines.map((line) => truncateToWidth(line, innerWidth));
 	}
 };
+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];
+	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)}`;
+}
+async function selectWatchRun(ctx, runs) {
+	const choices = runs.map(watchRunChoice);
+	const selected = await ctx.ui.select("Watch run:", choices);
+	if (!selected) return void 0;
+	return runs.find((_run, index) => choices[index] === selected);
+}
 async function openRunInspector(ctx, options) {
 	if (!ctx.hasUI) {
 		ctx.ui.notify("avenor-watch requires TUI mode", "warning");
 		return;
 	}
-	let runId = options.initialRunId?.trim();
-	if (!runId) {
+	const selector = options.initialRunId?.trim();
+	let tracked;
+	let runId;
+	if (selector) {
+		const matches = matchingWatchRuns(options.trackedRuns, selector);
+		tracked = matches.length === 1 ? matches[0] : matches.length > 1 ? await selectWatchRun(ctx, matches) : void 0;
+		if (matches.length > 1 && !tracked) return;
+		runId = tracked?.runId ?? selector;
+	} else {
 		if (options.trackedRuns.length === 0) {
 			ctx.ui.notify("No tracked runs", "warning");
 			return;
 		}
-		const selected = await ctx.ui.select("Watch run:", options.trackedRuns.map((run) => run.runId));
-		if (!selected) return;
-		runId = selected;
+		tracked = await selectWatchRun(ctx, options.trackedRuns);
+		if (!tracked) return;
+		runId = tracked.runId;
 	}
-	const tracked = options.trackedRuns.find((run) => run.runId === runId);
 	await ctx.ui.custom((tui, theme, keybindings, done) => new RunInspectorOverlay(tui, theme, keybindings, options.deps, tracked ?? { runId }, () => done(), options.onTrackRun), {
 		overlay: true,
 		overlayOptions: {
@@ -497,6 +519,15 @@ async function openRunInspector(ctx, options) {
 }
 //#endregion
 //#region src/types.ts
+function findLiveStatusForTrackedRun(run, liveStatuses) {
+	const knownRunIds = new Set([run.runId, run.lastStatus?.run_id].filter((id) => !!id));
+	let runtimeMatch;
+	for (const status of liveStatuses) {
+		if (knownRunIds.has(status.run_id)) return status;
+		if (!run.supervisorId && run.runtimeId === status.runtime_id) runtimeMatch = status;
+	}
+	return runtimeMatch;
+}
 const TERMINAL_STATUSES = new Set([
 	"done",
 	"failed",
@@ -537,6 +568,7 @@ const defaultDeps = {
 	answerPermissionTool,
 	followUpTool,
 	inspectTool,
+	resultTool,
 	shutdownTool,
 	observeRun,
 	dial,
@@ -699,7 +731,7 @@ function createExtension(deps = defaultDeps) {
 			}
 			const entries = [];
 			for (const run of trackedRuns.values()) {
-				const live = liveMap.get(run.runId);
+				const live = findLiveStatusForTrackedRun(run, liveMap.values());
 				if (live) {
 					liveMap.delete(live.run_id);
 					run.lastStatus = live;
@@ -1070,11 +1102,12 @@ function createExtension(deps = defaultDeps) {
 			name: "avenor_spawn",
 			label: "Avenor Spawn",
 			description: "Dispatch an agent run via avenor. Blocks by default, showing live progress. Set wait=false for fire-and-forget.",
-			promptSnippet: "Dispatch sub-agent runs via avenor (spawn, status, inspect, events, follow-up, shutdown)",
+			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 to check progress of fire-and-forget runs.",
-				"Use avenor_inspect to review a bounded transcript, tools, and final output from a run.",
+				"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_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_follow_up to iterate on a completed run.",
 				"Use avenor_shutdown when done delegating work."
@@ -1125,7 +1158,7 @@ function createExtension(deps = defaultDeps) {
 				if (!wait) return {
 					content: [{
 						type: "text",
-						text: `Dispatched "${label}" (run_id: ${result.run_id}). Call avenor_status to check progress or avenor_inspect for a bounded transcript snapshot.`
+						text: `Dispatched "${label}" (run_id: ${result.run_id}). Completion will be delivered automatically; use avenor_status with view "lifecycle" for progress or avenor_result to wait for the final result.`
 					}],
 					details: {
 						run_id: result.run_id,
@@ -1242,15 +1275,21 @@ function createExtension(deps = defaultDeps) {
 		pi.registerTool({
 			name: "avenor_status",
 			label: "Avenor Status",
-			description: "Get status of a run or all runs. Surfaces pending permission requests.",
+			description: "Get lifecycle status of a run or all runs. Use view=\"lifecycle\" for compact polling; full is the compatibility default.",
 			parameters: Type.Object({
 				run_id: Type.Optional(Type.String({ description: "Specific run ID to query" })),
+				view: Type.Optional(Type.Unsafe({
+					type: "string",
+					enum: ["lifecycle", "full"],
+					description: "Response detail (default full for compatibility)"
+				})),
 				supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
 			}),
 			async execute(_toolCallId, params) {
 				const result = await deps.statusTool({
 					runId: params.run_id,
-					supervisorId: params.supervisor_id
+					supervisorId: params.supervisor_id,
+					view: params.view
 				});
 				return {
 					content: [{
@@ -1261,6 +1300,44 @@ function createExtension(deps = defaultDeps) {
 				};
 			}
 		});
+		pi.registerTool({
+			name: "avenor_result",
+			label: "Avenor Result",
+			description: "Wait for a run to finish and return its bounded final output without transcript or event details.",
+			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)" })),
+				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" }))
+			}),
+			async execute(_toolCallId, params, signal) {
+				const tracked = trackedRuns.get(params.run_id);
+				const previousBlocking = tracked?.blocking;
+				if (tracked) tracked.blocking = true;
+				let completed = false;
+				try {
+					const result = await deps.resultTool({
+						runId: params.run_id,
+						supervisorId: params.supervisor_id,
+						wait: params.wait,
+						timeout: params.timeout,
+						signal
+					});
+					completed = result.ready;
+					if (completed) trackedRuns.delete(params.run_id);
+					else if (tracked && result.status === "waiting") tracked.permissionNotified = true;
+					return {
+						content: [{
+							type: "text",
+							text: JSON.stringify(result, null, 2)
+						}],
+						details: result
+					};
+				} finally {
+					if (!completed && tracked && trackedRuns.get(params.run_id) === tracked) tracked.blocking = previousBlocking ?? false;
+				}
+			}
+		});
 		pi.registerTool({
 			name: "avenor_inspect",
 			label: "Avenor Inspect",
@@ -1422,11 +1499,11 @@ function createExtension(deps = defaultDeps) {
 			}
 		});
 		pi.registerCommand("avenor-watch", {
-			description: "Open a live run inspector for an avenor run",
+			description: "Open a live run inspector by run ID, label, or agent name",
 			getArgumentCompletions: (prefix) => {
-				const items = Array.from(trackedRuns.values()).filter((run) => run.label.startsWith(prefix) || run.runId.startsWith(prefix)).map((run) => ({
+				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: `${run.label} (${run.runId.slice(0, 8)})`
+					label: `${sanitizeText(run.label)} (${sanitizeText(run.agent)}, ${sanitizeText(run.runId).slice(0, 8)})`
 				}));
 				return items.length > 0 ? items : null;
 			},
@@ -1448,9 +1525,9 @@ 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.runId.startsWith(prefix)).map((run) => ({
+				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: `${run.label} (${run.runId.slice(0, 8)})`
+					label: `${sanitizeText(run.label)} (${sanitizeText(run.agent)}, ${sanitizeText(run.runId).slice(0, 8)})`
 				}));
 				return items.length > 0 ? items : null;
 			},

package/package.json

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