@ggui-ai/mcp-server 0.25.0 → 0.26.0

package/dist/server.js

@@ -39,7 +39,7 @@
  */
 import { CONSOLE_DIST_DIR } from "@ggui-ai/console/server";
 import { RUNTIME_BUNDLE_FILE, RUNTIME_BUNDLE_URL_PATH, RUNTIME_SHIMS_DIR, RUNTIME_SHIMS_URL_PREFIX, } from "@ggui-ai/iframe-runtime/server";
-import { createDeterministicBlueprintSelector, isTokenRegisteringAuthAdapter, mintSessionToken, mintWsToken, verifyWsTokenSignature, verifyToken, } from "@ggui-ai/mcp-server-core";
+import { isTokenRegisteringAuthAdapter, DEFAULT_WS_TOKEN_REFRESH_WINDOW_MULTIPLIER, DEFAULT_WS_TOKEN_TTL_SEC, mintViewRoot, mintWsToken, verifyWsTokenSignature, verifyToken, } from "@ggui-ai/mcp-server-core";
 import { createInMemoryBlueprintSearch, createInMemoryGeneratorRegistry, FixedWindowRateLimiter, InMemoryActiveConsumerRegistry, InMemoryAppMetadataStore, InMemoryAuthAdapter, InMemoryBlueprintIndex, InMemoryBlueprintStore, InMemoryKeyValueStore, InMemoryPairingService, InMemoryPendingEventConsumer, InMemoryQuotaStore, InMemoryGguiSessionStore, InMemoryGguiSessionStreamBuffer, InMemoryVectorStore, MockEmbeddingProvider, NoopAuditSink, NoopRateLimiter, NoopTelemetrySink, } from "@ggui-ai/mcp-server-core/in-memory";
 import { createGguiListGadgetsHandler, createGguiListThemesHandler, } from "@ggui-ai/mcp-server-handlers/app-discovery";
 import { createDescribeBlueprintFormatHandler, createDescribeDataContractFormatHandler, createGetBlueprintBoilerplateHandler, createGetExampleBlueprintsHandler, createListAvailablePrimitivesHandler, createListFeaturedBlueprintsHandler, createRenderBlueprintHandler, createSearchBlueprintsHandler, createValidateBlueprintHandler, } from "@ggui-ai/mcp-server-handlers/blueprints";
@@ -68,10 +68,11 @@ import { BoundedValidatorTraceSink, mountConsoleValidatorRoutes } from "./consol
 // `ggui_ops_get_credit_balance`'s pattern).
 import { createCreateAppHandler, createDeleteAppHandler, createListAppsHandler, createSetAppThemeHandler, createSetDefaultAppHandler, createUpdateAppHandler, } from "@ggui-ai/mcp-server-handlers/ops-apps";
 import { fontFaceRules, validateOverlayCoverage } from "@ggui-ai/design/themes";
-import { createGguiConsumeHandler, createGguiDeclareToolCatalogHandler, createGguiEmitHandler, createGguiGetRenderSourceHandler, createGguiGetSessionHandler, createGguiHandshakeHandler, createGguiListSessionsHandler, createGguiRefreshWsTokenHandler, createGguiRenderHandler, createGguiRuntimePullHandler, createGguiRuntimeTelemetryHandler, createGguiSubmitActionHandler, createGguiSyncContextHandler, createGguiUpdateHandler, createGguiAmendHandler, InMemoryToolIdentityCatalogStore, createInMemoryProvisionalPreviewRegistry, } from "@ggui-ai/mcp-server-handlers/renders";
+import { createGguiConsumeHandler, createGguiDeclareToolCatalogHandler, createGguiEmitHandler, createGguiGetRenderSourceHandler, createGguiGetSessionHandler, createGguiHandshakeHandler, createGguiListSessionsHandler, createGguiRefreshWsTokenHandler, createGguiRenderHandler, createGguiReportRenderFailureHandler, createGguiRuntimePullHandler, createGguiRuntimeTelemetryHandler, createGguiSubmitActionHandler, createGguiSyncContextHandler, createGguiUpdateHandler, createGguiAmendHandler, InMemoryToolIdentityCatalogStore, createInMemoryProvisionalPreviewRegistry, } from "@ggui-ai/mcp-server-handlers/renders";
 import { DEFAULT_ADMIN_BLUEPRINTS_PATH, mountAdminBlueprintsTransport, } from "./admin-blueprints-transport.js";
 import { mountAdminOAuthProvidersTransport } from "./admin-oauth-providers-transport.js";
 import { DEFAULT_BUILDER_APP_ID, defaultAppIdFromIdentity } from "./auth.js";
