@dougbots/avenor-opencode 0.14.0 → 0.16.0

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 eight tools that your OpenCode agent can call directly — no extra configuration required.
+Once registered, the plugin exposes these tools that your OpenCode agent can call directly — no extra configuration required: `avenor_spawn`, `avenor_status`, `avenor_result`, `avenor_inspect`, `avenor_answer_permission`, `avenor_message`, `avenor_peers`, `avenor_events`, `avenor_kill`, `avenor_shutdown`, `avenor_workflow_cancel`, `avenor_workflow_status`, `avenor_workflow_wait`, `avenor_workflow_inspect`, `avenor_workflow_events`, `avenor_workflow_complete`, `avenor_workflow_gate`, and `avenor_workflow_controller_status`.
 
 ## Behaviour
 
@@ -42,7 +42,8 @@ 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.
-4. **Formats results** — OpenCode returns concise, bounded prose in its shared `output` for `avenor_status`, `avenor_result`, `avenor_answer_permission`, `avenor_follow_up`, `avenor_events`, `avenor_inspect`, and `avenor_shutdown`. Structured metadata stays in host/session state.
+4. **Formats results** — OpenCode returns concise, bounded prose in its shared `output` for `avenor_status`, `avenor_result`, `avenor_answer_permission`, `avenor_message`, `avenor_peers`, `avenor_events`, `avenor_inspect`, and `avenor_shutdown`. Structured metadata stays in host/session state.
+5. **Publishes its own finished turn** — a settled turn from the session that first ran a host messaging tool is recorded through `session_last_set`, so a peer's `avenor_peers` `action: "last"` can read it.
 
 MCP clients render their own results.
 
@@ -133,16 +134,34 @@ Answer a pending permission request. The `option_id` comes from the `pending_per
 | `request_id` | no | Request ID (auto-discovered if omitted) |
 | `supervisor_id` | no | Reuse an existing supervisor by socket path |
 
-### `avenor_follow_up`
+### `avenor_message`
 
-Resume a completed run with a follow-up message. Useful for iterating on results or asking the sub-agent to refine its output.
+Send a message to another run, withdraw a pending ask, resume a completed run, or deliver a control reply. Every action is explicit and every result states whether a failed ask can still be withdrawn.
 
-| Argument | Required | Description |
+| `action` | Required fields | What it does |
 |---|---|---|
-| `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 |
+| `tell` | `target`, `message` | Deliver a message without creating an ask edge |
+| `ask` | `target`, `message`, optional `timeout_ms` | Deliver a message and wait for a reply |
+| `reply` | `reply_to`, `message` | Answer an inbound ask. This session receives no inbound delivery, so the result is always `edge-absent` and nothing is sent |
+| `resume` | `target`, `message`, optional `label`, `idempotency_key` | Resume a completed run from its persisted session |
+| `withdraw` | `message_id` | Withdraw a pending ask |
+| `control_reply` | `target`, optional `payload` | Deliver a control reply where the provider supports it |
+
+`target` is a run id, a peer label, or `"self"`. `timeout_ms` must be an integer no greater than the shared ask cap. This tool does not take `supervisor_id`; it is bound to the default supervisor.
+
+The tool's structured metadata is the shared contract object in snake_case (`action`, `outcome`, `text`, and `message_id`, `run_id`, `label`, `reply`, `sentinel_file`, `on_event` when the outcome carries them), the same fields the MCP hosts return.
+
+### `avenor_peers`
+
+List the visible agent sessions, rename a run, or read a run's last agent message.
+
+| `action` | Fields | What it does |
+|---|---|---|
+| `list` (default) | — | List the visible peers |
+| `rename` | `name`, optional `session_id` | Change a display name, self by default |
+| `last` | `target` | Read the target's last agent message with its stop reason |
+
+`last` is read-only and returns the shared empty result when the target has no completed turn yet. `target` accepts a run id, a label, or `"self"`. The structured metadata is `{peers}`, `{renamed}` or `{last}` in snake_case, the same object the MCP hosts return.
 
 ### `avenor_events`
 
