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

package/dist/instructions-presets.js

@@ -38,20 +38,20 @@
  * already-shipped `--mcp-instructions` CLI flag and operator configs.
  */
 /**
- * Action-routing pattern detail (Pattern α / Pattern β). Layered atop
- * `default` by the `aggressive` and `always` presets — `default`
+ * Action-routing detail (submit_action → consume-pipe loop). Layered
+ * atop `default` by the `aggressive` and `always` presets — `default`
  * already covers the actionSpec wire shape via the MENTAL MODEL
  * block; this paragraph adds the host-side dispatch semantics that
  * matter when an operator wants the LLM to also reason about how the
  * underlying tools/call envelopes flow.
  */
-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).";
+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-render 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 → render pattern an
  * operator can copy.
  */
-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.";
+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?, source?, variance }, amendments?, validationFindings? }, contractHash: '<hex>' }. props is REQUIRED on every render (pass props: {} when the contract declares no propsSpec). ACCEPT PATH: ggui_render({ handshakeId: 'h_…', props: {} }) — OMIT override to reuse the proposed blueprintId verbatim; response carries the minted sessionId. OVERRIDE PATH: ggui_render({ handshakeId: 'h_…', props: {}, override: { contract: { ...refined } } }) — STRICT fresh draft against override.contract (server does NOT repair). override: { variance: {...} } instead re-aims the variant (persona/aesthetic/context/seedPrompt) while keeping the agreed contract.";
 /**
  * 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_render 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_session 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.',
     '',
@@ -80,39 +80,39 @@ const DEFAULT_PRESET_BODY = [
     '',
     '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.',
+    '  • `ggui_consume` and `ggui_update` operate on EXISTING sessions identified by `sessionId` and require NO handshake. The `sessionId` 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 session that the user can\'t see, orphaning whichever live iframe the gesture targeted.',
+    '  • Each `sessionId` 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.',
     '',
     '  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 steers cache lookup + gen by axis: `persona` ("minimalist", "playful"), `aesthetic` ("dense", "spacious"), `seedPrompt` (deterministic seed). HANDSHAKE IS FORGIVING — it ALWAYS returns a handshakeId + a CONFORMING contract, even when your draft is malformed: the server cache-matches an existing blueprint OR repairs your draft until it passes validation. The suggestion carries origin: cache (an existing blueprint matched — delivered instantly) | agent (your draft was already clean) | synth (your draft had problems and the server repaired it; `suggestion.validationFindings` lists exactly what was wrong so you learn for next time). CRITICAL: a synth result is NOT an error and NOT a request to retry — the returned contract is READY. Accept it and call ggui_render. Do NOT re-call ggui_handshake hoping for a different origin — that is a loop that wastes turns and changes nothing.',
     '',
-    '  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 handshake suggestion verbatim — THE NORMAL PATH, since the contract is already conforming — OR {handshakeId, decision: {kind:"override", blueprintDraft:{...}}} to commit to a FRESH draft of your own. OVERRIDE IS STRICT: a forced contract MUST already conform — the server does NOT repair it (override means "use mine exactly"). Prefer accept; override only when the suggestion genuinely is not what you want AND your replacement contract is correct. 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` / `missing_props` (props don\'t match propsSpec) → fix props and retry with the SAME handshakeId; `override_contract_invalid` (your forced override draft failed validation) → drop the override, re-run ggui_handshake with that draft (which WILL repair it), and accept the suggestion — do NOT retry override with the same draft.',
+    '  2. ggui_render — deliver the UI. handshakeId is REQUIRED (from step 1); calling render without it fails with `handshake_not_found`. props is ALSO REQUIRED on every call — send {handshakeId, props} (pass props: {} when the contract declares no propsSpec). OMIT `override` to use the handshake suggestion verbatim — THE NORMAL PATH, since the contract is already conforming. To commit to a FRESH draft of your own, add {handshakeId, props, override:{contract:{...}}}. OVERRIDE IS STRICT: a forced override.contract MUST already conform — the server does NOT repair it (override means "use mine exactly"). Alternatively {handshakeId, props, override:{variance:{...}}} re-aims the variant (persona/aesthetic/context/seedPrompt) while keeping the agreed contract. Prefer omitting override; override only when the suggestion genuinely is not what you want AND your replacement is correct. Response includes the minted `sessionId` — 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` / `missing_props` (props don\'t match propsSpec) → fix props and retry with the SAME handshakeId; `override_contract_invalid` (your override.contract failed validation) → drop override entirely, re-run ggui_handshake with that draft (which WILL repair it), and render the suggestion — do NOT retry override with the same draft.',
     '',
     '  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.',
     '',
-    '  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.',
+    '  4. ggui_consume (when render said to) — long-poll for user interaction. Keyed by sessionId. 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 1 to render the response. Continue until consume returns status:"completed" or no further follow-up is needed.',
     '',
-    '  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).',
+    '  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: `{sessionId, kind:"replace", props}` sends the FULL new props map (use when most fields changed or you want deterministic restoration); `{sessionId, 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 (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."',
     '',
-    '═══ REHYDRATED USER GESTURES (renderId-carrying user messages) ═══',
+    '═══ REHYDRATED USER GESTURES (sessionId-carrying user messages) ═══',
     '',
-    '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:',
+    '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 `sessionId` — 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:',
     '',
-    '  • 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.',
+    '  • The named `sessionId` identifies an EXISTING live iframe. Treat the message as a continuation of THAT session, not as a fresh request.',
+    '  • REQUIRED first tool call: `ggui_consume({sessionId: <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({sessionId, ...})` on the SAME sessionId.',
+    '  • DO NOT call `ggui_handshake` for a rehydrated-gesture message. Handshaking mints a SEPARATE new session 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 `sessionId` named in the user message, your first tool call is `ggui_consume({sessionId})`, full stop.',
     '',
     'Worked example — user reload + click:',
     '',
-    '  1. User reloads the page; the iframe for render `r_abc123` re-mounts.',
+    '  1. User reloads the page; the iframe for session `s_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`.',
+    '  3. Agent receives a user message containing `sessionId: s_abc123` (in a host-synthesized directive or as a structured slice).',
+    '  4. Agent calls `ggui_consume({sessionId: "s_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: [...]}})`.',
+    '  6. Agent calls `ggui_update({sessionId: "s_abc123", kind: "merge", patch: {todos: [...]}})`.',
     '',
-    '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.',
+    '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 sessionId is the source of truth for which iframe to address.',
     '',
     '═══ COMPLEMENTARY TOOLS ═══',
     '',
@@ -120,7 +120,7 @@ const DEFAULT_PRESET_BODY = [
     '',
     '  • 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_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).',
+    '  • ggui_get_session / ggui_list_sessions — inspect current session state if you\'ve lost track of what\'s on screen. ggui_get_session returns the session including its `contextSnapshot` — the canonical way to read contextSpec values from a raw MCP client. ggui_list_sessions enumerates every session in the current host conversation (paired by `_meta["ai.ggui/host-session"]` on the inbound call).',
     '',
     '═══ HOST RENDERING ═══',
     '',
@@ -157,9 +157,9 @@ export const MCP_INSTRUCTIONS_PRESETS = {
     default: DEFAULT_PRESET_BODY.join('\n'),
     /**
      * Default protocol primer + the host-side action-routing detail
-     * (Pattern α direct dispatch vs Pattern β cross-server consent
-     * bridge). Pick when the operator wants the LLM to also reason
-     * about how the underlying tools/call envelopes flow.
+     * (submit_action relay → per-render pipe → `ggui_consume` drain).
+     * Pick when the operator wants the LLM to also reason about how
+     * the underlying tools/call envelopes flow.
      */
     aggressive: [...DEFAULT_PRESET_BODY, '', ACTION_ROUTING_PARAGRAPH].join('\n'),
     /**

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

@@ -1,59 +1,44 @@
 /**
  * LLM-backed `HandshakeNegotiator` for the OSS server.
  *
- * Composes BYOK credentials + a `ProviderAdapter` from
- * `@ggui-ai/ui-gen/providers` into an `LLMCaller`, then runs
- * `@ggui-ai/negotiator`'s `negotiate()` pipeline. Mirrors the cloud
- * `createBedrockNegotiator` pattern (cloud/ggui-protocol-pod/src/
- * tools/handshake.ts), stripped of Bedrock-specific embedding +
- * vector-store wiring — those are absent on OSS by default and
- * `negotiate()` handles missing RAG deps gracefully.
+ * A thin adapter over the SHARED handshake-decision core
+ * (`decideHandshake` in `@ggui-ai/mcp-server-handlers`). This file owns
+ * only this server's seams; the decision spine is shared verbatim
+ * across every negotiator binding of the server family — same code,
+ * different adapter.
  *
- * ## What this binding does
+ * ## OSS adapter seams
  *
- * On every `ggui_handshake` call:
+ *   - **LLM** — `buildLlmCaller` composes BYOK credentials + a
+ *     `ProviderAdapter` from `@ggui-ai/ui-gen/providers` into an
+ *     `LLMCaller` (anthropic / openai / google / openrouter / bedrock).
+ *     The adapter's `resolveLlm(ctx)` returns it, or `undefined` when no
+ *     creds resolve (⇒ the core returns a no-LLM `create` fallback).
+ *   - **Pools** — a single per-app blueprint pool from `deps.cache`
+ *     (scope defaults to `ctx.appId`). Absent ⇒ no pools ⇒ synth-only.
+ *   - **warn** — `console.warn` for swallowed operational errors.
  *
- *   1. Resolves BYOK creds via the supplied `resolveLlm(ctx)`. No
- *      creds → returns a "create" result with a `no-creds` reason.
- *   2. Selects the matching `ProviderAdapter` for the resolved
- *      provider (anthropic / openai / google / openrouter / bedrock).
- *   3. Wraps the adapter into an `LLMCaller` (single-shot text
- *      completion).
- *   4. Calls `negotiate(deps, input)` with `embedding: undefined,
- *      vectors: undefined` — RAG search is skipped, decision LLM
- *      runs against an empty candidate list, returns a sensible
- *      create/update decision based on session state + agent
- *      prompt.
- *   5. Maps the `NegotiateResult` onto the OSS-shape
- *      `HandshakeNegotiatorResult`.
+ * ## Shared decision spine (in the core, not here)
  *
- * ## Failure modes
+ *   find-similar across pools (exact-key → coverage guard → judge →
+ *   atomic reuse) ⇒ else synth-repair create via
+ *   `ensureConformingContract`. Operational errors fail open; programmer
+ *   errors re-throw. See `decide-handshake.ts` for the full contract.
  *
- * Operational errors (network flap, provider 5xx, rate limit) fail
- * open: returns a "create" result with the error reason. Bugs
- * (TypeError / ReferenceError / RangeError / SyntaxError) re-throw
- * — those are programmer errors that should surface, not be
- * silently swallowed.
+ * ## selectVariant
  *
- * ## Cost posture
- *
- * One LLM call per handshake (when creds resolve). Operators
- * concerned about cost can either (a) skip handshake and call
- * `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: ...}})`.
+ * The optional LLM-driven variant-selection seam is OSS-specific and
+ * stays on this binding (it is not part of the shared decide spine).
  *
  * ## Default binding
  *
- * Bound by default in `createGguiServer` when handshake is enabled
- * AND a `resolveLlm` is wired into `generation`. OSS is cloud-aligned:
- * same `negotiate()` pipeline, just with degraded RAG when local
- * infrastructure isn't bound.
+ * Bound by default in `createGguiServer` when handshake is enabled AND a
+ * `resolveLlm` is wired into `generation`.
  */
