@ggui-ai/mcp-server 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/server.d.ts

@@ -37,35 +37,46 @@
  * handlers wired up. The `Logger.warn('dev_mode_auth_enabled')` fires
  * once at boot so operators see the shape they're running.
  */
-import type { AppMetadataStore, AuditSink, AuthAdapter, AuthResult, BlueprintProvider, BlueprintSearch, BlueprintSelector, BlueprintStore, CodeStore, ConnectorRegistry, EmbeddingProvider, GeneratorRegistry, KeyValueStore, PairingService, PendingEventConsumer, ProviderKeyStore, RateLimiter, RenderStore, SessionStreamBuffer, ShortCodeIndex, TelemetrySink, ThreadStore, VectorStore } from "@ggui-ai/mcp-server-core";
+import type { AppMetadataStore, AuditSink, AuthAdapter, AuthResult, BlueprintIndex, BlueprintProvider, BlueprintSearch, BlueprintSelector, BlueprintStore, CodeStore, EmbeddingProvider, GeneratorRegistry, KeyValueStore, PairingService, PendingEventConsumer, ProviderKeyStore, RateLimiter, GguiSessionStore, GguiSessionStreamBuffer, ShortCodeIndex, TelemetrySink, ThreadStore, VectorStore } from "@ggui-ai/mcp-server-core";
 import type { SharedHandler } from "@ggui-ai/mcp-server-handlers";
 import { type ThemeCatalogEntry } from "@ggui-ai/mcp-server-handlers/app-discovery";
-import type { OperatorConfig } from "@ggui-ai/project-config";
+import type { OperatorConfig, ThemeConfig } from "@ggui-ai/project-config";
 import type { DiscoveredPrimitiveCatalog, LoadedTheme } from "@ggui-ai/project-config/node";
 import type { Blueprint } from "@ggui-ai/protocol";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Express, type Request } from "express";
 import { Server as NodeHttpServer } from "node:http";
-import { type ZodRawShape } from "zod";
+import type { ZodRawShape } from "zod";
 import { type ThemeFileUploader, type ThemeWriter } from "./console-theme-routes.js";
 import { type AppsSource, type UserDefaultAppSource } from "@ggui-ai/mcp-server-handlers/ops-apps";
 import { type ConnectorKeysSource } from "@ggui-ai/mcp-server-handlers/ops-connector-keys";
 import { type CouponRedeemSource } from "@ggui-ai/mcp-server-handlers/ops-coupon";
 import { type OrgInvitesSource, type OrgsSource } from "@ggui-ai/mcp-server-handlers/ops-orgs";
-import { type ChannelNotifier, type GenerationCredentials, type GenerationDeps, type HandshakeNegotiator, type PropsUpdateNotifier, type ProvisionalPreviewConfig, type ProvisionalPreviewDeps, type ProvisionalPreviewEmitter, type ProvisionalPreviewOutcome } from "@ggui-ai/mcp-server-handlers/renders";
+import { type ChannelNotifier, type GenerationCredentials, type GenerationDeps, type BlueprintPool, type HandshakeNegotiator, type PropsUpdateNotifier, type ProvisionalPreviewConfig, type ProvisionalPreviewDeps, type ProvisionalPreviewEmitter, type ProvisionalPreviewOutcome, type ToolIdentityCatalogStore } from "@ggui-ai/mcp-server-handlers/renders";
 import type { UiRegistry } from "@ggui-ai/ui-registry";
-import { type ServerInfo } from "./build-mcp.js";
+import type { ServerInfo } from "./build-mcp.js";
 import { type EmailSender, type MagicLinkStore } from "./email-login.js";
 import { type McpInstructionsValue } from "./instructions-presets.js";
 import { type Logger } from "./logger.js";
 import { type McpServerMount, type McpService } from "./mcp-mounts.js";
 import { type OAuthConfig } from "./oauth.js";