@@ -155,6 +174,40 @@ Read events from a run, optionally filtered by type. Returns the last N events.
 | `limit` | no | Max events to return (default 50) |
 | `supervisor_id` | no | Reuse an existing supervisor by socket path |
 
+### `avenor_kill`
+
+Terminate a run without shutting down the supervisor. Other runs and the supervisor itself keep running.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID or label of the run to terminate |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor mode |
+
+### `avenor_workflow_cancel`
+
+Cancel a workflow instance. Both the actor and the reason are required; the manager rejects a missing actor before it looks at the reason.
+
+| Argument | Required | Description |
+|---|---|---|
+| `workflow_id` | yes | Workflow ID |
+| `actor` | yes | Who is cancelling |
+| `reason` | yes | Why the workflow is being cancelled |
+| `supervisor_id` | no | Supervisor ID for multi-supervisor mode |
+
+### Workflow tools
+
+The remaining workflow tools read or drive workflow instances. Their argument lists are in [`docs/control-protocol.md`](../../docs/control-protocol.md).
+
+| Tool | Purpose |
+|---|---|
+| `avenor_workflow_status` | Lightweight instance status |
+| `avenor_workflow_wait` | Wait for a terminal state or a timeout |
+| `avenor_workflow_inspect` | Full instance detail |
+| `avenor_workflow_events` | The instance's log events |
+| `avenor_workflow_complete` | Complete a machine/external handoff activation |
+| `avenor_workflow_gate` | Record a gate decision on a parked activation |
+| `avenor_workflow_controller_status` | Controller status, with an advisory candidate count |
+
 ### `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.
@@ -172,7 +225,7 @@ Shut down the avenor supervisor process and clean up temp files. Call this when
 2. (avenor_answer_permission  →  if a permission is routed to this session mid-run)
 3. tool call returns       →  completion preview with status + session_id
 4. avenor_result           →  retrieve the complete final output when needed
