@dougbots/avenor-opencode 0.1.0 → 0.2.1

package/README.md

@@ -35,11 +35,23 @@ For a project-level config, add the same entry to `.opencode.json` in your repo
 
 Once registered, the plugin exposes six tools that your OpenCode agent can call directly — no extra configuration required.
 
+## Behaviour
+
+When a run is dispatched with `avenor_spawn`, the plugin:
+
+1. **Blocks by default** — the tool call stays open, updating its title and metadata as the sub-agent runs, exactly like OpenCode's own sub-agent tool calls. The tool returns when the run reaches a terminal state.
+2. **Re-prompts on completion** — when a `wait=false` (fire-and-forget) run finishes, the plugin automatically injects a completion message into the orchestrating session so the LLM picks up without manual polling.
+3. **Routes permissions** — when a sub-agent running under the `opencode-http` backend requests a permission, the plugin injects a re-prompt into the orchestrating session. The LLM can call `avenor_answer_permission` to respond; the normal permission dialog is also shown as a fallback.
+
 ## Tools
 
 ### `avenor_spawn`
 
-Dispatch an agent run in the current working directory. Returns a `run_id` you can poll with `avenor_status`.
+Dispatch an agent run in the current working directory.
+
+**Blocking mode (default, `wait=true`):** the tool call shows live progress updates and returns a structured result when the run finishes.
+
+**Fire-and-forget (`wait=false`):** returns immediately with `run_id`. The orchestrating session is re-prompted automatically on completion.
 
 | Argument | Required | Description |
 |---|---|---|
@@ -49,6 +61,7 @@ Dispatch an agent run in the current working directory. Returns a `run_id` you c
 | `label` | no | Human-readable label for the run |
 | `timeout` | no | Timeout duration (e.g. `3600s`, `30m`) |
 | `model` | no | Model override |
+| `wait` | no | Block until complete (default `true`) |
 | `supervisor_id` | no | Reuse an existing supervisor by socket path |
 
 The working directory (`dir`) is injected automatically from your OpenCode session context — it is not a user-facing argument.
@@ -104,15 +117,25 @@ Shut down the avenor supervisor process and clean up temp files. Call this when
 | `supervisor_id` | no | Supervisor to shut down (defaults to the singleton) |
 | `force` | no | Force shutdown instead of graceful |
 
-## Typical workflow
+## Typical workflows
+
+**Blocking (default):**
+```
+1. avenor_spawn            →  tool call shows live progress, blocks until done
+2. (avenor_answer_permission  →  if a permission is routed to this session mid-run)
+3. tool call returns       →  structured result with status + session_id
+4. avenor_events           →  inspect detailed output
+5. avenor_follow_up        →  optionally iterate
+6. avenor_shutdown         →  clean up when finished
+```
 
+**Parallel / fire-and-forget (`wait=false`):**
 ```
-1. avenor_spawn  →  receive run_id
-2. avenor_status  →  check if still running, spot pending permissions
-3. avenor_answer_permission  →  unblock if a permission is requested
-4. avenor_events  →  inspect output once complete
-5. avenor_follow_up  →  optionally send a follow-up
-6. avenor_shutdown  →  clean up when finished
+1. avenor_spawn × N        →  each returns run_id immediately
+2. (session goes idle)     →  plugin starts monitoring all pending runs
+3. (sub-agent finishes)    →  plugin re-prompts this session automatically
+4. avenor_answer_permission  →  if a permission was routed here mid-run
+5. avenor_events           →  inspect output
 ```
 
 ## Dependencies

package/dist/index.js

