@dougbots/avenor-opencode 0.4.1 → 0.5.1

package/README.md

@@ -33,7 +33,7 @@ Add `@dougbots/avenor-opencode` to your OpenCode configuration. If you use a glo
 
 For a project-level config, add the same entry to `.opencode.json` in your repo root.
 
-Once registered, the plugin exposes six tools that your OpenCode agent can call directly — no extra configuration required.
+Once registered, the plugin exposes eight tools that your OpenCode agent can call directly — no extra configuration required.
 
 ## Behaviour
 
@@ -68,13 +68,27 @@ The working directory (`dir`) is injected automatically from your OpenCode sessi
 
 ### `avenor_status`
 
-Get status of a specific run or all active runs. Surfaces any pending permission requests the sub-agent is blocked on.
+Get status of a specific run or all active runs. Use the compact `lifecycle` view for progress and pending permission checks; `full` remains the compatibility default.
 
 | Argument | Required | Description |
 |---|---|---|
 | `run_id` | no | Specific run ID to query (omit for all runs) |
+| `view` | no | Response detail: `lifecycle` or `full` (default) |
 | `supervisor_id` | no | Reuse an existing supervisor by socket path |
 
+### `avenor_result`
+
+Wait for a run to finish and return its bounded final output without transcript or event details. This is the output retrieval tool; `avenor_status` remains a lifecycle check.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID to await |
+| `wait` | no | Wait for a terminal result (default `true`) |
+| `timeout` | no | Maximum time to wait (for example `30s` or `5m`) |
+| `supervisor_id` | no | Reuse an existing supervisor by socket path |
+
+A blocked run returns its pending permission instead of waiting forever. If this tool's own timeout expires, it returns the latest status with `ready: false` and `timed_out: true`.
+
 ### `avenor_answer_permission`
 
 Answer a pending permission request. The `option_id` comes from the `pending_permission.options` array returned by `avenor_status`.
@@ -123,8 +137,8 @@ Shut down the avenor supervisor process and clean up temp files. Call this when
 ```
 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
+3. tool call returns       →  completion preview with status + session_id
+4. avenor_result           →  retrieve the bounded final output when needed
 5. avenor_follow_up        →  optionally iterate
 6. avenor_shutdown         →  clean up when finished
 ```
@@ -135,7 +149,8 @@ Shut down the avenor supervisor process and clean up temp files. Call this when
 2. plugin starts monitoring each run immediately
 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
+5. avenor_result           →  wait for and retrieve the final output
+6. avenor_events           →  inspect raw event history when needed
 ```
 
 ## Dependencies

package/dist/index.js

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 import * as crypto from "node:crypto";
-import { Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, followUpTool, inspectTool, observeRun, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
 //#region src/plugin.ts
 const TERMINAL_STATUSES = new Set([
 	"done",
@@ -206,6 +206,10 @@ const AvenorPlugin = async (ctx) => {
 						kind: "aborted",
 						snapshot: current
 					};
+					if (handle.stopReason === "result") return {
+						kind: "stopped",
+						snapshot: current
+					};
 					return {
 						kind: "shutdown",
 						snapshot: current
@@ -241,6 +245,10 @@ const AvenorPlugin = async (ctx) => {
 							kind: "shutdown",
 							snapshot: current
 						};
+						if (handle.stopReason === "result") return {
+							kind: "stopped",
+							snapshot: current
+						};
 						if (current.pending_permission || current.phase === "waiting") return {
 							kind: "waiting",
 							snapshot: current
@@ -471,7 +479,7 @@ const AvenorPlugin = async (ctx) => {
 						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.`
+							output: `Dispatched "${result.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.`
 						};
 					}
 					context.metadata({ title: `Starting ${result.label}…` });
@@ -526,19 +534,49 @@ const AvenorPlugin = async (ctx) => {
 				}
 			}),
 			avenor_status: tool({
-				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.",
 				args: {
 					run_id: tool.schema.string().optional().describe("Specific run ID to query"),
+					view: tool.schema.enum(["lifecycle", "full"]).optional().describe("Response detail (default full for compatibility)"),
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
 				},
 				async execute(args, _context) {
 					const result = await statusTool({
 						runId: args.run_id,
-						supervisorId: args.supervisor_id
+						supervisorId: args.supervisor_id,
+						view: args.view
 					});
 					return JSON.stringify(result, null, 2);
 				}
 			}),
+			avenor_result: tool({
+				description: "Wait for a run to finish and return its bounded final output without transcript or event details.",
+				args: {
+					run_id: tool.schema.string().describe("Run ID to await"),
+					wait: tool.schema.boolean().optional().describe("Wait for a terminal result (default true)"),
+					timeout: tool.schema.string().optional().describe("Maximum time to wait (e.g. 30s, 5m)"),
+					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
+				},
+				async execute(args, context) {
+					const run = trackedRuns.get(args.run_id);
+					if (run) await stopMonitor(run.runId, "result");
+					try {
+						const result = await resultTool({
+							runId: args.run_id,
+							supervisorId: args.supervisor_id,
+							wait: args.wait,
+							timeout: args.timeout,
+							signal: context.abort
+						});
+						if (result.ready) unregisterRun(args.run_id);
+						else if (run) monitorRun(run).catch(console.error);
+						return JSON.stringify(result, null, 2);
+					} catch (error) {
+						if (run) monitorRun(run).catch(console.error);
+						throw error;
+					}
+				}
+			}),
 			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: {

package/package.json

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