-5. avenor_follow_up        →  optionally iterate
+5. avenor_message          →  optionally iterate with action "resume"
 6. avenor_shutdown         →  clean up when finished
 ```
 

package/dist/index.js

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 import * as crypto from "node:crypto";
-import { Supervisor, THINKING_LEVELS, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, followUpTool, inspectTool, killTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, validateSpawnSelection, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
+import { Supervisor, THINKING_LEVELS, answerPermissionTool, boundFinalOutput, createHostMessageProvider, createRunSnapshot, dial, eventsTool, extractEventText, extractTurnText, getSupervisorClient, inspectTool, killTool, messageTool, normalizeTurnStopReason, observeRun, peersDetails, peersTool, renderPeerList, resultOutput, resultTool, shutdownTool, spawnTool, statusTool, validateSpawnSelection, workflowCancelTool, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool } from "@dougbots/avenor-core";
 //#region src/render.ts
 const FINAL_OUTPUT_CHARS$1 = 1500;
 const SCALAR_CHARS = 240;
@@ -121,7 +121,7 @@ function guidance(status, pending, runId) {
 		const options = permissionOptions(pending);
 		if (options.length > 0) return `Guidance: Call avenor_answer_permission with run_id "${runId}" and option_id "${selected(options[0], "option_id")}".`;
 		if (pending) return `Guidance: Permission input is required, but no options are available; call avenor_inspect with run_id "${runId}".`;
-		return `Guidance: Call avenor_follow_up or avenor_status with run_id "${runId}".`;
+		return `Guidance: Call avenor_message with action "resume" or avenor_status with run_id "${runId}".`;
 	}
 	if (isTerminal(status)) return `Guidance: Call avenor_result or avenor_events with run_id "${runId}".`;
 	return `Guidance: Call avenor_result with run_id "${runId}".`;
@@ -212,14 +212,13 @@ function permissionLines(details, args) {
 		`Guidance: Call avenor_status with run_id "${runId}" to verify the permission state.`
 	];
 }
-function followUpLines(details, args) {
-	const result = asRecord(details);
-	if (!result || !stringValue(result.run_id) || !stringValue(result.label)) return void 0;
-	const runId = selected(result, "run_id", args.run_id);
-	const label = selected(result, "label", args.label, runId);
+function messageResumeLines(result, args) {
+	const runId = stringValue(result.runId);
+	const label = stringValue(result.label);
+	if (!runId || !label) return void 0;
 	return [
-		`Follow-up: ${label} — dispatched.`,
-		`Source run: ${scalar(args.run_id)}`,
+		`Message: ${label} — resumed.`,
+		`Source run: ${scalar(args.target)}`,
 		`Run: ${runId}`,
 		`Label: ${label}`,
 		`Guidance: Call avenor_status with run_id "${runId}".`
@@ -365,16 +364,30 @@ function formatAnswerPermissionOutput(args, result) {
 		}
 	};
 }
-function formatFollowUpOutput(args, result) {
-	const record = result;
-	const runId = selected(record, "run_id", args.run_id);
+function formatMessageResumeOutput(args, result) {
+	const runId = stringValue(result.runId) ?? scalar(args.target);
 	return {
-		title: `${selected(record, "label", args.label, runId)} — dispatched`,
-		output: output(followUpLines(result, args), "follow_up"),
-		metadata: {
-			...result,
-			source_run_id: args.run_id
-		}
+		title: `${stringValue(result.label) ?? scalar(args.label) ?? runId} — resumed`,
+		output: output(messageResumeLines(result, args), "message"),
+		metadata: resultOutput(result)
+	};
+}
+/** Every message action's prose comes from the contract's `text`; only a resume
+* keeps the structured acknowledgement lines the old follow-up tool rendered. */
+function formatMessageOutput(args, result) {
+	if (args.action === "resume") return formatMessageResumeOutput(args, result);
+	return {
+		title: `Avenor ${stringValue(result.action) ?? scalar(args.action)} — ${stringValue(result.outcome) ?? "unknown"}`,
+		output: stringValue(result.text) ?? output(void 0, "message"),
+		metadata: resultOutput(result)
+	};
+}
+function formatPeersOutput(args, result) {
+	const text = result.action === "list" ? [result.text, renderPeerList(result.peers)].filter((part) => part !== "").join("\n\n") : result.text;
+	return {
+		title: `Avenor peers — ${result.action}`,
+		output: text || output(void 0, "peers"),
+		metadata: peersDetails(result)
 	};
 }
 function formatEventsOutput(args, result) {
@@ -581,7 +594,7 @@ function buildWaitingText(run, snapshot) {
 	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.`);
+	if (!permission) lines.push(`Use \`avenor_message\` with action "resume" and target "${run.runId}" to respond, or \`avenor_status\` to re-check.`);
 	return lines.join("\n");
 }
 function buildCompletionText(run, snapshot, status, finalOutput) {
@@ -592,7 +605,7 @@ function buildCompletionText(run, snapshot, status, finalOutput) {
 	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.`);
+	lines.push("", `Call \`avenor_events\` with \`run_id: "${run.runId}"\` for raw events, or \`avenor_message\` with action "resume" to iterate.`);
 	return lines.join("\n");
 }
 const CHANNEL_RE = /<channel\s+source="([^"]*)"(?:\s+from_run_id="([^"]*)")?(?:\s+from_role="([^"]*)")?[^>]*>([\s\S]*?)<\/channel>/g;
@@ -915,8 +928,148 @@ const AvenorPlugin = async (ctx) => {
 			channelPolling = false;
 		}
 	}
