commandmate 0.27.1 → 0.29.0

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

@@ -42,7 +42,7 @@
  * @module lib/hooks/sources/opencode/client
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_OPENCODE_SSE_FRAME_CHARS = exports.MAX_OPENCODE_SESSION_STATUSES = exports.OPENCODE_EVENT_CONTENT_TYPE = exports.OPENCODE_JSON_CONTENT_TYPE = exports.OPENCODE_FETCH_REDIRECT = exports.OPENCODE_REQUEST_TIMEOUT_MS = exports.OPENCODE_SERVER_HOST = void 0;
+exports.OPENCODE_SHARE_REQUEST_TIMEOUT_MS = exports.MAX_OPENCODE_DIFF_PATCH_CHARS = exports.MAX_OPENCODE_DIFF_FILES = exports.OPENCODE_CONTEXT_MESSAGE_WINDOW = exports.MAX_OPENCODE_SESSION_MESSAGES = exports.MAX_OPENCODE_SSE_FRAME_CHARS = exports.MAX_OPENCODE_SESSION_STATUSES = exports.OPENCODE_EVENT_CONTENT_TYPE = exports.OPENCODE_JSON_CONTENT_TYPE = exports.OPENCODE_FETCH_REDIRECT = exports.OPENCODE_REQUEST_TIMEOUT_MS = exports.OPENCODE_SERVER_HOST = void 0;
 exports.opencodeBaseUrl = opencodeBaseUrl;
 exports.probeOpencodeHealth = probeOpencodeHealth;
 exports.fetchOpencodeHealth = fetchOpencodeHealth;
@@ -50,11 +50,37 @@ exports.fetchOpencodePendingPermissions = fetchOpencodePendingPermissions;
 exports.fetchOpencodePendingQuestions = fetchOpencodePendingQuestions;
 exports.fetchOpencodeSessionStatuses = fetchOpencodeSessionStatuses;
 exports.fetchOpencodeActivity = fetchOpencodeActivity;
+exports.abortOpencodeSession = abortOpencodeSession;
+exports.opencodeFileUrl = opencodeFileUrl;
+exports.newOpencodeMessageId = newOpencodeMessageId;
+exports.promptSelectionBody = promptSelectionBody;
+exports.sendOpencodePrompt = sendOpencodePrompt;
+exports.readOpencodeUserMessage = readOpencodeUserMessage;
 exports.replyOpencodePermission = replyOpencodePermission;
 exports.replyOpencodeQuestion = replyOpencodeQuestion;
 exports.createSseParser = createSseParser;
 exports.openOpencodeEventStream = openOpencodeEventStream;
+exports.fetchOpencodeSessionMessages = fetchOpencodeSessionMessages;
+exports.fetchOpencodeModelContextLimit = fetchOpencodeModelContextLimit;
+exports.readOpencodeModelContextLimit = readOpencodeModelContextLimit;
+exports.fetchOpencodeProviderCatalog = fetchOpencodeProviderCatalog;
+exports.readOpencodeProviderCatalog = readOpencodeProviderCatalog;
+exports.fetchOpencodeAgents = fetchOpencodeAgents;
+exports.readOpencodeAgents = readOpencodeAgents;
+exports.isOpencodeLaunchableAgent = isOpencodeLaunchableAgent;
+exports.fetchOpencodeContextTokens = fetchOpencodeContextTokens;
+exports.readOpencodeFileDiffs = readOpencodeFileDiffs;
+exports.fetchOpencodeMessageDiff = fetchOpencodeMessageDiff;
+exports.revertOpencodeMessage = revertOpencodeMessage;
+exports.unrevertOpencodeSession = unrevertOpencodeSession;
+exports.fetchOpencodeShareMode = fetchOpencodeShareMode;
+exports.shareOpencodeSession = shareOpencodeSession;
+exports.unshareOpencodeSession = unshareOpencodeSession;
+exports.fetchOpencodeSessionShareUrl = fetchOpencodeSessionShareUrl;
+const crypto_1 = require("crypto");
+const url_1 = require("url");
 const logger_1 = require("../../../../lib/logger");
