commandmate 0.22.2 → 0.23.0

package/dist/server/src/lib/hooks/sources/hook-event-vocabulary.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * The hook spellings and payload field names that several agent CLIs happen to
+ * share (Issue #1759, S1/S2 lifted out of `agent-event-types`).
+ *
+ * `agent-event-types` used to carry `CLAUDE_HOOK_EVENT_NAMES` and
+ * `extractClaudeEventDetail` next to the seven-word vocabulary. That put one
+ * tool's spelling inside the module every tool-agnostic consumer imports, and
+ * the predictable next move — a Phase 4-2 implementer adding `BeforeTool` to
+ * the same table — is exactly the copy-paste Epic #1720 exists to stop. The
+ * words stayed in `agent-event-types`; the spellings moved here, where a source
+ * *chooses* them.
+ *
+ * The table below is not "Claude's table". #1757 §8.1 measured all four new
+ * tools, and Claude, codex and copilot spell these events identically; gemini
+ * renames half of them (`BeforeTool` / `AfterTool` / `BeforeAgent` /
+ * `AfterAgent`) and antigravity ships no event-name field at all. So this is
+ * the CamelCase dialect three tools share, and a source that speaks a different
+ * one brings its own mappers.
+ *
+ * @module lib/hooks/sources/hook-event-vocabulary
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_CALL_ID_FIELDS = exports.SESSION_ID_FIELDS = exports.CAMEL_CASE_HOOK_EVENT_NAMES = void 0;
+exports.extractSnakeCaseEventDetail = extractSnakeCaseEventDetail;
+const event_mapper_1 = require("./event-mapper");
+/**
+ * `hook_event_name` values, in the CamelCase dialect Claude / codex / copilot
+ * share, mapped onto the seven words.
+ *
+ * Only the events CommandMate registers appear. An unmapped name is refused
+ * rather than filed under something adjacent — the whole value of a structured
+ * event is that it says precisely what happened.
+ *
+ * `PermissionRequest` is deliberately absent: its response body is a decision
+ * the agent obeys, which is the opposite contract to the fire-and-forget event
+ * route (#1724). It travels through {@link AgentEventSource.encodeVerdict}.
+ *
+ * `PostToolUse` is here on the strength of a measurement taken for #1726 rather
+ * than of the #1721 spike, which recorded it as unobserved. Driving a live
+ * Claude v2.1.223 session on 2026-08-06 with a `PostToolUse` hook registered:
+ *
+ * ```
+ * 15:36:04.112  PreToolUse   AskUserQuestion   (picker drawn)
+ * 15:36:10.127  Notification permission_prompt (picker still up)
+ * 15:36:28.643  PostToolUse  AskUserQuestion   (the human answered)
+ * 15:36:29.992  Stop
+ * ```
+ *
+ * It fires, and it is the precise signal — "this tool call is over" — where
+ * `Stop` is "the turn is over" and can be minutes later if the agent keeps
+ * working after the answer.
+ */
+exports.CAMEL_CASE_HOOK_EVENT_NAMES = {
+    Stop: 'stop',
+    SubagentStop: 'stop',
+    Notification: 'notification',
+    SessionStart: 'session_start',
+    SessionEnd: 'session_end',
+    UserPromptSubmit: 'user_prompt_submit',
+    // Issue #1726. Injected with matcher `AskUserQuestion`, so in practice these
+    // only ever arrive for that tool — but a receiver re-reads `tool_name` rather
+    // than trusting the matcher, because a user's own settings.json is
+    // concatenated with the injected one and may register a wider matcher.
+    PreToolUse: 'pre_tool_use',
+    PostToolUse: 'post_tool_use',
+};
+/**
+ * Payload keys that carry the agent's own session id, in preference order
+ * (#1757 R4).
+ *
+ * `session_id` covers Claude, codex, copilot and gemini; `conversationId` is
+ * antigravity's protojson spelling of the same thing. Never an identity key —
+ * `/clear` mints a new one while the instance is unchanged (#1721).
+ */
+exports.SESSION_ID_FIELDS = ['session_id', 'conversationId'];
+/**
+ * Payload keys that correlate one tool call (#1757 R5).
+ *
+ * `tool_use_id` is Claude's and codex's; it is absent from `PermissionRequest`
+ * on both (D2), so nothing may require it.
+ */
+exports.TOOL_CALL_ID_FIELDS = ['tool_use_id'];
+/**
+ * The event's subtype for a snake_case payload, or null when it has none.
+ *
+ * Each event spells this differently and none of them share a field:
+ *
+ * - `Notification` → `notification_type` (`permission_prompt` / `idle_prompt`).
+ *   This is also what a `Notification` matcher is tested against — **not**
+ *   `message`, which is English prose for a human (#1721 D3).
+ * - `SessionEnd` → `reason` (`clear` / `prompt_input_exit` / …)
+ * - `SessionStart` → `source` (`startup` / `clear` / …)
+ * - `PreToolUse` / `PostToolUse` → `tool_name` (`AskUserQuestion`), Issue #1726
+ *
+ * `stop` and `user_prompt_submit` have no subtype, so they answer null.
+ */
+function extractSnakeCaseEventDetail(event, payload) {
+    const field = event === 'notification'
+        ? 'notification_type'
+        : event === 'session_end'
+            ? 'reason'
+            : event === 'session_start'
+                ? 'source'
+                : event === 'pre_tool_use' || event === 'post_tool_use'
+                    ? 'tool_name'
+                    : null;
+    if (field === null)
+        return null;
+    return (0, event_mapper_1.boundDetail)((0, event_mapper_1.readStringField)(payload, field));
+}

package/dist/server/src/lib/hooks/sources/index.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * `AgentEventSource` — the public surface (Issue #1759).
+ *
+ * Import from here rather than from the files underneath. Importing `./registry`
+ * is what registers the built-in sources, so this barrel is also the guarantee
+ * that a caller who reached for the types got the implementations too.
+ *
+ * The spec this implements is `docs/design/agent-event-source-interface.md`,
+ * which also carries the checklist for adding a tool.
+ *
+ * @module lib/hooks/sources
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_CLI_TOOL_ID = exports.CODEX_CLI_TOOL_ID = exports.ANTIGRAVITY_CLI_TOOL_ID = exports.GEMINI_CLI_TOOL_ID = exports.COPILOT_CLI_TOOL_ID = exports.CLAUDE_CLI_TOOL_ID = exports.isAbstainSafe = exports.describeNoDecision = exports.describeAbstain = exports.resetPendingDecisions = exports.openDecisionSlot = exports.listOpenDecisions = exports.closeDecisionSlot = exports.answerPendingDecision = exports.TOOL_CALL_ID_FIELDS = exports.SESSION_ID_FIELDS = exports.extractSnakeCaseEventDetail = exports.CAMEL_CASE_HOOK_EVENT_NAMES = exports.whenNamed = exports.runEventMappers = exports.resetUnknownEventTallies = exports.readStringField = exports.readNestedString = exports.readFirstStringField = exports.isPlainObject = exports.getUnknownEventTally = exports.fromNameTable = exports.boundDetail = exports.definePushHookSource = exports.definePullEventSource = exports.unregisterAgentEventSource = exports.registerAgentEventSource = exports.listAgentEventSources = exports.hasAgentEventSource = exports.getAgentEventSource = void 0;
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "getAgentEventSource", { enumerable: true, get: function () { return registry_1.getAgentEventSource; } });
+Object.defineProperty(exports, "hasAgentEventSource", { enumerable: true, get: function () { return registry_1.hasAgentEventSource; } });
+Object.defineProperty(exports, "listAgentEventSources", { enumerable: true, get: function () { return registry_1.listAgentEventSources; } });
+Object.defineProperty(exports, "registerAgentEventSource", { enumerable: true, get: function () { return registry_1.registerAgentEventSource; } });
+Object.defineProperty(exports, "unregisterAgentEventSource", { enumerable: true, get: function () { return registry_1.unregisterAgentEventSource; } });
+var define_source_1 = require("./define-source");
+Object.defineProperty(exports, "definePullEventSource", { enumerable: true, get: function () { return define_source_1.definePullEventSource; } });
+Object.defineProperty(exports, "definePushHookSource", { enumerable: true, get: function () { return define_source_1.definePushHookSource; } });
+var event_mapper_1 = require("./event-mapper");
+Object.defineProperty(exports, "boundDetail", { enumerable: true, get: function () { return event_mapper_1.boundDetail; } });
+Object.defineProperty(exports, "fromNameTable", { enumerable: true, get: function () { return event_mapper_1.fromNameTable; } });
+Object.defineProperty(exports, "getUnknownEventTally", { enumerable: true, get: function () { return event_mapper_1.getUnknownEventTally; } });
+Object.defineProperty(exports, "isPlainObject", { enumerable: true, get: function () { return event_mapper_1.isPlainObject; } });
+Object.defineProperty(exports, "readFirstStringField", { enumerable: true, get: function () { return event_mapper_1.readFirstStringField; } });
+Object.defineProperty(exports, "readNestedString", { enumerable: true, get: function () { return event_mapper_1.readNestedString; } });
+Object.defineProperty(exports, "readStringField", { enumerable: true, get: function () { return event_mapper_1.readStringField; } });
+Object.defineProperty(exports, "resetUnknownEventTallies", { enumerable: true, get: function () { return event_mapper_1.resetUnknownEventTallies; } });
+Object.defineProperty(exports, "runEventMappers", { enumerable: true, get: function () { return event_mapper_1.runEventMappers; } });
+Object.defineProperty(exports, "whenNamed", { enumerable: true, get: function () { return event_mapper_1.whenNamed; } });
+var hook_event_vocabulary_1 = require("./hook-event-vocabulary");
+Object.defineProperty(exports, "CAMEL_CASE_HOOK_EVENT_NAMES", { enumerable: true, get: function () { return hook_event_vocabulary_1.CAMEL_CASE_HOOK_EVENT_NAMES; } });
+Object.defineProperty(exports, "extractSnakeCaseEventDetail", { enumerable: true, get: function () { return hook_event_vocabulary_1.extractSnakeCaseEventDetail; } });
+Object.defineProperty(exports, "SESSION_ID_FIELDS", { enumerable: true, get: function () { return hook_event_vocabulary_1.SESSION_ID_FIELDS; } });
+Object.defineProperty(exports, "TOOL_CALL_ID_FIELDS", { enumerable: true, get: function () { return hook_event_vocabulary_1.TOOL_CALL_ID_FIELDS; } });
+var pending_decisions_1 = require("./pending-decisions");
+Object.defineProperty(exports, "answerPendingDecision", { enumerable: true, get: function () { return pending_decisions_1.answerPendingDecision; } });
+Object.defineProperty(exports, "closeDecisionSlot", { enumerable: true, get: function () { return pending_decisions_1.closeDecisionSlot; } });
+Object.defineProperty(exports, "listOpenDecisions", { enumerable: true, get: function () { return pending_decisions_1.listOpenDecisions; } });
+Object.defineProperty(exports, "openDecisionSlot", { enumerable: true, get: function () { return pending_decisions_1.openDecisionSlot; } });
+Object.defineProperty(exports, "resetPendingDecisions", { enumerable: true, get: function () { return pending_decisions_1.resetPendingDecisions; } });
+var abstain_1 = require("./abstain");
+Object.defineProperty(exports, "describeAbstain", { enumerable: true, get: function () { return abstain_1.describeAbstain; } });
+Object.defineProperty(exports, "describeNoDecision", { enumerable: true, get: function () { return abstain_1.describeNoDecision; } });
+Object.defineProperty(exports, "isAbstainSafe", { enumerable: true, get: function () { return abstain_1.isAbstainSafe; } });
+var tool_id_1 = require("./claude/tool-id");
+Object.defineProperty(exports, "CLAUDE_CLI_TOOL_ID", { enumerable: true, get: function () { return tool_id_1.CLAUDE_CLI_TOOL_ID; } });
+var tool_id_2 = require("./copilot/tool-id");
+Object.defineProperty(exports, "COPILOT_CLI_TOOL_ID", { enumerable: true, get: function () { return tool_id_2.COPILOT_CLI_TOOL_ID; } });
+var tool_id_3 = require("./gemini/tool-id");
+Object.defineProperty(exports, "GEMINI_CLI_TOOL_ID", { enumerable: true, get: function () { return tool_id_3.GEMINI_CLI_TOOL_ID; } });
+var tool_id_4 = require("./antigravity/tool-id");
+Object.defineProperty(exports, "ANTIGRAVITY_CLI_TOOL_ID", { enumerable: true, get: function () { return tool_id_4.ANTIGRAVITY_CLI_TOOL_ID; } });
+var tool_id_5 = require("./codex/tool-id");
+Object.defineProperty(exports, "CODEX_CLI_TOOL_ID", { enumerable: true, get: function () { return tool_id_5.CODEX_CLI_TOOL_ID; } });
+var tool_id_6 = require("./opencode/tool-id");
+Object.defineProperty(exports, "OPENCODE_CLI_TOOL_ID", { enumerable: true, get: function () { return tool_id_6.OPENCODE_CLI_TOOL_ID; } });

package/dist/server/src/lib/hooks/sources/legacy-relay.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * The source used for a tool that has no source yet (Issue #1759).
+ *
+ * `POST /api/hooks/agent-event` has accepted `{"tool":"codex","event":"stop"}`
+ * since #1549, from hooks operators wired up by hand following
+ * `docs/user-guide/agent-event-hooks.md`. Those requests work today, and Phase
+ * 4-1 is a refactor: if asking the registry for an unregistered tool returned
+ * nothing, every one of them would start failing on the day this abstraction
+ * landed, for a reason that has nothing to do with what changed.
+ *
+ * So an unregistered tool gets this: the CamelCase name table and the
+ * snake_case subtype extraction that the receiver applied to every tool before
+ * the abstraction existed, which is exactly the behaviour being preserved. It
+ * is *not* a claim that the table is right for that tool — gemini spells four
+ * of the seven differently and antigravity spells none of them — only that a
+ * hook posting `{"event":"stop"}` keeps working while its tool waits for Phase
+ * 4-2…4-5.
+ *
+ * Its capabilities say so: `supportedEvents` is empty, which is the honest
+ * answer to "what does this tool emit?" when nobody has measured it. A caller
+ * that consults capabilities gets "unknown", not a confident wrong answer.
+ *
+ * Registering a real source for a tool replaces this automatically; there is no
+ * list to remove it from.
+ *
+ * @module lib/hooks/sources/legacy-relay
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLegacyRelaySource = createLegacyRelaySource;
+const ask_user_question_payload_1 = require("../../../lib/hooks/ask-user-question-payload");
+const permission_request_payload_1 = require("../../../lib/hooks/permission-request-payload");
+const source_1 = require("./claude/source");
+const define_source_1 = require("./define-source");
+const event_mapper_1 = require("./event-mapper");
+const hook_event_vocabulary_1 = require("./hook-event-vocabulary");
+/**
+ * Build the compatibility source for one tool.
+ *
+ * @param cliToolId - The tool nobody has written a source for yet
+ */
+function createLegacyRelaySource(cliToolId) {
+    return (0, define_source_1.definePushHookSource)({
+        cliToolId,
+        // The conservative reading, and the one that is true of the relay path this
+        // stands in for: a hook whose server does not answer is fail-open on every
+        // tool measured so far (#1757 §1.2). It is stated rather than inherited so
+        // that a tool where it is false — antigravity — cannot quietly ride on it;
+        // that tool gets a real source in Phase 4-4, with its own value.
+        noDecision: { kind: 'proceeds' },
+        capabilities: {
+            // Deliberately empty. Nothing has been measured for this tool through
+            // this path, and an empty list reads as "unknown" where a copy of
+            // Claude's list would read as a promise.
+            supportedEvents: [],
+            configScope: 'none',
+            decisionTimeoutSeconds: null,
+        },
+        mappers: (0, event_mapper_1.fromNameTable)(hook_event_vocabulary_1.CAMEL_CASE_HOOK_EVENT_NAMES),
+        nativeEventNameFields: ['hook_event_name'],
+        conversationIdFields: hook_event_vocabulary_1.SESSION_ID_FIELDS,
+        toolCallIdFields: hook_event_vocabulary_1.TOOL_CALL_ID_FIELDS,
+        extractDetail: hook_event_vocabulary_1.extractSnakeCaseEventDetail,
+        // Both receivers applied these parsers to every tool before #1759, so both
+        // stay wired here. They are strict — a payload that is not in Claude's
+        // shape answers null, which becomes "no structured data" / "no decision" —
+        // so applying them to a tool whose shape is unknown costs nothing and
+        // changes no behaviour that existed on the day this file landed.
+        parsePermissionRequest: (payload) => (0, permission_request_payload_1.parsePermissionRequestPayload)(payload),
+        parseQuestion: (payload) => (0, ask_user_question_payload_1.parseAskUserQuestionPayload)(payload),
+        // Likewise the verdict body: the permission receiver emitted Claude's shape
+        // for whatever tool reached it. **A real source must override this.**
+        // antigravity in particular reads an empty object as a denial and stops the
+        // tool call (#1757 P10), so Phase 4-4 has to encode abstention positively
+        // rather than inherit anything from here.
+        encodeVerdict: source_1.encodeClaudeVerdict,
+        // CommandMate does not inject config for these tools; their `startSession`
+        // in `src/lib/cli-tools/<tool>.ts` launches them bare.
+        prepareLaunch: (_target, executablePath) => ({
+            command: executablePath,
+            settingsPath: null,
+        }),
+    });
+}

package/dist/server/src/lib/hooks/sources/opencode/client.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * Talking to one opencode server (Issue #1763).
+ *
+ * The server is not a separate process. #1758 §5.1.2 measured that the plain
+ * `opencode` TUI *is* an HTTP server when it is given `--port`: `/global/health`,
+ * `/event`, `GET /permission` and the reply endpoints all answered identically
+ * to `opencode serve`. So there is no daemon to supervise here — the server's
+ * lifetime is the pane's lifetime, and everything in this file is a request to
+ * a port that either answers or does not.
+ *
+ * Four measurements shape the choices below.
+ *
+ *  - **The subscription is legacy `GET /event`.** `GET /api/event` (v2) goes
+ *    silent after the first three frames of a turn, reproducibly, and
+ *    `GET /api/session/:id/event?after=<seq>` returns zero bytes — so neither
+ *    the newer envelope nor durable replay is usable on 1.18.3 (#1758 §5.2.2).
+ *  - **The frames name their event in the JSON, not in the SSE `event:` field.**
+ *    Every frame is a bare `data:` line, so a named `EventSource` listener picks
+ *    up nothing. The parser below reads `data:` and nothing else.
+ *  - **Replies go to `POST /permission/:requestID/reply`.** There are two
+ *    endpoints and they differ (#1758 §5.5.2): the per-session one takes
+ *    `{"response":…}` and cannot carry a reason, while this one takes
+ *    `{"reply":…, "message"?:…}` and the message reaches the agent verbatim —
+ *    it turned up in the tool part's `state.error`. One had to be picked and
+ *    fixed; this is the superset, and a denial CommandMate cannot explain is a
+ *    denial the agent cannot act on.
+ *  - **Absence is free to detect.** A closed port fails in under a millisecond
+ *    (§5.7.2), so health checks cost nothing and every call here is allowed to
+ *    be attempted rather than guarded by cached state.
+ *
+ * Nothing in this module throws. A source that cannot reach its agent has to
+ * degrade to the screen scraper, and an exception on the way to that decision
+ * would take the caller down with it.
+ *
+ * @module lib/hooks/sources/opencode/client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_REQUEST_TIMEOUT_MS = exports.OPENCODE_SERVER_HOST = void 0;
+exports.opencodeBaseUrl = opencodeBaseUrl;
+exports.fetchOpencodeHealth = fetchOpencodeHealth;
+exports.fetchOpencodePendingPermissions = fetchOpencodePendingPermissions;
+exports.fetchOpencodePendingQuestions = fetchOpencodePendingQuestions;
+exports.fetchOpencodeActivity = fetchOpencodeActivity;
+exports.replyOpencodePermission = replyOpencodePermission;
+exports.replyOpencodeQuestion = replyOpencodeQuestion;
+exports.createSseParser = createSseParser;
+exports.readOpencodeEventStream = readOpencodeEventStream;
+const logger_1 = require("../../../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/client');
+/**
+ * The only host an opencode server is ever addressed on.
+ *
+ * `--hostname` defaults to this and the spike confirmed the LAN address refuses
+ * connections (#1758 §5.8.3). The server is unauthenticated by default, so
+ * binding it anywhere else would publish an arbitrary-command execution API to
+ * the network; `--mdns`, which flips the default to `0.0.0.0`, is never passed.
+ */
+exports.OPENCODE_SERVER_HOST = '127.0.0.1';
+/** Timeout for the small request/response calls. Generous: they answer in ms. */
+exports.OPENCODE_REQUEST_TIMEOUT_MS = 5_000;
+/** `http://127.0.0.1:<port>`. */
+function opencodeBaseUrl(port) {
+    return `http://${exports.OPENCODE_SERVER_HOST}:${port}`;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * One JSON request, with a timeout, that answers null instead of throwing.
+ *
+ * @param url - Absolute URL on the loopback server
+ * @param init - Method / body; a timeout signal is added
+ * @returns The parsed body, or null on any failure at all
+ */
+async function requestJson(url, init) {
+    try {
+        const response = await fetch(url, {
+            ...init,
+            signal: AbortSignal.timeout(exports.OPENCODE_REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        return (await response.json());
+    }
+    catch (error) {
+        // Includes the ordinary case: nothing is listening because the pane exited.
+        logger.debug('opencode-request-failed', {
+            url,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Ask whether an opencode server is listening on this port.
+ *
+ * @returns Its health and version, or null when nothing answered
+ */
+async function fetchOpencodeHealth(port) {
+    const body = await requestJson(`${opencodeBaseUrl(port)}/global/health`);
+    if (!isPlainObject(body))
+        return null;
+    if (body.healthy !== true)
+        return null;
+    return { healthy: true, version: typeof body.version === 'string' ? body.version : null };
+}
+/** An array body, or an empty array — `GET /permission` answers a bare array. */
+function asObjectArray(body) {
+    if (!Array.isArray(body))
+        return [];
+    return body.filter(isPlainObject);
+}
+/**
+ * The approvals currently waiting on a human (#1758 §5.4).
+ *
+ * This is what makes a missed `permission.asked` recoverable: the event is
+ * gone, but the pending state is still readable, which is the whole of the
+ * reconnect strategy since `?after=<seq>` returns nothing.
+ */
+async function fetchOpencodePendingPermissions(port) {
+    return asObjectArray(await requestJson(`${opencodeBaseUrl(port)}/permission`));
+}
+/** The questions currently waiting on a human. */
+async function fetchOpencodePendingQuestions(port) {
+    return asObjectArray(await requestJson(`${opencodeBaseUrl(port)}/question`));
+}
+/**
+ * Whether any session on this server is working (#1758 §5.7.4).
+ *
+ * `GET /session/status` answers `{"ses_…":{"type":"busy"|"idle"}}`. Note what
+ * this does *not* answer: a session blocked on an approval reads `busy`, so
+ * this says "the turn is not over", never "the agent is thinking".
+ *
+ * @returns `busy` when any session is busy, `idle` when none is, null when the
+ *   server could not be asked
+ */
+async function fetchOpencodeActivity(port) {
+    const body = await requestJson(`${opencodeBaseUrl(port)}/session/status`);
+    if (!isPlainObject(body))
+        return null;
+    for (const value of Object.values(body)) {
+        if (isPlainObject(value) && value.type === 'busy')
+            return 'busy';
+    }
+    return 'idle';
+}
+/**
+ * Answer one approval.
+ *
+ * @param port - The instance's server
+ * @param requestId - `per_…`, from `permission.asked` / `GET /permission`
+ * @param reply - `once` runs it and asks again next time; `always` saves the
+ *   pattern; `reject` fails the tool call
+ * @param message - Shown to the agent verbatim on a rejection. Only this
+ *   endpoint can carry it
+ * @returns Whether the server accepted it
+ */
+async function replyOpencodePermission(port, requestId, reply, message) {
+    const body = { reply };
+    if (message)
+        body.message = message;
+    const result = await requestJson(`${opencodeBaseUrl(port)}/permission/${encodeURIComponent(requestId)}/reply`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    return result !== null;
+}
+/**
+ * Answer one question.
+ *
+ * @param answers - One array of selected labels per question, in the order the
+ *   `question.asked` frame listed them
+ */
+async function replyOpencodeQuestion(port, questionId, answers) {
+    const result = await requestJson(`${opencodeBaseUrl(port)}/question/${encodeURIComponent(questionId)}/reply`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ answers }),
+    });
+    return result !== null;
+}
+// =============================================================================
+// SSE
+// =============================================================================
+/**
+ * Incremental parser for the one SSE shape opencode emits.
+ *
+ * `GET /event` sends frames with no `event:` line — a `data:` line, then a
+ * blank line. Multi-line `data:` is joined with `\n` per the SSE spec, though
+ * 1.18.3 has never been observed to send one; supporting it costs a line and
+ * removes a class of silent truncation.
+ *
+ * @returns A parser whose `push` returns whatever frames the chunk completed
+ */
+function createSseParser() {
+    let buffer = '';
+    let dataLines = [];
+    const completed = [];
+    const finishEvent = () => {
+        if (dataLines.length === 0)
+            return;
+        completed.push(dataLines.join('\n'));
+        dataLines = [];
+    };
+    const consumeLine = (rawLine) => {
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        if (line === '') {
+            finishEvent();
+            return;
+        }
+        if (line.startsWith(':'))
+            return; // comment / keepalive
+        if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).replace(/^ /, ''));
+        }
+        // `id:` / `event:` / `retry:` are not used by this server; ignored.
+    };
+    return {
+        push(chunk) {
+            buffer += chunk;
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex >= 0) {
+                consumeLine(buffer.slice(0, newlineIndex));
+                buffer = buffer.slice(newlineIndex + 1);
+                newlineIndex = buffer.indexOf('\n');
+            }
+            return completed.splice(0, completed.length);
+        },
+        flush() {
+            if (buffer !== '') {
+                consumeLine(buffer);
+                buffer = '';
+            }
+            finishEvent();
+            return completed.splice(0, completed.length);
+        },
+    };
+}
+/**
+ * Subscribe to one server's event stream.
+ *
+ * Yields parsed frames until the connection ends or `signal` aborts. A frame
+ * that is not JSON is skipped rather than ending the stream: a malformed line
+ * is a bug in one frame, not a reason to stop watching the session.
+ *
+ * Ending is normal and is the caller's cue to reconnect — the connection dies
+ * without a clean EOF when the server goes away (`transfer closed with
+ * outstanding read data remaining`, #1758 §5.7.2).
+ *
+ * @param port - The instance's server
+ * @param signal - Aborted by the subscription to close the stream
+ */
+async function* readOpencodeEventStream(port, signal) {
+    const response = await fetch(`${opencodeBaseUrl(port)}/event`, {
+        signal,
+        headers: { Accept: 'text/event-stream' },
+    });
+    if (!response.ok || !response.body) {
+        throw new Error(`opencode /event responded ${response.status}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const parser = createSseParser();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = decoder.decode(value, { stream: true });
+            for (const raw of parser.push(chunk)) {
+                const frame = safeParseFrame(raw);
+                if (frame)
+                    yield frame;
+            }
+        }
+        for (const raw of parser.flush()) {
+            const frame = safeParseFrame(raw);
+            if (frame)
+                yield frame;
+        }
+    }
+    finally {
+        // `cancel` on an already-aborted stream rejects; the connection is going
+        // away either way, so the failure is not actionable.
+        await reader.cancel().catch(() => { });
+    }
+}
+/** JSON, or null when the frame was not an object. */
+function safeParseFrame(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}