+	let hostProvider;
+	let hostBinding;
+	let bindSeq = 0;
+	async function boundHostProvider() {
+		const { client, supervisorId } = await getSupervisorClient(void 0, { owner: true });
+		if (hostProvider && hostProvider.client === client) return hostProvider.binding;
+		const seq = ++bindSeq;
+		const preflight = await client.messagePreflight();
+		const stale = seq !== bindSeq;
+		if (stale && hostProvider) return hostProvider.binding;
+		const binding = {
+			provider: createHostMessageProvider({
+				surface: "opencode",
+				supervisorId,
+				generation: preflight.generation,
+				client
+			}),
+			supervisorId,
+			generation: preflight.generation
+		};
+		if (stale) return binding;
+		hostProvider = {
+			client,
+			binding
+		};
+		if (hostBinding) hostBinding = {
+			...binding,
+			sessionId: hostBinding.sessionId
+		};
+		return binding;
+	}
+	async function hostMessageProvider(sessionId) {
+		const bound = await boundHostProvider();
+		if (!hostBinding) hostBinding = {
+			...bound,
+			sessionId
+		};
+		else if (hostBinding.sessionId !== sessionId) console.error(`opencode: host session already bound to ${hostBinding.sessionId}`);
+		return {
+			...bound.provider,
+			onResumed: (result) => trackResumed(sessionId, result)
+		};
+	}
+	async function trackResumed(sessionId, result) {
+		const run = {
+			runId: result.runId ?? "",
+			orchestratorSessionId: sessionId,
+			label: result.label ?? result.runId ?? "",
+			supervisorId: hostBinding?.supervisorId,
+			monitoring: false
+		};
+		trackedRuns.set(run.runId, run);
+		await primeTrackedRun(run);
+		monitorRun(run).catch(console.error);
+	}
+	let publishedTurn;
+	let publishChain = Promise.resolve();
+	function isNewerTurn(created, id) {
+		if (!publishedTurn) return true;
+		if (created !== publishedTurn.created) return created > publishedTurn.created;
+		return id > publishedTurn.id;
+	}
+	/** The raw stop reason one settled OpenCode assistant message reports. */
+	function stopReasonOf(info) {
+		const error = info.error;
+		if (error !== null && typeof error === "object") {
+			const name = error.name;
+			if (name === "MessageAbortedError") return "aborted";
+			if (name === "MessageOutputLengthError") return "length";
+			return "error";
+		}
+		const finish = typeof info.finish === "string" ? info.finish.trim() : "";
+		return finish === "" ? "end_turn" : finish;
+	}
+	/**
+	* Translate the ai-sdk finish spellings onto the words the shared normaliser
+	* knows. They are adapter vocabulary, not pi spellings, so they are mapped
+	* here rather than in the shared table a Pi child's session.end also uses.
+	*/
+	function normalizeFinish(stopReason) {
+		switch (stopReason) {
+			case "tool-calls":
+			case "tool_calls":
+			case "toolUse": return "tool_use";
+			case "end-turn": return "end_of_turn";
+			default: return stopReason;
+		}
+	}
+	/**
+	* The text parts of one assistant message, read by id. The read is bounded to
+	* the message the event carried, never the session's whole history.
+	*/
+	async function settledTurnText(sessionId, messageId) {
+		const response = await ctx.client.session.message({ path: {
+			id: sessionId,
+			messageID: messageId
+		} });
+		return (Array.isArray(response.data?.parts) ? response.data.parts : []).filter((part) => part !== null && typeof part === "object").filter((part) => part.type === "text").map((part) => part.text ?? "");
+	}
+	async function publishHostTurn(info) {
+		const binding = hostBinding;
+		if (!binding) return;
+		if (info.role !== "assistant") return;
+		if (info.sessionID !== binding.sessionId) return;
+		if (info.summary === true) return;
+		const time = info.time;
+		if (typeof time?.completed !== "number") return;
+		const created = typeof time.created === "number" ? time.created : 0;
+		const messageId = typeof info.id === "string" ? info.id : "";
+		if (messageId === "") return;
+		if (!binding.provider.recordLastTurn) return;
+		const publish = publishChain.then(() => publishTurn(binding, info, created, messageId));
+		publishChain = publish.catch(() => {});
+		await publish;
+	}
+	/**
+	* One queued publish. The newest-turn gate is read here rather than before
+	* queueing, so it sees the turn the publish ahead of it claimed.
+	*/
+	async function publishTurn(binding, info, created, messageId) {
+		if (!isNewerTurn(created, messageId)) return;
+		try {
+			const turn = extractTurnText([{
+				content: await settledTurnText(binding.sessionId, messageId),
+				stopReason: normalizeTurnStopReason(normalizeFinish(stopReasonOf(info)))
+			}]);
+			const bounded = boundFinalOutput(turn.text);
+			await binding.provider.recordLastTurn(bounded, turn.stopReason, turn.text.length > bounded.length);
+			publishedTurn = {
+				created,
+				id: messageId
+			};
+		} catch (error) {
+			console.error("[avenor] session_last_set failed:", error instanceof Error ? error.message : error);
+		}
+	}
 	return {
 		event: async ({ event }) => {
+			if (event.type === "message.updated") {
+				await publishHostTurn(event.properties.info);
+				return;
+			}
 			if (event.type !== "session.idle") return;
 			const { sessionID } = event.properties;
 			pollChannelMessages(sessionID).catch(console.error);
@@ -1140,34 +1293,64 @@ const AvenorPlugin = async (ctx) => {
 					}));
 				}
 			}),
