@ggui-ai/mcp-server 0.8.0 → 0.10.0

package/dist/api-renders-routes.d.ts

@@ -64,6 +64,27 @@ interface MountOptions {
     readonly codeStore?: CodeStore;
     /** Operator-configured public origin for absolute URL composition. */
     readonly publicBaseUrl?: string;
+    /**
+     * Origin the content-addressable routes (`/code/*`, `/contract/*`)
+     * are reached at — an edge-cached asset host when the deployment
+     * fronts static paths separately (ggui#522). Defaults to
+     * {@link publicBaseUrl}, then the request host. Session-API URLs
+     * (`/events`, `/stream`) never use it: those are dynamic and stay on
+     * the public origin.
+     */
+    readonly codeBaseUrl?: string;
+    /**
+     * Strict-CSP module-variant minter (ggui#522 slice 2) — the /state
+     * read re-mints the `codeModuleUrl` twin alongside `codeUrl`. Only
+     * consulted when an explicit {@link codeBaseUrl}/{@link publicBaseUrl}
+     * base resolved: the variant embeds absolute shim URLs on the SAME
+     * origin, and a request-derived base has no shim family behind it.
+     */
+    readonly mintCodeModuleUrl?: (args: {
+        readonly code: string;
+        readonly hash: string;
+        readonly base: string;
+    }) => string | undefined;
     /** Live-mode credential minter — fresh trio on every /state read. */
     readonly mintBootstrap?: (sessionId: string, appId: string) => {
         wsUrl: string;

package/dist/api-renders-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-renders-routes.d.ts","sourceRoot":"","sources":["../src/api-renders-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO9F,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,KACV;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,MAAM,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAgV9D"}
+{"version":3,"file":"api-renders-routes.d.ts","sourceRoot":"","sources":["../src/api-renders-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQ9F,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE;QAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,KACV;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,MAAM,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA8W9D"}

package/dist/api-renders-routes.js

@@ -44,16 +44,25 @@
  *     or the render was reset). Clients re-mount from /state.
  */
 import { verifyToken } from "@ggui-ai/mcp-server-core";
-import { deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, } from "@ggui-ai/mcp-server-handlers/renders";
-import { MCP_APP_AI_GGUI_RENDER_META_KEY, } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, spreadRenderMetaViewOntoSlice, } from "@ggui-ai/mcp-server-handlers/renders";
+import { composeSessionApiUrls, MCP_APP_AI_GGUI_RENDER_META_KEY, } from "@ggui-ai/protocol/integrations/mcp-apps";
 /**
  * Mount `GET /api/sessions/:sessionId/state` +
  * `GET /api/sessions/:sessionId/events` onto the express app.
  * Returns nothing — the routes self-register.
  */
 export function mountApiRendersRoutes(opts) {
-    const { app, renderStore, secret, appMetadataStore, themeId, themeMode, codeStore, publicBaseUrl, mintBootstrap, resolveRuntimeUrl, logger, } = opts;
+    const { app, renderStore, secret, appMetadataStore, themeId, themeMode, codeStore, publicBaseUrl, codeBaseUrl, mintBootstrap, resolveRuntimeUrl, logger, } = opts;
+    // The origin the content-addressable routes are reached at (asset
+    // host if fronted separately, else the public origin); the request
+    // host is the last resort for local/tunnel deployments.
+    const staticBase = codeBaseUrl ?? publicBaseUrl;
     app.get("/api/sessions/:sessionId/state", async (req, res) => {
+        // CORS on EVERY response, gates included: cross-origin frames can
+        // only read a status when the response carries ACAO. Without it a
+        // 410 (refresh the wsToken) is an opaque network error — the rung
+        // demotes as "structurally unreachable" instead of refreshing.
+        res.setHeader("Access-Control-Allow-Origin", "*");
         const sessionId = req.params["sessionId"];
         if (typeof sessionId !== "string" || sessionId.length === 0) {
             res.status(400).type("text/plain").send("sessionId required");
@@ -149,20 +158,26 @@ export function mountApiRendersRoutes(opts) {
         // stamps this trio on its resultMeta; mirroring here closes the
         // drift.
         const liveTrio = mintBootstrap ? mintBootstrap(stored.id, stored.appId) : undefined;
-        // Polling URL — the iframe-runtime's R6 polling-fallback path
-        // composes its fetch URL from `render.pollingUrl`. The /state
-        // endpoint IS that URL, so we stamp it here; without it the
-        // iframe-runtime can't fall back when the WS upgrade fails.
-        const requestHostForPolling = req.get("host") ?? "";
-        const pollingBase = publicBaseUrl
+        // Token-bearing session-API URL pair (pollingUrl → /events,
+        // sseUrl → /stream), composed via the protocol's ONE composer so
+        // this surface cannot drift from the render/update resultMeta
+        // stamping. Stamped ONLY when the live trio above was minted —
+        // both URLs embed the fresh long-TTL token, so a minter-less
+        // deployment honestly omits them (the old unconditional
+        // token-less `/state`-shaped pollingUrl could only 401 through
+        // the iframe-runtime's /events composer).
+        const sessionApiBase = publicBaseUrl
             ? publicBaseUrl.replace(/\/$/, "")
-            : `${req.protocol}://${requestHostForPolling}`;
-        const pollingUrl = `${pollingBase}/api/sessions/${encodeURIComponent(stored.id)}/state`;
+            : `${req.protocol}://${req.get("host") ?? ""}`;
+        const sessionApiUrls = liveTrio !== undefined
+            ? composeSessionApiUrls(sessionApiBase, stored.id, liveTrio.token)
+            : undefined;
         // Static-component delivery via codeUrl (the same content-addressable
         // channel the code routes serve). Polling clients are render-capable
         // and need the URL to mount/refresh the static-component variant.
         let renderCodeUrl;
         let renderCodeHash;
+        let renderCodeModuleUrl;
         let renderContractHash;
         let renderValidatorsUrl;
         if (!isSystem && !isMcpApps && codeStore) {
@@ -173,10 +188,19 @@ export function mountApiRendersRoutes(opts) {
                     await codeStore.put(hash, code);
                     renderCodeHash = hash;
                     const requestHost = req.get("host") ?? "";
-                    const base = publicBaseUrl
-                        ? publicBaseUrl.replace(/\/$/, "")
+                    const base = staticBase !== undefined
+                        ? staticBase.replace(/\/$/, "")
                         : `${req.protocol}://${requestHost}`;
                     renderCodeUrl = `${base}/code/${hash}.js`;
+                    // Strict-CSP module-variant twin — only on an explicit base
+                    // (see MountOptions.mintCodeModuleUrl for why).
+                    if (staticBase !== undefined) {
+                        renderCodeModuleUrl = opts.mintCodeModuleUrl?.({
+                            code,
+                            hash,
+                            base,
+                        });
+                    }
                 }
                 catch {
                     // Silent — the caller falls back to live-mode delivery, and
@@ -195,8 +219,8 @@ export function mountApiRendersRoutes(opts) {
                         await codeStore.put(bundle.contractHash, bundle.bundleSource);
                         renderContractHash = bundle.contractHash;
                         const requestHost = req.get("host") ?? "";
-                        const base = publicBaseUrl
-                            ? publicBaseUrl.replace(/\/$/, "")
+                        const base = staticBase !== undefined
+                            ? staticBase.replace(/\/$/, "")
                             : `${req.protocol}://${requestHost}`;
                         renderValidatorsUrl = `${base}/contract/${bundle.contractHash}.js`;
                     }
@@ -219,20 +243,19 @@ export function mountApiRendersRoutes(opts) {
                     expiresAt: liveTrio.expiresAt,
                 }
                 : {}),
-            pollingUrl,
+            ...(sessionApiUrls !== undefined
+                ? { pollingUrl: sessionApiUrls.pollingUrl, sseUrl: sessionApiUrls.sseUrl }
+                : {}),
             ...(themeId !== undefined ? { themeId } : {}),
             ...(themeMode !== undefined ? { themeMode } : {}),
-            // Per-app theme overlay projected by `deriveRenderMeta` from the
-            // render's `theme` sidecar — same field the render result-meta
-            // carries, so a /state read returns the identical overlay.
-            ...(view?.theme !== undefined ? { theme: view.theme } : {}),
-            ...(view?.gadgets !== undefined && view.gadgets.length > 0 ? { gadgets: view.gadgets } : {}),
             ...(statePublicEnv !== undefined && Object.keys(statePublicEnv).length > 0
                 ? { publicEnv: statePublicEnv }
                 : {}),
-            ...(view?.permissionsPolicy !== undefined && view.permissionsPolicy.length > 0
-                ? { permissionsPolicy: view.permissionsPolicy }
-                : {}),
+            // State + policy view fields (theme overlay, gadgets,
+            // permissionsPolicy, propsJson, contextSlots, #483 epoch) — ONE
+            // shared spread so /state cannot drift from the result-meta
+            // emitters (a hand-copied list once silently dropped `epoch`).
+            ...spreadRenderMetaViewOntoSlice(view),
             // R6 — load-bearing ledger cursor. Always stamped on /state
             // reads so polling clients can position the R7 /events cursor.
             lastSequence: stored.eventSequence,
@@ -242,10 +265,11 @@ export function mountApiRendersRoutes(opts) {
                 ? {
                     codeUrl: renderCodeUrl,
                     ...(renderCodeHash !== undefined ? { codeHash: renderCodeHash } : {}),
+                    ...(renderCodeModuleUrl !== undefined
+                        ? { codeModuleUrl: renderCodeModuleUrl }
+                        : {}),
                 }
                 : {}),
-            ...(view?.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
-            ...(view?.contextSlots !== undefined ? { contextSlots: view.contextSlots } : {}),
             ...(renderContractHash !== undefined && renderValidatorsUrl !== undefined
                 ? {
                     contractHash: renderContractHash,
@@ -253,7 +277,6 @@ export function mountApiRendersRoutes(opts) {
                 }
                 : {}),
         };
-        res.setHeader("Access-Control-Allow-Origin", "*");
         res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
         res.setHeader("Content-Type", "application/json; charset=utf-8");
         res.status(200).json({
@@ -261,6 +284,10 @@ export function mountApiRendersRoutes(opts) {
         });
     });
     app.get("/api/sessions/:sessionId/events", async (req, res) => {
+        // CORS pre-gates — same contract as /state: the 410/401 verdicts
+        // are part of the polling rung's protocol and must be readable
+        // from cross-origin frames.
+        res.setHeader("Access-Control-Allow-Origin", "*");
         const sessionId = req.params["sessionId"];
         if (typeof sessionId !== "string" || sessionId.length === 0) {
             res.status(400).type("text/plain").send("sessionId required");
@@ -368,7 +395,6 @@ export function mountApiRendersRoutes(opts) {
         // (Wave 7 of flatten-render-identity, 2026-05-28). The store
         // returns events in protocol-canonical shape (seq + type +
         // timestamp[ISO] + data); no projection needed.
-        res.setHeader("Access-Control-Allow-Origin", "*");
         res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
         res.setHeader("Content-Type", "application/json; charset=utf-8");
         res.status(200).json({

package/dist/api-renders-stream-route.d.ts

@@ -0,0 +1,80 @@
+/**
+ * wsToken-gated SSE live stream (the ladder's middle rung).
+ *
+ * GET /api/sessions/:sessionId/stream?wsToken=<token>[&sinceSequence=N][&fromSeq=M]
+ *
+ * Server-Sent Events delivery of the SAME ChannelFrame `{type,
+ * payload}` JSON the live-channel WS pushes — for hosts whose CSP
+ * blocks WebSocket upgrades but allows same-origin HTTP. The route
+ * registers a transport-neutral subscriber into the channel server via
+ * `attachExternalSubscriber`, so every fan-out plane WS subscribers
+ * ride (StreamFanout live tail, `props_update` / `render` /
+ * `drain_ack` walks, external broadcasts) reaches SSE subscribers with
+ * zero per-frame branching.
+ *
+ * Framing contract:
+ *   - Every `data:` line is EXACTLY one ChannelFrame JSON — byte-same
+ *     shape as the WS push (default event type, so `EventSource`'s
+ *     `onmessage` fires).
+ *   - `id:` = decimal GguiSessionEvent ledger seq, stamped ONLY on
+ *     ledger-backed `render_event` replay frames (and the
+ *     REPLAY_HORIZON_PASSED error frame, which carries the fresh
+ *     high-water mark). Live frames are id-less — same ephemeral
+ *     posture as WS; reconnects re-mount state from the ack snapshot.
+ *     The browser's `Last-Event-ID` therefore lands on the exact
+ *     cursor space `/events?sinceSequence=N` reads.
+ *   - First write after headers: `retry: 3000`.
+ *   - Heartbeat: comment line `: hb` every {@link SSE_HEARTBEAT_MS}
+ *     (under ALB's 60s idle default); each tick doubles as a render-
+ *     expiry probe.
+ *
+ * Cursor spaces: `Last-Event-ID` (browser-stamped on auto-reconnect)
+ * WINS over `?sinceSequence=`; the query seeds the first connect
+ * (EventSource cannot set headers). `?fromSeq=` mirrors
+ * `SubscribePayload.fromSeq` for the stream-buffer plane — note it is
+ * frozen in the EventSource URL, so duplicate `data` frames after an
+ * auto-reconnect are expected; ledger + stream deliveries are
+ * documented at-least-once and clients dedupe by seq.
+ *
+ * Auth: wsToken query gate cloned verbatim from `/state`
+ * (`api-renders-routes.ts`) — 401 missing/invalid/wrong-scope, 410
+ * expired, 404 unknown render, plus 503 when the channel is not yet
+ * constructed (pre-listen only). All gates run BEFORE any event-stream
+ * byte: EventSource fails the connection permanently on non-200, which
+ * is the client ladder's SSE→polling demotion signal.
+ */
+import type { GguiSessionStore } from "@ggui-ai/mcp-server-core";
+import type { Express } from "express";
+import type { GguiSessionChannelServer } from "./ggui-session-channel.js";
+import type { Logger } from "./logger.js";
+/**
+ * Heartbeat cadence (25s). Under ALB's 60s idle default with 2x+
+ * headroom; each tick also probes render expiry so an evicted /
+ * expired render ends the stream instead of idling forever.
+ */
+export declare const SSE_HEARTBEAT_MS = 25000;
+export interface MountApiRendersStreamRouteOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** GguiSession store the gate + expiry probe read from. */
+    readonly renderStore: GguiSessionStore;
+    /** Shared HMAC secret the wsToken query credential verifies against. */
+    readonly secret: string;
+    /**
+     * Late-bound channel accessor — `createGguiSessionChannelServer`
+     * runs after route mounting, so the route resolves the channel per
+     * request (same pattern as `stream.channelProvider`). `null` is
+     * possible pre-listen only; the route answers 503.
+     */
+    readonly channelProvider: () => GguiSessionChannelServer | null;
+    /** Heartbeat override for tests. Defaults to {@link SSE_HEARTBEAT_MS}. */
+    readonly heartbeatMs?: number;
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /api/sessions/:sessionId/stream` onto the express app.
+ * Returns nothing — the route self-registers.
+ */
+export declare function mountApiRendersStreamRoute(opts: MountApiRendersStreamRouteOptions): void;
+//# sourceMappingURL=api-renders-stream-route.d.ts.map

package/dist/api-renders-stream-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-renders-stream-route.d.ts","sourceRoot":"","sources":["../src/api-renders-stream-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAE1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AA2DvC,MAAM,WAAW,iCAAiC;IAChD,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,wBAAwB,GAAG,IAAI,CAAC;IAChE,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,iCAAiC,GAAG,IAAI,CA0MxF"}

package/dist/api-renders-stream-route.js

@@ -0,0 +1,311 @@
+/**
+ * wsToken-gated SSE live stream (the ladder's middle rung).
+ *
+ * GET /api/sessions/:sessionId/stream?wsToken=<token>[&sinceSequence=N][&fromSeq=M]
+ *
+ * Server-Sent Events delivery of the SAME ChannelFrame `{type,
+ * payload}` JSON the live-channel WS pushes — for hosts whose CSP
+ * blocks WebSocket upgrades but allows same-origin HTTP. The route
+ * registers a transport-neutral subscriber into the channel server via
+ * `attachExternalSubscriber`, so every fan-out plane WS subscribers
+ * ride (StreamFanout live tail, `props_update` / `render` /
+ * `drain_ack` walks, external broadcasts) reaches SSE subscribers with
+ * zero per-frame branching.
+ *
+ * Framing contract:
+ *   - Every `data:` line is EXACTLY one ChannelFrame JSON — byte-same
+ *     shape as the WS push (default event type, so `EventSource`'s
+ *     `onmessage` fires).
+ *   - `id:` = decimal GguiSessionEvent ledger seq, stamped ONLY on
+ *     ledger-backed `render_event` replay frames (and the
+ *     REPLAY_HORIZON_PASSED error frame, which carries the fresh
+ *     high-water mark). Live frames are id-less — same ephemeral
+ *     posture as WS; reconnects re-mount state from the ack snapshot.
+ *     The browser's `Last-Event-ID` therefore lands on the exact
+ *     cursor space `/events?sinceSequence=N` reads.
+ *   - First write after headers: `retry: 3000`.
+ *   - Heartbeat: comment line `: hb` every {@link SSE_HEARTBEAT_MS}
+ *     (under ALB's 60s idle default); each tick doubles as a render-
+ *     expiry probe.
+ *
+ * Cursor spaces: `Last-Event-ID` (browser-stamped on auto-reconnect)
+ * WINS over `?sinceSequence=`; the query seeds the first connect
+ * (EventSource cannot set headers). `?fromSeq=` mirrors
+ * `SubscribePayload.fromSeq` for the stream-buffer plane — note it is
+ * frozen in the EventSource URL, so duplicate `data` frames after an
+ * auto-reconnect are expected; ledger + stream deliveries are
+ * documented at-least-once and clients dedupe by seq.
+ *
+ * Auth: wsToken query gate cloned verbatim from `/state`
+ * (`api-renders-routes.ts`) — 401 missing/invalid/wrong-scope, 410
+ * expired, 404 unknown render, plus 503 when the channel is not yet
+ * constructed (pre-listen only). All gates run BEFORE any event-stream
+ * byte: EventSource fails the connection permanently on non-200, which
+ * is the client ladder's SSE→polling demotion signal.
+ */
+import { verifyToken } from "@ggui-ai/mcp-server-core";
+/**
+ * Heartbeat cadence (25s). Under ALB's 60s idle default with 2x+
+ * headroom; each tick also probes render expiry so an evicted /
+ * expired render ends the stream instead of idling forever.
+ */
+export const SSE_HEARTBEAT_MS = 25_000;
+/**
+ * SSE-backed {@link SubscriberSink}. Frames serialize to
+ * `data: <ChannelFrame JSON>\n\n` (JSON.stringify never emits raw
+ * newlines, so a single `data:` line is safe); `resumeId` prepends an
+ * `id: <seq>\n` line so the browser's `Last-Event-ID` advances on
+ * ledger-backed frames only.
+ */
+class SseSink {
+    res;
+    logger;
+    /**
+     * Invoked exactly once, from `end()`, BEFORE the response closes —
+     * the route assigns its teardown (clear heartbeat + detach) here so
+     * a channel-initiated `end` (pod shutdown, expiry probe) tears the
+     * subscriber down through the same single path as a client close.
+     */
+    onEnd;
+    constructor(res, logger) {
+        this.res = res;
+        this.logger = logger;
+    }
+    isOpen() {
+        return !this.res.writableEnded && !this.res.destroyed;
+    }
+    write(frame, opts) {
+        if (!this.isOpen())
+            return;
+        try {
+            const idLine = opts?.resumeId !== undefined ? `id: ${opts.resumeId}\n` : "";
+            this.res.write(`${idLine}data: ${JSON.stringify(frame)}\n\n`);
+        }
+        catch (err) {
+            // Same posture as the WS send guard: per-frame write failures
+            // are logged, never propagated — a dead transport must not fail
+            // the fan-out caller.
+            this.logger.warn("sse_write_failed", { error: String(err) });
+        }
+    }
+    end(reason) {
+        const teardown = this.onEnd;
+        this.onEnd = undefined;
+        teardown?.();
+        this.logger.info("sse_stream_ended", { reason });
+        if (!this.res.writableEnded && !this.res.destroyed) {
+            this.res.end();
+        }
+    }
+}
+/** Strict non-negative decimal integer parse; `null` on anything else. */
+function parseNonNegativeInt(raw) {
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : null;
+}
+/**
+ * Mount `GET /api/sessions/:sessionId/stream` onto the express app.
+ * Returns nothing — the route self-registers.
+ */
+export function mountApiRendersStreamRoute(opts) {
+    const { app, renderStore, secret, channelProvider, logger } = opts;
+    const heartbeatMs = opts.heartbeatMs ?? SSE_HEARTBEAT_MS;
+    app.get("/api/sessions/:sessionId/stream", async (req, res) => {
+        // ── Phase 1: plain-HTTP gates, BEFORE any event-stream byte ──
+        // (EventSource fails permanently on non-200 — the demotion signal.)
+        // CORS pre-gates: a gate verdict without ACAO is an OPAQUE error
+        // to a cross-origin frame — the 410 refresh-your-token signal
+        // becomes indistinguishable from a CSP block, so the runtime
+        // demotes off a perfectly healthy rung instead of refreshing.
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        const sessionId = req.params["sessionId"];
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+            res.status(400).type("text/plain").send("sessionId required");
+            return;
+        }
+        const wsTokenRaw = req.query["wsToken"];
+        const wsToken = typeof wsTokenRaw === "string" ? wsTokenRaw : "";
+        if (wsToken.length === 0) {
+            res.status(401).type("text/plain").send("wsToken query required");
+            return;
+        }
+        const verify = verifyToken(wsToken, secret, "ws");
+        if (!verify.ok) {
+            // 410 Gone for expired (matches `BOOTSTRAP_EXPIRED` semantics on
+            // the WS upgrade): once-valid but aged out — refresh, don't
+            // treat as hostile. 401 for tamper / wrong-kind / malformed.
+            if (verify.reason === "expired") {
+                res.status(410).type("text/plain").send("wsToken expired");
+                return;
+            }
+            res.status(401).type("text/plain").send("wsToken invalid");
+            return;
+        }
+        // Tenancy gate: the wsToken's claimed sessionId MUST match the
+        // URL's sessionId.
+        if (verify.claims.sessionId !== sessionId) {
+            res.status(401).type("text/plain").send("wsToken scope mismatch");
+            return;
+        }
+        // Cursor queries — validated pre-headers so a caller bug is an
+        // honest 400, not a silently-ignored replay.
+        const sinceSequenceRaw = req.query["sinceSequence"];
+        let sinceSequence;
+        if (typeof sinceSequenceRaw === "string" && sinceSequenceRaw.length > 0) {
+            const parsed = parseNonNegativeInt(sinceSequenceRaw);
+            if (parsed === null) {
+                res.status(400).type("text/plain").send("sinceSequence must be a non-negative integer");
+                return;
+            }
+            sinceSequence = parsed;
+        }
+        const fromSeqRaw = req.query["fromSeq"];
+        let fromSeq;
+        if (typeof fromSeqRaw === "string" && fromSeqRaw.length > 0) {
+            const parsed = parseNonNegativeInt(fromSeqRaw);
+            if (parsed === null) {
+                res.status(400).type("text/plain").send("fromSeq must be a non-negative integer");
+                return;
+            }
+            fromSeq = parsed;
+        }
+        // Last-Event-ID (browser-stamped on auto-reconnect) WINS over the
+        // query seed. Malformed header → warn + fall back to the query
+        // (never a 4xx: the header is browser-controlled, and failing the
+        // reconnect permanently over a polyfill quirk would strand the
+        // client on a working credential).
+        const lastEventIdRaw = req.get("last-event-id");
+        if (typeof lastEventIdRaw === "string" && lastEventIdRaw.length > 0) {
+            const parsed = parseNonNegativeInt(lastEventIdRaw);
+            if (parsed === null) {
+                logger.warn("sse_last_event_id_malformed", {
+                    sessionId,
+                    lastEventId: lastEventIdRaw,
+                });
+            }
+            else {
+                sinceSequence = parsed;
+            }
+        }
+        let stored;
+        try {
+            stored = await renderStore.get(sessionId);
+        }
+        catch (err) {
+            logger.warn("sse_stream_read_failed", { sessionId, error: String(err) });
+            res.status(500).type("text/plain").send("internal error");
+            return;
+        }
+        if (!stored) {
+            // 404: render evicted / never existed — the browser's
+            // auto-reconnect lands here after an expiry-probe stream end,
+            // failing the EventSource permanently (clean rung exit).
+            res.status(404).type("text/plain").send("render not found");
+            return;
+        }
+        // Tenancy gate (round 2): the wsToken's appId MUST match the
+        // render's appId.
+        if (verify.claims.appId !== stored.appId) {
+            res.status(401).type("text/plain").send("wsToken scope mismatch");
+            return;
+        }
+        const channel = channelProvider();
+        if (channel === null) {
+            // Pre-listen only: mcpApps ⇒ renderChannel is enforced at
+            // composition, so a running server always has a channel. Honest
+            // guard rather than a crash on a boot-race request.
+            logger.warn("sse_stream_channel_unavailable", { sessionId });
+            res.status(503).type("text/plain").send("live channel not ready");
+            return;
+        }
+        // ── Phase 2: open the event stream ──
+        res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+        res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
+        res.setHeader("Connection", "keep-alive");
+        // Tell nginx-family proxies not to buffer the stream. Self-hosters
+        // behind proxies that ignore this must configure pass-through.
+        res.setHeader("X-Accel-Buffering", "no");
+        res.flushHeaders?.();
+        res.write("retry: 3000\n\n");
+        const sink = new SseSink(res, logger);
+        // Single idempotent teardown shared by every exit path: client
+        // close, channel-initiated sink.end (pod shutdown / expiry probe),
+        // attach failure.
+        let detachFn = null;
+        let torn = false;
+        const teardown = () => {
+            if (torn)
+                return;
+            torn = true;
+            clearInterval(heartbeat);
+            detachFn?.();
+        };
+        sink.onEnd = teardown;
+        res.on("close", teardown);
+        // Heartbeat: `: hb` comment (invisible to the EventSource JS API,
+        // visible to proxies/ALBs) + render-expiry probe. A vanished or
+        // expired render ends the stream; the auto-reconnect then hits the
+        // 404 pre-gate for the permanent verdict. Store-read failure on a
+        // tick keeps streaming (availability over freshness; next tick
+        // retries).
+        const heartbeat = setInterval(() => {
+            if (!sink.isOpen()) {
+                teardown();
+                return;
+            }
+            res.write(": hb\n\n");
+            void (async () => {
+                let probe;
+                try {
+                    probe = await renderStore.get(sessionId);
+                }
+                catch (err) {
+                    logger.warn("sse_expiry_probe_failed", { sessionId, error: String(err) });
+                    return;
+                }
+                if (!probe || probe.expiresAt <= Date.now()) {
+                    sink.end("session_expired");
+                }
+            })();
+        }, heartbeatMs);
+        heartbeat.unref?.();
+        // Identity synthesized from the verified wsToken claims — the same
+        // bootstrap shape the WS subscribe path builds: a render-scoped
+        // credential, not a person (see subscribe.ts on why it must never
+        // become the row's subject).
+        const identity = {
+            identity: {
+                kind: "user",
+                userId: sessionId,
+                workspaceId: stored.appId,
+                roles: [],
+            },
+            source: "apikey",
+        };
+        try {
+            const { detach } = await channel.attachExternalSubscriber({
+                sessionId,
+                appId: stored.appId,
+                identity,
+                sink,
+                ...(sinceSequence !== undefined ? { sinceSequence } : {}),
+                ...(fromSeq !== undefined ? { fromSeq } : {}),
+            });
+            detachFn = detach;
+            if (torn) {
+                // Client disconnected while the attach was in flight — the
+                // teardown ran with no handle; undo the registration now.
+                detach();
+            }
+        }
+        catch (err) {
+            // Lost race with render eviction (the pre-gate passed moments
+            // ago) or a store failure inside the subscribe tail. Headers are
+            // out, so no status rewrite — end the stream; the reconnect gets
+            // the authoritative pre-gate verdict.
+            logger.warn("sse_attach_failed", { sessionId, error: String(err) });
+            teardown();
+            sink.end("service_restart");
+        }
+    });
+}