-import type { EmbeddingProvider, LlmSelection, ProviderKeyRef, VariantSelectionContext, VariantSelectionDecision, VectorStore } from "@ggui-ai/mcp-server-core";
+import type { BlueprintIndex, 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 BlueprintPool, type HandshakeNegotiator, type InstalledBlueprintsProvider, type ToolIdentityCatalogStore } 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
@@ -98,34 +83,22 @@ export interface LlmBackedHandshakeNegotiatorDeps {
         providerKey: ProviderKeyRef;
     } | null> | null;
     /**
-     * Estimated cold-generation latency, embedded on the "create"
-     * fallback result's `plan.estimatedLatencyMs`. Default 30s.
-     */
-    estimatedGenerationLatencyMs?: number;
-    /**
-     * Blueprint-registry deps for the handshake-time exact-key match
-     * fast path. When bound, every `decide()` call first asks
-     * `matchBlueprint` whether the agent's draft canonical-key-equals
-     * an already-registered blueprint. A hit short-circuits the synth
-     * LLM round-trip and returns `origin: 'cache'` with the cached
-     * blueprint's contract + codeHash.
-     *
-     * The exact-key strategy is the only safe match when a contract is
-     * supplied (see the fuzzy-match gate in `blueprint-matcher.ts` —
-     * fuzzy matches across non-equal canonical contracts let cached
-     * call sites drift from the request's actionSpec/contextSpec wire
-     * surface).
-     * Semantic strategy fires only when contract is omitted, which the
-     * handshake input schema today disallows.
+     * Blueprint-registry deps for the handshake-time find-similar match
+     * (exact-key → coverage guard → judge). When bound, the shared
+     * `decideHandshake` core probes this registry (as a single per-app
+     * pool) before the synth path: an exact-key or semantic hit
+     * short-circuits the synth LLM round-trip and returns `origin:
+     * 'cache'` with the matched blueprint's contract + codeHash.
      *
      * Optional so deployments without RAG infrastructure (no embedding
      * / vector store) continue to use the synth-only path. Mirrors the
-     * shape used by `push.ts:1539-1541` so a single
+     * shape used by the render handler (`render.ts`) so a single
      * `generationWithCache.cache` value threads into both seams.
      */
     cache?: {
         readonly embedding: EmbeddingProvider;
         readonly vectorStore: VectorStore;
+        readonly index: BlueprintIndex;
     };
     /**
      * Marketplace-install bridge. When wired alongside
@@ -136,13 +109,41 @@ export interface LlmBackedHandshakeNegotiatorDeps {
      * without a separate synth round-trip.
      */
     installedBlueprints?: InstalledBlueprintsProvider;
