@ggui-ai/cli 0.1.0-rc.3 → 0.2.0-alpha.1

package/dist/mcp-backend.js

@@ -19,62 +19,61 @@
  *   - `console: { sessionCookie: true }` — landing page at `/` +
  *     `/s/<shortCode>` viewer + same-origin HTTP-only cookie flow.
  *   - `shortCodeIndex: new InMemoryShortCodeIndex()` — required by
- *     the `sessionCookie` flow so `POST /ggui/console/session-cookie`
- *     can resolve a posted shortCode to `{sessionId, appId}`.
- *     In-memory is correct for the OSS first-run: session state lives
+ *     the `sessionCookie` flow so `POST /ggui/console/render-cookie`
+ *     can resolve a posted shortCode to the bound `{renderId, appId}`.
+ *     In-memory is correct for the OSS first-run: render state lives
  *     in memory unless the operator opts into sqlite, so a matching
  *     index lifetime is what operators expect.
- *   - `mcpApps: { renderBaseUrl, wsUrl }` — registers the `ggui_push`
- *     tool with MCP Apps `_meta.ui.*` declaration, serves
- *     `ui://ggui/session`, and advertises the `io.modelcontextprotocol/ui`
- *     capability. Without this the console `/s/<shortCode>` viewer
- *     is orphaned — there's no tool minting shortCodes. Resolved host +
- *     port are mandatory so the agent-returned `url` resolves to this
- *     same server's `/s/` endpoint. See §2.4.1 "sole entry-point tool"
- *     lock in the OSS-split plan.
+ *   - `mcpApps: { wsUrl }` — registers the `ggui_render` tool with
+ *     MCP Apps `_meta.ui.*` declaration, serves `ui://ggui/render`,
+ *     and advertises the `io.modelcontextprotocol/ui` capability.
+ *     `wsUrl` is the live-channel URL the spawned iframe subscribes
+ *     to; resolved host + port are mandatory so it points back at
+ *     this same process. See §2.4.1 "sole entry-point tool" lock
+ *     in the OSS-split plan.
  *
  * Embedding hosts that want a different shape (no landing page, no
  * pairing, programmatic control) compose `createGguiServer()` directly
  * rather than going through `ggui serve`.
  */
-import { createServer as createNetServer } from 'node:net';
-import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { composeWiredActionRouterFromMounts, createGguiServer, DEFAULT_BUILDER_APP_ID, FileSystemCodeStore, FixedWindowRateLimiter, InMemoryAuthAdapter, InMemoryQuotaStore, InMemoryShortCodeIndex, selectEmailSenderFromEnv, } from '@ggui-ai/mcp-server';
-import { createDeterministicPreviewEmitter } from '@ggui-ai/preview-a2ui/emitters';
-import { RUNTIME_BUNDLE_URL_PATH } from '@ggui-ai/iframe-runtime/server';
-import { createLocalEmbeddingProvider } from '@ggui-ai/embedding-local';
-import { PlaintextFileProviderKeyStore } from '@ggui-ai/mcp-server-core/plaintext';
-import { InMemoryAppMetadataStore, InMemoryVectorStore } from '@ggui-ai/mcp-server-core/in-memory';
-import { listThemes } from '@ggui-ai/design/themes';
-import { createInstalledBlueprintsProvider, } from '@ggui-ai/mcp-server-handlers/session-mutations';
-import { compileUiOnDemand } from '@ggui-ai/dev-stack';
-import { getCodeCacheDir, getCredentialsFile, getEmbeddingCacheDir, } from './paths.js';
-import { readOrMintHexSecret } from './persistent-secrets.js';
-import { join } from 'node:path';
+import { listThemes } from "@ggui-ai/design/themes";
+import { compileUiOnDemand } from "@ggui-ai/dev-stack";
+import { createLocalEmbeddingProvider } from "@ggui-ai/embedding-local";
+import { RUNTIME_BUNDLE_URL_PATH } from "@ggui-ai/iframe-runtime/server";
+import { composeWiredActionRouterFromMounts, createGguiServer, DEFAULT_BUILDER_APP_ID, FileSystemCodeStore, FixedWindowRateLimiter, InMemoryAuthAdapter, InMemoryQuotaStore, InMemoryShortCodeIndex, selectEmailSenderFromEnv, } from "@ggui-ai/mcp-server";
+import { InMemoryAppMetadataStore, InMemoryVectorStore } from "@ggui-ai/mcp-server-core/in-memory";
+import { PlaintextFileProviderKeyStore } from "@ggui-ai/mcp-server-core/plaintext";
+import { createInstalledBlueprintsProvider, } from "@ggui-ai/mcp-server-handlers/renders";
+import { createDeterministicPreviewEmitter } from "@ggui-ai/preview-a2ui/emitters";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { createServer as createNetServer } from "node:net";
+import { join } from "node:path";
+import { getCodeCacheDir, getCredentialsFile, getEmbeddingCacheDir } from "./paths.js";
+import { readOrMintHexSecret } from "./persistent-secrets.js";
 /**
  * Pick a free localhost TCP port by letting the OS assign one on a
  * throwaway listener. Close the listener immediately and return the
  * chosen number. Exported so the CLI (`cli.ts::runServeCommand`) and
  * the integration tests can resolve `--port 0` to a concrete port
  * BEFORE constructing the backend — {@link buildMcpServerBackend}
- * captures the port in the composed `mcpApps.renderBaseUrl` / `wsUrl`
+ * captures the port in the composed `mcpApps.wsUrl` / `runtime.url`
  * at construction time, so the caller must know it up-front.
  *
  * Tiny race window: another process could claim the port between our
  * `close()` and the caller's `listen()`. The CLI surfaces bind errors
  * as a fatal exit; the OSS first-run path recovers by re-running.
  */