@@ -2,108 +2,280 @@ import { tool } from "@opencode-ai/plugin";
 import { z } from "zod";
 import { answerPermissionTool, eventsTool, followUpTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
 //#region src/plugin.ts
-const AvenorPlugin = async (_ctx) => ({ tool: {
-	avenor_spawn: tool({
-		description: "Dispatch an agent run via avenor. Returns run_id for status polling.",
-		args: {
-			agent: z.string().describe("Agent name (required, no default)"),
-			prompt: z.string().optional().describe("Prompt text"),
-			prompt_file: z.string().optional().describe("Path to prompt file"),
-			label: z.string().optional().describe("Human-readable label for the run"),
-			timeout: z.string().optional().describe("Timeout duration (e.g. 3600s)"),
-			model: z.string().optional().describe("Model override"),
-			supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
-		},
-		async execute(args, context) {
-			return spawnTool({
-				agent: args.agent,
-				prompt: args.prompt,
-				promptFile: args.prompt_file,
-				label: args.label,
-				dir: context.directory,
-				timeout: args.timeout,
-				model: args.model,
-				supervisorId: args.supervisor_id
-			});
-		}
-	}),
-	avenor_status: tool({
-		description: "Get status of a run or all runs. Surfaces pending permission requests.",
-		args: {
-			run_id: z.string().optional().describe("Specific run ID to query"),
-			supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
-		},
-		async execute(args, _context) {
-			return statusTool({
-				runId: args.run_id,
-				supervisorId: args.supervisor_id
-			});
-		}
-	}),
-	avenor_answer_permission: tool({
-		description: "Answer a pending permission request. Pass option_id from avenor_status pending_permission.options.",
-		args: {
-			run_id: z.string().describe("Run ID with the pending permission"),
-			option_id: z.string().describe("Option ID from pending_permission.options array"),
-			request_id: z.string().optional().describe("Request ID (auto-discovered if omitted)"),
-			supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
-		},
-		async execute(args, _context) {
-			return answerPermissionTool({
-				runId: args.run_id,
-				optionId: args.option_id,
-				requestId: args.request_id,
-				supervisorId: args.supervisor_id
-			});
-		}
-	}),
-	avenor_follow_up: tool({
-		description: "Resume a completed run with a follow-up message.",
-		args: {
-			run_id: z.string().describe("Completed run ID to resume"),
-			message: z.string().describe("Follow-up message text"),
-			label: z.string().optional().describe("Override label (defaults to <original>-followup)"),
-			supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
-		},
-		async execute(args, _context) {
-			return followUpTool({
-				runId: args.run_id,
-				message: args.message,
-				label: args.label,
-				supervisorId: args.supervisor_id
-			});
+const TERMINAL_STATUSES = new Set([
+	"done",
+	"failed",
+	"timeout",
+	"killed"
+]);
+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;
+}
+const AvenorPlugin = async (ctx) => {
+	const trackedRuns = /* @__PURE__ */ new Map();
+	const sessionIdToRunId = /* @__PURE__ */ new Map();
+	function registerSessionId(sessionId, runId) {
+		if (sessionId && !sessionIdToRunId.has(sessionId)) sessionIdToRunId.set(sessionId, runId);
+	}
+	async function monitorRun(run) {
+		while (true) {
+			await sleep(POLL_INTERVAL_MS);
+			let raw;
+			try {
+				raw = await statusTool({
+					runId: run.runId,
+					supervisorId: run.supervisorId
+				});
+			} catch {
+				continue;
+			}
+			const result = Array.isArray(raw) ? raw[0] : raw;
+			if (!result) continue;
+			registerSessionId(result.session_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;
+			}
 		}
-	}),
-	avenor_events: tool({
-		description: "Read events from a run. Filter by type. Returns last N events.",
-		args: {
-			run_id: z.string().describe("Run ID to read events from"),
-			types: z.array(z.string()).optional().describe("Filter by event types"),
-			limit: z.number().optional().describe("Max events to return (default 50)"),
-			supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
+	}
+	return {
+		event: async ({ event }) => {
+			if (event.type !== "session.idle") return;
+			const { sessionID } = event.properties;
+			for (const run of trackedRuns.values()) if (run.orchestratorSessionId === sessionID && !run.monitoring) {
+				run.monitoring = true;
+				monitorRun(run).catch(console.error);
+			}
 		},
-		async execute(args, _context) {
-			return eventsTool({
-				runId: args.run_id,
-				types: args.types,
-				limit: args.limit,
-				supervisorId: args.supervisor_id
-			});
-		}
-	}),
-	avenor_shutdown: tool({
-		description: "Shut down the avenor supervisor and clean up temp files.",
-		args: {
-			supervisor_id: z.string().optional().describe("Supervisor to shut down (defaults to singleton)"),
-			force: z.boolean().optional().describe("Force shutdown instead of graceful")
+		"permission.ask": async (permission, _output) => {
+			const runId = sessionIdToRunId.get(permission.sessionID);
+			if (!runId) return;
+			const run = trackedRuns.get(runId);
+			if (!run) return;
+			const patternStr = permission.pattern ? [permission.pattern].flat().join(", ") : void 0;
+			const lines = [
+				`Sub-agent "${run.label}" is requesting permission for \`${permission.type}\`.`,
+				...patternStr ? [`Pattern: \`${patternStr}\``] : [],
+				``,
+				`To answer: call \`avenor_answer_permission\` with:`,
+				`  run_id: "${runId}"`,
+				`  request_id: "${permission.id}"`,
+				`  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(() => {});
 		},
-		async execute(args, _context) {
-			return shutdownTool({
-				supervisorId: args.supervisor_id,
-				force: args.force
-			});
+		tool: {
+			avenor_spawn: tool({
+				description: "Dispatch an agent run via avenor. Blocks by default, showing live progress as an updating tool call. Set wait=false for fire-and-forget — you will be re-prompted automatically on completion.",
+				args: {
+					agent: z.string().describe("Agent name (required, no default)"),
+					prompt: z.string().optional().describe("Prompt text"),
+					prompt_file: z.string().optional().describe("Path to prompt file"),
+					label: z.string().optional().describe("Human-readable label for the run"),
+					timeout: z.string().optional().describe("Timeout duration (e.g. 3600s)"),
+					model: z.string().optional().describe("Model override"),
+					backend: z.string().optional().describe("Backend override"),
+					server_url: z.string().optional().describe("Backend server URL"),
+					supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path"),
+					wait: z.boolean().default(true).describe("Block until complete with live status updates. False = fire-and-forget.")
+				},
+				async execute(args, context) {
+					const result = await spawnTool({
+						agent: args.agent,
+						prompt: args.prompt,
+						promptFile: args.prompt_file,
+						label: args.label,
+						dir: context.directory,
+						timeout: args.timeout,
+						model: args.model,
+						backend: args.backend,
+						serverUrl: args.server_url,
+						supervisorId: args.supervisor_id
+					});
+					const supervisorId = result.supervisor_id || args.supervisor_id;
+					trackedRuns.set(result.run_id, {
+						runId: result.run_id,
+						orchestratorSessionId: context.sessionID,
+						label: result.label,
+						supervisorId,
+						monitoring: args.wait
+					});
+					if (!args.wait) return result;
+					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
+							});
+						} catch {
+							continue;
+						}
+						const status = Array.isArray(raw) ? raw[0] : raw;
+						if (!status) continue;
+						registerSessionId(status.session_id, result.run_id);
+						if (status.pending_permission) context.metadata({
+							title: `[blocked] ${result.label}`,
+							metadata: {
+								status: "permission",
+								permission: status.pending_permission.description
+							}
+						});
+						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
+								}
+							};
+						}
+					}
+					trackedRuns.delete(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.`,
+						metadata: { run_id: result.run_id }
+					};
+				}
+			}),
+			avenor_status: tool({
+				description: "Get status of a run or all runs. Surfaces pending permission requests.",
+				args: {
+					run_id: z.string().optional().describe("Specific run ID to query"),
+					supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
+				},
+				async execute(args, _context) {
+					return statusTool({
+						runId: args.run_id,
+						supervisorId: args.supervisor_id
+					});
+				}
+			}),
+			avenor_answer_permission: tool({
+				description: "Answer a pending permission request for a sub-agent. Pass option_id from avenor_status pending_permission.options, or use \"allow_once\", \"allow_always\", \"deny\".",
+				args: {
+					run_id: z.string().describe("Run ID with the pending permission"),
+					option_id: z.string().describe("allow_once | allow_always | deny, or option_id from pending_permission.options"),
+					request_id: z.string().optional().describe("Permission request ID (auto-discovered if omitted)"),
+					supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
+				},
+				async execute(args, _context) {
+					return answerPermissionTool({
+						runId: args.run_id,
+						optionId: args.option_id,
+						requestId: args.request_id,
+						supervisorId: args.supervisor_id
+					});
+				}
+			}),
+			avenor_follow_up: tool({
+				description: "Resume a completed run with a follow-up message.",
+				args: {
+					run_id: z.string().describe("Completed run ID to resume"),
+					message: z.string().describe("Follow-up message text"),
+					label: z.string().optional().describe("Override label (defaults to <original>-followup)"),
+					supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
+				},
+				async execute(args, _context) {
+					return followUpTool({
+						runId: args.run_id,
+						message: args.message,
+						label: args.label,
+						supervisorId: args.supervisor_id
+					});
+				}
+			}),
+			avenor_events: tool({
+				description: "Read events from a run. Filter by type. Returns last N events.",
+				args: {
+					run_id: z.string().describe("Run ID to read events from"),
+					types: z.array(z.string()).optional().describe("Filter by event types"),
+					limit: z.number().optional().describe("Max events to return (default 50)"),
+					supervisor_id: z.string().optional().describe("Reuse an existing supervisor by socket path")
+				},
+				async execute(args, _context) {
+					return eventsTool({
+						runId: args.run_id,
+						types: args.types,
+						limit: args.limit,
+						supervisorId: args.supervisor_id
+					});
+				}
+			}),
+			avenor_shutdown: tool({
+				description: "Shut down the avenor supervisor and clean up temp files.",
+				args: {
+					supervisor_id: z.string().optional().describe("Supervisor to shut down (defaults to singleton)"),
+					force: z.boolean().optional().describe("Force shutdown instead of graceful")
+				},
+				async execute(args, _context) {
+					return shutdownTool({
+						supervisorId: args.supervisor_id,
+						force: args.force
+					});
+				}
+			})
 		}
-	})
-} });
+	};
+};
 //#endregion
 export { AvenorPlugin };

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@dougbots/avenor-opencode",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sdougbrown/avenor",
+    "directory": "packages/opencode"
+  },
   "files": [
     "dist"
   ],
@@ -22,7 +27,7 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "workspace:*",
+    "@dougbots/avenor-core": "^0.2.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {