commandmate 0.22.2 → 0.23.0

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

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * opencode as an {@link AgentEventSource} — the first pull implementation
+ * (Issue #1763, Epic #1720 Phase 4-5).
+ *
+ * Five tools push into `POST /api/hooks/agent-event`; this one is subscribed
+ * to. #1758 established that the difference is real and not cosmetic, and
+ * #1759 built the interface so it could be expressed without a special case.
+ * What is here is that expression: `definePullEventSource`, the measured
+ * values, and nothing shaped like `if (tool === 'opencode')` anywhere above it.
+ *
+ * ## Why each declared value is what it is
+ *
+ * - **`noDecision: 'blocks'`** — measured, and the single most consequential
+ *   line in the file. An approval left unanswered for **10 minutes 19 seconds**
+ *   was still pending, with no timeout event and no fall-through (#1758 §5.5.3).
+ *   The TUI dialog and the REST request are not two stages, they are the same
+ *   pending object seen twice, so "abstaining costs a dialog" — true on Claude,
+ *   codex and copilot — is false here: abstaining costs the session. Callers
+ *   read this through `describeAbstain()` and owe the operator a visible signal.
+ * - **`configScope: 'none'`** — nothing is written anywhere. No settings file,
+ *   no hooks entry, no change to `~/.config/opencode/opencode.jsonc`. The whole
+ *   integration is a `--port` argument and a subscription.
+ * - **`decisionTimeoutSeconds: null`** — the honest encoding of "waits forever".
+ *   Not zero, which would read as "answer instantly or lose the chance", and not
+ *   a large number, which would read as a deadline that exists.
+ * - **`supportedEvents`** — seven words, but two of them mean less than their
+ *   name suggests. `session_end` fires only for an explicit
+ *   `DELETE /session/:id`; the TUI's `/exit` emits nothing at all, so process
+ *   death stays tmux's question (§5.6.4). And `notification` is a bundle of
+ *   three unrelated events with no `idle_prompt` member — opencode never reports
+ *   "the agent is sitting at the composer".
+ *
+ * ## What is deliberately not done
+ *
+ * `GET /session` is never called to enumerate "this instance's sessions". It
+ * returns sessions belonging to *other processes* that share the same `HOME`
+ * and project directory, because a session belongs to `opencode.db` rather than
+ * to a server (§5.6.3). Instance identity is (worktree, tool, instance) and the
+ * port, exactly as it is for every other tool.
+ *
+ * @module lib/hooks/sources/opencode/source
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.opencodeAgentEventSource = void 0;
+exports.toOpencodePermissionReply = toOpencodePermissionReply;
+exports.prepareOpencodeLaunch = prepareOpencodeLaunch;
+const agent_event_types_1 = require("../../../../lib/hooks/agent-event-types");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const logger_1 = require("../../../../lib/logger");
+const define_source_1 = require("../define-source");
+const client_1 = require("./client");
+const mappers_1 = require("./mappers");
+const payloads_1 = require("./payloads");
+const ports_1 = require("./ports");
+const subscription_1 = require("./subscription");
+const tool_id_1 = require("./tool-id");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/source');
+/**
+ * The `AGENT_EVENT_TYPES` members opencode can produce.
+ *
+ * All seven, but see the module comment for what two of them actually mean.
+ * Spelled from the shared constant so a new word added to the vocabulary is a
+ * compile-time decision here rather than a silent omission.
+ */
+const OPENCODE_SUPPORTED_EVENTS = agent_event_types_1.AGENT_EVENT_TYPES;
+/**
+ * Map a verdict onto opencode's three-valued reply, or null when it has none.
+ *
+ * `abstain` is null and that is the point: there is no wire value for "no
+ * opinion", because there is no request to answer — the reply is a fresh POST
+ * that simply does not happen. What that costs is {@link
+ * AgentEventSource.noDecision}, not something this function can express.
+ */
+function toOpencodePermissionReply(verdict) {
+    switch (verdict.kind) {
+        case 'allowOnce':
+            return 'once';
+        case 'allowAlways':
+            return 'always';
+        case 'deny':
+            return 'reject';
+        case 'answer':
+        case 'abstain':
+            return null;
+    }
+}
+/**
+ * Send a verdict over its own connection (C2).
+ *
+ * The caller — `answerPendingDecision` — does not know this is an HTTP call
+ * rather than a response body, and must not.
+ */
+async function decideOpencode(target, decision, verdict) {
+    const instanceId = target.instanceId ?? target.cliToolId;
+    if (verdict.kind === 'abstain') {
+        // Nothing is sent, and on this tool that is an action rather than the
+        // absence of one: the agent waits with no timeout. Logged here as well as
+        // at the receiver, because this is the layer that knows the decision was
+        // addressed to a source whose silence blocks.
+        logger.warn('opencode-verdict-abstained', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            decisionId: decision.id,
+            consequence: 'the agent waits indefinitely; nothing else will unblock it',
+        });
+        return;
+    }
+    const port = (0, ports_1.getAssignedOpencodePort)(target);
+    if (port === null) {
+        logger.warn('opencode-verdict-undeliverable-no-port', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            decisionId: decision.id,
+        });
+        return;
+    }
+    if (decision.kind === 'question') {
+        if (verdict.kind !== 'answer') {
+            // An approval verdict cannot answer a question — and unlike Claude, where
+            // allowing the `AskUserQuestion` permission still leaves the picker up,
+            // there is nothing here that would make it harmless.
+            logger.info('opencode-question-not-answerable', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                decisionId: decision.id,
+                verdict: verdict.kind,
+            });
+            return;
+        }
+        const delivered = await (0, client_1.replyOpencodeQuestion)(port, decision.id, verdict.answers);
+        logger.info('opencode-question-replied', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            decisionId: decision.id,
+            delivered,
+        });
+        return;
+    }
+    const reply = toOpencodePermissionReply(verdict);
+    if (reply === null)
+        return;
+    const delivered = await (0, client_1.replyOpencodePermission)(port, decision.id, reply, verdict.kind === 'deny' ? verdict.message : undefined);
+    logger.info('opencode-permission-replied', {
+        worktreeId: target.worktreeId,
+        instanceId,
+        decisionId: decision.id,
+        reply,
+        delivered,
+    });
+}
+/** Re-read what is waiting on a human (C7). */
+async function listOpencodePending(target) {
+    const port = (0, ports_1.getAssignedOpencodePort)(target);
+    if (port === null)
+        return [];
+    const askedAt = Date.now();
+    const [permissions, questions] = await Promise.all([
+        (0, client_1.fetchOpencodePendingPermissions)(port),
+        (0, client_1.fetchOpencodePendingQuestions)(port),
+    ]);
+    const pending = [];
+    for (const entry of permissions) {
+        const decision = (0, payloads_1.toOpencodePendingPermission)(entry, askedAt);
+        if (decision)
+            pending.push(decision);
+    }
+    for (const entry of questions) {
+        const decision = (0, payloads_1.toOpencodePendingQuestion)(entry, askedAt);
+        if (decision)
+            pending.push(decision);
+    }
+    return pending;
+}
+/**
+ * Ask whether the conversation is working (C7).
+ *
+ * Note what `busy` includes: a session blocked on an approval reads `busy`
+ * (#1758 §5.3.1), because from the server's point of view the turn has not
+ * ended. This answers "is the turn over", never "is a human needed".
+ */
+async function probeOpencodeActivity(target) {
+    const port = (0, ports_1.getAssignedOpencodePort)(target);
+    if (port === null)
+        return null;
+    return (0, client_1.fetchOpencodeActivity)(port);
+}
+/**
+ * The command that starts opencode for one instance (S3 / S4 / S5).
+ *
+ * The whole of the launch change #1763 makes. #1758 §5.1.2 measured that the
+ * plain TUI serves the same API `opencode serve` does when given `--port`, so
+ * there is no second process to start, no pid to track and no orphan to reap —
+ * the server's lifetime is the pane's.
+ *
+ * Falls back to the bare executable — the pre-#1763 command, byte for byte —
+ * whenever there is no port to pass: `CM_AGENT_HOOKS_INJECT=0`, an exhausted
+ * range, or a caller that did not allocate one. A session that starts without
+ * structured events is the status quo; a session that fails to start is not.
+ *
+ * `--hostname` is passed explicitly even though `127.0.0.1` is the default,
+ * because the default is the security property: the server is unauthenticated,
+ * and `--mdns` (never passed) would move it to `0.0.0.0` (#1758 §5.8.3).
+ */
+function prepareOpencodeLaunch(target, executablePath) {
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)()) {
+        return { command: executablePath, settingsPath: null };
+    }
+    const port = (0, ports_1.getAssignedOpencodePort)(target);
+    if (port === null) {
+        return { command: executablePath, settingsPath: null };
+    }
+    return {
+        command: `${(0, hook_settings_generator_1.shellQuote)(executablePath)} --port ${port} --hostname ${client_1.OPENCODE_SERVER_HOST}`,
+        // Nothing is written to disk. `configScope: 'none'` says the same thing to
+        // a caller that asks the capabilities instead of the plan.
+        settingsPath: null,
+    };
+}
+/**
+ * opencode as an event source.
+ *
+ * Registered in `../registry`. Nothing outside this directory imports it by
+ * name; callers ask the registry for the tool they are holding.
+ */
+exports.opencodeAgentEventSource = (0, define_source_1.definePullEventSource)({
+    cliToolId: tool_id_1.OPENCODE_CLI_TOOL_ID,
+    // #1758 §5.5.3. Not a default, not an assumption — a stopwatch.
+    noDecision: { kind: 'blocks' },
+    capabilities: {
+        supportedEvents: OPENCODE_SUPPORTED_EVENTS,
+        configScope: 'none',
+        decisionTimeoutSeconds: null,
+    },
+    // C4. Predicates, not a name table: see ./mappers.
+    mappers: mappers_1.OPENCODE_MAPPERS,
+    // The envelope names the event in `type`; `hook_event_name` does not exist.
+    nativeEventNameFields: ['type'],
+    // Flat lookup cannot reach `properties.sessionID`; the rules fill it in.
+    conversationIdFields: [],
+    parsePermissionRequest: payloads_1.parseOpencodePermissionRequest,
+    parseQuestion: payloads_1.parseOpencodeQuestion,
+    // Self-reference resolves at call time, which is after this const is bound.
+    subscribe: (target, onEvent) => (0, subscription_1.openOpencodeSubscription)(target, onEvent, (raw) => exports.opencodeAgentEventSource.normalizeEvent(raw)),
+    decide: decideOpencode,
+    listPending: listOpencodePending,
+    probeActivity: probeOpencodeActivity,
+    liveness: (target) => (0, subscription_1.getOpencodeLiveness)(target),
+    prepareLaunch: prepareOpencodeLaunch,
+});

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

