@dougbots/avenor-opencode 0.9.0 → 0.10.1

package/README.md

@@ -58,17 +58,36 @@ Dispatch an agent run in the current working directory.
 
 | Argument | Required | Description |
 |---|---|---|
-| `agent` | yes | Agent name (no default — must be specified) |
+| `agent` | no | Agent name; omission uses the supplied model or runtime defaults |
 | `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 |
+| `thinking` | no | Run-level reasoning control; unsupported effective backends reject explicit values |
+| `backend` | no | Backend override; direct mode defaults to Avenor's `opencode-acp` backend when omitted |
+| `roster_file` | no | Path to a top-level roster map |
+| `roster_entry` | no | Key within `roster_file` |
 | `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.
 
+#### Direct and roster modes
+
+Use `roster_file` plus `roster_entry` to select a complete identity. Every roster entry requires `backend` and at least one of `agent` or `model`; roster mode rejects direct `agent`, `model`, and `backend` overrides. Direct mode allows all three identity fields to be omitted independently, including backend-only selection. Roster mode does not apply the direct `opencode-acp` default.
+
+```json
+{
+  "prompt": "Review the repository",
+  "roster_file": "/repo/roster.json",
+  "roster_entry": "reviewer",
+  "wait": true
+}
+```
+
+Roster entries currently support only `backend`, `agent`, and `model`. `system` and `thinking` are rejected; `thinking` remains a run-level value and is validated against the effective backend. A resumed session cannot change backend. The plugin passes `roster_file` as supplied, so an absolute path avoids ambiguity when the OpenCode process directory differs from the project directory.
+
 ### `avenor_status`
 
 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.

package/dist/index.d.ts