+    /**
+     * Per-app tool-identity catalog store (READ side). When wired, the
+     * shared `decideHandshake` core runs `canonicalizeToolIdentity`
+     * against `catalogStore.get(ctx.appId)` BEFORE keying — rewriting each
+     * tool's `serverInfo` to the canonical identity the host runtime
+     * declared via `ggui_runtime_declare_tool_catalog`, so blueprint reuse
+     * is framework-invariant. Absent ⇒ the canonicalization step is a
+     * no-op (Tier 2). The SAME instance the declaration handler writes.
+     */
+    catalogStore?: ToolIdentityCatalogStore;
+    /**
+     * Read-only shared/seed pools (cross-deployment reuse). Appended to
+     * adapter.pools AFTER the per-app pool, so a deployment's own
+     * blueprints win on exact-key first-match. Each is typically built by
+     * `buildSeedPool` from a distributable artifact. Absent ⇒ no shared pool.
+     */
+    readonly seedPools?: readonly BlueprintPool[];
 }
+/**
+ * Build the handshake pool list: the per-app pool (from `cache`) first —
+ * so a deployment's own blueprints win on exact-key first-match — then
+ * any read-only seed pools.
+ */
+export declare function assembleHandshakePools(deps: Pick<LlmBackedHandshakeNegotiatorDeps, 'cache' | 'installedBlueprints' | 'seedPools'>): BlueprintPool[];
 /**
  * Build an LLM-backed `HandshakeNegotiator` for the OSS server.
- * Wires BYOK creds + an LLM provider adapter into
- * `@ggui-ai/negotiator`'s `negotiate()` pipeline. Operators get the
- * same negotiation shape cloud uses, with RAG gracefully degraded
- * (no embedding / vectors required).
+ *
+ * Thin wrapper over the shared `decideHandshake` core
+ * (`@ggui-ai/mcp-server-handlers`): injects the OSS adapter — a BYOK
+ * LLM resolver (`resolveLlm` → `buildLlmCaller`) and a single per-app
+ * blueprint pool (`deps.cache`, scope defaults to `ctx.appId`). The
+ * decision spine (find-similar → coverage guard → judge → atomic
+ * reuse, else synth-repair create) is shared verbatim across every
+ * negotiator binding; only the injected adapter differs.
+ * `selectVariant` is specific to this binding.
  *
  * @public
  */
