@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/server.d.ts

@@ -0,0 +1,2060 @@
+/**
+ * createGguiServer — build a runnable open MCP server.
+ *
+ * Composition:
+ *
+ *   - `@ggui-ai/mcp-server-handlers/blueprints` — the three blueprint-read
+ *     handlers (search / list_featured / render), shared with hosted
+ *     closed-runtime servers. If you want more tools, extract the next
+ *     family into `@ggui-ai/mcp-server-handlers` and pass it via
+ *     `handlers:`.
+ *
+ *   - `@ggui-ai/mcp-server-core/in-memory` — default backing adapters
+ *     (vectors, embedding, auth). Real persistence bindings ship in
+ *     later packages (sqlite / postgres / redis) and plug into the
+ *     same interfaces.
+ *
+ *   - `@modelcontextprotocol/sdk` — `McpServer` + `StreamableHTTPServerTransport`
+ *     matching the MCP wire spec. Fresh transport + fresh server per
+ *     request (stateless); response close tears both down.
+ *
+ * Transport:
+ *
+ *   POST /mcp             — MCP Streamable HTTP wire protocol (JSON-RPC).
+ *   GET  /ggui/health     — unauthenticated liveness, returns
+ *                           `{status, server, version, tools, ...}`.
+ *   GET  /ggui/auth-check — authenticated liveness. 204 when the bearer
+ *                           token resolves via the configured AuthAdapter,
+ *                           401 otherwise. Pairs with `/ggui/health` so
+ *                           clients (e.g. Portal settings) can distinguish
+ *                           `reachable` from `token-invalid` without
+ *                           opening a full MCP session just to probe.
+ *   GET/DELETE /mcp       — 405 (stateless server doesn't support the
+ *                           streaming continuation / session-terminate verbs).
+ *
+ * Zero-config boot: omit every option and you get an in-memory server
+ * accepting any bearer token (dev mode) with the blueprint-read
+ * handlers wired up. The `Logger.warn('dev_mode_auth_enabled')` fires
+ * once at boot so operators see the shape they're running.
+ */
+import { type Express, type Request } from 'express';
+import { Server as NodeHttpServer } from 'node:http';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ThemeWriter, type ThemeFileUploader } from './console-theme-routes.js';
+import { type ZodRawShape } from 'zod';
+import type { AppMetadataStore, AuditSink, AuthAdapter, AuthResult, BlueprintProvider, BlueprintSearch, BlueprintSelector, BlueprintStore, ConnectorRegistry, CodeStore, EmbeddingProvider, GeneratorRegistry, KeyValueStore, PairingService, PendingEventConsumer, ProviderKeyStore, RateLimiter, SessionStore, SessionStreamBuffer, ShortCodeIndex, TelemetrySink, ThreadStore, VectorStore } from '@ggui-ai/mcp-server-core';
+import type { Blueprint } from '@ggui-ai/protocol';
+import type { DiscoveredPrimitiveCatalog, LoadedTheme } from '@ggui-ai/project-config/node';
+import type { OperatorConfig } from '@ggui-ai/project-config';
+import type { SharedHandler } from '@ggui-ai/mcp-server-handlers';
+import { type ThemeCatalogEntry } from '@ggui-ai/mcp-server-handlers/app-discovery';
+import { type AppsSource, type UserDefaultAppSource } from '@ggui-ai/mcp-server-handlers/ops-apps';
+import { type OrgsSource, type OrgInvitesSource } from '@ggui-ai/mcp-server-handlers/ops-orgs';
+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 { UiRegistry } from '@ggui-ai/ui-registry';
+import { type ChannelNotifier, type GenerationCredentials, type GenerationDeps, type HandshakeNegotiator, type PropsUpdateNotifier, type ProvisionalPreviewDeps, type ProvisionalPreviewEmitter, type ProvisionalPreviewConfig, type ProvisionalPreviewOutcome } from '@ggui-ai/mcp-server-handlers/session-mutations';
+import { type ServerInfo } from './build-mcp.js';
+import { type OAuthConfig } from './oauth.js';
+import { type Logger } from './logger.js';
+import { type EmailSender, type MagicLinkStore } from './email-login.js';
+import { type McpInstructionsValue } from './instructions-presets.js';
+import { type ThreadOwnerResolver } from './thread-transport.js';
+import { type SessionChannelServer, type WiredActionRouter } from './session-channel.js';
+import { type McpServerMount, type McpService } from './mcp-mounts.js';
+import { type SchemaCompatMode } from './schema-compat.js';
+export declare function defaultHandlers(deps: {
+    readonly embedding: EmbeddingProvider;
+    readonly vectors: VectorStore;
+    /**
+     * Optional blueprint catalog source. When bound,
+     * `ggui_list_featured_blueprints` enumerates the provider's
+     * catalog; absent = the handler returns an empty list (the
+     * zero-config OSS default).
+     *
+     * `createGguiServer` constructs a `ManifestBlueprintProvider`
+     * from `ggui.json#blueprints.include` at boot and threads it in
+     * here — that's how manifest-declared UIs surface through the MCP
+     * tool.
+     */
+    readonly blueprints?: BlueprintProvider;
+    /**
+     * UI registry consulted by `ggui_render_blueprint`. When bound,
+     * the render handler is registered and resolves every call through
+     * this registry's `get(id)` + `getBundle(id)` pair. Absent = the
+     * render handler is omitted from the handler array (no deprecation
+     * shim, no throwing stub — operator sees "tool unavailable" only
+     * if a caller tries to invoke it).
+     *
+     * `createGguiServer` threads `opts.uiRegistry` through when
+     * present. OSS `ggui serve` binds
+     * `@ggui-ai/dev-stack::LocalUiRegistry`.
+     */
+    readonly uiRegistry?: UiRegistry;
+    /**
+     * Handshake-state KV store. When bound, `ggui_handshake` is
+     * registered and the paired `ggui_push({handshakeId})` consume
+     * path is enabled. Both handlers share the same instance so the
+     * write + read sit on one source of truth.
+     *
+     * Absent = handshake handler is NOT registered AND
+     * `ggui_push({handshakeId})` falls back to a rejection shape.
+     */
+    readonly handshake?: {
+        readonly kvStore: KeyValueStore;
+        /**
+         * Optional session store. When bound, `ggui_handshake` validates
+         * the wire `sessionId` against this store (existence + tenant
+         * ownership) before negotiating. OSS sets this to the same store
+         * push uses so the handshake catches unknown / cross-tenant ids
+         * at the earliest boundary; cloud pods omit and validate at push
+         * time via their own DDB-backed path.
+         */
+        readonly sessionStore?: SessionStore;
+        /**
+         * Optional negotiator binding. Absent = `ggui_handshake` stamps
+         * `action: 'create'` + honest no-negotiator reason on the record
+         * (the seam is still real; persistence + consumption still
+         * anchor the round-trip).
+         */
+        readonly negotiator?: HandshakeNegotiator;
+        /**
+         * Optional per-app metadata resolver. When bound, the handshake
+         * handler reads `app.gadgets` and threads the catalog to
+         * the negotiator so synth knows which gadget bindings the app
+         * exposes. Defaults to the same `appMetadataStore` the
+         * `ggui_list_gadgets` tool uses.
+         */
+        readonly appMetadataStore?: AppMetadataStore;
+        /**
+         * Optional resolver for the `serverCapabilities` field on
+         * every handshake response. Composition wires this so iframes
+         * learn which `streamSpec[ch].source.tool` channels they can WS-
+         * subscribe-for vs. must iframe-poll directly. Returning
+         * `undefined` omits the field (universal iframe-polling fallback).
+         */
+        readonly serverCapabilities?: () => import('@ggui-ai/protocol').ServerCapabilities | undefined;
+    };
+    readonly push?: {
+        readonly sessionStore: SessionStore;
+        readonly renderBaseUrl: string;
+        /**
+         * Optional render-URL signer. Returns the query suffix to append
+         * to a minted URL (`sig=...&exp=...`, no leading `?` or `&`).
+         * Absent when `renderSigning: false` is set on boot.
+         * Mirrors the handler-side dep with the same name.
+         */
+        readonly signRenderUrl?: (shortCode: string) => string;
+        /**
+         * Optional bootstrap-credential minter. When present, `ggui_push`
+         * results carry `_meta.ggui.bootstrap`. When absent, they don't —
+         * non-MCP-Apps hosts still get `structuredContent.url` as the
+         * fallback link.
+         */
+        readonly mintBootstrap?: (sessionId: string, appId: string) => {
+            wsUrl: string;
+            token: string;
+            expiresAt: string;
+        };
+        /**
+         * URL of the renderer bundle the thin-shell HTML should fetch
+         * (C8 — plan §C8). Padded onto
+         * {@link GguiBootstrapMeta.runtimeUrl} at `resultMeta` time.
+         * Same-origin default is `/_ggui/iframe-runtime.js`; hosted cloud
+         * operators override to a CDN URL. Required when `mintBootstrap`
+         * is set (the thin shell depends on it); otherwise ignored.
+         *
+         * Function form: callers passing a getter let the handler
+         * resolve the URL per request — auto-derive from
+         * `X-Forwarded-Host` when the TCP peer is loopback so tunnel/
+         * reverse-proxy setups produce absolute URLs that work under
+         * srcdoc iframes (claude.ai). Static `publicBaseUrl` config
+         * still wins.
+         */
+        readonly runtimeUrl?: string | (() => string | undefined);
+        /**
+         * Theme preset id resolved from `ggui.json#theme`. Forwarded onto
+         * `_meta.ggui.bootstrap.themeId` in the `ggui_push` resultMeta so
+         * MCP Apps hosts (claude.ai, Claude Desktop) propagate the
+         * operator's theme into the iframe.
+         */
+        readonly themeId?: string;
+        /** 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.
+         * 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
+         * 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_push`
+         * gates every call through `rateLimiter.check({key:
+         * 'ggui_push:<appId>', cost:1})` before doing any work; denial
+         * surfaces as a `RateLimitedError`. Omitted = unlimited (the
+         * `NoopRateLimiter` server default).
+         */
+        readonly rateLimiter?: RateLimiter;
+        /**
+         * Optional shortCode → session binding index. When present,
+         * `ggui_push` 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
+         * flow (DynamoDB side-table owns lookups), or console not
+         * enabled.
+         */
+        readonly shortCodeIndex?: ShortCodeIndex;
+        /**
+         * Optional provisional-preview wiring. When present, `ggui_push`
+         * kicks off the configured emitter on every qualifying push (the
+         * `evaluateProvisionalPreviewGate` predicate filters MCP Apps
+         * pushes + storyless calls automatically). Absent = no preview
+         * channel traffic.
+         *
+         * Constructed by `createGguiServer` from `opts.provisionalPreview`
+         * plus the late-bound `SessionChannelServer.sendToSession`
+         * closure; callers threading their own handler set can build
+         * `ProvisionalPreviewDeps` directly.
+         */
+        readonly provisionalPreview?: ProvisionalPreviewDeps;
+        /**
+         * Optional generation wiring. When present, `ggui_push` invokes
+         * the supplied {@link UiGenerator} on every story-path call and
+         * appends the generated `StackItem` to the session before
+         * returning `codeReady: true`. Absent = push stays in
+         * placeholder mode (session + shortCode + preview still work,
+         * but no componentCode is produced).
+         *
+         * Callers compose the `GenerationDeps` directly via the
+         * `@ggui-ai/mcp-server-handlers` export — `defaultHandlers`
+         * simply threads the bundle through to `createGguiPushHandler`.
+         */
+        readonly generation?: GenerationDeps;
+        /**
+         * Optional live-subscriber stack-push notifier.
+         * When present, every successful `appendStackItem` inside `ggui_push`
+         * fan-outs a `{type:'push', payload:{stackItem}}` live-channel frame to
+         * every live subscriber on the affected session. Forwarded as-is
+         * to `createGguiPushHandler`.
+         *
+         * Hosts without a session channel (programmatic embedding, Lambda
+         * one-shot) leave this absent — there are no live subscribers to
+         * notify, and the push handler's own no-op-on-absent posture
+         * keeps the path intact.
+         */
+        readonly channelNotifier?: ChannelNotifier;
+        /**
+         * Optional F4 schema compat check hook. When present,
+         * `ggui_push` invokes it immediately
+         * before every `appendStackItem` — if the pending StackItem's
+         * `actionSpec` / `streamSpec` references a tool whose schemas
+         * disagree, the hook throws `SchemaCompatError` and the handler
+         * converts the rejection into an error stack-item + `codeReady:
+         * false`. Forwarded as-is to `createGguiPushHandler`.
+         *
+         * `createGguiServer` binds this closure against the composed
+         * `handlers` list + `opts.schemaCompatCheck` (default `'reject'`)
+         * automatically; callers composing their own push handler via
+         * `defaultHandlers` wire the hook themselves.
+         */
+        readonly checkStackItemContracts?: (shape: {
+            readonly actionSpec?: import('@ggui-ai/protocol').ActionSpec;
+            readonly streamSpec?: import('@ggui-ai/protocol').StreamSpec;
+        }) => void;
+        /**
+         * Optional content-addressable code store. When present together
+         * with {@link codeBaseUrl}, `ggui_push` writes generated
+         * componentCode to the store and surfaces `codeUrl` + `codeHash`
+         * on the response — the sole static-component delivery channel
+         * post-T3-1 (2026-05-13).
+         *
+         * Absent: `ggui_push.resultMeta` omits `codeUrl`. The iframe boots
+         * via live-mode (wsUrl+token) and receives the stack item via the
+         * live-channel WS subscribe. `/r/<shortCode>` + `/api/bootstrap/<shortCode>`
+         * routes ALSO mint `codeUrl` when `codeStore` is set — they derive
+         * the base URL from `req.protocol + req.host` when `codeBaseUrl`
+         * isn't explicit (works for local dev + tunnel deployments).
+         * Forwarded as-is to `createGguiPushHandler`.
+         */
+        readonly codeStore?: CodeStore;
+        /**
+         * Base URL the code-blob route resolves to. Required when
+         * `codeStore` is present so the handler can compose
+         * `<base>/code/<hash>.js`. Forwarded as-is to
+         * `createGguiPushHandler`.
+         */
+        readonly codeBaseUrl?: string;
+        /**
+         * Resolver for the bootstrap field
+         * `streamWebSocketLocalTools`. Mirrors the handshake's
+         * `serverCapabilities.streamWebSocketLocalTools` so iframe-runtime
+         * can pick WS-subscribe vs iframe-poll per channel. Composing
+         * `createGguiServer` wires both from the SAME
+         * `streamWebSocketLocalTools` option — so a server that advertises
+         * a tool on the handshake also surfaces it on the bootstrap.
+         *
+         * Returns undefined ⇒ field omitted from bootstrap ⇒ legacy
+         * "iframe polls everything" path. Returns an empty array ⇒
+         * "WS transport supported but no tool is local" (still useful —
+         * lets the iframe know the server is transport-aware).
+         */
+        readonly streamWebSocketLocalTools?: () => readonly string[] | undefined;
+        /**
+         * Optional bootstrap-refresh seam for the
+         * `ggui_runtime_refresh_bootstrap` 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
+         * paths share one HMAC secret and one refresh-window policy.
+         *
+         * Absent: the tool is NOT registered on this deployment. iframes
+         * fall back to the historical "fresh handshake on every reconnect"
+         * posture — fast via the matcher cache, but more wire traffic than
+         * 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.
+         */
+        readonly bootstrapRefresh?: import('@ggui-ai/mcp-server-handlers/session-mutations').BootstrapRefreshSeam;
+    };
+    /**
+     * `ggui_update` wiring. When present, register the OSS update
+     * handler against the supplied SessionStore + optional live-channel
+     * props_update notifier. The handler reads sessionId / stackItemId
+     * from wire input today, but a future in-process dispatcher can
+     * populate them on the canonical context.
+     *
+     * Absent = `ggui_update` is NOT registered on this server. Hosts
+     * that don't expose props mutation keep the smaller surface (e.g.,
+     * static-blueprint demos, MCP-Apps-only deployments).
+     */
+    readonly update?: {
+        readonly sessionStore: SessionStore;
+        /**
+         * Optional live-subscriber `props_update` notifier — typically a
+         * thin closure over `SessionChannelServer.sendPropsUpdate`.
+         * Forwarded as-is to `createGguiUpdateHandler`. Hosts without a
+         * session channel leave this absent; the handler still persists
+         * via `sessionStore.appendStackItem` on every successful patch.
+         */
+        readonly propsUpdateNotifier?: PropsUpdateNotifier;
+        /**
+         * Bootstrap-credential minter (live trio). When wired, the
+         * `ggui_update` resultMeta emits `_meta.ggui.bootstrap` so MCP Apps
+         * hosts that re-post `ui/notifications/tool-result` via postMessage
+         * can re-apply patched props on the live mount without re-subscribing.
+         * Mirrors the same field on `push` deps; composing hosts wire both
+         * from the same minter.
+         */
+        readonly mintBootstrap?: (sessionId: string, appId: string) => {
+            wsUrl: string;
+            token: string;
+            expiresAt: string;
+        };
+        /** Iframe-runtime bundle URL forwarded onto bootstrap.runtimeUrl.
+         *  Function form mirrors push deps — see {@link BuildMcpDeps.push}. */
+        readonly runtimeUrl?: string | (() => string | undefined);
+        /** Theme preset id forwarded onto bootstrap.themeId. */
+        readonly themeId?: string;
+        /** Theme color mode forwarded onto bootstrap.themeMode. */
+        readonly themeMode?: 'light' | 'dark';
+        /** Live theme getter — overrides static themeId/themeMode per-update. */
+        readonly themeProvider?: () => {
+            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`
+     * 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).
+     *
+     * `defaultSessionTtlSeconds` controls the activity-bump TTL the
+     * handler forwards to `consumeAndClear` on every read. Falls back
+     * to 1 day when omitted.
+     */
+    readonly consume?: {
+        readonly pendingEventConsumer?: PendingEventConsumer;
+        readonly defaultSessionTtlSeconds?: number;
+    };
+    /**
+     * Stream channel wiring for `ggui_emit`. When `push` is bound, the
+     * handler registers automatically; its `sendEnvelope` closes over
+     * `stream.channelProvider`, a lazy getter that resolves the
+     * `SessionChannelServer` at emit time (the channel is constructed
+     * AFTER `defaultHandlers` runs, so a static reference would always
+     * be null on the OSS in-process boot).
+     *
+     * Absent / returns null = no live receiver. Emit still succeeds at
+     * the protocol level; the envelope just isn't fanned out. Matches
+     * cloud's `ggui_emit_accepted_no_receiver` posture.
+     *
+     * The getter pattern lets the OSS server bind once at boot, then
+     * mutate the cell after `createSessionChannelServer` runs.
+     */
+    readonly stream?: {
+        readonly channelProvider?: () => SessionChannelServer | null;
+    };
+    /**
+     * Structured-event logger threaded into handlers that emit
+     * protocol-adherence telemetry — `ggui_consume` fires the yellow-
+     * flag `action_consume_slow` info-event when an event sat in the
+     * pipe past the latency threshold. Absent = silent; the handler's
+     * drain semantics are unaffected.
+     */
+    readonly logger?: Logger;
+    /**
+     * Operational-signal sink. Threaded into handlers that emit named
+     * events (`ggui_new_session` emits `session.created` /
+     * `session.create_failed`). Absent = NoopTelemetrySink semantic.
+     * Lossy + non-throwing per the {@link TelemetrySink} contract.
+     */
+    readonly telemetry?: TelemetrySink;
+    /**
+     * Per-app metadata store backing `ggui_list_gadgets`.
+     * Absent = `createGguiServer` constructs a fresh
+     * `InMemoryAppMetadataStore` seeded with `STDLIB_GADGETS` per app
+     * on first access (sandbox-app permitted-error path inside the
+     * handler also falls back to stdlib, so omitting the store still
+     * yields a working tool).
+     *
+     * Hosted deployments inject an `AppMetadataStore` backed by their per-app
+     * metadata table (cloud's DDB-backed adapter applies the
+     * default-on-read pattern inside `getApp` directly).
+     */
+    readonly appMetadataStore?: AppMetadataStore;
+    /**
+     * Global theme-catalog resolver consumed by `ggui_list_themes` AND by
+     * `ggui_new_session`'s opt-in `requestThemeList` projection. Returns
+     * the full registry every call (kept as a function so additions to
+     * the catalog at runtime — e.g. operator-defined themes in a future
+     * slice — surface without a server restart). When BOTH this and
+     * `appMetadataStore` are bound, `ggui_list_themes` registers; either
+     * absent ⇒ the tool is omitted from the handler array (zero-config
+     * OSS behavior: a deployment that hasn't wired themes simply doesn't
+     * advertise theme picking).
+     *
+     * The CLI binds this to `@ggui-ai/design`'s `listThemes()`; hosted
+     * deployments may project a different shape so this stays
+     * design-package-agnostic at the handler layer.
+     */
+    readonly themes?: () => readonly ThemeCatalogEntry[];
+    /**
+     * Operator-class blueprint tool wiring. When
+     * `generators` + `blueprintStore` + `blueprintSearch` are all
+     * bound, `defaultHandlers` registers the four `ggui_ops_*`
+     * blueprint tools on `/ops`:
+     *
+     *   - `ggui_ops_generate_blueprint` (requires `resolveLlm` +
+     *     `blueprints` too — same deps the push generation path
+     *     reads).
+     *   - `ggui_ops_list_blueprints`
+     *   - `ggui_ops_update_blueprint`
+     *   - `ggui_ops_delete_blueprint`
+     *
+     * Absent = the ops tools are not registered (operator UX falls
+     * back to whatever surface the cloud pod exposes, or the deployment
+     * runs without operator authorship). The list/update/delete trio
+     * registers even when `generate` deps are absent — read-only
+     * operations on an existing store can be useful for inspection.
+     */
+    readonly opsBlueprint?: {
+        readonly registry: GeneratorRegistry;
+        readonly blueprintStore: BlueprintStore;
+        readonly blueprintSearch: BlueprintSearch;
+        /**
+         * Hook into the store's code-body path. When the bound
+         * `blueprintStore` is an `InMemoryBlueprintStore`, pass
+         * `(codeHash, body) => store.putCode(codeHash, body)` so the
+         * generated body is reachable via `getCode(codeHash)`. Cloud
+         * adapters that persist code inside `BlueprintStore.put` omit
+         * this.
+         */
+        readonly putCode?: (codeHash: string, body: string) => void | Promise<void>;
+        /**
+         * Per-app blueprint enumerator — used for the persona near-dup
+         * warning on the generate path. Optional; when omitted the
+         * check is skipped.
+         */
+        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
+         * closure. When absent, the generate handler is NOT registered
+         * (list/update/delete still register).
+         */
+        readonly resolveLlm?: (ctx: import('@ggui-ai/mcp-server-handlers').HandlerContext) => Promise<GenerationCredentials | null> | GenerationCredentials | null;
+        /**
+         * BlueprintProvider passed to the generator (same instance
+         * `defaultHandlers`'s blueprint search reads). Required when
+         * `resolveLlm` is set — generate needs this on its
+         * UiGenerateInput.
+         */
+        readonly blueprints?: BlueprintProvider;
+        /**
+         * 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.
+         */
+        readonly cacheRegistry?: {
+            readonly embedding: EmbeddingProvider;
+            readonly vectorStore: VectorStore;
+        };
+    };
+    /**
+     * Per-domain dep bundles for the twelve operator-class `ggui_ops_*`
+     * handlers covering apps + orgs + connector-keys + coupons. Each
+     * domain is independently optional:
+     * deployments that don't wire the seam simply don't register that
+     * domain's tools (matching `ggui_ops_get_credit_balance`'s pattern).
+     *
+     * OSS deployments (no AppSync, no Cognito) leave these all
+     * undefined and the surface stays narrow. Cloud pods bind
+     * AppSync-backed adapters in a follow-up slice; the handlers ship
+     * here with deps seams only.
+     */
+    readonly opsApps?: {
+        readonly apps: AppsSource;
+        readonly userDefaultApp: UserDefaultAppSource;
+    };
+    readonly opsOrgs?: {
+        readonly orgs: OrgsSource;
+        readonly invites: OrgInvitesSource;
+    };
+    readonly opsConnectorKeys?: {
+        readonly connectorKeys: ConnectorKeysSource;
+    };
+    readonly opsCoupon?: {
+        readonly coupons: CouponRedeemSource;
+    };
+}): ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+export interface CreateGguiServerOptions {
+    /**
+     * Server identity broadcast to MCP clients. Defaults to
+     * `{name: 'ggui-mcp-server', version: '0.0.1', ...}`.
+     */
+    readonly info?: Partial<ServerInfo>;
+    /**
+     * Operator-mode hint that gates the `/devtools/*` namespace.
+     *
+     *   - `'prod'` (default for `ggui serve`): only `/admin/*` mounts.
+     *   - `'dev'` (default for `ggui dev`): `/devtools/*` mounts in
+     *     addition to `/admin/*` and the SPA shows the dev-mode link
+     *     in the TopNav. The dev surfaces are admin-cookie gated, same
+     *     as `/admin/*` — `mode: 'dev'` only changes WHAT mounts, not
+     *     who can reach it.
+     *
+     * When omitted, resolves from `process.env.GGUI_MODE` (`'dev'` →
+     * dev, anything else including unset → prod). Pass an explicit
+     * value to override the env in test fixtures and embedders.
+     */
+    readonly mode?: 'dev' | 'prod';
+    /**
+     * Shared handler set to expose. Defaults to the blueprint-read family
+     * (search + list_featured + render). Pass your own list to add / remove
+     * tools — handlers MUST be `SharedHandler` instances from
+     * `@ggui-ai/mcp-server-handlers` (or shape-compatible custom ones).
+     */
+    readonly handlers?: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+    /**
+     * Identity-kind allowlist for tool registration. When set, handlers
+     * whose `allowedFor` field declares a non-overlapping audience are
+     * skipped at registration time. Handlers without `allowedFor` register
+     * unconditionally.
+     *
+     *   - agent-builder posture sets `['app']` — skips hypothetical
+     *     `['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
+     *     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.
+     *
+     * See `packages/mcp-server-handlers/src/types.ts`
+     * (`SharedHandler.allowedFor`).
+     */
+    readonly allowedKinds?: ReadonlyArray<'app' | 'user' | 'builder'>;
+    /**
+     * Auth adapter. Defaults to `InMemoryAuthAdapter({devAllowAll: true})`
+     * — accepts any non-empty bearer token as the `builder` identity.
+     * Every real deployment SHOULD override this (e.g. with a
+     * `PairingService`-backed adapter).
+     */
+    readonly auth?: AuthAdapter;
+    /**
+     * Vector store for blueprint search. Defaults to `InMemoryVectorStore`.
+     */
+    readonly vectors?: VectorStore;
+    /**
+     * Embedding provider for blueprint search. Defaults to `MockEmbeddingProvider`
+     * — produces deterministic but NOT semantically meaningful vectors.
+     * Swap for a real provider (OpenAI / Bedrock / Voyage / local) in
+     * production.
+     */
+    readonly embedding?: EmbeddingProvider;
+    /**
+     * Per-app metadata source. When bound, threaded into
+     * `defaultHandlers` so `ggui_list_gadgets`,
+     * `ggui_list_themes`, `ggui_new_session({themeId?})`, and the
+     * handshake's `app.gadgets` lookup all read from the same
+     * store. The CLI binds an `InMemoryAppMetadataStore` seeded from
+     * `ggui.json#theme.preset` (so every appId picks up the operator's
+     * chosen default theme without an explicit `register()`); hosted
+     * deployments bind a multi-tenant adapter.
+     *
+     * Absent ⇒ `defaultHandlers` constructs a fresh
+     * `InMemoryAppMetadataStore` per request site that needs one (no
+     * cross-handler sharing) and `ggui_list_themes` is NOT registered.
+     */
+    readonly appMetadataStore?: AppMetadataStore;
+    /**
+     * Global theme-catalog resolver. When bound alongside
+     * `appMetadataStore`, registers `ggui_list_themes` and projects the
+     * same catalog into `ggui_new_session({requestThemeList: true})`
+     * outputs. Read each call so additions to the registry at runtime
+     * (operator-defined themes in a future slice) surface without a
+     * restart.
+     *
+     * The OSS CLI binds this to `@ggui-ai/design`'s `listThemes()`;
+     * hosted deployments may project a different shape. Kept as a
+     * resolver function so this surface stays design-package-agnostic.
+     */
+    readonly themes?: () => readonly ThemeCatalogEntry[];
+    /**
+     * Blueprint catalog source consulted by
+     * `ggui_list_featured_blueprints`. Omitted = the handler returns
+     * an empty list (zero-config default). The `ggui-cli` binding
+     * constructs a `ManifestBlueprintProvider` from the declared
+     * `ggui.json#blueprints.include` manifests and passes it here,
+     * so `ggui serve` surfaces every authored UI through the MCP tool
+     * without any code change per deployment.
+     *
+     * Passing `blueprintProvider:` is what makes the `ggui.json`
+     * manifest's blueprint declarations take effect — the manifest
+     * shape stops being inert once a provider is wired.
+     */
+    readonly blueprintProvider?: BlueprintProvider;
+    /**
+     * Admin-blueprints transport (`POST /admin/blueprints`) — runtime
+     * manifest registration into the active {@link blueprintProvider}.
+     *
+     *   - `undefined` (default) or an object `{path?}` — mount the
+     *     route at `/admin/blueprints` (override via `{path: '/x'}`).
+     *     Only actually mounted when {@link blueprintProvider} is also
+     *     wired; without a caller-supplied provider the default
+     *     provider built inside `defaultHandlers` is unreachable from
+     *     this scope and silently mounting would surprise operators.
+     *   - `{path: null}` — disable the route explicitly while leaving
+     *     the provider wired (operators who want the provider but not
+     *     the HTTP admin surface).
+     *   - `false` — same as `{path: null}`, but shorter.
+     *
+     * In-memory only: runtime-registered manifests survive until the
+     * server process exits. Plan explicitly permits this choice; a
+     * follow-up slice may add disk persistence if operators ask.
+     *
+     * Auth: builder-bearer, same gate as `/admin/pair/init`.
+     */
+    readonly adminBlueprints?: false | {
+        readonly path?: string | null;
+    };
+    /**
+     * UI registry consulted by `ggui_render_blueprint`. When present, the
+     * render handler is registered on the MCP wire and resolves every
+     * call through this registry's `get(id)` + `getBundle(id)` pair.
+     * When absent, `ggui_render_blueprint` is NOT registered at all —
+     * callers that attempted to invoke it get a clean "tool not
+     * available" MCP response instead of a throwing shim.
+     *
+     * OSS `ggui serve` binds `@ggui-ai/dev-stack::LocalUiRegistry` here
+     * (manifest-backed, compile-on-demand via esbuild). Hosted or
+     * programmatic embedders plug in their own implementation (cloud
+     * origin, S3-backed, etc.) — the handler is pure over the
+     * `UiRegistry` interface.
+     */
+    readonly uiRegistry?: UiRegistry;
+    /**
+     * Primitive catalogs declared in `ggui.json#primitives.{packages,local}`
+     * and resolved at boot by `discoverPrimitives()` in
+     * `@ggui-ai/project-config/node`. Threaded through here so future
+     * consumers (generator wiring, capability introspection) can
+     * enumerate every declared primitive source without re-reading the
+     * manifest.
+     *
+     * The server itself does NOT yet thread these into the generation
+     * pipeline. Making the catalogs visible at boot is the minimum
+     * honest "capability is consumed" signal: the declaration is no
+     * longer inert; any in-process host can read
+     * `server.primitiveCatalogs`.
+     *
+     * Omitted = the zero-config default (the CLI passes the single
+     * shipped `@ggui-ai/design/primitives` catalog; programmatic hosts
+     * may pass whatever they discovered themselves).
+     */
+    readonly primitiveCatalogs?: readonly DiscoveredPrimitiveCatalog[];
+    /**
+     * Theme resolved at boot from `ggui.json#theme` by
+     * `loadTheme()` in `@ggui-ai/project-config/node`. Threaded through
+     * here so future consumers (console bootstrap, render endpoint,
+     * MCP apps iframe) can pull the token tree + pre-rendered CSS block
+     * without re-reading the manifest.
+     *
+     * The server itself does NOT yet inject theme CSS into console
+     * or bake it into MCP responses. Making the theme visible at boot
+     * is the minimum honest "capability is consumed" signal: the
+     * declaration stops being inert; any in-process host can read
+     * `server.theme`.
+     *
+     * Omitted = the zero-config default (the server builds a
+     * `LoadedTheme` backed by `@ggui-ai/design`'s shipped `lightTheme`
+     * internally; `server.theme.source === 'default'`).
+     */
+    readonly theme?: LoadedTheme;
+    /**
+     * Optional callback that persists a theme selection back to disk.
+     *
+     * The console `/theme` route mutates `ggui.json#theme` via this
+     * callback. The server never touches the filesystem itself — the
+     * caller (typically `@ggui-ai/cli`'s serve command) provides a
+     * writer that knows where `ggui.json` lives and how to rewrite
+     * just the `theme` field while preserving formatting + comments.
+     *
+     * Signature: receives the new {@link ThemeConfig} (or `null` to
+     * clear the field and fall back to defaults). Returns a promise
+     * that resolves once the write is durable. Throwing surfaces as
+     * a 500 from `POST /ggui/console/theme` with the error message
+     * forwarded to the operator.
+     *
+     * Omitted = `POST /ggui/console/theme` returns 501
+     * (`writer_not_configured`). The picker stays browsable; clicking
+     * "save" surfaces the missing-writer error instead of silently
+     * writing nowhere.
+     */
+    readonly themeWriter?: ThemeWriter;
+    /**
+     * Optional callback that writes an uploaded DTCG theme document to a
+     * file alongside `ggui.json`. Pairs with {@link themeWriter}: the
+     * `POST /ggui/console/theme/upload` route invokes this first, then
+     * calls `themeWriter` with `{ file: './<filename>', mode }`.
+     *
+     * Omitted = the upload route returns 501 and the picker hides its
+     * "Upload theme.json" button. Provided alone (without a writer) is
+     * also treated as "not configured" — both side-effects must land for
+     * an upload to be meaningful.
+     */
+    readonly themeFileUploader?: ThemeFileUploader;
+    /**
+     * Live-theme getter. When set, the `ggui_push` handler reads this
+     * on every result-meta computation and embeds the returned `id` /
+     * `mode` into `_meta.ggui.bootstrap`. 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
+     * captured `themeId` at boot from the static `theme` opt and
+     * silently ignored every subsequent ggui.json edit until restart.
+     *
+     * Returning `undefined` means "no theme override" — the static
+     * `theme` opt's resolved id/mode (if any) take effect. Returning
+     * `{ id, mode? }` always wins over the static path.
+     */
+    readonly themeProvider?: () => {
+        readonly id?: string;
+        readonly mode?: 'light' | 'dark';
+    } | undefined;
+    /**
+     * Optional change notifier — fires when the operator's theme
+     * selection changes via `POST /ggui/console/theme` (or the
+     * `/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
+     * without restarting the server.
+     *
+     * `next` matches `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;
+    /**
+     * Map a resolved identity to the `appId` used by handlers for tenant
+     * scoping. Defaults to `defaultAppIdFromIdentity` — single-user
+     * `'builder'` for builder-kind identities, `userId`/`workspaceId`
+     * for user-kind.
+     */
+    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.
+     *
+     * Threaded into the well-known protected-resource metadata so OAuth
+     * clients discover the right resource URL, and into the route table
+     * so `app.post(${path})` / `app.get/delete(${path})` mount on it.
+     */
+    readonly universalMcpPath?: string;
+    /**
+     * Per-tenant URL routing. When set, the factory
+     * additionally mounts `${pathPrefix}/:${paramName}(${paramPattern})`
+     * 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',
+     * 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
+     * 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).
+     *
+     * 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.
+     *
+     * `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.
+     */
+    readonly perAppRouting?: {
+        readonly paramName: string;
+        readonly paramPattern: string;
+        /**
+         * Optional path prefix prepended to the per-app route. Cloud
+         * `mcp.ggui.ai` uses `'/apps'` so URLs are
+         * `mcp.ggui.ai/apps/<appId>` — leaves the bare root for system
+         * routes (`/health`, `/oauth/*`, `/.well-known/*`) without
+         * collision concerns. Omit when the pattern alone guarantees
+         * non-collision (e.g. UUIDs, opaque hex of fixed length).
+         */
+        readonly pathPrefix?: string;
+        readonly authorize?: (urlAppId: string, identity: AuthResult) => Promise<void>;
+    };
+    /** Structured logger. Defaults to `createConsoleLogger()`. */
+    readonly logger?: Logger;
+    /**
+     * Optional error-to-HTTP mapper invoked on any handler / transport
+     * exception that surfaces past the MCP SDK. When the mapper returns
+     * a `{status, code, message}` triple the factory writes that JSON-RPC
+     * error response instead of the default `500 / -32603 'Internal
+     * server error'`. Returning `undefined` (or omitting the option)
+     * preserves the default.
+     *
+     * Use case: hosted closed-runtime deployments throw domain errors from
+     * tool handlers (e.g. `SessionAccessError` "this session 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
+     * otherwise.
+     *
+     * The mapper MUST NOT throw. It runs inside the factory's outer
+     * `catch (err)` block; any throw from the mapper itself is treated
+     * as if it returned `undefined` (default 500).
+     */
+    readonly errorMapper?: (err: unknown) => {
+        readonly status: number;
+        readonly code: number;
+        readonly message: string;
+    } | undefined;
+    /**
+     * BYOK provider-key store consumed by the operator-facing
+     * `/ggui/console/llm-keys` admin API and (today, transparently
+     * via `ggui-cli`'s `ByokResolver`) by the generation pipeline.
+     *
+     * When set, the gated route block mounts:
+     *   - `GET    /ggui/console/llm-keys`           — list providers + presence
+     *   - `POST   /ggui/console/llm-keys`           — set a provider's key
+     *   - `DELETE /ggui/console/llm-keys/:provider` — clear (idempotent)
+     *
+     * The store is the SAME instance backing the CLI's `ByokResolver`
+     * second-step lookup (`~/.ggui/credentials.json` by default) — writing
+     * via this API has immediate effect on subsequent generations because
+     * `PlaintextFileProviderKeyStore` re-reads the file on every `get()`.
+     *
+     * Omitted (default): the route block is NOT mounted. Operators
+     * who want the /settings UI to work pass a store explicitly. The
+     * CLI binding does so for personal-mode `ggui serve`; programmatic
+     * embedders (test suites, custom hosts) can omit it.
+     */
+    readonly providerKeys?: ProviderKeyStore;
+    /**
+     * Map an authenticated request to the BYOK scope key the
+     * `/ggui/console/llm-keys` endpoints write under (and that the
+     * generation pipeline reads via `ProviderKeyStore.get(scope, provider)`).
+     *
+     * Default depends on {@link providerKeysGate}:
+     *   - `'admin-token'` (default): scope is always `'global'` — the
+     *     OSS-personal posture: every caller who clears the admin gate
+     *     operates on the single global keyset stored in
+     *     `~/.ggui/credentials.json`.
+     *   - `'auth-adapter'`: scope is derived from the authenticated
+     *     identity — `userId` for `kind: 'user'`, `appId` for `kind: 'app'`,
+     *     and `'global'` for `kind: 'builder'` (which under multi-tenant
+     *     is rejected at the gate before this fires anyway).
+     *
+     * Operators with composite scopes (`${appId}:${userId}` for per-app-
+     * per-user keysets) override this; the underlying store treats the
+     * value as opaque. The `identity` arg is `null` under the
+     * `'admin-token'` gate (no auth-adapter call happens) and the
+     * resolved `AuthResult` under the `'auth-adapter'` gate.
+     */
+    readonly providerKeyScope?: (req: Request, identity: AuthResult | null) => string;
+    /**
+     * Which gate guards the `/ggui/console/llm-keys` plane.
+     *
+     *   - `'admin-token'` (default — OSS-personal posture): the gate
+     *     accepts the admin bearer (Authorization header or
+     *     `ggui_console_admin` cookie). Single global keyset; the
+     *     /settings UI lets the operator paste keys that everyone uses.
+     *   - `'auth-adapter'` (multi-tenant posture): the gate calls the
+     *     server's configured `AuthAdapter` (same path as `/mcp`). Each
+     *     authenticated end-user manages their OWN keys, scoped by
+     *     {@link providerKeyScope} (default: `userId` / `appId`).
+     *     `kind: 'builder'` identities are rejected at the gate — the
+     *     posture is meaningless without a real per-caller identifier.
+     *
+     * Both gates require `providerKeys` to be set; route block is
+     * unmounted otherwise. Under `'admin-token'`, the route block is
+     * additionally unmounted when the server has no admin token wired
+     * (e.g. embedding hosts that don't surface console routes). Under
+     * `'auth-adapter'`, the admin token is irrelevant — the route is
+     * mounted whenever `providerKeys` is set.
+     */
+    readonly providerKeysGate?: 'admin-token' | 'auth-adapter';
+    /** Express body size limit. Defaults to `'4mb'`. */
+    readonly bodyLimit?: string;
+    /**
+     * Session store — backing plane for the live-channel session endpoint
+     * (and future OSS session-reading MCP tools). Defaults to
+     * `InMemorySessionStore`, which is fine for OSS zero-config / dev.
+     * SQLite / Postgres / Redis adapters bind via the same interface
+     * when they land.
+     */
+    readonly sessionStore?: SessionStore;
+    /**
+     * Outbound stream replay buffer for the live-channel endpoint. Defaults
+     * to a fresh `InMemorySessionStreamBuffer` — fine for OSS zero-config
+     * / dev. Operators who need durability layer a different
+     * `SessionStreamBuffer` implementation behind this seam.
+     *
+     * Only used when `sessionChannel` is enabled. Ignored otherwise.
+     */
+    readonly streamBuffer?: SessionStreamBuffer;
+    /**
+     * Enable the OSS live-channel session endpoint at `/ws` (configurable).
+     *
+     *   - `false` (default): no session 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.
+     *   - `{ path?: string }`: override the mount path.
+     *
+     * The live channel is where the live-contract enforcement point
+     * lives. Enabling this makes the OSS server a second real consumer
+     * of the shared `@ggui-ai/mcp-server-handlers/session-mutations`
+     * helpers.
+     */
+    readonly sessionChannel?: 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
+     * stackItemId-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 `createSessionChannelServer`.
+     */
+    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
+     * `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
+     * direct polling via the MCP host proxy.
+     *
+     * The `allowlist` is also advertised on every successful
+     * `ggui_handshake` response as
+     * `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 `createSessionChannelServer` (see
+     * `SessionChannelOptions.streamWebSocketLocalTools`).
+     */
+    readonly streamWebSocketLocalTools?: import('./session-channel.js').SessionChannelLocalToolsOptions;
+    /**
+     * 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
+     * `createSessionChannelServer`. See `SessionChannelOptions
+     * .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
+     * 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
+     * via the protocol-shipped builtin regardless of this option.
+     *
+     * Pass `new Map()` (explicitly empty) to DISABLE the A2UI default —
+     * useful in tests that want to assert `validateStreamData`'s
+     * fall-through behavior on `_ggui:preview` without the adapter
+     * running.
+     */
+    readonly extraReservedValidators?: ReadonlyMap<string, import('@ggui-ai/protocol').ReservedChannelValidator>;
+    /**
+     * Protocol-version handshake policy for the session channel. Forwarded
+     * verbatim to `createSessionChannelServer` (see
+     * `SessionChannelOptions.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.
+     */
+    readonly versionPolicy?: 'advisory' | 'reject';
+    /**
+     * Policy for the schema compat check. Checks that every
+     * `actionSpec[name]` tool ref points at a tool whose
+     * `inputSchema` is a superset of the
+     * action's declared `schema`, and that every
+     * `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).
+     *     Canonical enforcement posture for launch.
+     *   - `'warn'` — violations log through the server's structured
+     *     logger (`schema_compat_warn` event with the full report
+     *     attached). Caller's flow continues. Used for controlled
+     *     migration windows.
+     *   - `'off'` — check is skipped entirely. Test / opt-out
+     *     convenience.
+     *
+     * Applies to both check points wired by this server:
+     *
+     *   1. The console `POST /ggui/console/blueprint/:id/try`
+     *      endpoint (blueprint registration — fires when a manifest
+     *      blueprint's pre-declared `actionSpec` / `streamSpec`
+     *      references a tool mounted on this server).
+     *   2. The `ggui_push` generation path (push-time — defensive
+     *      wiring for when the generator starts emitting
+     *      actionSpec / streamSpec on its `UIGenerationResponse`;
+     *      current generators emit only componentCode, but the
+     *      hook is in place so the check fires automatically when
+     *      generator outputs widen).
+     *
+     * See `./schema-compat.ts` for the check helper contract, and
+     * `@ggui-ai/protocol/validation/{schema-subset,zod-to-json-schema}`
+     * for the underlying primitives.
+     */
+    readonly schemaCompatCheck?: SchemaCompatMode;
+    /**
+     * Enable OAuth 2.1 + PKCE + Dynamic Client Registration on this
+     * server (per MCP spec 2025-06-18+).
+     *
+     *   - `false` / omitted (default): OAuth routes NOT mounted;
+     *     `WWW-Authenticate` header NOT set on 401 responses. Pure-bearer
+     *     clients (CLI tools shipping `Authorization: Bearer ggui_user_*`)
+     *     still work; OAuth-discovery clients (Claude Desktop, claude.ai,
+     *     Goose, etc.) bail with "couldn't reach" / "couldn't authenticate".
+     *   - `true`: enable with defaults. Mounts:
+     *       GET  /.well-known/oauth-protected-resource (RFC 9728)
+     *       GET  /.well-known/oauth-authorization-server (RFC 8414)
+     *       POST /oauth/register (RFC 7591 DCR)
+     *       GET  /oauth/authorize (paste-key form)
+     *       POST /oauth/authorize (form submit)
+     *       POST /oauth/token (code → access_token)
+     *     Adds `WWW-Authenticate: Bearer realm=mcp, resource_metadata=…`
+     *     header to 401 responses on `/mcp`. Storage defaults to
+     *     {@link InMemoryOAuthStorage}.
+     *   - `{ issuerUrl?, storage? }`: explicit config. `issuerUrl` is the
+     *     public origin the server advertises in metadata + redirects
+     *     (defaults to derivation from `X-Forwarded-Proto`/`Host`);
+     *     `storage` swaps the in-memory map for a Redis/DDB-backed
+     *     implementation when multi-replica deployments need stateless
+     *     token exchange.
+     *
+     * The OAuth flow is a one-time ceremony per Claude Desktop install:
+     * the user pastes their `ggui_user_*` API key once, the server hands
+     * it back as the `access_token`. Subsequent `/mcp` calls hit the
+     * existing {@link AuthAdapter} (e.g. `ApiKeyAuthAdapter`) unchanged.
+     * See `./oauth.ts` for the full flow.
+     */
+    readonly oauth?: boolean | OAuthConfig;
+    /**
+     * Enable the MCP Apps outbound delivery path on this server.
+     *
+     *   - `false` / omitted (default): `ggui_push` is NOT registered;
+     *     `ui://ggui/session` is NOT served; `io.modelcontextprotocol/ui`
+     *     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;
+     *     throws at construction otherwise. `renderBaseUrl` defaults to
+     *     `"http://localhost/r/"` (dev-sensible; production operators
+     *     override).
+     *   - `{ renderBaseUrl?, shellHtml?, wsUrl? }`: explicit config.
+     *
+     * When enabled, FOUR things happen on every fresh per-request
+     * `McpServer`:
+     *   1. `ggui_push` tool is registered, carrying `_meta.ui.resourceUri:
+     *      "ui://ggui/session"` and `_meta.ui.visibility: ["model"]` on
+     *      its declaration.
+     *   2. `ui://ggui/session` is served via `resources/read`.
+     *   3. `io.modelcontextprotocol/ui` is advertised in the server's
+     *      `initialize` capabilities (under `experimental`).
+     *   4. Each `ggui_push` result carries `_meta.ggui.bootstrap` (wsUrl
+     *      + short-TTL token + expiresAt). The session-channel server
+     *      accepts that token on `subscribe` and issues a longer-TTL
+     *      `sessionToken` in the ack for iframe reconnects.
+     */
+    readonly mcpApps?: boolean | {
+        readonly renderBaseUrl?: string;
+        readonly shellHtml?: string;
+        /**
+         * External WebSocket URL the iframe should open, visible to
+         * MCP Apps hosts. Defaults to `"ws://localhost:<port>/ws"`
+         * — only sensible for local dev. Production operators pass
+         * their public URL (`wss://mcp.example.com/ws`).
+         */
+        readonly wsUrl?: string;
+    };
+    /**
+     * Iframe-runtime bundle mount (C8 — plan §C8).
+     *
+     * The thin-shell HTML served from `ui://ggui/session` dynamic-
+     * script-loads the renderer bundle from this URL. The server needs
+     * to either (a) serve the bundle itself (default), or (b) publish
+     * the operator-owned URL on `_meta.ggui.bootstrap.runtimeUrl`
+     * so the shell knows where to look.
+     *
+     *   - `true` / omitted (default when `mcpApps` is on): serve the
+     *     bundle via `express.static` at `/_ggui/iframe-runtime.js` from the
+     *     `@ggui-ai/iframe-runtime` package's built `dist/iframe-runtime.js`.
+     *     `runtimeUrl` on the bootstrap becomes `/_ggui/iframe-runtime.js`.
+     *   - `false`: no static mount. Operator MUST supply
+     *     `runtime.url` so the bootstrap still carries a valid URL
+     *     (or the shell will fail `MALFORMED_BOOTSTRAP`).
+     *   - `{ path?, distDir?, url? }`: explicit config. `path` is the
+     *     HTTP route under which the bundle is served (default
+     *     `/_ggui/iframe-runtime.js`); `distDir` overrides the
+     *     {@link @ggui-ai/iframe-runtime/server!RUNTIME_BUNDLE_FILE} auto-
+     *     resolution for advanced embeddings; `url` overrides the URL
+     *     written onto the bootstrap (useful when a CDN / proxy fronts
+     *     the bundle — mount here for local verification, publish the
+     *     external URL to clients).
+     *
+     * Ignored entirely when `mcpApps` is disabled.
+     */
+    readonly runtime?: boolean | {
+        readonly path?: string;
+        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
+     * mints a random 32-byte secret at boot — fine for dev + a single
+     * long-running process, wrong for multi-host deployments (each host
+     * would reject the others' tokens). Production operators MUST pass
+     * a deterministic secret (typically from env / secrets manager).
+     *
+     * Ignored entirely when MCP Apps is disabled.
+     */
+    readonly bootstrapSecret?: string;
+    /**
+     * Enable the pairing transport. Adds `POST /pair` (public, completes a
+     * pairing handshake) and by default `POST /admin/pair/init` (builder-
+     * authenticated, mints a one-shot code).
+     *
+     *   - `false` / omitted (default): pairing routes are NOT mounted.
+     *     `GguiServer.pairingService` is `null`. The server is still a
+     *     valid MCP server; pairing is simply not part of its surface.
+     *   - `true`: enable with defaults. Constructs an
+     *     `InMemoryPairingService` and bridges its `onTokenIssued` /
+     *     `onTokenRevoked` callbacks into the configured {@link auth}
+     *     adapter. Requires the adapter to implement
+     *     `registerToken`/`unregisterToken` (see
+     *     `isTokenRegisteringAuthAdapter`); throws at construction
+     *     otherwise.
+     *   - `{ service?, serverName?, path?, adminInitPath? }`: explicit
+     *     config. When `service` is omitted, the default
+     *     `InMemoryPairingService` + auth-adapter bridge is constructed
+     *     as above. When `service` is provided, the caller owns the
+     *     service's lifecycle AND the auth bridge — `createGguiServer`
+     *     mounts the HTTP routes only.
+     *
+     * Pairing-minted tokens authenticate subsequent `/mcp` and live-channel
+     * requests through the normal bearer path — the bridge registers them
+     * into the active AuthAdapter, NOT a parallel pairing-only store.
+     */
+    /**
+     * Enable the persistent-chat HTTP transport. Mounts six routes under
+     * the configured path (defaults to `/threads`):
+     *
+     *   POST   /threads                  — createThread
+     *   GET    /threads                  — listThreads
+     *   GET    /threads/:id              — getThread
+     *   PATCH  /threads/:id              — applyThreadAction
+     *   GET    /threads/:id/messages     — listMessages
+     *   POST   /threads/:id/messages     — appendMessage
+     *
+     *   - Omitted / undefined (default): no thread routes. The server is
+     *     still a valid MCP server + optional live-channel host; persistent
+     *     chat simply isn't part of its surface.
+     *   - `{ store: ThreadStore }`: enable with the supplied store. OSS
+     *     dev callers pass `new InMemoryThreadStore()`. SQLite binding
+     *     (Step 6 of the slice) plugs in the same way.
+     *   - Extra fields (`path`, `ownerFromIdentity`) are power-user
+     *     overrides — sensible defaults otherwise.
+     *
+     * SSE observe endpoint (`GET /threads/:id/stream`) is Step 5 of the
+     * same slice; it lands behind this option but in a separate route.
+     */
+    readonly threads?: {
+        readonly store: ThreadStore;
+        /**
+         * URL prefix. Defaults to `/threads`. Operators who already have
+         * another server mounted under `/threads` override here.
+         */
+        readonly path?: string;
+        /**
+         * Identity → ownerId mapping override. Defaults to
+         * `defaultThreadOwnerFromIdentity` from `thread-transport.ts`:
+         * pairing metadata → `paired_<pairingId>`; cognito → `cognito_<sub>`;
+         * kind=user → `user_<workspaceId ?? userId>`; everything else →
+         * `DEFAULT_BUILDER_OWNER_ID` ("builder").
+         */
+        readonly ownerFromIdentity?: ThreadOwnerResolver;
+        /**
+         * Durability advertisement for the thread store. Surfaced on
+         * `GET /ggui/health` under `threads.durability` so Portal + other
+         * clients can decide whether to display a non-durable caveat.
+         *
+         *   - `'durable'`: data survives server restart. `ggui serve`
+         *     resolves this automatically when `storage.threads.driver ===
+         *     'sqlite'` is declared in `ggui.json`.
+         *   - `'ephemeral'` (default): in-memory or otherwise lost on
+         *     restart. Safe default — overclaiming durability would mislead
+         *     Portal into hiding its caveat.
+         *
+         * Embedded hosts that supply a custom `store` also supply the
+         * right durability claim; the server doesn't inspect the store
+         * instance to guess.
+         */
+        readonly durability?: 'durable' | 'ephemeral';
+    };
+    readonly pairing?: boolean | {
+        /**
+         * Custom PairingService implementation. When present, the
+         * caller owns the service's full lifecycle including any
+         * `onTokenIssued` / `onTokenRevoked` bridging into their auth
+         * adapter. When absent, a default `InMemoryPairingService`
+         * is constructed and bridged automatically.
+         */
+        readonly service?: PairingService;
+        /**
+         * Server display name the default `InMemoryPairingService`
+         * surfaces in `PairingInit.serverName` and `PairingCompletion
+         * .serverName`. Defaults to `info.name`. Ignored when
+         * {@link service} is provided.
+         */
+        readonly serverName?: string;
+        /**
+         * When set, the default `InMemoryPairingService` persists
+         * its pairings + idCounter to this JSON file (atomic write,
+         * `0600` perms) and restores them on subsequent boots —
+         * tokens survive a `ggui serve` restart. Tokens are stored in
+         * **plaintext**: assume the file lives on operator-controlled
+         * disk (e.g. `~/.ggui/keys.json`). For multi-operator or
+         * untrusted-host deployments swap to a hashed adapter.
+         * Ignored when {@link service} is provided.
+         */
+        readonly persistencePath?: string;
+        /**
+         * URL path the `POST /pair` route is mounted at. Defaults to
+         * `/pair`.
+         */
+        readonly path?: string;
+        /**
+         * URL path the `POST /admin/pair/init` route is mounted at.
+         * Defaults to `/admin/pair/init`. Pass `null` to disable the
+         * HTTP-triggered mint path — embedded hosts that call
+         * `GguiServer.pairingService.initPairing()` programmatically
+         * may not want the route.
+         */
+        readonly adminInitPath?: string | null;
+        /**
+         * URL-template the `POST /admin/pair/:pairingId/revoke` route
+         * is mounted at. Defaults to `/admin/pair/:pairingId/revoke`.
+         * Pass `null` to disable the HTTP-triggered revoke path —
+         * embedded hosts that call `GguiServer.pairingService
+         * .revokePairing()` programmatically may not want the route.
+         */
+        readonly adminRevokePath?: string | null;
+    };
+    /**
+     * Operational / product-signal sink. Bound once at composition;
+     * transports + handlers call `emit` for lossy counts / durations.
+     * Defaults to {@link NoopTelemetrySink} — an OSS deployment that
+     * doesn't care about metrics sees zero-cost no-op. Real adapters
+     * (OTLP, CloudWatch, Datadog) plug in here.
+     *
+     * Sync, fire-and-forget, MUST NOT throw — see `TelemetrySink`.
+     */
+    readonly telemetry?: TelemetrySink;
+    /**
+     * Durable audit-log sink for privileged actions (pairing-token
+     * lifecycle today; API-key lifecycle + admin mutations follow in
+     * later slices). Bound once at composition; ingress points await
+     * `record` and surface failure.
+     *
+     * Defaults to {@link NoopAuditSink} with a boot-time `warn` log —
+     * same pattern as the missing-auth-adapter warning. Production
+     * deployments MUST bind a durable implementation (DynamoDB /
+     * Postgres journal / Kafka topic) because privileged actions
+     * leaving no record is a compliance breach.
+     */
+    readonly audit?: AuditSink;
+    /**
+     * Admission-control limiter applied at the highest-cost handler
+     * ingress — today just `ggui_push`. Defaults to
+     * {@link NoopRateLimiter} (always allows). Per-handler wiring maps
+     * denials from a `RateLimitedError` to HTTP 429 + `Retry-After` /
+     * `X-RateLimit-*` headers at the transport boundary.
+     *
+     * For real policy (per-app or per-identity windows), bind a
+     * `FixedWindowRateLimiter` over a durable
+     * {@link import('@ggui-ai/mcp-server-core').QuotaStore} — or any
+     * adapter that implements the same contract. Handlers never see the
+     * policy shape; they just call `check` and honor the decision.
+     *
+     * Wiring only the highest-cost handler is intentional. Other
+     * handlers (blueprint search, thread reads, pairing) follow as
+     * individual slices when real policy signal demands it.
+     */
+    readonly rateLimiter?: RateLimiter;
+    /**
+     * CSRF secret used to HMAC-sign double-submit tokens for browser
+     * POST/PUT/DELETE/PATCH endpoints. Production deployments pass a
+     * stable value (so tokens survive a deploy); OSS dev defaults to a
+     * fresh per-process random — pre-restart tokens won't validate
+     * after restart, which is acceptable for dev where sessions don't
+     * survive a restart anyway.
+     */
+    readonly csrfSecret?: string;
+    /**
+     * Trust the `X-Forwarded-For` header for per-IP rate limiting on
+     * `/pair`. Operators behind a reverse proxy / load
+     * balancer that strips and re-attaches a trusted client-IP header
+     * pass `true`; localhost-only dev paths leave it falsy so requests
+     * key on `req.socket.remoteAddress` instead.
+     */
+    readonly trustProxy?: boolean;
+    /**
+     * Public base URL the server is reachable at — REQUIRED for OAuth
+     * login routes. Composes the `redirect_uri` registered
+     * with each OAuth provider's console as
+     * `${publicBaseUrl}/ggui/oauth-login/<providerId>/callback`. If
+     * absent, OAuth login routes are NOT mounted (admin transport
+     * still mounts so operators can paste credentials in advance).
+     */
+    readonly publicBaseUrl?: string;
+    /**
+     * Render-URL signing config — capability-URL hardening.
+     *
+     * When set (default), every minted `/r/<code>` URL carries
+     * `?sig=<hmac>&exp=<unix>`. The gate on `/r/` + `/api/bootstrap/`
+     * verifies the sig + freshness before lookup; tampered or expired
+     * URLs return 410.
+     *
+     *   - `secret`: 32-byte hex key. When omitted, a fresh random key
+     *     is minted at boot — restart = every outstanding URL dies
+     *     (good for incident response, bad if you don't want it).
+     *     Pin a stable secret to survive restarts.
+     *   - `ttlSeconds`: URL lifetime. Defaults to 24h (86400s).
+     *   - Set `renderSigning: false` to disable the layer entirely
+     *     (`--no-render-signing`). URLs revert to the plain unsigned
+     *     form. Use for legacy hosts that strip query strings or
+     *     tooling that pre-records URLs.
+     */
+    readonly renderSigning?: false | {
+        readonly secret?: string;
+        readonly ttlSeconds?: number;
+    };
+    /**
+     * Per-shortCode rate-limit config. Defends `/r/` and
+     * `/api/bootstrap/` against brute-force scans.
+     *
+     *   - `windowSeconds` + `limit`: bucket size. Default 60s / 30 hits.
+     *   - `false`: disable rate limiting entirely (CI/test convenience).
+     *
+     * Rate-limit decision is per-shortCode (not per-peer) — cross-origin
+     * iframe hosts NAT every user through one proxy; per-peer limits
+     * would either rate-limit the whole host or accept every peer.
+     * See render-rate-limit.ts for the rationale.
+     */
+    readonly renderRateLimit?: false | {
+        readonly windowSeconds?: number;
+        readonly limit?: number;
+    };
+    /**
+     * Override path for `~/.ggui/oauth-providers.json`. Mainly for
+     * tests + per-deployment isolation. Defaults to the home-relative
+     * path resolved by `createOAuthProvidersStore`.
+     */
+    readonly oauthProvidersPath?: string;
+    /**
+     * Server-level instructions surfaced on the MCP `InitializeResult.
+     * instructions` field. MCP hosts (Claude.ai web, Claude Desktop,
+     * the MCP Inspector) inject this into the LLM's system prompt as a
+     * top-level block, ABOVE per-tool descriptions — influencing
+     * "how should I behave with this server's tools generally?"
+     *
+     *   - Omit (`undefined`): use the package default (`'default'`
+     *     preset — sensible "ggui first when UI fits" nudge).
+     *   - Preset name: `'default' | 'aggressive' | 'minimal' | 'off'`.
+     *     `'aggressive'` matches a manual "always use ggui_*" custom
+     *     instruction. `'off'` omits the field entirely.
+     *   - Arbitrary string: used verbatim. Lets operators write
+     *     deployment-specific copy without forking the package.
+     *
+     * Since OSS forks can edit `instructions-presets.ts` directly, the
+     * preset enum is a convenience dial, not a contract — devs are
+     * welcome to ship custom strings or tweak the presets to match
+     * their fleet's voice.
+     */
+    readonly mcpInstructions?: McpInstructionsValue;
+    /**
+     * Email magic-link login config. When set, mounts
+     * `POST /ggui/email-login/start`, `GET /ggui/email-login/verify`,
+     * and `GET /ggui/email-login/config` so the `/login` UI can offer
+     * a passwordless email path. Requires `publicBaseUrl` so the magic
+     * link the user clicks resolves back to this server.
+     *
+     *   - `false` / omitted: no email login routes mounted. `/login`
+     *     fetches `/ggui/email-login/config` → 404 → hides the form.
+     *   - `{ sender, fromAddress, ... }`: opt-in. The `sender` is the
+     *     transport (use `ConsoleEmailSender` for dev; SMTP / Resend /
+     *     SES adapters for production). `fromAddress` is stamped on
+     *     every outgoing message.
+     *
+     * Authentication: callbacks mint
+     * `{ kind: 'user', userId: 'email:<lowercased-email>', roles: [] }`
+     * via `auth.registerToken`. The configured `auth` adapter MUST
+     * support `registerToken` — pairing-incompatible adapters
+     * (Cognito/OIDC) can't accept email login.
+     */
+    readonly emailLogin?: {
+        readonly sender: EmailSender;
+        readonly fromAddress: string;
+        readonly store?: MagicLinkStore;
+        readonly subject?: string;
+        readonly bodyText?: string;
+        readonly bodyHtml?: string;
+    };
+    /**
+     * Enable the `@ggui-ai/console` operator landing page. When
+     * enabled, the server:
+     *
+     *   - Mounts `GET /ggui/console/info` — returns
+     *     `{ server, version, description?, pairing: { enabled, pending } }`
+     *     as JSON. Consumed by the landing-page SPA on first load.
+     *   - Mounts `express.static` at the configured `path` (default `/`)
+     *     pointing at the console's built `dist/`.
+     *
+     * Boundary lock:
+     *
+     *   - Same-origin ONLY — not a Portal replacement, not an MCP Apps
+     *     iframe shell.
+     *   - No same-origin cookie, no session viewer, no WebSocket
+     *     wiring yet.
+     *
+     * Options:
+     *
+     *   - `false` / omitted (default): no console mount. The server
+     *     is identical to the pre-console surface.
+     *   - `true`: mount at `/` with the package's built-in `dist/`.
+     *   - `{ path?, distDir? }`: override the URL path (`path`) and/or
+     *     the filesystem dir that Express serves (`distDir`). `distDir`
+     *     is primarily a test-fixture seam — production should leave it
+     *     unset so the package-shipped bundle is served.
+     *
+     * If the resolved `distDir` does not exist on disk when the route is
+     * hit, the server responds with 503 + a clear hint pointing operators
+     * at `pnpm --filter @ggui-ai/console build`. Silent 404 would be
+     * a worse failure mode — operators would think console was
+     * broken rather than unbuilt.
+     */
+    readonly console?: boolean | {
+        /** URL path to mount at. Defaults to `/`. */
+        readonly path?: string;
+        /**
+         * Override the filesystem dir Express serves. Defaults to the
+         * package-shipped `dist/` (`CONSOLE_DIST_DIR`). Primarily a
+         * test-fixture seam.
+         */
+        readonly distDir?: string;
+        /**
+         * Enable the Slice-2 same-origin session-cookie flow
+         * (`POST /ggui/console/session-cookie` + session-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
+         * 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.
+         *
+         * Enabling REQUIRES a configured {@link shortCodeIndex} — the
+         * cookie endpoint resolves shortCode → sessionId by reading
+         * it. Throws at construction if the index is absent.
+         *
+         * The cookie signing secret is the same {@link bootstrapSecret}
+         * used by the MCP Apps bootstrap/session tokens — different
+         * token `kind` claims make cross-kind confusion impossible
+         * (see `console-auth.ts` isolation comment).
+         */
+        readonly sessionCookie?: boolean | {
+            /**
+             * Cookie TTL in seconds. Defaults to 8 hours
+             * (`DEFAULT_DEVTOOL_SESSION_TTL_SEC`).
+             */
+            readonly ttlSec?: number;
+            /**
+             * Add `Secure` to the Set-Cookie attributes. Explicit
+             * because auto-detecting TLS through a reverse proxy
+             * is unreliable — operators passing `true` when their
+             * public URL is HTTPS is the safe contract.
+             */
+            readonly secure?: boolean;
+        };
+        /**
+         * Admin bearer that gates the operator-only console routes
+         * (`/ggui/console/keys*`, `/ggui/console/admin-login`). When
+         * absent, `createGguiServer` mints `ggui_admin_<base64url(9)>`
+         * at boot — surfaced on {@link GguiServer.adminToken} so the
+         * CLI banner can print it. Operator passes `--admin-token <t>`
+         * to pin a stable value across restarts.
+         *
+         * 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,
+         * 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
+         * be reachable to anyone who finds the URL over a tunnel.
+         */
+        readonly adminToken?: string;
+        /**
+         * Onboarding-redirect probe. Called per `GET /` request; if
+         * it returns a non-null path, the server responds 302 to that
+         * path instead of the SPA index. Use this to send first-run
+         * operators (no LLM credentials configured) to the assistant-
+         * connection flow before the chat playground is meaningful.
+         *
+         * The probe is recomputed every request — once the operator
+         * sets a key, the next visit serves the SPA normally. Scoped
+         * to the root path only; deep links bypass the redirect so
+         * `/preview/<id>` / `/blueprints` / etc. continue to work.
+         *
+         * Return `null` to fall through to the SPA. Returning the
+         * same path the request is already on is a no-op (the server
+         * compares before redirecting to avoid loops).
+         */
+        readonly landingRedirect?: () => string | null;
+    };
+    /**
+     * Public welcome page served at the console root (`/`) when the
+     * console is mounted there.
+     *
+     * Resolved from `ggui.json#operator` + `ggui.json#app.name` by the
+     * `ggui serve` CLI; programmatic embedders pass whatever values
+     * fit their context. The page identifies who runs the server
+     * (operator block — hidden entirely when nothing is configured)
+     * and links to the public deep-link surfaces (`/preview/<id>`,
+     * `/s/<shortCode>`) plus an "Operator login →" affordance pointing
+     * at `/admin-login`.
+     *
+     * Posture: this page is the ONLY unauthenticated SPA-mount HTML
+     * surface alongside `/admin-login`. Every other client-side route
+     * (`/admin/*`, `/devtools/*`) requires the admin cookie/bearer.
+     *
+     * Omitted = the legacy SPA index handler runs at `/` (no welcome
+     * page; the SPA handles its own root-route render).
+     *
+     * Ignored when `console.path !== '/'` — operators mounting console
+     * on a non-root prefix already opted out of the welcome page surface.
+     */
+    readonly welcomePage?: {
+        /** Operator-block input. Hidden entirely when omitted/empty. */
+        readonly operator?: OperatorConfig;
+        /**
+         * Display name for the running app (typically `ggui.json#app.name`).
+         * Falls back to the server identity name when omitted.
+         */
+        readonly appName?: string;
+    };
+    /**
+     * 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).
+     *
+     * Pair this with a `push` handler so the agent's `ggui_push` writes
+     * the shortCode into the same index that console later reads.
+     * See `defaultHandlers` for the wiring seam.
+     */
+    readonly shortCodeIndex?: ShortCodeIndex;
+    /**
+     * 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
+     * to the store before emitting `_meta.ggui.bootstrap.codeUrl`.
+     *
+     * Defaults: when omitted the route is NOT mounted; the push
+     * handler falls back to inline base64 `componentCode` on
+     * `_meta.ggui.bootstrap` (legacy delivery channel).
+     *
+     * OSS dev wires `FileSystemCodeStore` (rooted at `~/.ggui/code-cache/`)
+     * via `ggui-cli/buildMcpServerBackend`. Tests wire
+     * `InMemoryCodeStore` from `@ggui-ai/mcp-server-core/in-memory`.
+     * A hosted closed runtime wires a durable adapter (e.g. S3-backed)
+     * from its own closed-source package. The wire format is identical
+     * across deployments — only the storage adapter changes.
+     */
+    readonly codeStore?: CodeStore;
+    /**
+     * Provisional A2UI preview wiring for `ggui_push`. When the config
+     * flag is on, every qualifying component push kicks off the
+     * supplied emitter; frames land on the reserved `_ggui:preview`
+     * channel of the push's session.
+     *
+     * 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).
+     * 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.
+     *
+     * `ggui-cli`'s `buildMcpServerBackend` passes the deterministic
+     * emitter from `@ggui-ai/preview-a2ui/emitters` as the OSS
+     * default; hosted + programmatic hosts inject their own.
+     */
+    readonly provisionalPreview?: {
+        /** Global kill-switch. Default `false` (no preview fan-out). */
+        readonly enabled: boolean;
+        /**
+         * Caller-supplied producer. Absent = no preview even when
+         * `enabled` is true (guardrail: hosts opting in must be
+         * explicit about the producer).
+         */
+        readonly emitter: ProvisionalPreviewEmitter;
+        /** Per-push predicate. See {@link ProvisionalPreviewConfig}. */
+        readonly isEnabledFor?: ProvisionalPreviewConfig['isEnabledFor'];
+        /** Lifecycle observer. Fires sync — must not throw. */
+        readonly onOutcome?: (outcome: ProvisionalPreviewOutcome) => void;
+        /** Clock override for tests. Defaults to `Date.now`. */
+        readonly now?: () => number;
+    };
+    /**
+     * Handshake preflight wiring. When `mcpApps` is enabled, the
+     * server defaults to an `InMemoryKeyValueStore` + no negotiator:
+     * `ggui_handshake` is registered, `ggui_push({handshakeId})` is
+     * consumable, and handshake records persist for 10 minutes before
+     * single-use consumption.
+     *
+     * Explicit overrides:
+     *
+     *   - `{kvStore}` — swap the persistence backend (e.g., SQLite
+     *     when it lands) while keeping the default "no negotiator"
+     *     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`.
+     *   - `false` — explicitly disable: `ggui_handshake` is NOT
+     *     registered and `ggui_push({handshakeId})` falls back to
+     *     the rejection shape.
+     *
+     * Omitted entirely means "use the default in-memory store when
+     * `mcpApps` is on". That matches how `sessionStore` and
+     * `streamBuffer` default — no opt-in required for the OSS
+     * first-run path.
+     *
+     * Requires `mcpApps` to be enabled — handshake is paired with
+     * `ggui_push`, which is only registered under MCP Apps. Throws
+     * at construction when handshake is explicitly enabled without
+     * MCP Apps.
+     */
+    readonly handshake?: false | {
+        /**
+         * Persistence plane. Omit to accept the default
+         * `InMemoryKeyValueStore`.
+         */
+        readonly kvStore?: KeyValueStore;
+        /**
+         * Optional negotiator. Omit = handshake records stamp
+         * `action: 'create'` + no-negotiator-bound reason.
+         */
+        readonly negotiator?: HandshakeNegotiator;
+    };
+    /**
+     * Generation wiring for the `ggui_push` story path. When present,
+     * every component push invokes the bound `UiGenerator` and
+     * appends the result as a real `StackItem` on the session.
+     * Absent = placeholder mode: `ggui_push` on the story path
+     * returns `codeReady: false` without writing componentCode.
+     *
+     * Requires `mcpApps` to be enabled — generation attaches to
+     * `ggui_push`, which is only registered when MCP Apps is on.
+     * Throws at construction otherwise so a misconfigured server
+     * doesn't silently drop the generator binding.
+     *
+     * The `@ggui-ai/ui-gen` package ships the OSS default
+     * implementation (`createUiGenerator({adapter})`); a hosted closed
+     * 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.
+     */
+    readonly generation?: GenerationDeps;
+    /**
+     * Optional multi-generator registry. When present, exposes named
+     * generators (e.g. `ui-gen-default-haiku-4-5`,
+     * `ui-gen-advanced-opus-4-7`) for consumers such as the blueprint
+     * matcher, `ggui_ops_generate_blueprint`, the LLM-driven variant
+     * selector, the console blueprint UI, and the benchmark framework.
+     *
+     * When omitted, `createGguiServer` auto-seeds a registry containing
+     * `generation.uiGenerator` (when `generation` is supplied) so
+     * consumers observe a non-empty registry by default. When supplied,
+     * the caller's registry is used as-is; the caller is responsible
+     * for including their `generation.uiGenerator` if they want it
+     * discoverable.
+     */
+    readonly generators?: GeneratorRegistry;
+    /**
+     * 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,
+     * `createGguiServer` auto-seeds an {@link InMemoryBlueprintStore}.
+     */
+    readonly blueprintStore?: BlueprintStore;
+    /**
+     * Optional variant selector. When present, the handshake handler
+     * calls `selectVariant(candidates)` against the candidate list
+     * returned by `blueprintStore.list((appId, contractHash))`. When
+     * omitted, `createGguiServer` defaults to
+     * {@link createDeterministicBlueprintSelector} — a deterministic
+     * fallback ladder.
+     *
+     * Operators MAY swap in an LLM-driven selector without touching the
+     * handler composition.
+     */
+    readonly blueprintSelector?: BlueprintSelector;
+    /**
+     * Optional multi-axis blueprint search. When present, the
+     * three-step handshake reads through this seam for the
+     * parallel-search half of step 2 (cache vs agent vs synth
+     * routing). When omitted, `createGguiServer` auto-seeds an
+     * `createInMemoryBlueprintSearch` against the resolved
+     * `blueprintStore`. The auto-seeded search wires the optional
+     * `embedding` provider when set, so cached `contractEmbedding`
+     * fields on Blueprint rows surface in the embed axis without
+     * additional caller wiring.
+     *
+     * Operators MAY swap in a vector-DB-backed search (Pinecone,
+     * pgvector, OpenSearch) without touching downstream handlers —
+     * the seam is the contract; the implementation is fungible.
+     */
+    readonly blueprintSearch?: BlueprintSearch;
+    /**
+     * External tool-handler bundles aggregated onto this server's
+     * `/mcp` surface. Every mount's handlers register alongside
+     * ggui's native tools, so one MCP session sees both — `tools/list`
+     * enumerates ggui-native tools plus every mount's tools, and
+     * `tools/call` dispatches uniformly.
+     *
+     * Each mount is a `{ name, handlers }` bundle where `handlers` is
+     * `SharedHandler[]` — the exact shape ggui-native handlers use.
+     * A fixture, hosted adapter, or programmatic host builds handlers
+     * against the same `@ggui-ai/mcp-server-handlers` seams + zod
+     * shapes they'd use for any ggui-native tool, then passes them
+     * here.
+     *
+     * Collision rules: mount tool names MUST NOT collide with a
+     * ggui-native tool name OR with any other mount's tool name.
+     * Composition throws on collision so misconfiguration surfaces
+     * at server-construction time rather than as a surprising
+     * "tools/call dispatched to the wrong handler" at runtime.
+     *
+     * Ignored when {@link handlers} is set — callers who pass a
+     * custom handler list compose the final list themselves.
+     */
+    readonly mcpMounts?: ReadonlyArray<McpServerMount>;
+    /**
+     * Isolated MCP services — each mounted at its own HTTP path with
+     * its own tool namespace. Unlike {@link mcpMounts} (which aggregates
+     * tools onto the shared audience-filtered routes), every entry here
+     * becomes a self-contained MCP server reachable at `app.post(path)`.
+     *
+     * Use a service when the handler set is conceptually a distinct MCP
+     * server (`mcp.ggui.ai/docs`, `mcp.ggui.ai/playground/todos`). Use a
+     * mount when the handlers should appear alongside ggui-native tools
+     * on the shared `/mcp` surface.
+     *
+     * Compose-time invariants are enforced by `validateMcpServices`:
+     * unique non-reserved paths, non-empty handler `outputSchema`, no
+     * `audience` tags on service handlers, no within-service tool-name
+     * collisions. Cross-service tool-name collisions ARE allowed.
+     *
+     * Empty / absent → no service routes mounted, no behavior change.
+     */
+    readonly mcpServices?: ReadonlyArray<McpService>;
+    /**
+     * Per-request resource registrars run against every fresh
+     * `McpServer` instance, after the MCP-Apps outbound install (when
+     * enabled) and before tool registration. The hook is the canonical
+     * extension seam for hosts that mount cross-cutting MCP App UI
+     * bundles (e.g. a `ui://`-scheme resource for system-level cards)
+     * without baking the bundle's wiring into this OSS factory.
+     *
+     * Each registrar receives the per-request `McpServer`; misuse
+     * (duplicate URI, malformed declaration) throws synchronously and
+     * fails the request before tool dispatch, surfacing the
+     * misconfiguration immediately. Idempotent in spirit — the
+     * underlying SDK rejects duplicate registrations.
+     */
+    readonly extraResources?: ReadonlyArray<(server: McpServer) => void>;
+    /**
+     * Per-domain dep seams for the twelve operator-class `ggui_ops_*`
+     * handlers covering the console's apps + orgs + connector-keys +
+     * coupon surfaces. Each domain is independently optional —
+     * `defaultHandlers` registers a domain's tools only when its seam
+     * is bound here. OSS deployments leave these undefined (the smaller
+     * surface); cloud pods bind AppSync-backed adapters.
+     *
+     * Mirrors `creditBalance` + `creditTransactions`'s pattern — the
+     * shared-handler layer is the same code path everywhere, and the
+     * deps interface is the boundary between the open handler and the
+     * deployment-specific implementation.
+     */
+    readonly opsApps?: {
+        readonly apps: AppsSource;
+        readonly userDefaultApp: UserDefaultAppSource;
+    };
+    readonly opsOrgs?: {
+        readonly orgs: OrgsSource;
+        readonly invites: OrgInvitesSource;
+    };
+    readonly opsConnectorKeys?: {
+        readonly connectorKeys: ConnectorKeysSource;
+    };
+    readonly opsCoupon?: {
+        readonly coupons: CouponRedeemSource;
+    };
+}
+export interface GguiServer {
+    /**
+     * The Express app. Mount it under your own parent router if you want
+     * to add middleware, or call {@link listen} for the zero-config path.
+     */
+    readonly app: Express;
+    /**
+     * Bind the app to a port and return the underlying `node:http` server.
+     * Resolves once the listener is accepting connections.
+     */
+    listen(port?: number, host?: string): Promise<NodeHttpServer>;
+    /** Close every outstanding HTTP connection. Idempotent. */
+    close(): Promise<void>;
+    /**
+     * Number of MCP tools registered on this server. Same value the
+     * `GET /ggui/health` endpoint echoes. Useful for hosts (CLIs,
+     * dashboards, tests) that want to surface a real count without
+     * round-tripping over HTTP.
+     */
+    readonly toolCount: number;
+    /**
+     * The OSS live-channel session endpoint, when `sessionChannel` was
+     * enabled. `null` when disabled. Hosts can use this for
+     * introspection (`.sessionCount`, `.subscriberCount`) or for
+     * composition with future mutation handlers that want to fan out
+     * via `sessionChannel.sendToSession(sessionId, data)`.
+     */
+    readonly sessionChannel: SessionChannelServer | null;
+    /**
+     * The pairing service bound to this server, when the `pairing` option
+     * was enabled. `null` when pairing is disabled. In-process hosts
+     * (CLIs, embedded viewers) use this to call `initPairing()` directly
+     * instead of POSTing to `/admin/pair/init`, and to list / revoke
+     * pairings over a programmatic path.
+     */
+    readonly pairingService: PairingService | null;
+    /**
+     * Primitive catalogs resolved at boot from
+     * `ggui.json#primitives.{packages,local}`. Empty array when the
+     * operator passed nothing (programmatic hosts) or when the
+     * declaration resolved to an empty set. Read-only; callers that
+     * need to mutate the catalog should rebuild the server.
+     *
+     * After the CLI `discoverPrimitives()` walk, every declared source
+     * surfaces here in boot-time order (packages first, locals after).
+     * Generator integration (threading the catalog into
+     * `buildSystemPrompt`) consumes this field.
+     */
+    readonly primitiveCatalogs: readonly DiscoveredPrimitiveCatalog[];
+    /**
+     * Theme resolved at boot from `ggui.json#theme`. Always populated
+     * — the server falls back to `@ggui-ai/design`'s shipped
+     * `lightTheme` when the caller omits `opts.theme`, so consumers
+     * never have to null-check.
+     *
+     * Carries the parsed DTCG document + a pre-rendered
+     * `:root { --ggui-*: value; }` CSS block. The server does not yet
+     * inject this CSS into any HTTP response or console bootstrap;
+     * downstream consumers read `server.theme.document` or
+     * `server.theme.cssVariables` as they layer on.
+     */
+    readonly theme: LoadedTheme;
+    /**
+     * Admin bearer that gates the operator-only console routes
+     * (`/ggui/console/keys*` + `/ggui/console/admin-login`). Either the
+     * value the caller supplied via {@link CreateGguiServerOptions.console}
+     * `.adminToken`, or a freshly minted `ggui_admin_*` token when the
+     * caller didn't pass one. `null` when console is disabled (the gate
+     * has no consumer).
+     *
+     * The CLI banner reads this and prints it next to PAIR_CODE so the
+     * operator can paste it into the admin-login page on their first
+     * visit to `/keys`.
+     */
+    readonly adminToken: string | null;
+    /**
+     * The composed generator registry. When the caller passed
+     * `opts.generators`, this is that exact registry. Otherwise, when
+     * `opts.generation` was supplied, this is an auto-seeded registry
+     * containing `generation.uiGenerator` under its declared slug.
+     * `null` when neither was supplied (no generators to expose).
+     *
+     * This field is a seam — consumers read it for blueprint matcher
+     * dispatch, `ggui_ops_generate_blueprint`, the LLM-driven variant
+     * selector, the console blueprint UI, and the benchmark framework.
+     */
+    readonly generators: GeneratorRegistry | null;
+    /**
+     * The composed multi-variant blueprint store. When the caller
+     * passed `opts.blueprintStore`, this is that exact instance.
+     * Otherwise an auto-seeded {@link InMemoryBlueprintStore}.
+     */
+    readonly blueprintStore: BlueprintStore;
+    /**
+     * The composed variant selector. When the caller passed
+     * `opts.blueprintSelector`, this is that exact instance. Otherwise
+     * {@link createDeterministicBlueprintSelector} — a deterministic
+     * fallback ladder. Operators MAY swap in an LLM-driven selector.
+     */
+    readonly blueprintSelector: BlueprintSelector;
+    /**
+     * The composed multi-axis blueprint search. When the caller passed
+     * `opts.blueprintSearch`, this is that exact instance. Otherwise
+     * `createInMemoryBlueprintSearch` against the resolved
+     * `blueprintStore`, wiring the optional `embedding` provider if one
+     * was supplied.
+     *
+     * The three-step handshake reads this for its parallel search +
+     * validate step. Hosts MAY introspect it for cache-warm runbooks
+     * or observability.
+     */
+    readonly blueprintSearch: BlueprintSearch;
+}
+/**
+ * Build a runnable OSS MCP server. Every option has a sensible default
+ * so `createGguiServer()` with no arguments boots a working in-memory
+ * server on demand.
+ */
+export declare function createGguiServer(opts?: CreateGguiServerOptions): GguiServer;
+//# sourceMappingURL=server.d.ts.map