@dougbots/avenor-opencode 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# @dougbots/avenor-opencode
+
+OpenCode plugin that registers avenor agent runs as tools in your OpenCode 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.
+
+## Setup
+
+Install the package alongside its peer dependency:
+
+```bash
+bun add @dougbots/avenor-opencode @opencode-ai/plugin@1.15.3
+```
+
+You also need the `avenor` binary. Either add it to your `PATH` or set the `AVENOR_BIN` environment variable to its location.
+
+```bash
+# Option 1 — add to PATH (e.g. via mise, brew, or manual install)
+which avenor
+
+# Option 2 — explicit path
+export AVENOR_BIN=~/.botfiles/bin/avenor
+```
+
+## Register the plugin
+
+Add `@dougbots/avenor-opencode` to your OpenCode configuration. If you use a global config:
+
+```json
+// ~/.opencode.json
+{
+  "plugins": ["@dougbots/avenor-opencode"]
+}
+```
+
+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.
+
+## Tools
+
+### `avenor_spawn`
+
+Dispatch an agent run in the current working directory. Returns a `run_id` you can poll with `avenor_status`.
+
+| Argument | Required | Description |
+|---|---|---|
+| `agent` | yes | Agent name (no default — must be specified) |
+| `prompt` | no | Prompt text |
+| `prompt_file` | no | Path to a prompt file |
+| `label` | no | Human-readable label for the run |
+| `timeout` | no | Timeout duration (e.g. `3600s`, `30m`) |
+| `model` | no | Model override |
+| `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.
+
+### `avenor_status`
+
+Get status of a specific run or all active runs. Surfaces any pending permission requests the sub-agent is blocked on.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | no | Specific run ID to query (omit for all runs) |
+| `supervisor_id` | no | Reuse an existing supervisor by socket path |
+
+### `avenor_answer_permission`
+
+Answer a pending permission request. The `option_id` comes from the `pending_permission.options` array returned by `avenor_status`.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID with the pending permission |
+| `option_id` | yes | Option ID from `pending_permission.options` |
+| `request_id` | no | Request ID (auto-discovered if omitted) |
+| `supervisor_id` | no | Reuse an existing supervisor by socket path |
+
+### `avenor_follow_up`
+
+Resume a completed run with a follow-up message. Useful for iterating on results or asking the sub-agent to refine its output.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | yes | Completed run ID to resume |
+| `message` | yes | Follow-up message text |
+| `label` | no | Override label (defaults to `<original>-followup`) |
+| `supervisor_id` | no | Reuse an existing supervisor by socket path |
+
+### `avenor_events`
+
+Read events from a run, optionally filtered by type. Returns the last N events.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID to read events from |
+| `types` | no | Filter by event type (array of strings) |
+| `limit` | no | Max events to return (default 50) |
+| `supervisor_id` | no | Reuse an existing supervisor by socket path |
+
+### `avenor_shutdown`
+
+Shut down the avenor supervisor process and clean up temp files. Call this when you are done delegating work or if the supervisor has crashed.
+
+| Argument | Required | Description |
+|---|---|---|
+| `supervisor_id` | no | Supervisor to shut down (defaults to the singleton) |
+| `force` | no | Force shutdown instead of graceful |
+
+## Typical workflow
+
+```
+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
+```
+
+## Dependencies
+
+- **Peer:** `@opencode-ai/plugin` v1.15.3 (the runtime that host agents use to mount plugins)
+- **Binary:** `avenor` must be available on `PATH` or at `AVENOR_BIN` (checked at first tool invocation, not at plugin load time)

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { Plugin } from "@opencode-ai/plugin";
+
+//#region src/plugin.d.ts
+declare const AvenorPlugin: Plugin;
+//#endregion
+export { AvenorPlugin };

package/dist/index.js

@@ -0,0 +1,109 @@
+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
+			});
+		}
+	}),
+	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

@@ -0,0 +1,39 @@
+{
+  "name": "@dougbots/avenor-opencode",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "bun test",
+    "dev": "tsdown --watch"
+  },
+  "dependencies": {
+    "@dougbots/avenor-core": "workspace:*",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "1.15.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.15.3",
+    "@types/bun": "^1.3.12",
+    "@types/node": "^25.8.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "unrun": "^0.3.0"
+  }
+}