-import { type RenderChannelServer, type WiredActionRouter } from "./render-channel.js";
+import { type GguiSessionChannelServer } from "./ggui-session-channel.js";
 import { type SchemaCompatMode } from "./schema-compat.js";
 import { type ThreadOwnerResolver } from "./thread-transport.js";
 export declare function defaultHandlers(deps: {
     readonly embedding: EmbeddingProvider;
     readonly vectors: VectorStore;
+    /**
+     * Per-app tool-identity catalog store (write side). When bound,
+     * registers `ggui_runtime_declare_tool_catalog` — the host runtime's
+     * `{ bareToolName -> canonical serverInfo }` declaration is persisted
+     * here under `ctx.appId`. The SAME instance the handshake negotiator's
+     * `toolIdentityCatalog` resolver reads, so a reused blueprint's tool
+     * `serverInfo` is canonicalized before keying. Absent ⇒ the declaration
+     * tool is NOT registered (zero-config OSS without the round-trip wired
+     * stays clean).
+     */
+    readonly toolIdentityCatalogStore?: ToolIdentityCatalogStore;
     /**
      * Optional blueprint catalog source. When bound,
      * `ggui_list_featured_blueprints` enumerates the provider's
@@ -105,12 +116,12 @@ export declare function defaultHandlers(deps: {
         /**
          * Optional render store. When bound, `ggui_handshake` validates
          * the wire render id against this store (existence + tenant
-         * ownership) before negotiating. OSS sets this to the same store
-         * the render-commit handler uses so the handshake catches unknown
-         * / cross-tenant ids at the earliest boundary; cloud pods omit and
-         * validate at render-commit time via their own DDB-backed path.
+         * ownership) before negotiating. This server sets it to the same
+         * store the render-commit handler uses so the handshake catches
+         * unknown / cross-tenant ids at the earliest boundary; deployments
+         * that omit it validate at render-commit time instead.
          */
-        readonly renderStore?: RenderStore;
+        readonly renderStore?: GguiSessionStore;
         /**
          * Optional negotiator binding. Absent = `ggui_handshake` stamps
          * `action: 'create'` + honest no-negotiator reason on the record
@@ -135,16 +146,16 @@ export declare function defaultHandlers(deps: {
          */
         readonly serverCapabilities?: () => import("@ggui-ai/protocol").ServerCapabilities | undefined;
     };
-    readonly push?: {
-        readonly renderStore: RenderStore;
+    readonly render?: {
+        readonly renderStore: GguiSessionStore;
         /**
          * Optional bootstrap-credential minter. When present, `ggui_render`
          * (the renamed render-commit tool) results carry the
          * `ai.ggui/render` slice meta. When absent, they don't —
-         * non-MCP-Apps hosts read `{renderId}` off structuredContent and
+         * non-MCP-Apps hosts read `{sessionId}` off structuredContent and
          * resolve the render-resource themselves.
          */
-        readonly mintBootstrap?: (renderId: string, appId: string) => {
+        readonly mintBootstrap?: (sessionId: string, appId: string) => {
             wsUrl: string;
             token: string;
             expiresAt: string;
@@ -175,24 +186,18 @@ export declare function defaultHandlers(deps: {
         /** Theme color mode resolved from `ggui.json#theme.mode`. */
         readonly themeMode?: "light" | "dark";
         /**
-         * Live theme getter — resolved per-push. When set, supersedes
-         * the static `themeId` / `themeMode` for every push's bootstrap.
+         * Live theme getter — resolved per-render. When set, supersedes
+         * the static `themeId` / `themeMode` for every render's bootstrap.
          * Pair with the same getter passed into `createGguiServer({
          * themeProvider })` and a closure that reads from the shared
          * mutable cell `mountDevtoolThemeRoutes`'s POST handler updates.
-         * Forwarded onto `deps.push.themeProvider` so the handler reads
+         * Forwarded onto `deps.render.themeProvider` so the handler reads
          * the live theme each call.
          */
         readonly themeProvider?: () => {
             readonly id?: string;
             readonly mode?: "light" | "dark";
         } | undefined;
-        /**
-         * Optional connector registry — required for accepting
-         * `shortcuts.mcpApps` push payloads (inbound MCP Apps hosting).
-         * Omitted = inbound path is rejected with a clear error.
-         */
-        readonly connectors?: ConnectorRegistry;
         /**
          * Optional admission-control limiter. When present, `ggui_render`
          * gates every call through `rateLimiter.check({key:
@@ -202,23 +207,22 @@ export declare function defaultHandlers(deps: {
          */
         readonly rateLimiter?: RateLimiter;
         /**
-         * Optional shortCode → session binding index. When present,
+         * Optional shortCode → render binding index. When present,
          * `ggui_render` records every minted `shortCode` so console's
-         * `/s/<shortCode>` viewer (via the session-cookie endpoint) can
-         * resolve it back to the right session. Absent = hosted cloud
+         * `/s/<shortCode>` viewer (via the render-cookie endpoint) can
+         * resolve it back to the right render. Absent = hosted cloud
          * flow (DynamoDB side-table owns lookups), or console not
          * enabled.
          */
         readonly shortCodeIndex?: ShortCodeIndex;
         /**
          * Optional provisional-preview wiring. When present, `ggui_render`
-         * kicks off the configured emitter on every qualifying push (the
-         * `evaluateProvisionalPreviewGate` predicate filters MCP Apps
-         * pushes + storyless calls automatically). Absent = no preview
-         * channel traffic.
+         * kicks off the configured emitter on every qualifying render (the
+         * `evaluateProvisionalPreviewGate` predicate filters storyless
+         * calls automatically). Absent = no preview channel traffic.
          *
          * Constructed by `createGguiServer` from `opts.provisionalPreview`
-         * plus the late-bound `RenderChannelServer.sendToSession`
+         * plus the late-bound `GguiSessionChannelServer.sendToGguiSession`
          * closure; callers threading their own handler set can build
          * `ProvisionalPreviewDeps` directly.
          */
@@ -226,8 +230,8 @@ export declare function defaultHandlers(deps: {
         /**
          * Optional generation wiring. When present, `ggui_render` invokes
          * the supplied {@link UiGenerator} on every story-path call and
-         * commits the generated `Render` before returning `codeReady:
-         * true`. Absent = push stays in placeholder mode (render +
+         * commits the generated `GguiSession` before returning `codeReady:
+         * true`. Absent = render stays in placeholder mode (render +
          * shortCode + preview still work, but no componentCode is
          * produced).
          *
@@ -252,7 +256,7 @@ export declare function defaultHandlers(deps: {
         /**
          * Optional F4 schema compat check hook. When present,
          * `ggui_render` invokes it immediately
-         * before every `renderStore.commit` — if the pending Render's
+         * before every `renderStore.commit` — if the pending GguiSession's
          * `actionSpec` / `streamSpec` references a tool whose schemas
          * disagree, the hook throws `SchemaCompatError` and the handler
          * converts the rejection into an error render + `codeReady:
@@ -260,7 +264,7 @@ export declare function defaultHandlers(deps: {
          *
          * `createGguiServer` binds this closure against the composed
          * `handlers` list + `opts.schemaCompatCheck` (default `'reject'`)
-         * automatically; callers composing their own push handler via
+         * automatically; callers composing their own render handler via
          * `defaultHandlers` wire the hook themselves.
          */
         readonly checkRenderContracts?: (shape: {
@@ -275,7 +279,7 @@ export declare function defaultHandlers(deps: {
          * post-T3-1 (2026-05-13).
          *
          * Absent: `ggui_render.resultMeta` omits `codeUrl`. The iframe boots
-         * via live-mode (wsUrl+token) and receives the stack item via the
+         * via live-mode (wsUrl+token) and receives the render via the
          * live-channel WS subscribe. `/r/<shortCode>` (HTML default; JSON branch on `Accept: application/json`)
          * routes ALSO mint `codeUrl` when `codeStore` is set — they derive
          * the base URL from `req.protocol + req.host` when `codeBaseUrl`
@@ -307,11 +311,11 @@ export declare function defaultHandlers(deps: {
         readonly streamWebSocketLocalTools?: () => readonly string[] | undefined;
         /**
          * Optional bootstrap-refresh seam for the
-         * `ggui_runtime_refresh_bootstrap` tool (G14, 2026-05-23). When
+         * `ggui_runtime_refresh_ws_token` tool (G14, 2026-05-23). When
          * supplied, the tool registers and validates each refresh request
          * via this seam's HMAC check + refresh-window arithmetic. Typically
          * wired against the SAME `channelBootstrap.refresh` the
-         * session-channel server uses for WS upgrade validation, so both
+         * render-channel server uses for WS upgrade validation, so both
          * paths share one HMAC secret and one refresh-window policy.
          *
          * Absent: the tool is NOT registered on this deployment. iframes
@@ -320,15 +324,16 @@ export declare function defaultHandlers(deps: {
          * a stateless refresh.
          *
          * `createGguiServer` wires this from the `mcpAppsEnabled` branch's
-         * `channelBootstrap.refresh` so the OSS factory's behavior matches
-         * the cloud pod's tool-side composition.
+         * `channelBootstrap.refresh` so the factory's behavior matches the
+         * tool-side composition every deployment of this server family
+         * uses.
          */
         readonly bootstrapRefresh?: import("@ggui-ai/mcp-server-handlers/renders").WsTokenRefreshSeam;
     };
     /**
      * `ggui_update` wiring. When present, register the OSS update
-     * handler against the supplied RenderStore + optional live-channel
-     * props_update notifier. The handler reads `renderId` from wire
+     * handler against the supplied GguiSessionStore + optional live-channel
+     * props_update notifier. The handler reads `sessionId` from wire
      * input today, but a future in-process dispatcher can populate it
      * on the canonical context.
      *
@@ -337,10 +342,10 @@ export declare function defaultHandlers(deps: {
      * static-blueprint demos, MCP-Apps-only deployments).
      */
     readonly update?: {
-        readonly renderStore: RenderStore;
+        readonly renderStore: GguiSessionStore;
         /**
          * Optional live-subscriber `props_update` notifier — typically a
-         * thin closure over `RenderChannelServer.sendPropsUpdate`.
+         * thin closure over `GguiSessionChannelServer.sendPropsUpdate`.
          * Forwarded as-is to `createGguiUpdateHandler`. Hosts without a
          * render channel leave this absent; the handler still persists
          * via `renderStore.commit` on every successful patch.
@@ -355,14 +360,14 @@ export declare function defaultHandlers(deps: {
          * the same field on `render` deps; composing hosts wire both from
          * the same minter.
          */
-        readonly mintBootstrap?: (renderId: string, appId: string) => {
+        readonly mintBootstrap?: (sessionId: string, appId: string) => {
             wsUrl: string;
             token: string;
             expiresAt: string;
         };
         /** Iframe-runtime bundle URL forwarded onto the
          *  `ai.ggui/render.runtimeUrl` slice field.
-         *  Function form mirrors push deps — see {@link BuildMcpDeps.push}. */
+         *  Function form mirrors the `render` deps' `runtimeUrl`. */
         readonly runtimeUrl?: string | (() => string | undefined);
         /** Theme preset id forwarded onto the `ai.ggui/render.themeId` slice field. */
         readonly themeId?: string;
@@ -373,13 +378,9 @@ export declare function defaultHandlers(deps: {
             readonly id?: string;
             readonly mode?: "light" | "dark";
         } | undefined;
-        /** Returns names of app-visible tools for bootstrap.appCallableTools. */
-        readonly appCallableTools?: () => readonly string[];
-        /** Resolver for bootstrap.streamWebSocketLocalTools. */
-        readonly streamWebSocketLocalTools?: () => readonly string[] | undefined;
     };
     /**
-     * Pending-events consumer wiring for `ggui_consume`. When `push`
+     * Pending-events consumer wiring for `ggui_consume`. When `render`
      * is bound, the handler registers automatically with an in-memory
      * default; pass `consume.pendingEventConsumer` to override (e.g.,
      * SQLite-backed for persistent dev or a Dynamo adapter on cloud).
@@ -393,10 +394,10 @@ export declare function defaultHandlers(deps: {
         readonly defaultRenderTtlSeconds?: number;
     };
     /**
-     * Stream channel wiring for `ggui_emit`. When `push` is bound, the
+     * Stream channel wiring for `ggui_emit`. When `render` is bound, the
      * handler registers automatically; its `sendEnvelope` closes over
      * `stream.channelProvider`, a lazy getter that resolves the
-     * `RenderChannelServer` at emit time (the channel is constructed
+     * `GguiSessionChannelServer` at emit time (the channel is constructed
      * AFTER `defaultHandlers` runs, so a static reference would always
      * be null on the OSS in-process boot).
      *
@@ -405,10 +406,10 @@ export declare function defaultHandlers(deps: {
      * cloud's `ggui_emit_accepted_no_receiver` posture.
      *
      * The getter pattern lets the OSS server bind once at boot, then
-     * mutate the cell after `createRenderChannelServer` runs.
+     * mutate the cell after `createGguiSessionChannelServer` runs.
      */
     readonly stream?: {
-        readonly channelProvider?: () => RenderChannelServer | null;
+        readonly channelProvider?: () => GguiSessionChannelServer | null;
     };
     /**
      * Structured-event logger threaded into handlers that emit
@@ -462,7 +463,7 @@ export declare function defaultHandlers(deps: {
      * blueprint tools on `/ops`:
      *
      *   - `ggui_ops_generate_blueprint` (requires `resolveLlm` +
-     *     `blueprints` too — same deps the push generation path
+     *     `blueprints` too — same deps the render generation path
      *     reads).
      *   - `ggui_ops_list_blueprints`
      *   - `ggui_ops_update_blueprint`
@@ -495,7 +496,7 @@ export declare function defaultHandlers(deps: {
         readonly listAllForApp?: (appId: string) => Promise<readonly Blueprint[]>;
         /**
          * Resolver for LLM credentials on the generate path. Same shape
-         * as `push.generation.resolveLlm` — typically wired to the same
+         * as `render.generation.resolveLlm` — typically wired to the same
          * closure. When absent, the generate handler is NOT registered
          * (list/update/delete still register).
          */
@@ -511,12 +512,13 @@ export declare function defaultHandlers(deps: {
          * Cache-registry mirror for `ggui_ops_generate_blueprint`. When
          * bound, operator-authored blueprints are dual-written to the
          * cache vectorStore via `registerBlueprint` so the agent-facing
-         * matchBlueprint exact-key probe (handshake + push) finds them.
-         * Same bundle the push handler reads/writes.
+         * matchBlueprint exact-key probe (handshake + render) finds them.
+         * Same bundle the render handler reads/writes.
          */
         readonly cacheRegistry?: {
             readonly embedding: EmbeddingProvider;
             readonly vectorStore: VectorStore;
+            readonly index: BlueprintIndex;
         };
     };
     /**
@@ -584,7 +586,7 @@ export interface CreateGguiServerOptions {
      *     `['user']`-only handlers without affecting the existing toolset
      *     (which is all `['app', 'builder']`).
      *   - end-user / Connector posture sets `['user']` — skips all
-     *     agent-builder writes (push / handshake / update) while keeping
+     *     agent-builder writes (render / handshake / update) while keeping
      *     the read-only blueprint surface visible.
      *   - OSS local omits this option — every handler registers; OSS
      *     callers resolve to `kind: 'builder'` and the filter never fires.
@@ -604,6 +606,16 @@ export interface CreateGguiServerOptions {
      * Vector store for blueprint search. Defaults to `InMemoryVectorStore`.
      */
     readonly vectors?: VectorStore;
+    /**
+     * Blueprint identity index — resolves `(scope, exactKey) → blueprintId`
+     * without a scope scan. Defaults to `InMemoryBlueprintIndex`. Operators
+     * who wire a persistent `vectors` store SHOULD pass a matching
+     * persistent index (e.g. `SqliteBlueprintIndex`) so the binding survives
+     * a restart. Threaded into the generation cache + every
+     * `BlueprintRegistryDeps` the server builds so the matcher + registry
+     * share one instance.
+     */
+    readonly index?: BlueprintIndex;
     /**
      * Embedding provider for blueprint search. Defaults to `MockEmbeddingProvider`
      * — produces deterministic but NOT semantically meaningful vectors.
@@ -626,6 +638,24 @@ export interface CreateGguiServerOptions {
      * cross-handler sharing) and `ggui_list_themes` is NOT registered.
      */
     readonly appMetadataStore?: AppMetadataStore;
+    /**
+     * Per-app tool-identity catalog store — the shared persistence seam
+     * for cross-runtime tool-identity canonicalization. The SAME instance
+     * is wired into BOTH sides of the round-trip:
+     *   - WRITE: the `ggui_runtime_declare_tool_catalog` handler (the host
+     *     runtime declares `{ bareToolName -> canonical serverInfo }` on
+     *     connect).
+     *   - READ: the handshake decision adapter's `toolIdentityCatalog`
+     *     resolver, so a reused blueprint's tool `serverInfo` is rewritten
+     *     to the canonical identity before keying (framework-invariant
+     *     reuse).
+     *
+     * Absent ⇒ `createGguiServer` constructs a single shared
+     * `InMemoryToolIdentityCatalogStore` and threads it into both sides
+     * (mirrors the `appMetadataStore` default). Hosted deployments bind a
+     * multi-tenant adapter.
+     */
+    readonly toolIdentityCatalogStore?: ToolIdentityCatalogStore;
     /**
      * Global theme-catalog resolver. When bound alongside
      * `appMetadataStore`, registers `ggui_list_themes` and projects the
@@ -768,7 +798,7 @@ export interface CreateGguiServerOptions {
      * `mode` into the `ai.ggui/render` slice meta. Pair with
      * {@link onThemeConfigChange} so a console save updates the
      * shared state cell the closure reads from. The cell pattern
-     * closes the parallel-state-stores bug where the push handler
+     * closes the parallel-state-stores bug where the render handler
      * captured `themeId` at boot from the static `theme` opt and
      * silently ignored every subsequent ggui.json edit until restart.
      *
@@ -786,22 +816,15 @@ export interface CreateGguiServerOptions {
      * `/upload` variant). Forwarded onto
      * `mountDevtoolThemeRoutes({onConfigChange})`. Pair with a
      * `themeProvider` closure that reads from the same shared cell
-     * the callback writes to so a console save reaches the next push
+     * the callback writes to so a console save reaches the next render
      * without restarting the server.
      *
-     * `next` matches `ThemeConfig` from `@ggui-ai/project-config` —
+     * `next` is `ThemeConfig` from `@ggui-ai/project-config` —
      * one of: a string shorthand (`'indigo'`), a preset object
      * (`{ preset, mode?, overrides? }`), a file object
      * (`{ file, mode? }`), or `null` (cleared).
      */
-    readonly onThemeConfigChange?: (next: string | {
-        preset: string;
-        mode?: "light" | "dark";
-        overrides?: Record<string, string>;
-    } | {
-        file: string;
-        mode?: "light" | "dark";
-    } | null) => void;
+    readonly onThemeConfigChange?: (next: ThemeConfig | null) => void;
     /**
      * Map a resolved identity to the `appId` used by handlers for tenant
      * scoping. Defaults to `defaultAppIdFromIdentity` — single-user
@@ -811,9 +834,9 @@ export interface CreateGguiServerOptions {
     readonly appIdFromIdentity?: (result: AuthResult) => string;
     /**
      * Path the universal MCP endpoint mounts at. Defaults to `/mcp` per
-     * Streamable HTTP convention. Cloud `mcp.ggui.ai` overrides to `/`
-     * (bare root) so URLs are short — the domain already says "mcp",
-     * no need to repeat it in the path.
+     * Streamable HTTP convention. A deployment on a dedicated MCP
+     * domain may override to `/` (bare root) so URLs stay short — the
+     * domain already says "mcp", no need to repeat it in the path.
      *
      * Threaded into the well-known protected-resource metadata so OAuth
      * clients discover the right resource URL, and into the route table
@@ -822,37 +845,39 @@ export interface CreateGguiServerOptions {
     readonly universalMcpPath?: string;
     /**
      * Per-tenant URL routing. When set, the factory
-     * additionally mounts `${pathPrefix}/:${paramName}(${paramPattern})`
+     * additionally mounts `${pathPrefix}/:${paramName}`
      * alongside the universal path. The shared handler reads
      * `req.params[paramName]` and uses it as `ctx.appId`, overriding
      * `appIdFromIdentity` for that request.
      *
-     * Cloud `mcp.ggui.ai` deployments pass `{paramName: 'appId',
+     * A multi-tenant deployment passes e.g. `{paramName: 'appId',
      * paramPattern: '[A-Za-z0-9]{8}', pathPrefix: '/apps'}` so URLs
-     * like `mcp.ggui.ai/apps/aB3kP9xY` route to a session scoped to
-     * that specific GguiApp. The `/apps/` prefix segments the
+     * like `example.com/apps/aB3kP9xY` route to a session scoped to
+     * that specific app. The `/apps/` prefix segments the
      * namespace cleanly — no risk of an 8-char appId colliding with a
      * bare-root system route like `/health` or `/settings`.
      *
      * Without `pathPrefix`, the route mounts at the bare
-     * `/:${paramName}(${paramPattern})` — useful only when the
-     * deployment owns the entire URL space and the pattern guarantees
-     * no collision (e.g. UUIDs).
+     * `/:${paramName}` — useful only when the deployment owns the
+     * entire URL space and the pattern guarantees no collision
+     * (e.g. UUIDs).
      *
-     * Pattern is an Express-compatible regex (no slashes, no flags).
-     * Express only matches the URL when it satisfies the pattern; a
-     * malformed appId 404s instead of reaching the handler.
+     * Pattern is a JS regex source (no slashes, no flags). `path-to-
+     * regexp` v8 (express@5) dropped inline `:param(pattern)` route
+     * syntax, so the factory enforces `paramPattern` with an `app.param`
+     * validator (anchored full-match) rather than baking it into the
+     * route string; a malformed appId 404s before reaching the handler.
      *
      * `authorize` is the deployment-specific access check. After auth
      * resolves but before session work begins, the handler invokes it
      * with the URL-supplied appId + identity. Throw to deny — the
      * handler converts to a 403 response and skips MCP processing.
-     * Cloud uses this to verify `GguiApp.userId === identity.userId`
-     * (raw-DDB readers in pod tools bypass AppSync owner-auth, so
-     * this is the boundary that prevents cross-user blueprint reads).
-     * OSS deployments that opt in to per-app routing without an
-     * authorize callback are TRUSTED — every authenticated caller can
-     * scope to any URL appId.
+     * Multi-tenant deployments use this to verify the resolved identity
+     * owns the URL-addressed app — this is the boundary that prevents
+     * cross-user blueprint reads when downstream stores don't enforce
+     * ownership themselves. Deployments that opt in to per-app routing
+     * without an authorize callback are TRUSTED — every authenticated
+     * caller can scope to any URL appId.
      */
     readonly perAppRouting?: {
         readonly paramName: string;
@@ -879,7 +904,7 @@ export interface CreateGguiServerOptions {
      * preserves the default.
      *
      * Use case: hosted closed-runtime deployments throw domain errors from
-     * tool handlers (e.g. `SessionAccessError` "this session doesn't belong
+     * tool handlers (e.g. `GguiSessionAccessError` "this render doesn't belong
      * to you") that should map to HTTP 404 so callers can distinguish
      * tenancy violations from real server bugs. OSS deployments don't
      * need this seam — every domain error is a 500 unless they say
@@ -962,30 +987,30 @@ export interface CreateGguiServerOptions {
     /** Express body size limit. Defaults to `'4mb'`. */
     readonly bodyLimit?: string;
     /**
-     * Render store — backing plane for the live-channel render endpoint
+     * GguiSession store — backing plane for the live-channel render endpoint
      * (and OSS render-reading MCP tools). Defaults to
-     * `InMemoryRenderStore`, which is fine for OSS zero-config / dev.
+     * `InMemoryGguiSessionStore`, which is fine for OSS zero-config / dev.
      * SQLite / Postgres / Redis adapters bind via the same interface
      * when they land.
      */
-    readonly renderStore?: RenderStore;
+    readonly renderStore?: GguiSessionStore;
     /**
      * Outbound stream replay buffer for the live-channel endpoint. Defaults
-     * to a fresh `InMemorySessionStreamBuffer` — fine for OSS zero-config
+     * to a fresh `InMemoryGguiSessionStreamBuffer` — fine for OSS zero-config
      * / dev. Operators who need durability layer a different
-     * `SessionStreamBuffer` implementation behind this seam.
+     * `GguiSessionStreamBuffer` implementation behind this seam.
      *
-     * Only used when `sessionChannel` is enabled. Ignored otherwise.
+     * Only used when `renderChannel` is enabled. Ignored otherwise.
      */
-    readonly streamBuffer?: SessionStreamBuffer;
+    readonly streamBuffer?: GguiSessionStreamBuffer;
     /**
-     * Enable the OSS live-channel session endpoint at `/ws` (configurable).
+     * Enable the OSS live-channel render endpoint at `/ws` (configurable).
      *
-     *   - `false` (default): no session channel. `/mcp` is the only
+     *   - `false` (default): no render channel. `/mcp` is the only
      *     HTTP surface. Callers who only need the tool plane get the
      *     smallest shape.
      *   - `true`: mount the channel at the default path (`/ws`) with
-     *     the default session store.
+     *     the default render store.
      *   - `{ path?: string }`: override the mount path.
      *
      * The live channel is where the live-contract enforcement point
@@ -993,41 +1018,13 @@ export interface CreateGguiServerOptions {
      * of the shared `@ggui-ai/mcp-server-handlers/renders`
      * helpers.
      */
-    readonly sessionChannel?: boolean | {
+    readonly renderChannel?: boolean | {
         readonly path?: string;
     };
-    /**
-     * Opt-in WS-direct action dispatcher for agent-less deployments.
-     * When present AND `sessionChannel: true`, the channel server
-     * fires the tool named by an incoming action's `payload.tool` hint
-     * (falling back to `actionSpec[name].nextStep` when the client
-     * omitted the hint) in-process after inbound validation, and emits
-     * every declared `streamSpec[name].source.tool` refresh on the
-     * session. See {@link WiredActionRouter} + `session-channel.ts` for
-     * the full router contract.
-     *
-     * Absent = agent-mediated behavior (canonical for MCP Apps hosts and
-     * Claude Agent SDK consumers). Inbound actions land on the
-     * renderId-keyed pending-events pipe via `ggui_runtime_submit_action`
-     * and the agent's `ggui_consume` long-poll drains them. CLI
-     * composition in `ggui serve` wires a router by default over the
-     * same handler bundle `/mcp` uses, since that command runs WITHOUT
-     * an agent (raw WS clients hitting the OSS server directly). Library
-     * consumers MAY pass their own router; library consumers running
-     * behind an agent typically pass `undefined` so actions flow through
-     * the agent's reasoning loop.
-     */
-    readonly wiredActionRouter?: WiredActionRouter;
-    /**
-     * Per-call timeout for wired-tool invocations, in ms. Defaults to
-     * `DEFAULT_WIRED_TOOL_TIMEOUT_MS` (30 s) when omitted. Forwarded
-     * verbatim to `createRenderChannelServer`.
-     */
-    readonly wiredActionTimeoutMs?: number;
     /**
      * Opt-in plumbing for `channel_subscribe` polling — the WS fan-out
      * path for `streamSpec[*].source.tool`. When present, the
-     * session channel accepts `channel_subscribe` frames whose
+     * render channel accepts `channel_subscribe` frames whose
      * `source.tool` is in `allowlist` and begins polling. When absent
      * (the OSS first-run zero-config posture), every `channel_subscribe`
      * rejects with `CHANNEL_NOT_LOCAL` so the iframe falls back to
@@ -1038,49 +1035,39 @@ export interface CreateGguiServerOptions {
      * `serverCapabilities.streamWebSocketLocalTools` so `@ggui-ai/wire`
      * agrees with the server on which channels use WS fan-out.
      *
-     * Only consulted when `sessionChannel` is enabled. Forwarded
-     * verbatim to `createRenderChannelServer` (see
-     * `RenderChannelOptions.streamWebSocketLocalTools`).
+     * Only consulted when `renderChannel` is enabled. Forwarded
+     * verbatim to `createGguiSessionChannelServer` (see
+     * `GguiSessionChannelOptions.streamWebSocketLocalTools`).
      */
-    readonly streamWebSocketLocalTools?: import("./render-channel.js").RenderChannelLocalToolsOptions;
+    readonly streamWebSocketLocalTools?: import("./ggui-session-channel.js").GguiSessionChannelLocalToolsOptions;
     /**
      * Hook fired when the local subscriber count for `sessionId`
      * transitions 0 → 1 on the live channel. Forwarded verbatim to
-     * `createRenderChannelServer`. Used by cloud adapters for per-session
+     * `createGguiSessionChannelServer`. Used by cloud adapters for per-render
      * cross-pod pubsub channel scoping; OSS callers leave this undefined.
      *
-     * Only consulted when `sessionChannel` is enabled. See
-     * `RenderChannelOptions.onFirstSubscriber` for the full contract.
+     * Only consulted when `renderChannel` is enabled. See
+     * `GguiSessionChannelOptions.onFirstSubscriber` for the full contract.
      */
     readonly onFirstSubscriber?: (sessionId: string) => void;
     /**
      * Hook fired when the local subscriber count for `sessionId`
      * transitions 1 → 0 on the live channel. Forwarded verbatim to
-     * `createRenderChannelServer`.
+     * `createGguiSessionChannelServer`.
      *
-     * Only consulted when `sessionChannel` is enabled. See
-     * `RenderChannelOptions.onLastSubscriberGone` for the full contract.
+     * Only consulted when `renderChannel` is enabled. See
+     * `GguiSessionChannelOptions.onLastSubscriberGone` for the full contract.
      */
     readonly onLastSubscriberGone?: (sessionId: string) => void;
-    /**
-     * Override the sanitizer applied to the stringified original error
-     * written into `ContractErrorPayload.error.causedBy`. Defaults to
-     * `@ggui-ai/protocol::sanitizeCausedBy` when omitted — redacts
-     * Bearer tokens, query-param secrets, common env-var dumps, and
-     * truncates at 2 KB. Forwarded verbatim to
-     * `createRenderChannelServer`. See `RenderChannelOptions
-     * .sanitizeCausedBy` for the contract.
-     */
-    readonly sanitizeCausedBy?: import("@ggui-ai/protocol").SanitizeCausedBy;
     /**
      * Extra reserved-channel payload validators merged with the
      * server's default A2UI preview validator before being passed to
-     * the session channel (Item 4 injection pattern). Caller-provided
+     * the render channel (Item 4 injection pattern). Caller-provided
      * entries WIN on key conflict — the pattern is "server supplies
      * defaults, operator may replace by key".
      *
      * Absent = the server binds only the A2UI validator for
-     * `_ggui:preview` by default. `_ggui:contract-error` is validated
+     * `_ggui:preview` by default. `_ggui:lifecycle` is validated
      * via the protocol-shipped builtin regardless of this option.
      *
      * Pass `new Map()` (explicitly empty) to DISABLE the A2UI default —
@@ -1090,15 +1077,15 @@ export interface CreateGguiServerOptions {
      */
     readonly extraReservedValidators?: ReadonlyMap<string, import("@ggui-ai/protocol").ReservedChannelValidator>;
     /**
-     * Protocol-version handshake policy for the session channel. Forwarded
-     * verbatim to `createRenderChannelServer` (see
-     * `RenderChannelOptions.versionPolicy`). Defaults to `'reject'` —
+     * Protocol-version handshake policy for the render channel. Forwarded
+     * verbatim to `createGguiSessionChannelServer` (see
+     * `GguiSessionChannelOptions.versionPolicy`). Defaults to `'reject'` —
      * mismatched `SubscribePayload.supportedVersions` emits
      * UPGRADE_REQUIRED and closes the connection. Legacy opt-out
      * `'advisory'` keeps the connection open after the error frame for
      * controlled migration windows.
      *
-     * Only consulted when `sessionChannel` is enabled.
+     * Only consulted when `renderChannel` is enabled.
      */
     readonly versionPolicy?: "advisory" | "reject";
     /**
@@ -1109,8 +1096,8 @@ export interface CreateGguiServerOptions {
      * `streamSpec[channel].tool` ref points at a tool whose return
      * schema fits inside the channel's declared `schema`.
      *
-     *   - `'reject'` (default) — violations throw before the stack
-     *     item commits (or before blueprint registration completes).
+     *   - `'reject'` (default) — violations throw before the render
+     *     commits (or before blueprint registration completes).
      *     Canonical enforcement posture for launch.
      *   - `'warn'` — violations log through the server's structured
      *     logger (`schema_compat_warn` event with the full report
@@ -1178,7 +1165,7 @@ export interface CreateGguiServerOptions {
      *     is NOT advertised. Server looks identical to the pre-MCP-Apps
      *     surface.
      *   - `true`: enable with sensible defaults. Requires
-     *     `sessionChannel: true` so the iframe has a WebSocket to open;
+     *     `renderChannel: true` so the iframe has a WebSocket to open;
      *     throws at construction otherwise.
      *   - `{ shellHtml?, wsUrl? }`: explicit config.
      *
@@ -1191,9 +1178,9 @@ export interface CreateGguiServerOptions {
      *   3. `io.modelcontextprotocol/ui` is advertised in the server's
      *      `initialize` capabilities (under `experimental`).
      *   4. Each `ggui_render` result carries the `ai.ggui/render` slice
-     *      with wsUrl + short-TTL token + expiresAt. The session-channel
+     *      with wsUrl + short-TTL token + expiresAt. The render-channel
      *      server accepts that token on `subscribe` and issues a
-     *      longer-TTL `renderToken` in the ack for iframe reconnects.
+     *      longer-TTL `sessionToken` in the ack for iframe reconnects.
      */
     readonly mcpApps?: boolean | {
         readonly shellHtml?: string;
@@ -1237,13 +1224,6 @@ export interface CreateGguiServerOptions {
         readonly distDir?: string;
         readonly url?: string;
     };
-    /**
-     * Connector registry for external MCP servers. Required to accept
-     * inbound MCP Apps push payloads (`shortcuts.mcpApps`) and for the
-     * `/mcp-apps/resource` proxy route to resolve source-server
-     * endpoints. Absent = inbound MCP Apps hosting disabled.
-     */
-    readonly connectors?: ConnectorRegistry;
     /**
      * HMAC secret used to sign bootstrap + session tokens. When the MCP
      * Apps outbound path is enabled and no secret is passed, the server
@@ -1522,7 +1502,7 @@ export interface CreateGguiServerOptions {
      *
      *   - Same-origin ONLY — not a Portal replacement, not an MCP Apps
      *     iframe shell.
-     *   - No same-origin cookie, no session viewer, no WebSocket
+     *   - No same-origin cookie, no render viewer, no WebSocket
      *     wiring yet.
      *
      * Options:
@@ -1552,13 +1532,13 @@ export interface CreateGguiServerOptions {
         readonly distDir?: string;
         /**
          * Enable the Slice-2 same-origin session-cookie flow
-         * (`POST /ggui/console/render-cookie` + session-channel
+         * (`POST /ggui/console/session-cookie` + render-channel
          * cookie-auth wiring). Defaults to OFF — the landing-page
          * static surface is useful on its own (pair-code display,
          * server identity); turning on the cookie flow is an
          * explicit step that pulls in additional deps.
          *
-         * Enabling REQUIRES `sessionChannel: true` — the cookie only
+         * Enabling REQUIRES `renderChannel: true` — the cookie only
          * authenticates the live-channel WebSocket upgrade, so a cookie
          * flow without a channel to use it on would be pointless +
          * confusing. Throws at construction if that invariant fails.
@@ -1568,7 +1548,7 @@ export interface CreateGguiServerOptions {
          * it. Throws at construction if the index is absent.
          *
          * The cookie signing secret is the same {@link wsTokenSecret}
-         * used by the MCP Apps bootstrap/session tokens — different
+         * used by the MCP Apps bootstrap/render tokens — different
          * token `kind` claims make cross-kind confusion impossible
          * (see `console-auth.ts` isolation comment).
          */
@@ -1596,7 +1576,7 @@ export interface CreateGguiServerOptions {
          *
          * The gate accepts either an `Authorization: Bearer <token>`
          * header OR the `ggui_console_admin` cookie set by the
-         * admin-login route. Other console routes (registry, sessions,
+         * admin-login route. Other console routes (registry, renders,
          * cached blueprints, …) are NOT gated by this token — that's
          * a separate audit slice. The keys plane is the immediate
          * threat: plaintext bearer rendering + mint + revoke must not
@@ -1655,9 +1635,9 @@ export interface CreateGguiServerOptions {
     /**
      * Index for resolving `shortCode → { sessionId, appId }`. Required
      * when `console.sessionCookie` is enabled (the cookie endpoint
-     * looks up the posted shortCode to find the session to bind).
+     * looks up the posted shortCode to find the render to bind).
      *
-     * Pair this with a `push` handler so the agent's `ggui_render` writes
+     * Pair this with a `render` handler so the agent's `ggui_render` writes
      * the shortCode into the same index that console later reads.
      * See `defaultHandlers` for the wiring seam.
      */
@@ -1665,11 +1645,11 @@ export interface CreateGguiServerOptions {
     /**
      * Content-addressable code blob storage. When wired, this server
      * mounts `GET /code/<hash>.js` for the iframe runtime to fetch
-     * compiled componentCode by content hash. The push handler writes
+     * compiled componentCode by content hash. The render handler writes
      * to the store before emitting `codeUrl` on the `ai.ggui/render`
      * slice.
      *
-     * Defaults: when omitted the route is NOT mounted; the push
+     * Defaults: when omitted the route is NOT mounted; the render
      * handler falls back to inline base64 `componentCode` on the
      * `ai.ggui/render` slice (legacy delivery channel).
      *
@@ -1683,15 +1663,15 @@ export interface CreateGguiServerOptions {
     readonly codeStore?: CodeStore;
     /**
      * Provisional A2UI preview wiring for `ggui_render`. When the config
-     * flag is on, every qualifying component push kicks off the
+     * flag is on, every qualifying component render kicks off the
      * supplied emitter; frames land on the reserved `_ggui:preview`
-     * channel of the push's session.
+     * channel of the render.
      *
      * The server owns the `sendEnvelope` + registry plumbing — only
      * the emitter + flag + optional observers are caller-facing.
      *
-     * Requires `sessionChannel: true` + `mcpApps` enabled (preview
-     * needs a channel to emit on AND a push handler to attach to).
+     * Requires `renderChannel: true` + `mcpApps` enabled (preview
+     * needs a channel to emit on AND a render handler to attach to).
      * When the flag is on without those, `createGguiServer` throws —
      * silent drop would make "I enabled preview and nothing fires"
      * look like a generation bug instead of a wiring bug.
@@ -1709,7 +1689,7 @@ export interface CreateGguiServerOptions {
          * explicit about the producer).
          */
         readonly emitter: ProvisionalPreviewEmitter;
-        /** Per-push predicate. See {@link ProvisionalPreviewConfig}. */
+        /** Per-render predicate. See {@link ProvisionalPreviewConfig}. */
         readonly isEnabledFor?: ProvisionalPreviewConfig["isEnabledFor"];
         /** Lifecycle observer. Fires sync — must not throw. */
         readonly onOutcome?: (outcome: ProvisionalPreviewOutcome) => void;
@@ -1730,7 +1710,7 @@ export interface CreateGguiServerOptions {
      *     shape.
      *   - `{kvStore, negotiator}` — wire a real negotiator (e.g. RAG
      *     in a hosted closed runtime) so handshake records carry a
-     *     decision the paired push echoes as `structuredContent.decision`.
+     *     decision the paired render echoes as `structuredContent.decision`.
      *   - `false` — explicitly disable: `ggui_handshake` is NOT
      *     registered and `ggui_render({handshakeId})` falls back to
      *     the rejection shape.
@@ -1759,8 +1739,8 @@ export interface CreateGguiServerOptions {
     };
     /**
      * Generation wiring for the `ggui_render` story path. When present,
-     * every component push invokes the bound `UiGenerator` and commits
-     * the result as a real `Render`. Absent = placeholder mode:
+     * every component render invokes the bound `UiGenerator` and commits
+     * the result as a real `GguiSession`. Absent = placeholder mode:
      * `ggui_render` on the story path returns `codeReady: false`
      * without writing componentCode.
      *
@@ -1774,9 +1754,15 @@ export interface CreateGguiServerOptions {
      * runtime supplies its own generator binding through the same seam.
      * BYOK resolution (env → credentials file) is the CLI layer's
      * concern — at this boundary the caller hands in a closure that
-     * returns resolved credentials per push.
+     * returns resolved credentials per render.
      */
     readonly generation?: GenerationDeps;
+    /**
+     * Read-only shared/seed blueprint pools for cross-deployment reuse.
+     * Threaded into the handshake negotiator's `seedPools`. Built by the
+     * CLI from `--seed-pool` artifacts; absent ⇒ no shared pool.
+     */
+    readonly seedPools?: readonly BlueprintPool[];
     /**
      * Optional multi-generator registry. When present, exposes named
      * generators (e.g. `ui-gen-default-haiku-4-5`,
@@ -1795,7 +1781,7 @@ export interface CreateGguiServerOptions {
     /**
      * Optional multi-variant blueprint store. When present, `Blueprint`
      * rows persist via this seam so `ggui_ops_generate_blueprint` and
-     * push-on-cache-miss can read + write through it. When omitted,
+     * render-on-cache-miss can read + write through it. When omitted,
      * `createGguiServer` auto-seeds an {@link InMemoryBlueprintStore}.
      */
     readonly blueprintStore?: BlueprintStore;
@@ -1964,13 +1950,13 @@ export interface GguiServer {
      */
     readonly toolCount: number;
     /**
-     * The OSS live-channel session endpoint, when `sessionChannel` was
+     * The OSS live-channel render endpoint, when `renderChannel` was
      * enabled. `null` when disabled. Hosts can use this for
-     * introspection (`.sessionCount`, `.subscriberCount`) or for
+     * introspection (`.renderCount`, `.subscriberCount`) or for
      * composition with future mutation handlers that want to fan out
-     * via `sessionChannel.sendToSession(sessionId, data)`.
+     * via `renderChannel.sendToGguiSession(sessionId, data)`.
      */
-    readonly sessionChannel: RenderChannelServer | null;
+    readonly renderChannel: GguiSessionChannelServer | null;
     /**
      * The pairing service bound to this server, when the `pairing` option
      * was enabled. `null` when pairing is disabled. In-process hosts