@ggui-ai/mcp-server 0.1.0-rc.3 → 0.2.0-alpha.3

package/dist/console-timeline.js

@@ -1,13 +1,13 @@
 import { applyDevtoolSecurityHeaders } from './console-headers.js';
 /**
- * Drain {@link SessionStore.observe} into an array. The observe iterator
+ * Drain {@link RenderStore.observe} into an array. The observe iterator
  * with `{ tail: false }` resolves cleanly after replaying every stored
  * event, so this is a plain `for await`. Bound by the store's per-
- * session retention (in-memory: full history; hosted: store-defined).
+ * render retention (in-memory: full history; hosted: store-defined).
  */
-async function drainSessionEvents(sessionStore, sessionId) {
+async function drainRenderEvents(renderStore, renderId) {
     const out = [];
-    for await (const event of sessionStore.observe(sessionId, {
+    for await (const event of renderStore.observe(renderId, {
         fromSeq: 1,
         tail: false,
     })) {
@@ -21,9 +21,9 @@ async function drainSessionEvents(sessionStore, sessionId) {
  * function does not re-implement auth (matches the
  * `mountConsoleLlmTraceRoutes` shape in console-llm-trace.ts).
  */
-export function mountConsoleTimelineRoutes(app, sessionStore, streamBuffer) {
-    // GET /ggui/console/timeline/sessions?limit=<n>
-    app.get('/ggui/console/timeline/sessions', async (req, res) => {
+export function mountConsoleTimelineRoutes(app, renderStore, streamBuffer) {
+    // GET /ggui/console/timeline/renders?limit=<n>
+    app.get('/ggui/console/timeline/renders', async (req, res) => {
         applyDevtoolSecurityHeaders(res);
         const limitRaw = req.query['limit'];
         let limit = 50;
@@ -34,86 +34,85 @@ export function mountConsoleTimelineRoutes(app, sessionStore, streamBuffer) {
             }
         }
         // Zero-config shape: no store wired (pure-MCP boot) → empty list.
-        if (!sessionStore) {
-            const body = { sessions: [], total: 0 };
+        if (!renderStore) {
+            const body = { renders: [], total: 0 };
             res.json(body);
             return;
         }
         try {
             // No status filter — operators want to debug completed +
-            // expired sessions, not just live ones. Limit is post-filter
+            // expired renders, not just live ones. Limit is post-filter
             // so the response stays bounded.
-            const sessions = await sessionStore.list({});
+            const stored = await renderStore.list({});
             const summaries = [];
             const now = Date.now();
-            for (const session of sessions) {
+            for (const row of stored) {
                 let streamSeq = 0;
                 if (streamBuffer) {
                     try {
-                        streamSeq = await streamBuffer.currentSeq(session.id);
+                        streamSeq = await streamBuffer.currentSeq(row.id);
                     }
                     catch {
                         // Stream-cursor lookup is best-effort metadata; an
                         // adapter error must not blank the picker.
                     }
                 }
-                // Compute status from session state (the store doesn't
-                // surface its private `closed` flag on the Session type).
-                // We mirror the InMemorySessionStore's `computeStatus` rule:
+                // Compute status from render state (the store doesn't
+                // surface its private `closed` flag uniformly across impls).
+                // We mirror the InMemoryRenderStore's rule:
                 // expired = expiresAt <= now, otherwise active. The
                 // 'completed' state needs the closed flag to disambiguate;
                 // we report 'active' until eviction. Operators reading the
                 // detail pane get the authoritative status from the store.
-                const status = session.expiresAt <= now ? 'expired' : 'active';
+                const status = row.expiresAt <= now ? 'expired' : 'active';
                 summaries.push({
-                    sessionId: session.id,
-                    appId: session.appId,
-                    stackSize: session.stack.length,
-                    createdAt: session.createdAt,
-                    lastActivityAt: session.lastActivityAt,
+                    renderId: row.id,
+                    appId: row.appId,
+                    createdAt: row.createdAt,
+                    lastActivityAt: row.lastActivityAt,
                     status,
                     streamSeq,
                 });
             }
-            // Most-recent activity first. Tiebreak on sessionId for
+            // Most-recent activity first. Tiebreak on renderId for
             // stable ordering across reloads.
             summaries.sort((a, b) => {
                 const byRecency = b.lastActivityAt - a.lastActivityAt;
                 if (byRecency !== 0)
                     return byRecency;
-                return a.sessionId.localeCompare(b.sessionId);
+                return a.renderId.localeCompare(b.renderId);
             });
             const trimmed = summaries.slice(0, limit);
             const body = {
-                sessions: trimmed,
+                renders: trimmed,
                 total: summaries.length,
             };
             res.json(body);
         }
         catch (err) {
             res.status(500).json({
-                error: 'timeline_sessions_list_failed',
+                error: 'timeline_renders_list_failed',
                 message: err instanceof Error
-                    ? `Session store failed to list — ${err.message}`
-                    : `Session store failed to list — ${String(err)}`,
+                    ? `Render store failed to list — ${err.message}`
+                    : `Render store failed to list — ${String(err)}`,
             });
         }
     });
-    // GET /ggui/console/timeline/:sessionId/events
-    app.get('/ggui/console/timeline/:sessionId/events', async (req, res) => {
+    // GET /ggui/console/timeline/:renderId/events
+    app.get('/ggui/console/timeline/:renderId/events', async (req, res) => {
         applyDevtoolSecurityHeaders(res);
-        const sessionId = req.params['sessionId'];
-        if (!sessionId || sessionId.length === 0) {
+        const renderId = req.params['renderId'];
+        if (!renderId || renderId.length === 0) {
             res.status(400).json({
-                error: 'invalid_session_id',
-                message: 'sessionId path parameter is required',
+                error: 'invalid_render_id',
+                message: 'renderId path parameter is required',
             });
             return;
         }
         // Zero-config shape: no store wired → empty events.
-        if (!sessionStore) {
+        if (!renderStore) {
             const body = {
-                sessionId,
+                renderId,
                 events: [],
                 streamSeq: 0,
                 status: 'unknown',
@@ -122,14 +121,14 @@ export function mountConsoleTimelineRoutes(app, sessionStore, streamBuffer) {
             return;
         }
         try {
-            const session = await sessionStore.get(sessionId);
-            if (!session) {
+            const stored = await renderStore.get(renderId);
+            if (!stored) {
                 // 404 is the right status — but we still return a well-
                 // formed body so the SPA can render an "expired/dropped"
                 // notice without a special-case branch. Body matches the
                 // schema; status code disambiguates.
                 const body = {
-                    sessionId,
+                    renderId,
                     events: [],
                     streamSeq: 0,
                     status: 'unknown',
@@ -137,20 +136,20 @@ export function mountConsoleTimelineRoutes(app, sessionStore, streamBuffer) {
                 res.status(404).json(body);
                 return;
             }
-            const events = await drainSessionEvents(sessionStore, sessionId);
+            const events = await drainRenderEvents(renderStore, renderId);
             let streamSeq = 0;
             if (streamBuffer) {
                 try {
-                    streamSeq = await streamBuffer.currentSeq(sessionId);
+                    streamSeq = await streamBuffer.currentSeq(renderId);
                 }
                 catch {
                     // Best-effort. Inbound events stand on their own.
                 }
             }
             const now = Date.now();
-            const status = session.expiresAt <= now ? 'expired' : 'active';
+            const status = stored.expiresAt <= now ? 'expired' : 'active';
             const body = {
-                sessionId,
+                renderId,
                 events,
                 streamSeq,
                 status,
@@ -161,8 +160,8 @@ export function mountConsoleTimelineRoutes(app, sessionStore, streamBuffer) {
             res.status(500).json({
                 error: 'timeline_events_drain_failed',
                 message: err instanceof Error
-                    ? `Session store failed to drain — ${err.message}`
-                    : `Session store failed to drain — ${String(err)}`,
+                    ? `Render store failed to drain — ${err.message}`
+                    : `Render store failed to drain — ${String(err)}`,
             });
         }
     });

package/dist/index.d.ts

@@ -26,9 +26,9 @@
  * The `ggui serve` CLI command boots this server with the OSS defaults.
  */
 export type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers';
-export type { GadgetDescriptor, McpAppsMode, SessionStackEntry, StackItem, SystemStackItem, } from '@ggui-ai/protocol';
+export type { GadgetDescriptor, McpUiDisplayMode, Render, SystemRender, } from '@ggui-ai/protocol';
 export type { GenerationCredentials, GenerationDeps, } from '@ggui-ai/mcp-server-handlers';
-export { NO_CREDENTIALS_SYSTEM_CARD_KIND, buildNoCredentialsStackItem, } from '@ggui-ai/mcp-server-handlers';
+export { NO_CREDENTIALS_SYSTEM_CARD_KIND, buildNoCredentialsRender, } from '@ggui-ai/mcp-server-handlers';
 export { createGguiServer, defaultHandlers } from './server.js';
 export type { CreateGguiServerOptions, GguiServer, } from './server.js';
 export { FileSystemCodeStore } from './code-store-fs.js';
@@ -38,14 +38,14 @@ export { composeWiredActionRouterFromMounts } from './mcp-mounts.js';
 export type { McpService, ServicePath } from './mcp-mounts.js';
 export { validateMcpServices, validateServicePath } from './mcp-mounts.js';
 export { composePreviewReservedValidator, mergeReservedValidators, } from './reserved-validators.js';
-export { checkStackItemSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, SchemaCompatError, } from './schema-compat.js';
-export type { SchemaCompatFinding, SchemaCompatMode, SchemaCompatReport, StackItemContractShape, ToolSchemaRef, } from './schema-compat.js';
+export { checkRenderSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, SchemaCompatError, } from './schema-compat.js';
+export type { SchemaCompatFinding, SchemaCompatMode, SchemaCompatReport, RenderContractShape, ToolSchemaRef, } from './schema-compat.js';
 export type { ServerInfo } from './build-mcp.js';
 export { UnauthenticatedError, DEFAULT_BUILDER_APP_ID, defaultAppIdFromIdentity, } from './auth.js';
 export { createConsoleLogger } from './logger.js';
 export type { Logger } from './logger.js';
-export { createSessionChannelServer, DEFAULT_SESSION_CHANNEL_PATH, DEFAULT_WIRED_TOOL_TIMEOUT_MS, } from './session-channel.js';
-export type { SessionChannelOptions, SessionChannelServer, WiredActionContext, WiredActionRouter, } from './session-channel.js';
+export { createRenderChannelServer, DEFAULT_RENDER_CHANNEL_PATH, DEFAULT_WIRED_TOOL_TIMEOUT_MS, } from './render-channel.js';
+export type { RenderChannelOptions, RenderChannelServer, WiredActionContext, WiredActionRouter, } from './render-channel.js';
 export { resolveStorageFromConfig } from './storage.js';
 export type { ResolveStorageFromConfigOptions, ResolvedStorageStores, } from './storage.js';
 export { DEFAULT_PAIRING_ADMIN_INIT_PATH, DEFAULT_PAIRING_PATH, mountPairingTransport, } from './pairing-transport.js';
@@ -97,6 +97,6 @@ export type { DiscoveredPrimitiveCatalog } from '@ggui-ai/project-config/node';
 export type { LoadedTheme } from '@ggui-ai/project-config/node';
 export type { OperatorConfig } from '@ggui-ai/project-config';
 export type { ThemeWriter, ThemeFileUploader, } from './console-theme-routes.js';
-export type { LlmProvider, LlmSelection, ProviderKeyRef, UiGenerateEvent, UiGenerateInput, UiGenerateResult, UiGenerator, GeneratorTier, GeneratorRegistry, GeneratorSlugParts, } from '@ggui-ai/mcp-server-core';
+export type { LlmProvider, LlmRoute, LlmSelection, ProviderKeyRef, UiGenerateEvent, UiGenerateInput, UiGenerateResult, UiGenerator, GeneratorTier, GeneratorRegistry, GeneratorSlugParts, } from '@ggui-ai/mcp-server-core';
 export { formatGeneratorSlug, isValidGeneratorSlug, parseGeneratorSlug, } from '@ggui-ai/mcp-server-core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAKlF,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACN,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,qBAAqB,EACrB,cAAc,GACf,MAAM,8BAA8B,CAAC;AAKtC,OAAO,EACL,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EACV,uBAAuB,EACvB,UAAU,GACX,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAKrE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,kCAAkC,EAAE,MAAM,iBAAiB,CAAC;AAMrE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAO3E,OAAO,EACL,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EACV,+BAA+B,EAC/B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAKtE,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,6BAA6B,EAC7B,kCAAkC,EAClC,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAK3E,OAAO,EACL,kCAAkC,EAClC,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAM5E,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAC;AACnF,YAAY,EAAE,gCAAgC,EAAE,MAAM,kCAAkC,CAAC;AAKzF,OAAO,EACL,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,iCAAiC,EACjC,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,EACd,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,QAAQ,IAAI,2BAA2B,GACxC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,kCAAkC,EAClC,iCAAiC,GAClC,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EAAE,mCAAmC,EAAE,MAAM,sCAAsC,CAAC;AAIhG,YAAY,EACV,oBAAoB,EACpB,OAAO,EACP,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,8BAA8B,EAC9B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAS/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,YAAY,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAQrF,OAAO,EACL,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EACV,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AASxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,YAAY,EACV,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAOlE,YAAY,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAU/E,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAOhE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAU9D,YAAY,EACV,WAAW,EACX,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAQnC,YAAY,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -26,10 +26,10 @@
  * The `ggui serve` CLI command boots this server with the OSS defaults.
  */
 // No-credentials fallback helpers — re-exported so the OSS CLI can
-// build the no-credentials card stack item (pointing at the resolved
+// build the no-credentials card render (pointing at the resolved
 // `/settings` URL) without taking a direct `@ggui-ai/mcp-server-handlers`
 // dependency.
-export { NO_CREDENTIALS_SYSTEM_CARD_KIND, buildNoCredentialsStackItem, } from '@ggui-ai/mcp-server-handlers';
+export { NO_CREDENTIALS_SYSTEM_CARD_KIND, buildNoCredentialsRender, } from '@ggui-ai/mcp-server-handlers';
 export { createGguiServer, defaultHandlers } from './server.js';
 // Content-addressable code delivery (2026-05-03). FileSystemCodeStore
 // is the OSS dev default; in-memory variant ships in
@@ -48,10 +48,10 @@ export { composePreviewReservedValidator, mergeReservedValidators, } from './res
 // type, the canonical error, and the default mode constant. Consumers
 // embedding their own endpoint paths (custom hosted wrappers) can
 // reuse the helper directly.
-export { checkStackItemSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, SchemaCompatError, } from './schema-compat.js';
+export { checkRenderSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, SchemaCompatError, } from './schema-compat.js';
 export { UnauthenticatedError, DEFAULT_BUILDER_APP_ID, defaultAppIdFromIdentity, } from './auth.js';
 export { createConsoleLogger } from './logger.js';
-export { createSessionChannelServer, DEFAULT_SESSION_CHANNEL_PATH, DEFAULT_WIRED_TOOL_TIMEOUT_MS, } from './session-channel.js';
+export { createRenderChannelServer, DEFAULT_RENDER_CHANNEL_PATH, DEFAULT_WIRED_TOOL_TIMEOUT_MS, } from './render-channel.js';
 export { resolveStorageFromConfig } from './storage.js';
 export { DEFAULT_PAIRING_ADMIN_INIT_PATH, DEFAULT_PAIRING_PATH, mountPairingTransport, } from './pairing-transport.js';
 // End-user browser-session cookie + login routes. Cookie + endpoints
@@ -103,7 +103,7 @@ export { InMemoryShortCodeIndex } from '@ggui-ai/mcp-server-core/in-memory';
 export { InMemoryAuthAdapter } from '@ggui-ai/mcp-server-core/in-memory';
 // In-memory rate-limiter + quota-store reference adapters. Re-exported
 // for the same reason as `InMemoryAuthAdapter` — CLI hosts can compose
-// `--public-demo` posture (per-IP rate limit on ggui_push) without
+// `--public-demo` posture (per-IP rate limit on ggui_render) without
 // taking a direct `@ggui-ai/mcp-server-core` dep. The default fallback
 // inside `createGguiServer` is `NoopRateLimiter`; this is the smallest
 // non-trivial alternative.

package/dist/instructions-presets.d.ts

@@ -61,7 +61,7 @@ export declare const MCP_INSTRUCTIONS_PRESETS: {
     readonly aggressive: string;
     /**
      * `aggressive` + a worked invocation example. Useful when the
-     * operator wants the LLM to see a complete handshake → push
+     * operator wants the LLM to see a complete handshake → render
      * pattern at boot.
      */
     readonly always: string;

package/dist/instructions-presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions-presets.d.ts","sourceRoot":"","sources":["../src/instructions-presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA4FH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;IACnC;;;;OAIG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IASH;;;OAGG;;IAIH;;;;OAIG;;CAEK,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG,MAAM,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,SAAS,GACtC,MAAM,GAAG,SAAS,CAWpB"}
+{"version":3,"file":"instructions-presets.d.ts","sourceRoot":"","sources":["../src/instructions-presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA8GH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;IACnC;;;;OAIG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IASH;;;OAGG;;IAIH;;;;OAIG;;CAEK,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG,MAAM,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,SAAS,GACtC,MAAM,GAAG,SAAS,CAWpB"}

package/dist/instructions-presets.js

@@ -48,10 +48,10 @@
 const ACTION_ROUTING_PARAGRAPH = "Action routing: every actionSpec entry is a GESTURE — a discrete event the agent reacts to on its next turn. When the user interacts, the iframe relays the action through `ggui_runtime_submit_action` to the server, which appends the event onto a per-stack-item pipe. Your `ggui_consume` long-poll unblocks mid-turn with the event payload plus a uiContext snapshot of every declared contextSpec slot. There is no synchronous server-side tool-fire — `actions drive turns` is a structural invariant (docs/principles/actions-vs-context.md): an action always waits for the agent. Cross-MCP `nextStep` hints work the same way: the agent reads the event's `actionData.nextStep`, decides whether to honor it, and calls the named tool on the next turn (the tool MAY live on a different MCP server — declare it in `agentCapabilities.tools` so the cross-ref invariant passes).";
 /**
  * Worked invocation example. Layered atop the `aggressive` content by
- * `always` only — shows the literal handshake → push pattern an
+ * `always` only — shows the literal handshake → render pattern an
  * operator can copy.
  */
-const WORKED_EXAMPLE_PARAGRAPH = "Example: ggui_handshake({ sessionId: 's_…', intent: 'a settings panel for notification preferences', blueprintDraft: { contract: {...}, variance: { persona: 'minimalist' } } }) returns { handshakeId: 'h_…', suggestion: { origin: 'cache' | 'agent' | 'synth', blueprintMeta: { blueprintId, contractHash, codeHash?, generator, variance }, amendments?, validationFindings? }, contractHash: '<hex>' }. ACCEPT PATH: ggui_push({ handshakeId: 'h_…', decision: { kind: 'accept' } }) — reuses the provisional blueprintId. OVERRIDE PATH: ggui_push({ handshakeId: 'h_…', decision: { kind: 'override', blueprintDraft: { contract: { ...refined } } } }) — mints a fresh blueprintId against your new draft.";
+const WORKED_EXAMPLE_PARAGRAPH = "Example: ggui_handshake({ intent: 'a settings panel for notification preferences', blueprintDraft: { contract: {...}, variance: { persona: 'minimalist' } } }) returns { handshakeId: 'h_…', suggestion: { origin: 'cache' | 'agent' | 'synth', blueprintMeta: { blueprintId, contractHash, codeHash?, generator, variance }, amendments?, validationFindings? }, contractHash: '<hex>' }. ACCEPT PATH: ggui_render({ handshakeId: 'h_…', decision: { kind: 'accept' } }) — reuses the provisional blueprintId; response carries the minted renderId. OVERRIDE PATH: ggui_render({ handshakeId: 'h_…', decision: { kind: 'override', blueprintDraft: { contract: { ...refined } } } }) — mints a fresh blueprintId against your new draft.";
 /**
  * The default-preset body, captured as a const so `aggressive` and
  * `always` can layer additional paragraphs on top without diverging
@@ -68,7 +68,7 @@ const DEFAULT_PRESET_BODY = [
     '',
     '  • actionSpec   — client → agent (discrete events). User gestures (clicks, submits) that drive the agent\'s NEXT TURN. Each entry has a `label`, optional `schema` for the payload, and optional `nextStep: "<toolName>"`. When `nextStep` is present, it names the tool the agent SHOULD call next AND the same name MUST also appear in `agentCapabilities.tools` (cross-ref invariant; rejection code `cross_reference_unresolved`). Omit `nextStep` entirely when the agent should decide freely from broader context (open-ended form submits). e.g. a feedback form has `submit` on actionSpec with `nextStep:"record_feedback"` (and `record_feedback` listed under `agentCapabilities.tools`).',
     '',
-    '  • contextSpec  — client → agent (observed state, not events). Continuous client state the agent observes — slider position, draft text, current selection. Use contextSpec when you need to KNOW the state but don\'t need to ACT on every change. On MCP Apps hosts the runtime auto-mirrors the snapshot into the host\'s widget-context surface (the agent sees it on the next turn without polling). On raw MCP clients there is no auto-mirror — call ggui_get_stack to read `contextSnapshot` when you need the latest values. e.g. a calendar has `selectedDate` on contextSpec.',
+    '  • contextSpec  — client → agent (observed state, not events). Continuous client state the agent observes — slider position, draft text, current selection. Use contextSpec when you need to KNOW the state but don\'t need to ACT on every change. On MCP Apps hosts the runtime auto-mirrors the snapshot into the host\'s widget-context surface (the agent sees it on the next turn without polling). On raw MCP clients there is no auto-mirror — call ggui_get_render to read `contextSnapshot` when you need the latest values. e.g. a calendar has `selectedDate` on contextSpec.',
     '',
     '  • streamSpec   — agent → client (live updates). Live outbound channels for streaming data to the UI mid-render — chat tokens, progress events, log lines, time-series data. Each entry has a `schema` for the frame shape; you push frames via ggui_emit. e.g. a chat surface has `assistantMessage` on streamSpec for token-by-token output.',
     '',
@@ -78,49 +78,67 @@ const DEFAULT_PRESET_BODY = [
     '',
     'Every chat that touches ggui follows this loop:',
     '',
-    '  1. ggui_new_session — FIRST CALL of any chat. Mints a sessionId. Call once per conversation; thread the result through every subsequent handshake.',
+    'TOOL PREREQUISITES (read once, internalize):',
+    '  • `ggui_handshake` is a prerequisite for `ggui_render` ONLY. It returns the contract+code negotiation state (`handshakeId`) that `ggui_render` consumes. Call it BEFORE rendering a NEW UI.',
+    '  • `ggui_consume` and `ggui_update` operate on EXISTING renders identified by `renderId` and require NO handshake. The `renderId` was minted by an earlier `ggui_render` call; it identifies the live iframe the user is interacting with. Calling `ggui_handshake` before `ggui_consume`/`ggui_update` is a category error — it would mint a SEPARATE new render that the user can\'t see, orphaning whichever live iframe the gesture targeted.',
+    '  • Each `renderId` is the agent\'s persistent handle to one specific live iframe. Reuse it across consume/update for as long as the user is interacting with that UI; only call `ggui_handshake` again when you need to spawn a genuinely new UI surface.',
     '',
-    '  2. ggui_handshake — negotiate a contract for the next UI. Post {sessionId, intent, blueprintDraft: {contract, variance?, generator?}}. `variance` is optional and lets you steer cache lookup + gen by axis: `persona` ("minimalist", "playful"), `aesthetic` ("dense", "spacious"), `intentContext` (free-form usage notes), `seedPrompt` (deterministic seed). Server runs BlueprintSearch + contract-validation in parallel and returns a handshakeId + suggestion (origin: cache | agent | synth). cache → blueprint already exists, push delivers it instantly. agent → novel-but-clean draft, gen runs on push. synth → your draft failed validation, server amended it; diff is on suggestion.amendments.',
+    '  1. ggui_handshake — FIRST CALL for any UI. Negotiate a contract for the next render. Post {intent, blueprintDraft: {contract, variance?, generator?}}. `variance` is optional and lets you steer cache lookup + gen by axis: `persona` ("minimalist", "playful"), `aesthetic` ("dense", "spacious"), `intentContext` (free-form usage notes), `seedPrompt` (deterministic seed). Server runs BlueprintSearch + contract-validation in parallel and returns a handshakeId + suggestion (origin: cache | agent | synth). cache → blueprint already exists, render delivers it instantly. agent → novel-but-clean draft, gen runs on render. synth → your draft failed validation, server amended it; diff is on suggestion.amendments.',
     '',
-    '  3. ggui_push — deliver the UI. handshakeId is REQUIRED (from step 2); calling push without it fails with `handshake_not_found`. Send {handshakeId, decision: {kind:"accept"}} to use the suggestion verbatim, OR {handshakeId, decision: {kind:"override", blueprintDraft:{...}}} to mint fresh against a new draft. If the contract declares propsSpec, props is REQUIRED. Handshake records are SINGLE-USE and expire after 10 minutes. On error: `handshake_not_found` → call ggui_handshake again. `contract_violation` (props don\'t match propsSpec) / `contract_schema_invalid` (an inner JSON Schema is malformed) / `cross_reference_unresolved` (`actionSpec[*].nextStep` or `streamSpec[*].source.tool` names a tool not in `agentCapabilities.tools`) / `schema_mismatch_error` (action schema not a subset of the named tool\'s inputSchema) / `missing_props` → fix the input and retry with the SAME handshakeId (still valid until consumed).',
+    '  2. ggui_render — deliver the UI. handshakeId is REQUIRED (from step 1); calling render without it fails with `handshake_not_found`. Send {handshakeId, decision: {kind:"accept"}} to use the suggestion verbatim, OR {handshakeId, decision: {kind:"override", blueprintDraft:{...}}} to mint fresh against a new draft. If the contract declares propsSpec, props is REQUIRED. Response includes the minted `renderId` — your handle for every follow-up call. Handshake records are SINGLE-USE and expire after 10 minutes. On error: `handshake_not_found` → call ggui_handshake again. `contract_violation` (props don\'t match propsSpec) / `contract_schema_invalid` (an inner JSON Schema is malformed) / `cross_reference_unresolved` (`actionSpec[*].nextStep` or `streamSpec[*].source.tool` names a tool not in `agentCapabilities.tools`) / `schema_mismatch_error` (action schema not a subset of the named tool\'s inputSchema) / `missing_props` → fix the input and retry with the SAME handshakeId (still valid until consumed).',
     '',
-    '  4. NEXT STEP — read the push response. If it carries a `nextStep` field, call that tool with the given args. Push only emits `nextStep` when the contract declared a non-empty actionSpec (i.e., the UI has interactive buttons/forms); in that case nextStep names ggui_consume and your job is to long-poll for the user\'s gesture. If the push response has NO nextStep, the UI is pure-display (props only, no actionSpec) — you can end your turn; the user reads the UI and types their next prompt when they\'re ready.',
+    '  3. NEXT STEP — read the render response. If it carries a `nextStep` field, call that tool with the given args. Render only emits `nextStep` when the contract declared a non-empty actionSpec (i.e., the UI has interactive buttons/forms); in that case nextStep names ggui_consume and your job is to long-poll for the user\'s gesture. If the render response has NO nextStep, the UI is pure-display (props only, no actionSpec) — you can end your turn; the user reads the UI and types their next prompt when they\'re ready.',
     '',
-    '  5. ggui_consume (when push said to) — long-poll for user interaction. Keyed by stackItemId. Blocks up to ~15 min (deployment-configurable); returns when an actionSpec event arrives or the session closes. Each return carries `{events, status}`: `events[]` is the discrete action(s) the user just took. Each event is an envelope `{intent, actionData, uiContext, actionId, firedAt}` — `actionData` is WHAT the user did (action name + validated payload, plus `nextStep` hint if the author declared one); `uiContext` is the iframe-local snapshot of every declared contextSpec slot AT THE MOMENT the action fired (form fields, selected tab, slider value, scroll position — whatever the contract declared). Both inform your reaction without a second round trip. Honor each event\'s `actionData.nextStep` hint if the tool is available, then loop back to step 2 to render the response. Continue until consume returns status:"completed" or no further follow-up is needed.',
+    '  4. ggui_consume (when render said to) — long-poll for user interaction. Keyed by renderId. Blocks up to ~15 min (deployment-configurable); returns when an actionSpec event arrives or the render closes. Each return carries `{events, status}`: `events[]` is the discrete action(s) the user just took. Each event is an envelope `{intent, actionData, uiContext, actionId, firedAt}` — `actionData` is WHAT the user did (action name + validated payload, plus `nextStep` hint if the author declared one); `uiContext` is the iframe-local snapshot of every declared contextSpec slot AT THE MOMENT the action fired (form fields, selected tab, slider value, scroll position — whatever the contract declared). Both inform your reaction without a second round trip. Honor each event\'s `actionData.nextStep` hint if the tool is available, then loop back to step 1 to render the response. Continue until consume returns status:"completed" or no further follow-up is needed.',
     '',
-    '  6. ggui_update — reflect the new state in the UI. After ANY domain-tool call whose result changed data the rendered UI displays (e.g. `todo_toggle` flips a todo\'s `done`, `cart_add_item` extends a cart, `note_save` persists text), you MUST immediately call `ggui_update` with the refreshed props so the user sees what just happened. The rendered UI does NOT auto-refresh — it only shows the props it was last given. Skipping `ggui_update` after a state-mutating tool call leaves the user staring at stale state and is the #1 wire bug. Pattern: `consume → domain-tool → ggui_update → loop to consume`. Two modes: `{stackItemId, kind:"replace", props}` sends the FULL new props map (use when most fields changed or you want deterministic restoration); `{stackItemId, kind:"merge", patch}` sends ONLY the delta as RFC 7396 JSON Merge Patch (shallow merge, recurse on nested objects, `null` deletes a key, arrays fully replace — use when most props stay the same and only one or two fields changed). Prefer `merge` after a single domain-tool mutation; prefer `replace` when restoring state or when most fields changed. The only times you skip `ggui_update` are: (a) the domain tool was pure-read (todo_list, search, etc.) AND its result wasn\'t for the UI, or (b) the contract has no propsSpec (pure-display with no mutable state).',
+    '  5. ggui_update — reflect the new state in the UI. After ANY domain-tool call whose result changed data the rendered UI displays (e.g. `todo_toggle` flips a todo\'s `done`, `cart_add_item` extends a cart, `note_save` persists text), you MUST immediately call `ggui_update` with the refreshed props so the user sees what just happened. The rendered UI does NOT auto-refresh — it only shows the props it was last given. Skipping `ggui_update` after a state-mutating tool call leaves the user staring at stale state and is the #1 wire bug. Pattern: `consume → domain-tool → ggui_update → loop to consume`. Two modes: `{renderId, kind:"replace", props}` sends the FULL new props map (use when most fields changed or you want deterministic restoration); `{renderId, kind:"merge", patch}` sends ONLY the delta as RFC 7396 JSON Merge Patch (shallow merge, recurse on nested objects, `null` deletes a key, arrays fully replace — use when most props stay the same and only one or two fields changed). Prefer `merge` after a single domain-tool mutation; prefer `replace` when restoring state or when most fields changed. The only times you skip `ggui_update` are: (a) the domain tool was pure-read (todo_list, search, etc.) AND its result wasn\'t for the UI, or (b) the contract has no propsSpec (pure-display with no mutable state).',
     '',
-    'In short: let the protocol\'s `nextStep` fields drive routing. Every ggui_* tool whose response logically chains forwards (new_session → handshake → push → consume) emits a nextStep when there IS a next step; the absence of nextStep means "you\'re done with this thread for now."',
+    'In short: let the protocol\'s `nextStep` fields drive routing. Every ggui_* tool whose response logically chains forwards (handshake → render → consume) emits a nextStep when there IS a next step; the absence of nextStep means "you\'re done with this thread for now."',
     '',
-    '═══ COMPLEMENTARY TOOLS ═══',
+    '═══ REHYDRATED USER GESTURES (renderId-carrying user messages) ═══',
     '',
-    '  • ggui_update    — refresh a delivered UI with new props WITHOUT destroying it. Two modes: `kind:"replace"` (full props) or `kind:"merge"` (RFC 7396 delta — see step 6). ALWAYS call this after any state-mutating tool call; re-pushing would lose scroll position, focus, and uncommitted input. Forgetting `ggui_update` after a mutation is the most common protocol bug.',
+    'When the user reloads the page after interacting with a rendered UI, the iframe re-mounts but the agent process may have lost its `ggui_consume` long-poll. Subsequent clicks in the rehydrated iframe arrive as a USER MESSAGE that carries an explicit `renderId` — either as a structured directive block (host-synthesized prefix wrapping the user prose) or as a typed slice the host passes through. EITHER WAY, the rule is the same:',
     '',
-    '  • ggui_emit    — push frames to a streamSpec channel on a delivered UI. Use when the contract declared streamSpec (chat tokens, progress bars, live data). Frames must match the channel\'s declared `schema`. The live channel of the wire carries these.',
+    '  • The named `renderId` identifies an EXISTING live iframe. Treat the message as a continuation of THAT render, not as a fresh request.',
+    '  • REQUIRED first tool call: `ggui_consume({renderId: <the-named-id>})` to drain the queued gesture. This returns the event the user fired; act on it with the appropriate domain tool, then `ggui_update({renderId, ...})` on the SAME renderId.',
+    '  • DO NOT call `ggui_handshake` for a rehydrated-gesture message. Handshaking mints a SEPARATE new render the user can\'t see, orphaning the live iframe they actually clicked. This is the most common reload-flow regression — when in doubt and you see a `renderId` named in the user message, your first tool call is `ggui_consume({renderId})`, full stop.',
+    '',
+    'Worked example — user reload + click:',
+    '',
+    '  1. User reloads the page; the iframe for render `r_abc123` re-mounts.',
+    '  2. User clicks "undo" in the iframe.',
+    '  3. Agent receives a user message containing `renderId: r_abc123` (in a host-synthesized directive or as a structured slice).',
+    '  4. Agent calls `ggui_consume({renderId: "r_abc123"})` — NOT `ggui_handshake`.',
+    '  5. Consume returns the click event; agent calls `todo_toggle({id: 1, done: false})`.',
+    '  6. Agent calls `ggui_update({renderId: "r_abc123", kind: "merge", patch: {todos: [...]}})`.',
     '',
-    '  • ggui_pop       — pop the top stack item (e.g., close a modal you pushed). Idempotent — popping an empty stack returns null without error.',
+    'The same flow applies whether the message arrives mid-conversation or as the very first turn after the user opens a saved chat URL — the renderId is the source of truth for which iframe to address.',
     '',
-    '  • ggui_close     — explicitly end a session. Optional; sessions GC on their own. Use when the user has clearly finished and you want to free resources.',
+    '═══ COMPLEMENTARY TOOLS ═══',
+    '',
+    '  • ggui_update    — refresh a delivered UI with new props WITHOUT destroying it. Two modes: `kind:"replace"` (full props) or `kind:"merge"` (RFC 7396 delta — see step 5). ALWAYS call this after any state-mutating tool call; re-rendering would lose scroll position, focus, and uncommitted input. Forgetting `ggui_update` after a mutation is the most common protocol bug.',
+    '',
+    '  • ggui_emit    — push frames to a streamSpec channel on a delivered UI. Use when the contract declared streamSpec (chat tokens, progress bars, live data). Frames must match the channel\'s declared `schema`. The live channel of the wire carries these.',
     '',
-    '  • ggui_get_session / ggui_get_stack — inspect current session state if you\'ve lost track of what\'s rendered. ggui_get_stack also returns each item\'s `contextSnapshot` — the canonical way to read contextSpec values from a raw MCP client.',
+    '  • ggui_get_render / ggui_list_renders — inspect current render state if you\'ve lost track of what\'s on screen. ggui_get_render returns the render including its `contextSnapshot` — the canonical way to read contextSpec values from a raw MCP client. ggui_list_renders enumerates every render in the current host conversation (paired by `_meta["ai.ggui/host-session"]` on the inbound call).',
     '',
     '═══ HOST RENDERING ═══',
     '',
-    'Two host shapes consume push output identically — your job is the same:',
+    'Two host shapes consume render output identically — your job is the same:',
     '',
-    '  • MCP Apps hosts (claude.ai, MCP-Apps-aware desktop clients) — push responses carry the rendered UI inline via `_meta.ggui.bootstrap`; the host displays it automatically. The user interacts with the UI directly, and contextSpec snapshots flow back into your widget-context surface without any agent action.',
+    '  • MCP Apps hosts (claude.ai, MCP-Apps-aware desktop clients) — render responses carry the rendered UI inline via `_meta["ai.ggui/render"]`; the host displays it automatically. The user interacts with the UI directly, and contextSpec snapshots flow back into your widget-context surface without any agent action.',
     '',
-    '  • Plain MCP clients (Claude Agent SDK without MCP Apps host adapter, raw CLI clients) — push responses carry a renderer URL in the structured content; the host either embeds it as an iframe or displays it as a link. Wire flow is identical (handshake → push → consume); only the rendering surface differs.',
+    '  • Plain MCP clients (Claude Agent SDK without MCP Apps host adapter, raw CLI clients) — render responses carry a renderer URL in the structured content; the host either embeds it as an iframe or displays it as a link. Wire flow is identical (handshake → render → consume); only the rendering surface differs.',
     '',
     'Rendered UIs are LIVE — actionSpec entries route back to you as events you receive via consume (each gesture\'s payload validated against the entry\'s declared schema). You don\'t write glue code for any of this; declaring the spec at handshake time is enough.',
     '',
     '═══ TOOL DISCOVERY (lazy-loading hosts) ═══',
     '',
-    'Some MCP hosts (notably claude.ai\'s connector model) use PROGRESSIVE tool discovery — only a small priority subset of tools is warmed at conversation start; the rest must be explicitly discovered via `tool_search` before they\'re callable. The ggui_* loop crosses this boundary on every push: handshake/push warm easily because you call them early, but `ggui_consume` and `ggui_update` are needed AFTER push and the host may not have loaded them yet.',
+    'Some MCP hosts (notably claude.ai\'s connector model) use PROGRESSIVE tool discovery — only a small priority subset of tools is warmed at conversation start; the rest must be explicitly discovered via `tool_search` before they\'re callable. The ggui_* loop crosses this boundary on every render: handshake/render warm easily because you call them early, but `ggui_consume` and `ggui_update` are needed AFTER render and the host may not have loaded them yet.',
     '',
     'SYMPTOM: a tool call fails with a message like "tool has not been loaded yet — call tool_search first" or "you do not have the correct parameter names." RECOVERY: call `tool_search` with the tool name as a query (e.g. `tool_search({ query: "ggui_consume" })`), wait for the load to complete, then retry the original call with the same args. Same pattern for `ggui_update`. After one successful `tool_search` per tool per conversation, subsequent calls work directly.',
     '',
-    'WHEN IN DOUBT: if the push response carries `nextStep`, the host has effectively asked you to call that tool. Don\'t skip ggui_consume because the host whined about it being unloaded — `tool_search` first, then call. Skipping it leaves the user staring at a UI whose actions silently never reach the agent — the worst protocol failure mode.',
+    'WHEN IN DOUBT: if the render response carries `nextStep`, the host has effectively asked you to call that tool. Don\'t skip ggui_consume because the host whined about it being unloaded — `tool_search` first, then call. Skipping it leaves the user staring at a UI whose actions silently never reach the agent — the worst protocol failure mode.',
 ];
 /**
  * Preset name → instruction-string map. Operators select a preset by
@@ -146,7 +164,7 @@ export const MCP_INSTRUCTIONS_PRESETS = {
     aggressive: [...DEFAULT_PRESET_BODY, '', ACTION_ROUTING_PARAGRAPH].join('\n'),
     /**
      * `aggressive` + a worked invocation example. Useful when the
-     * operator wants the LLM to see a complete handshake → push
+     * operator wants the LLM to see a complete handshake → render
      * pattern at boot.
      */
     always: [

package/dist/llm-backed-negotiator.d.ts

@@ -39,7 +39,7 @@
  *
  * One LLM call per handshake (when creds resolve). Operators
  * concerned about cost can either (a) skip handshake and call
- * `ggui_push` directly with `{story}`, or (b) bind a different
+ * `ggui_render` directly with `{story}`, or (b) bind a different
  * negotiator (e.g., the cache-backed one for read-only cache
  * lookups) via `createGguiServer({handshake: {negotiator: ...}})`.
  *
@@ -50,11 +50,11 @@
  * same `negotiate()` pipeline, just with degraded RAG when local
  * infrastructure isn't bound.
  */
-import { type LLMCaller } from '@ggui-ai/negotiator';
-import type { EmbeddingProvider, LlmSelection, ProviderKeyRef, VariantSelectionContext, VariantSelectionDecision, VectorStore } from '@ggui-ai/mcp-server-core';
-import type { HandlerContext } from '@ggui-ai/mcp-server-handlers';
-import { type HandshakeNegotiator, type InstalledBlueprintsProvider } from '@ggui-ai/mcp-server-handlers/session-mutations';
-import type { Blueprint } from '@ggui-ai/protocol';
+import type { EmbeddingProvider, LlmSelection, ProviderKeyRef, VariantSelectionContext, VariantSelectionDecision, VectorStore } from "@ggui-ai/mcp-server-core";
+import type { HandlerContext } from "@ggui-ai/mcp-server-handlers";
+import { type HandshakeNegotiator, type InstalledBlueprintsProvider } from "@ggui-ai/mcp-server-handlers/renders";
+import { type LLMCaller } from "@ggui-ai/negotiator";
+import type { Blueprint } from "@ggui-ai/protocol";
 /**
  * Wrap a resolved BYOK credential pair into an `LLMCaller` the
  * negotiator can call. The adapter is chosen via `selectAdapter`

package/dist/llm-backed-negotiator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-backed-negotiator.d.ts","sourceRoot":"","sources":["../src/llm-backed-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EACV,iBAAiB,EAEjB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAGL,KAAK,mBAAmB,EAExB,KAAK,2BAA2B,EAEjC,MAAM,gDAAgD,CAAC;AAGxD,OAAO,KAAK,EACV,SAAS,EAGV,MAAM,mBAAmB,CAAC;AAiB3B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,cAAc,GAC1B,SAAS,CAwCX;AAiFD;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;;OAMG;IACH,UAAU,EAAE,CACV,GAAG,EAAE,cAAc,KAEjB;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GACxD,OAAO,CAAC;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC,GACxE,IAAI,CAAC;IACT;;;OAGG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;KACnC,CAAC;IACF;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;CACnD;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,mBAAmB,CAgNrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,2wDAqBgN,CAAC;AAqC7P;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CAmDR;AA8CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,GACX,wBAAwB,CAyB1B"}
+{"version":3,"file":"llm-backed-negotiator.d.ts","sourceRoot":"","sources":["../src/llm-backed-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAGL,KAAK,mBAAmB,EAExB,KAAK,2BAA2B,EAEjC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAqC,MAAM,mBAAmB,CAAC;AAmBtF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,GAAG,SAAS,CAmD9F;AA6ED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;;OAMG;IACH,UAAU,EAAE,CACV,GAAG,EAAE,cAAc,KAEjB;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GACxD,OAAO,CAAC;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC,GACxE,IAAI,CAAC;IACT;;;OAGG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;KACnC,CAAC;IACF;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;CACnD;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,mBAAmB,CA2MrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,2wDAoBgN,CAAC;AAqC7P;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CA2CR;AA8CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,CAyBpF"}