-export function pickFreePort(host = '127.0.0.1') {
+export function pickFreePort(host = "127.0.0.1") {
     return new Promise((resolve, reject) => {
         const probe = createNetServer();
-        probe.once('error', (err) => {
+        probe.once("error", (err) => {
             probe.close();
             reject(err);
         });
         probe.listen(0, host, () => {
             const addr = probe.address();
-            if (addr === null || typeof addr === 'string') {
+            if (addr === null || typeof addr === "string") {
                 probe.close();
                 reject(new Error(`pickFreePort: could not resolve a free port (got ${String(addr)})`));
                 return;
@@ -96,15 +95,15 @@ export function buildMcpServerBackend(opts) {
     if (!Number.isInteger(opts.port) || opts.port <= 0 || opts.port > 65535) {
         throw new Error(`buildMcpServerBackend: \`port\` must be a concrete TCP port (1..65535), got ${opts.port}. Resolve \`--port 0\` via pickFreePort() before composing.`);
     }
-    // `baseUrl` feeds `mcpApps.renderBaseUrl` + `runtime.url`; `wsBaseUrl`
-    // feeds `mcpApps.wsUrl`. With `--public-base-url`, both derive from
-    // the operator-provided tunnel URL so the agent emits links that
-    // resolve from the remote host's perspective. Without it, both fall
-    // back to the local bind. The shape was validated at flag-parse
-    // time (`http://`/`https://`, no trailing slash); we just substitute
-    // the scheme for ws/wss to derive the live-channel URL.
+    // `baseUrl` feeds `runtime.url`; `wsBaseUrl` feeds `mcpApps.wsUrl`.
+    // With `--public-base-url`, both derive from the operator-provided
+    // tunnel URL so the URLs the iframe receives resolve from the remote
+    // host's perspective. Without it, both fall back to the local bind.
+    // The shape was validated at flag-parse time (`http://`/`https://`,
+    // no trailing slash); we just substitute the scheme for ws/wss to
+    // derive the live-channel URL.
     const baseUrl = opts.publicBaseUrl ?? `http://${opts.host}:${opts.port}`;
-    const wsBaseUrl = baseUrl.replace(/^http(s?):\/\//, 'ws$1://');
+    const wsBaseUrl = baseUrl.replace(/^http(s?):\/\//, "ws$1://");
     // Router over the mount handler bundle. Computed once; absent
     // (`null`) when no mounts are declared so the server falls through
     // to agent-routed behavior.
@@ -136,7 +135,7 @@ export function buildMcpServerBackend(opts) {
     });
     // Per-IP rate limiter — only bound under `--public-demo` so an
     // anonymous visitor can't burn the operator's BYOK budget by pumping
-    // ggui_push. Defaults: 30 generations / 10 minutes per IP. Operators
+    // ggui_render. Defaults: 30 generations / 10 minutes per IP. Operators
     // who need different ceilings construct their own backend
     // programmatically (calling `createGguiServer({ rateLimiter })`
     // directly). Skipped under `--dev-allow-all` because that's the
@@ -186,8 +185,8 @@ export function buildMcpServerBackend(opts) {
     const emailSenderSelection = selectEmailSenderFromEnv();
     let emailSender;
     let emailFromAddress;
-    const defaultFromAddress = 'ggui-serve <noreply@localhost>';
-    if (emailSenderSelection.kind === 'ok') {
+    const defaultFromAddress = "ggui-serve <noreply@localhost>";
+    if (emailSenderSelection.kind === "ok") {
         emailSender = emailSenderSelection.sender;
         emailFromAddress = emailSenderSelection.fromAddress ?? defaultFromAddress;
     }
@@ -195,26 +194,26 @@ export function buildMcpServerBackend(opts) {
         // eslint-disable-next-line no-console -- one-shot boot warning, mirrors banner output
         console.warn(`[ggui-cli] email-login: ${emailSenderSelection.reason}; falling back to ConsoleEmailSender (magic links print to terminal).`);
         const fallback = selectEmailSenderFromEnv({
-            env: { GGUI_EMAIL_SENDER: 'console' },
+            env: { GGUI_EMAIL_SENDER: "console" },
         });
-        if (fallback.kind !== 'ok') {
+        if (fallback.kind !== "ok") {
             throw new Error(`[ggui-cli] email-login: console fallback selection failed: ${fallback.reason}`);
         }
         emailSender = fallback.sender;
         emailFromAddress = process.env.GGUI_EMAIL_FROM?.trim() || defaultFromAddress;
     }
     // Resolve cross-restart HMAC secrets. When the caller declared a
-    // persistent dir, read-or-mint `bootstrap-secret.hex` +
+    // persistent dir, read-or-mint `ws-token-secret.hex` +
     // `render-signer-secret.hex` (32 bytes / 64 hex chars, 0600). Both
     // get threaded into `createGguiServer` below so the server stops
     // minting fresh process-local secrets every boot — the precondition
-    // for any cached `_meta.ggui.bootstrap.token` or `/r/<code>?sig=&exp=`
-    // URL surviving a restart. Absent dir = legacy ephemeral behavior.
-    let persistedBootstrapSecret;
+    // for any cached `_meta["ai.ggui/render"].wsToken` surviving a
+    // restart. Absent dir = legacy ephemeral behavior.
+    let persistedWsTokenSecret;
     let persistedRenderSignerSecret;
     if (opts.persistentDir !== undefined) {
-        persistedBootstrapSecret = readOrMintHexSecret(join(opts.persistentDir, 'bootstrap-secret.hex'));
-        persistedRenderSignerSecret = readOrMintHexSecret(join(opts.persistentDir, 'render-signer-secret.hex'));
+        persistedWsTokenSecret = readOrMintHexSecret(join(opts.persistentDir, "ws-token-secret.hex"));
+        persistedRenderSignerSecret = readOrMintHexSecret(join(opts.persistentDir, "render-signer-secret.hex"));
     }
     // Resolve mcpInstructions: CLI flag wins over env var. Validated
     // env-var values pass through to createGguiServer; invalid values
@@ -222,11 +221,11 @@ export function buildMcpServerBackend(opts) {
     const envInstructions = process.env.GGUI_MCP_INSTRUCTIONS?.trim();
     let resolvedMcpInstructions = opts.mcpInstructions;
     if (resolvedMcpInstructions === undefined && envInstructions) {
-        if (envInstructions === 'default' ||
-            envInstructions === 'aggressive' ||
-            envInstructions === 'always' ||
-            envInstructions === 'minimal' ||
-            envInstructions === 'off') {
+        if (envInstructions === "default" ||
+            envInstructions === "aggressive" ||
+            envInstructions === "always" ||
+            envInstructions === "minimal" ||
+            envInstructions === "off") {
             resolvedMcpInstructions = envInstructions;
         }
         else {
@@ -242,11 +241,9 @@ export function buildMcpServerBackend(opts) {
     // `listThemes()` either way; the file-mode override only affects the
     // server's bound `theme` (rendered CSS variables), not the
     // session/handler-side `themeId` chain.
-    const manifestThemePreset = opts.theme?.source === 'preset' ? opts.theme.preset : undefined;
+    const manifestThemePreset = opts.theme?.source === "preset" ? opts.theme.preset : undefined;
     const appMetadataStore = new InMemoryAppMetadataStore({
-        ...(manifestThemePreset !== undefined
-            ? { defaultThemeId: manifestThemePreset }
-            : {}),
+        ...(manifestThemePreset !== undefined ? { defaultThemeId: manifestThemePreset } : {}),
         // `ggui.json#app.gadgets` declarations (Leaflet, Mapbox, …). When
         // omitted, the InMemoryAppMetadataStore falls back to
         // STDLIB_GADGETS from @ggui-ai/protocol so the first-party hooks
@@ -262,11 +259,10 @@ export function buildMcpServerBackend(opts) {
         ...(opts.publicEnv !== undefined && Object.keys(opts.publicEnv).length > 0
             ? { defaultPublicEnv: opts.publicEnv }
             : {}),
-        // `ggui.json#app.defaultMcpAppsMode`. `'canvas'` makes
-        // `ggui_new_session` mint a session-scoped iframe + route
-        // subsequent pushes through the session channel; absent ⇒ inline.
-        ...(opts.defaultMcpAppsMode !== undefined
-            ? { defaultMcpAppsMode: opts.defaultMcpAppsMode }
+        // `ggui.json#app.defaultDisplayMode`. Stamped per-push as
+        // `_meta.ui.displayMode`; controls only host-side presentation.
+        ...(opts.defaultDisplayMode !== undefined
+            ? { defaultDisplayMode: opts.defaultDisplayMode }
             : {}),
     });
     // Materialize the vectorStore here so the marketplace-install
@@ -292,9 +288,7 @@ export function buildMcpServerBackend(opts) {
             installedBlueprints: () => entries.flatMap((entry) => {
                 if (entry.manifest.contract === undefined)
                     return [];
-                const intent = entry.manifest.description ??
-                    entry.manifest.name ??
-                    entry.id;
+                const intent = entry.manifest.description ?? entry.manifest.name ?? entry.id;
                 return [
                     {
                         id: entry.id,
@@ -307,21 +301,21 @@ export function buildMcpServerBackend(opts) {
             compile: async (entry) => {
                 const ui = byId.get(entry.id);
                 if (!ui) {
-                    return { kind: 'missing-entry', tried: [] };
+                    return { kind: "missing-entry", tried: [] };
                 }
                 const result = await compileUiOnDemand({
                     projectRoot,
                     manifestPath: ui.manifestPath,
                     manifest: ui.manifest,
                 });
-                if (result.kind === 'ok') {
-                    return { kind: 'ok', code: result.code };
+                if (result.kind === "ok") {
+                    return { kind: "ok", code: result.code };
                 }
-                if (result.kind === 'missing-entry') {
-                    return { kind: 'missing-entry', tried: result.tried };
+                if (result.kind === "missing-entry") {
+                    return { kind: "missing-entry", tried: result.tried };
                 }
                 return {
-                    kind: 'failure',
+                    kind: "failure",
                     errors: result.errors.map((m) => m.text),
                 };
             },
@@ -330,8 +324,7 @@ export function buildMcpServerBackend(opts) {
                 process.stderr.write(`[ggui serve] installed-blueprint ${issue.id}: ${issue.kind}: ${issue.message}\n`);
             },
         };
-        installedBlueprintsProvider =
-            createInstalledBlueprintsProvider(providerOptions);
+        installedBlueprintsProvider = createInstalledBlueprintsProvider(providerOptions);
     }
     // Fold the bridge into the generation deps so the push handler +
     // handshake negotiator both consume it via `MatchBlueprintDeps.
@@ -351,8 +344,8 @@ export function buildMcpServerBackend(opts) {
         providerKeys,
         // Seeded per-app metadata store. Threaded so the in-process
         // singleton is shared across `ggui_list_gadgets`,
-        // `ggui_list_themes`, `ggui_new_session` (theme default
-        // resolution), and the handshake (gadgets lookup).
+        // `ggui_list_themes`, and the handshake (gadgets + theme default
+        // resolution).
         appMetadataStore,
         // Theme catalog resolver. Reads from `@ggui-ai/design`'s registry
         // each call so runtime additions surface without a restart.
@@ -365,29 +358,23 @@ export function buildMcpServerBackend(opts) {
         // process. Render-signer.secret rides on the `renderSigning`
         // discriminated union (the `false` shape disables the layer
         // entirely; we always want it on here, so build the object form).
-        ...(persistedBootstrapSecret !== undefined
-            ? { bootstrapSecret: persistedBootstrapSecret }
-            : {}),
+        ...(persistedWsTokenSecret !== undefined ? { wsTokenSecret: persistedWsTokenSecret } : {}),
         ...(persistedRenderSignerSecret !== undefined
             ? { renderSigning: { secret: persistedRenderSignerSecret } }
             : {}),
-        ...(resolvedMcpInstructions !== undefined
-            ? { mcpInstructions: resolvedMcpInstructions }
-            : {}),
+        ...(resolvedMcpInstructions !== undefined ? { mcpInstructions: resolvedMcpInstructions } : {}),
         // `--multi-tenant` flips the `/ggui/console/llm-keys` gate from
         // admin-token to auth-adapter. Default scope derivation in the
         // server picks up `userId` / `appId` from the resolved identity;
         // operators with composite scopes pass their own `providerKeyScope`
         // by composing `createGguiServer` directly.
-        ...(opts.multiTenant
-            ? { providerKeysGate: 'auth-adapter' }
-            : {}),
+        ...(opts.multiTenant ? { providerKeysGate: "auth-adapter" } : {}),
         // Gate OAuth login routes on publicBaseUrl. Without it the
         // redirect_uri can't be composed; the admin transport still mounts
         // so operators can paste credentials in advance.
         ...(opts.publicBaseUrl ? { publicBaseUrl: opts.publicBaseUrl } : {}),
         ...(rateLimiter ? { rateLimiter } : {}),
-        ...(storage.sessionStore ? { sessionStore: storage.sessionStore } : {}),
+        ...(storage.renderStore ? { renderStore: storage.renderStore } : {}),
         // Always pass the materialized vectorStore so the install bridge
         // and the matcher share state. Passing only `storage.vectors`
         // (set when the manifest declares sqlite) would, on an absent
@@ -406,16 +393,12 @@ export function buildMcpServerBackend(opts) {
             ? {
                 threads: {
                     store: storage.threadStore,
-                    ...(storage.threadDurability
-                        ? { durability: storage.threadDurability }
-                        : {}),
+                    ...(storage.threadDurability ? { durability: storage.threadDurability } : {}),
                 },
             }
             : {}),
         sessionChannel: true,
-        pairing: opts.keysFile
-            ? { persistencePath: opts.keysFile }
-            : true,
+        pairing: opts.keysFile ? { persistencePath: opts.keysFile } : true,
         // Email magic-link login. OSS first-run default mirrors
         // `provisionalPreview` — wire a sender so magic links can be
         // delivered. `selectEmailSenderFromEnv` reads
@@ -464,7 +447,7 @@ export function buildMcpServerBackend(opts) {
                         !!process.env.GOOGLE_API_KEY ||
                         !!process.env.OPENROUTER_API_KEY;
                     if (!credsFileExists && !anyEnvKey) {
-                        return '/admin-login?next=%2Fadmin%2Fllm-keys';
+                        return "/admin-login?next=%2Fadmin%2Fllm-keys";
                     }
                     return null;
                 }
@@ -479,10 +462,10 @@ export function buildMcpServerBackend(opts) {
         // absent = no welcome page (SPA index handler still owns `/`).
         ...(opts.welcomePage ? { welcomePage: opts.welcomePage } : {}),
         // Default to in-memory; caller substitutes a persistent impl
-        // (SqliteShortCodeIndex under `persistentDir`) so cached
-        // `/api/bootstrap/<code>` lookups survive a restart. Without
-        // that, /r/<code> 404s the moment the agent's host (claude.ai)
-        // replays its cached `_meta.ggui.bootstrap` envelope.
+        // (SqliteShortCodeIndex under `persistentDir`) so cached short-code
+        // lookups survive a restart. Used by render-URL signing and
+        // legacy compat paths; post-R5 the primary mount path is the
+        // ui://ggui/render resource (auth-bearer-gated), not shortCodes.
         shortCodeIndex: opts.shortCodeIndex ?? new InMemoryShortCodeIndex(),
         // Content-addressable componentCode delivery. The OSS dev default
         // is filesystem-backed at `~/.ggui/code-cache/` (override via
@@ -495,9 +478,7 @@ export function buildMcpServerBackend(opts) {
         // found UIs in `blueprints.include`; absent = the server's
         // `ggui_list_featured_blueprints` returns an empty catalog (the
         // zero-config default).
-        ...(opts.blueprintProvider
-            ? { blueprintProvider: opts.blueprintProvider }
-            : {}),
+        ...(opts.blueprintProvider ? { blueprintProvider: opts.blueprintProvider } : {}),
         // Manifest-backed UI registry — resolves blueprint ids to
         // compiled bundles for `ggui_render_blueprint`. Paired with
         // `blueprintProvider` above (metadata vs. bundle resolution on
@@ -506,9 +487,7 @@ export function buildMcpServerBackend(opts) {
         // Manifest-declared primitive catalogs. Present when `ggui serve`
         // resolved `primitives.{packages,local}`; absent = in-memory-only
         // server with an empty `server.primitiveCatalogs`.
-        ...(opts.primitiveCatalogs
-            ? { primitiveCatalogs: opts.primitiveCatalogs }
-            : {}),
+        ...(opts.primitiveCatalogs ? { primitiveCatalogs: opts.primitiveCatalogs } : {}),
         // Manifest-declared theme. Present when `ggui serve` resolved
         // `ggui.json#theme`; absent = `createGguiServer` falls back to its
         // `lightTheme`-backed default internally.
@@ -524,25 +503,18 @@ export function buildMcpServerBackend(opts) {
         // bootstrap envelope without a restart. Both threaded through
         // when present; absent = boot-baked behaviour (legacy).
         ...(opts.themeProvider ? { themeProvider: opts.themeProvider } : {}),
-        ...(opts.onThemeConfigChange
-            ? { onThemeConfigChange: opts.onThemeConfigChange }
-            : {}),
-        // Register `ggui_push` + serve `ui://ggui/session`. URLs point at
-        // this server's own console viewer + live channel — same-origin,
-        // same process. Without this, `ggui_push` is absent and the `/s/`
-        // viewer can never resolve (nothing mints shortCodes).
+        ...(opts.onThemeConfigChange ? { onThemeConfigChange: opts.onThemeConfigChange } : {}),
+        // Register `ggui_render` + serve `ui://ggui/render`. The `wsUrl`
+        // is the live-channel URL published on `_meta["ai.ggui/render"]`
+        // so iframes opened by an MCP Apps host (Claude Desktop, Claude
+        // Code, claude.ai) can subscribe back to this same process.
+        // First-party hosts (Studio, Portal, console) consume
+        // `_meta.ui.resourceUri` instead and never hit the URL directly.
         mcpApps: {
-            // The `/r/` route serves the public self-contained shell that
-            // any MCP Apps host (Claude Desktop, Claude Code, claude.ai)
-            // can render directly — `structuredContent.url` lands on it
-            // as a full HTML page. First-party hosts (Studio, Portal,
-            // console) consume `_meta.ui.resourceUri` and never hit the
-            // URL directly, so the same prefix works for everyone.
-            renderBaseUrl: `${baseUrl}/r/`,
             wsUrl: `${wsBaseUrl}/ws`,
         },
         // Task #382 — `runtimeUrl` MUST be absolute. The thin-shell HTML
-        // served from `ui://ggui/session` is mounted via `srcdoc` in most
+        // served from `ui://ggui/render` is mounted via `srcdoc` in most
         // consumers (`<McpAppIframe>` default path for inline text), which
         // gives the iframe `about:srcdoc` as its URL — a relative path
         // like `/_ggui/iframe-runtime.js` resolves against `about:` and the
@@ -550,16 +522,16 @@ export function buildMcpServerBackend(opts) {
         // URL built from the CLI's own known `baseUrl` makes srcdoc mount
         // work without operator action. The server still serves the bundle
         // at `/_ggui/iframe-runtime.js` under `runtimePath`; this overrides
-        // only the URL published on `_meta.ggui.bootstrap.runtimeUrl`.
+        // only the URL published on `_meta["ai.ggui/render"].runtimeUrl`.
         runtime: { url: `${baseUrl}${RUNTIME_BUNDLE_URL_PATH}` },
         // OSS first-run default: provisional A2UI preview is on. The
         // deterministic emitter from `@ggui-ai/preview-a2ui/emitters`
-        // adapts each push's `story.intent` into a small A2UI surface
+        // adapts each render's `story.intent` into a small A2UI surface
         // (heading → shell → teardown) and streams it on
         // `_ggui:preview`. Embedded-ui's `/s/<shortCode>` viewer mounts
         // `<ProvisionalRenderer>` to paint the frames as they arrive,
         // so operators see a live UI build-up the first time they
-        // invoke `ggui_push` — before any LLM generation lands on OSS.
+        // invoke `ggui_render` — before any LLM generation lands on OSS.
         //
         // Hosted + programmatic hosts opt-in by composing
         // `createGguiServer()` directly and supplying their own
@@ -570,8 +542,8 @@ export function buildMcpServerBackend(opts) {
             emitter: createDeterministicPreviewEmitter(),
         },
         // Generation wiring. Threaded through to
-        // `defaultHandlers.push.generation` → `createGguiPushHandler`.
-        // Absent = placeholder mode: push creates sessions + shortCodes
+        // `defaultHandlers.render.generation` → `createGguiRenderHandler`.
+        // Absent = placeholder mode: render mints renderIds + shortCodes
         // + preview but does NOT produce componentCode. The CLI's
         // `runServeCommand` probes BYOK (env → credentials file) at
         // boot and only supplies this opt on a hit. See
@@ -581,9 +553,7 @@ export function buildMcpServerBackend(opts) {
         // `/mcp` alongside ggui-native tools. No CLI config loader yet —
         // programmatic hosts + integration tests compose mounts through
         // this opt directly.
-        ...(opts.mcpMounts && opts.mcpMounts.length > 0
-            ? { mcpMounts: opts.mcpMounts }
-            : {}),
+        ...(opts.mcpMounts && opts.mcpMounts.length > 0 ? { mcpMounts: opts.mcpMounts } : {}),
         // wiredActionRouter composed from the same mount handlers. With
         // mounts present, every mounted tool becomes wire-dispatchable
         // from a generated UI's `actionSpec[name].dispatch.tool` (when
@@ -603,11 +573,11 @@ export function buildMcpServerBackend(opts) {
         // 'off'`. Unrecognized values fall through to the server's
         // default. Keeping the parse narrow so a typo yields default
         // behavior (reject) rather than silent relaxation.
-        ...(process.env['GGUI_SCHEMA_COMPAT_MODE'] === 'warn' ||
-            process.env['GGUI_SCHEMA_COMPAT_MODE'] === 'off' ||
-            process.env['GGUI_SCHEMA_COMPAT_MODE'] === 'reject'
+        ...(process.env["GGUI_SCHEMA_COMPAT_MODE"] === "warn" ||
+            process.env["GGUI_SCHEMA_COMPAT_MODE"] === "off" ||
+            process.env["GGUI_SCHEMA_COMPAT_MODE"] === "reject"
             ? {
-                schemaCompatCheck: process.env['GGUI_SCHEMA_COMPAT_MODE'],
+                schemaCompatCheck: process.env["GGUI_SCHEMA_COMPAT_MODE"],
             }
             : {}),
         // Wired-tool per-call timeout override (default 30 s in
@@ -624,8 +594,8 @@ export function buildMcpServerBackend(opts) {
         // Operators that need a different production timeout SHOULD compose
         // `createGguiServer` directly rather than rely on env coupling.
         ...(() => {
-            const raw = process.env['GGUI_WIRED_TIMEOUT_MS'];
-            if (raw === undefined || raw === '')
+            const raw = process.env["GGUI_WIRED_TIMEOUT_MS"];
+            if (raw === undefined || raw === "")
                 return {};
             const parsed = Number(raw);
             if (!Number.isFinite(parsed) || parsed <= 0)
@@ -637,14 +607,14 @@ export function buildMcpServerBackend(opts) {
         listen: async (port, host) => {
             const httpServer = await server.listen(port, host);
             const addr = httpServer.address();
-            if (!addr || typeof addr === 'string') {
-                throw new Error('server.address() returned an unexpected shape');
+            if (!addr || typeof addr === "string") {
+                throw new Error("server.address() returned an unexpected shape");
             }
             return addr.port;
         },
         close: () => server.close(),
         toolCount: server.toolCount,
-        serverName: 'ggui-mcp-server',
+        serverName: "ggui-mcp-server",
         serverVersion: opts.cliVersion,
         primitiveCatalogCount: server.primitiveCatalogs.length,
         themeSource: server.theme.source,

package/dist/persistent-secrets.js

@@ -3,13 +3,13 @@
  * restart.
  *
  * Background: `createGguiServer` mints two HMAC secrets at boot when the
- * caller doesn't pass them — `bootstrapSecret` (signs MCP Apps `_meta.
- * ggui.bootstrap.token` so iframes can subscribe to the live-channel WS)
- * and the render-URL signer secret (signs `/r/<code>?sig=&exp=`). Both
- * are process-local `randomBytes(32)` by default — fine for a single
+ * caller doesn't pass them — `wsTokenSecret` (signs the
+ * `_meta["ai.ggui/render"].wsToken` envelope so iframes can subscribe
+ * to the live-channel WS) and the render-URL signer secret. Both are
+ * process-local `randomBytes(32)` by default — fine for a single
  * process lifetime, fatal for "revisit a claude.ai chat history after a
- * restart": the cached bootstrap token + cached render URL fail HMAC
- * verify against the freshly-minted secret.
+ * restart": the cached wsToken fails HMAC verify against the freshly-
+ * minted secret.
  *
  * Persisting the secrets to a 0600-mode file makes those tokens valid
  * across restarts, which is the precondition for any rehydrate path
@@ -17,10 +17,10 @@
  * lowercase hex (32 bytes), no trailing newline, no JSON wrapper. Easy
  * to inspect, easy to rotate (delete the file, restart, fresh secret).
  *
- * Security posture: these secrets are a session-token signing key, NOT
+ * Security posture: these secrets are a render-token signing key, NOT
  * a long-lived credential like an OAuth client secret. Losing them
  * means an attacker can mint MCP Apps bootstrap tokens for arbitrary
- * `(sessionId, appId)` pairs — same blast radius as before, just
+ * `(renderId, appId)` pairs — same blast radius as before, just
  * surviving restart. Mode 0600 on the file matches `~/.ggui/credentials
  * .json` (BYOK keys) which has the same threat model.
  *

package/dist/persistent-stores.d.ts

@@ -1,5 +1,5 @@
-import type { SessionStore, VectorStore } from '@ggui-ai/mcp-server-core';
-export declare function createPersistentSessionStore(persistentDir: string): Promise<SessionStore>;
+import type { RenderStore, VectorStore } from '@ggui-ai/mcp-server-core';
+export declare function createPersistentRenderStore(persistentDir: string): Promise<RenderStore>;
 export declare function createPersistentVectorStore(persistentDir: string): Promise<VectorStore>;
 /**
  * Compute the auto-default `keysFile` path. Returns `undefined` when

package/dist/persistent-stores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistent-stores.d.ts","sourceRoot":"","sources":["../src/persistent-stores.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"persistent-stores.d.ts","sourceRoot":"","sources":["../src/persistent-stores.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/persistent-stores.js

@@ -1,12 +1,12 @@
 /**
  * Default-on persistent stores under `<persistentDir>/`. Used when the
- * operator hasn't declared `storage.sessions` / `storage.vectors` in
- * `ggui.json` AND hasn't passed `--ephemeral`. Closes the SessionStore
+ * operator hasn't declared `storage.renders` / `storage.vectors` in
+ * `ggui.json` AND hasn't passed `--ephemeral`. Closes the RenderStore
  * leg of the rehydrate problem: without this, a restart drops every
- * session row even though the HMAC secret + ShortCodeIndex now persist.
+ * render row even though the HMAC secret + ShortCodeIndex now persist.
  *
  * Override precedence (caller enforces):
- *   1. Explicit `ggui.json#storage.sessions` / `.vectors`   (user wins)
+ *   1. Explicit `ggui.json#storage.renders` / `.vectors`   (user wins)
  *   2. These defaults                                       (operator-friendly)
  *   3. In-memory (`createGguiServer`'s internal fallback)   (last resort)
  *
@@ -16,11 +16,11 @@
  */
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-export async function createPersistentSessionStore(persistentDir) {
+export async function createPersistentRenderStore(persistentDir) {
     mkdirSync(persistentDir, { recursive: true });
-    const { SqliteSessionStore } = await import('@ggui-ai/mcp-server-core/sqlite');
-    return new SqliteSessionStore({
-        filename: join(persistentDir, 'sessions.sqlite'),
+    const { SqliteRenderStore } = await import('@ggui-ai/mcp-server-core/sqlite');
+    return new SqliteRenderStore({
+        filename: join(persistentDir, 'renders.sqlite'),
     });
 }
 export async function createPersistentVectorStore(persistentDir) {