@ggui-ai/mcp-server 0.7.0 → 0.9.0

package/dist/ggui-session-channel/subscribe.js

@@ -8,6 +8,7 @@
  */
 import { PROTOCOL_SCHEMA_VERSION, UPGRADE_REQUIRED } from "@ggui-ai/protocol";
 import { defaultAppIdFromIdentity, resolveIdentityFromHeaders, UnauthenticatedError, } from "../auth.js";
+import { createWsSink } from "./outbound.js";
 /**
  * Marker `userId` (and `workspaceId`) `resolveIdentityFromUpgrade`
  * returns for a bootstrap-gated upgrade — see the "WS-token gate"
@@ -277,6 +278,24 @@ export function createSubscribeHandlers(deps) {
                 return;
             }
         }
+        // Transport-neutral tail — shared verbatim with the SSE attach
+        // path (`attachExternalSubscriber`). The WS head above resolved
+        // auth + render; the tail owns snapshot → replay → register →
+        // ack → ledger replay → stream replay.
+        await completeSubscribe({
+            stored,
+            identity: effectiveIdentity,
+            sink: createWsSink(ws, deps.logger),
+            transport: "ws",
+            ws,
+            ...(payload.sinceSequence !== undefined ? { sinceSequence: payload.sinceSequence } : {}),
+            ...(payload.fromSeq !== undefined ? { fromSeq: payload.fromSeq } : {}),
+            ...(message.requestId ? { requestId: message.requestId } : {}),
+            ...(mintedSessionToken !== undefined ? { sessionToken: mintedSessionToken } : {}),
+        });
+    }
+    async function completeSubscribe(args) {
+        const { stored, sink } = args;
         // Snapshot the outbound-stream cursor BEFORE registering the
         // subscriber. Any concurrent producer that calls sendToGguiSession
         // between here and registration gets seq > snapshotSeq, so the
@@ -300,8 +319,8 @@ export function createSubscribeHandlers(deps) {
         const activeStreamSpec = activeItem.type !== "mcpApps" && activeItem.type !== "system"
             ? activeItem.streamSpec
             : undefined;
-        const replay = payload.fromSeq !== undefined
-            ? await deps.streamBuffer.replay(stored.id, payload.fromSeq, activeStreamSpec)
+        const replay = args.fromSeq !== undefined
+            ? await deps.streamBuffer.replay(stored.id, args.fromSeq, activeStreamSpec)
             : await deps.streamBuffer.replay(stored.id, 0, undefined);
         // Subscribe to the StreamFanout BEFORE constructing the Subscriber:
         // the seam returns an AsyncIterable whose iterator we hand off; the
@@ -310,29 +329,34 @@ export function createSubscribeHandlers(deps) {
         // point onward queues into our iterator — paired with the
         // replayCompletedSeq cursor below, that's race-free.
         const fanoutIter = deps.streamFanout.subscribe(stored.id)[Symbol.asyncIterator]();
-        const sub = {
-            ws,
+        const base = {
             sessionId: stored.id,
             appId: stored.appId,
-            identity: effectiveIdentity,
+            identity: args.identity,
             connectedAt: Date.now(),
             replayCompletedSeq: snapshotSeq,
             iter: fanoutIter,
             // Per-subscriber channel-subscribe tracker. Populated
             // lazily by the `channel_subscribe` handler when the operator
-            // wired `streamWebSocketLocalTools`; stays empty otherwise.
+            // wired `streamWebSocketLocalTools`; stays empty otherwise
+            // (structurally so for SSE — no inbound channel).
             channelSubs: new Map(),
+            sink,
         };
+        const sub = args.transport === "ws"
+            ? { ...base, transport: "ws", ws: args.ws }
+            : { ...base, transport: "sse" };
         deps.register(sub);
         deps.logger.info("render_channel_subscribed", {
             sessionId: stored.id,
             appId: stored.appId,
-            identityKind: effectiveIdentity.identity.kind,
-            fromSeq: payload.fromSeq,
+            identityKind: args.identity.identity.kind,
+            transport: args.transport,
+            fromSeq: args.fromSeq,
             snapshotSeq,
             replayCount: replay?.envelopes.length ?? 0,
             replayTruncated: replay?.truncated ?? false,
-            bootstrap: mintedSessionToken !== undefined,
+            bootstrap: args.sessionToken !== undefined,
         });
         const ackPayload = {
             sequence: stored.eventSequence,
@@ -346,14 +370,14 @@ export function createSubscribeHandlers(deps) {
             // the handshake ignore the field (legacy-pass-through).
             serverVersion: PROTOCOL_SCHEMA_VERSION,
             ...(replay?.truncated ? { replayTruncated: true } : {}),
-            ...(mintedSessionToken !== undefined ? { sessionToken: mintedSessionToken } : {}),
+            ...(args.sessionToken !== undefined ? { sessionToken: args.sessionToken } : {}),
         };
-        deps.send(ws, {
+        sink.write({
             type: "ack",
             payload: ackPayload,
-            ...(message.requestId ? { requestId: message.requestId } : {}),
+            ...(args.requestId ? { requestId: args.requestId } : {}),
         });
-        // R7 — GguiSessionEvent ledger replay. When `payload.sinceSequence` is
+        // R7 — GguiSessionEvent ledger replay. When `args.sinceSequence` is
         // present, fetch events with `seq > sinceSequence` from the per-
         // render ledger and emit each as a `render_event` wire frame
         // BEFORE the per-channel stream-buffer replay. Consumers dispatch
@@ -361,38 +385,70 @@ export function createSubscribeHandlers(deps) {
         // (render/props_update/etc.) — same cursor model as the HTTP
         // `/api/sessions/:id/events?sinceSequence=N` endpoint.
         //
+        // Each replay frame carries `resumeId` = the ledger seq — the SSE
+        // sink stamps it as the `id:` field so the browser's Last-Event-ID
+        // lands on the exact same cursor space; the WS sink ignores it.
+        //
+        // Pagination: a hasMore-loop over 100-event pages (the HTTP
+        // route's default page size). Strict superset of the previous
+        // single-page-100 WS behavior.
+        //
         // Horizon gate: a cursor below the server's replay horizon OR
         // above `lastSequence` (stale from a different deployment) emits
         // an error frame with `code: 'REPLAY_HORIZON_PASSED'` and skips
-        // the replay. Client recovery: re-mount from a fresh /state read.
-        if (payload.sinceSequence !== undefined) {
-            const sinceSeq = payload.sinceSequence;
+        // the replay. The frame carries `resumeId` = lastSequence — a
+        // dispatched id-bearing frame advances the browser's Last-Event-ID
+        // to the fresh high-water mark, and the ack snapshot already
+        // re-mounted state. Client recovery: re-mount from a fresh /state
+        // read (WS) / the already-delivered ack (SSE).
+        if (args.sinceSequence !== undefined) {
+            const sinceSeq = args.sinceSequence;
             if (sinceSeq < 0 || !Number.isInteger(sinceSeq)) {
-                deps.sendError(ws, "INVALID_SINCE_SEQUENCE", "sinceSequence must be a non-negative integer", message.requestId);
+                sink.write({
+                    type: "error",
+                    payload: {
+                        code: "INVALID_SINCE_SEQUENCE",
+                        message: "sinceSequence must be a non-negative integer",
+                    },
+                    ...(args.requestId ? { requestId: args.requestId } : {}),
+                });
             }
             else {
-                const ledger = await deps.renderStore.listEventsSince(stored.id, sinceSeq, 
-                // Server-side cap matches the HTTP route's default (100).
-                // Stress + replay-from-zero workloads cap here.
-                100);
-                if (ledger === null) {
-                    // GguiSession disappeared between resolve and ledger read —
-                    // already handled by the broader error envelope path; nothing
-                    // to do here.
-                }
-                else if (sinceSeq > ledger.lastSequence || sinceSeq < ledger.horizonSeq) {
-                    deps.sendError(ws, "REPLAY_HORIZON_PASSED", `cursor ${sinceSeq} is outside replayable range [${ledger.horizonSeq}, ${ledger.lastSequence}]`, message.requestId, { currentSequence: ledger.lastSequence });
-                }
-                else {
+                let cursor = sinceSeq;
+                let firstPage = true;
+                for (;;) {
+                    const ledger = await deps.renderStore.listEventsSince(stored.id, cursor, 100);
+                    if (ledger === null) {
+                        // GguiSession disappeared between resolve and ledger read —
+                        // already handled by the broader error envelope path;
+                        // nothing to do here.
+                        break;
+                    }
+                    if (firstPage && (sinceSeq > ledger.lastSequence || sinceSeq < ledger.horizonSeq)) {
+                        sink.write({
+                            type: "error",
+                            payload: {
+                                code: "REPLAY_HORIZON_PASSED",
+                                message: `cursor ${sinceSeq} is outside replayable range [${ledger.horizonSeq}, ${ledger.lastSequence}]`,
+                                details: { currentSequence: ledger.lastSequence },
+                            },
+                            ...(args.requestId ? { requestId: args.requestId } : {}),
+                        }, { resumeId: String(ledger.lastSequence) });
+                        break;
+                    }
+                    firstPage = false;
                     for (const event of ledger.events) {
                         // GguiSessionEvent is now the wire-shape ledger primitive
                         // (Wave 7 of flatten-render-identity, 2026-05-28); no
                         // projection — emit the store's row directly.
-                        deps.send(ws, {
-                            type: "render_event",
-                            payload: event,
-                        });
+                        sink.write({ type: "render_event", payload: event }, { resumeId: String(event.seq) });
+                        cursor = event.seq;
                     }
+                    // Defensive: an empty page with hasMore would loop forever;
+                    // the store contract never produces it, but a broken adapter
+                    // must not spin the server.
+                    if (!ledger.hasMore || ledger.events.length === 0)
+                        break;
                 }
             }
         }
@@ -403,9 +459,14 @@ export function createSubscribeHandlers(deps) {
         // the single source of truth for ordering.
         if (replay) {
             for (const env of replay.envelopes) {
-                deps.send(ws, { type: "data", payload: env });
+                sink.write({ type: "data", payload: env });
             }
         }
+        return {
+            detach: () => {
+                deps.unregister(sub);
+            },
+        };
     }
-    return { resolveIdentityFromUpgrade, handleSubscribe };
+    return { resolveIdentityFromUpgrade, handleSubscribe, completeSubscribe };
 }

package/dist/ggui-session-channel/subscriber-lifecycle.d.ts

@@ -1,26 +1,35 @@
 /**
- * WS subscriber lifecycle for the live channel — registration into the
+ * Subscriber lifecycle for the live channel — registration into the
  * shared subscriber set, the per-subscriber live-tail pump loop, and
  * the symmetric teardown path (`unregister`) that ends the pump,
  * unhooks the StreamFanout subscription, and clears every
  * `channel_subscribe` polling loop the subscriber owned.
  *
+ * Transport-neutral: subscribers write through their `SubscriberSink`,
+ * so WS-attached and SSE-attached subscribers share this module
+ * unchanged. Only the ws→subscriber reverse index is WS-specific —
+ * it is populated for `transport: 'ws'` rows only, because it exists
+ * for the inbound socket-router dispatch SSE does not have.
+ *
  * Owns the per-render subscriber counter that drives the
  * `onFirstSubscriber` / `onLastSubscriberGone` 0↔1 transition hooks —
- * no other module reads it.
+ * no other module reads it. The hooks fire for SSE attaches too:
+ * hosted cross-pod pubsub scoping keys on "does this pod hold any
+ * subscriber for this render", regardless of transport.
  */
