@dougbots/avenor-pi 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# @dougbots/avenor-pi
+
+Pi extension that registers avenor agent runs as tools in your Pi session. When you need a sub-agent to handle a well-defined task — write code, run tests, search a codebase — avenor operates in the background while you keep your session focused.
+
+## Prerequisites
+
+You need the `avenor` binary available. It is installed to `~/.botfiles/bin/avenor` by default.
+
+```bash
+# Check it's on PATH
+which avenor
+
+# Or set explicitly
+export AVENOR_BIN=~/.botfiles/bin/avenor
+```
+
+## Installation
+
+### From npm (once published)
+
+```bash
+pi install npm:@dougbots/avenor-pi
+```
+
+This writes to your global settings (`~/.pi/agent/settings.json`). Use `-l` for project-local installation (`.pi/settings.json`).
+
+### From a git repo
+
+```bash
+pi install git:github.com/sdougbrown/avenor@v0.1.0
+```
+
+Pi will clone the repo and load the extension from `packages/pi`.
+
+### Local development
+
+**Quick test** — run pi with the extension directly:
+
+```bash
+cd packages/pi
+pi -e ./src/index.ts
+```
+
+**Symlink for auto-discovery** — link into your global extensions directory:
+
+```bash
+mkdir -p ~/.pi/agent/extensions/avenor
+ln -sf $(pwd)/packages/pi/src/index.ts ~/.pi/agent/extensions/avenor/index.ts
+```
+
+Pi auto-discovers `~/.pi/agent/extensions/*/index.ts`. Changes are hot-reloadable with `/reload`.
+
+**Local path in settings** — add the built dist directly:
+
+```bash
+# Build first
+cd packages/pi && bun run build
+
+# Add to settings
+pi install /path/to/avenor/packages/pi
+```
+
+### Manual settings.json
+
+If you prefer to edit settings directly:
+
+```json
+// ~/.pi/agent/settings.json
+{
+  "packages": ["npm:@dougbots/avenor-pi"]
+}
+```
+
+Or for a local path:
+
+```json
+{
+  "packages": ["/path/to/avenor/packages/pi"]
+}
+```
+
+## Package Structure
+
+```
+packages/pi/
+├── package.json
+├── tsdown.config.ts
+├── src/
+│   ├── index.ts          # main extension (tools, commands, hooks, rendering)
+│   ├── types.ts          # shared types, status emoji mapping
+│   └── watch.ts          # EventFeedOverlay TUI component
+└── dist/
+    └── index.js          # built output (loaded by pi)
+```
+
+The `pi` key in `package.json` declares the extension entry point:
+
+```json
+{
+  "pi": {
+    "extensions": ["./dist/index.js"]
+  }
+}
+```
+
+## Features
+
+### Tools
+
+Six tools for the LLM to dispatch and manage sub-agents:
+
+| Tool | Description |
+|---|---|
+| `avenor_spawn` | Dispatch an agent run (blocking or fire-and-forget) |
+| `avenor_status` | Get status of a run or all runs |
+| `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 |
+| `avenor_shutdown` | Shut down the avenor supervisor |
+
+### Pi-specific features
+
+Beyond the tools, the extension integrates with Pi's TUI and event system:
+
+- **Status widget** — persistent widget showing all active runs with status, phase, and permission state
+- **Footer status** — active runs shown in the Pi footer bar
+- **Live progress** — blocking `avenor_spawn` calls stream progress updates via `onUpdate`
+- **Context enrichment** — active sub-agents are automatically surfaced in the system prompt via `before_agent_start`
+- **Custom rendering** — tool calls and results are rendered with status emojis and color-coded output
+- **Commands** — interactive commands for run management:
+  - `/avenor-status` — show status of all runs
+  - `/avenor-watch <run_id>` — open a live event feed overlay
+  - `/avenor-cancel <run_id>` — cancel a running sub-agent
+
+## Typical workflows
+
+**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
+```
+
+**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
+```
+
+## Dependencies
+
+- **Peer:** `@earendil-works/pi-coding-agent` (Pi runtime, provided by pi)
+- **Peer:** `@earendil-works/pi-tui` (TUI components, provided by pi)
+- **Dependency:** `@dougbots/avenor-core` (supervisor, client, tool primitives)
+- **Binary:** `avenor` must be available on `PATH` or at `AVENOR_BIN`

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+//#region src/index.d.ts
+declare function export_default(pi: ExtensionAPI): Promise<void>;
+//#endregion
+export { export_default as default };

package/dist/index.js

@@ -0,0 +1,618 @@
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { answerPermissionTool, eventsTool, followUpTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+//#region src/watch.ts
+var EventFeedOverlay = class {
+	_events = [];
+	_runId;
+	_onClose;
+	_maxLines = 50;
+	constructor(runId, onClose) {
+		this._runId = runId;
+		this._onClose = onClose ?? (() => {});
+	}
+	setOnClose(fn) {
+		this._onClose = fn;
+	}
+	setEvents(events) {
+		this._events = events.slice(-this._maxLines);
+	}
+	appendEvent(event) {
+		this._events.push(event);
+		if (this._events.length > this._maxLines) this._events = this._events.slice(-this._maxLines);
+	}
+	render(width) {
+		const lines = [];
+		const header = `📡 avenor watch: ${this._runId.slice(0, 8)}… (Esc to close)`;
+		lines.push(header);
+		lines.push("─".repeat(Math.min(width, header.length)));
+		if (this._events.length === 0) lines.push("  (waiting for events…)");
+		else for (const evt of this._events) {
+			const ts = new Date(evt.ts).toISOString().slice(11, 19);
+			const type = evt.type ?? "unknown";
+			const extra = this.summarizeEvent(evt);
+			lines.push(`  ${ts} ${type}${extra ? ` — ${extra}` : ""}`);
+		}
+		return lines;
+	}
+	handleInput(data) {
+		if (data === "\x1B") this._onClose();
+	}
+	summarizeEvent(evt) {
+		if (evt.type === "tool.call" || evt.type === "tool.use") return `called ${String(evt.tool ?? evt.name ?? "")}`;
+		if (evt.type === "agent.message_chunk") return "thinking…";
+		if (evt.type?.startsWith("permission.")) return "permission requested";
+		if (evt.type === "tool.result") {
+			const result = evt.result;
+			if (typeof result === "string" && result.length < 80) return result;
+			return "completed";
+		}
+		return "";
+	}
+	invalidate() {}
+};
+//#endregion
+//#region src/types.ts
+const TERMINAL_STATUSES = new Set([
+	"done",
+	"failed",
+	"timeout",
+	"killed"
+]);
+const STATUS_EMOJI = {
+	running: "🟢",
+	idle: "🟡",
+	done: "✅",
+	failed: "❌",
+	timeout: "⏱️",
+	killed: "💀",
+	permission: "🔒"
+};
+function statusEmoji(status) {
+	return STATUS_EMOJI[status] ?? "⚪";
+}
+function formatRunLine(entry) {
+	const emoji = statusEmoji(entry.status);
+	const perm = entry.pendingPermission ? ` — blocked: ${entry.permissionDescription ?? "permission"}` : "";
+	const phase = entry.phaseLabel ? ` (${entry.phaseLabel})` : "";
+	return `${emoji} ${entry.label} (${entry.agent}) — ${entry.status}${phase}${perm}`;
+}
+//#endregion
+//#region src/index.ts
+const POLL_INTERVAL_MS = 3e3;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function buildCompletionText(run, result) {
+	const lines = [`Sub-agent "${run.label}" finished with status **${result.status}**.`];
+	if (result.stop_reason && result.stop_reason.toUpperCase() !== result.status.toUpperCase()) lines.push(`Stop reason: ${result.stop_reason}`);
+	if (result.session_id) lines.push(`Session: \`${result.session_id}\``);
+	lines.push(`\nCall \`avenor_events\` with \`run_id: "${run.runId}"\` to review the output, or \`avenor_follow_up\` to iterate.`);
+	return lines.join("\n");
+}
+function summarizeEvent(evt) {
+	const type = String(evt.type ?? evt.event ?? "");
+	if (type === "tool.call" || type === "tool.use") return `called ${String(evt.tool ?? evt.name ?? type)}`;
+	if (type === "agent.message_chunk") return "thinking…";
+	if (type.startsWith("permission.")) return `permission requested`;
+	return type;
+}
+async function src_default(pi) {
+	const trackedRuns = /* @__PURE__ */ new Map();
+	let pollingActive = false;
+	let sessionCtx = null;
+	async function pollRuns() {
+		let raw;
+		try {
+			raw = await statusTool({});
+		} catch (err) {
+			console.error("avenor pollRuns: statusTool failed", err);
+			return [];
+		}
+		const results = Array.isArray(raw) ? raw : [raw];
+		const entries = [];
+		for (const r of results) {
+			const run = trackedRuns.get(r.run_id);
+			if (run) run.lastStatus = r;
+			entries.push({
+				runId: r.run_id,
+				label: r.label,
+				status: r.status,
+				phase: r.phase,
+				phaseLabel: r.phase_label,
+				agent: trackedRuns.get(r.run_id)?.agent ?? "unknown",
+				pendingPermission: !!r.pending_permission,
+				permissionDescription: r.pending_permission?.description
+			});
+		}
+		return entries;
+	}
+	function renderStatusLines(entries) {
+		const active = entries.filter((e) => !TERMINAL_STATUSES.has(e.status));
+		if (active.length === 0) return [];
+		return active.map((e) => {
+			const emoji = statusEmoji(e.status);
+			const perm = e.pendingPermission ? ` 🔒` : "";
+			const phase = e.phaseLabel ? ` [${e.phaseLabel}]` : "";
+			return `${emoji} ${e.label} — ${e.status}${phase}${perm}`;
+		});
+	}
+	function updateWidget(entries) {
+		if (!sessionCtx) return;
+		const lines = renderStatusLines(entries);
+		if (lines.length > 0) {
+			sessionCtx.ui.setWidget("avenor-status", lines);
+			const parts = lines.map((l) => l.slice(0, 60));
+			sessionCtx.ui.setStatus("avenor", parts.join("  "));
+		} else {
+			sessionCtx.ui.setWidget("avenor-status", void 0);
+			sessionCtx.ui.setStatus("avenor", "");
+		}
+	}
+	function startPolling() {
+		if (pollingActive) return;
+		pollingActive = true;
+		const tick = async () => {
+			const prevStatuses = /* @__PURE__ */ new Map();
+			for (const [id, run] of trackedRuns) prevStatuses.set(id, run.lastStatus?.status);
+			const entries = await pollRuns();
+			updateWidget(entries);
+			for (const entry of entries) if (TERMINAL_STATUSES.has(entry.status)) {
+				if (trackedRuns.get(entry.runId)) {
+					const prevStatus = prevStatuses.get(entry.runId);
+					if (prevStatus && !TERMINAL_STATUSES.has(prevStatus)) sessionCtx?.ui.notify(`Sub-agent "${entry.label}" finished: ${entry.status}`, entry.status === "done" ? "info" : "warning");
+					trackedRuns.delete(entry.runId);
+				}
+			}
+			if (entries.some((e) => !TERMINAL_STATUSES.has(e.status))) setTimeout(tick, POLL_INTERVAL_MS);
+			else {
+				pollingActive = false;
+				sessionCtx?.ui.setStatus("avenor", "");
+				sessionCtx?.ui.setWidget("avenor-status", void 0);
+			}
+		};
+		tick();
+	}
+	pi.on("session_start", async (_event, ctx) => {
+		sessionCtx = ctx;
+	});
+	pi.on("session_shutdown", async (_event, _ctx) => {
+		pollingActive = false;
+		sessionCtx = null;
+	});
+	pi.on("before_agent_start", async (event, _ctx) => {
+		if (trackedRuns.size === 0) return;
+		const active = (await pollRuns()).filter((e) => !TERMINAL_STATUSES.has(e.status));
+		if (active.length === 0) return;
+		return { message: {
+			customType: "avenor-active-runs",
+			content: `Active sub-agents:\n${active.map((e) => {
+				const perm = e.pendingPermission ? ` [blocked: ${e.permissionDescription ?? "permission"}]` : "";
+				const phase = e.phaseLabel ? ` (${e.phaseLabel})` : "";
+				return `  • ${e.label} (${e.agent}): ${e.status}${phase}${perm}`;
+			}).join("\n")}`,
+			display: true
+		} };
+	});
+	pi.registerMessageRenderer("avenor-active-runs", (message, options, theme) => {
+		const lines = message.content.split("\n");
+		let text = "";
+		for (let i = 0; i < lines.length; i++) {
+			if (i === 0) text += theme.fg("info", theme.bold(lines[i]));
+			else text += theme.fg("muted", lines[i]);
+			if (i < lines.length - 1) text += "\n";
+		}
+		return new Text(text, 0, 0);
+	});
+	pi.registerTool({
+		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, 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_events to inspect detailed output from a run.",
+			"Use avenor_follow_up to iterate on a completed run.",
+			"Use avenor_shutdown when done delegating work."
+		],
+		parameters: Type.Object({
+			agent: Type.String({ description: "Agent name (required, no default)" }),
+			prompt: Type.Optional(Type.String({ description: "Prompt text" })),
+			prompt_file: Type.Optional(Type.String({ description: "Path to prompt file" })),
+			dir: Type.Optional(Type.String({ description: "Working directory (defaults to session directory)" })),
+			label: Type.Optional(Type.String({ description: "Human-readable label for the run" })),
+			timeout: Type.Optional(Type.String({ description: "Timeout duration (e.g. 3600s)" })),
+			model: Type.Optional(Type.String({ description: "Model override" })),
+			backend: Type.Optional(Type.String({ description: "Backend override" })),
+			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)" }))
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			if (signal?.aborted) return { content: [{
+				type: "text",
+				text: "Cancelled"
+			}] };
+			const wait = params.wait ?? true;
+			const dir = params.dir ?? ctx.cwd;
+			const label = params.label ?? `${params.agent}-${Date.now()}`;
+			const result = await spawnTool({
+				agent: params.agent,
+				prompt: params.prompt,
+				promptFile: params.prompt_file,
+				label,
+				dir,
+				timeout: params.timeout,
+				model: params.model,
+				backend: params.backend,
+				serverUrl: params.server_url,
+				supervisorId: params.supervisor_id
+			});
+			trackedRuns.set(result.run_id, {
+				runId: result.run_id,
+				agent: params.agent,
+				label,
+				supervisorId: result.supervisor_id,
+				startTime: Date.now()
+			});
+			startPolling();
+			if (!wait) return {
+				content: [{
+					type: "text",
+					text: `Dispatched "${label}" (run_id: ${result.run_id}). Call avenor_status to check progress.`
+				}],
+				details: {
+					run_id: result.run_id,
+					label
+				}
+			};
+			onUpdate?.({
+				content: [{
+					type: "text",
+					text: `Starting ${label}…`
+				}],
+				details: {
+					status: "running",
+					run_id: result.run_id
+				}
+			});
+			let firstPoll = true;
+			while (!signal?.aborted) {
+				if (!firstPoll) await sleep(POLL_INTERVAL_MS);
+				firstPoll = false;
+				let raw;
+				try {
+					raw = await statusTool({
+						runId: result.run_id,
+						supervisorId: result.supervisor_id
+					});
+				} catch (err) {
+					console.error("avenor spawn poll: statusTool failed", err);
+					continue;
+				}
+				const status = Array.isArray(raw) ? raw[0] : raw;
+				if (!status) continue;
+				if (status.pending_permission) onUpdate?.({
+					content: [{
+						type: "text",
+						text: `[blocked] ${label} — permission: ${status.pending_permission.description}`
+					}],
+					details: {
+						status: "permission",
+						run_id: result.run_id
+					}
+				});
+				else {
+					let lastAction = "";
+					if (!result.supervisor_id) try {
+						const eventsResult = await eventsTool({
+							runId: result.run_id,
+							limit: 3
+						});
+						const last = eventsResult.events[eventsResult.events.length - 1];
+						if (last) lastAction = summarizeEvent(last);
+					} catch (err) {
+						console.error("avenor spawn poll: eventsTool failed", err);
+					}
+					onUpdate?.({
+						content: [{
+							type: "text",
+							text: `${label}${status.phase_label ? ` (${status.phase_label})` : ""}${lastAction ? ` — ${lastAction}` : ""}`
+						}],
+						details: {
+							status: status.status,
+							run_id: result.run_id,
+							lastAction
+						}
+					});
+				}
+				if (TERMINAL_STATUSES.has(status.status)) {
+					trackedRuns.delete(result.run_id);
+					return {
+						content: [{
+							type: "text",
+							text: buildCompletionText({
+								runId: result.run_id,
+								label
+							}, status)
+						}],
+						details: {
+							status: status.status,
+							run_id: result.run_id,
+							session_id: status.session_id
+						}
+					};
+				}
+			}
+			trackedRuns.delete(result.run_id);
+			return {
+				content: [{
+					type: "text",
+					text: `Monitoring of "${label}" (run_id: ${result.run_id}) was interrupted. Use avenor_status to check.`
+				}],
+				details: { run_id: result.run_id }
+			};
+		},
+		renderCall(args, theme) {
+			const agent = theme.fg("toolTitle", theme.bold("avenor_spawn "));
+			const agentName = theme.fg("accent", args.agent);
+			const label = args.label ? theme.fg("dim", ` "${args.label}"`) : "";
+			const wait = args.wait === false ? theme.fg("warning", " [async]") : "";
+			return new Text(agent + agentName + label + wait, 0, 0);
+		},
+		renderResult(result, { isPartial }, theme) {
+			if (isPartial) {
+				const emoji = statusEmoji(result.details?.status ?? "running");
+				return new Text(theme.fg("info", `${emoji} ${result.content?.[0]?.text ?? "Running…"}`), 0, 0);
+			}
+			const status = result.details?.status;
+			if (status && TERMINAL_STATUSES.has(status)) {
+				const emoji = statusEmoji(status);
+				const header = theme.fg(status === "done" ? "success" : "error", `${emoji} ${status}`);
+				const lines = (result.content?.[0]?.text ?? "").split("\n");
+				return new Text(header + "\n" + lines.map((l) => theme.fg("muted", `  ${l}`)).join("\n"), 0, 0);
+			}
+			return new Text((result.content?.[0]?.text ?? "").split("\n").map((l) => theme.fg("muted", l)).join("\n"), 0, 0);
+		}
+	});
+	pi.registerTool({
+		name: "avenor_status",
+		label: "Avenor Status",
+		description: "Get status of a run or all runs. Surfaces pending permission requests.",
+		parameters: Type.Object({
+			run_id: Type.Optional(Type.String({ description: "Specific run ID to query" })),
+			supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
+		}),
+		async execute(_toolCallId, params) {
+			const result = await statusTool({
+				runId: params.run_id,
+				supervisorId: params.supervisor_id
+			});
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				details: result
+			};
+		}
+	});
+	pi.registerTool({
+		name: "avenor_answer_permission",
+		label: "Avenor Answer Permission",
+		description: "Answer a pending permission request for a sub-agent. Pass option_id from avenor_status pending_permission.options.",
+		parameters: Type.Object({
+			run_id: Type.String({ description: "Run ID with the pending permission" }),
+			option_id: Type.String({ description: "allow_once | allow_always | deny" }),
+			request_id: Type.Optional(Type.String({ description: "Permission request ID (auto-discovered if omitted)" })),
+			supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
+		}),
+		async execute(_toolCallId, params) {
+			const result = await answerPermissionTool({
+				runId: params.run_id,
+				optionId: params.option_id,
+				requestId: params.request_id,
+				supervisorId: params.supervisor_id
+			});
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				details: result
+			};
+		}
+	});
+	pi.registerTool({
+		name: "avenor_follow_up",
+		label: "Avenor Follow Up",
+		description: "Resume a completed run with a follow-up message.",
+		parameters: Type.Object({
+			run_id: Type.String({ description: "Completed run ID to resume" }),
+			message: Type.String({ description: "Follow-up message text" }),
+			label: Type.Optional(Type.String({ description: "Override label (defaults to <original>-followup)" })),
+			supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
+		}),
+		async execute(_toolCallId, params) {
+			const result = await followUpTool({
+				runId: params.run_id,
+				message: params.message,
+				label: params.label,
+				supervisorId: params.supervisor_id
+			});
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				details: result
+			};
+		}
+	});
+	pi.registerTool({
+		name: "avenor_events",
+		label: "Avenor Events",
+		description: "Read events from a run. Filter by type. Returns last N events.",
+		parameters: Type.Object({
+			run_id: Type.String({ description: "Run ID to read events from" }),
+			types: Type.Optional(Type.Array(Type.String(), { description: "Filter by event types" })),
+			limit: Type.Optional(Type.Number({ description: "Max events to return (default 50)" })),
+			supervisor_id: Type.Optional(Type.String({ description: "Reuse an existing supervisor by socket path" }))
+		}),
+		async execute(_toolCallId, params) {
+			const result = await eventsTool({
+				runId: params.run_id,
+				types: params.types,
+				limit: params.limit,
+				supervisorId: params.supervisor_id
+			});
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				details: result
+			};
+		}
+	});
+	pi.registerTool({
+		name: "avenor_shutdown",
+		label: "Avenor Shutdown",
+		description: "Shut down the avenor supervisor and clean up temp files.",
+		parameters: Type.Object({
+			supervisor_id: Type.Optional(Type.String({ description: "Supervisor to shut down (defaults to singleton)" })),
+			force: Type.Optional(Type.Boolean({ description: "Force shutdown instead of graceful" }))
+		}),
+		async execute(_toolCallId, params) {
+			const result = await shutdownTool({
+				supervisorId: params.supervisor_id,
+				force: params.force
+			});
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}],
+				details: result
+			};
+		}
+	});
+	pi.registerCommand("avenor-status", {
+		description: "Show status of all avenor runs",
+		handler: async (_args, ctx) => {
+			const entries = await pollRuns();
+			if (entries.length === 0) {
+				ctx.ui.notify("No active avenor runs", "info");
+				return;
+			}
+			const lines = entries.map((e) => formatRunLine(e));
+			ctx.ui.setWidget("avenor-status-detail", lines);
+		}
+	});
+	pi.registerCommand("avenor-watch", {
+		description: "Open a live event feed for a run",
+		getArgumentCompletions: (prefix) => {
+			const items = Array.from(trackedRuns.values()).filter((r) => r.label.startsWith(prefix) || r.runId.startsWith(prefix)).map((r) => ({
+				value: r.runId,
+				label: `${r.label} (${r.runId.slice(0, 8)})`
+			}));
+			return items.length > 0 ? items : null;
+		},
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("avenor-watch requires TUI mode", "warning");
+				return;
+			}
+			let runId = args?.trim();
+			if (!runId) {
+				const runList = Array.from(trackedRuns.values());
+				if (runList.length === 0) {
+					ctx.ui.notify("No tracked runs", "warning");
+					return;
+				}
+				const choices = runList.map((r) => r.runId);
+				const labels = runList.map((r) => `${r.label} (${r.runId.slice(0, 8)})`);
+				const idx = await ctx.ui.select("Watch run:", labels);
+				if (idx === null) return;
+				runId = choices[idx];
+			}
+			let watchActive = true;
+			const overlay = new EventFeedOverlay(runId);
+			try {
+				const { events } = await eventsTool({
+					runId,
+					limit: 50
+				});
+				overlay.setEvents(events);
+			} catch (err) {
+				console.error("avenor watch: failed to load initial events", err);
+				overlay.setEvents([]);
+			}
+			const handle = ctx.ui.custom((_tui, _theme, _kb, done) => {
+				overlay.setOnClose(() => {
+					watchActive = false;
+					done();
+				});
+				return overlay;
+			}, {
+				overlay: true,
+				overlayOptions: {
+					anchor: "right-center",
+					width: "45%",
+					minWidth: 60,
+					maxHeight: "70%"
+				},
+				onHandle: (h) => {
+					handle._inner = h;
+				}
+			});
+			const watchTick = async () => {
+				while (watchActive) {
+					await sleep(POLL_INTERVAL_MS);
+					try {
+						const { events } = await eventsTool({
+							runId,
+							limit: 50
+						});
+						overlay.setEvents(events);
+						handle.requestRender?.();
+					} catch (err) {
+						console.error("avenor watch poll: eventsTool failed", err);
+						watchActive = false;
+					}
+				}
+			};
+			watchTick();
+		}
+	});
+	pi.registerCommand("avenor-cancel", {
+		description: "Cancel a running avenor sub-agent",
+		getArgumentCompletions: (prefix) => {
+			const items = Array.from(trackedRuns.values()).filter((r) => r.label.startsWith(prefix) || r.runId.startsWith(prefix)).map((r) => ({
+				value: r.runId,
+				label: `${r.label} (${r.runId.slice(0, 8)})`
+			}));
+			return items.length > 0 ? items : null;
+		},
+		handler: async (args, ctx) => {
+			if (!args?.trim()) {
+				ctx.ui.notify("Usage: /avenor-cancel <run_id>", "warning");
+				return;
+			}
+			const runId = args.trim();
+			const run = trackedRuns.get(runId);
+			const label = run?.label ?? runId;
+			if (!await ctx.ui.confirm("Cancel run", `Cancel "${label}" (${runId.slice(0, 8)})?`)) return;
+			try {
+				const { Supervisor } = await import("@dougbots/avenor-core");
+				await (await Supervisor.get()).getClient().cancel(run?.lastStatus?.runtime_id ?? runId);
+				ctx.ui.notify(`Cancelled "${label}"`, "info");
+			} catch (err) {
+				ctx.ui.notify(`Failed to cancel: ${err instanceof Error ? err.message : String(err)}`, "error");
+			}
+		}
+	});
+}
+//#endregion
+export { src_default as default };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dougbots/avenor-pi",
+  "version": "0.1.0",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sdougbrown/avenor",
+    "directory": "packages/pi"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "bun test",
+    "dev": "tsdown --watch"
+  },
+  "dependencies": {
+    "@dougbots/avenor-core": "^0.3.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/bun": "^1.3.12",
+    "@types/node": "^25.8.0",
+    "tsdown": "^0.22.0",
+    "typebox": "^1.2.17",
+    "typescript": "^6.0.3"
+  }
+}