@@ -0,0 +1,422 @@
+"use strict";
+/**
+ * Holding the SSE connection to one opencode instance (Issue #1763, constraint
+ * C1).
+ *
+ * Every other tool CommandMate supports pushes: the agent runs a hook, the hook
+ * POSTs, and there is nothing to keep alive. opencode is subscribed to, so this
+ * module owns the states a push transport does not have — connected, lost,
+ * reconnecting — and the failure modes that come with them.
+ *
+ * ## What it has to get right
+ *
+ * - **Reconnect, and re-read what was missed.** Durable replay does not work on
+ *   1.18.3: `GET /api/session/:id/event?after=<seq>` returns zero bytes (#1758
+ *   §5.2.2). So a reconnect cannot ask "what did I miss"; it re-reads *state*
+ *   instead, from `GET /permission` and `GET /question`, which is what makes a
+ *   dropped approval recoverable rather than lost forever. A missed
+ *   `session.idle` is not recoverable and is not pretended to be — `wait` falls
+ *   back to the scraper, which is the pre-#1763 behaviour.
+ * - **Not report a turn twice.** See `./turn-gate`.
+ * - **Not throw on an unknown frame.** `server.heartbeat` arrives every ten
+ *   seconds and is not in the server's own OpenAPI `Event` union (#1758 D5), so
+ *   a strict reader would fail six times a minute on a healthy connection. It is
+ *   counted, not raised.
+ * - **Know when the connection is dead.** The heartbeat is the signal: 60 of
+ *   them over ten minutes, gaps of 10.00-10.03 s (§5.7.1). Silence past
+ *   {@link OPENCODE_HEARTBEAT_TIMEOUT_MS} means the stream is gone even if the
+ *   socket has not noticed.
+ *
+ * ## Held on `globalThis`
+ *
+ * Not decoration (Issue #1736). Under `next dev` every route handler is bundled
+ * separately, so a module-scoped map of live subscriptions would be one map per
+ * bundle: the launcher would open a stream the receiver cannot see, closing a
+ * session would leave a stream running against a dead pane, and starting the
+ * same instance twice would open two streams that both deliver every event.
+ * None of that produces an error.
+ *
+ * @module lib/hooks/sources/opencode/subscription
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_RECONNECT_BACKOFF_MS = exports.OPENCODE_HEARTBEAT_TIMEOUT_MS = void 0;
+exports.isOpencodeSubscribed = isOpencodeSubscribed;
+exports.getOpencodeLiveness = getOpencodeLiveness;
+exports.openOpencodeSubscription = openOpencodeSubscription;
+exports.closeOpencodeSubscription = closeOpencodeSubscription;
+exports.resetOpencodeSubscriptions = resetOpencodeSubscriptions;
+const logger_1 = require("../../../../lib/logger");
+const auto_yes_state_1 = require("../../../../lib/auto-yes-state");
+const event_mapper_1 = require("../event-mapper");
+const client_1 = require("./client");
+const mappers_1 = require("./mappers");
+const payloads_1 = require("./payloads");
+const ports_1 = require("./ports");
+const turn_gate_1 = require("./turn-gate");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/subscription');
+/**
+ * How long a connection may be silent before it counts as dead.
+ *
+ * The heartbeat is a metronome at 10 s (#1758 §5.7.1), so three missed beats is
+ * unambiguous while leaving room for a stalled event loop. Shorter would churn
+ * connections on a busy server; longer would leave `liveness` claiming `live`
+ * for a stream that stopped.
+ */
+exports.OPENCODE_HEARTBEAT_TIMEOUT_MS = 30_000;
+/** Reconnect backoff, in ms. The last value repeats. */
+exports.OPENCODE_RECONNECT_BACKOFF_MS = [
+    1_000, 2_000, 4_000, 8_000, 15_000, 30_000,
+];
+/** Cap on remembered decision ids, so a long session cannot grow the set. */
+const MAX_SEEN_DECISIONS = 256;
+const subscriptions = (globalThis.__opencodeSubscriptions ??= new Map());
+function keyOf(target) {
+    return (0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId);
+}
+/** Whether a stream is currently held for this instance. */
+function isOpencodeSubscribed(target) {
+    return subscriptions.has(keyOf(target));
+}
+/**
+ * How the connection to this instance is doing (C6).
+ *
+ * `unknown` for an instance with no subscription, which is the honest answer:
+ * a session started before this feature, or launched with structured events off,
+ * is indistinguishable from one whose stream has not been opened.
+ */
+function getOpencodeLiveness(target) {
+    return subscriptions.get(keyOf(target))?.liveness ?? { state: 'unknown' };
+}
+/** A subscription handle for an instance that has no server to subscribe to. */
+function inertSubscription() {
+    return { close: async () => { }, liveness: { state: 'unknown' } };
+}
+/**
+ * Open — or re-use — the event stream for one instance.
+ *
+ * Resolves as soon as the stream loop is running, not when the first frame
+ * arrives: the caller is a `startSession` that must not be held up by a server
+ * that is still booting, and the loop's own reconnect handles a port that is
+ * not listening yet.
+ *
+ * Never throws. A source that cannot reach its agent degrades to the scraper,
+ * and this call sits on the session-start path.
+ *
+ * @param target - The instance to watch
+ * @param onEvent - Receives normalised events, gated by {@link TurnGate}
+ * @param normalize - The source's own `normalizeEvent`, passed in rather than
+ *   imported so this module does not depend on the module that depends on it
+ * @param port - Overrides the recorded assignment. For tests
+ */
+async function openOpencodeSubscription(target, onEvent, normalize, port) {
+    const key = keyOf(target);
+    const existing = subscriptions.get(key);
+    if (existing)
+        return handleFor(existing);
+    const resolvedPort = port ?? (0, ports_1.getAssignedOpencodePort)(target);
+    if (resolvedPort === null) {
+        // No port was assigned: structured events are off, allocation failed, or
+        // this pane predates the feature. All three mean "the scraper is in charge",
+        // which is exactly what an inert subscription expresses.
+        logger.info('opencode-subscription-skipped-no-port', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+        });
+        return inertSubscription();
+    }
+    const state = {
+        key,
+        target,
+        port: resolvedPort,
+        onEvent,
+        normalize,
+        gate: (0, turn_gate_1.createTurnGate)(),
+        seenDecisions: new Set(),
+        streamController: new AbortController(),
+        liveness: { state: 'unknown' },
+        closed: false,
+        watchdog: null,
+    };
+    subscriptions.set(key, state);
+    logger.info('opencode-subscription-opened', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        port: resolvedPort,
+    });
+    // Deliberately not awaited: the loop runs for the life of the session.
+    void runStream(state);
+    return handleFor(state);
+}
+/** The handle the caller holds. `liveness` reads through to the live state. */
+function handleFor(state) {
+    return {
+        close: async () => {
+            await closeOpencodeSubscription(state.target);
+        },
+        get liveness() {
+            return state.liveness;
+        },
+    };
+}
+/** Stop watching an instance. Idempotent. */
+async function closeOpencodeSubscription(target) {
+    const key = keyOf(target);
+    const state = subscriptions.get(key);
+    if (!state)
+        return;
+    state.closed = true;
+    clearWatchdog(state);
+    state.streamController.abort();
+    subscriptions.delete(key);
+    logger.info('opencode-subscription-closed', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        port: state.port,
+    });
+}
+/** Close every subscription without waiting. Test seam. */
+function resetOpencodeSubscriptions() {
+    for (const state of subscriptions.values()) {
+        state.closed = true;
+        clearWatchdog(state);
+        state.streamController.abort();
+    }
+    subscriptions.clear();
+}
+function clearWatchdog(state) {
+    if (state.watchdog !== null) {
+        clearTimeout(state.watchdog);
+        state.watchdog = null;
+    }
+}
+/**
+ * Restart the silence timer.
+ *
+ * `unref` so a held connection never keeps a CLI process alive; the server has
+ * its own reasons to stay up and does not need this timer to supply one.
+ */
+function armWatchdog(state) {
+    clearWatchdog(state);
+    const timer = setTimeout(() => {
+        if (state.closed)
+            return;
+        logger.warn('opencode-subscription-heartbeat-lost', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            port: state.port,
+            afterMs: exports.OPENCODE_HEARTBEAT_TIMEOUT_MS,
+        });
+        // Force the read to end; the loop treats it as a dropped connection.
+        state.streamController.abort();
+    }, exports.OPENCODE_HEARTBEAT_TIMEOUT_MS);
+    timer.unref?.();
+    state.watchdog = timer;
+}
+/** Sleep, unless the subscription is torn down first. */
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+function backoffFor(attempt) {
+    const index = Math.min(attempt, exports.OPENCODE_RECONNECT_BACKOFF_MS.length - 1);
+    return exports.OPENCODE_RECONNECT_BACKOFF_MS[index];
+}
+/**
+ * The connection loop.
+ *
+ * Runs until `close()`. Every ending — a clean EOF, an aborted read, a refused
+ * connection — is the same thing to this function: reconnect after a backoff,
+ * having first re-read the state that could not be replayed.
+ */
+async function runStream(state) {
+    let attempt = 0;
+    while (!state.closed) {
+        state.streamController = new AbortController();
+        // A reconnect is a new arming window: whatever was mid-turn when the
+        // connection dropped, its `session.status(busy)` was on the old stream, and
+        // an idle that arrives without one must not resolve a `wait`.
+        state.gate.reset();
+        let reason = 'stream-ended';
+        try {
+            await resyncPending(state);
+            armWatchdog(state);
+            for await (const frame of (0, client_1.readOpencodeEventStream)(state.port, state.streamController.signal)) {
+                attempt = 0;
+                armWatchdog(state);
+                handleFrame(state, frame);
+            }
+        }
+        catch (error) {
+            reason = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            clearWatchdog(state);
+        }
+        if (state.closed)
+            break;
+        state.liveness = { state: 'lost', since: Date.now(), reason };
+        logger.warn('opencode-subscription-disconnected', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            port: state.port,
+            reason,
+            attempt,
+        });
+        await delay(backoffFor(attempt), state.streamController.signal);
+        attempt += 1;
+    }
+}
+/**
+ * Re-read what is waiting on a human and announce anything not seen yet (C7).
+ *
+ * The only recovery opencode offers. An approval raised while CommandMate was
+ * disconnected is still pending on the server, so re-reading it restores both
+ * the "a human is blocked" state and Auto-Yes's chance to adjudicate it — which
+ * matters more here than anywhere else, because an unanswered opencode approval
+ * waits forever (#1758 §5.5.3).
+ */
+async function resyncPending(state) {
+    const now = Date.now();
+    const [permissions, questions] = await Promise.all([
+        (0, client_1.fetchOpencodePendingPermissions)(state.port),
+        (0, client_1.fetchOpencodePendingQuestions)(state.port),
+    ]);
+    const replay = (entries, type) => {
+        for (const entry of entries) {
+            const id = (0, event_mapper_1.readStringField)(entry, 'id');
+            if (!id || state.seenDecisions.has(id))
+                continue;
+            // Rebuilt into the envelope the live path uses, so one mapper and one
+            // parser cover both arrival routes.
+            deliver(state, { id: `resync_${id}`, type, properties: entry }, now);
+        }
+    };
+    replay(permissions, 'permission.asked');
+    replay(questions, 'question.asked');
+}
+/** Process one frame off the stream. */
+function handleFrame(state, frame) {
+    const type = (0, event_mapper_1.readStringField)(frame, 'type');
+    if (type === 'server.heartbeat' || type === 'server.connected') {
+        state.liveness = { state: 'live', lastHeartbeatAt: Date.now() };
+        // Still normalised below so the unknown-event tally counts it: the tally is
+        // the diagnostic for "this tool sends words we have none for", and a
+        // keepalive silently excluded from it would make the count look healthier
+        // than the vocabulary is.
+    }
+    deliver(state, frame, Date.now());
+}
+/**
+ * Normalise one frame and hand it on, if the gate allows.
+ *
+ * @param frame - `{ id, type, properties }`, live or rebuilt from a re-sync
+ * @param receivedAt - Epoch ms
+ */
+function deliver(state, frame, receivedAt) {
+    const type = (0, event_mapper_1.readStringField)(frame, 'type');
+    // Recorded before the mapping, and for every status: `permission.asked` names
+    // no tool, only a `callID`, and the frame that does name it is the `pending`
+    // one — which maps to nothing at all. Reading it only from mapped events
+    // would leave every approval anonymous (see ./payloads).
+    if (type === 'message.part.updated') {
+        const callId = (0, mappers_1.partCallId)(frame);
+        const toolName = (0, mappers_1.partToolName)(frame);
+        if (callId && toolName)
+            (0, payloads_1.rememberOpencodeToolCall)(callId, toolName);
+    }
+    const observation = state.gate.observe(type, frame);
+    if (observation.kind === 'failed') {
+        logger.warn('opencode-session-error', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            sessionId: observation.sessionId,
+            errorName: observation.errorName,
+        });
+    }
+    let normalized = null;
+    try {
+        normalized = state.normalize({ payload: frame, receivedAt });
+    }
+    catch (error) {
+        // The interface forbids this, and a source that broke the rule must still
+        // not take the connection down with it.
+        logger.error('opencode-normalize-threw', {
+            type,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    if (!normalized)
+        return;
+    const suppressedBecause = gateVerdict(normalized.event, observation);
+    if (suppressedBecause !== null) {
+        logger.info('opencode-repeat-suppressed', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            sessionId: normalized.conversationId,
+            event: normalized.event,
+            reason: suppressedBecause,
+        });
+        return;
+    }
+    rememberDecisionId(state, frame);
+    try {
+        state.onEvent(normalized);
+    }
+    catch (error) {
+        logger.error('opencode-event-handler-failed', {
+            type,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Whether the gate refuses to let this event through, and why.
+ *
+ * Both words opencode repeats are gated, and both would be wrong in the same
+ * direction — the status layer reads only the newest event, so a repeat of
+ * either overwrites the truth:
+ *
+ *  - a second `stop` resolves a `wait` for work that is not over;
+ *  - a trailing `user_prompt_submit` — which opencode emits *after*
+ *    `session.idle` — leaves a finished turn reading `running` for the next
+ *    thirty minutes.
+ *
+ * Everything else passes: repeats of `pre_tool_use` and `post_tool_use` are
+ * idempotent in the state machine they feed, and the receiver's own dedup
+ * window collapses them anyway.
+ *
+ * @returns The suppression reason, or null when the event may be delivered
+ */
+function gateVerdict(event, observation) {
+    if (event === 'stop' && observation.kind !== 'completed') {
+        return observation.kind === 'suppressed' ? observation.reason : 'not-a-turn-end';
+    }
+    if (event === 'user_prompt_submit' && observation.kind !== 'announced') {
+        return observation.kind === 'suppressed' ? observation.reason : 'not-a-new-prompt';
+    }
+    return null;
+}
+/** Note an approval / question id so a later re-sync does not repeat it. */
+function rememberDecisionId(state, frame) {
+    const type = (0, event_mapper_1.readStringField)(frame, 'type');
+    if (type !== 'permission.asked' && type !== 'question.asked')
+        return;
+    const properties = (0, event_mapper_1.isPlainObject)(frame.properties) ? frame.properties : {};
+    const id = (0, event_mapper_1.readStringField)(properties, 'id');
+    if (!id)
+        return;
+    state.seenDecisions.add(id);
+    while (state.seenDecisions.size > MAX_SEEN_DECISIONS) {
+        const oldest = state.seenDecisions.values().next();
+        if (oldest.done)
+            break;
+        state.seenDecisions.delete(oldest.value);
+    }
+}

package/dist/server/src/lib/hooks/sources/opencode/tool-id.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * opencode's {@link CLIToolType}, on its own so the id can be imported without
+ * pulling in the source (Issue #1763).
+ *
+ * Same shape as `../claude/tool-id`: the registry, the launcher and the tests
+ * all need the literal, and only the registry needs the implementation.
+ *
+ * @module lib/hooks/sources/opencode/tool-id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_CLI_TOOL_ID = void 0;
+/** The tool id every opencode module keys off. */
+exports.OPENCODE_CLI_TOOL_ID = 'opencode';