-import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
 import type { WebSocket } from "ws";
 import type { Logger } from "../logger.js";
-import type { Subscriber } from "./internal-types.js";
+import type { Subscriber, WsSubscriber } from "./internal-types.js";
 export interface SubscriberLifecycleDeps {
     readonly logger: Logger;
-    /** Flat set of all live WS subscribers — membership owned HERE. */
+    /** Flat set of all live subscribers (WS + SSE) — membership owned HERE. */
     readonly wsSubscribers: Set<Subscriber>;
-    /** ws → subscriber reverse index so socket-close can look up cheaply. */
-    readonly subscribersByWs: WeakMap<WebSocket, Subscriber>;
-    /** Low-level wire write from the outbound module. */
-    readonly send: (ws: WebSocket, msg: WebSocketMessage) => void;
+    /**
+     * ws → subscriber reverse index so socket-close / inbound dispatch
+     * can look up cheaply. WS-only by construction: populated for
+     * `transport: 'ws'` subscribers only.
+     */
+    readonly subscribersByWs: WeakMap<WebSocket, WsSubscriber>;
     /** 0→1 transition hook — see `GguiSessionChannelOptions.onFirstSubscriber`. */
     readonly onFirstSubscriber?: (sessionId: string) => void;
     /** 1→0 transition hook — see `GguiSessionChannelOptions.onLastSubscriberGone`. */
@@ -30,11 +39,12 @@ export interface SubscriberLifecycle {
     /** Add a subscriber to the live set and start its pump loop. */
     register(sub: Subscriber): void;
     /**
-     * Tear down the subscriber bound to `ws` (if any): remove from the
-     * live set, end the fanout iterator (terminates the pump), clear
-     * every channel-subscribe polling timer. Idempotent.
+     * Tear down `sub` (if still registered): remove from the live set,
+     * end the fanout iterator (terminates the pump), clear every
+     * channel-subscribe polling timer. Idempotent — a second call for
+     * the same subscriber is a no-op.
      */
-    unregister(ws: WebSocket): void;
+    unregister(sub: Subscriber): void;
 }
 export declare function createSubscriberLifecycle(deps: SubscriberLifecycleDeps): SubscriberLifecycle;
 //# sourceMappingURL=subscriber-lifecycle.d.ts.map

package/dist/ggui-session-channel/subscriber-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriber-lifecycle.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/subscriber-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACzD,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC9D,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CA4G5F"}
+{"version":3,"file":"subscriber-lifecycle.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/subscriber-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;CACnC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CAiH5F"}

package/dist/ggui-session-channel/subscriber-lifecycle.js

@@ -1,13 +1,21 @@
 /**
- * WS subscriber lifecycle for the live channel — registration into the
+ * Subscriber lifecycle for the live channel — registration into the
  * shared subscriber set, the per-subscriber live-tail pump loop, and
  * the symmetric teardown path (`unregister`) that ends the pump,
  * unhooks the StreamFanout subscription, and clears every
  * `channel_subscribe` polling loop the subscriber owned.
  *
+ * Transport-neutral: subscribers write through their `SubscriberSink`,
+ * so WS-attached and SSE-attached subscribers share this module
+ * unchanged. Only the ws→subscriber reverse index is WS-specific —
+ * it is populated for `transport: 'ws'` rows only, because it exists
+ * for the inbound socket-router dispatch SSE does not have.
+ *
  * Owns the per-render subscriber counter that drives the
  * `onFirstSubscriber` / `onLastSubscriberGone` 0↔1 transition hooks —
- * no other module reads it.
+ * no other module reads it. The hooks fire for SSE attaches too:
+ * hosted cross-pod pubsub scoping keys on "does this pod hold any
+ * subscriber for this render", regardless of transport.
  */
 export function createSubscriberLifecycle(deps) {
     /**
@@ -21,7 +29,7 @@ export function createSubscriberLifecycle(deps) {
     const renderCountById = new Map();
     /**
      * Pump live frames from the StreamFanout iterator out to this
-     * subscriber's WS. Started fire-and-forget by `register`; ends when
+     * subscriber's sink. Started fire-and-forget by `register`; ends when
      * the iterator yields done (close() on the seam) OR `unregister`
      * calls `iter.return()`. Per-subscriber seq filter applied here:
      * frames with `seq <= replayCompletedSeq` were (or will be)
@@ -42,11 +50,11 @@ export function createSubscriberLifecycle(deps) {
                     return;
                 if (value.seq <= sub.replayCompletedSeq)
                     continue;
-                if (sub.ws.readyState !== sub.ws.OPEN) {
+                if (!sub.sink.isOpen()) {
                     await sub.iter.return?.();
                     return;
                 }
-                deps.send(sub.ws, { type: "data", payload: value });
+                sub.sink.write({ type: "data", payload: value });
             }
         }
         catch (err) {
@@ -58,7 +66,9 @@ export function createSubscriberLifecycle(deps) {
     }
     function register(sub) {
         deps.wsSubscribers.add(sub);
-        deps.subscribersByWs.set(sub.ws, sub);
+        if (sub.transport === "ws") {
+            deps.subscribersByWs.set(sub.ws, sub);
+        }
         // Per-render count bookkeeping + 0→1 hook for cloud pubsub
         // adapter scoping. Increment FIRST so the hook sees the up-to-date
         // state; hook fires only on the transition (prevCount === 0).
@@ -70,7 +80,7 @@ export function createSubscriberLifecycle(deps) {
             }
             catch (err) {
                 // Best-effort: a thrown hook MUST NOT corrupt the
-                // wsSubscribers set vs the real socket lifecycle.
+                // wsSubscribers set vs the real transport lifecycle.
                 deps.logger.warn("render_channel_on_first_subscriber_threw", {
                     sessionId: sub.sessionId,
                     error: String(err),
@@ -81,12 +91,15 @@ export function createSubscriberLifecycle(deps) {
         // inside pumpSubscriber, never propagated.
         void pumpSubscriber(sub);
     }
-    function unregister(ws) {
-        const sub = deps.subscribersByWs.get(ws);
-        if (!sub)
+    function unregister(sub) {
+        // Idempotency gate: membership in the live set is the single
+        // "still registered" signal, shared across transports.
+        if (!deps.wsSubscribers.has(sub))
             return;
-        deps.subscribersByWs.delete(ws);
         deps.wsSubscribers.delete(sub);
+        if (sub.transport === "ws") {
+            deps.subscribersByWs.delete(sub.ws);
+        }
         // Per-render count bookkeeping + 1→0 hook (symmetric with register).
         const prevCount = renderCountById.get(sub.sessionId) ?? 0;
         if (prevCount <= 1) {

package/dist/ggui-session-channel.d.ts

@@ -20,11 +20,13 @@
  *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
  *     through `assertStreamContract` before delivery.
  *
- * `props_update`: the agent-driven `ggui_update` handler calls
- * `channel.sendPropsUpdate(sessionId, props)` (wired as its
- * `propsUpdateNotifier`) to fan a `{type:'props_update'}` frame to
- * live subscribers. Reaches the renderer's existing `props_update`
- * branch in `iframe-runtime` and applies new props in-place.
+ * `props_update`: the agent-driven `ggui_update` / `ggui_amend`
+ * handlers call `channel.sendPropsUpdate(sessionId, props, epoch)`
+ * (wired as their `propsUpdateNotifier`) to fan a
+ * `{type:'props_update'}` frame to live subscribers. Reaches the
+ * renderer's `props_update` branch in `iframe-runtime`, which applies
+ * new props in-place — or freezes the mount when the frame's `epoch`
+ * exceeds its own (#483 freeze latch).
  *
  * Not handled here:
  *
@@ -56,6 +58,7 @@ import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
 import type { IncomingMessage } from "node:http";
 import type { Duplex } from "node:stream";
 import { type GguiSessionChannelLocalToolsOptions } from "./ggui-session-channel/channel-subscriptions.js";
+import type { SubscriberSink } from "./ggui-session-channel/internal-types.js";
 import { type GguiSessionChannelBootstrap, type GguiSessionChannelCookieAuth } from "./ggui-session-channel/subscribe.js";
 import type { Logger } from "./logger.js";
 /** Default URL path for the channel endpoint. Operators can override. */
@@ -110,6 +113,17 @@ export declare const DEFAULT_PRE_SUBSCRIBE_IDLE_MS = 30000;
 export declare const DEFAULT_MAX_PRE_SUBSCRIBE_CONNECTIONS = 1024;
 export type { GguiSessionChannelLocalToolsOptions } from "./ggui-session-channel/channel-subscriptions.js";
 export type { GguiSessionChannelBootstrap, GguiSessionChannelBootstrapRefreshResult, GguiSessionChannelBootstrapVerifyResult, GguiSessionChannelCookieAuth, } from "./ggui-session-channel/subscribe.js";
+export type { SubscriberSink } from "./ggui-session-channel/internal-types.js";
+/**
+ * Thrown by {@link GguiSessionChannelServer.attachExternalSubscriber}
+ * when the target render does not exist OR is bound to a different
+ * app than the caller claims. Callers that pre-gated (the SSE route
+ * does) treat this as a lost race with eviction; callers that did not
+ * MUST map it to their 404 surface.
+ */
+export declare class ChannelSessionNotFoundError extends Error {
+    constructor(sessionId: string);
+}
 export interface GguiSessionChannelOptions {
     /** Required — the render backing store (typically `InMemoryGguiSessionStore`). */
     readonly renderStore: GguiSessionStore;
@@ -432,11 +446,13 @@ export interface GguiSessionChannelServer {
      */
     notifyGguiSessionCommit(sessionId: string, render: GguiSession, matchType?: string): void;
     /**
-     * Fan a `{type:'props_update', payload:{sessionId, props}}` wire frame
-     * to every subscriber currently bound to `sessionId`. The agent-driven
-     * `ggui_update` handler calls this (wired as its `propsUpdateNotifier`)
-     * so a props patch replaces renderer props in-place on live
-     * subscribers without waiting for a resubscribe.
+     * Fan a `{type:'props_update', payload:{sessionId, props, epoch}}`
+     * wire frame to every subscriber currently bound to `sessionId`.
+     * Both mutation handlers call this (wired as their
+     * `propsUpdateNotifier`): `ggui_amend` fans the unchanged head
+     * epoch so the live mount repaints in place, `ggui_update` fans its
+     * freshly-advanced epoch so superseded mounts freeze (#483 latch)
+     * — no waiting for a resubscribe either way.
      *
      * Validation posture (mirrors `notifyGguiSessionCommit`'s "best-effort orphan
      * no-op"):
@@ -464,7 +480,7 @@ export interface GguiSessionChannelServer {
      * `render.propsSpec` before applying — defense-in-depth at the
      * receiving boundary.
      */
-    sendPropsUpdate(sessionId: string, props: JsonObject): Promise<void>;
+    sendPropsUpdate(sessionId: string, props: JsonObject, epoch: number): Promise<void>;
     /**
      * Fan a `{type:'drain_ack', payload:{sessionId, appId,
      * eventId, drainedAt}}` wire frame to every subscriber currently
@@ -508,6 +524,37 @@ export interface GguiSessionChannelServer {
      * subscriber send failures are logged but never propagated.
      */
     externalBroadcast(sessionId: string, frame: WebSocketMessage): void;
+    /**
+     * Register an externally-transported (non-WS) subscriber into the
+     * SAME fan-out planes WS subscribers ride: the StreamFanout live
+     * tail, the direct walks (`props_update` / `render` / `drain_ack` /
+     * external broadcasts), and the subscribe tail's ack → ledger-replay
+     * → stream-replay ordering. The single consumer today is the SSE
+     * route (`GET /api/sessions/:sessionId/stream`).
+     *
+     * The caller owns transport-level auth (the SSE route clones the
+     * /state wsToken gate) — this method only re-checks render existence
+     * + appId binding as defense-in-depth, throwing
+     * {@link ChannelSessionNotFoundError} on mismatch.
+     *
+     * `sinceSequence` replays the GguiSessionEvent ledger as
+     * `render_event` frames (each written with `resumeId` = ledger seq —
+     * the SSE sink stamps it as the `id:` field); `fromSeq` replays the
+     * stream buffer as `data` frames. Returns `detach` — idempotent
+     * teardown that unregisters the subscriber, ends its pump, and fires
+     * the 1→0 subscriber hook when applicable. The caller MUST invoke it
+     * on transport close.
+     */
+    attachExternalSubscriber(args: {
+        readonly sessionId: string;
+        readonly appId: string;
+        readonly identity: AuthResult;
+        readonly sink: SubscriberSink;
+        readonly sinceSequence?: number;
+        readonly fromSeq?: number;
+    }): Promise<{
+        readonly detach: () => void;
+    }>;
     /** Number of live subscribers. Useful for health / debug introspection. */
     readonly subscriberCount: number;
     /** Number of distinct renders with at least one subscriber. */

package/dist/ggui-session-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ggui-session-channel.d.ts","sourceRoot":"","sources":["../src/ggui-session-channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ggui-session-channel.d.ts","sourceRoot":"","sources":["../src/ggui-session-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACd,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C,OAAO,EAEL,KAAK,mCAAmC,EACzC,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAEV,cAAc,EAGf,MAAM,0CAA0C,CAAC;AAGlD,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EAClC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B,UAAY,CAAC;AACtD;;;;;;GAMG;AACH,eAAO,MAAM,uCAAuC,QAAS,CAAC;AAC9D;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,OAAQ,CAAC;AAK3D,YAAY,EAAE,mCAAmC,EAAE,MAAM,iDAAiD,CAAC;AAK3G,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,uCAAuC,EACvC,4BAA4B,GAC7B,MAAM,qCAAqC,CAAC;AAM7C,YAAY,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE/E;;;;;;GAMG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,SAAS,EAAE,MAAM;CAI9B;AAED,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC5D,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;IAChD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,2BAA2B,CAAC;IAEjD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,4BAA4B,CAAC;IACnD;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACjF;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,mCAAmC,CAAC;IACzE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC/C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IAC9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;;;OAQG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IAC7C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD;;;;;;;OAOG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,iBAAiB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,IAAI,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,GAAG,IAAI,CAAC;IACT;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,wBAAwB,CAAC,IAAI,EAAE;QAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;QAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAC;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,sBAAsB,EAAE;QAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,yBAAyB,GAC9B,wBAAwB,CAmQ1B"}

package/dist/ggui-session-channel.js

@@ -20,11 +20,13 @@
  *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
  *     through `assertStreamContract` before delivery.
  *
- * `props_update`: the agent-driven `ggui_update` handler calls
- * `channel.sendPropsUpdate(sessionId, props)` (wired as its
- * `propsUpdateNotifier`) to fan a `{type:'props_update'}` frame to
- * live subscribers. Reaches the renderer's existing `props_update`
- * branch in `iframe-runtime` and applies new props in-place.
+ * `props_update`: the agent-driven `ggui_update` / `ggui_amend`
+ * handlers call `channel.sendPropsUpdate(sessionId, props, epoch)`
+ * (wired as their `propsUpdateNotifier`) to fan a
+ * `{type:'props_update'}` frame to live subscribers. Reaches the
+ * renderer's `props_update` branch in `iframe-runtime`, which applies
+ * new props in-place — or freezes the mount when the frame's `epoch`
+ * exceeds its own (#483 freeze latch).
  *
  * Not handled here:
  *
@@ -109,6 +111,19 @@ export const DEFAULT_PRE_SUBSCRIBE_IDLE_MS = 30_000;
  * Disable with `0`.
  */
 export const DEFAULT_MAX_PRE_SUBSCRIBE_CONNECTIONS = 1_024;
+/**
+ * Thrown by {@link GguiSessionChannelServer.attachExternalSubscriber}
+ * when the target render does not exist OR is bound to a different
+ * app than the caller claims. Callers that pre-gated (the SSE route
+ * does) treat this as a lost race with eviction; callers that did not
+ * MUST map it to their 404 surface.
+ */
+export class ChannelSessionNotFoundError extends Error {
+    constructor(sessionId) {
+        super(`GguiSession '${sessionId}' not found (or bound to a different app)`);
+        this.name = "ChannelSessionNotFoundError";
+    }
+}
 /**
  * Build an OSS live-channel server. The returned object is designed to be
  * composed into `createGguiServer` — see `server.ts` for the wire-up.
@@ -141,13 +156,18 @@ export function createGguiSessionChannelServer(opts) {
         ? new WebSocketServer({ noServer: true, maxPayload: wsMaxPayloadBytes })
         : new WebSocketServer({ noServer: true });
     /**
-     * Flat set of all live WS subscribers. Replaces the per-render
-     * `subscribersByRender` Map — routing is now StreamFanout's job;
-     * this set tracks WS-specific bookkeeping (stats, shutdown-broadcast)
-     * that the seam can't see (and shouldn't).
+     * Flat set of all live subscribers — WS-attached AND externally-
+     * attached (SSE). Replaces the per-render `subscribersByRender` Map —
+     * routing is now StreamFanout's job; this set tracks channel-level
+     * bookkeeping (stats, shutdown-broadcast) that the seam can't see
+     * (and shouldn't).
      */
     const wsSubscribers = new Set();
-    /** ws → subscriber reverse index so socket-close can look up cheaply. */
+    /**
+     * ws → subscriber reverse index so socket-close / inbound dispatch
+     * can look up cheaply. WS-only: the lifecycle module populates it
+     * for `transport: 'ws'` subscribers only.
+     */
     const subscribersByWs = new WeakMap();
     // Send / fan-out family — wire-write primitives shared by every
     // handler module plus the public fan-out surfaces the returned
@@ -169,7 +189,6 @@ export function createGguiSessionChannelServer(opts) {
         logger: opts.logger,
         wsSubscribers,
         subscribersByWs,
-        send,
         onFirstSubscriber: opts.onFirstSubscriber,
         onLastSubscriberGone: opts.onLastSubscriberGone,
     });
@@ -197,7 +216,7 @@ export function createGguiSessionChannelServer(opts) {
     // Subscribe / credential-path family — upgrade-time identity
     // resolution (bearer / bootstrap / console cookie) + the
     // `subscribe` handler. See `ggui-session-channel/subscribe.ts`.
-    const { resolveIdentityFromUpgrade, handleSubscribe } = createSubscribeHandlers({
+    const { resolveIdentityFromUpgrade, handleSubscribe, completeSubscribe } = createSubscribeHandlers({
         logger: opts.logger,
         auth: opts.auth,
         renderStore: opts.renderStore,
@@ -207,9 +226,9 @@ export function createGguiSessionChannelServer(opts) {
         cookieAuth: opts.cookieAuth,
         appIdFromIdentity: opts.appIdFromIdentity,
         versionPolicy: opts.versionPolicy,
-        send,
         sendError,
         register,
+        unregister,
     });
     // WS lifecycle / message routing — the `connection` handler with
     // the per-socket inbound ordering chain, pre-subscribe identity +
@@ -272,6 +291,24 @@ export function createGguiSessionChannelServer(opts) {
         sendPropsUpdate: outbound.sendPropsUpdate,
         sendDrainAck: outbound.sendDrainAck,
         externalBroadcast: outbound.externalBroadcast,
+        async attachExternalSubscriber(args) {
+            // Defense-in-depth re-check — the transport route already gated
+            // on the wsToken's (sessionId, appId) claims, but this method is
+            // a public surface: never register a subscriber onto a render
+            // that no longer exists or belongs to a different app.
+            const stored = await opts.renderStore.get(args.sessionId);
+            if (!stored || stored.appId !== args.appId) {
+                throw new ChannelSessionNotFoundError(args.sessionId);
+            }
+            return completeSubscribe({
+                stored,
+                identity: args.identity,
+                sink: args.sink,
+                transport: "sse",
+                ...(args.sinceSequence !== undefined ? { sinceSequence: args.sinceSequence } : {}),
+                ...(args.fromSeq !== undefined ? { fromSeq: args.fromSeq } : {}),
+            });
+        },
         get subscriberCount() {
             return wsSubscribers.size;
         },
@@ -312,12 +349,11 @@ export function createGguiSessionChannelServer(opts) {
             const sessionIds = new Set();
             for (const sub of wsSubscribers) {
                 sessionIds.add(sub.sessionId);
-                try {
-                    sub.ws.close(1012, "service_restart");
-                }
-                catch {
-                    /* best-effort */
-                }
+                // Transport-neutral shutdown: WS maps to close(1012), SSE ends
+                // the response so EventSource auto-reconnects to the new pod —
+                // exactly the 1012 semantics. `sink.end` is best-effort by
+                // contract (never throws on an already-closing transport).
+                sub.sink.end("service_restart");
                 void sub.iter.return?.();
             }
             wsSubscribers.clear();