commandmate 0.26.0 → 0.27.0

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

@@ -9,7 +9,7 @@
  * lifetime is the pane's lifetime, and everything in this file is a request to
  * a port that either answers or does not.
  *
- * Four measurements shape the choices below.
+ * Five measurements shape the choices below.
  *
  *  - **The subscription is legacy `GET /event`.** `GET /api/event` (v2) goes
  *    silent after the first three frames of a turn, reproducibly, and
@@ -28,6 +28,12 @@
  *  - **Absence is free to detect.** A closed port fails in under a millisecond
  *    (§5.7.2), so health checks cost nothing and every call here is allowed to
  *    be attempted rather than guarded by cached state.
+ *  - **An unknown route answers `200 text/html`.** Measured on 1.18.21 (Issue
+ *    #1931): a path the server does not know gets the web UI's SPA shell, not a
+ *    404. "The socket accepted me" is therefore not "the route exists", which is
+ *    why every call below checks the media type as well as the status — and why
+ *    redirects are refused rather than followed. See
+ *    {@link OPENCODE_FETCH_REDIRECT}.
  *
  * Nothing in this module throws. A source that cannot reach its agent has to
  * degrade to the screen scraper, and an exception on the way to that decision
@@ -36,16 +42,18 @@
  * @module lib/hooks/sources/opencode/client
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPENCODE_REQUEST_TIMEOUT_MS = exports.OPENCODE_SERVER_HOST = void 0;
+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;
 exports.fetchOpencodePendingPermissions = fetchOpencodePendingPermissions;
 exports.fetchOpencodePendingQuestions = fetchOpencodePendingQuestions;
+exports.fetchOpencodeSessionStatuses = fetchOpencodeSessionStatuses;
 exports.fetchOpencodeActivity = fetchOpencodeActivity;
 exports.replyOpencodePermission = replyOpencodePermission;
 exports.replyOpencodeQuestion = replyOpencodeQuestion;
 exports.createSseParser = createSseParser;
-exports.readOpencodeEventStream = readOpencodeEventStream;
+exports.openOpencodeEventStream = openOpencodeEventStream;
 const logger_1 = require("../../../../lib/logger");
 const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/client');
 /**
@@ -59,6 +67,73 @@ const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/client');
 exports.OPENCODE_SERVER_HOST = '127.0.0.1';
 /** Timeout for the small request/response calls. Generous: they answer in ms. */
 exports.OPENCODE_REQUEST_TIMEOUT_MS = 5_000;
+/**
+ * Never follow a redirect off this port (Issue #1931, §10.4 / S13).
+ *
+ * The port is the whole of the trust model here: an opencode server is
+ * unauthenticated, and `isPortFree` is a bind-and-close check, so any local
+ * process can take the number CommandMate wrote down. `fetch` defaults to
+ * `redirect: 'follow'`, which means a squatter answering `302 Location: …`
+ * chooses where CommandMate's *server* sends its next request. Two consequences,
+ * and the second is the worse one:
+ *
+ *  - It reads the identity, the pending approvals and the session activity off a
+ *    host it never chose, and then adjudicates approvals against it.
+ *  - Pointed back at CommandMate's own API, it is an SSRF that arrives from
+ *    `127.0.0.1` — and `CM_ALLOWED_IPS` is enforced on `getClientIp`, which
+ *    reads the `x-real-ip` the server sets from `socket.remoteAddress`
+ *    (`src/lib/security/ip-restriction.ts`). A request the server makes to
+ *    itself is therefore inside every allowlist that names loopback.
+ *
+ * `'manual'` turns every 3xx into a response with `ok === false`, which each
+ * caller below already treats as "this is not our server".
+ *
+ * Applied through {@link loopbackFetch} rather than at each call site so there is
+ * one place to regress, and spread *after* the caller's `init` so no caller can
+ * put it back to `follow` by accident.
+ */
+exports.OPENCODE_FETCH_REDIRECT = 'manual';
+/**
+ * `application/json`, which is what opencode answers on every JSON route.
+ *
+ * Measured on 1.18.21 (Issue #1931): `/global/health`, `/permission`,
+ * `/question`, `/session/status` and both reply endpoints all send the bare type
+ * with no parameters — on their 400 and 404 replies too.
+ */
+exports.OPENCODE_JSON_CONTENT_TYPE = 'application/json';
+/**
+ * `text/event-stream`, which is what `GET /event` answers.
+ *
+ * Load-bearing rather than cosmetic. The same measurement found that an
+ * *unknown* route on a real opencode server answers **`200 text/html`** — the
+ * web UI's SPA shell, not a 404. So a server on this port that does not have the
+ * route CommandMate wants hands back a success with a body, and without this
+ * check {@link openOpencodeEventStream} would hold an HTML page open, report the
+ * subscription `live`, and yield frames forever at a rate of none.
+ */
+exports.OPENCODE_EVENT_CONTENT_TYPE = 'text/event-stream';
+/**
+ * One request to the loopback server, with redirects refused.
+ *
+ * @param url - Absolute URL on the loopback server
+ * @param init - Method / body / signal. `redirect` is overridden, on purpose
+ */
+async function loopbackFetch(url, init) {
+    return fetch(url, { ...init, redirect: exports.OPENCODE_FETCH_REDIRECT });
+}
+/**
+ * Whether a response says it is the media type this call can read.
+ *
+ * The type alone, lower-cased: a `; charset=…` parameter is legal even though
+ * 1.18.21 sends none. A response with no `content-type` at all is *not* accepted
+ * — opencode always sends one, so its absence means something else answered.
+ */
+function hasContentType(response, expected) {
+    const header = response.headers?.get?.('content-type');
+    if (typeof header !== 'string')
+        return false;
+    return header.split(';', 1)[0]?.trim().toLowerCase() === expected;
+}
 /** `http://127.0.0.1:<port>`. */
 function opencodeBaseUrl(port) {
     return `http://${exports.OPENCODE_SERVER_HOST}:${port}`;
@@ -75,12 +150,21 @@ function isPlainObject(value) {
  */
 async function requestJson(url, init) {
     try {
-        const response = await fetch(url, {
+        const response = await loopbackFetch(url, {
             ...init,
             signal: AbortSignal.timeout(exports.OPENCODE_REQUEST_TIMEOUT_MS),
         });
+        // A 3xx lands here rather than at its target, because of the `redirect`
+        // above; a squatter's SPA shell lands here as a 200 that is not JSON.
         if (!response.ok)
             return null;
+        if (!hasContentType(response, exports.OPENCODE_JSON_CONTENT_TYPE)) {
+            logger.debug('opencode-request-content-type', {
+                url,
+                contentType: response.headers?.get?.('content-type') ?? null,
+            });
+            return null;
+        }
         return (await response.json());
     }
     catch (error) {
@@ -92,18 +176,54 @@ async function requestJson(url, init) {
         return null;
     }
 }
+/**
+ * Ask whether an opencode server is listening on this port, and say what kind
+ * of no it was (Issue #1900).
+ */
+async function probeOpencodeHealth(port) {
+    const url = `${opencodeBaseUrl(port)}/global/health`;
+    let response;
+    try {
+        response = await loopbackFetch(url, {
+            signal: AbortSignal.timeout(exports.OPENCODE_REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.debug('opencode-request-failed', { url, error: message });
+        return { kind: 'refused', error: message };
+    }
+    // A 3xx is `rejected`, not `refused`, and that classification is the point:
+    // `refused` is retried on the way back up (a server still booting), while a
+    // process that answers a redirect will answer one again. Retrying it would
+    // only delay the fall back to the scraper.
+    if (!response.ok)
+        return { kind: 'rejected', status: response.status };
+    if (!hasContentType(response, exports.OPENCODE_JSON_CONTENT_TYPE)) {
+        return { kind: 'rejected', status: 0 };
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return { kind: 'rejected', status: response.status };
+    }
+    if (!isPlainObject(body) || body.healthy !== true)
+        return { kind: 'rejected', status: 0 };
+    return {
+        kind: 'healthy',
+        health: { healthy: true, version: typeof body.version === 'string' ? body.version : null },
+    };
+}
 /**
  * Ask whether an opencode server is listening on this port.
  *
  * @returns Its health and version, or null when nothing answered
  */
 async function fetchOpencodeHealth(port) {
-    const body = await requestJson(`${opencodeBaseUrl(port)}/global/health`);
-    if (!isPlainObject(body))
-        return null;
-    if (body.healthy !== true)
-        return null;
-    return { healthy: true, version: typeof body.version === 'string' ? body.version : null };
+    const outcome = await probeOpencodeHealth(port);
+    return outcome.kind === 'healthy' ? outcome.health : null;
 }
 /** An array body, or an empty array — `GET /permission` answers a bare array. */
 function asObjectArray(body) {
@@ -126,24 +246,67 @@ async function fetchOpencodePendingQuestions(port) {
     return asObjectArray(await requestJson(`${opencodeBaseUrl(port)}/question`));
 }
 /**
- * Whether any session on this server is working (#1758 §5.7.4).
+ * Cap on sessions read back from one `/session/status` (§4 D3, DR4-009).
+ *
+ * The document comes off a process CommandMate did not start, and one server's
+ * `opencode.db` is shared by every TUI with the same HOME and project (#1758
+ * §5.6.3), so the map is not bounded by this instance's own behaviour.
+ */
+exports.MAX_OPENCODE_SESSION_STATUSES = 128;
+/**
+ * What every session on this server is doing (#1758 §5.7.4).
  *
  * `GET /session/status` answers `{"ses_…":{"type":"busy"|"idle"}}`. Note what
  * this does *not* answer: a session blocked on an approval reads `busy`, so
  * this says "the turn is not over", never "the agent is thinking".
  *
- * @returns `busy` when any session is busy, `idle` when none is, null when the
- *   server could not be asked
+ * Per-session rather than aggregated, because a reconnect has to decide about
+ * *one* turn (Issue #1900): "something on this server is busy" cannot tell a
+ * parent session that is still working from a sub-agent's that is.
+ *
+ * @returns The map, or null when the server could not be asked. An entry whose
+ *   `type` is neither word is dropped rather than guessed at
  */
-async function fetchOpencodeActivity(port) {
+async function fetchOpencodeSessionStatuses(port) {
     const body = await requestJson(`${opencodeBaseUrl(port)}/session/status`);
     if (!isPlainObject(body))
         return null;
-    for (const value of Object.values(body)) {
-        if (isPlainObject(value) && value.type === 'busy')
-            return 'busy';
+    const statuses = {};
+    let read = 0;
+    for (const [sessionId, value] of Object.entries(body)) {
+        if (read >= exports.MAX_OPENCODE_SESSION_STATUSES) {
+            logger.warn('opencode-session-status-truncated', {
+                port,
+                kept: read,
+                total: Object.keys(body).length,
+                limit: exports.MAX_OPENCODE_SESSION_STATUSES,
+            });
+            break;
+        }
+        if (!isPlainObject(value))
+            continue;
+        if (value.type !== 'busy' && value.type !== 'idle')
+            continue;
+        statuses[sessionId] = value.type;
+        read += 1;
     }
-    return 'idle';
+    return statuses;
+}
+/**
+ * Whether any session on this server is working (#1758 §5.7.4).
+ *
+ * The aggregate view of {@link fetchOpencodeSessionStatuses}, which is what
+ * `AgentEventSource.probeActivity` promises its callers — they hold an instance,
+ * not a session id.
+ *
+ * @returns `busy` when any session is busy, `idle` when none is, null when the
+ *   server could not be asked
+ */
+async function fetchOpencodeActivity(port) {
+    const statuses = await fetchOpencodeSessionStatuses(port);
+    if (statuses === null)
+        return null;
+    return Object.values(statuses).includes('busy') ? 'busy' : 'idle';
 }
 /**
  * Answer one approval.
@@ -184,6 +347,22 @@ async function replyOpencodeQuestion(port, questionId, answers) {
 // =============================================================================
 // SSE
 // =============================================================================
+/**
+ * Cap on one SSE frame, in characters (Issue #1931, §10.4).
+ *
+ * 256 Ki, which is the design's 256 KiB counted in the unit the parser actually
+ * holds: it accumulates a JavaScript string, so a byte-exact bound would mean
+ * re-encoding every line. A character is one to four UTF-8 bytes, so this is a
+ * bound in either unit at the same order — and a bound is the whole point. The
+ * largest captured opencode frame is under 8 KiB.
+ *
+ * Two things are being bounded, and only the second is hostile. A server that
+ * sends a frame far larger than anything measured is a version CommandMate does
+ * not understand; a process that took the port and streams bytes with no line
+ * or frame boundary at all is memory exhaustion in one socket, because a naive
+ * parser holds every byte it has not yet been able to split.
+ */
+exports.MAX_OPENCODE_SSE_FRAME_CHARS = 256 * 1024;
 /**
  * Incremental parser for the one SSE shape opencode emits.
  *
@@ -192,28 +371,63 @@ async function replyOpencodeQuestion(port, questionId, answers) {
  * 1.18.3 has never been observed to send one; supporting it costs a line and
  * removes a class of silent truncation.
  *
+ * A frame over {@link MAX_OPENCODE_SSE_FRAME_CHARS} is dropped — along with the
+ * rest of its lines, up to the next frame boundary — and counted, rather than
+ * ending the stream. That is a deliberate departure from "discard and
+ * reconnect" (Issue #1931): tearing the connection down over one fat frame
+ * costs a full re-sync of `/permission`, `/question` and `/session/status`, and
+ * on a stream where the fat frame *repeats* it costs the live subscription
+ * entirely. The reconnect still happens in the case that needs it — a socket
+ * whose only traffic is oversized yields no frames, so nothing re-arms the
+ * heartbeat watchdog and the subscription drops and re-verifies the port's
+ * identity on its own.
+ *
  * @returns A parser whose `push` returns whatever frames the chunk completed
  */
 function createSseParser() {
     let buffer = '';
     let dataLines = [];
+    let dataChars = 0;
+    /** Dropping the remainder of a frame that already went over the cap. */
+    let discarding = false;
+    let oversized = 0;
     const completed = [];
+    const dropOversizedFrame = () => {
+        dataLines = [];
+        dataChars = 0;
+        discarding = true;
+        oversized += 1;
+    };
     const finishEvent = () => {
         if (dataLines.length === 0)
             return;
         completed.push(dataLines.join('\n'));
         dataLines = [];
+        dataChars = 0;
     };
     const consumeLine = (rawLine) => {
         const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
         if (line === '') {
-            finishEvent();
+            // A blank line ends the frame either way: the good one is emitted, the
+            // oversized one is what the parser has been waiting to stop dropping.
+            if (discarding)
+                discarding = false;
+            else
+                finishEvent();
             return;
         }
+        if (discarding)
+            return;
         if (line.startsWith(':'))
             return; // comment / keepalive
         if (line.startsWith('data:')) {
-            dataLines.push(line.slice(5).replace(/^ /, ''));
+            const data = line.slice(5).replace(/^ /, '');
+            if (dataChars + data.length > exports.MAX_OPENCODE_SSE_FRAME_CHARS) {
+                dropOversizedFrame();
+                return;
+            }
+            dataLines.push(data);
+            dataChars += data.length;
         }
         // `id:` / `event:` / `retry:` are not used by this server; ignored.
     };
@@ -226,6 +440,13 @@ function createSseParser() {
                 buffer = buffer.slice(newlineIndex + 1);
                 newlineIndex = buffer.indexOf('\n');
             }
+            // Nothing above can bound a sender that never sends a newline: the whole
+            // stream stays in `buffer` as one unsplittable line. Drop it and resume at
+            // the next boundary, which is the same treatment an oversized frame gets.
+            if (buffer.length > exports.MAX_OPENCODE_SSE_FRAME_CHARS) {
+                buffer = '';
+                dropOversizedFrame();
+            }
             return completed.splice(0, completed.length);
         },
         flush() {
@@ -233,36 +454,76 @@ function createSseParser() {
                 consumeLine(buffer);
                 buffer = '';
             }
-            finishEvent();
+            if (discarding)
+                discarding = false;
+            else
+                finishEvent();
             return completed.splice(0, completed.length);
         },
+        oversizedFrames() {
+            return oversized;
+        },
     };
 }
 /**
- * Subscribe to one server's event stream.
+ * Subscribe to one server's event stream — connect first, iterate second.
  *
- * Yields parsed frames until the connection ends or `signal` aborts. A frame
- * that is not JSON is skipped rather than ending the stream: a malformed line
- * is a bug in one frame, not a reason to stop watching the session.
+ * The returned generator yields parsed frames until the connection ends or
+ * `signal` aborts. A frame that is not JSON is skipped rather than ending the
+ * stream: a malformed line is a bug in one frame, not a reason to stop watching
+ * the session. Ending is normal and is the caller's cue to reconnect — the
+ * connection dies without a clean EOF when the server goes away (`transfer
+ * closed with outstanding read data remaining`, #1758 §5.7.2).
  *
- * Ending is normal and is the caller's cue to reconnect — the connection dies
- * without a clean EOF when the server goes away (`transfer closed with
- * outstanding read data remaining`, #1758 §5.7.2).
+ * The two halves are split because *when* the subscription became live is a
+ * fact the caller needs and a generator cannot give it (Issue #1900 item 5): a
+ * generator does not issue its `fetch` until somebody pulls the first frame, so
+ * a caller that re-read `GET /permission` before starting to iterate was
+ * re-reading a server it had not subscribed to yet. An approval raised in that
+ * window appeared on neither side and stayed invisible until the next
+ * reconnect. This call resolves once the response headers are in, which is the
+ * instant the server has accepted the subscription — everything raised after it
+ * arrives on the returned stream.
  *
  * @param port - The instance's server
  * @param signal - Aborted by the subscription to close the stream
+ * @returns The frames, from the moment of connection
  */
-async function* readOpencodeEventStream(port, signal) {
-    const response = await fetch(`${opencodeBaseUrl(port)}/event`, {
+async function openOpencodeEventStream(port, signal) {
+    const response = await loopbackFetch(`${opencodeBaseUrl(port)}/event`, {
         signal,
-        headers: { Accept: 'text/event-stream' },
+        headers: { Accept: exports.OPENCODE_EVENT_CONTENT_TYPE },
     });
     if (!response.ok || !response.body) {
         throw new Error(`opencode /event responded ${response.status}`);
     }
-    const reader = response.body.getReader();
+    if (!hasContentType(response, exports.OPENCODE_EVENT_CONTENT_TYPE)) {
+        // Measured: an unknown route answers `200 text/html`, so "the socket
+        // accepted me" is not "the subscription exists". Throwing hands the caller
+        // its ordinary reconnect, which re-checks the identity first.
+        throw new Error(`opencode /event answered ${response.headers?.get?.('content-type') ?? 'no content-type'}`);
+    }
+    return iterateOpencodeFrames(port, response.body.getReader());
+}
+/** Parse an open body into frames until it ends. */
+async function* iterateOpencodeFrames(port, reader) {
     const decoder = new TextDecoder();
     const parser = createSseParser();
+    let reportedOversized = 0;
+    // A silent cap is a cap nobody can act on: the frame is gone either way, and
+    // the count is the only thing that says so.
+    const reportOversized = () => {
+        const dropped = parser.oversizedFrames();
+        if (dropped === reportedOversized)
+            return;
+        logger.warn('opencode-sse-frame-oversized', {
+            port,
+            dropped,
+            newlyDropped: dropped - reportedOversized,
+            limitChars: exports.MAX_OPENCODE_SSE_FRAME_CHARS,
+        });
+        reportedOversized = dropped;
+    };
     try {
         for (;;) {
             const { done, value } = await reader.read();
@@ -274,12 +535,14 @@ async function* readOpencodeEventStream(port, signal) {
                 if (frame)
                     yield frame;
             }
+            reportOversized();
         }
         for (const raw of parser.flush()) {
             const frame = safeParseFrame(raw);
             if (frame)
                 yield frame;
         }
+        reportOversized();
     }
     finally {
         // `cancel` on an already-aborted stream rejects; the connection is going