@ggui-ai/mcp-server 0.2.0-alpha.3 → 0.3.0-rc.0

package/dist/admin-blueprints-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin-blueprints-transport.d.ts","sourceRoot":"","sources":["../src/admin-blueprints-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,QAAQ,EAAE;QACpB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,CAAC;CACV;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,GAC1B,QAAQ,IAAI,iBAAiB,GAAG,mBAAmB,CAIrD;AAED,MAAM,WAAW,+BAA+B;IAC9C,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,+BAA+B,GACpC,IAAI,CA8GN"}
+{"version":3,"file":"admin-blueprints-transport.d.ts","sourceRoot":"","sources":["../src/admin-blueprints-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,QAAQ,EAAE;QACpB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,CAAC;CACV;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,GAC1B,QAAQ,IAAI,iBAAiB,GAAG,mBAAmB,CAIrD;AAED,MAAM,WAAW,+BAA+B;IAC9C,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,+BAA+B,GACpC,IAAI,CA8GN"}

package/dist/admin-blueprints-transport.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@ggui-ai/protocol';
 import { resolveIdentity, UnauthenticatedError } from './auth.js';
 /**
  * Default URL path the admin-blueprints route is mounted at. Sits
@@ -56,7 +57,7 @@ export function mountAdminBlueprintsTransport(app, opts) {
         // 2. Body validation. Minimum shape: {id: string, name: string}.
         //    Optional fields: description, category, tags (string[]),
         //    updatedAt (ISO string). Anything else is ignored.
-        const body = (req.body ?? {});
+        const body = isRecord(req.body) ? req.body : {};
         const id = typeof body['id'] === 'string' ? body['id'] : undefined;
         const name = typeof body['name'] === 'string' ? body['name'] : undefined;
         if (!id || !name) {

package/dist/admin-oauth-providers-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin-oauth-providers-transport.d.ts","sourceRoot":"","sources":["../src/admin-oauth-providers-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAEV,SAAS,EACT,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,eAAO,MAAM,kCAAkC,gCAAgC,CAAC;AAEhF,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAqCD,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,mCAAmC,GACxC,IAAI,CAiQN"}
+{"version":3,"file":"admin-oauth-providers-transport.d.ts","sourceRoot":"","sources":["../src/admin-oauth-providers-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAEV,SAAS,EACT,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,eAAO,MAAM,kCAAkC,gCAAgC,CAAC;AAEhF,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAqCD,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,mCAAmC,GACxC,IAAI,CAiQN"}

package/dist/admin-oauth-providers-transport.js

@@ -1,4 +1,6 @@
+import { isRecord } from '@ggui-ai/protocol';
 import { resolveIdentity, UnauthenticatedError } from './auth.js';
+import { singleParam } from './route-param.js';
 export const DEFAULT_ADMIN_OAUTH_PROVIDERS_PATH = '/ggui/admin/oauth-providers';
 function redact(record) {
     return {
@@ -100,8 +102,8 @@ export function mountAdminOAuthProvidersTransport(app, opts) {
         const reqLogger = opts.logger.child({ route: 'PUT ' + basePath + '/:providerId' });
         if (!(await requireBuilder(req, res, reqLogger)))
             return;
-        const providerId = req.params['providerId'] ?? '';
-        const body = (req.body ?? {});
+        const providerId = singleParam(req.params['providerId']) ?? '';
+        const body = isRecord(req.body) ? req.body : {};
         const clientId = typeof body['clientId'] === 'string' ? body['clientId'] : undefined;
         const clientSecret = typeof body['clientSecret'] === 'string' ? body['clientSecret'] : undefined;
         const enabled = typeof body['enabled'] === 'boolean' ? body['enabled'] : undefined;
@@ -171,8 +173,8 @@ export function mountAdminOAuthProvidersTransport(app, opts) {
         });
         if (!(await requireBuilder(req, res, reqLogger)))
             return;
-        const providerId = req.params['providerId'] ?? '';
-        const body = (req.body ?? {});
+        const providerId = singleParam(req.params['providerId']) ?? '';
+        const body = isRecord(req.body) ? req.body : {};
         const enabled = typeof body['enabled'] === 'boolean' ? body['enabled'] : undefined;
         if (enabled === undefined) {
             res.status(400).json({
@@ -233,7 +235,7 @@ export function mountAdminOAuthProvidersTransport(app, opts) {
         });
         if (!(await requireBuilder(req, res, reqLogger)))
             return;
-        const providerId = req.params['providerId'] ?? '';
+        const providerId = singleParam(req.params['providerId']) ?? '';
         try {
             await opts.store.remove(providerId);
             reqLogger.info('admin_oauth_providers_remove', { providerId });

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

@@ -0,0 +1,85 @@
+/**
+ * wsToken-gated render read routes (R6 + R7).
+ *
+ * R6 — GET /api/sessions/:sessionId/state?wsToken=<token>
+ *
+ * Auth'd snapshot read of the current render state, returning the
+ * same slice envelope as the wire `_meta` (a single
+ * `{"ai.ggui/render": {...}}` slice — Phase B collapsed the prior
+ * session + stack-item pair). Polling clients call this on a fixed
+ * interval (registry-level polling — see R6 library refactor) to
+ * pick up changes when WS is blocked at the host's CSP layer.
+ *
+ * wsToken-gated: same credential as the live-channel WS upgrade
+ * (`?wsToken=<token>` on `/ws`). Drift-free with the WS surface —
+ * the iframe-runtime already has the token from the bootstrap
+ * envelope; no separate refresh path needed.
+ *
+ * Distinct from `/r/:shortCode` (JSON branch):
+ *   - `/r/...` was shortCode-gated (bearer-by-obscurity; anyone with
+ *     the URL could read). R5 deleted that surface entirely.
+ *   - `/api/sessions/.../state` is wsToken-gated (HMAC-signed,
+ *     short-TTL, scoped to sessionId+appId). Survives R5.
+ *
+ * R7 — GET /api/sessions/:sessionId/events?wsToken=&sinceSequence=N&limit=M
+ *
+ * Cursor-replay read from the GguiSessionEvent ledger. Returns events
+ * with `seq > sinceSequence`, up to `limit` (default 100, max 500).
+ *
+ * Unification: WS subscribe's `sinceSequence` cursor and this HTTP
+ * endpoint read from the SAME ledger via the same `listEventsSince`
+ * GguiSessionStore method. Different transports, same cursor model —
+ * that's R7's payoff.
+ *
+ * Auth: wsToken-gated, identical posture to /state.
+ *
+ * Responses (/events):
+ *   - 200 — `{events, lastSequence, hasMore}` (matches
+ *     `EventsResponse` from @ggui-ai/protocol/integrations/mcp-apps).
+ *   - 401 — wsToken missing / invalid / wrong-scope.
+ *   - 404 — sessionId does not resolve.
+ *   - 410 — `{reason: 'REPLAY_HORIZON_PASSED', currentSequence}` when
+ *     `sinceSequence` is below the server's replay horizon OR strictly
+ *     greater than `lastSequence` (cursor is from a stale deployment
+ *     or the render was reset). Clients re-mount from /state.
+ */
+import type { AppMetadataStore, CodeStore, GguiSessionStore } from "@ggui-ai/mcp-server-core";
+import { type McpAppAiGguiRenderMeta } from "@ggui-ai/protocol/integrations/mcp-apps";
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** GguiSession store both routes read from. */
+    readonly renderStore: GguiSessionStore;
+    /** Shared HMAC secret the wsToken query credential verifies against. */
+    readonly secret: string;
+    /** Per-app metadata store for the publicEnv projection (optional). */
+    readonly appMetadataStore?: AppMetadataStore;
+    /** Operator-picked theme preset id stamped on /state reads. */
+    readonly themeId?: string;
+    /** Operator-picked theme mode stamped on /state reads. */
+    readonly themeMode?: McpAppAiGguiRenderMeta["themeMode"];
+    /** Content-addressable store for codeUrl / validatorsUrl emission. */
+    readonly codeStore?: CodeStore;
+    /** Operator-configured public origin for absolute URL composition. */
+    readonly publicBaseUrl?: string;
+    /** Live-mode credential minter — fresh trio on every /state read. */
+    readonly mintBootstrap?: (sessionId: string, appId: string) => {
+        wsUrl: string;
+        token: string;
+        expiresAt: string;
+    };
+    /** Per-request runtime-bundle URL resolver (tunnel/proxy aware). */
+    readonly resolveRuntimeUrl: () => string;
+    /** Structured logger for store-read failures. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /api/sessions/:sessionId/state` +
+ * `GET /api/sessions/:sessionId/events` onto the express app.
+ * Returns nothing — the routes self-register.
+ */
+export declare function mountApiRendersRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=api-renders-routes.d.ts.map

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

@@ -0,0 +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,CAwU9D"}

package/dist/api-renders-routes.js

@@ -0,0 +1,372 @@
+/**
+ * wsToken-gated render read routes (R6 + R7).
+ *
+ * R6 — GET /api/sessions/:sessionId/state?wsToken=<token>
+ *
+ * Auth'd snapshot read of the current render state, returning the
+ * same slice envelope as the wire `_meta` (a single
+ * `{"ai.ggui/render": {...}}` slice — Phase B collapsed the prior
+ * session + stack-item pair). Polling clients call this on a fixed
+ * interval (registry-level polling — see R6 library refactor) to
+ * pick up changes when WS is blocked at the host's CSP layer.
+ *
+ * wsToken-gated: same credential as the live-channel WS upgrade
+ * (`?wsToken=<token>` on `/ws`). Drift-free with the WS surface —
+ * the iframe-runtime already has the token from the bootstrap
+ * envelope; no separate refresh path needed.
+ *
+ * Distinct from `/r/:shortCode` (JSON branch):
+ *   - `/r/...` was shortCode-gated (bearer-by-obscurity; anyone with
+ *     the URL could read). R5 deleted that surface entirely.
+ *   - `/api/sessions/.../state` is wsToken-gated (HMAC-signed,
+ *     short-TTL, scoped to sessionId+appId). Survives R5.
+ *
+ * R7 — GET /api/sessions/:sessionId/events?wsToken=&sinceSequence=N&limit=M
+ *
+ * Cursor-replay read from the GguiSessionEvent ledger. Returns events
+ * with `seq > sinceSequence`, up to `limit` (default 100, max 500).
+ *
+ * Unification: WS subscribe's `sinceSequence` cursor and this HTTP
+ * endpoint read from the SAME ledger via the same `listEventsSince`
+ * GguiSessionStore method. Different transports, same cursor model —
+ * that's R7's payoff.
+ *
+ * Auth: wsToken-gated, identical posture to /state.
+ *
+ * Responses (/events):
+ *   - 200 — `{events, lastSequence, hasMore}` (matches
+ *     `EventsResponse` from @ggui-ai/protocol/integrations/mcp-apps).
+ *   - 401 — wsToken missing / invalid / wrong-scope.
+ *   - 404 — sessionId does not resolve.
+ *   - 410 — `{reason: 'REPLAY_HORIZON_PASSED', currentSequence}` when
+ *     `sinceSequence` is below the server's replay horizon OR strictly
+ *     greater than `lastSequence` (cursor is from a stale deployment
+ *     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";
+/**
+ * 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;
+    app.get("/api/sessions/:sessionId/state", async (req, res) => {
+        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 the `BOOTSTRAP_EXPIRED`
+            // semantics on the WS upgrade): the envelope was once valid
+            // but has aged out; the iframe-runtime branches on this to
+            // surface a refresh-vs-rehandshake prompt instead of treating
+            // it as a hostile request.
+            if (verify.reason === "expired") {
+                res.status(410).type("text/plain").send("wsToken expired");
+                return;
+            }
+            // 401 for tamper / wrong-kind / malformed / invalid-format —
+            // the caller is broken or hostile; no info leak.
+            res.status(401).type("text/plain").send("wsToken invalid");
+            return;
+        }
+        // Tenancy gate: the wsToken's claimed sessionId MUST match the
+        // URL's sessionId. A wsToken minted for render A MUST NOT read
+        // render B's state.
+        if (verify.claims.sessionId !== sessionId) {
+            res.status(401).type("text/plain").send("wsToken scope mismatch");
+            return;
+        }
+        let stored;
+        try {
+            stored = await renderStore.get(sessionId);
+        }
+        catch (err) {
+            logger.warn("state_read_failed", {
+                sessionId,
+                error: String(err),
+            });
+            res.status(500).type("text/plain").send("internal error");
+            return;
+        }
+        if (!stored) {
+            // 404: render evicted / never existed. Polling clients fold
+            // this into "stop polling" — distinct from 410 which signals
+            // "credential aged out, refresh".
+            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. Closes the case where a render is created
+        // under a different appId than the token was minted for.
+        if (verify.claims.appId !== stored.appId) {
+            res.status(401).type("text/plain").send("wsToken scope mismatch");
+            return;
+        }
+        // Phase B: a render IS the addressable unit. Pick directly from
+        // the resolved GguiSession (no stack walk).
+        const render = stored.render;
+        const isMcpApps = render.type === "mcpApps";
+        const isSystem = !isMcpApps && render.type === "system";
+        const renderKind = isSystem && typeof render.kind === "string"
+            ? render.kind
+            : undefined;
+        // Build render-slice meta. Mirror render.resultMeta's shape so
+        // the iframe-runtime parser admits identical envelopes regardless
+        // of which surface served them. `lastSequence` is the load-bearing
+        // R6 addition: polling clients use it to initialize the R7 /events
+        // cursor (`?sinceSequence=N`) aligned with the WS stream.
+        const view = !isMcpApps ? deriveRenderMeta(render) : undefined;
+        let statePublicEnv;
+        if (appMetadataStore && !isMcpApps) {
+            try {
+                const appRecord = await appMetadataStore.get(stored.appId);
+                statePublicEnv = derivePublicEnvProjection(render, appRecord?.publicEnv);
+            }
+            catch {
+                // Silent — wrappers calling getPublicEnv throw clearly.
+            }
+        }
+        // Live-mode credential trio. Always minted fresh on /state reads
+        // so the iframe-runtime gets a long-TTL token + the host learns
+        // `wsUrl` (the CSP-permitted WebSocket origin). Without this,
+        // any caller of /state — including the restore-bootstrap path in
+        // every host (claude.ai, ChatGPT, our sample-agent) — receives a
+        // render slice missing `wsUrl`. CSP `connect-src` then omits the
+        // `ws://` scheme, the browser blocks the upgrade, and props_update
+        // never reaches the iframe. The render-commit handler already
+        // 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
+            ? publicBaseUrl.replace(/\/$/, "")
+            : `${req.protocol}://${requestHostForPolling}`;
+        const pollingUrl = `${pollingBase}/api/sessions/${encodeURIComponent(stored.id)}/state`;
+        // 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 renderContractHash;
+        let renderValidatorsUrl;
+        if (!isSystem && !isMcpApps && codeStore) {
+            const code = render.componentCode;
+            if (typeof code === "string" && code.length > 0) {
+                try {
+                    const hash = codeStore.hashOf(code);
+                    await codeStore.put(hash, code);
+                    renderCodeHash = hash;
+                    const requestHost = req.get("host") ?? "";
+                    const base = publicBaseUrl
+                        ? publicBaseUrl.replace(/\/$/, "")
+                        : `${req.protocol}://${requestHost}`;
+                    renderCodeUrl = `${base}/code/${hash}.js`;
+                }
+                catch {
+                    // Silent — caller falls back to live-mode delivery.
+                }
+                try {
+                    const bundle = await deriveContractBundle(render);
+                    if (bundle) {
+                        await codeStore.put(bundle.contractHash, bundle.bundleSource);
+                        renderContractHash = bundle.contractHash;
+                        const requestHost = req.get("host") ?? "";
+                        const base = publicBaseUrl
+                            ? publicBaseUrl.replace(/\/$/, "")
+                            : `${req.protocol}://${requestHost}`;
+                        renderValidatorsUrl = `${base}/contract/${bundle.contractHash}.js`;
+                    }
+                }
+                catch {
+                    // Silent — server-side gate remains authoritative.
+                }
+            }
+        }
+        // Phase B: single flat ai.ggui/render slice — render + visible-
+        // bits surface fields merged into one shape.
+        const renderMeta = {
+            sessionId: stored.id,
+            appId: stored.appId,
+            runtimeUrl: resolveRuntimeUrl(),
+            ...(liveTrio !== undefined
+                ? {
+                    wsUrl: liveTrio.wsUrl,
+                    wsToken: liveTrio.token,
+                    expiresAt: liveTrio.expiresAt,
+                }
+                : {}),
+            pollingUrl,
+            ...(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 }
+                : {}),
+            // R6 — load-bearing ledger cursor. Always stamped on /state
+            // reads so polling clients can position the R7 /events cursor.
+            lastSequence: stored.eventSequence,
+            // Visible-bits surface merged onto the single render slice.
+            ...(renderKind !== undefined ? { kind: renderKind } : {}),
+            ...(renderCodeUrl !== undefined
+                ? {
+                    codeUrl: renderCodeUrl,
+                    ...(renderCodeHash !== undefined ? { codeHash: renderCodeHash } : {}),
+                }
+                : {}),
+            ...(view?.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
+            ...(view?.contextSlots !== undefined ? { contextSlots: view.contextSlots } : {}),
+            ...(renderContractHash !== undefined && renderValidatorsUrl !== undefined
+                ? {
+                    contractHash: renderContractHash,
+                    validatorsUrl: renderValidatorsUrl,
+                }
+                : {}),
+        };
+        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({
+            [MCP_APP_AI_GGUI_RENDER_META_KEY]: renderMeta,
+        });
+    });
+    app.get("/api/sessions/:sessionId/events", async (req, res) => {
+        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) {
+            if (verify.reason === "expired") {
+                res.status(410).type("text/plain").send("wsToken expired");
+                return;
+            }
+            res.status(401).type("text/plain").send("wsToken invalid");
+            return;
+        }
+        if (verify.claims.sessionId !== sessionId) {
+            res.status(401).type("text/plain").send("wsToken scope mismatch");
+            return;
+        }
+        // Parse + validate sinceSequence (required, non-negative integer)
+        // and limit (optional, 1..500, default 100).
+        //
+        // sinceSequence is REQUIRED — explicit cursor reads only. A missing
+        // query is a caller bug (no sensible default; `0` means "replay
+        // everything" which we don't want to fire unintentionally).
+        const sinceSequenceRaw = req.query["sinceSequence"];
+        if (typeof sinceSequenceRaw !== "string" || sinceSequenceRaw.length === 0) {
+            res
+                .status(400)
+                .type("text/plain")
+                .send("sinceSequence query required (non-negative integer)");
+            return;
+        }
+        const sinceSequence = Number(sinceSequenceRaw);
+        if (!Number.isInteger(sinceSequence) || sinceSequence < 0) {
+            res.status(400).type("text/plain").send("sinceSequence must be a non-negative integer");
+            return;
+        }
+        const limitRaw = req.query["limit"];
+        let limit = 100;
+        if (typeof limitRaw === "string" && limitRaw.length > 0) {
+            const parsed = Number(limitRaw);
+            if (!Number.isInteger(parsed) || parsed < 1 || parsed > 500) {
+                res.status(400).type("text/plain").send("limit must be an integer in [1, 500]");
+                return;
+            }
+            limit = parsed;
+        }
+        let result;
+        try {
+            result = await renderStore.listEventsSince(sessionId, sinceSequence, limit);
+        }
+        catch (err) {
+            logger.warn("events_read_failed", {
+                sessionId,
+                error: String(err),
+            });
+            res.status(500).type("text/plain").send("internal error");
+            return;
+        }
+        if (result === null) {
+            // 404 — render not found. Distinct from 410 (cursor stale on
+            // a live render) so polling clients can branch.
+            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. We need the render record to check — fetch
+        // it. listEventsSince validated the render exists.
+        const stored = await renderStore.get(sessionId);
+        if (!stored) {
+            res.status(404).type("text/plain").send("render not found");
+            return;
+        }
+        if (verify.claims.appId !== stored.appId) {
+            res.status(401).type("text/plain").send("wsToken scope mismatch");
+            return;
+        }
+        // Replay-horizon gate. Two cases collapse to REPLAY_HORIZON_PASSED:
+        //   (a) sinceSequence < horizonSeq — events evicted (cloud TTL,
+        //       in-mem never).
+        //   (b) sinceSequence > lastSequence — cursor from a different
+        //       deployment / reset render; the server has no events
+        //       beyond what it knows, and we can't safely advance.
+        if (sinceSequence > result.lastSequence) {
+            res.status(410).type("application/json").json({
+                reason: "REPLAY_HORIZON_PASSED",
+                currentSequence: result.lastSequence,
+            });
+            return;
+        }
+        if (sinceSequence < result.horizonSeq) {
+            res.status(410).type("application/json").json({
+                reason: "REPLAY_HORIZON_PASSED",
+                currentSequence: result.lastSequence,
+            });
+            return;
+        }
+        // GguiSessionEvent is now the unified wire-shape ledger primitive
+        // (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({
+            events: result.events,
+            lastSequence: result.lastSequence,
+            hasMore: result.hasMore,
+        });
+    });
+}

package/dist/build-mcp.d.ts

@@ -40,7 +40,7 @@ export interface BuildMcpServerOptions {
     /**
      * Per-render self-contained shell options. When supplied,
      * `installMcpAppsOutbound` ALSO registers
-     * `ui://ggui/render/{renderId}` as a resource template — the URI
+     * `ui://ggui/render/{sessionId}` as a resource template — the URI
      * `ggui_render.resultMeta` stamps on per-call `_meta.ui.resourceUri`
      * for third-party MCP Apps hosts (Claude Desktop, claude.ai web)
      * that don't speak ggui's custom postMessage protocol.

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;AAEpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACd,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,CA8IX"}
+{"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,KAAK,EACV,cAAc,EACd,aAAa,EACd,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,CAyJX"}

package/dist/build-mcp.js

@@ -10,6 +10,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
+import { isRecord } from '@ggui-ai/protocol';
 import { z } from 'zod';
 import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
 /**
@@ -74,11 +75,13 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
             // deadline. Both ride the canonical context without leaking the
             // SDK type into the handlers package.
             const baseCtx = getContext();
+            // `_meta` is `unknown` at the SDK seam; per JSON-RPC it MUST be
+            // an object, so narrow with the validating predicate and DROP
+            // anything else rather than asserting.
+            const requestMeta = extra?._meta;
             const ctx = {
                 ...baseCtx,
-                ...(extra?._meta !== undefined
-                    ? { requestMeta: extra._meta }
-                    : {}),
+                ...(isRecord(requestMeta) ? { requestMeta } : {}),
                 ...(extra?.signal !== undefined ? { signal: extra.signal } : {}),
             };
             const start = Date.now();
@@ -128,11 +131,18 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
         // single canonical key only; the helper owns the back-compat
         // shape. Handlers without `_meta.ui` fall through to plain
         // `registerTool` — the ext-apps helper requires `_meta.ui` to be
-        // typed.
+        // typed. A declared-but-malformed `_meta.ui` is a programming
+        // 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)) {
+                throw new Error(`Tool ${handler.name} declares _meta.ui with an invalid shape — ` +
+                    `expected { resourceUri?: string; visibility?: ('model' | 'app')[] }.`);
+            }
             registerAppTool(server, handler.name, {
                 ...baseConfig,
-                _meta: handler._meta,
+                _meta: { ...handler._meta, ui },
             }, cb);
         }
         else {
@@ -144,6 +154,30 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
     }
     return server;
 }
+/**
+ * Validating narrower for declaration-level MCP-Apps UI meta. The
+ * `SharedHandler` seam types `_meta` as `Record<string, unknown>`;
+ * `registerAppTool` requires `_meta.ui` typed as `McpUiToolMeta`.
+ * Validates the two fields the ext-apps helper actually reads —
+ * `resourceUri` (string when present) and `visibility`
+ * (`"model"`/`"app"` array when present) — instead of asserting
+ * blindly across the SDK seam.
+ */
+function isMcpUiToolMeta(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.resourceUri !== undefined && typeof value.resourceUri !== 'string') {
+        return false;
+    }
+    if (value.visibility !== undefined) {
+        if (!Array.isArray(value.visibility))
+            return false;
+        if (!value.visibility.every((v) => v === 'model' || v === 'app')) {
+            return false;
+        }
+    }
+    return true;
+}
 function errorClassName(err) {
     if (err instanceof Error) {
         if (err.name && err.name !== 'Error')