-			avenor_follow_up: tool({
-				description: "Resume a completed run with a follow-up message.",
+			avenor_message: tool({
+				description: "Send a message to another agent run, withdraw a pending ask, resume a completed run, or deliver a control reply. Every action is explicit and the result states whether a failed ask can still be withdrawn. `reply` always reports edge-absent here: this session receives no inbound asks, so nothing is sent.",
 				args: {
-					run_id: tool.schema.string().describe("Completed run ID to resume"),
-					message: tool.schema.string().describe("Follow-up message text"),
-					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")
+					action: tool.schema.enum([
+						"tell",
+						"ask",
+						"reply",
+						"resume",
+						"withdraw",
+						"control_reply"
+					]).describe("tell | ask | reply | resume | withdraw | control_reply"),
+					target: tool.schema.string().optional().describe("Recipient for tell/ask/resume (a run id, a peer label, or \"self\"), or the opaque control message id for control_reply"),
+					message: tool.schema.string().optional().describe("Message text for tell/ask/reply/resume"),
+					reply_to: tool.schema.string().optional().describe("Inbound ask id being answered (reply)"),
+					message_id: tool.schema.string().optional().describe("Ask id being withdrawn (withdraw)"),
+					timeout_ms: tool.schema.number().int().optional().describe("Bound on the ask wait in milliseconds"),
+					label: tool.schema.string().optional().describe("Override label for the resumed run (resume)"),
+					idempotency_key: tool.schema.string().optional().describe("Forwarded verbatim to the resume authority (resume)"),
+					payload: tool.schema.unknown().optional().describe("Control reply body (control_reply)")
 				},
 				async execute(args, context) {
-					const result = await followUpTool({
-						runId: args.run_id,
-						message: args.message,
-						label: args.label,
-						supervisorId: args.supervisor_id
+					return formatMessageOutput(args, await messageTool(args, await hostMessageProvider(context.sessionID), { signal: context.abort }));
+				}
+			}),
+			avenor_peers: tool({
+				description: "List the visible agent sessions, rename a run, or read a run's last agent message. `last` returns the target's final text with its stop reason, or an empty result when the target has no completed turn yet.",
+				args: {
+					action: tool.schema.enum([
+						"list",
+						"rename",
+						"last"
+					]).optional().describe("list (the default) | rename | last"),
+					name: tool.schema.string().optional().describe("New display name (rename)"),
+					session_id: tool.schema.string().optional().describe("Run to rename; omitted renames the caller (rename)"),
+					target: tool.schema.string().optional().describe("Peer to read: a run id, a label, or \"self\" (last)")
+				},
+				async execute(args, context) {
+					return formatPeersOutput(args, await peersTool(args, await hostMessageProvider(context.sessionID)));
+				}
+			}),
+			avenor_workflow_cancel: tool({
+				description: "Cancel a workflow instance. The actor and reason are required.",
+				args: {
+					workflow_id: tool.schema.string().describe("Workflow ID"),
+					actor: tool.schema.string().describe("Who is cancelling"),
+					reason: tool.schema.string().describe("Why the workflow is being cancelled"),
+					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 workflowCancelTool({
+						...rest,
+						supervisorId: 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
+					return {
+						title: "workflow",
+						output: JSON.stringify(result, null, 2)
 					};
-					trackedRuns.set(result.run_id, run);
-					await primeTrackedRun(run);
-					monitorRun(run).catch(console.error);
-					return formatFollowUpOutput(args, result);
 				}
 			}),
 			avenor_events: tool({

package/package.json

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