@@ -6,7 +6,14 @@ type TrackedRun = {
   runId: string;
   runtimeId?: string;
   sessionId?: string;
-  agent: string;
+  agent?: string;
+  model?: string;
+  backend?: string;
+  rosterFile?: string;
+  rosterEntry?: string;
+  effectiveAgent?: string;
+  effectiveModel?: string;
+  effectiveBackend?: string;
   orchestratorSessionId: string;
   label: string;
   supervisorId?: string;
@@ -15,7 +22,12 @@ type TrackedRun = {
   lastSnapshot?: RunSnapshot;
 };
 declare function terminalStatus(snapshot: RunSnapshot, fallback?: StatusResult): string;
+type HostIdentityMetadataInput = Pick<TrackedRun, 'agent' | 'model' | 'backend' | 'rosterFile' | 'rosterEntry' | 'effectiveAgent' | 'effectiveModel' | 'effectiveBackend'>;
+type HostIdentityStatus = Pick<StatusResult, 'roster_file' | 'roster_entry' | 'agent' | 'model' | 'backend' | 'effective_agent' | 'effective_model' | 'effective_backend'>;
+/** Project shared spawn identity into OpenCode metadata without resolving rosters here. */
+declare function hostIdentityMetadata(run?: HostIdentityMetadataInput, status?: HostIdentityStatus): Record<string, unknown>;
+declare function buildSnapshotMetadata(snapshot: RunSnapshot, run?: HostIdentityMetadataInput, status?: HostIdentityStatus): Record<string, unknown>;
 declare function buildWaitingText(run: TrackedRun, snapshot: RunSnapshot): string;
 declare const AvenorPlugin: Plugin;
 //#endregion
-export { AvenorPlugin, buildWaitingText, terminalStatus };
+export { AvenorPlugin, buildSnapshotMetadata, buildWaitingText, hostIdentityMetadata, terminalStatus };

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, extractEventText, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { Supervisor, THINKING_LEVELS, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, validateSpawnSelection, workflowCompleteTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
 //#region src/render.ts
 const FINAL_OUTPUT_CHARS$1 = 1500;
 const SCALAR_CHARS = 240;
@@ -462,7 +462,20 @@ function formatTranscriptPreview(snapshot) {
 	if (lines.length === 0) return void 0;
 	return clipTail(lines.join("\n"), METADATA_TEXT_CHARS);
 }
-function buildSnapshotMetadata(snapshot) {
+/** Project shared spawn identity into OpenCode metadata without resolving rosters here. */
+function hostIdentityMetadata(run = {}, status) {
+	const metadata = {};
+	const add = (key, value) => {
+		if (typeof value === "string" && value.length > 0) metadata[key] = value;
+	};
+	add("roster_file", status?.roster_file ?? run.rosterFile);
+	add("roster_entry", status?.roster_entry ?? run.rosterEntry);
+	add("effective_agent", status?.effective_agent ?? status?.agent ?? run.effectiveAgent);
+	add("effective_model", status?.effective_model ?? status?.model ?? run.effectiveModel);
+	add("effective_backend", status?.effective_backend ?? status?.backend ?? run.effectiveBackend);
+	return metadata;
+}
+function buildSnapshotMetadata(snapshot, run, status) {
 	const metadata = {};
 	if (snapshot.phase) metadata.phase = snapshot.phase;
 	if (snapshot.latest_seq !== void 0) metadata.latest_seq = snapshot.latest_seq;
@@ -472,6 +485,7 @@ function buildSnapshotMetadata(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;
+	Object.assign(metadata, hostIdentityMetadata(run, status));
 	return metadata;
 }
 function buildWaitingText(run, snapshot) {
@@ -544,6 +558,16 @@ const AvenorPlugin = async (ctx) => {
 		if (snapshot.latest_seq !== void 0) run.latestSeq = snapshot.latest_seq;
 		registerSessionId(snapshot.identity.session_id, snapshot.identity.runtime_id, run.runId);
 	}
+	function updateRunIdentity(run, status) {
+		run.rosterFile = status.roster_file ?? run.rosterFile;
+		run.rosterEntry = status.roster_entry ?? run.rosterEntry;
+		run.effectiveAgent = status.effective_agent ?? status.agent ?? run.effectiveAgent;
+		run.effectiveModel = status.effective_model ?? status.model ?? run.effectiveModel;
+		run.effectiveBackend = status.effective_backend ?? status.backend ?? run.effectiveBackend;
+		run.agent = run.effectiveAgent ?? run.agent;
+		run.model = run.effectiveModel ?? run.model;
+		run.backend = run.effectiveBackend ?? run.backend;
+	}
 	async function primeTrackedRun(run, options = {}) {
 		try {
 			const raw = await statusTool({
@@ -553,6 +577,7 @@ const AvenorPlugin = async (ctx) => {
 			const status = Array.isArray(raw) ? raw[0] : raw;
 			if (!status) return void 0;
 			registerSessionId(status.session_id, status.runtime_id, run.runId);
+			updateRunIdentity(run, status);
 			if (status.latest_seq !== void 0 && options.captureLatestSeq) run.latestSeq = status.latest_seq;
 			return status;
 		} catch {
@@ -578,10 +603,12 @@ const AvenorPlugin = async (ctx) => {
 	}
 	async function loadInspection(run) {
 		try {
-			return await inspectTool({
+			const inspection = await inspectTool({
 				runId: run.runId,
 				supervisorId: run.supervisorId
 			});
+			updateRunIdentity(run, inspection.status);
+			return inspection;
 		} catch {
 			return;
 		}
@@ -840,43 +867,46 @@ const AvenorPlugin = async (ctx) => {
 		},
 		tool: {
 			avenor_spawn: tool({
-				description: "Dispatch an agent run via avenor. Optional thinking accepts off, minimal, low, medium, high, xhigh, or max; unsupported backends reject explicit values. 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.",
+				description: `Dispatch an agent run via avenor. Optional thinking accepts ${[...THINKING_LEVELS].slice(0, -1).join(", ")}, or ${THINKING_LEVELS[THINKING_LEVELS.length - 1]}; unsupported backends reject explicit values. 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: tool.schema.string().describe("Agent name (required, no default)"),
+					agent: tool.schema.string().optional().describe("Optional agent name; omission uses the supplied model or runtime defaults"),
 					prompt: tool.schema.string().optional().describe("Prompt text"),
 					prompt_file: tool.schema.string().optional().describe("Path to prompt file"),
 					dir: tool.schema.string().optional().describe("Working directory for the run (defaults to the session project directory)"),
 					label: tool.schema.string().optional().describe("Human-readable label for the run"),
 					timeout: tool.schema.string().optional().describe("Timeout duration (e.g. 3600s)"),
 					model: tool.schema.string().optional().describe("Model override"),
-					thinking: tool.schema.enum([
-						"off",
-						"minimal",
-						"low",
-						"medium",
-						"high",
-						"xhigh",
-						"max"
-					]).optional().describe("Thinking level; omission uses the backend default"),
+					thinking: tool.schema.enum([...THINKING_LEVELS]).optional().describe("Thinking level; omission uses the backend default"),
 					backend: tool.schema.string().optional().describe("Backend override"),
+					roster_file: tool.schema.string().optional().describe("Path to the roster map"),
+					roster_entry: tool.schema.string().optional().describe("Roster entry to select"),
 					server_url: tool.schema.string().optional().describe("Backend server URL"),
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path"),
 					wait: tool.schema.boolean().default(true).describe("Block until complete with live status updates. False = fire-and-forget.")
 				},
 				async execute(args, context) {
-					const ownerRunId = ensureParentRunId();
-					const result = await spawnTool({
+					validateSpawnSelection({
 						agent: args.agent,
-						prompt: args.prompt,
-						promptFile: args.prompt_file,
-						label: args.label,
-						dir: args.dir ?? context.directory,
-						timeout: args.timeout,
 						model: args.model,
-						thinking: args.thinking,
 						backend: args.backend,
-						serverUrl: args.server_url,
-						supervisorId: args.supervisor_id,
+						roster_file: args.roster_file,
+						roster_entry: args.roster_entry
+					});
+					const ownerRunId = ensureParentRunId();
+					const result = await spawnTool({
+						...args.agent !== void 0 ? { agent: args.agent } : {},
+						...args.prompt !== void 0 ? { prompt: args.prompt } : {},
+						...args.prompt_file !== void 0 ? { promptFile: args.prompt_file } : {},
+						...args.label !== void 0 ? { label: args.label } : {},
+						dir: args.dir ?? context.directory,
+						...args.timeout !== void 0 ? { timeout: args.timeout } : {},
+						...args.model !== void 0 ? { model: args.model } : {},
+						...args.thinking !== void 0 ? { thinking: args.thinking } : {},
+						...args.backend !== void 0 ? { backend: args.backend } : {},
+						...args.roster_file !== void 0 ? { rosterFile: args.roster_file } : {},
+						...args.roster_entry !== void 0 ? { rosterEntry: args.roster_entry } : {},
+						...args.server_url !== void 0 ? { serverUrl: args.server_url } : {},
+						...args.supervisor_id !== void 0 ? { supervisorId: args.supervisor_id } : {},
 						parent_run_id: ownerRunId
 					});
 					if (result.broker_url) brokerUrl = result.broker_url;
@@ -885,6 +915,10 @@ const AvenorPlugin = async (ctx) => {
 						runId: result.run_id,
 						runtimeId: result.runtime_id,
 						agent: args.agent,
+						model: args.model,
+						backend: args.backend,
+						rosterFile: args.roster_file,
+						rosterEntry: args.roster_entry,
 						orchestratorSessionId: context.sessionID,
 						label: result.label,
 						supervisorId: result.supervisor_id || args.supervisor_id,
@@ -897,7 +931,8 @@ const AvenorPlugin = async (ctx) => {
 						monitorRun(run).catch(console.error);
 						return {
 							title: `${result.label} — dispatched`,
-							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.`
+							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.`,
+							metadata: hostIdentityMetadata(run)
 						};
 					}
 					context.metadata({ title: `Starting ${result.label}…` });
@@ -906,7 +941,7 @@ const AvenorPlugin = async (ctx) => {
 						onSnapshot: (snapshot) => {
 							context.metadata({
 								title: snapshot.pending_permission ? `[blocked] ${result.label}` : result.label,
-								metadata: buildSnapshotMetadata(snapshot)
+								metadata: buildSnapshotMetadata(snapshot, run)
 							});
 						}
 					});
@@ -921,7 +956,7 @@ const AvenorPlugin = async (ctx) => {
 								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)
+								...buildSnapshotMetadata(snapshot, run, inspection?.status)
 							}
 						};
 					}
@@ -934,20 +969,26 @@ const AvenorPlugin = async (ctx) => {
 							metadata: {
 								run_id: result.run_id,
 								session_id: inspection?.status.session_id ?? snapshot.identity.session_id,
-								...buildSnapshotMetadata(snapshot)
+								...buildSnapshotMetadata(snapshot, run, inspection?.status)
 							}
 						};
 					}
 					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 }
+						metadata: {
+							run_id: result.run_id,
+							...hostIdentityMetadata(run)
+						}
 					};
 					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.`,
-						metadata: { run_id: result.run_id }
+						metadata: {
+							run_id: result.run_id,
+							...hostIdentityMetadata(run)
+						}
 					};
 				}
 			}),
@@ -1090,9 +1131,146 @@ const AvenorPlugin = async (ctx) => {
 						force: args.force
 					}));
 				}
+			}),
+			avenor_workflow_status: tool({
+				description: "Get lightweight status for a workflow instance",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					supervisor_id: tool.schema.string().optional().describe("Supervisor ID for multi-supervisor mode")
+				},
+				async execute(args, _context) {
+					const result = await workflowStatusTool({
+						workflowId: args.workflow_id,
+						supervisorId: args.supervisor_id
+					});
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
+					};
+				}
+			}),
+			avenor_workflow_wait: tool({
+				description: "Wait for a workflow to reach a terminal state or until timeout",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					timeout: tool.schema.string().optional().describe("Timeout (e.g. 30s, 5m)"),
+					supervisor_id: tool.schema.string().optional().describe("Supervisor ID for multi-supervisor mode")
+				},
+				async execute(args, _context) {
+					const result = await workflowWaitTool({
+						workflowId: args.workflow_id,
+						timeout: args.timeout,
+						supervisorId: args.supervisor_id
+					});
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
+					};
+				}
+			}),
+			avenor_workflow_inspect: tool({
+				description: "Return the full instance detail for a workflow",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					supervisor_id: tool.schema.string().optional().describe("Supervisor ID for multi-supervisor mode")
+				},
+				async execute(args, _context) {
+					const result = await workflowInspectTool({
+						workflowId: args.workflow_id,
+						supervisorId: args.supervisor_id
+					});
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
+					};
+				}
+			}),
+			avenor_workflow_events: tool({
+				description: "Read log events from a workflow instance's event log",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					after_seq: tool.schema.number().optional().describe("Only include events after this sequence number"),
+					limit: tool.schema.number().optional().describe("Max events to return (default 50)"),
+					supervisor_id: tool.schema.string().optional().describe("Supervisor ID for multi-supervisor mode")
+				},
+				async execute(args, _context) {
+					const result = await workflowEventsTool({
+						workflowId: args.workflow_id,
+						afterSeq: args.after_seq,
+						limit: args.limit,
+						supervisorId: args.supervisor_id
+					});
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
+					};
+				}
+			}),
+			avenor_workflow_complete: tool({
+				description: "Atomically complete a machine/external handoff activation",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					node_id: tool.schema.string().describe("Node ID"),
+					activation_id: tool.schema.string().describe("Activation ID"),
+					attempt_id: tool.schema.string().describe("Attempt ID"),
+					lease_id: tool.schema.string().describe("Lease ID"),
+					owner_token: tool.schema.string().describe("Owner token"),
+					outcome: tool.schema.string().describe("Outcome"),
+					outputs: tool.schema.unknown().optional().describe("Outputs"),
+					artifacts: tool.schema.unknown().optional().describe("Artifacts"),
+					supervisor_id: tool.schema.string().optional().describe("Supervisor ID for multi-supervisor mode")
+				},
+				async execute(args, _context) {
+					const { supervisor_id, ...rest } = args;
+					const result = await workflowCompleteTool({
+						...rest,
+						supervisorId: supervisor_id
+					});
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
+					};
+				}
+			}),
+			avenor_workflow_gate: tool({
+				description: "Record a gate decision on a parked awaiting_gate activation",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					node_id: tool.schema.string().describe("Node ID"),
+					gate_id: tool.schema.string().describe("Gate ID"),
+					activation_id: tool.schema.string().describe("Activation ID"),
+					operation: tool.schema.enum([
+						"satisfy",
+						"reject",
+						"waive",
+						"external_result"
+					]).describe("Gate operation"),
+					actor: tool.schema.string().optional().describe("Actor"),
+					reason: tool.schema.string().optional().describe("Reason"),
+					outcome: tool.schema.string().optional().describe("Outcome"),
+					subject: tool.schema.unknown().optional().describe("Subject"),
+					poll_id: tool.schema.string().optional().describe("Poll ID"),
+					source: tool.schema.string().optional().describe("Source"),
+					result: tool.schema.string().optional().describe("Result"),
+					response_hash: tool.schema.string().optional().describe("Response hash"),
+					observed_at: tool.schema.string().optional().describe("Observed at"),
+					evidence_ids: tool.schema.array(tool.schema.string()).optional().describe("Evidence IDs"),
+					supervisor_id: tool.schema.string().optional().describe("Supervisor ID for multi-supervisor mode")
+				},
+				async execute(args, _context) {
+					const { supervisor_id, ...rest } = args;
+					const result = await workflowGateTool({
+						...rest,
+						supervisorId: supervisor_id
+					});
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
+					};
+				}
 			})
 		}
 	};
 };
 //#endregion
-export { AvenorPlugin, buildWaitingText, terminalStatus };
+export { AvenorPlugin, buildSnapshotMetadata, buildWaitingText, hostIdentityMetadata, terminalStatus };

package/package.json

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