@ggui-ai/mcp-server 0.8.0 → 0.9.0

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,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,CA0V9D"}

package/dist/api-renders-routes.js

@@ -44,8 +44,8 @@
  *     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.
@@ -54,6 +54,11 @@ import { MCP_APP_AI_GGUI_RENDER_META_KEY, } from "@ggui-ai/protocol/integrations
 export function mountApiRendersRoutes(opts) {
     const { app, renderStore, secret, appMetadataStore, themeId, themeMode, codeStore, publicBaseUrl, mintBootstrap, resolveRuntimeUrl, logger, } = opts;
     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,15 +154,20 @@ 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.
@@ -219,20 +229,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,
@@ -244,8 +253,6 @@ export function mountApiRendersRoutes(opts) {
                     ...(renderCodeHash !== undefined ? { codeHash: renderCodeHash } : {}),
                 }
                 : {}),
-            ...(view?.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
-            ...(view?.contextSlots !== undefined ? { contextSlots: view.contextSlots } : {}),
             ...(renderContractHash !== undefined && renderValidatorsUrl !== undefined
                 ? {
                     contractHash: renderContractHash,
@@ -253,7 +260,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 +267,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 +378,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");
+        }
+    });
+}

package/dist/build-mcp.d.ts

@@ -60,6 +60,16 @@ export interface BuildMcpServerOptions {
      * host that owns the iframe CSP itself.
      */
     readonly publicBaseUrl?: string;
+    /**
+     * Live-channel origins for the static shell's CSP declaration —
+     * forwarded to `installMcpAppsOutbound`. Deployments that set no
+     * `publicBaseUrl` (the cloud pod) pass their `wsUrl` + its ws→http
+     * origin flip here so the mounted iframe's `connect-src` covers the
+     * SSE / HTTP-polling session API and the WebSocket; otherwise
+     * cross-origin hosts CSP-block every network rung of the failover
+     * ladder (#471 round 11).
+     */
+    readonly extraConnectUrls?: readonly (string | undefined)[];
     /**
      * Identity-kind allowlist for tool registration. When set, handlers
      * whose `allowedFor` field is non-empty AND does NOT intersect this

package/dist/build-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CAqLX"}
+{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CAmPX"}

package/dist/build-mcp.js

@@ -13,6 +13,7 @@ import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { isRecord } from '@ggui-ai/protocol';
 import { z } from 'zod';
 import { isHandlerFailure, } from '@ggui-ai/mcp-server-handlers';
+import { GGUI_RENDER_RESOURCE_URI } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
 /**
  * Build a fresh MCP server with every handler registered.
@@ -28,8 +29,13 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
         ...(info.description ? { description: info.description } : {}),
         ...(opts.instructions ? { instructions: opts.instructions } : {}),
     });
+    // Content-addressed shell URI (stale-shell bust) — when MCP Apps
+    // outbound wiring registers the shell, declarations advertising the
+    // BARE `ui://ggui/render` are rewritten to the versioned twin below
+    // so host prefetch caches key on content, not on a constant string.
+    let shellResourceUri;
     if (opts.mcpAppsOutbound) {
-        installMcpAppsOutbound(server, {
+        ({ shellResourceUri } = installMcpAppsOutbound(server, {
             ...(opts.shellHtml !== undefined ? { shellHtml: opts.shellHtml } : {}),
             // Thread the same per-request context accessor + logger the tool
             // path uses (`getContext`, param 3 of `buildMcpServer`) so the
@@ -41,7 +47,10 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
             ...(opts.publicBaseUrl !== undefined
                 ? { publicBaseUrl: opts.publicBaseUrl }
                 : {}),
-        });
+            ...(opts.extraConnectUrls !== undefined
+                ? { extraConnectUrls: opts.extraConnectUrls }
+                : {}),
+        }));
     }
     // Per-request resource registrars supplied by the host. Run BEFORE
     // tool registration so `tools/list` ordering is unaffected and any
@@ -127,9 +136,52 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
                     outcome: 'success',
                     elapsedMs: Date.now() - start,
                 });
+                // When the handler's output carries a `nextStep`, lead the
+                // model-visible content with the imperative in PLAIN TEXT.
+                // Burying the chain cue inside the JSON block proved fragile
+                // on live hosts (the first claude.ai #471 test: the agent
+                // rendered, never noticed `nextStep`, ended its turn, and the
+                // user's click had no listener). The JSON stays second —
+                // structured consumers read `structuredContent` anyway.
+                const nextStepHint = validated !== null &&
+                    typeof validated === 'object' &&
+                    'nextStep' in validated &&
+                    validated.nextStep &&
+                    typeof validated.nextStep
+                        .example === 'string'
+                    ? validated.nextStep.example
+                    : undefined;
+                // The gesture-poll wrapper below describes ggui_consume's
+                // semantics ("catch an immediate gesture", "waits up to 25s")
+                // — it is ONLY true when the nextStep IS the consume hint.
+                // Ungated, it decorated ggui_handshake results too (whose
+                // nextStep is a ggui_render example), telling agents a
+                // not-yet-rendered UI "has interactive actions" — a live agent
+                // flagged the contradiction against an actions=∅ contract
+                // (2026-08-12).
+                const gestureHint = nextStepHint !== undefined && nextStepHint.includes('ggui_consume')
+                    ? nextStepHint
+                    : undefined;
                 return {
                     structuredContent: validated,
                     content: [
+                        ...(gestureHint !== undefined
+                            ? [
+                                {
+                                    type: 'text',
+                                    // Gentle + bounded, deliberately: a forcing
+                                    // imperative hijacked live agents into polling
+                                    // instead of acting (matrix scenario 6), and an
+                                    // unbounded "re-call on empty" looped them past
+                                    // their turn budget. The poll is a latency
+                                    // optimization, not the delivery guarantee — when
+                                    // nobody is polling, a gesture rings the chat via
+                                    // ui/message and arrives as a new user message
+                                    // carrying its own consume directive.
+                                    text: `The UI has interactive actions. After this turn's work, you may call ${gestureHint} once to catch an immediate gesture (waits up to 25s); if events is empty, end your turn — later gestures arrive as new user messages.`,
+                                },
+                            ]
+                            : []),
                         { type: 'text', text: JSON.stringify(validated) },
                     ],
                     ...(meta !== undefined ? { _meta: meta } : {}),
@@ -164,11 +216,19 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
         // error on the handler author's side — fail loud rather than
         // silently registering the tool without its UI surface.
         if (handler._meta && 'ui' in handler._meta) {
-            const ui = handler._meta['ui'];
-            if (!isMcpUiToolMeta(ui)) {
+            const uiRaw = handler._meta['ui'];
+            if (!isMcpUiToolMeta(uiRaw)) {
                 throw new Error(`Tool ${handler.name} declares _meta.ui with an invalid shape — ` +
                     `expected { resourceUri?: string; visibility?: ('model' | 'app')[] }.`);
             }
+            // Declarations author the STABLE `ui://ggui/render` constant;
+            // registration swaps in the content-addressed twin so hosts
+            // prefetch (and cache) the shell by its content hash. Handlers
+            // stay host-cache-agnostic; the swap lives in ONE place.
+            const ui = shellResourceUri !== undefined &&
+                uiRaw.resourceUri === GGUI_RENDER_RESOURCE_URI
+                ? { ...uiRaw, resourceUri: shellResourceUri }
+                : uiRaw;
             registerAppTool(server, handler.name, {
                 ...baseConfig,
                 _meta: { ...handler._meta, ui },