@ggui-ai/mcp-server 0.8.0 → 0.10.0

package/dist/server.js

@@ -38,20 +38,20 @@
  * once at boot so operators see the shape they're running.
  */
 import { CONSOLE_DIST_DIR } from "@ggui-ai/console/server";
-import { RUNTIME_BUNDLE_FILE, RUNTIME_BUNDLE_URL_PATH } from "@ggui-ai/iframe-runtime/server";
+import { RUNTIME_BUNDLE_FILE, RUNTIME_BUNDLE_URL_PATH, RUNTIME_SHIMS_DIR, RUNTIME_SHIMS_URL_PREFIX, } from "@ggui-ai/iframe-runtime/server";
 import { createDeterministicBlueprintSelector, isTokenRegisteringAuthAdapter, mintSessionToken, mintWsToken, refreshWsToken, verifyToken, } from "@ggui-ai/mcp-server-core";
 import { createInMemoryBlueprintSearch, createInMemoryGeneratorRegistry, FixedWindowRateLimiter, InMemoryActiveConsumerRegistry, InMemoryAppMetadataStore, InMemoryAuthAdapter, InMemoryBlueprintIndex, InMemoryBlueprintStore, InMemoryKeyValueStore, InMemoryPairingService, InMemoryPendingEventConsumer, InMemoryQuotaStore, InMemoryGguiSessionStore, InMemoryGguiSessionStreamBuffer, InMemoryVectorStore, MockEmbeddingProvider, NoopAuditSink, NoopRateLimiter, NoopTelemetrySink, } from "@ggui-ai/mcp-server-core/in-memory";
 import { createGguiListGadgetsHandler, createGguiListThemesHandler, } from "@ggui-ai/mcp-server-handlers/app-discovery";
 import { createDescribeBlueprintFormatHandler, createDescribeDataContractFormatHandler, createGetBlueprintBoilerplateHandler, createGetExampleBlueprintsHandler, createListAvailablePrimitivesHandler, createListFeaturedBlueprintsHandler, createRenderBlueprintHandler, createSearchBlueprintsHandler, createValidateBlueprintHandler, } from "@ggui-ai/mcp-server-handlers/blueprints";
 import { createGguiOpsDeleteBlueprintHandler, createGguiOpsGenerateBlueprintHandler, createGguiOpsListBlueprintsHandler, createGguiOpsRegisterBlueprintHandler, createGguiOpsUpdateBlueprintHandler, } from "@ggui-ai/mcp-server-handlers/ops-blueprint";
-import { setCacheTraceSink, setPayloadTraceSink } from "@ggui-ai/mcp-server-handlers/renders";
+import { setCacheTraceSink, setPayloadTraceSink, wsOriginToHttpOrigin, } from "@ggui-ai/mcp-server-handlers/renders";
 import { loadTheme } from "@ggui-ai/project-config/node";
 import { LIFECYCLE_CHANNEL } from "@ggui-ai/protocol";
 import { setLlmTraceSink } from "@ggui-ai/ui-gen/harness/llm-trace-sink";
 import { setValidatorTraceSink } from "@ggui-ai/ui-gen/harness/validator-trace-sink";
 import express from "express";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { BoundedCacheTraceSink, mountConsoleCacheRoutes } from "./console-cache.js";
