@dougbots/avenor-opencode 0.3.7 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,21 @@
 import { Plugin } from "@opencode-ai/plugin";
+import { RunSnapshot, StatusResult } from "@dougbots/avenor-core";
 
 //#region src/plugin.d.ts
+type TrackedRun = {
+  runId: string;
+  runtimeId?: string;
+  sessionId?: string;
+  agent: string;
+  orchestratorSessionId: string;
+  label: string;
+  supervisorId?: string;
+  monitoring: boolean;
+  latestSeq?: number;
+  lastSnapshot?: RunSnapshot;
+};
+declare function terminalStatus(snapshot: RunSnapshot, fallback?: StatusResult): string;
+declare function buildWaitingText(run: TrackedRun, snapshot: RunSnapshot): string;
 declare const AvenorPlugin: Plugin;
 //#endregion
-export { AvenorPlugin };
+export { AvenorPlugin, buildWaitingText, terminalStatus };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 import * as crypto from "node:crypto";
-import { answerPermissionTool, eventsTool, followUpTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, followUpTool, inspectTool, observeRun, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
 //#region src/plugin.ts
 const TERMINAL_STATUSES = new Set([
 	"done",
@@ -9,22 +9,83 @@ const TERMINAL_STATUSES = new Set([
 	"killed"
 ]);
 const POLL_INTERVAL_MS = 3e3;
+const FINAL_OUTPUT_CHARS = 1500;
+const METADATA_TEXT_CHARS = 400;
+const TRANSCRIPT_PREVIEW_ENTRIES = 3;
 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.`);
+function clipTail(text, limit) {
+	if (!text) return void 0;
+	if (text.length <= limit) return text;
+	return text.slice(text.length - limit);
+}
+function terminalStatus(snapshot, fallback) {
+	if (fallback?.status) return fallback.status;
+	if (snapshot.phase && TERMINAL_STATUSES.has(snapshot.phase)) return snapshot.phase;
+	return snapshot.stop_reason ?? "done";
+}
+function formatLiveTool(snapshot) {
+	const tool = snapshot.live_tools[snapshot.live_tools.length - 1];
+	if (!tool) return void 0;
+	const base = tool.title ?? tool.kind ?? tool.id ?? tool.key;
+	const status = tool.status ? ` (${tool.status})` : "";
+	const preview = clipTail(tool.preview, 120);
+	return preview ? `${base}${status}: ${preview}` : `${base}${status}`;
+}
+function formatTranscriptEntry(entry) {
+	const text = clipTail(entry.text?.trim(), 120);
+	switch (entry.kind) {
+		case "assistant": return text ? `assistant: ${text}` : void 0;
+		case "thought": return text ? `thought: ${text}` : void 0;
+		case "user": return text ? `user: ${text}` : void 0;
+		case "tool": {
+			const title = entry.title ?? "tool";
+			const status = entry.status ? ` (${entry.status})` : "";
+			return text ? `${title}${status}: ${text}` : `${title}${status}`;
+		}
+		case "permission": return text ? `permission: ${text}` : void 0;
+		case "status": return text ? `status: ${text}` : void 0;
+		case "session": return text ? `session: ${text}` : void 0;
+	}
+}
+function formatTranscriptPreview(snapshot) {
+	const lines = snapshot.transcript.slice(-TRANSCRIPT_PREVIEW_ENTRIES).map(formatTranscriptEntry).filter((line) => Boolean(line));
+	if (lines.length === 0) return void 0;
+	return clipTail(lines.join("\n"), METADATA_TEXT_CHARS);
+}
+function buildSnapshotMetadata(snapshot) {
+	const metadata = {};
+	if (snapshot.phase) metadata.phase = snapshot.phase;
+	if (snapshot.latest_seq !== void 0) metadata.latest_seq = snapshot.latest_seq;
+	const liveTool = formatLiveTool(snapshot);
+	if (liveTool) metadata.live_tool = liveTool;
+	const transcriptPreview = formatTranscriptPreview(snapshot);
+	if (transcriptPreview) metadata.transcript_preview = transcriptPreview;
+	const pendingPermission = clipTail(snapshot.pending_permission?.description ?? snapshot.pending_permission?.question ?? snapshot.phase_label, METADATA_TEXT_CHARS);
+	if (pendingPermission) metadata.pending_permission = pendingPermission;
+	return metadata;
+}
+function buildWaitingText(run, snapshot) {
+	const permission = snapshot.pending_permission;
+	const lines = [`Sub-agent "${run.label}" is waiting for input.`];
+	if (permission) lines.push(`Permission request: ${permission.description ?? permission.question ?? permission.tool ?? "permission requested"}`, `To answer: call \`avenor_answer_permission\` with run_id "${run.runId}", option_id "allow_once" | "allow_always" | "deny"`);
+	else if (snapshot.phase_label) lines.push(`Question: ${snapshot.phase_label}`);
+	const transcriptPreview = formatTranscriptPreview(snapshot);
+	if (transcriptPreview) lines.push("", `Recent context:\n${transcriptPreview}`);
+	if (!permission) lines.push(`Use \`avenor_follow_up\` with run_id "${run.runId}" to respond, or \`avenor_status\` to re-check.`);
 	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;
+function buildCompletionText(run, snapshot, status, finalOutput) {
+	const lines = [`Sub-agent "${run.label}" finished with status **${terminalStatus(snapshot, status)}**.`];
+	const stopReason = status?.stop_reason ?? snapshot.stop_reason;
+	if (stopReason && stopReason.toUpperCase() !== terminalStatus(snapshot, status).toUpperCase()) lines.push(`Stop reason: ${stopReason}`);
+	const sessionId = status?.session_id ?? snapshot.identity.session_id;
+	if (sessionId) lines.push(`Session: \`${sessionId}\``);
+	const boundedOutput = clipTail(finalOutput ?? snapshot.final_output, FINAL_OUTPUT_CHARS);
+	if (boundedOutput) lines.push("", "Final output:", "```text", boundedOutput, "```");
+	lines.push("", `Call \`avenor_events\` with \`run_id: "${run.runId}"\` for raw events, or \`avenor_follow_up\` to iterate.`);
+	return lines.join("\n");
 }
 const CHANNEL_RE = /<channel\s+source="([^"]*)"(?:\s+from_run_id="([^"]*)")?(?:\s+from_role="([^"]*)")?[^>]*>([\s\S]*?)<\/channel>/g;
 function formatAgentMessage(source, fromRunId, fromRole, content) {
@@ -45,6 +106,7 @@ function formatChannelBlocks(text) {
 }
 const AvenorPlugin = async (ctx) => {
 	const trackedRuns = /* @__PURE__ */ new Map();
+	const activeMonitors = /* @__PURE__ */ new Map();
 	const sessionIdToRunId = /* @__PURE__ */ new Map();
 	const runtimeIdToRunId = /* @__PURE__ */ new Map();
 	let parentRunId = "";
@@ -55,55 +117,215 @@ const AvenorPlugin = async (ctx) => {
 		if (!parentRunId) parentRunId = crypto.randomUUID();
 		return parentRunId;
 	}
+	function unregisterRun(runId) {
+		trackedRuns.delete(runId);
+		for (const [sessionId, mappedRunId] of [...sessionIdToRunId.entries()]) if (mappedRunId === runId) sessionIdToRunId.delete(sessionId);
+		for (const [runtimeId, mappedRunId] of [...runtimeIdToRunId.entries()]) if (mappedRunId === runId) runtimeIdToRunId.delete(runtimeId);
+	}
 	function registerSessionId(sessionId, runtimeId, runId) {
+		const run = trackedRuns.get(runId);
+		if (run) {
+			if (sessionId) run.sessionId = sessionId;
+			if (runtimeId) run.runtimeId = runtimeId;
+		}
 		if (sessionId && !sessionIdToRunId.has(sessionId)) sessionIdToRunId.set(sessionId, runId);
 		if (runtimeId && !runtimeIdToRunId.has(runtimeId)) runtimeIdToRunId.set(runtimeId, runId);
 	}
-	async function monitorRun(run) {
-		let firstPoll = true;
-		while (true) {
-			if (!firstPoll) await sleep(POLL_INTERVAL_MS);
-			firstPoll = false;
-			let raw;
+	function syncRunSnapshot(run, snapshot) {
+		run.lastSnapshot = snapshot;
+		if (snapshot.latest_seq !== void 0) run.latestSeq = snapshot.latest_seq;
+		registerSessionId(snapshot.identity.session_id, snapshot.identity.runtime_id, run.runId);
+	}
+	async function primeTrackedRun(run, options = {}) {
+		try {
+			const raw = await statusTool({
+				runId: run.runId,
+				supervisorId: run.supervisorId
+			});
+			const status = Array.isArray(raw) ? raw[0] : raw;
+			if (!status) return void 0;
+			registerSessionId(status.session_id, status.runtime_id, run.runId);
+			if (status.latest_seq !== void 0 && options.captureLatestSeq) run.latestSeq = status.latest_seq;
+			return status;
+		} catch {
+			return;
+		}
+	}
+	async function createObserver(run) {
+		if (!run.supervisorId) run.supervisorId = Supervisor.currentInstance()?.supervisorId;
+		if (!run.runtimeId) await primeTrackedRun(run);
+		if (!run.supervisorId || !run.runtimeId) throw new Error(`unable to observe run ${run.runId}`);
+		return observeRun(await dial(run.supervisorId), {
+			runtime_id: run.runtimeId,
+			replay: true,
+			...run.latestSeq !== void 0 ? { after_seq: run.latestSeq } : {},
+			close_client: true
+		});
+	}
+	async function stopMonitor(runId, reason) {
+		const active = activeMonitors.get(runId);
+		if (!active) return;
+		active.stopReason = active.stopReason ?? reason;
+		await active.observer?.close().catch(() => {});
+	}
+	async function loadInspection(run) {
+		try {
+			return await inspectTool({
+				runId: run.runId,
+				supervisorId: run.supervisorId
+			});
+		} catch {
+			return;
+		}
+	}
+	async function observeTrackedRun(run, options = {}) {
+		const existing = activeMonitors.get(run.runId);
+		if (existing) return existing.promise;
+		run.monitoring = true;
+		const handle = { promise: Promise.resolve({
+			kind: "stopped",
+			snapshot: run.lastSnapshot
+		}) };
+		handle.promise = (async () => {
+			let observer;
+			let unsubscribe;
+			let abortListener;
 			try {
-				raw = await statusTool({
-					runId: run.runId,
-					supervisorId: run.supervisorId
+				observer = await createObserver(run);
+				handle.observer = observer;
+				if (handle.stopReason) {
+					await observer.close();
+					const current = observer.snapshot();
+					syncRunSnapshot(run, current);
+					if (handle.stopReason === "permission-routed") return {
+						kind: "waiting",
+						snapshot: current,
+						notified: true
+					};
+					if (handle.stopReason === "abort") return {
+						kind: "aborted",
+						snapshot: current
+					};
+					return {
+						kind: "shutdown",
+						snapshot: current
+					};
+				}
+				if (options.abort) {
+					const onAbort = () => {
+						stopMonitor(run.runId, "abort");
+					};
+					options.abort.addEventListener("abort", onAbort, { once: true });
+					abortListener = () => options.abort?.removeEventListener("abort", onAbort);
+					if (options.abort.aborted) await stopMonitor(run.runId, "abort");
+				}
+				unsubscribe = observer.subscribe((snapshot) => {
+					syncRunSnapshot(run, snapshot);
+					options.onSnapshot?.(snapshot);
 				});
-			} catch {
-				continue;
-			}
-			const result = Array.isArray(raw) ? raw[0] : raw;
-			if (!result) continue;
-			registerSessionId(result.session_id, result.runtime_id, run.runId);
-			if (TERMINAL_STATUSES.has(result.status)) {
-				trackedRuns.delete(run.runId);
-				await ctx.client.session.promptAsync({
-					path: { id: run.orchestratorSessionId },
-					body: { parts: [{
-						type: "text",
-						text: buildCompletionText(run, result)
-					}] }
-				}).catch(() => {});
-				return;
-			}
-			if (result.status === "waiting") {
-				const perm = result.pending_permission;
-				const lines = [`Sub-agent "${run.label}" is waiting for input.`];
-				if (perm) lines.push(`Permission request: ${perm.description}`, `To answer: call \`avenor_answer_permission\` with run_id "${run.runId}", option_id "allow_once" | "allow_always" | "deny"`);
-				else if (result.phase_label) lines.push(`Question: ${result.phase_label}`);
-				lines.push(`Use \`avenor_follow_up\` with run_id "${run.runId}" to respond, or \`avenor_status\` to re-check.`);
-				await ctx.client.session.promptAsync({
-					path: { id: run.orchestratorSessionId },
-					body: { parts: [{
-						type: "text",
-						text: lines.join("\n")
-					}] }
-				}).catch(() => {});
+				while (true) {
+					const snapshot = await observer.next();
+					if (!snapshot) {
+						const current = observer.snapshot();
+						syncRunSnapshot(run, current);
+						if (handle.stopReason === "permission-routed") return {
+							kind: "waiting",
+							snapshot: current,
+							notified: true
+						};
+						if (handle.stopReason === "abort") return {
+							kind: "aborted",
+							snapshot: current
+						};
+						if (handle.stopReason === "shutdown") return {
+							kind: "shutdown",
+							snapshot: current
+						};
+						if (current.pending_permission || current.phase === "waiting") return {
+							kind: "waiting",
+							snapshot: current
+						};
+						if (current.ended) return {
+							kind: "terminal",
+							snapshot: current
+						};
+						return {
+							kind: "stopped",
+							snapshot: current
+						};
+					}
+					syncRunSnapshot(run, snapshot);
+					if (snapshot.pending_permission || snapshot.phase === "waiting") return {
+						kind: "waiting",
+						snapshot
+					};
+					if (snapshot.ended) return {
+						kind: "terminal",
+						snapshot
+					};
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				const snapshot = observer?.snapshot() ?? run.lastSnapshot ?? {
+					...createRunSnapshot(),
+					identity: {
+						run_id: run.runId,
+						run_label: run.label,
+						runtime_id: run.runtimeId,
+						agent: run.agent
+					}
+				};
+				syncRunSnapshot(run, snapshot);
+				return {
+					kind: "error",
+					snapshot,
+					error: message
+				};
+			} finally {
+				abortListener?.();
+				unsubscribe?.();
+				await observer?.close().catch(() => {});
+				if (activeMonitors.get(run.runId) === handle) activeMonitors.delete(run.runId);
 				run.monitoring = false;
-				return;
 			}
+		})();
+		activeMonitors.set(run.runId, handle);
+		return handle.promise;
+	}
+	async function promptSession(sessionId, text) {
+		await ctx.client.session.promptAsync({
+			path: { id: sessionId },
+			body: { parts: [{
+				type: "text",
+				text
+			}] }
+		}).catch(() => {});
+	}
+	async function monitorRun(run) {
+		const outcome = await observeTrackedRun(run);
+		if (outcome.kind === "error") {
+			await promptSession(run.orchestratorSessionId, `Monitoring of "${run.label}" (run_id: ${run.runId}) failed: ${outcome.error ?? "unknown error"}. The run may still be active — use avenor_status to check.`);
+			return;
+		}
+		if (outcome.kind === "waiting") {
+			if (!outcome.notified) await promptSession(run.orchestratorSessionId, buildWaitingText(run, outcome.snapshot));
+			return;
 		}
+		if (outcome.kind === "terminal") {
+			const inspection = await loadInspection(run);
+			const snapshot = inspection?.snapshot ?? outcome.snapshot;
+			await promptSession(run.orchestratorSessionId, buildCompletionText(run, snapshot, inspection?.status, inspection?.final_output));
+			unregisterRun(run.runId);
+			return;
+		}
+		if (outcome.kind === "aborted" || outcome.kind === "shutdown") unregisterRun(run.runId);
+	}
+	async function stopTrackedRuns(predicate) {
+		const runs = [...trackedRuns.values()].filter(predicate);
+		await Promise.all(runs.map(async (run) => {
+			await stopMonitor(run.runId, "shutdown");
+			unregisterRun(run.runId);
+		}));
 	}
 	async function pollChannelMessages(sessionId) {
 		if (channelPolling || !brokerUrl || !parentRunId || !parentToken) return;
@@ -169,10 +391,7 @@ const AvenorPlugin = async (ctx) => {
 			if (event.type !== "session.idle") return;
 			const { sessionID } = event.properties;
 			pollChannelMessages(sessionID).catch(console.error);
-			for (const run of trackedRuns.values()) if (run.orchestratorSessionId === sessionID && !run.monitoring) {
-				run.monitoring = true;
-				monitorRun(run).catch(console.error);
-			}
+			for (const run of trackedRuns.values()) if (run.orchestratorSessionId === sessionID && !run.monitoring) monitorRun(run).catch(console.error);
 		},
 		"permission.ask": async (permission, _output) => {
 			const runId = sessionIdToRunId.get(permission.sessionID);
@@ -183,19 +402,15 @@ const AvenorPlugin = async (ctx) => {
 			const lines = [
 				`Sub-agent "${run.label}" is requesting permission for \`${permission.type}\`.`,
 				...patternStr ? [`Pattern: \`${patternStr}\``] : [],
-				``,
-				`To answer: call \`avenor_answer_permission\` with:`,
+				"",
+				"To answer: call `avenor_answer_permission` with:",
 				`  run_id: "${runId}"`,
 				`  request_id: "${permission.id}"`,
-				`  option_id: "allow_once" | "allow_always" | "deny"`
+				"  option_id: \"allow_once\" | \"allow_always\" | \"deny\""
 			];
-			await ctx.client.session.promptAsync({
-				path: { id: run.orchestratorSessionId },
-				body: { parts: [{
-					type: "text",
-					text: lines.join("\n")
-				}] }
-			}).catch(() => {});
+			await primeTrackedRun(run, { captureLatestSeq: true });
+			await stopMonitor(run.runId, "permission-routed");
+			await promptSession(run.orchestratorSessionId, lines.join("\n"));
 		},
 		"chat.message": async (message, _output) => {
 			if (!message?.parts) return;
@@ -224,7 +439,7 @@ const AvenorPlugin = async (ctx) => {
 					wait: tool.schema.boolean().default(true).describe("Block until complete with live status updates. False = fire-and-forget.")
 				},
 				async execute(args, context) {
-					const parentRunId = ensureParentRunId();
+					const ownerRunId = ensureParentRunId();
 					const result = await spawnTool({
 						agent: args.agent,
 						prompt: args.prompt,
@@ -236,111 +451,73 @@ const AvenorPlugin = async (ctx) => {
 						backend: args.backend,
 						serverUrl: args.server_url,
 						supervisorId: args.supervisor_id,
-						parent_run_id: parentRunId
+						parent_run_id: ownerRunId
 					});
 					if (result.broker_url) brokerUrl = result.broker_url;
 					if (result.parent_token) parentToken = result.parent_token;
-					const supervisorId = result.supervisor_id || args.supervisor_id;
-					trackedRuns.set(result.run_id, {
+					const run = {
 						runId: result.run_id,
+						runtimeId: result.runtime_id,
 						agent: args.agent,
 						orchestratorSessionId: context.sessionID,
 						label: result.label,
-						supervisorId,
-						monitoring: args.wait
-					});
-					if (result.runtime_id) runtimeIdToRunId.set(result.runtime_id, result.run_id);
+						supervisorId: result.supervisor_id || args.supervisor_id,
+						monitoring: false
+					};
+					trackedRuns.set(result.run_id, run);
+					registerSessionId(void 0, result.runtime_id, result.run_id);
+					await primeTrackedRun(run);
 					if (!args.wait) {
-						const run = trackedRuns.get(result.run_id);
-						if (run) {
-							run.monitoring = true;
-							monitorRun(run).catch(console.error);
-						}
+						monitorRun(run).catch(console.error);
 						return {
 							title: `${result.label} — dispatched`,
 							output: `Dispatched "${result.label}" (run_id: ${result.run_id}). Call avenor_status with run_id to check progress, or wait for the completion notification.`
 						};
 					}
 					context.metadata({ title: `Starting ${result.label}…` });
-					let firstPoll = true;
-					while (!context.abort.aborted) {
-						if (!firstPoll) await sleep(POLL_INTERVAL_MS);
-						firstPoll = false;
-						if (context.abort.aborted) break;
-						let raw;
-						try {
-							raw = await statusTool({
-								runId: result.run_id,
-								supervisorId
+					const outcome = await observeTrackedRun(run, {
+						abort: context.abort,
+						onSnapshot: (snapshot) => {
+							context.metadata({
+								title: snapshot.pending_permission ? `[blocked] ${result.label}` : result.label,
+								metadata: buildSnapshotMetadata(snapshot)
 							});
-						} catch {
-							continue;
 						}
-						const status = Array.isArray(raw) ? raw[0] : raw;
-						if (!status) continue;
-						registerSessionId(status.session_id, status.runtime_id, result.run_id);
-						if (status.pending_permission) context.metadata({
-							title: `[blocked] ${result.label}`,
+					});
+					if (outcome.kind === "terminal") {
+						const inspection = await loadInspection(run);
+						const snapshot = inspection?.snapshot ?? outcome.snapshot;
+						unregisterRun(result.run_id);
+						return {
+							title: `${result.label} — ${terminalStatus(snapshot, inspection?.status)}`,
+							output: buildCompletionText(run, snapshot, inspection?.status, inspection?.final_output),
 							metadata: {
-								status: "permission",
-								permission: status.pending_permission.description
+								run_id: result.run_id,
+								session_id: inspection?.status.session_id ?? snapshot.identity.session_id,
+								final_output: clipTail(inspection?.final_output ?? snapshot.final_output, FINAL_OUTPUT_CHARS),
+								...buildSnapshotMetadata(snapshot)
 							}
-						});
-						else {
-							let lastAction = "";
-							if (!supervisorId) try {
-								const { events } = await eventsTool({
-									runId: result.run_id,
-									limit: 3
-								});
-								const last = events[events.length - 1];
-								if (last) lastAction = summarizeEvent(last);
-							} catch {}
-							context.metadata({
-								title: result.label,
-								metadata: {
-									status: status.status,
-									...status.phase_label && { phase: status.phase_label },
-									...lastAction && { last: lastAction }
-								}
-							});
-						}
-						if (TERMINAL_STATUSES.has(status.status)) {
-							trackedRuns.delete(result.run_id);
-							return {
-								title: `${result.label} — ${status.status}`,
-								output: buildCompletionText({
-									runId: result.run_id,
-									label: result.label
-								}, status),
-								metadata: {
-									status: status.status,
-									run_id: result.run_id,
-									session_id: status.session_id
-								}
-							};
-						}
-						if (status.status === "waiting") {
-							const perm = status.pending_permission;
-							const lines = [`Sub-agent "${result.label}" is waiting for input.`];
-							if (perm) lines.push(`Permission request: ${perm.description}`, `To answer: call \`avenor_answer_permission\` with run_id "${result.run_id}", option_id "allow_once" | "allow_always" | "deny"`);
-							else if (status.phase_label) lines.push(`Question: ${status.phase_label}`);
-							lines.push(`Use \`avenor_follow_up\` with run_id "${result.run_id}" to respond, or \`avenor_status\` to re-check.`);
-							const tracked = trackedRuns.get(result.run_id);
-							if (tracked) tracked.monitoring = false;
-							return {
-								title: `${result.label} — waiting`,
-								output: lines.join("\n"),
-								metadata: {
-									status: "waiting",
-									run_id: result.run_id,
-									session_id: status.session_id,
-									...perm && { pending_permission: perm }
-								}
-							};
-						}
+						};
 					}
-					trackedRuns.delete(result.run_id);
+					if (outcome.kind === "waiting") {
+						const inspection = await loadInspection(run);
+						const snapshot = inspection?.snapshot ?? outcome.snapshot;
+						return {
+							title: `${result.label} — waiting`,
+							output: buildWaitingText(run, snapshot),
+							metadata: {
+								run_id: result.run_id,
+								session_id: inspection?.status.session_id ?? snapshot.identity.session_id,
+								...buildSnapshotMetadata(snapshot)
+							}
+						};
+					}
+					if (outcome.kind === "error") return {
+						title: `${result.label} — monitoring error`,
+						output: `Monitoring failed: ${outcome.error ?? "unknown error"}. The run may still be active — use avenor_status to check.`,
+						metadata: { run_id: result.run_id }
+					};
+					unregisterRun(result.run_id);
 					return {
 						title: `${result.label} — aborted`,
 						output: `Monitoring of "${result.label}" (run_id: ${result.run_id}) was interrupted. The run may still be active — use avenor_status to check.`,
@@ -388,13 +565,25 @@ const AvenorPlugin = async (ctx) => {
 					label: tool.schema.string().optional().describe("Override label (defaults to <original>-followup)"),
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
 				},
-				async execute(args, _context) {
+				async execute(args, context) {
 					const result = await followUpTool({
 						runId: args.run_id,
 						message: args.message,
 						label: args.label,
 						supervisorId: args.supervisor_id
 					});
+					const priorRun = trackedRuns.get(args.run_id);
+					const run = {
+						runId: result.run_id,
+						agent: priorRun?.agent ?? "agent",
+						orchestratorSessionId: context.sessionID,
+						label: result.label,
+						supervisorId: args.supervisor_id ?? Supervisor.currentInstance()?.supervisorId,
+						monitoring: false
+					};
+					trackedRuns.set(result.run_id, run);
+					await primeTrackedRun(run);
+					monitorRun(run).catch(console.error);
 					return JSON.stringify(result, null, 2);
 				}
 			}),
@@ -416,6 +605,24 @@ const AvenorPlugin = async (ctx) => {
 					return JSON.stringify(result, null, 2);
 				}
 			}),
+			avenor_inspect: tool({
+				description: "Inspect a run with reduced snapshot, transcript, tools, permissions, and final output.",
+				args: {
+					run_id: tool.schema.string().describe("Run ID to inspect"),
+					limit: tool.schema.number().optional().describe("Max events to reduce into the snapshot (default 50)"),
+					after_seq: tool.schema.number().optional().describe("Only include events after this sequence number"),
+					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
+				},
+				async execute(args, _context) {
+					const result = await inspectTool({
+						runId: args.run_id,
+						limit: args.limit,
+						after_seq: args.after_seq,
+						supervisorId: args.supervisor_id
+					});
+					return JSON.stringify(result, null, 2);
+				}
+			}),
 			avenor_shutdown: tool({
 				description: "Shut down the avenor supervisor and clean up temp files.",
 				args: {
@@ -423,6 +630,7 @@ const AvenorPlugin = async (ctx) => {
 					force: tool.schema.boolean().optional().describe("Force shutdown instead of graceful")
 				},
 				async execute(args, _context) {
+					await stopTrackedRuns((run) => !args.supervisor_id || run.supervisorId === args.supervisor_id);
 					const result = await shutdownTool({
 						supervisorId: args.supervisor_id,
 						force: args.force
@@ -434,4 +642,4 @@ const AvenorPlugin = async (ctx) => {
 	};
 };
 //#endregion
-export { AvenorPlugin };
+export { AvenorPlugin, buildWaitingText, terminalStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-opencode",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "^0.3.7"
+    "@dougbots/avenor-core": "^0.4.0"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "1.15.3"