+const opencode_share_1 = require("../../../../types/opencode-share");
 const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/client');
 /**
  * The only host an opencode server is ever addressed on.
@@ -308,6 +334,238 @@ async function fetchOpencodeActivity(port) {
         return null;
     return Object.values(statuses).includes('busy') ? 'busy' : 'idle';
 }
+/**
+ * Stop the turn one session is running (Issue #2034).
+ *
+ * `POST /session/:id/abort`. Measured live on **1.18.22** — isolated HOME, an
+ * `opencode serve` on 127.0.0.1:4298, LM Studio as the provider, a generation
+ * aborted 6 s in:
+ *
+ * ```
+ * HTTP/1.1 200 OK
+ * Content-Type: application/json
+ * Content-Length: 4
+ *
+ * true
+ * ```
+ *
+ * and on the event stream, in the same millisecond as the reply:
+ *
+ * ```
+ * 10:17:25.946  session.error   MessageAbortedError
+ * 10:17:25.946  session.status  idle
+ * 10:17:25.946  session.idle          <- 1st
+ * 10:17:25.969  session.idle          <- 2nd, 23 ms later
+ * ```
+ *
+ * Two consequences for the caller, and neither is visible from the status code:
+ *
+ *  - **`true` is "accepted", not "a turn was stopped".** Aborting the SAME
+ *    session again once it was already idle answered `200 true` as well, and
+ *    emitted one more `session.idle`. So the reply cannot confirm the turn
+ *    ended; only the event can — see `./subscription`'s idle watch.
+ *  - **The idle can arrive before this promise resolves.** It did here: the
+ *    frame is emitted while the request is still in flight. A caller that
+ *    starts watching *after* awaiting this call can miss its own completion.
+ *
+ * `true` is required rather than "not null" because the route's own schema
+ * (`GET /doc`, `operationId: session.abort`) declares a bare boolean body: a
+ * `false` is the server saying it did not take the request, and `requestJson`
+ * would hand that back as a perfectly good parsed body.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`, the session whose turn should stop
+ * @returns Whether the server accepted the abort
+ */
+async function abortOpencodeSession(port, sessionId) {
+    const result = await requestJson(`${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/abort`, { method: 'POST' });
+    return result === true;
+}
+/**
+ * The `file://` URL for a local file, which is the only form the route takes.
+ *
+ * Measured on 1.18.22 (Issue #2035). A bare absolute path in `FilePartInput.url`
+ * is **accepted with `204` and then silently discarded** — the server answers
+ * before it resolves the part, and the resolution failure arrives on the event
+ * stream instead:
+ *
+ * ```
+ * session.error  UnknownError
+ *   TypeError: "/…/probe.png" cannot be parsed as a URL.
+ *     at SessionPrompt.resolveUserPart …
+ * ```
+ *
+ * and the **whole message is dropped, its text part included** — a read-back of
+ * the message id answers `404`. So this is not a nicety: a path handed over
+ * unencoded loses the operator's message with a success status code on the wire.
+ *
+ * `pathToFileURL` rather than `'file://' + path` because the difference is
+ * exactly the paths people have: a space or a `#` in a worktree name makes the
+ * concatenated string a different URL, and non-ASCII makes it an invalid one.
+ *
+ * @param absolutePath - Absolute path to a local file
+ * @returns `file:///…`, percent-encoded
+ */
+function opencodeFileUrl(absolutePath) {
+    return (0, url_1.pathToFileURL)(absolutePath).href;
+}
+/**
+ * A message id for a prompt CommandMate is about to post.
+ *
+ * The route accepts a caller-chosen `messageID` (schema: `pattern: "^msg"`), and
+ * that is what makes the send verifiable: the id is known *before* the request,
+ * so {@link readOpencodeUserMessage} can ask for that exact message afterwards
+ * rather than guessing which of the session's messages was this one. Measured on
+ * 1.18.22 — `msg_cmate2035probe0001` was accepted and read back verbatim.
+ *
+ * The `cmate` infix is deliberate: opencode's own ids are
+ * `msg_037794348001Ajss6k50nWrocp`, so a CommandMate-originated message stays
+ * identifiable in `opencode.db` afterwards, and the two generators cannot
+ * collide.
+ */
+function newOpencodeMessageId() {
+    return `msg_cmate${(0, crypto_1.randomBytes)(12).toString('hex')}`;
+}
+/**
+ * The `prompt_async` body keys a selection contributes, or nothing.
+ *
+ * Keys are omitted rather than nulled so a request from an instance with no
+ * settings is byte-identical to the pre-#2048 one.
+ */
+function promptSelectionBody(selection) {
+    if (!selection)
+        return {};
+    const body = {};
+    if (selection.agent)
+        body.agent = selection.agent;
+    if (selection.model?.providerID && selection.model.modelID) {
+        body.model = {
+            providerID: selection.model.providerID,
+            modelID: selection.model.modelID,
+        };
+    }
+    if (selection.variant)
+        body.variant = selection.variant;
+    return body;
+}
+/**
+ * Post one prompt to a session without waiting for the reply (Issue #2035).
+ *
+ * `POST /session/:id/prompt_async`. This is the route the send path takes when
+ * the instance has a server, and it was chosen over `/tui/append-prompt` +
+ * `/tui/submit-prompt` on a measurement, not a preference — see
+ * `docs/design/opencode-server-live-verification.md` §11.4. The short version:
+ * the `/tui/*` pair drives the TUI's **composer**, so it inherits the composer's
+ * state, and a body whose first token matches a slash command opens the command
+ * palette and the palette then eats the submit. `/exit` as a message body
+ * answered `200 true` on all three calls and produced no message at all. This
+ * route does not go through the composer, and the same body arrived verbatim.
+ *
+ * **`204` means accepted, not delivered.** Three measured ways that gap opens:
+ *
+ *  - a file part whose `url` is not a URL is dropped along with its whole
+ *    message ({@link opencodeFileUrl});
+ *  - a server that shares `HOME` + project with this one answers `204` for a
+ *    session it can reach through `opencode.db` — and the message then appears
+ *    on **neither** this server's event stream nor this pane's screen;
+ *  - an unknown route on a real opencode answers `200 text/html` (#1931), which
+ *    is why the status is compared exactly rather than through `response.ok`.
+ *
+ * {@link readOpencodeUserMessage} is the other half, and callers are expected to
+ * use it. Nothing here throws.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`, the session the message belongs to
+ * @param messageId - `msg_…`, from {@link newOpencodeMessageId}
+ * @param parts - The message body; at least one part
+ * @returns Whether the server answered `204`
+ */
+async function sendOpencodePrompt(port, sessionId, messageId, parts, selection) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/prompt_async`;
+    try {
+        const response = await loopbackFetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': exports.OPENCODE_JSON_CONTENT_TYPE },
+            body: JSON.stringify({
+                messageID: messageId,
+                ...promptSelectionBody(selection),
+                parts,
+            }),
+            signal: AbortSignal.timeout(exports.OPENCODE_REQUEST_TIMEOUT_MS),
+        });
+        if (response.status !== 204) {
+            logger.warn('opencode-prompt-rejected', { port, sessionId, status: response.status });
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        logger.debug('opencode-request-failed', {
+            url,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Read back one message by the id it was posted under (Issue #2035).
+ *
+ * `GET /session/:id/message/:messageID`. The positive evidence for a send, in
+ * the same sense `session.idle` is the positive evidence for an abort (#2034):
+ * the status code on the way in says the request was taken, and only this says
+ * the message exists.
+ *
+ * Measured on 1.18.22 across five runs: the message was readable on the **first**
+ * attempt, 8-23 ms after the POST began — `prompt_async` answers `204` after the
+ * message is created, not before. The falsification ran too: a message posted
+ * with a malformed file part answered `204` and then `404` here, which is the
+ * case the whole ladder is for.
+ *
+ * `info.role` is checked because the id space is shared with the assistant's
+ * messages: a `messageID` that collided with one would otherwise read back as a
+ * perfectly good delivery of somebody else's text.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @param messageId - `msg_…`, the id the prompt was posted under
+ */
+async function readOpencodeUserMessage(port, sessionId, messageId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}` +
+        `/message/${encodeURIComponent(messageId)}`;
+    let response;
+    try {
+        response = await loopbackFetch(url, {
+            signal: AbortSignal.timeout(exports.OPENCODE_REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return { kind: 'unknown', reason: error instanceof Error ? error.message : String(error) };
+    }
+    if (response.status === 404)
+        return { kind: 'missing' };
+    if (!response.ok)
+        return { kind: 'unknown', reason: `status ${response.status}` };
+    if (!hasContentType(response, exports.OPENCODE_JSON_CONTENT_TYPE)) {
+        return { kind: 'unknown', reason: 'content-type' };
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return { kind: 'unknown', reason: 'body' };
+    }
+    if (!isPlainObject(body))
+        return { kind: 'unknown', reason: 'body' };
+    const info = isPlainObject(body.info) ? body.info : null;
+    if (info === null || info.role !== 'user')
+        return { kind: 'unknown', reason: 'role' };
+    const texts = (Array.isArray(body.parts) ? body.parts : [])
+        .filter(isPlainObject)
+        .filter((part) => part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text);
+    return { kind: 'found', texts };
+}
 /**
  * Answer one approval.
  *
@@ -333,8 +591,17 @@ async function replyOpencodePermission(port, requestId, reply, message) {
 /**
  * Answer one question.
  *
+ * Reachable from production since Issue #2039. It was written with #1763's
+ * source and then had no caller for a year of Issues: `decideOpencode` routes
+ * `{ kind: 'answer' }` here, and nothing in `src/` built that verdict, so a
+ * `question.asked` could be displayed and never answered except with arrow
+ * keys. What #2039 added is the two mappings above it —
+ * `resolveStructuredQuestionAnswer` and the `kind === 'question'` branch of
+ * `respondByDecisionId` — not a line of this function.
+ *
  * @param answers - One array of selected labels per question, in the order the
- *   `question.asked` frame listed them
+ *   `question.asked` frame listed them. Measured shape: `{"answers":[["Blue"]]}`
+ *   for the one-question call (#1758 §5.2.4)
  */
 async function replyOpencodeQuestion(port, questionId, answers) {
     const result = await requestJson(`${opencodeBaseUrl(port)}/question/${encodeURIComponent(questionId)}/reply`, {
@@ -560,3 +827,641 @@ function safeParseFrame(raw) {
         return null;
     }
 }
+/**
+ * Cap on messages read back from one `GET /session/:id/message` (Issue #2041).
+ *
+ * Same argument as {@link MAX_OPENCODE_SESSION_STATUSES}: the document comes off
+ * a process CommandMate did not start, one server's `opencode.db` is shared by
+ * every TUI with the same HOME and project (#1758 §5.6.3), and a session that
+ * has been going for a week is not bounded by this instance's behaviour. Two
+ * messages per turn measured on 1.18.22 (one user, one or two assistant), so
+ * this is roughly 250 turns.
+ */
+exports.MAX_OPENCODE_SESSION_MESSAGES = 500;
+/**
+ * Every message in one session, with its parts (Issue #2041).
+ *
+ * `GET /session/:id/message`. The only route to a reply CommandMate did not see
+ * arrive: a fresh subscription to `/event` replays **nothing** — measured on
+ * 1.18.22, a second SSE connection opened after three completed turns received
+ * one `server.connected` frame and then silence — so a turn that ran while this
+ * server was down exists only here.
+ *
+ * The body is an array of `{ info, parts }`. Returned raw rather than parsed
+ * because the parsing lives in `./transcript`, which has to read the *same*
+ * shape off the event stream and must not have two readers of it.
+ *
+ * Answers null for every failure, including the ordinary "nothing is listening
+ * because the pane exited" — a caller cannot act on the difference and the
+ * distinction {@link OpencodeMessageReadback} draws is not available here (a
+ * missing session is a 404 that means the same as an unreachable one for a
+ * backfill: there is nothing to recover).
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @returns The array, bounded to the newest {@link MAX_OPENCODE_SESSION_MESSAGES}, or null
+ */
+async function fetchOpencodeSessionMessages(port, sessionId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/message`;
+    const body = await requestJson(url);
+    if (!Array.isArray(body))
+        return null;
+    const entries = body.filter(isPlainObject);
+    // Newest kept, and the array stays in the server's own order so `parentID`
+    // grouping still sees a turn's messages together.
+    return entries.length > exports.MAX_OPENCODE_SESSION_MESSAGES
+        ? entries.slice(entries.length - exports.MAX_OPENCODE_SESSION_MESSAGES)
+        : entries;
+}
+// ============================================================================
+// Context occupancy (Issue #2042). Appended at the end of the file on purpose:
+// #2041 is rewriting this module's neighbours in parallel, and everything below
+// is additive — no export above it is touched.
+// ============================================================================
+/**
+ * How many trailing messages are read back to find the last assistant turn.
+ *
+ * `GET /session/:id/message?limit=N` answers the **last** N messages in
+ * chronological order — measured on 1.18.22, see
+ * `docs/design/opencode-server-live-verification.md` §14.3. Four is two
+ * user/assistant pairs: enough that a turn still streaming (its assistant
+ * message exists but has `output === 0`) falls back to the previous completed
+ * one, and small enough that the read stays a few KB rather than the whole
+ * conversation. A session whose last four messages contain no finished
+ * assistant turn answers null, which is the honest answer — it has not spent a
+ * turn yet.
+ */
+exports.OPENCODE_CONTEXT_MESSAGE_WINDOW = 4;
+/**
+ * What one model declares it can hold, as `GET /config/providers` states it.
+ *
+ * Only `context` is read. `limit.input` is also published and is **not** the
+ * denominator: on `github-copilot/claude-sonnet-4.6` it is 936,000 against a
+ * `context` of 1,000,000, and opencode's own readout divides by `context`
+ * (§14.2 quotes the 1.18.22 bundle).
+ */
+async function fetchOpencodeModelContextLimit(port, providerId, modelId) {
+    const body = await fetchOpencodeProvidersDocument(port);
+    return readOpencodeModelContextLimit(body, providerId, modelId);
+}
+/**
+ * `GET /config/providers`, unparsed — the one reader of that route (#2048).
+ *
+ * Issue #2042 read this route for `limit.context` and Issue #2048 needs the
+ * same document for the *model and variant catalogue* the settings pane offers.
+ * Two independent readers of one endpoint is how the two come to disagree about
+ * its shape, so both go through here and each takes what it needs from the
+ * body. Nothing is cached: the call is a loopback round trip on a route that
+ * answers from memory, and the alternative is a cache that has to be invalidated
+ * when the operator adds a provider.
+ */
+async function fetchOpencodeProvidersDocument(port) {
+    return requestJson(`${opencodeBaseUrl(port)}/config/providers`);
+}
+/**
+ * `limit.context` for one model, out of a `GET /config/providers` body.
+ *
+ * Split from the fetch so the arithmetic is testable against a recorded body
+ * rather than a live server. Behaviour is #2042's, unchanged: `context` only,
+ * and a non-positive value is "no percentage" rather than a divisor.
+ */
+function readOpencodeModelContextLimit(body, providerId, modelId) {
+    if (!isPlainObject(body))
+        return null;
+    const providers = Array.isArray(body.providers) ? body.providers : [];
+    for (const provider of providers) {
+        if (!isPlainObject(provider) || provider.id !== providerId)
+            continue;
+        const models = isPlainObject(provider.models) ? provider.models : null;
+        if (!models)
+            return null;
+        const model = models[modelId];
+        if (!isPlainObject(model))
+            return null;
+        const limit = isPlainObject(model.limit) ? model.limit : null;
+        if (!limit)
+            return null;
+        const context = limit.context;
+        // A zero or a negative would divide into a percentage nobody can read, and
+        // opencode itself treats a falsy `limit.context` as "no percentage".
+        if (typeof context !== 'number' || !Number.isFinite(context) || context <= 0)
+            return null;
+        return context;
+    }
+    return null;
+}
+/**
+ * The provider / model / variant catalogue the settings pane offers (#2048).
+ *
+ * Three shapes measured on 1.18.22 (§20.1), each of which is easy to guess
+ * wrong:
+ *
+ *  - **`providers` is an array, `models` is an object.** The models are keyed by
+ *    model id, not listed — `providers[].models["claude-sonnet-4.6"]` — so an
+ *    `Array.isArray` guard on it drops every model there is.
+ *  - **`variants` is an object too**, keyed by variant name (`low` / `medium` /
+ *    `high` / `max` / `minimal` / `none` / `xhigh` across the measured
+ *    catalogue), whose values carry `effort` or `reasoningEffort`. Only the keys
+ *    are kept: the name is what `prompt_async` takes, and the effort inside it
+ *    is opencode's own restatement of the same word.
+ *  - **`variants: {}` is a real answer**, not a missing field — `kimi-k2.7-code`
+ *    publishes it — and it is how the pane knows to offer no variant at all.
+ *
+ * Entries that do not parse are dropped rather than represented: this feeds a
+ * `<select>`, and an option with no id is an option that cannot be chosen.
+ *
+ * @param port - The instance's server
+ * @returns The catalogue, or an empty array when the server could not be asked
+ */
+async function fetchOpencodeProviderCatalog(port) {
+    return readOpencodeProviderCatalog(await fetchOpencodeProvidersDocument(port));
+}
+/** {@link fetchOpencodeProviderCatalog}'s parser, over an already-read body. */
+function readOpencodeProviderCatalog(body) {
+    if (!isPlainObject(body))
+        return [];
+    const providers = Array.isArray(body.providers) ? body.providers : [];
+    const catalog = [];
+    for (const provider of providers) {
+        if (!isPlainObject(provider))
+            continue;
+        const id = typeof provider.id === 'string' ? provider.id : null;
+        if (!id)
+            continue;
+        const models = [];
+        const rawModels = isPlainObject(provider.models) ? provider.models : {};
+        for (const [modelId, rawModel] of Object.entries(rawModels)) {
+            if (!isPlainObject(rawModel))
+                continue;
+            const variants = isPlainObject(rawModel.variants) ? Object.keys(rawModel.variants) : [];
+            models.push({
+                id: modelId,
+                name: typeof rawModel.name === 'string' && rawModel.name.length > 0
+                    ? rawModel.name
+                    : modelId,
+                variants: variants.sort(),
+            });
+        }
+        models.sort((a, b) => a.id.localeCompare(b.id));
+        catalog.push({
+            id,
+            name: typeof provider.name === 'string' && provider.name.length > 0 ? provider.name : id,
+            models,
+        });
+    }
+    catalog.sort((a, b) => a.id.localeCompare(b.id));
+    return catalog;
+}
+/**
+ * The personas this server will start a session as — `GET /agent` (#2048).
+ *
+ * An **array**, unlike `/config/providers`'s object-of-models, and its entries
+ * carry two fields that decide what the pane may offer (§20.1): `mode` is
+ * `primary` or `subagent`, and `hidden` is `true` on the three internal
+ * personas (`compaction`, `summary`, `title`). A stock 1.18.22 install answered
+ * seven agents of which exactly two — `build` and `plan` — are primary and
+ * visible, which is the pair Issue #2048's acceptance condition names.
+ *
+ * Both fields are kept rather than filtered here: this is the reader, and which
+ * agents a *launch* may name is a policy the caller states —
+ * {@link isOpencodeLaunchableAgent}.
+ *
+ * @param port - The instance's server
+ * @returns Every agent the server declared, or an empty array when it could not
+ *   be asked
+ */
+async function fetchOpencodeAgents(port) {
+    return readOpencodeAgents(await requestJson(`${opencodeBaseUrl(port)}/agent`));
+}
+/** {@link fetchOpencodeAgents}'s parser, over an already-read body. */
+function readOpencodeAgents(body) {
+    if (!Array.isArray(body))
+        return [];
+    const agents = [];
+    for (const entry of body) {
+        if (!isPlainObject(entry))
+            continue;
+        const name = typeof entry.name === 'string' ? entry.name : null;
+        if (!name)
+            continue;
+        // `hidden` is absent on the visible ones rather than `false`, so the test is
+        // truthiness of the key and not a comparison against `false`.
+        if (entry.hidden === true)
+            continue;
+        agents.push({
+            name,
+            mode: typeof entry.mode === 'string' ? entry.mode : '',
+            description: typeof entry.description === 'string' ? entry.description : null,
+        });
+    }
+    return agents;
+}
+/**
+ * Whether an agent may be named on a launch line or a prompt.
+ *
+ * `primary` only. A `subagent` (`explore`, `general`) is something a running
+ * session spawns for a `task` tool call; naming one as the session's own persona
+ * is not a thing opencode's UI offers and not something measured to work.
+ */
+function isOpencodeLaunchableAgent(agent) {
+    return agent.mode === 'primary';
+}
+/** A finite, non-negative token count, or 0 — the shape `tokens.*` arrives in. */
+function readTokenCount(source, key) {
+    const value = source[key];
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * How full this session's context is, in tokens (Issue #2042).
+ *
+ * **This is not `Session.tokens` and the difference is the whole point.**
+ * `session.updated` reports a *cumulative* count — after two turns the measured
+ * session read `input 6 / output 11 / cache.read 8482 / cache.write 8500`, which
+ * is what `opencode stats` prints and what `AgentSessionRecord` carries.
+ * What opencode's own TUI shows as `8.5K (1%)` is a different quantity: the
+ * token footprint of the **last assistant message**, which is what the next
+ * request actually has to fit into a context window. Summing the session's
+ * counts would have said 16,999 where opencode says 8,508, and the gap widens
+ * with every turn (§14.2).
+ *
+ * The rule is opencode's own, transcribed from the 1.18.22 bundle rather than
+ * inferred: take the last message with `role === 'assistant'` **and**
+ * `tokens.output > 0`, and add `input + output + reasoning + cache.read +
+ * cache.write`. The `output > 0` clause is what skips the assistant message a
+ * turn opens with, whose counts are all zero until the turn finishes.
+ *
+ * `tokens.total` on that message is opencode's own sum of exactly those five
+ * and was measured equal to it (8491, then 8508) — it is not read here because
+ * it is absent until the turn completes, and the five are the definition.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @returns The occupancy in tokens, or null when no finished assistant turn is
+ *   in the window (a fresh session, or one whose last four messages are all
+ *   user prompts) and on every transport failure
+ */
+async function fetchOpencodeContextTokens(port, sessionId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/message` +
+        `?limit=${exports.OPENCODE_CONTEXT_MESSAGE_WINDOW}`;
+    const body = await requestJson(url);
+    if (!Array.isArray(body))
+        return null;
+    for (let index = body.length - 1; index >= 0; index -= 1) {
+        const entry = body[index];
+        if (!isPlainObject(entry))
+            continue;
+        // `{ info, parts }`; only `info` carries the counts.
+        const info = isPlainObject(entry.info) ? entry.info : null;
+        if (!info || info.role !== 'assistant')
+            continue;
+        const tokens = isPlainObject(info.tokens) ? info.tokens : null;
+        if (!tokens)
+            continue;
+        const output = readTokenCount(tokens, 'output');
+        if (output <= 0)
+            continue;
+        const cache = isPlainObject(tokens.cache) ? tokens.cache : {};
+        return (readTokenCount(tokens, 'input') +
+            output +
+            readTokenCount(tokens, 'reasoning') +
+            readTokenCount(cache, 'read') +
+            readTokenCount(cache, 'write'));
+    }
+    return null;
+}
+const OPENCODE_FILE_DIFF_STATUSES = ['added', 'deleted', 'modified'];
+/**
+ * Cap on files kept from one diff.
+ *
+ * A diff is carried on the status poll's payload, and `patch` is unbounded — a
+ * generated lockfile is megabytes of it. The cap is on *files* rather than
+ * bytes so the panel never shows half a file's name; {@link MAX_OPENCODE_DIFF_PATCH_CHARS}
+ * is the byte-side companion.
+ */
+exports.MAX_OPENCODE_DIFF_FILES = 200;
+/** Cap on one file's `patch`. Truncated patches still render; huge ones do not. */
+exports.MAX_OPENCODE_DIFF_PATCH_CHARS = 64 * 1024;
+/**
+ * Read an array of `SnapshotFileDiff` off any opencode payload.
+ *
+ * Shared by the event reader and the REST reader on purpose: `session.diff`'s
+ * `properties.diff` and `GET /session/:id/diff`'s body are the *same* schema,
+ * and two readers of one shape is how they come apart.
+ *
+ * Entries that are not objects are dropped rather than represented, and a
+ * non-array answers the empty array — "the server said nothing readable" and
+ * "the server said no files" are the same instruction to a panel that hides
+ * itself when empty.
+ */
+function readOpencodeFileDiffs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const files = [];
+    for (const entry of value) {
+        if (!isPlainObject(entry))
+            continue;
+        const patch = typeof entry.patch === 'string' ? entry.patch : null;
+        files.push({
+            file: typeof entry.file === 'string' && entry.file.length > 0 ? entry.file : null,
+            patch: patch === null ? null : patch.slice(0, exports.MAX_OPENCODE_DIFF_PATCH_CHARS),
+            additions: typeof entry.additions === 'number' && Number.isFinite(entry.additions)
+                ? entry.additions
+                : 0,
+            deletions: typeof entry.deletions === 'number' && Number.isFinite(entry.deletions)
+                ? entry.deletions
+                : 0,
+            status: typeof entry.status === 'string' && OPENCODE_FILE_DIFF_STATUSES.includes(entry.status)
+                ? entry.status
+                : null,
+        });
+        if (files.length >= exports.MAX_OPENCODE_DIFF_FILES)
+            break;
+    }
+    return files;
+}
+/**
+ * The files one user message's turn changed (Issue #2043).
+ *
+ * `GET /session/:id/diff?messageID=<msg…>`. **The `messageID` is not optional in
+ * practice**: measured on 1.18.22, the same route without it answered `[]` both
+ * before and after a turn that changed two files, while the same call *with* it
+ * answered both files and their patches.
+ *
+ * The answer is a historical record rather than live state — measured: it still
+ * returned the turn's two files after that turn had been reverted — so a caller
+ * showing "what this turn changed" is reading the right thing, and a caller
+ * asking "is this still applied" is not.
+ *
+ * A malformed `messageID` (one not starting with `msg`) is a **400** from the
+ * server, which collapses to null here like every other failure.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @param messageId - `msg_…`, the *user* message that opened the turn
+ * @returns The files, or null when the server could not be asked
+ */
+async function fetchOpencodeMessageDiff(port, sessionId, messageId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/diff` +
+        `?messageID=${encodeURIComponent(messageId)}`;
+    const body = await requestJson(url);
+    if (!Array.isArray(body))
+        return null;
+    return readOpencodeFileDiffs(body);
+}
+/**
+ * `Session.revert.messageID`, or null when the session holds nothing back.
+ *
+ * The one field that distinguishes a revert that took from one that did not,
+ * for both routes: `POST /revert` sets it, `POST /unrevert` clears it, and a
+ * no-op leaves it as it was.
+ */
+function readSessionRevertMessageId(body) {
+    if (!isPlainObject(body))
+        return null;
+    const revert = isPlainObject(body.revert) ? body.revert : null;
+    if (!revert)
+        return null;
+    return typeof revert.messageID === 'string' && revert.messageID.length > 0
+        ? revert.messageID
+        : null;
+}
+/** One POST to a revert route, with the three measured statuses kept apart. */
+async function postOpencodeRevertRoute(url, body) {
+    let response;
+    try {
+        response = await loopbackFetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': exports.OPENCODE_JSON_CONTENT_TYPE },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(exports.OPENCODE_REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        logger.debug('opencode-request-failed', {
+            url,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { outcome: { kind: 'unreachable' } };
+    }
+    if (response.status === 409)
+        return { outcome: { kind: 'busy' } };
+    if (!response.ok) {
+        logger.warn('opencode-revert-rejected', { url, status: response.status });
+        return { outcome: { kind: 'rejected', status: response.status } };
+    }
+    // #1931: an unknown route on a real opencode answers `200 text/html`, so a
+    // 200 alone does not mean this route exists on the server that answered.
+    if (!hasContentType(response, exports.OPENCODE_JSON_CONTENT_TYPE)) {
+        return { outcome: { kind: 'unreachable' } };
+    }
+    try {
+        return { revertedTo: readSessionRevertMessageId(await response.json()) };
+    }
+    catch {
+        return { outcome: { kind: 'unreachable' } };
+    }
+}
+/**
+ * Undo one turn's file changes (Issue #2043).
+ *
+ * `POST /session/:id/revert` with `{ messageID }`. **Destructive and measured to
+ * be so**: reverting to the first turn of a two-turn session restored
+ * `sample.txt` to its pre-session contents *and deleted* the `added.txt` the
+ * agent had created. It rewrites the working tree from opencode's own git
+ * snapshot ledger, so it can also undo work that was already committed — the
+ * measurement in §16.5 left a clean tree reading ` D added.txt` / ` M
+ * sample.txt` afterwards.
+ *
+ * That is why the caller is expected to confirm first, and why a `no_op` is
+ * reported rather than swallowed.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @param messageId - `msg_…`, the user message whose turn is being undone
+ */
+async function revertOpencodeMessage(port, sessionId, messageId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/revert`;
+    const result = await postOpencodeRevertRoute(url, { messageID: messageId });
+    if ('outcome' in result)
+        return result.outcome;
+    // Measured twice, and the second measurement is why this compares ids rather
+    // than testing for null. From a session with nothing reverted, an unknown
+    // `messageID` answers `200` with `revert: null`. From a session that is
+    // **already** holding a revert, the same request answers `200` with the
+    // *existing* `revert` untouched — so a null check alone reported success, and
+    // reported it under the previous revert's message id. A revert that took
+    // echoes the id that was asked for; anything else did nothing.
+    return result.revertedTo === messageId
+        ? { kind: 'reverted', messageId }
+        : { kind: 'no_op' };
+}
+/**
+ * Put back everything a revert is holding (Issue #2043).
+ *
+ * `POST /session/:id/unrevert`. Takes no arguments — it restores *all*
+ * previously reverted messages, per the server's own summary — and answers
+ * **200 on a session with nothing reverted**, which is why "restored" here means
+ * "nothing is held back now" rather than "something moved".
+ *
+ * Measured asymmetry worth knowing: a successful unrevert emits **no
+ * `session.diff` frame at all**, only `session.updated` with `revert: null`. A
+ * reader that waited for `session.diff` to go empty would wait forever, which is
+ * why {@link readOpencodeRevertState} reads the session frame too.
+ */
+async function unrevertOpencodeSession(port, sessionId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/unrevert`;
+    const result = await postOpencodeRevertRoute(url, {});
+    if ('outcome' in result)
+        return result.outcome;
+    // Here the null check *is* the right test: unrevert takes no argument, so
+    // "nothing is held back any more" is the whole success condition. A session
+    // that still reports a revert refused to let go of it.
+    return result.revertedTo === null
+        ? { kind: 'restored' }
+        : { kind: 'no_op' };
+}
+// =============================================================================
+// Session sharing (Issue #2051)
+// =============================================================================
+/**
+ * Timeout for the two share routes.
+ *
+ * Longer than {@link OPENCODE_REQUEST_TIMEOUT_MS}, which bounds loopback calls
+ * that opencode answers out of its own process. These two do not stay on the
+ * loopback: opencode uploads the session to its hosting and waits for the reply,
+ * so the round trip includes somebody else's network. 20s rather than 5s, and
+ * still bounded, because the operator is watching a spinner.
+ */
+exports.OPENCODE_SHARE_REQUEST_TIMEOUT_MS = 20_000;
+/**
+ * The `share` setting this server is running with.
+ *
+ * A whole `GET /config` fetch for one key, because that is the only place the
+ * setting is exposed: there is no `/config/share`, and the value is not on the
+ * session. Cheap enough — the measured body is under 200 bytes.
+ *
+ * @param port - The instance's server
+ * @returns The mode, or null when the key is unset, unknown to this build, or
+ *   the server could not be asked. `null` must not be read as `'disabled'`;
+ *   see `src/types/opencode-share.ts`
+ */
+async function fetchOpencodeShareMode(port) {
+    const body = await requestJson(`${opencodeBaseUrl(port)}/config`);
+    return (0, opencode_share_1.readOpencodeShareMode)(body);
+}
+/**
+ * Publish one session to opencode's hosting.
+ *
+ * **This makes the conversation readable by anyone with the link**, under the
+ * operator's own credentials. Measured on 1.18.22: the published page carries
+ * the session *unredacted* — the prompts, the replies and the absolute
+ * `directory` path were all present in the HTML. It is the exact opposite of
+ * `opencode export --sanitize`, and nothing between here and the operator
+ * removes anything. Every caller must have taken an explicit confirmation
+ * first.
+ *
+ * Written against `requestJson`'s siblings rather than through it because the
+ * status code is load-bearing here: `requestJson` collapses every non-2xx to
+ * null, and a 404 (no such session) needs telling apart from a 500 (refused).
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @returns The outcome; on success, the URL opencode minted
+ */
+async function shareOpencodeSession(port, sessionId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/share`;
+    try {
+        // Measured: the route takes no request body at all (`requestBody: null` in
+        // opencode's own OpenAPI), so none is sent.
+        const response = await loopbackFetch(url, {
+            method: 'POST',
+            signal: AbortSignal.timeout(exports.OPENCODE_SHARE_REQUEST_TIMEOUT_MS),
+        });
+        if (response.status === 404)
+            return { kind: 'not-found' };
+        if (!response.ok) {
+            logger.warn('opencode-share-refused', { port, sessionId, status: response.status });
+            return { kind: 'refused', status: response.status };
+        }
+        if (!hasContentType(response, exports.OPENCODE_JSON_CONTENT_TYPE)) {
+            return { kind: 'failed', reason: 'response was not JSON' };
+        }
+        const body = (await response.json());
+        const shareUrl = (0, opencode_share_1.readOpencodeShareUrl)(body);
+        if (shareUrl === null) {
+            // A 200 with no usable URL is the one case that must not read as success:
+            // the session may well be published, and the operator would be told it is
+            // not. Reported as a failure so the UI keeps the revoke path visible.
+            logger.warn('opencode-share-no-url', { port, sessionId });
+            return { kind: 'failed', reason: 'server returned no share URL' };
+        }
+        logger.info('opencode-share-created', { port, sessionId });
+        return { kind: 'shared', url: shareUrl };
+    }
+    catch (error) {
+        return {
+            kind: 'failed',
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Take one session's published page down.
+ *
+ * Measured on 1.18.22, and both halves matter:
+ *
+ * - It **works**: the public URL stops serving the conversation and renders
+ *   opencode's own "Not Found" view instead. Note that the HTTP status stays
+ *   **200** — the not-found view is client-rendered — so a caller must not
+ *   verify revocation by fetching the URL and testing for 404.
+ * - The session **keeps its `share: { url }`** afterwards, in the response to
+ *   this very call and in `GET /session/:id`, and it survives a server restart.
+ *   So there is no server-side flag saying "currently shared", and this
+ *   function's boolean is the only signal a caller gets.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @returns Whether opencode accepted the revocation
+ */
+async function unshareOpencodeSession(port, sessionId) {
+    const url = `${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}/share`;
+    try {
+        const response = await loopbackFetch(url, {
+            method: 'DELETE',
+            signal: AbortSignal.timeout(exports.OPENCODE_SHARE_REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            logger.warn('opencode-unshare-refused', { port, sessionId, status: response.status });
+            return false;
+        }
+        logger.info('opencode-share-removed', { port, sessionId });
+        return true;
+    }
+    catch (error) {
+        logger.warn('opencode-unshare-failed', {
+            port,
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * The share URL opencode currently records against one session.
+ *
+ * A raw `GET /session/:id` rather than `fetchOpencodeSession()`, which projects
+ * the body down to `{ id, title, directory, parentId }` and drops `share`
+ * along with it.
+ *
+ * Read what this returns as **"a page was published for this session at some
+ * point"**, never as "a page is up now": the field survives
+ * {@link unshareOpencodeSession} and a server restart. See that function.
+ *
+ * @param port - The instance's server
+ * @param sessionId - `ses_…`
+ * @returns The recorded `https:` URL, or null when there is none
+ */
+async function fetchOpencodeSessionShareUrl(port, sessionId) {
+    const body = await requestJson(`${opencodeBaseUrl(port)}/session/${encodeURIComponent(sessionId)}`);
+    return (0, opencode_share_1.readOpencodeShareUrl)(body);
+}