@@ -71,12 +71,13 @@ import { createCreateAppHandler, createDeleteAppHandler, createListAppsHandler,
 import { createIssueConnectorKeyHandler, createListConnectorKeysHandler, createRevokeConnectorKeyHandler, } from "@ggui-ai/mcp-server-handlers/ops-connector-keys";
 import { createRedeemCouponHandler, } from "@ggui-ai/mcp-server-handlers/ops-coupon";
 import { createCreateOrgHandler, createGetOrgBalanceHandler, createInviteToOrgHandler, createListOrgsHandler, createRemoveOrgMemberHandler, createRenameOrgHandler, createRevokeInviteHandler, } from "@ggui-ai/mcp-server-handlers/ops-orgs";
-import { createGguiConsumeHandler, createGguiDeclareToolCatalogHandler, createGguiEmitHandler, createGguiGetSessionHandler, createGguiHandshakeHandler, createGguiListSessionsHandler, createGguiRefreshWsTokenHandler, createGguiRenderHandler, createGguiSubmitActionHandler, createGguiSyncContextHandler, createGguiUpdateHandler, InMemoryToolIdentityCatalogStore, createInMemoryProvisionalPreviewRegistry, } from "@ggui-ai/mcp-server-handlers/renders";
+import { createGguiConsumeHandler, createGguiDeclareToolCatalogHandler, createGguiEmitHandler, createGguiGetRenderSourceHandler, createGguiGetSessionHandler, createGguiHandshakeHandler, createGguiListSessionsHandler, createGguiRefreshWsTokenHandler, createGguiRenderHandler, createGguiRuntimePullHandler, createGguiRuntimeTelemetryHandler, createGguiSubmitActionHandler, createGguiSyncContextHandler, createGguiUpdateHandler, createGguiAmendHandler, InMemoryToolIdentityCatalogStore, createInMemoryProvisionalPreviewRegistry, } from "@ggui-ai/mcp-server-handlers/renders";
 import { DEFAULT_ADMIN_BLUEPRINTS_PATH, mountAdminBlueprintsTransport, } from "./admin-blueprints-transport.js";
 import { mountAdminOAuthProvidersTransport } from "./admin-oauth-providers-transport.js";
 import { DEFAULT_BUILDER_APP_ID, defaultAppIdFromIdentity } from "./auth.js";
 import { mountMcpEndpoints } from "./mcp-endpoint-routes.js";
 import { mountApiRendersRoutes } from "./api-renders-routes.js";
+import { mountApiRendersStreamRoute } from "./api-renders-stream-route.js";
 import { mountConsoleBlueprintRoutes } from "./console-blueprint-routes.js";
 import { mountConsoleChatRoutes } from "./console-chat-routes.js";
 import { mountConsoleConfigRoutes } from "./console-config-routes.js";
@@ -89,10 +90,12 @@ import { mountConsoleSessionRoutes } from "./console-session-routes.js";
 import { mountConsoleStaticRoutes } from "./console-static-routes.js";
 import { mountConsoleSessionsRoutes } from "./console-sessions-routes.js";
 import { mountCodeRoutes } from "./code-routes.js";
+import { captureShimSources, createCodeModuleUrlMinter, mountShimRoutes, } from "./code-module-variant.js";
 import { mountHealthRoutes } from "./health-routes.js";
 import { mountOAuthAuthorizationServerRoutes } from "./oauth-as-routes.js";
 import { mountOAuthClientsRoutes } from "./oauth-clients-routes.js";
 import { mountRuntimeBundleRoute } from "./runtime-bundle-route.js";
+import { computeRuntimeBundleHash, insertRuntimeBundleHash, } from "./runtime-bundle-hash.js";
 import { createCsrfMiddleware, mountCsrfTokenRoute } from "./csrf-middleware.js";
 import { mountEmailLoginRoutes } from "./email-login.js";
 import { resolveMcpInstructions } from "./instructions-presets.js";
@@ -110,7 +113,7 @@ import { InMemoryOAuthStorage } from "./oauth.js";
 import { DEFAULT_PAIRING_ADMIN_INIT_PATH, DEFAULT_PAIRING_PATH, mountPairingTransport, } from "./pairing-transport.js";
 import { createPairLoginRateLimitMiddleware } from "./rate-limit-middleware.js";
 import { createGguiSessionChannelServer, } from "./ggui-session-channel.js";
-import { buildRequestContextMiddleware, resolveRuntimeUrl } from "./request-context.js";
+import { buildRequestContextMiddleware, resolvePublicBaseUrl, resolveRuntimeUrl, } from "./request-context.js";
 import { composePreviewReservedValidator, mergeReservedValidators } from "./reserved-validators.js";
 import { checkRenderSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, } from "./schema-compat.js";
 import { createSecurityHeadersMiddleware } from "./security-headers-middleware.js";
@@ -124,30 +127,6 @@ const DEFAULT_INFO = {
     version: "0.0.1",
     description: "Open self-hosted MCP server for the ggui protocol. Powered by @ggui-ai/mcp-server-handlers.",
 };
-/**
- * Canonical default handler set. Every `@ggui-ai/mcp-server-handlers`
- * family the OSS server ships with lands here, bound to the caller-
- * supplied deps. Use this when you want to EXTEND the defaults rather
- * than replace them wholesale:
- *
- * ```ts
- * const server = createGguiServer({
- *   vectors, embedding,
- *   handlers: [
- *     ...defaultHandlers({ vectors, embedding }),
- *     myCustomHandler,
- *   ],
- * });
- * ```
- *
- * Without this helper, `handlers:` replaces the full list — callers
- * lose the defaults unless they copy-paste them. Keeping `defaultHandlers`
- * named means the default set stays discoverable + testable in one place.
- *
- * `render` is opt-in via `deps.render` — it's only useful when the server
- * was booted with `mcpApps: true` (so `ui://ggui/render` is served)
- * and pairs a real GguiSessionStore. Callers get the choice explicitly.
- */
 /**
  * Assemble the `opsBlueprint` dep bundle for `defaultHandlers`.
  *
@@ -177,9 +156,82 @@ function buildOpsBlueprintDeps(input) {
             ...(input.resolveLlm ? { resolveLlm: input.resolveLlm } : {}),
             ...(input.blueprints ? { blueprints: input.blueprints } : {}),
             ...(input.cacheRegistry ? { cacheRegistry: input.cacheRegistry } : {}),
+            authorizeAppAccess: input.authorizeAppAccess ?? (async () => ({ allowed: true })),
         },
     };
 }
+/**
+ * Materialize the operator-class blueprint family from a bound
+ * {@link OpsBlueprintBundle}. Registered on the control plane via
+ * `audience: ['ops']`.
+ *
+ * Four of the five land whenever the bundle is present; the `generate`
+ * tool additionally requires `resolveLlm` + `blueprints` (the same deps
+ * the render generation path reads) because without them it has no
+ * dispatch target.
+ *
+ * Lives here — not inline in {@link defaultHandlers} — so BOTH
+ * composition paths build the family from ONE body:
+ * `defaultHandlers` for the default handler set, and
+ * {@link buildOpsBundleHandlers} for deployments that supply their own
+ * `CreateGguiServerOptions.handlers` array. The construction used to sit
+ * only inside `defaultHandlers`, so an explicit handler list silently
+ * dropped all five tools even with the bundle bound.
+ */
+export function buildOpsBlueprintHandlers(input) {
+    const { bundle } = input;
+    const handlers = [];
+    // Bundle-explicit `appMetadataStore` wins; falls back to the
+    // server-level one — same precedence
+    // `deps.handshake.appMetadataStore ?? deps.appMetadataStore` uses.
+    // Gates `assertGadgetsRegistered` inside both generate + register
+    // (see each handler's own no-op-when-unbound posture).
+    const opsBlueprintAppMetadataStore = bundle.appMetadataStore ?? input.appMetadataStore;
+    if (bundle.resolveLlm && bundle.blueprints) {
+        handlers.push(createGguiOpsGenerateBlueprintHandler({
+            registry: bundle.registry,
+            blueprintStore: bundle.blueprintStore,
+            resolveLlm: bundle.resolveLlm,
+            blueprints: bundle.blueprints,
+            ...(bundle.putCode ? { putCode: bundle.putCode } : {}),
+            ...(bundle.listAllForApp ? { listAllForApp: bundle.listAllForApp } : {}),
+            ...(opsBlueprintAppMetadataStore
+                ? { appMetadataStore: opsBlueprintAppMetadataStore }
+                : {}),
+            ...(bundle.cacheRegistry ? { cacheRegistry: bundle.cacheRegistry } : {}),
+            ...(input.telemetry ? { telemetry: input.telemetry } : {}),
+            authorizeAppAccess: bundle.authorizeAppAccess,
+        }));
+    }
+    // `ggui_ops_register_blueprint` — sibling of `_generate_*` that
+    // accepts pre-built componentCode bytes. No LLM dispatch, so it
+    // registers whenever the ops dep bundle is bound (no resolveLlm
+    // / blueprints gate). Operator UX entry point for fixture
+    // seeding + export/reimport round-trips.
+    handlers.push(createGguiOpsRegisterBlueprintHandler({
+        blueprintStore: bundle.blueprintStore,
+        ...(bundle.putCode ? { putCode: bundle.putCode } : {}),
+        ...(bundle.listAllForApp ? { listAllForApp: bundle.listAllForApp } : {}),
+        ...(opsBlueprintAppMetadataStore ? { appMetadataStore: opsBlueprintAppMetadataStore } : {}),
+        ...(bundle.cacheRegistry ? { cacheRegistry: bundle.cacheRegistry } : {}),
+        ...(input.telemetry ? { telemetry: input.telemetry } : {}),
+        authorizeAppAccess: bundle.authorizeAppAccess,
+    }));
+    handlers.push(createGguiOpsListBlueprintsHandler({
+        blueprintStore: bundle.blueprintStore,
+        blueprintSearch: bundle.blueprintSearch,
+        authorizeAppAccess: bundle.authorizeAppAccess,
+    }));
+    handlers.push(createGguiOpsUpdateBlueprintHandler({
+        blueprintStore: bundle.blueprintStore,
+        authorizeAppAccess: bundle.authorizeAppAccess,
+    }));
+    handlers.push(createGguiOpsDeleteBlueprintHandler({
+        blueprintStore: bundle.blueprintStore,
+        authorizeAppAccess: bundle.authorizeAppAccess,
+    }));
+    return handlers;
+}
 export function defaultHandlers(deps) {
     // Single shared pending-events pipe (Model C, sessionId-keyed).
     // render opens (`markCreated`), submit_action appends, consume drains,
@@ -284,6 +336,30 @@ export function defaultHandlers(deps) {
                 ? { renderIdentityStore: deps.render.renderIdentityStore }
                 : {}),
         }));