+import { assertViewProofDeclarations, createViewProofGate, unverifiableViewProofTools, } from "./view-proof-gate.js";
 import { mountMcpEndpoints } from "./mcp-endpoint-routes.js";
 import { mountApiRendersRoutes } from "./api-renders-routes.js";
 import { mountApiRendersStreamRoute } from "./api-renders-stream-route.js";
@@ -96,7 +97,7 @@ import { computeRuntimeBundleHash, insertRuntimeBundleHash, } from "./runtime-bu
 import { createCsrfMiddleware, mountCsrfTokenRoute } from "./csrf-middleware.js";
 import { mountEmailLoginRoutes } from "./email-login.js";
 import { resolveMcpInstructions } from "./instructions-presets.js";
-import { buildLlmCaller, createLlmBackedHandshakeNegotiator } from "./llm-backed-negotiator.js";
+import { createLlmBackedHandshakeNegotiator } from "./llm-backed-negotiator.js";
 import { createConsoleLogger } from "./logger.js";
 import { buildControlService, CONTROL_PATH } from "./control-service.js";
 import { createBrowserCorsMiddleware, createPreflightFallback } from "./browser-cors.js";
@@ -230,6 +231,9 @@ export function buildOpsBlueprintHandlers(input) {
     }));
     handlers.push(createGguiOpsDeleteBlueprintHandler({
         blueprintStore: bundle.blueprintStore,
+        // ggui#1541 — the registry generate and register mirror into, so a
+        // delete takes the blueprint out of the handshake's reuse too.
+        ...(bundle.cacheRegistry ? { cacheRegistry: bundle.cacheRegistry } : {}),
         authorizeAppAccess: bundle.authorizeAppAccess,
     }));
     return handlers;