@@ -155,7 +156,7 @@ export declare function createLlmBackedHandshakeNegotiator(deps: LlmBackedHandsh
  * token budget on the user message (candidate JSON) is more useful
  * than verbose system framing.
  */
-export declare const VARIANT_SELECTION_SYSTEM_PROMPT = "You are the variant selector for the ggui UI matcher. You receive a shortlist of pre-built UI blueprint variants and a request context. Pick the variant that best fits the request.\n\nEach variant carries:\n  - blueprintId: stable identity (you MUST echo back exactly one of these).\n  - generator: which generator built it (e.g. \"ui-gen-default-haiku-4-5\", \"ui-gen-advanced-opus-4-7\"). Advanced wins on visual polish; default wins on simplicity.\n  - validatorScore: optional 0-1 self-assessed quality from the advanced generator's validators. Higher is better, undefined \u21D2 unknown.\n  - isOperatorDefault: true \u21D2 the human operator pinned this as the default. Strong signal.\n  - variance.persona: free-form tag (\"minimalist\", \"data-dense\", \"mobile-first\"\u2026).\n  - variance.aesthetic: optional free-form tag (\"glassy\", \"flat\", \"editorial\"\u2026).\n  - variance.context: small structured signal (theme, accent, \u2026).\n  - variance.seedPrompt: the operator's original prose that produced this variant.\n\nThe request context carries the same fields. Match on:\n  1. variance.persona equality / closeness (strongest non-pin signal).\n  2. variance.aesthetic equality / closeness.\n  3. variance.context overlap (shared keys + values).\n  4. seedPrompt semantic similarity to context.intent.\n\nHonor operator pins (isOperatorDefault: true) unless variance.persona / variance.aesthetic on the request clearly contradicts the pinned variant \u2014 that's the only case where you should override the pin.\n\nCalibrate confidence honestly. Return high (\u2265 0.7) only when a clear best match exists. Return low (< 0.6) when signals are weak \u2014 the orchestration falls back to a deterministic ladder in that case. The fallback is safe; over-confident picks are NOT.";
+export declare const VARIANT_SELECTION_SYSTEM_PROMPT = "You are the variant selector for the ggui UI matcher. You receive a shortlist of pre-built UI blueprint variants and a request context. Pick the variant that best fits the request.\n\nEach variant carries:\n  - blueprintId: stable identity (you MUST echo back exactly one of these).\n  - source: provenance. {kind:\"llm\", generator, model} = engine-generated (advanced generators win on visual polish; default generators win on simplicity). {kind:\"user\"} = operator-registered hand-authored code. {kind:\"curated\"} = catalog-shipped system blueprint.\n  - validatorScore: optional 0-1 self-assessed quality from the advanced generator's validators. Higher is better, undefined \u21D2 unknown.\n  - isOperatorDefault: true \u21D2 the human operator pinned this as the default. Strong signal.\n  - variance.persona: free-form tag (\"minimalist\", \"data-dense\", \"mobile-first\"\u2026).\n  - variance.aesthetic: optional free-form tag (\"glassy\", \"flat\", \"editorial\"\u2026).\n  - variance.context: small structured signal (theme, accent, \u2026).\n  - variance.seedPrompt: the operator's original prose that produced this variant.\n\nThe request context carries the same fields. Match on:\n  1. variance.persona equality / closeness (strongest non-pin signal).\n  2. variance.aesthetic equality / closeness.\n  3. variance.context overlap (shared keys + values).\n  4. seedPrompt semantic similarity to context.intent.\n\nHonor operator pins (isOperatorDefault: true) unless variance.persona / variance.aesthetic on the request clearly contradicts the pinned variant \u2014 that's the only case where you should override the pin.\n\nCalibrate confidence honestly. Return high (\u2265 0.7) only when a clear best match exists. Return low (< 0.6) when signals are weak \u2014 the orchestration falls back to a deterministic ladder in that case. The fallback is safe; over-confident picks are NOT.";
 /**
  * Build the user-message payload for the variant-selection prompt.
  * The candidate list is projected to a compact JSON shape that

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,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,EAA4B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EACV,SAAS,EAIV,MAAM,mBAAmB,CAAC;AAmB3B;;;;;;;;;;;;;;;;;;;;;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;AA6CD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,mBAAmB,CAiKrB;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"}
+{"version":3,"file":"llm-backed-negotiator.d.ts","sourceRoot":"","sources":["../src/llm-backed-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,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,EAEL,KAAK,aAAa,EAElB,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;QAClC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;KAChC,CAAC;IACF;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;IAClD;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,CAAC,gCAAgC,EAAE,OAAO,GAAG,qBAAqB,GAAG,WAAW,CAAC,GAC1F,aAAa,EAAE,CAQjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,mBAAmB,CA6DrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,m3DAoBgN,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"}