+        // `ggui_runtime_pull` — terminal bridge-pull rung of the live-channel
+        // failover ladder (WS → SSE → HTTP polling → bridge-pull). A
+        // CSP-jailed MCP Apps iframe pulls the GguiSessionEvent ledger over
+        // the host's tools/call postMessage relay — same
+        // `_meta.ui.visibility: ['app']` channel as ggui_runtime_submit_action,
+        // same ledger + horizon semantics as `GET /api/sessions/:id/events`
+        // (both read `renderStore.listEventsSince`). Wired only when a
+        // renderStore is bound (render is on) — without render there is no
+        // ledger to serve.
+        handlers.push(createGguiRuntimePullHandler({
+            renderStore: deps.render.renderStore,
+        }));
+        // `ggui_runtime_telemetry` — the iframe runtime's transport
+        // self-report (visibility ['app'], same view-callable channel as
+        // submit_action/pull). Sandboxed hosts (claude.ai's
+        // claudemcpcontent frames) expose no readable console and no
+        // network, so the delivery ladder's behavior there is invisible
+        // WITHOUT this channel: the view batches its rung transitions +
+        // doorbell events and this handler logs them for operators.
+        // Fire-and-forget, store-less — gated on deps.render only because
+        // the ladder it reports on exists only when renders do.
+        handlers.push(createGguiRuntimeTelemetryHandler({
+            ...(deps.logger ? { logger: deps.logger } : {}),
+        }));
         // `ggui_runtime_refresh_ws_token` — G14 (2026-05-23) signed-
         // envelope refresh tool. Registered only when a refresh seam is
         // wired (typically `channelBootstrap.refresh` from the
@@ -351,6 +427,11 @@ export function defaultHandlers(deps) {
                 ? { serverCapabilities: deps.handshake.serverCapabilities }
                 : {}),
             ...(lifecycleEmitter ? { lifecycleEmitter } : {}),
+            // Server-level TelemetrySink → the handler's `handshake.decided`
+            // emission. Without this thread the composed emission never
+            // fired (the handler dep predates the wiring — P2 of
+            // docs/plans/2026-08-19-schema-precise-render.md pinned it).
+            ...(deps.telemetry ? { telemetrySink: deps.telemetry } : {}),
         }));
     }
     if (deps.update) {
@@ -367,11 +448,34 @@ export function defaultHandlers(deps) {
             // re-apply patched props on the live mount without a WS round-trip.
             ...(deps.update.mintBootstrap ? { mintWsToken: deps.update.mintBootstrap } : {}),
             ...(deps.update.runtimeUrl !== undefined ? { runtimeUrl: deps.update.runtimeUrl } : {}),
+            ...(deps.update.sessionApiBaseUrl !== undefined
+                ? { sessionApiBaseUrl: deps.update.sessionApiBaseUrl }
+                : {}),
             ...(deps.update.themeId !== undefined ? { themeId: deps.update.themeId } : {}),
             ...(deps.update.themeMode !== undefined ? { themeMode: deps.update.themeMode } : {}),
             ...(deps.update.themeProvider !== undefined
                 ? { themeProvider: deps.update.themeProvider }
                 : {}),
+            // Mutation-time `render.contract_violation` events (P2
+            // measurement — update-time violations are baselined with
+            // render-time ones, not hidden).
+            ...(deps.telemetry ? { telemetrySink: deps.telemetry } : {}),
+        }));
+        // ggui_amend rides the SAME deps slot (#483 tool split): one
+        // mutation core, one wiring. It reads only the mutation-flow deps
+        // (renderStore / identity / notifier) — the bootstrap-emission
+        // options above are meaningless to a tool that emits no result
+        // meta by design.
+        handlers.push(createGguiAmendHandler({
+            renderStore: deps.update.renderStore,
+            ...(deps.update.renderIdentityStore
+                ? { renderIdentityStore: deps.update.renderIdentityStore }
+                : {}),
+            ...(deps.update.propsUpdateNotifier
+                ? { propsUpdateNotifier: deps.update.propsUpdateNotifier }
+                : {}),
+            // Same mutation core as ggui_update — same violation events.
+            ...(deps.telemetry ? { telemetrySink: deps.telemetry } : {}),
         }));
     }
     // ggui_consume registers whenever render is bound (it shares the