@@ -362,6 +366,15 @@ export function defaultHandlers(deps) {
         handlers.push(createGguiRuntimeTelemetryHandler({
             ...(deps.logger ? { logger: deps.logger } : {}),
         }));
+        // `ggui_runtime_report_render_failure` (ggui#1609) — a card whose render
+        // failed says so, for the session its view proof binds. Unlike
+        // telemetry it is recorded, so its session is proven, never claimed;
+        // this server names each proven report (`render_failed`) and stores
+        // nothing — a deployment that keeps a per-session mark supplies
+        // `recordRenderFailure` when it composes its own handler set.
+        handlers.push(createGguiReportRenderFailureHandler({
+            renderStore: deps.render.renderStore,
+        }));
         // `ggui_runtime_refresh_ws_token` — the authorized re-mint of a
         // view's live credential (ggui#1496 part B). Registered only when the
         // deployment can both verify an envelope and mint a credential;
@@ -450,7 +463,13 @@ export function defaultHandlers(deps) {
             // Bootstrap-emission deps mirror render so MCP Apps hosts that
             // forward `ui/notifications/tool-result` via postMessage can
             // re-apply patched props on the live mount without a WS round-trip.
-            ...(deps.update.mintBootstrap ? { mintWsToken: deps.update.mintBootstrap } : {}),
+            // The result door issues a view key when a key-issuing minter is
+            // wired (ggui#1415); otherwise it mints the live credential alone.
+            ...(deps.update.mintViewRoot
+                ? { mintWsToken: deps.update.mintViewRoot }
+                : deps.update.mintBootstrap
+                    ? { mintWsToken: deps.update.mintBootstrap }
+                    : {}),
             ...(deps.update.runtimeUrl !== undefined ? { runtimeUrl: deps.update.runtimeUrl } : {}),
             ...(deps.update.sessionApiBaseUrl !== undefined
                 ? { sessionApiBaseUrl: deps.update.sessionApiBaseUrl }
@@ -634,7 +653,13 @@ export function defaultHandlers(deps) {
             ...(deps.render.streamWebSocketLocalTools !== undefined
                 ? { streamWebSocketLocalTools: deps.render.streamWebSocketLocalTools }
                 : {}),
-            ...(deps.render.mintBootstrap ? { mintWsToken: deps.render.mintBootstrap } : {}),
+            // The result door issues a view key when a key-issuing minter is
+            // wired (ggui#1415); otherwise it mints the live credential alone.
+            ...(deps.render.mintViewRoot
+                ? { mintWsToken: deps.render.mintViewRoot }
+                : deps.render.mintBootstrap
+                    ? { mintWsToken: deps.render.mintBootstrap }
+                    : {}),
             ...(deps.render.runtimeUrl !== undefined ? { runtimeUrl: deps.render.runtimeUrl } : {}),
             ...(deps.render.sessionApiBaseUrl !== undefined
                 ? { sessionApiBaseUrl: deps.render.sessionApiBaseUrl }
@@ -750,6 +775,35 @@ export function buildOpsBundleHandlers(deps) {
     }
     return handlers;
 }
+/**
+ * How long {@link GguiServer.close} lets active connections finish before
+ * it ends them (ggui#1631), in milliseconds.
+ */
+export const DEFAULT_CLOSE_GRACE_MS = 5000;
+/**
+ * The ws-token TTL and refresh window a server mints with (ggui#1496 part
+ * B). Both are positive whole seconds, and the window is at least the TTL:
+ * then every token this server mints, root and renewal alike, is past its
+ * `exp` by `rootIat + window`, so every gate refuses it in the same second.
+ * (A token minted while the window was longer, or by a server sharing the
+ * secret with a longer window, can outlive that second on the other gates;
+ * only `/state` refuses it.)
+ */
+function resolveWsTokenLifetimes(opts) {
+    const wholePositive = (v) => Number.isInteger(v) && v > 0;
+    const ttlSec = opts.wsTokenTtlSec ?? DEFAULT_WS_TOKEN_TTL_SEC;
+    if (!wholePositive(ttlSec)) {
+        throw new Error(`createGguiServer: wsTokenTtlSec must be a positive whole number of seconds (got ${String(ttlSec)}).`);
+    }
+    const windowSec = opts.wsTokenRefreshWindowSec ?? DEFAULT_WS_TOKEN_REFRESH_WINDOW_MULTIPLIER * ttlSec;
+    if (!wholePositive(windowSec)) {
+        throw new Error(`createGguiServer: wsTokenRefreshWindowSec must be a positive whole number of seconds (got ${String(windowSec)}).`);
+    }
+    if (windowSec < ttlSec) {
+        throw new Error(`createGguiServer: wsTokenRefreshWindowSec (${windowSec}) must be at least wsTokenTtlSec (${ttlSec}); a shorter window would let a root token outlive its own renewal chain.`);
+    }
+    return { ttlSec, windowSec };
+}
 /**
  * Build a runnable OSS MCP server. Every option has a sensible default
  * so `createGguiServer()` with no arguments boots a working in-memory
@@ -759,6 +813,11 @@ export function createGguiServer(opts = {}) {
     if ((opts.perAppRouting?.perAppOnlySources?.length ?? 0) > 0 && !opts.perAppRouting?.authorize) {
         throw new Error("createGguiServer: perAppRouting.perAppOnlySources lists credential sources that are valid only at their app's endpoint, but perAppRouting.authorize is not wired");
     }
+    const { ttlSec: wsTokenTtlSec, windowSec: wsTokenRefreshWindowSec } = resolveWsTokenLifetimes(opts);
+    const keyedSince = opts.viewProof?.keyedSince;
+    if (keyedSince !== undefined && (!Number.isFinite(keyedSince) || keyedSince < 0)) {
+        throw new Error(`createGguiServer: viewProof.keyedSince must be a finite, non-negative epoch in milliseconds (got ${String(keyedSince)}).`);
+    }
     const info = { ...DEFAULT_INFO, ...opts.info };
     const logger = opts.logger ?? createConsoleLogger({ server: info.name });
     const bodyLimit = opts.bodyLimit ?? "4mb";
@@ -973,12 +1032,23 @@ export function createGguiServer(opts = {}) {
     // (which always call this on the live-mode path) get clean strings
     // without per-callsite narrowing.
     let mintBootstrap;
+    // The key-issuing doors' minters (ggui#1415): a root ws token stamped
+    // with the secret's key id and the door, and the view key rooted in it.
+    // Only the render/update results (`result`) and the data-plane read door
+    // (`read`), on a read that issues the key, use them; every bearer door,
+    // and every read that issues no key, mints through `mintBootstrap`.
+    let mintResultViewRoot;
+    let mintReadViewRoot;
+    // `/state`'s one minter (ggui#1496 part B, slice 2): a possession renewal
+    // that carries its chain's root forward. Every other door mints a root
+    // through `mintBootstrap`.
+    let mintChainedBootstrap;
     let channelBootstrap;
     // The authorized refresh's envelope check (ggui#1496 part B): signature,
     // shape and kind at ANY age, over the same secret the minter signs with.
     let wsTokenVerify;
-    // Shared HMAC secret for server-minted creds (bootstrap tokens,
-    // session tokens, console cookies). Distinct `kind` claims
+    // Shared HMAC secret for server-minted creds (ws bootstrap tokens,
+    // console cookies). Distinct `kind` claims
     // prevent cross-kind confusion; sharing the secret keeps the
     // config surface small and means operators rotate ONE value.
     // Resolved here so both the MCP Apps block and the console
@@ -999,7 +1069,7 @@ export function createGguiServer(opts = {}) {
         // from `@ggui-ai/mcp-server-core` for callers that need explicit
         // single-use semantics (one-time-link share, etc.).
         const syncMinter = (sessionId, appId) => {
-            const { token, claims } = mintWsToken({ sessionId, appId }, secret);
+            const { token, claims } = mintWsToken({ sessionId, appId, ttlSec: wsTokenTtlSec }, secret);
             return {
                 wsUrl,
                 token,
@@ -1007,6 +1077,36 @@ export function createGguiServer(opts = {}) {
             };
         };
         mintBootstrap = syncMinter;
+        const viewRootMinter = (src) => (sessionId, appId) => {
+            const minted = mintViewRoot({ sessionId, appId, ttlSec: wsTokenTtlSec, src }, secret);
+            if (minted.viewKeyNotIssued !== undefined) {
+                logger.info("view_key_not_issued", { sessionId, src, reason: minted.viewKeyNotIssued });
+            }
+            return {
+                wsUrl,
+                token: minted.token,
+                expiresAt: new Date(minted.claims.exp * 1000).toISOString(),
+                viewKey: minted.viewKey,
+            };
+        };
+        mintResultViewRoot = viewRootMinter("result");
+        mintReadViewRoot = viewRootMinter("read");
+        // The renewal's `exp` is capped at `rootIat + window` by the mint
+        // itself (`notAfter`), from the same clock read that stamps its `iat`.
+        // No second left means nothing to renew (`undefined`, answered as the
+        // ordinary expiry). That happens when the bound's second arrives between
+        // the route's expiry check and this mint (the route awaits the store in
+        // between), or for a token minted while the window was longer.
+        mintChainedBootstrap = (sessionId, appId, rootIat) => {
+            const { token, claims } = mintWsToken({ sessionId, appId, ttlSec: wsTokenTtlSec, rootIat, notAfter: rootIat + wsTokenRefreshWindowSec }, secret);
+            if (claims.exp <= claims.iat)
+                return undefined;
+            return {
+                wsUrl,
+                token,
+                expiresAt: new Date(claims.exp * 1000).toISOString(),
+            };
+        };
         channelBootstrap = {
             verify: (token) => {
                 const result = verifyToken(token, secret, "ws");
@@ -1025,15 +1125,16 @@ export function createGguiServer(opts = {}) {
                 }
                 return { ok: false, reason: "invalid" };
             },
-            issueSessionToken: (sessionId, appId) => {
-                const { token } = mintSessionToken({ sessionId, appId }, secret);
-                return token;
-            },
         };
         wsTokenVerify = (envelope) => {
             const result = verifyWsTokenSignature(envelope, secret);
             return result.ok
-                ? { ok: true, sessionId: result.claims.sessionId, appId: result.claims.appId, iat: result.claims.iat }
+                ? {
+                    ok: true,
+                    sessionId: result.claims.sessionId,
+                    appId: result.claims.appId,
+                    rootIat: result.claims.rootIat ?? result.claims.iat,
+                }
                 : { ok: false };
         };
     }
@@ -1140,7 +1241,6 @@ export function createGguiServer(opts = {}) {
         new InMemoryBlueprintStore({
             embeddingProvider: opts.embedding,
         });
-    const blueprintSelector = opts.blueprintSelector ?? createDeterministicBlueprintSelector();
     // Auto-seed the multi-axis search against the resolved store.
     // Type-narrowed at the call site: when the caller passed
     // their own store we can't assume it implements `listAllForApp`,
@@ -1423,6 +1523,7 @@ export function createGguiServer(opts = {}) {
                             ? { postFailureHook: opts.renderPostFailureHook }
                             : {}),
                         ...(mintBootstrap ? { mintBootstrap } : {}),
+                        ...(mintResultViewRoot ? { mintViewRoot: mintResultViewRoot } : {}),
                         // The authorized refresh's envelope check (ggui#1496 part B),
                         // over the same secret as `mintBootstrap`. Absent when MCP
                         // Apps isn't enabled; the tool isn't registered then.
@@ -1499,25 +1600,7 @@ export function createGguiServer(opts = {}) {
                         // every story-path render + emits `cache.hit /
                         // similarity / cachedBlueprintId / llmCallsAvoided` on
                         // structuredContent.
-                        ...(generationWithCache
-                            ? {
-                                generation: {
-                                    ...generationWithCache,
-                                    // Thread an LLMCaller resolver into
-                                    // render so the registry-based three-tier matcher
-                                    // can fire its rerank step. Per-call resolution
-                                    // because BYOK creds depend on ctx.
-                                    resolveLlmCaller: async (ctx) => {
-                                        if (!generationWithCache.resolveLlm)
-                                            return null;
-                                        const creds = await generationWithCache.resolveLlm(ctx);
-                                        if (!creds)
-                                            return null;
-                                        return buildLlmCaller(creds.selection, creds.providerKey);
-                                    },
-                                },
-                            }
-                            : {}),
+                        ...(generationWithCache ? { generation: generationWithCache } : {}),
                         // Live-subscriber notifier. Late-binds to the
                         // GguiSessionChannelServer created further down (`channel`
                         // / `channelForHealth`) — the channel doesn't exist yet
@@ -1651,6 +1734,7 @@ export function createGguiServer(opts = {}) {
                         // resolvers keeps the two transports byte-identical at the
                         // bootstrap-projection boundary.
                         ...(mintBootstrap ? { mintBootstrap } : {}),
+                        ...(mintResultViewRoot ? { mintViewRoot: mintResultViewRoot } : {}),
                         // Function form: matches render so ggui_update emits the
                         // same absolute URL when the server sits behind a tunnel
                         // / reverse proxy.
@@ -1762,6 +1846,30 @@ export function createGguiServer(opts = {}) {
     // construction instead of at first `tools/call`. The actual route
     // mounting happens below alongside the canonical routes.
     const mcpServices = validateMcpServices(opts.mcpServices);
+    // ggui#1415 — the view-origin proof's measuring gate, over every handler
+    // this server serves (the data and control planes, mounts, and isolated
+    // services). Every declared proof must be one a view can sign (refused at
+    // boot otherwise). The gate runs where views are keyed (MCP Apps on);
+    // without it, a declared call's line says `viewProofUnverifiable`, named
+    // once here.
+    const servedHandlers = [...handlers, ...mcpServices.flatMap((service) => service.handlers)];
+    assertViewProofDeclarations(servedHandlers);
+    const viewProofGate = mcpAppsEnabled && sharedTokenSecret !== undefined
+        ? createViewProofGate({
+            secret: sharedTokenSecret,
+            sessionStore: renderStore,
+            ...(keyedSince !== undefined ? { keyedSince } : {}),
+        })
+        : undefined;
+    if (viewProofGate === undefined) {
+        const unverifiable = unverifiableViewProofTools(servedHandlers);
+        if (unverifiable.length > 0) {
+            logger.warn("view_proof_unverifiable", {
+                tools: unverifiable,
+                hint: "These tools declare a view proof. MCP Apps is off, so this server keys no view and does not verify proofs.",
+            });
+        }
+    }
     // The control plane — every `protocol`- and `ops`-tagged handler,
     // projected onto one anonymous-capable route with per-tool auth and
     // confirmation gates. Built from the SAME composed `handlers` array
@@ -1860,10 +1968,12 @@ export function createGguiServer(opts = {}) {
     // pass a stable `csrfSecret` so tokens survive a restart.
     app.use(createSecurityHeadersMiddleware());
     // Resolved once at boot — every per-request `buildMcpServer` call
-    // receives the same string, so `tools/list` + `initialize` stay
-    // consistent across the lifetime of the process. Operators tune
-    // via `mcpInstructions: 'default' | 'aggressive' | 'minimal' | 'off'`
-    // or a custom string. See `instructions-presets.ts` for full copy.
+    // receives the same string, so every `initialize` result carries the
+    // same instructions for the life of the process. Operators opt in via
+    // `mcpInstructions: 'default' | 'aggressive' | 'always' | 'minimal'` or
+    // a custom string; unset or `'off'` sends none (ggui#1579). The boot
+    // line says what is SENT, so it can never again name text no host got.
+    // See `instructions-presets.ts` for the copy.
     const resolvedInstructions = resolveMcpInstructions(opts.mcpInstructions);
     if (resolvedInstructions) {
         logger.info("mcp_instructions_set", {
@@ -1874,15 +1984,19 @@ export function createGguiServer(opts = {}) {
                     opts.mcpInstructions === "minimal" ||
                     opts.mcpInstructions === "off")
                 ? opts.mcpInstructions
-                : opts.mcpInstructions === undefined
-                    ? "default (no-preset fallback)"
-                    : "custom",
+                : "custom",
             length: resolvedInstructions.length,
+            sentInInitialize: true,
         });
     }
     else {
         logger.info("mcp_instructions_off", {
-            reason: opts.mcpInstructions === "off" ? "preset=off" : "empty custom string",
+            reason: opts.mcpInstructions === undefined
+                ? "unset (the default is off)"
+                : opts.mcpInstructions === "off"
+                    ? "preset=off"
+                    : "empty custom string",
+            sentInInitialize: false,
         });
     }
     const csrfSecret = opts.csrfSecret && opts.csrfSecret.length >= 32
@@ -2026,6 +2140,7 @@ export function createGguiServer(opts = {}) {
     // endpoint family spreads a fresh copy per request.
     const buildMcpOptions = {
         mcpAppsOutbound: mcpAppsEnabled,
+        ...(viewProofGate !== undefined ? { viewProofGate } : {}),
         // Caller-provided `shellHtml` overrides the default (and the
         // inline-runtime shell); `installMcpAppsOutbound` falls back to
         // its baked `GGUI_RENDER_SHELL_HTML` constant when both are
@@ -2198,6 +2313,10 @@ export function createGguiServer(opts = {}) {
                     // Mirrors the per-tool `mintBootstrap` plumbed into
                     // the handler factory above.
                     ...(mintBootstrap ? { mintWsToken: mintBootstrap } : {}),
+                    // The data-plane read door issues a view key (ggui#1415); every
+                    // other mount, and an anonymous caller, mints through
+                    // `mintBootstrap` alone.
+                    ...(mintReadViewRoot ? { mintViewRoot: mintReadViewRoot } : {}),
                 },
             }
             : {}),
@@ -2267,9 +2386,10 @@ export function createGguiServer(opts = {}) {
     // R6 /state snapshot + R7 /events cursor-replay reads — see
     // `./api-renders-routes.ts` for the wsToken auth posture, binding +
     // app-scope gates, and response taxonomy. Mounted only when MCP Apps is on,
-    // a render store is resolved, and a token secret exists (the same
-    // preconditions the credential minter needs).
-    if (mcpAppsEnabled && renderStore && sharedTokenSecret !== undefined) {
+    // a render store is resolved, and a token secret exists. MCP Apps being on
+    // is also what assigns the two minters, so the last conjunct only narrows
+    // the type: it never keeps a deployment from mounting.
+    if (mcpAppsEnabled && renderStore && sharedTokenSecret !== undefined && mintChainedBootstrap) {
         mountApiRendersRoutes({
             app,
             renderStore,
@@ -2287,7 +2407,7 @@ export function createGguiServer(opts = {}) {
             // composes (ggui#522) — session-API URLs keep the public origin.
             ...(opts.codeBaseUrl !== undefined ? { codeBaseUrl: opts.codeBaseUrl } : {}),
             ...(mintCodeModuleUrl !== undefined ? { mintCodeModuleUrl } : {}),
-            ...(mintBootstrap ? { mintBootstrap } : {}),
+            mintChainedBootstrap,
             resolveRuntimeUrl: resolveRuntimeUrlForResultMeta,
             logger,
         });
@@ -3138,7 +3258,6 @@ export function createGguiServer(opts = {}) {
         adminToken: resolvedAdminToken,
         generators: generators ?? null,
         blueprintStore,
-        blueprintSelector,
         blueprintSearch,
         async listen(port = 0, host = opts.host ?? "127.0.0.1") {
             // The Origin/Host validation policy (ggui#438a) was built above
@@ -3222,14 +3341,28 @@ export function createGguiServer(opts = {}) {
                 }
             });
         },
-        async close() {
+        async close(options = {}) {
             if (channel)
                 await channel.close();
             const server = httpServer;
             if (!server)
                 return;
+            const graceMs = options.graceMs ?? DEFAULT_CLOSE_GRACE_MS;
             await new Promise((resolve, reject) => {
-                server.close((err) => (err ? reject(err) : resolve()));
+                // ggui#1631: after the grace, end what is still open. The timer is
+                // unref'd so it never keeps the process alive on its own.
+                const deadline = Number.isFinite(graceMs)
+                    ? setTimeout(() => server.closeAllConnections(), Math.max(0, graceMs))
+                    : undefined;
+                deadline?.unref();
+                server.close((err) => {
+                    if (deadline !== undefined)
+                        clearTimeout(deadline);
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
             });
             httpServer = null;
         },

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-import type { GguiSessionStore, ThreadStore, VectorStore } from '@ggui-ai/mcp-server-core';
+import type { GguiSessionStore, GguiSessionStreamBuffer, ThreadStore, VectorStore } from '@ggui-ai/mcp-server-core';
 import type { StorageConfig } from '@ggui-ai/project-config';
 export interface ResolveStorageFromConfigOptions {
     /**
@@ -49,6 +49,14 @@ export interface ResolvedStorageStores {
      * `/ggui/health` advertisement matches the active store.
      */
     readonly threadDurability?: 'durable' | 'ephemeral';
+    /**
+     * The live channel's stream buffer, present iff `renders` declares
+     * sqlite: a `SqliteGguiSessionStreamBuffer` on the same database file,
+     * so a session that survives a restart also keeps its stream `seq`, its
+     * epoch and its retained envelopes (ggui#1534). Absent otherwise, and
+     * `createGguiServer` keeps its in-memory buffer.
+     */
+    readonly streamBuffer?: GguiSessionStreamBuffer;
 }
 /**
  * Instantiate the concrete storage adapters declared in a parsed

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAqDA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,+BAA+B;IAC9C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC;oEACgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC;oEACgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;;;;;;;;;;;;;yCAiBqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,IAAI,GAAE,+BAAoC,GACzC,OAAO,CAAC,qBAAqB,CAAC,CAgDhC"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAqDA,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,+BAA+B;IAC9C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC;oEACgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC;oEACgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;;;;;;;;;;;;;yCAiBqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IACpD;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,IAAI,GAAE,+BAAoC,GACzC,OAAO,CAAC,qBAAqB,CAAC,CAkDhC"}

package/dist/storage.js

@@ -41,9 +41,9 @@
  * who want storage from config write:
  *
  * ```ts
- * const { renderStore, vectors } =
+ * const { renderStore, vectors, streamBuffer } =
  *   await resolveStorageFromConfig(manifest.storage, { baseDir: projectRoot });
- * const server = createGguiServer({ renderStore, vectors });
+ * const server = createGguiServer({ renderStore, vectors, streamBuffer });
  * ```
  *
  * Explicit instances passed to `createGguiServer` still win — this
@@ -113,11 +113,12 @@ export async function resolveStorageFromConfig(config, opts = {}) {
     // Single dynamic import serves every sqlite adapter — better-sqlite3's
     // N-API binding loads once even if the import lands twice; the
     // subpath barrel is cached by Node's module loader.
-    const { SqliteGguiSessionStore, SqliteVectorStore, SqliteThreadStore } = await import('@ggui-ai/mcp-server-core/sqlite');
+    const { SqliteGguiSessionStore, SqliteGguiSessionStreamBuffer, SqliteVectorStore, SqliteThreadStore } = await import('@ggui-ai/mcp-server-core/sqlite');
     if (config.renders && config.renders.driver === 'sqlite') {
         const filename = resolveStoragePath(config.renders.path, opts.baseDir);
         ensureParentDir(filename);
         result.renderStore = new SqliteGguiSessionStore({ filename });
+        result.streamBuffer = new SqliteGguiSessionStreamBuffer({ filename });
     }
     if (config.vectors && config.vectors.driver === 'sqlite') {
         const filename = resolveStoragePath(config.vectors.path, opts.baseDir);

package/dist/view-proof-gate.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The view-origin proof's measuring gate (ggui#1415, release N): for a tool
+ * that declares a view proof, verify the call's proof before the handler
+ * runs, put the verdict on the handler context, and name it on the
+ * `tool_invoked` line. It never refuses a call and never fails one: at this
+ * release the proof is measured, not enforced.
+ *
+ * Built once per server (`createViewProofGate`, holding the secret the ws
+ * envelopes are signed with) and run per call (`runViewProofGate`) from
+ * `buildMcpServer`'s per-tool callback.
+ */
+import { ViewProofRepeatCache, type GguiSessionStore, type ViewProofVerdict, type VerifyViewProofInput } from '@ggui-ai/mcp-server-core';
+import { type HandlerContext, type SharedHandler } from '@ggui-ai/mcp-server-handlers';
+import { type ViewRootSrc } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { ZodRawShape } from 'zod';
+/**
+ * Which era a call's session belongs to, for a `required` call whose proof
+ * is not valid; the first match wins. `row_absent`: no store, no row, or
+ * the read failed. `foreign`: another app owns the row. `unkeyed`: the
+ * session's ids are too long for a view key. `legacy`: created before
+ * `keyedSince`, or `keyedSince` is unset. `current`: everything else.
+ */
+export type ViewProofEra = 'current' | 'legacy' | 'unkeyed' | 'foreign' | 'row_absent';
+/** How old the proof's root is on the server's clock (`now − rootIat`). */
+export type ViewProofRootAge = 'lt_3m' | 'lt_1h' | 'lt_1d' | 'lt_7d' | 'lt_30d' | 'ge_30d';
+/**
+ * The view clock against the server's (`vtime − now`), bucketed at 30 s,
+ * 5 min and 1 h on each side. Relay latency makes it negative (`behind`),
+ * so `ahead` can only be the view's clock running ahead.
+ */
+export type ViewProofSkew = 'behind_ge_1h' | 'behind_lt_1h' | 'behind_lt_5m' | 'within_30s' | 'ahead_lt_5m' | 'ahead_lt_1h' | 'ahead_ge_1h';
+/**
+ * The proof's fields on a `tool_invoked` line: ids, flags and buckets only.
+ * Never the proof, its root, its nonce, its tags, the view key or any
+ * argument.
+ */
+export interface ViewProofLineFields {
+    readonly viewProof?: ViewProofVerdict['verdict'];
+    readonly viewProofReason?: string;
+    readonly viewProofErrorClass?: string;
+    /** Valid only: the session the proof's root names (it equals the call's). */
+    readonly viewProofSessionId?: string;
+    /** Not valid: the call's session as the caller claims it, capped. */
+    readonly claimedSessionId?: string;
+    readonly claimedSessionIdTruncated?: true;
+    readonly viewProofRootAge?: ViewProofRootAge;
+    readonly viewProofRootSrc?: ViewRootSrc;
+    readonly viewProofSkew?: ViewProofSkew;
+    /** Dispatch only: the gesture's user-activation flag, self-asserted by any key holder. */
+    readonly viewProofActivation?: boolean;
+    /** This replica saw the same `(session, nonce)` within the repeat window. */
+    readonly viewProofRepeat?: true;
+    readonly viewProofEra?: ViewProofEra;
+    /** The tool declares a proof and the server has no verifier. */
+    readonly viewProofUnverifiable?: true;
+}
+/** A server's gate: its verifier, and what it reads to classify an era. */
+export interface ViewProofGate {
+    verify(input: VerifyViewProofInput): ViewProofVerdict;
+    /** Whether a session's ids fit a view key's root. */
+    keyable(sessionId: string, appId: string): boolean;
+    readonly sessionStore: GguiSessionStore | undefined;
+    /** Epoch ms from which every replica of this deployment issues view keys. */
+    readonly keyedSince: number | undefined;
+    readonly repeatCache: ViewProofRepeatCache;
+    now(): number;
+}
+export interface CreateViewProofGateOptions {
+    /** The secret the server's ws envelopes are signed with. */
+    readonly secret: string;
+    readonly sessionStore: GguiSessionStore | undefined;
+    readonly keyedSince?: number;
+    readonly now?: () => number;
+}
+/** Build a server's gate once; the secret stays in its closures. */
+export declare function createViewProofGate(opts: CreateViewProofGateOptions): ViewProofGate;
+/**
+ * Refuse, at boot, a handler that declares a view proof on a tool the
+ * proof's bound-argument table does not name: no view can sign a call to
+ * it, so every call would read `missing` for a reason no one could find.
+ */
+export declare function assertViewProofDeclarations(handlers: ReadonlyArray<Pick<SharedHandler<ZodRawShape, ZodRawShape>, 'name' | 'viewProof'>>): void;
+/** The tools whose declared proof a server without a verifier cannot check. */
+export declare function unverifiableViewProofTools(handlers: ReadonlyArray<Pick<SharedHandler<ZodRawShape, ZodRawShape>, 'name' | 'viewProof'>>): string[];
+/** What the gate hands back: the context the handler runs with, and the line fields. */
+export interface ViewProofGateResult {
+    readonly ctx: HandlerContext;
+    readonly fields: ViewProofLineFields;
+}
+/**
+ * Run the gate for one call. `gate` is undefined on a server with no
+ * verifier. Total: it never throws, and never changes what the handler
+ * answers; a declaration it cannot read leaves the call as it came.
+ */
+export declare function runViewProofGate(gate: ViewProofGate | undefined, handler: Pick<SharedHandler<ZodRawShape, ZodRawShape>, 'name' | 'viewProof'>, input: Record<string, unknown>, ctx: HandlerContext): Promise<ViewProofGateResult>;
+//# sourceMappingURL=view-proof-gate.d.ts.map

package/dist/view-proof-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-proof-gate.d.ts","sourceRoot":"","sources":["../src/view-proof-gate.ts"],"names":[],"mappings":"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"}