commandmate 0.29.2 → 0.30.1

package/dist/server/src/lib/realtime/publisher-registry.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Process-local registry naming the one module instance that owns live
+ * WebSocket rooms (Issue #2220).
+ *
+ * ## The failure this exists to close
+ *
+ * `ws-server` keeps `wss`, `clients` and `rooms` in its module scope, and only
+ * the instance the custom server called `setupWebSocket()` on ever holds a
+ * socket. That was believed to be a `next dev` nicety; it is not. A production
+ * build has two graphs, and the build artifacts say so:
+ *
+ * ```
+ * dist/server/server.js          -> require("./src/lib/ws-server")   // owner
+ * .next/server/app/api/**\/route.js -> .next/server/chunks/<n>.js      // a second copy
+ * ```
+ *
+ * `setupWebSocket` appears in the `.next` chunk only as an exported binding —
+ * grep it and the sole hit is the export map, never a call. So the route
+ * bundle's `rooms` is empty for the life of the process, and every
+ * `broadcast()` reached from a route handler returned in silence.
+ *
+ * ## What is shared and what is not
+ *
+ * Only the *capability* crosses the boundary: four functions the owner hands
+ * over. `wss`, the socket set, `clients` and `rooms` stay inside the owner's
+ * module scope, so a route bundle can ask for a frame to be published but can
+ * neither enumerate nor mutate the connection state. Putting the maps
+ * themselves on `globalThis` would work — same process, same `globalThis` — but
+ * it exposes the central state to every bundle and leaves ownership undefined
+ * once two instances have both initialised.
+ *
+ * This is the shape #1788 already uses for the waiting edge
+ * (`waiting-episode-state`'s `globalThis` listener set, written by
+ * `ws-server`'s `setupWebSocket`), and it is measurably cross-bundle in the same
+ * build: `__sessionWaitingTransitionListeners` appears in both `dist/server` and
+ * the `.next` chunks.
+ *
+ * ## Ownership
+ *
+ * Registration is a generation counter that only ever moves forward, and
+ * withdrawal is authorised by the token handed out at registration. A stale
+ * instance calling `closeWebSocket()` after a newer one has taken over
+ * therefore cannot silence the live server — the classic HMR / re-entered
+ * `setupWebSocket` hazard.
+ *
+ * ## Import discipline
+ *
+ * This module must stay a leaf: it imports the logger and nothing else. Both
+ * `ws-server` and every producer reach it, so an edge back into either would
+ * rebuild the module-scope cycle `tests/unit/guards/no-ws-server-manager-cycle-1984.test.ts`
+ * exists to forbid.
+ *
+ * @module lib/realtime/publisher-registry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNROUTED_PUBLISH_WARN_INTERVAL_MS = void 0;
+exports.registerRoomPublisher = registerRoomPublisher;
+exports.unregisterRoomPublisher = unregisterRoomPublisher;
+exports.getRoomPublisher = getRoomPublisher;
+exports.getRoomPublisherGeneration = getRoomPublisherGeneration;
+exports.recordUnroutedPublish = recordUnroutedPublish;
+exports.getUnroutedPublishStats = getUnroutedPublishStats;
+exports.__resetRoomPublisherRegistryForTest = __resetRoomPublisherRegistryForTest;
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('publisher-registry');
+/** At most one warning per minute; the rest are counted, not printed. */
+exports.UNROUTED_PUBLISH_WARN_INTERVAL_MS = 60_000;
+function unroutedState() {
+    return (globalThis.__realtimeUnroutedPublish ??= {
+        total: 0,
+        suppressed: 0,
+        lastWarnedAt: null,
+        operations: {},
+    });
+}
+/**
+ * Claim ownership of the process's rooms.
+ *
+ * Called from `setupWebSocket()` and nowhere else. A second call supersedes the
+ * first rather than being rejected: re-entering `setupWebSocket` builds a new
+ * `WebSocketServer`, and the newest one is the one holding sockets.
+ *
+ * @param publisher - The owner's implementation, closed over its own maps.
+ * @returns A handle whose `unregister()` is honoured only while it is current.
+ */
+function registerRoomPublisher(publisher) {
+    const token = (globalThis.__realtimeRoomPublisherGeneration ?? 0) + 1;
+    globalThis.__realtimeRoomPublisherGeneration = token;
+    globalThis.__realtimeRoomPublisher = { generation: token, publisher };
+    // A live owner means the frames counted below are no longer being dropped;
+    // carrying the old totals forward would keep warning about a fixed process.
+    globalThis.__realtimeUnroutedPublish = undefined;
+    return {
+        token,
+        unregister: () => unregisterRoomPublisher(token),
+    };
+}
+/**
+ * Withdraw the registration identified by `token`.
+ *
+ * A token that is not the current generation is ignored. That is the whole
+ * point: under HMR — or in a suite that stands two servers up — the instance
+ * being torn down is frequently *not* the one that owns the live sockets, and
+ * its `closeWebSocket()` must not take the running server's publisher with it.
+ *
+ * @returns Whether this call actually cleared the registration.
+ */
+function unregisterRoomPublisher(token) {
+    const current = globalThis.__realtimeRoomPublisher;
+    if (!current || current.generation !== token)
+        return false;
+    globalThis.__realtimeRoomPublisher = undefined;
+    return true;
+}
+/** The owner's publisher, or null when no instance has claimed the rooms. */
+function getRoomPublisher() {
+    return globalThis.__realtimeRoomPublisher?.publisher ?? null;
+}
+/** Generation of the current registration; 0 when there is none. */
+function getRoomPublisherGeneration() {
+    return globalThis.__realtimeRoomPublisher?.generation ?? 0;
+}
+/**
+ * Note that a publish found no owner, warning at most once a minute.
+ *
+ * Without this the failure has no symptom at all. The room lookup returns
+ * `undefined`, the function returns, and the browser still shows the socket as
+ * `connected` — because it is: the socket is healthy and only the server-side
+ * publisher is missing. That is the state #2220 sat in unnoticed. The counters
+ * are readable through {@link getUnroutedPublishStats} so a test can assert the
+ * signal exists rather than trusting a log line.
+ *
+ * @param operation - The surface that lost the frame, e.g. `'broadcast'`.
+ * @param worktreeId - Room the frame was addressed to.
+ */
+function recordUnroutedPublish(operation, worktreeId, now = Date.now()) {
+    const state = unroutedState();
+    state.total += 1;
+    state.operations[operation] = (state.operations[operation] ?? 0) + 1;
+    if (state.lastWarnedAt !== null && now - state.lastWarnedAt < exports.UNROUTED_PUBLISH_WARN_INTERVAL_MS) {
+        state.suppressed += 1;
+        return;
+    }
+    const suppressed = state.suppressed;
+    state.suppressed = 0;
+    state.lastWarnedAt = now;
+    logger.warn('realtime:no-room-publisher', {
+        operation,
+        worktreeId,
+        total: state.total,
+        suppressedSinceLastWarning: suppressed,
+        operations: { ...state.operations },
+    });
+}
+/** Read-only view of the unrouted-publish counters. */
+function getUnroutedPublishStats() {
+    const state = unroutedState();
+    return { ...state, operations: { ...state.operations } };
+}
+/**
+ * Drop the registration and the counters.
+ *
+ * Test seam. The generation counter is deliberately NOT reset — a suite that
+ * reset it could hand two different registrations the same token and stop
+ * exercising the ownership rule this module is built around.
+ */
+function __resetRoomPublisherRegistryForTest() {
+    globalThis.__realtimeRoomPublisher = undefined;
+    globalThis.__realtimeUnroutedPublish = undefined;
+}

package/dist/server/src/lib/realtime/terminal-broadcast.js

@@ -23,7 +23,8 @@ const logger_1 = require("../../lib/logger");
 const manager_1 = require("../../lib/cli-tools/manager");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
 const logger = (0, logger_1.createLogger)('terminal-broadcast');
-const versionCounters = new Map();
+const versionCounters = globalThis.__terminalSnapshotVersions ??
+    (globalThis.__terminalSnapshotVersions = new Map());
 exports.INTERACTION_SNAPSHOT_RETRY_DELAYS_MS = [100, 250, 500, 750];
 function nextVersion(key) {
     const version = (versionCounters.get(key) ?? 0) + 1;
@@ -54,6 +55,12 @@ function snapshotFingerprint(payload) {
     return JSON.stringify([
         payload.fullOutput ?? '',
         payload.isRunning,
+        // Issue #2240: part of the frame since the snapshot started carrying it, so
+        // a redraw whose only change is the verdict (`waiting` -> `running` on an
+        // answered dialog, say) is still published. Leaving it out would put the
+        // field back in the position this issue took it out of — present on the
+        // wire, but not deliverable by the path that actually feeds a live turn.
+        payload.sessionStatus,
         payload.thinking ?? false,
         payload.isPromptWaiting ?? false,
         payload.isSelectionListActive ?? false,
@@ -76,6 +83,12 @@ function emitTerminalSnapshot(worktreeId, cliToolId, payload, instanceId) {
         instanceId: resolvedInstanceId,
         output: payload.fullOutput ?? '',
         isRunning: payload.isRunning,
+        // Issue #2240: straight through, so push and poll answer the same question
+        // with the same value. `/current-output` returns this very payload, so the
+        // two paths differ only in transport. Not `?? something` — the builder
+        // types it as a required `string` and publishes `'idle'` for a session that
+        // is not running, so there is no absent case to invent a default for.
+        sessionStatus: payload.sessionStatus,
         thinking: payload.thinking ?? false,
         isPromptWaiting: payload.isPromptWaiting ?? false,
         promptData: payload.promptData ?? null,

package/dist/server/src/lib/realtime/types.js

@@ -9,8 +9,9 @@
  * the canonical {@link RealtimeEvent}.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
+exports.MESSAGES_INVALIDATED_EVENT_TYPE = exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH = exports.CHAT_TURN_PROGRESS_MIN_INTERVAL_MS = exports.CHAT_TURN_PROGRESS_EVENT_TYPE = exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
 exports.isVersionMismatch = isVersionMismatch;
+exports.truncateChatTurnProgressBody = truncateChatTurnProgressBody;
 exports.parseRealtimeEvent = parseRealtimeEvent;
 /**
  * Client → server hello carrying the client bundle version, sent on every
@@ -38,6 +39,100 @@ function isVersionMismatch(serverVersion, clientVersion) {
         return false;
     return serverVersion !== clientVersion;
 }
+/**
+ * The body of the turn that is being generated **right now** (Issue #2199).
+ *
+ * The chat surface has no partial assistant text of its own: a reply reaches
+ * `chat_messages` only once the turn is over, so a long turn leaves the surface
+ * saying "Responding…" for minutes while the terminal surface next to it is
+ * filling up. This frame is that missing text, and everything about its shape
+ * follows from one decision — **it is never persisted**.
+ *
+ * Not persisted means the row this becomes is written by somebody else: the
+ * existing `message` broadcast, from `sources/<tool>/history`, whose `requestId`
+ * is exactly {@link ChatTurnProgressEvent.turnKey}. So a client replaces the
+ * progress body with the confirmed row by matching that one string, and a
+ * missed frame costs a moment of staleness rather than a lost reply. It is also
+ * why there is no replay on reconnect and no `done: true` member: the settled
+ * state of a turn is a `chat_messages` row, and this event has nothing to say
+ * about it.
+ *
+ * `version` is monotonic per (worktreeId, cliToolId, instanceId) — the same
+ * discipline {@link TerminalSnapshotEvent} carries, and for a sharper reason
+ * here: opencode's SSE re-sends its boundary frames, so a client that trusted
+ * arrival order would redraw an older body over a newer one.
+ */
+exports.CHAT_TURN_PROGRESS_EVENT_TYPE = 'chat_turn_progress';
+/**
+ * Smallest gap between two progress frames for one instance.
+ *
+ * The producers are a 2 s poller tick (claude) and an SSE part stream that
+ * measured 88 delta frames for a single 967-character paragraph (opencode), so
+ * the second one needs a brake and the first one does not. One brake for both,
+ * because the expensive half of the claude path — a 4 MiB tail read and a parse
+ * — happens *behind* this gate too, and a surface polled over HTTP at ~1 s
+ * would otherwise pay for it on every request.
+ */
+exports.CHAT_TURN_PROGRESS_MIN_INTERVAL_MS = 1000;
+/**
+ * Longest body one progress frame carries, in UTF-16 code units.
+ *
+ * Two orders of magnitude below `MAX_CLAUDE_TURN_BODY_LENGTH` /
+ * `MAX_OPENCODE_TURN_BODY_LENGTH`, which bound the body that gets *saved*. This
+ * one is re-sent every second while a turn runs, so its cost is per frame
+ * rather than per turn.
+ */
+exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH = 64 * 1024;
+/**
+ * Cut an over-long progress body, **keeping the tail**.
+ *
+ * The head is what goes, and that is the opposite of what the two turn writers
+ * do. They are recording a reply and the reply reads from the top; this is
+ * showing a reply being written, and the interesting end is the one the model
+ * is still adding to. A reader who needs the head has the terminal surface and,
+ * a moment later, the settled row.
+ *
+ * The cut is reported rather than hidden — see `partial` on
+ * {@link ChatTurnProgressEvent}. Silently showing the middle of a reply as if it
+ * were the whole of one is the failure this signature exists to prevent.
+ */
+function truncateChatTurnProgressBody(body, maxLength = exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH) {
+    if (maxLength <= 0)
+        return { body: '', truncated: body.length > 0 };
+    if (body.length <= maxLength)
+        return { body, truncated: false };
+    return { body: body.slice(body.length - maxLength), truncated: true };
+}
+/**
+ * "This instance's history changed in a way no row-level frame can express —
+ * re-read it" (Issue #2219).
+ *
+ * The one mutation that has no row to publish is a **delete**:
+ * `sendUserMessage` removes the previous, identical user row after the retry is
+ * persisted (#379's duplicate guard), and `message` / `message_updated` can only
+ * ever say "this row now looks like this". A second device therefore kept the
+ * deleted row until its own poll came round — 15s while a socket is up, since
+ * #2195 demoted that poll to a fallback — showing the same sentence twice.
+ *
+ * It carries a **scope, not a payload**, and that is the whole design:
+ *
+ *  - the receiver re-fetches, so it lands on the DB's settled state rather than
+ *    on a diff it has to merge — a `message` frame that was dropped on the way
+ *    is repaired by the same round trip;
+ *  - the re-fetch bumps `useSplitMessages`' request id, which retires any fetch
+ *    that started *before* the delete and would otherwise resolve with the row
+ *    still in it;
+ *  - no tombstone has to be kept anywhere, and `archived` — which means "a
+ *    previous session's history" — keeps meaning only that.
+ *
+ * The cost is one extra GET per orphan cleanup, on an event that fires only when
+ * someone re-sends the exact text of their last unanswered message.
+ *
+ * {@link instanceId} is always resolved (`instanceId ?? cliToolId`), like
+ * {@link TerminalSnapshotEvent}'s: a client matches it against its own pane and
+ * an omitted field would simply never match.
+ */
+exports.MESSAGES_INVALIDATED_EVENT_TYPE = 'messages_invalidated';
 /**
  * Parse a raw WebSocket frame into the inner realtime event.
  *