@@ -437,6 +541,12 @@ export function defaultHandlers(deps) {
         handlers.push(createGguiGetSessionHandler({
             renderStore: deps.render.renderStore,
         }));
+        // ggui_get_render_source (#282 data-plane rider) — the calling
+        // app reads its OWN render's generated source. No heartbeat: a
+        // one-shot source read is not an activity signal.
+        handlers.push(createGguiGetRenderSourceHandler({
+            renderStore: deps.render.renderStore,
+        }));
         // ggui_list_sessions — host-scoped render enumeration for resume.
         // Folds the ws-token mint into the same call so the host doesn't
         // round-trip twice (list, then mint-per-render). Reuses the
@@ -515,12 +625,20 @@ export function defaultHandlers(deps) {
                 : {}),
             ...(deps.render.mintBootstrap ? { mintWsToken: deps.render.mintBootstrap } : {}),
             ...(deps.render.runtimeUrl !== undefined ? { runtimeUrl: deps.render.runtimeUrl } : {}),
+            ...(deps.render.sessionApiBaseUrl !== undefined
+                ? { sessionApiBaseUrl: deps.render.sessionApiBaseUrl }
+                : {}),
             ...(deps.render.themeId !== undefined ? { themeId: deps.render.themeId } : {}),
             ...(deps.render.themeMode !== undefined ? { themeMode: deps.render.themeMode } : {}),
             ...(deps.render.themeProvider !== undefined
                 ? { themeProvider: deps.render.themeProvider }
                 : {}),
             ...(deps.render.rateLimiter ? { rateLimiter: deps.render.rateLimiter } : {}),
+            // Render measurement events (`render.attempted` /
+            // `render.contract_violation` / `render.committed`) — P2 of
+            // docs/plans/2026-08-19-schema-precise-render.md. One
+            // server-level sink, every consumer.
+            ...(deps.telemetry ? { telemetrySink: deps.telemetry } : {}),
             ...(deps.render.shortCodeIndex ? { shortCodeIndex: deps.render.shortCodeIndex } : {}),
             ...(deps.render.renderIdentityStore
                 ? { renderIdentityStore: deps.render.renderIdentityStore }
@@ -553,6 +671,9 @@ export function defaultHandlers(deps) {
                 ? {
                     codeStore: deps.render.codeStore,
                     codeBaseUrl: deps.render.codeBaseUrl,
+                    ...(deps.render.mintCodeModuleUrl
+                        ? { mintCodeModuleUrl: deps.render.mintCodeModuleUrl }
+                        : {}),
                 }
                 : {}),
             // Share the handshake KV store between the two handlers so
@@ -565,61 +686,24 @@ export function defaultHandlers(deps) {
             ...(lifecycleEmitter ? { lifecycleEmitter } : {}),
         }));
     }
