commandmate 0.42.2 → 0.43.0

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

@@ -0,0 +1,455 @@
+"use strict";
+/**
+ * The long-lived SSE subscription to one OpenCode V2 instance's own server
+ * (Issue #2934, decision D5).
+ *
+ * One instance = one `opencode2 serve` (started by `scripts/opencode-v2/launch.sh`
+ * in the instance's pane) = one subscription. Because the server is the
+ * instance's alone, routing is by construction: every frame this stream yields
+ * belongs to the instance it was opened for, whether or not the frame carries
+ * `location.directory` (several do not).
+ *
+ * The loop, per connection attempt:
+ *  1. read the password file — gone means the session was killed, so the
+ *     subscription ends rather than retrying forever;
+ *  2. probe `GET /openapi.json` with it — `rejected` means the port now belongs
+ *     to something that does not hold this password, which ends the
+ *     subscription too (reading it would be reading someone else's events);
+ *  3. open `GET /api/event` and deliver the frames Phase 1 maps, while every
+ *     frame and every `: heartbeat` refreshes the liveness and re-arms a
+ *     watchdog that forces a reconnect on a silent socket.
+ * Any other failure waits out a backoff and tries again.
+ *
+ * Unlike v1's subscription this one keeps no turn gate. It does record the
+ * reply (Issue #2940): a frame that ends a turn also has `./history` read the
+ * finished turn off `GET /api/session/{id}/message`. And (Issue #2951) each
+ * connection first replays what the server is still waiting on
+ * ({@link resyncOpencodeV2Pending}), as v1's `resyncPending` does, so an
+ * approval raised while the stream was down is recorded and adjudicated.
+ * And (Issue #2981) `session.usage.updated` and the end of a turn have
+ * `./usage` refresh the session's spend and context, which the subscription
+ * drops again when it closes or ends — the place v1 drops them.
+ *
+ * @module lib/hooks/sources/opencode-v2/subscription
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_V2_MAX_RESYNCED_DECISIONS = exports.OPENCODE_V2_MAX_REJECTED_PROBES = exports.OPENCODE_V2_RECONNECT_BACKOFF_MS = exports.OPENCODE_V2_HEARTBEAT_TIMEOUT_MS = void 0;
+exports.isOpencodeV2Subscribed = isOpencodeV2Subscribed;
+exports.getOpencodeV2Liveness = getOpencodeV2Liveness;
+exports.isOpencodeV2StructuredHistoryLive = isOpencodeV2StructuredHistoryLive;
+exports.getOpencodeV2SubscribedPort = getOpencodeV2SubscribedPort;
+exports.openOpencodeV2Subscription = openOpencodeV2Subscription;
+exports.closeOpencodeV2Subscription = closeOpencodeV2Subscription;
+exports.resetOpencodeV2Subscriptions = resetOpencodeV2Subscriptions;
+exports.resyncOpencodeV2Pending = resyncOpencodeV2Pending;
+exports.deliverOpencodeV2Frame = deliverOpencodeV2Frame;
+exports.refreshOpencodeV2UsageOnFrame = refreshOpencodeV2UsageOnFrame;
+exports.recordOpencodeV2TurnEnd = recordOpencodeV2TurnEnd;
+const agent_session_telemetry_1 = require("../../../../lib/hooks/agent-session-telemetry");
+const logger_1 = require("../../../../lib/logger");
+const event_mapper_1 = require("../event-mapper");
+const client_1 = require("./client");
+const history_1 = require("./history");
+const mappers_1 = require("./mappers");
+const secrets_1 = require("./secrets");
+const usage_1 = require("./usage");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode-v2/subscription');
+/**
+ * A connection that has said nothing — not even a heartbeat — for this long is
+ * re-opened. 2.0.18 sends `: heartbeat` every 15 s (measured 2026-09-28), so
+ * this is four missed beats.
+ */
+exports.OPENCODE_V2_HEARTBEAT_TIMEOUT_MS = 60_000;
+/** Waits between reconnect attempts; the last value repeats. */
+exports.OPENCODE_V2_RECONNECT_BACKOFF_MS = [
+    500, 1_000, 2_000, 4_000, 8_000, 15_000, 30_000,
+];
+/** Consecutive `rejected` probes after which the port is taken to be someone else's. */
+exports.OPENCODE_V2_MAX_REJECTED_PROBES = 3;
+/**
+ * Cap on decisions replayed per list on one connection (Issue #2951). The same
+ * bound, for the same reason, as v1's `MAX_RESYNCED_DECISIONS`: the list comes
+ * off a server CommandMate does not police.
+ */
+exports.OPENCODE_V2_MAX_RESYNCED_DECISIONS = 50;
+const subscriptions = (globalThis.__opencodeV2Subscriptions ??= new Map());
+/** The last liveness of a subscription that ended on its own, for `liveness()`. */
+const endedLiveness = (globalThis.__opencodeV2EndedLiveness ??= new Map());
+/** Whether a subscription is open for the instance. */
+function isOpencodeV2Subscribed(target) {
+    return subscriptions.has((0, secrets_1.opencodeV2KeyOf)(target));
+}
+/** The instance's subscription liveness. */
+function getOpencodeV2Liveness(target) {
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    return subscriptions.get(key)?.liveness ?? endedLiveness.get(key) ?? { state: 'unknown' };
+}
+/**
+ * Whether this instance's replies are being written from its server
+ * (Issue #2940).
+ *
+ * The screen scraper's stand-down test, read through
+ * `lib/polling/structured-history-gate`. `live` only, for the reason v1's
+ * `isOpencodeStructuredHistoryLive` gives: a `lost` stream delivers no end of
+ * turn, so it writes nothing, and standing the scraper down for it would leave
+ * the reply recorded by nobody.
+ */
+function isOpencodeV2StructuredHistoryLive(target) {
+    return getOpencodeV2Liveness(target).state === 'live';
+}
+/** The port an open subscription reads, or null. */
+function getOpencodeV2SubscribedPort(target) {
+    return subscriptions.get((0, secrets_1.opencodeV2KeyOf)(target))?.port ?? null;
+}
+function handleFor(state) {
+    return {
+        close: async () => {
+            await closeOpencodeV2Subscription(state.target);
+        },
+        get liveness() {
+            return state.liveness;
+        },
+    };
+}
+/**
+ * Open (or return the already-open) subscription for an instance.
+ *
+ * @param target - The instance
+ * @param port - Its server's port
+ * @param onEvent - Receives every mapped event
+ * @param normalize - The source's normalizer
+ */
+function openOpencodeV2Subscription(target, port, onEvent, normalize) {
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    const existing = subscriptions.get(key);
+    if (existing)
+        return handleFor(existing);
+    endedLiveness.delete(key);
+    const state = {
+        key,
+        target,
+        port,
+        onEvent,
+        normalize,
+        streamController: new AbortController(),
+        lifetimeController: new AbortController(),
+        liveness: { state: 'unknown' },
+        closed: false,
+        watchdog: null,
+    };
+    subscriptions.set(key, state);
+    logger.info('opencode-v2-subscription-opened', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        port,
+    });
+    void runStream(state);
+    return handleFor(state);
+}
+/** Close the instance's subscription. Safe to call when none is open. */
+async function closeOpencodeV2Subscription(target) {
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    endedLiveness.delete(key);
+    const state = subscriptions.get(key);
+    if (!state)
+        return;
+    stop(state);
+    subscriptions.delete(key);
+    // Issue #2981, where v1's close does it (#2040): the records describe the
+    // conversation this process was having, and closing is the pane going away.
+    (0, agent_session_telemetry_1.forgetAgentSessionTelemetry)(target);
+    logger.info('opencode-v2-subscription-closed', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        port: state.port,
+    });
+}
+/** Close every subscription. For tests. */
+function resetOpencodeV2Subscriptions() {
+    for (const state of subscriptions.values())
+        stop(state);
+    subscriptions.clear();
+    endedLiveness.clear();
+}
+function stop(state) {
+    state.closed = true;
+    clearWatchdog(state);
+    state.streamController.abort();
+    state.lifetimeController.abort();
+}
+/** End a subscription from inside its own loop, remembering why. */
+function endSubscription(state, reason) {
+    stop(state);
+    state.liveness = { state: 'lost', since: Date.now(), reason };
+    if (subscriptions.get(state.key) === state)
+        subscriptions.delete(state.key);
+    endedLiveness.set(state.key, state.liveness);
+    // Issue #2981: ending on its own means the password file is gone or the port
+    // is someone else's — the server this pane had is not coming back either.
+    (0, agent_session_telemetry_1.forgetAgentSessionTelemetry)(state.target);
+    logger.warn('opencode-v2-subscription-ended', {
+        worktreeId: state.target.worktreeId,
+        instanceId: state.target.instanceId ?? state.target.cliToolId,
+        port: state.port,
+        reason,
+    });
+}
+function clearWatchdog(state) {
+    if (state.watchdog !== null) {
+        clearTimeout(state.watchdog);
+        state.watchdog = null;
+    }
+}
+function markAlive(state) {
+    state.liveness = { state: 'live', lastHeartbeatAt: Date.now() };
+    clearWatchdog(state);
+    const timer = setTimeout(() => {
+        if (state.closed)
+            return;
+        logger.warn('opencode-v2-subscription-heartbeat-lost', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            port: state.port,
+            afterMs: exports.OPENCODE_V2_HEARTBEAT_TIMEOUT_MS,
+        });
+        state.streamController.abort();
+    }, exports.OPENCODE_V2_HEARTBEAT_TIMEOUT_MS);
+    timer.unref?.();
+    state.watchdog = timer;
+}
+function waitUnlessAborted(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        timer.unref?.();
+    });
+}
+function backoffFor(attempt) {
+    return exports.OPENCODE_V2_RECONNECT_BACKOFF_MS[Math.min(attempt, exports.OPENCODE_V2_RECONNECT_BACKOFF_MS.length - 1)];
+}
+async function runStream(state) {
+    let attempt = 0;
+    let rejected = 0;
+    while (!state.closed) {
+        state.streamController = new AbortController();
+        let reason = 'stream-ended';
+        try {
+            const password = (0, secrets_1.readOpencodeV2Password)(state.target);
+            if (password === null) {
+                endSubscription(state, 'password-file-missing');
+                return;
+            }
+            const probe = await (0, client_1.probeOpencodeV2Server)(state.port, password);
+            if (state.closed)
+                return;
+            if (probe.kind === 'rejected') {
+                rejected += 1;
+                reason = `server-rejected-${probe.status}`;
+                if (rejected >= exports.OPENCODE_V2_MAX_REJECTED_PROBES) {
+                    endSubscription(state, 'port-identity-changed');
+                    return;
+                }
+            }
+            else if (probe.kind === 'unreachable') {
+                reason = 'server-unreachable';
+            }
+            else {
+                rejected = 0;
+                const items = await (0, client_1.openOpencodeV2EventStream)(state.port, password, state.streamController.signal);
+                markAlive(state);
+                attempt = 0;
+                // Issue #2951: before the first live frame, so an approval raised while
+                // the stream was down reaches the same ingest (and Auto-Yes) as a live
+                // one. A frame for the same id on the new stream is then a duplicate by
+                // identity, not a second approval.
+                await resyncOpencodeV2Pending(state.target, state.port, password, (frame) => deliver(state, frame));
+                for await (const item of items) {
+                    if (state.closed)
+                        break;
+                    markAlive(state);
+                    if (item.kind === 'frame')
+                        deliver(state, item.frame);
+                }
+            }
+        }
+        catch (error) {
+            reason = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            clearWatchdog(state);
+        }
+        if (state.closed)
+            return;
+        state.liveness = { state: 'lost', since: Date.now(), reason };
+        logger.info('opencode-v2-subscription-disconnected', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            port: state.port,
+            reason,
+            attempt,
+        });
+        await waitUnlessAborted(backoffFor(attempt), state.lifetimeController.signal);
+        attempt += 1;
+    }
+}
+/**
+ * Replay what the server is still waiting on as the frames that announced it
+ * (Issue #2951).
+ *
+ * `GET /api/permission/request` entries become `permission.asked` frames and
+ * `GET /api/form` entries `form.created` frames (the form nested as
+ * `data.form`, as 2.0.18 sends it), so one mapper and one parser cover both
+ * arrival routes. Never throws; an unreachable server replays nothing.
+ *
+ * Exported for the tests.
+ *
+ * @returns How many frames were replayed
+ */
+async function resyncOpencodeV2Pending(target, port, password, replay) {
+    let replayed = 0;
+    try {
+        const [permissions, forms] = await Promise.all([
+            (0, client_1.fetchOpencodeV2PendingPermissions)(port, password),
+            (0, client_1.fetchOpencodeV2PendingForms)(port, password),
+        ]);
+        const each = (entries, type, wrap) => {
+            const list = (entries ?? []).filter(event_mapper_1.isPlainObject);
+            const kept = list.slice(0, exports.OPENCODE_V2_MAX_RESYNCED_DECISIONS);
+            if (list.length > kept.length) {
+                logger.warn('opencode-v2-resync-truncated', {
+                    worktreeId: target.worktreeId,
+                    instanceId: target.instanceId ?? target.cliToolId,
+                    type,
+                    examined: kept.length,
+                    skipped: list.length - kept.length,
+                    limit: exports.OPENCODE_V2_MAX_RESYNCED_DECISIONS,
+                });
+            }
+            for (const entry of kept) {
+                const id = typeof entry.id === 'string' && entry.id !== '' ? entry.id : null;
+                if (id === null)
+                    continue;
+                replay({ id: `resync_${id}`, type, data: wrap(entry) });
+                replayed += 1;
+            }
+        };
+        each(permissions, 'permission.asked', (entry) => entry);
+        each(forms, 'form.created', (entry) => ({ form: entry }));
+    }
+    catch (error) {
+        logger.warn('opencode-v2-resync-failed', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (replayed > 0) {
+        logger.info('opencode-v2-resync', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            replayed,
+        });
+    }
+    return replayed;
+}
+/**
+ * Normalize one frame and hand it on, if Phase 1 reads its type.
+ *
+ * Exported for the mapping tests, which drive frames through exactly the path
+ * the stream does.
+ */
+function deliverOpencodeV2Frame(frame, normalize, onEvent, receivedAt = Date.now()) {
+    if (!(0, mappers_1.isHandledOpencodeV2EventType)((0, mappers_1.frameType)(frame)))
+        return false;
+    const event = normalize({ payload: frame, receivedAt });
+    if (!event)
+        return false;
+    onEvent(event);
+    return true;
+}
+function deliver(state, frame) {
+    try {
+        deliverOpencodeV2Frame(frame, state.normalize, state.onEvent);
+    }
+    catch (error) {
+        logger.warn('opencode-v2-frame-delivery-failed', {
+            worktreeId: state.target.worktreeId,
+            instanceId: state.target.instanceId ?? state.target.cliToolId,
+            type: (0, mappers_1.frameType)(frame),
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    void recordOpencodeV2TurnEnd(state.target, state.port, frame);
+    void refreshOpencodeV2UsageOnFrame(state.target, state.port, frame, () => isCurrentSubscription(state));
+}
+function isCurrentSubscription(state) {
+    return !state.closed && subscriptions.get(state.key) === state;
+}
+/**
+ * Have `./usage` re-read the session's spend and context when this frame says
+ * they moved (Issue #2981): `session.usage.updated`, or the end of a turn.
+ *
+ * Not awaited, for the reason {@link recordOpencodeV2TurnEnd} gives. Exported
+ * for the tests.
+ *
+ * @returns The refresh, or null when the frame triggers none
+ */
+function refreshOpencodeV2UsageOnFrame(target, port, frame, isCurrent = () => true) {
+    try {
+        if (!(0, usage_1.isOpencodeV2UsageTriggerType)((0, mappers_1.frameType)(frame)))
+            return null;
+        const sessionId = (0, mappers_1.frameSessionId)(frame);
+        if (sessionId === null)
+            return null;
+        return (0, usage_1.scheduleOpencodeV2SessionUsageRefresh)(target, port, sessionId, isCurrent);
+    }
+    catch (error) {
+        logger.warn('opencode-v2-usage-trigger-failed', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Have `./history` record the reply of a turn this frame ends (Issue #2940).
+ *
+ * Not awaited: the read loop delivers one frame at a time and a fetch plus a
+ * database write must not hold the stream (or the `stop` just delivered).
+ * `syncOpencodeV2History` catches its own failures; the guard here is for a
+ * frame that cannot even be read.
+ *
+ * Exported for the tests, which drive frames through the path the stream does.
+ *
+ * @returns The sync, or null when the frame ends no turn
+ */
+function recordOpencodeV2TurnEnd(target, port, frame) {
+    try {
+        if (!(0, history_1.isOpencodeV2TurnEndEventType)((0, mappers_1.frameType)(frame)))
+            return null;
+        const sessionId = (0, mappers_1.frameSessionId)(frame);
+        if (sessionId === null)
+            return null;
+        return (0, history_1.syncOpencodeV2History)(target, port, sessionId);
+    }
+    catch (error) {
+        logger.warn('opencode-v2-history-trigger-failed', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}

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

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * OpenCode V2's {@link CLIToolType}, on its own so the id can be imported
+ * without pulling in the source (Issue #2934).
+ *
+ * The same one-line module `../opencode/tool-id` is. OpenCode V2 (`opencode2`)
+ * is a separate tool id rather than a version branch of `opencode` (Epic #2370,
+ * decision 1): its server, its event vocabulary and its screen all differ, and
+ * v1 keeps every behaviour it had.
+ *
+ * @module lib/hooks/sources/opencode-v2/tool-id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_V2_COMMAND = exports.OPENCODE_V2_CLI_TOOL_ID = void 0;
+/** The tool id every OpenCode V2 module keys off. */
+exports.OPENCODE_V2_CLI_TOOL_ID = 'opencode-v2';
+/** The executable OpenCode V2 installs (npm `@opencode/cli`). */
+exports.OPENCODE_V2_COMMAND = 'opencode2';

package/dist/server/src/lib/hooks/sources/opencode-v2/usage.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * What an OpenCode V2 session has spent, and how full its context is
+ * (Issue #2981, Epic #2370).
+ *
+ * v1 publishes both through `lib/hooks/agent-session-telemetry`: the session
+ * record off `session.updated`, and the context occupancy from two further
+ * requests to v1's server. This module fills the same two records for
+ * `opencode-v2`, so every reader (`current-output`, `capture --json`, the pane
+ * header, the cost sampler) shows v2 without knowing it is v2.
+ *
+ * ## What was measured (2.0.18, `tests/fixtures/opencode-v2-usage-2981`)
+ *
+ * | quantity | where | after turn 1 | after turn 2 |
+ * |---|---|---|---|
+ * | session, cumulative | `session.usage.updated` `data.tokens` = `GET /api/session/{id}` `tokens` | 2857 / 12 / 64 / 3840 | 5925 / 34 / 128 / 13312 |
+ * | context, last turn | newest assistant message's `tokens` (= its `session.step.ended`) | 6,208 | 6,341 |
+ * | TUI | footer / sidebar | `6.2K (1%)` / `6,208 tokens` | `6.3K (1%)` / `6,341 tokens` |
+ *
+ * (input / output / reasoning / cache.read.) The session total also counts the
+ * title-generation call (the first `session.usage.updated` of a session, 565
+ * tokens, belongs to no assistant message), so the two are different quantities
+ * and v1's rule holds unchanged: the record is the cumulative figure, the
+ * context is the newest assistant message's sum, and the percentage is
+ * `round(tokens / limit.context * 100)` with `limit.context` from
+ * `GET /api/model` (1,000,000 for the measured model).
+ *
+ * ## Pull on the frame, not the frame
+ *
+ * `session.usage.updated` carries `sessionID`, `cost` and `tokens` and nothing
+ * else — no title, agent, model or `parentID`. So the frame is a trigger, as
+ * the end of a turn is: both make this module read `GET /api/session/{id}`
+ * (the record, and `parentID` so a sub-agent's session is refused exactly as
+ * v1 refuses it), the newest messages (the context) and `GET /api/model` (the
+ * limit), with the instance's own port and password. Refreshes are coalesced
+ * per instance: one in flight, at most one queued behind it.
+ *
+ * ## Lifetime
+ *
+ * The subscription drops both records when it closes or ends
+ * (`forgetAgentSessionTelemetry`, the call v1 makes in the same place), and a
+ * refresh that finishes after that writes nothing ({@link refreshOpencodeV2SessionUsage}'s
+ * `isCurrent`).
+ *
+ * @module lib/hooks/sources/opencode-v2/usage
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_V2_USAGE_EVENT_TYPE = void 0;
+exports.isOpencodeV2UsageTriggerType = isOpencodeV2UsageTriggerType;
+exports.readOpencodeV2ContextTokens = readOpencodeV2ContextTokens;
+exports.readOpencodeV2ModelContextLimit = readOpencodeV2ModelContextLimit;
+exports.refreshOpencodeV2SessionUsage = refreshOpencodeV2SessionUsage;
+exports.resetOpencodeV2UsageRefreshes = resetOpencodeV2UsageRefreshes;
+exports.scheduleOpencodeV2SessionUsageRefresh = scheduleOpencodeV2SessionUsageRefresh;
+const agent_session_telemetry_1 = require("../../../../lib/hooks/agent-session-telemetry");
+const logger_1 = require("../../../../lib/logger");
+const event_mapper_1 = require("../event-mapper");
+const client_1 = require("./client");
+const history_1 = require("./history");
+const secrets_1 = require("./secrets");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode-v2/usage');
+/** The frame that says a session's running total moved. */
+exports.OPENCODE_V2_USAGE_EVENT_TYPE = 'session.usage.updated';
+/** Whether a frame `type` should refresh the usage records. */
+function isOpencodeV2UsageTriggerType(type) {
+    return type === exports.OPENCODE_V2_USAGE_EVENT_TYPE || (0, history_1.isOpencodeV2TurnEndEventType)(type);
+}
+function readCount(source, key) {
+    const value = source[key];
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function createdAtOf(message) {
+    const time = (0, event_mapper_1.isPlainObject)(message.time) ? message.time : null;
+    const created = time?.created;
+    return typeof created === 'number' && Number.isFinite(created) ? created : 0;
+}
+/**
+ * The newest assistant message's token footprint, or null.
+ *
+ * v1's `fetchOpencodeContextTokens` rule on v2's message shape: the newest
+ * `assistant` message (by `time.created`, the id breaking ties) that produced
+ * output, `input + output + reasoning + cache.read + cache.write`. A message
+ * with no output yet is a step still streaming, and would read as a context
+ * that shrank. Order-agnostic, pure.
+ */
+function readOpencodeV2ContextTokens(entries) {
+    let newest = null;
+    for (const entry of entries) {
+        if (!(0, event_mapper_1.isPlainObject)(entry) || (0, event_mapper_1.readStringField)(entry, 'type') !== 'assistant')
+            continue;
+        const tokens = (0, event_mapper_1.isPlainObject)(entry.tokens) ? entry.tokens : null;
+        if (!tokens)
+            continue;
+        const output = readCount(tokens, 'output');
+        if (output <= 0)
+            continue;
+        const cache = (0, event_mapper_1.isPlainObject)(tokens.cache) ? tokens.cache : {};
+        const total = readCount(tokens, 'input') +
+            output +
+            readCount(tokens, 'reasoning') +
+            readCount(cache, 'read') +
+            readCount(cache, 'write');
+        const at = createdAtOf(entry);
+        const id = (0, event_mapper_1.readStringField)(entry, 'id') ?? '';
+        if (newest === null || at > newest.at || (at === newest.at && id > newest.id)) {
+            newest = { at, id, total };
+        }
+    }
+    return newest?.total ?? null;
+}
+/**
+ * `limit.context` of one model out of `GET /api/model`'s `data`, or null.
+ *
+ * `context` only, and a non-positive value is "no percentage" — v1's
+ * `readOpencodeModelContextLimit` rule. v2 lists models flat, each naming its
+ * `providerID` and `id`.
+ */
+function readOpencodeV2ModelContextLimit(models, providerId, modelId) {
+    for (const model of models) {
+        if (!(0, event_mapper_1.isPlainObject)(model))
+            continue;
+        if (model.providerID !== providerId || model.id !== modelId)
+            continue;
+        const limit = (0, event_mapper_1.isPlainObject)(model.limit) ? model.limit : null;
+        const context = limit?.context;
+        if (typeof context !== 'number' || !Number.isFinite(context) || context <= 0)
+            return null;
+        return context;
+    }
+    return null;
+}
+/**
+ * Read the session, its context and its model's limit, and store both records.
+ *
+ * Never throws. Answers the record it stored, or null when it stored nothing:
+ * no password (the session was killed), a session the server did not answer, a
+ * sub-agent's session, or `isCurrent()` false by the time the answers came in.
+ *
+ * @param isCurrent - Whether the subscription that asked is still the
+ *   instance's; checked after the requests, right before writing
+ */
+async function refreshOpencodeV2SessionUsage(target, port, sessionId, isCurrent = () => true) {
+    try {
+        const password = (0, secrets_1.readOpencodeV2Password)(target);
+        if (password === null)
+            return null;
+        const info = await (0, client_1.fetchOpencodeV2Session)(port, password, sessionId);
+        const record = (0, agent_session_telemetry_1.readOpencodeSessionInfo)(info, Date.now());
+        if (!record || !record.id)
+            return null;
+        const provider = record.provider;
+        const model = record.model;
+        const [messages, models] = await Promise.all([
+            (0, client_1.fetchOpencodeV2RecentMessages)(port, password, record.id),
+            provider && model ? (0, client_1.fetchOpencodeV2Models)(port, password) : Promise.resolve(null),
+        ]);
+        const tokens = messages ? readOpencodeV2ContextTokens(messages) : null;
+        const limit = models && provider && model ? readOpencodeV2ModelContextLimit(models, provider, model) : null;
+        if (!isCurrent())
+            return null;
+        (0, agent_session_telemetry_1.recordAgentSessionTelemetry)(target, record);
+        (0, agent_session_telemetry_1.recordAgentSessionContextUsage)(target, {
+            tokens,
+            limit,
+            percent: (0, agent_session_telemetry_1.agentSessionContextPercent)(tokens, limit),
+            sessionAt: record.at,
+            at: Date.now(),
+        });
+        return record;
+    }
+    catch (error) {
+        logger.warn('opencode-v2-usage-refresh-failed', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            port,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/** One refresh in flight per instance, on `globalThis` for #1736's reason. */
+const slots = (globalThis.__opencodeV2UsageRefreshes ??= new Map());
+/** Forget in-flight markers. Test seam. */
+function resetOpencodeV2UsageRefreshes() {
+    slots.clear();
+}
+/**
+ * Refresh the instance's usage, coalescing a burst of frames into at most one
+ * request set in flight and one queued behind it (the newest wins the queue).
+ *
+ * @returns A promise that settles when the instance has no refresh left to run
+ */
+function scheduleOpencodeV2SessionUsageRefresh(target, port, sessionId, isCurrent = () => true) {
+    const key = (0, secrets_1.opencodeV2KeyOf)(target);
+    const existing = slots.get(key);
+    if (existing) {
+        existing.queued = { port, sessionId, isCurrent };
+        return existing.running;
+    }
+    const slot = { running: Promise.resolve(), queued: null };
+    slot.running = (async () => {
+        let next = { port, sessionId, isCurrent };
+        while (next !== null) {
+            const current = next;
+            slot.queued = null;
+            await refreshOpencodeV2SessionUsage(target, current.port, current.sessionId, current.isCurrent);
+            next = slot.queued;
+        }
+        if (slots.get(key) === slot)
+            slots.delete(key);
+    })();
+    slots.set(key, slot);
+    return slot.running;
+}