-    // Operator-class blueprint tools. Registered
-    // on /ops via `audience: ['ops']`. Three read-mutating tools land
-    // whenever the blueprint store + search seam is bound; the
-    // `generate` tool additionally requires `resolveLlm` +
-    // `blueprints` (same deps the render generation path reads). Cloud
-    // pods wire all four through their own composition layer.
+    // Operator-class blueprint tools — see `buildOpsBlueprintHandlers`
+    // for the family's registration rules. The server-level
+    // `deps.appMetadataStore` + `deps.telemetry` are offered as the
+    // bundle's fallbacks; render already gets the server-level store at
+    // :1398. Cloud pods that pass their own handler list pick the same
+    // family up through `buildOpsBundleHandlers`.
     if (deps.opsBlueprint) {
-        if (deps.opsBlueprint.resolveLlm && deps.opsBlueprint.blueprints) {
-            handlers.push(createGguiOpsGenerateBlueprintHandler({
-                registry: deps.opsBlueprint.registry,
-                blueprintStore: deps.opsBlueprint.blueprintStore,
-                resolveLlm: deps.opsBlueprint.resolveLlm,
-                blueprints: deps.opsBlueprint.blueprints,
-                ...(deps.opsBlueprint.putCode ? { putCode: deps.opsBlueprint.putCode } : {}),
-                ...(deps.opsBlueprint.listAllForApp
-                    ? { listAllForApp: deps.opsBlueprint.listAllForApp }
-                    : {}),
-                ...(deps.opsBlueprint.cacheRegistry
-                    ? { cacheRegistry: deps.opsBlueprint.cacheRegistry }
-                    : {}),
-                ...(deps.telemetry ? { telemetry: deps.telemetry } : {}),
-            }));
-        }
-        // `ggui_ops_register_blueprint` — sibling of `_generate_*` that
-        // accepts pre-built componentCode bytes. No LLM dispatch, so it
-        // registers whenever the ops dep bundle is bound (no resolveLlm
-        // / blueprints gate). Operator UX entry point for fixture
-        // seeding + export/reimport round-trips.
-        handlers.push(createGguiOpsRegisterBlueprintHandler({
-            blueprintStore: deps.opsBlueprint.blueprintStore,
-            ...(deps.opsBlueprint.putCode ? { putCode: deps.opsBlueprint.putCode } : {}),
-            ...(deps.opsBlueprint.listAllForApp
-                ? { listAllForApp: deps.opsBlueprint.listAllForApp }
-                : {}),
-            ...(deps.opsBlueprint.cacheRegistry
-                ? { cacheRegistry: deps.opsBlueprint.cacheRegistry }
-                : {}),
+        handlers.push(...buildOpsBlueprintHandlers({
+            bundle: deps.opsBlueprint,
+            ...(deps.appMetadataStore ? { appMetadataStore: deps.appMetadataStore } : {}),
             ...(deps.telemetry ? { telemetry: deps.telemetry } : {}),
         }));
-        handlers.push(createGguiOpsListBlueprintsHandler({
-            blueprintStore: deps.opsBlueprint.blueprintStore,
-            blueprintSearch: deps.opsBlueprint.blueprintSearch,
-        }));
-        handlers.push(createGguiOpsUpdateBlueprintHandler({
-            blueprintStore: deps.opsBlueprint.blueprintStore,
-        }));
-        handlers.push(createGguiOpsDeleteBlueprintHandler({
-            blueprintStore: deps.opsBlueprint.blueprintStore,
-        }));
     }
     return handlers;
 }
 /**
  * Build the operator-class handlers for the apps / orgs /
- * connector-keys / coupon domains. Each domain materializes
+ * connector-keys / coupon / blueprint domains. Each domain materializes
  * independently when its deps seam is bound; deployments that wired
  * none get an empty list.
  *
@@ -650,6 +734,15 @@ export function buildOpsBundleHandlers(deps) {
             coupons: deps.opsCoupon.coupons,
         }));
     }
+    if (deps.opsBlueprint) {
+        // No server-level `appMetadataStore` fallback on this path — the
+        // bundle's own field governs, since a deployment that binds its own
+        // bundle here binds the store with it.
+        handlers.push(...buildOpsBlueprintHandlers({
+            bundle: deps.opsBlueprint,
+            ...(deps.telemetry ? { telemetry: deps.telemetry } : {}),
+        }));
+    }
     return handlers;
 }
 /**
@@ -661,6 +754,9 @@ export function createGguiServer(opts = {}) {
     const info = { ...DEFAULT_INFO, ...opts.info };
     const logger = opts.logger ?? createConsoleLogger({ server: info.name });
     const bodyLimit = opts.bodyLimit ?? "4mb";
+    // Where the content-addressable routes are reached from the iframe:
+    // an explicit asset host, else the public origin (see `codeBaseUrl`).
+    const codeBaseUrl = opts.codeBaseUrl ?? opts.publicBaseUrl;
     // Operator mode: gates the `/devtools/*` namespace. Explicit option
     // wins; otherwise read GGUI_MODE env (`'dev'` opts in, anything else
     // including unset is `'prod'`). Surfaced via `/info` so the SPA
@@ -799,22 +895,40 @@ export function createGguiServer(opts = {}) {
     // pointing at a foreign copy is left untouched, and
     // `runtime.hashedUrl: false` opts out entirely.
     const runtimeBundleHash = runtimeBundleBytes !== undefined && runtimeConfig.hashedUrl !== false
-        ? createHash("sha256").update(runtimeBundleBytes).digest("hex").slice(0, 12)
+        ? computeRuntimeBundleHash(runtimeBundleBytes)
         : undefined;
-    const insertHash = (urlOrPath) => {
-        if (runtimeBundleHash === undefined)
-            return urlOrPath;
-        const plainName = runtimePath.slice(runtimePath.lastIndexOf("/") + 1);
-        const dot = plainName.lastIndexOf(".");
-        const hashedName = dot === -1
-            ? `${plainName}.${runtimeBundleHash}`
-            : `${plainName.slice(0, dot)}.${runtimeBundleHash}${plainName.slice(dot)}`;
-        if (!urlOrPath.endsWith(`/${plainName}`) && urlOrPath !== plainName)
-            return urlOrPath;
-        return `${urlOrPath.slice(0, urlOrPath.length - plainName.length)}${hashedName}`;
-    };
+    const insertHash = (urlOrPath) => runtimeBundleHash === undefined
+        ? urlOrPath
+        : insertRuntimeBundleHash(urlOrPath, runtimeBundleHash, runtimePath.slice(runtimePath.lastIndexOf("/") + 1));
     const hashedRuntimePath = runtimeBundleHash !== undefined ? insertHash(runtimePath) : undefined;
     const runtimeBootstrapUrl = insertHash(runtimeConfig.url ?? runtimePath);
+    // Strict-CSP module-variant family (ggui#522 slice 2). Every
+    // ingredient must exist for any of it to mount: the shim files the
+    // runtime build emitted next to the bundle (the fetchable twins of
+    // the data-url shims), the bundle content hash (the variant KEY —
+    // shims ship in the bundle's dist, so one hash versions both), the
+    // code store (the variant is a `/code` twin), and an absolute code
+    // base URL (the rewrite embeds absolute shim URLs — a srcdoc frame
+    // has no base to resolve relative ones). Missing any ⇒ no variant
+    // URLs are minted and no variant routes mount; renders keep the raw
+    // codeUrl/codeB64 carriers and the renderer's blob ladder.
+    const shimSources = runtimeEnabled && runtimeBundleHash !== undefined
+        ? captureShimSources(runtimeConfig.distDir !== undefined
+            ? path.join(runtimeConfig.distDir, "shims")
+            : RUNTIME_SHIMS_DIR)
+        : undefined;
+    const codeModuleVariant = shimSources !== undefined &&
+        runtimeBundleHash !== undefined &&
+        opts.codeStore !== undefined &&
+        codeBaseUrl !== undefined
+        ? {
+            runtimeHash: runtimeBundleHash,
+            shimBaseUrl: `${codeBaseUrl.replace(/\/$/, "")}${RUNTIME_SHIMS_URL_PREFIX}/${runtimeBundleHash}`,
+        }
+        : undefined;
+    const mintCodeModuleUrl = codeModuleVariant !== undefined
+        ? createCodeModuleUrlMinter({ runtimeHash: codeModuleVariant.runtimeHash })
+        : undefined;
     // Lazy resolver: each render/update handler invocation looks up the
     // request-context-derived absolute base inside the request scope
     // (via AsyncLocalStorage). Static `publicBaseUrl` wins when set;
@@ -1315,6 +1429,14 @@ export function createGguiServer(opts = {}) {
                         // an absolute URL instead of the relative default that
                         // breaks under srcdoc iframes (claude.ai).
                         runtimeUrl: resolveRuntimeUrlForResultMeta,
+                        // Session-API base for `pollingUrl` + `sseUrl` stamping.
+                        // Same lazy request-scope resolution as runtimeUrl:
+                        // static publicBaseUrl wins, X-Forwarded-Host honored
+                        // for loopback peers, `undefined` outside any request —
+                        // the handler then falls back to the minted trio's
+                        // wsUrl origin flip (OSS dev: `ws://localhost/ws` →
+                        // `http://localhost`).
+                        sessionApiBaseUrl: () => resolvePublicBaseUrl(opts.publicBaseUrl),
                         // Forward operator-picked theme onto every
                         // `ai.ggui/render.themeId` slice field so MCP Apps hosts
                         // (claude.ai, Claude Desktop) that mount via the
@@ -1418,18 +1540,22 @@ export function createGguiServer(opts = {}) {
                         //
                         // Content-addressable code delivery. When the operator
                         // wired `opts.codeStore`, forward it to the render
-                        // handler along with the base
-                        // URL the code-blob route resolves to. We prefer the
-                        // explicit `--public-base-url` (so the URL is reachable
-                        // from a remote host's iframe sandbox); when absent we
-                        // fall back to "no codeUrl emission" — the iframe then
+                        // handler along with the base URL the code-blob route
+                        // resolves to: the explicit `codeBaseUrl` (an edge-cached
+                        // asset host, ggui#522) or, absent that, the
+                        // `--public-base-url` (so the URL is reachable from a
+                        // remote host's iframe sandbox); with neither we fall
+                        // back to "no codeUrl emission" — the iframe then
                         // mounts through the live trio and the WS subscribe
                         // carries the render body, which is the delivery path a
                         // render-channel deployment already has.
-                        ...(opts.codeStore && opts.publicBaseUrl
+                        ...(opts.codeStore && codeBaseUrl !== undefined
                             ? {
                                 codeStore: opts.codeStore,
-                                codeBaseUrl: opts.publicBaseUrl,
+                                codeBaseUrl,
+                                ...(mintCodeModuleUrl !== undefined
+                                    ? { mintCodeModuleUrl }
+                                    : {}),
                             }
                             : {}),
                         // Bootstrap-side mirror of the handshake's
@@ -1503,10 +1629,10 @@ export function createGguiServer(opts = {}) {
                             ? { renderIdentityStore: opts.renderIdentityStore }
                             : {}),
                         propsUpdateNotifier: {
-                            sendPropsUpdate: async (sessionId, props) => {
+                            sendPropsUpdate: async (sessionId, props, epoch) => {
                                 if (!channelForHealth)
                                     return;
-                                await channelForHealth.sendPropsUpdate(sessionId, props);
+                                await channelForHealth.sendPropsUpdate(sessionId, props, epoch);
                             },
                         },
                         // Bootstrap-emission deps. Mirror render so MCP Apps hosts
@@ -1520,6 +1646,9 @@ export function createGguiServer(opts = {}) {
                         // same absolute URL when the server sits behind a tunnel
                         // / reverse proxy.
                         runtimeUrl: resolveRuntimeUrlForResultMeta,
+                        // Session-API base — matches render so both tools stamp
+                        // identical `pollingUrl` + `sseUrl` values.
+                        sessionApiBaseUrl: () => resolvePublicBaseUrl(opts.publicBaseUrl),
                         ...(opts.theme !== undefined && opts.theme.source === "preset"
                             ? { themeId: opts.theme.preset }
                             : {}),
@@ -1549,42 +1678,48 @@ export function createGguiServer(opts = {}) {
             // `appMetadataStore` to register `ggui_list_themes`; absent ⇒
             // tool omitted from `tools/list`.
             ...(opts.themes ? { themes: opts.themes } : {}),
-            // Operator-class blueprint tool wiring. Threads the
-            // resolved blueprint store + search + generator registry into
-            // defaultHandlers; the four `ggui_ops_*` tools land on /ops
-            // via their `audience: ['ops']` tag. The `resolveLlm` +
-            // `blueprints` deps come from the same source render reads, so
-            // generate dispatches through the same credential + catalog
-            // path as live agent traffic. listAllForApp wires only when
-            // the resolved store is the in-memory adapter (which exposes
-            // it); cloud adapters bind their own listAllForApp via the
-            // search seam.
-            // Wire only when we have a resolved generator
-            // registry. Without `generators`, the ops `generate` path has
-            // no dispatch target; the list/update/delete trio could
-            // technically run without it but the operator UX expects all
-            // four together, so we gate the whole block on the registry.
-            ...(generators
-                ? buildOpsBlueprintDeps({
-                    registry: generators,
-                    blueprintStore,
-                    blueprintSearch,
-                    ...(generationWithCache?.resolveLlm
-                        ? { resolveLlm: generationWithCache.resolveLlm }
-                        : {}),
-                    ...(generationWithCache?.blueprints
-                        ? { blueprints: generationWithCache.blueprints }
-                        : opts.blueprintProvider
-                            ? { blueprints: opts.blueprintProvider }
+            // Operator-class blueprint tool wiring. Explicit-wins: a
+            // deployment that supplies `opts.opsBlueprint` gets that bundle
+            // threaded through AS-IS (its own store/search/registry/
+            // authorizer — the factory does not assemble or override it).
+            // Otherwise falls back to the OSS default assembly below, which
+            // threads the resolved blueprint store + search + generator
+            // registry into defaultHandlers; the five `ggui_ops_*` tools
+            // land on the control plane via their `audience: ['ops']` tag.
+            // The `resolveLlm` + `blueprints` deps come from the same
+            // source render reads, so generate dispatches through the same
+            // credential + catalog path as live agent traffic.
+            // listAllForApp wires only when the resolved store is the
+            // in-memory adapter (which exposes it); cloud adapters bind
+            // their own listAllForApp via the search seam.
+            // The fallback is gated on `generators`: without it, the ops
+            // `generate` path has no dispatch target; the
+            // register/list/update/delete quartet could technically run
+            // without it but the operator UX expects all five together, so
+            // we gate the whole block on the registry.
+            ...(opts.opsBlueprint
+                ? { opsBlueprint: opts.opsBlueprint }
+                : generators
+                    ? buildOpsBlueprintDeps({
+                        registry: generators,
+                        blueprintStore,
+                        blueprintSearch,
+                        ...(generationWithCache?.resolveLlm
+                            ? { resolveLlm: generationWithCache.resolveLlm }
                             : {}),
-                    // Mirror operator-authored blueprints into the cache
-                    // vectorStore so the agent-facing matchBlueprint exact-
-                    // key probe (handshake + render) finds them. Same bundle
-                    // the render handler + handshake negotiator already
-                    // consume.
-                    ...(generationWithCache?.cache ? { cacheRegistry: generationWithCache.cache } : {}),
-                })
-                : {}),
+                        ...(generationWithCache?.blueprints
+                            ? { blueprints: generationWithCache.blueprints }
+                            : opts.blueprintProvider
+                                ? { blueprints: opts.blueprintProvider }
+                                : {}),
+                        // Mirror operator-authored blueprints into the cache
+                        // vectorStore so the agent-facing matchBlueprint exact-
+                        // key probe (handshake + render) finds them. Same bundle
+                        // the render handler + handshake negotiator already
+                        // consume.
+                        ...(generationWithCache?.cache ? { cacheRegistry: generationWithCache.cache } : {}),
+                    })
+                    : {}),
             // ggui_emit resolves the channel via
             // a lazy getter so the handler captures whatever
             // `channelForHealth` ends up pointing at after
@@ -1600,11 +1735,13 @@ export function createGguiServer(opts = {}) {
             logger,
         });
     // Operator-class domain handlers (apps / orgs / connector-keys /
-    // coupon). Built on EVERY path — they hang off their own explicit
-    // options, so a deployment that supplies a custom base handler list
-    // still gets the domains it wired. A name already claimed by the base
-    // list wins: that's how the cloud pod ships its own
-    // `ggui_ops_create_app` while still picking up the rest of the family.
+    // coupon / blueprints). Built on EVERY path — they hang off their own
+    // explicit options, so a deployment that supplies a custom base
+    // handler list still gets the domains it wired. A name already claimed
+    // by the base list wins: that's how the cloud pod ships its own
+    // `ggui_ops_create_app` while still picking up the rest of the family,
+    // and it is what keeps the blueprint family single-registered when the
+    // default handler set already built it from the same bundle.
     const baseHandlerNames = new Set(baseHandlers.map((h) => h.name));
     const opsBundleHandlers = buildOpsBundleHandlers(opts).filter((h) => !baseHandlerNames.has(h.name));
     const handlers = composeHandlersWithMounts(opsBundleHandlers.length > 0 ? [...baseHandlers, ...opsBundleHandlers] : baseHandlers, opts.mcpMounts);
@@ -1772,6 +1909,7 @@ export function createGguiServer(opts = {}) {
             buildResourceValidator({
                 universalMcpPath: opts.universalMcpPath ?? "/mcp",
                 perAppRouting: opts.perAppRouting,
+                controlPath: CONTROL_PATH,
             }),
     };
     const oauthStorage = oauthConfig.storage ?? new InMemoryOAuthStorage();
@@ -1785,6 +1923,7 @@ export function createGguiServer(opts = {}) {
             oauthConfig,
             oauthStorage,
             universalMcpPath: opts.universalMcpPath ?? "/mcp",
+            controlPath: CONTROL_PATH,
             ...(opts.perAppRouting !== undefined
                 ? {
                     perAppRouting: {
@@ -1811,6 +1950,7 @@ export function createGguiServer(opts = {}) {
         info,
         toolCount: handlers.length,
         readinessChecks: opts.readinessChecks ?? [],
+        advisoryChecks: opts.advisoryChecks ?? [],
         getChannel: () => channelForHealth,
         ...(opts.threads !== undefined
             ? {
@@ -1868,6 +2008,18 @@ export function createGguiServer(opts = {}) {
         // (`connect-src 'none'`) blocks the iframe from fetching the
         // runtime bundle and opening the WebSocket.
         ...(opts.publicBaseUrl !== undefined ? { publicBaseUrl: opts.publicBaseUrl } : {}),
+        // Live-channel origins for the static shell's CSP declaration:
+        // the WS endpoint + its http-origin flip (the session-API base the
+        // sseUrl/pollingUrl stamps derive from when `publicBaseUrl` is
+        // unset — the cloud pod's posture, see compose.ts's Origin/Host
+        // ruling). Cross-origin hosts (claude.ai) build the frame CSP from
+        // the STATIC shell resource they mount; per-render declarations
+        // never reach it, so without these entries every network rung of
+        // the failover ladder (WS, SSE, HTTP polling) is `connect-src`-
+        // blocked in the frame — observed live in #471 round 11.
+        ...(mcpAppsEnabled
+            ? { extraConnectUrls: [wsUrl, wsOriginToHttpOrigin(wsUrl)] }
+            : {}),
         // Per-render self-contained shell registration. Only wired
         // when MCP Apps is on AND the render store is resolved —
         // both preconditions for `ggui_render.resultMeta` stamping a
@@ -1892,6 +2044,13 @@ export function createGguiServer(opts = {}) {
                     ...(opts.theme !== undefined && opts.theme.source !== "default"
                         ? { themeMode: opts.theme.mode }
                         : {}),
+                    // The live pick reaches the read door too (ggui#539) — same
+                    // getter the render handler's deps carry, so the FIRST
+                    // resolution layer is identical across the tool-result
+                    // slice and the served shell.
+                    ...(opts.themeProvider !== undefined
+                        ? { themeProvider: opts.themeProvider }
+                        : {}),
                     // Resume contract — registry-only fallback. Wired
                     // when the blueprint vector store is available so the
                     // resource handler can rehydrate a render-evicted
@@ -1930,10 +2089,13 @@ export function createGguiServer(opts = {}) {
                     // shell that would never paint. Wiring both (the shape
                     // this factory produces) also means a fault on one
                     // degrades to the other instead of failing the read.
-                    ...(opts.codeStore && opts.publicBaseUrl
+                    ...(opts.codeStore && codeBaseUrl !== undefined
                         ? {
                             codeStore: opts.codeStore,
-                            codeBaseUrl: opts.publicBaseUrl,
+                            codeBaseUrl,
+                            ...(mintCodeModuleUrl !== undefined
+                                ? { mintCodeModuleUrl }
+                                : {}),
                         }
                         : {}),
                     // Bind the app-metadata store so the resource
@@ -2000,6 +2162,7 @@ export function createGguiServer(opts = {}) {
         ...(opts.allowedKinds !== undefined ? { allowedKinds: opts.allowedKinds } : {}),
         ...(resolvedInstructions !== undefined ? { instructions: resolvedInstructions } : {}),
         ...(opts.extraResources !== undefined ? { extraResources: opts.extraResources } : {}),
+        ...(opts.withholdResultMeta === true ? { withholdResultMeta: true } : {}),
     };
     // MCP wire endpoints (data plane: universal / per-app; control
     // plane: /control; plus any isolated services) — see
@@ -2014,6 +2177,7 @@ export function createGguiServer(opts = {}) {
         info,
         handlers,
         controlHandlers: controlService.handlers,
+        controlOpsToolNames: controlService.opsToolNames,
         mcpServices,
         als,
         appIdFromIdentity,
@@ -2043,6 +2207,20 @@ export function createGguiServer(opts = {}) {
                 ? { hashed: { path: hashedRuntimePath, source: runtimeBundleBytes } }
                 : {}),
         });
+        // Static shim assets (ggui#522 slice 2) — the fetchable twins of
+        // the data-url import shims, served immutable under the runtime
+        // bundle's content hash. Mounted whenever the build shipped them
+        // (independent of the code store: the `/code` variant route is the
+        // usual consumer, but a foreign composition may rewrite against
+        // these shims itself).
+        if (shimSources !== undefined && runtimeBundleHash !== undefined) {
+            mountShimRoutes({
+                app,
+                urlPrefix: RUNTIME_SHIMS_URL_PREFIX,
+                runtimeHash: runtimeBundleHash,
+                shims: shimSources,
+            });
+        }
     }
     // R6 /state snapshot + R7 /events cursor-replay reads — see
     // `./api-renders-routes.ts` for the wsToken auth posture, tenancy
@@ -2063,16 +2241,41 @@ export function createGguiServer(opts = {}) {
                 : {}),
             ...(opts.codeStore ? { codeStore: opts.codeStore } : {}),
             ...(opts.publicBaseUrl !== undefined ? { publicBaseUrl: opts.publicBaseUrl } : {}),
+            // Asset host for the content-addressable URLs the /state read
+            // composes (ggui#522) — session-API URLs keep the public origin.
+            ...(opts.codeBaseUrl !== undefined ? { codeBaseUrl: opts.codeBaseUrl } : {}),
+            ...(mintCodeModuleUrl !== undefined ? { mintCodeModuleUrl } : {}),
             ...(mintBootstrap ? { mintBootstrap } : {}),
             resolveRuntimeUrl: resolveRuntimeUrlForResultMeta,
             logger,
         });
+        // SSE live stream (the ladder's middle rung) — same wsToken auth
+        // posture as /state and /events; see `./api-renders-stream-route.ts`
+        // for the framing contract. The channel is late-bound via the same
+        // `() => channelForHealth` pattern as `stream.channelProvider`:
+        // route mounting runs before `createGguiSessionChannelServer`, and
+        // the mcpApps ⇒ renderChannel throw above guarantees a channel
+        // exists by listen time.
+        mountApiRendersStreamRoute({
+            app,
+            renderStore,
+            secret: sharedTokenSecret,
+            channelProvider: () => channelForHealth,
+            logger,
+        });
     }
     // Content-addressable code + contract-validator delivery — see
     // `./code-routes.ts` for the route contract (cache posture, CORS,
     // hash validation).
     if (opts.codeStore) {
-        mountCodeRoutes({ app, codeStore: opts.codeStore, logger });
+        mountCodeRoutes({
+            app,
+            codeStore: opts.codeStore,
+            logger,
+            ...(codeModuleVariant !== undefined
+                ? { moduleVariant: codeModuleVariant }
+                : {}),
+        });
     }
     // Pairing transport + auth bridge. Opt-in via `opts.pairing`. When
     // enabled with defaults, we mint an `InMemoryPairingService` and wire
@@ -2975,7 +3178,7 @@ export function createGguiServer(opts = {}) {
  * Build the {@link OAuthConfig.validateResource} callback from the
  * deployment shape (RFC 8707).
  *
- * Two valid resource shapes are recognized:
+ * Three valid resource shapes are recognized:
  *   - **Universal** — exactly `${issuer}` when `universalMcpPath` is
  *     `/`, otherwise `${issuer}${universalMcpPath}`. Cloud
  *     `mcp.ggui.ai` collapses the bare-root case (the domain already
@@ -2983,6 +3186,11 @@ export function createGguiServer(opts = {}) {
  *   - **Per-app** — `${issuer}${perAppRouting.pathPrefix}/<appId>`
  *     where `<appId>` matches `perAppRouting.paramPattern`. Cloud
  *     uses `/apps` prefix + `[A-Za-z0-9]{8}`.
+ *   - **Control plane** — `${issuer}${controlPath}` (ggui#505). A
+ *     host naming `/control` consents through the same ceremony and
+ *     receives a UNIVERSAL key: the consent page extracts an appId
+ *     only from the per-app shape, and control-plane ops are
+ *     account-level by design.
  *
  * Anything else returns `false` → /authorize emits `invalid_target`
  * per RFC 8707 §2 before showing consent. Defense-in-depth — the
@@ -2990,7 +3198,7 @@ export function createGguiServer(opts = {}) {
  * can trust the value because it's already been validated.
  */
 function buildResourceValidator(opts) {
-    const { universalMcpPath, perAppRouting } = opts;
+    const { universalMcpPath, perAppRouting, controlPath } = opts;
     // Normalize a single trailing slash on the path-only-root form. RFC
     // 3986 §6.2.3 says `https://host` and `https://host/` are equivalent
     // when no other path segments follow. Some clients (claude.ai 2026-05)
@@ -3003,6 +3211,10 @@ function buildResourceValidator(opts) {
         const universalResource = universalMcpPath === "/" ? issuer : `${issuer}${universalMcpPath}`;
         if (stripTrailingSlash(resource) === stripTrailingSlash(universalResource))
             return true;
+        if (controlPath !== undefined &&
+            stripTrailingSlash(resource) === stripTrailingSlash(`${issuer}${controlPath}`)) {
+            return true;
+        }
         if (!perAppRouting)
             return false;
         const { paramPattern, pathPrefix = "" } = perAppRouting;