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

package/dist/llm-backed-negotiator.js

@@ -1,78 +1,43 @@
 /**
  * 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 { DEFAULT_GENERATOR_SLUG, matchBlueprint, } from "@ggui-ai/mcp-server-handlers/renders";
-import { ensureConformingContract } from "@ggui-ai/negotiator";
-import { dataContractSchema, lintContract } from "@ggui-ai/protocol";
-import { blueprintKey } from "@ggui-ai/protocol/blueprint-key";
+import { decideHandshake, } from "@ggui-ai/mcp-server-handlers/renders";
+import { isRecord } from "@ggui-ai/protocol";
 import { selectAdapter } from "@ggui-ai/ui-gen/providers";
-import { createHash, randomUUID } from "node:crypto";
-/**
- * Operational error classifier — mirrors the cloud helper. Bugs
- * surface; provider failures + network blips degrade to a "create"
- * stub so the agent isn't blocked by a transient infrastructure
- * issue.
- */
-function isOperationalError(err) {
-    if (err instanceof TypeError)
-        return false;
-    if (err instanceof ReferenceError)
-        return false;
-    if (err instanceof RangeError)
-        return false;
-    if (err instanceof SyntaxError)
-        return false;
-    return true;
-}
 /**
  * Wrap a resolved BYOK credential pair into an `LLMCaller` the
  * negotiator can call. The adapter is chosen via `selectAdapter`
@@ -195,174 +160,70 @@ async function anthropicCallStructured(args) {
     }
     return toolUse.input;
 }
-const DEFAULT_GEN_LATENCY_MS = 30_000;
-function buildCreateFallback(draftContract, reason, _estimatedLatencyMs) {
-    // No-LLM fallback (no BYOK creds, or an operational error during synth).
-    // The handshake backstop (validateContract) THROWS on a malformed draft,
-    // and there is no LLM here to repair it — so deterministically
-    // substitute the trivially-conforming empty contract (+ loud findings)
-    // when the draft fails the gate. NEVER return a raw malformed draft into
-    // the throwing backstop (that would revive the handshake-retry loop).
-    // A clean draft is kept verbatim (origin: agent).
-    const lint = lintContract(draftContract);
-    const contract = lint.errors.length === 0 ? dataContractSchema.parse(draftContract) : {};
-    const findings = lint.errors.map((e) => ({
-        code: e.code,
-        severity: "error",
-        path: e.path,
-        message: e.message,
-    }));
-    const contractHash = blueprintKey(contract);
-    const suggestion = {
-        origin: "agent",
-        rationale: reason,
-        blueprintMeta: {
-            blueprintId: `bp_${randomUUID()}`,
-            contractHash,
-            generator: "ui-gen-default-haiku-4-5",
-            variance: {},
-        },
-        ...(findings.length > 0 ? { validationFindings: findings } : {}),
-    };
-    return {
-        action: "create",
-        reason,
-        suggestion,
-        effectiveContract: contract,
-    };
+/**
+ * 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 function assembleHandshakePools(deps) {
+    const perAppPool = deps.cache
+        ? {
+            registry: deps.cache,
+            ...(deps.installedBlueprints ? { installedBlueprints: deps.installedBlueprints } : {}),
+        }
+        : undefined;
+    return [...(perAppPool ? [perAppPool] : []), ...(deps.seedPools ?? [])];
 }
 /**
  * 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
  */
 export function createLlmBackedHandshakeNegotiator(deps) {
-    const estimatedLatencyMs = deps.estimatedGenerationLatencyMs ?? DEFAULT_GEN_LATENCY_MS;
-    return {
-        async decide({ intent, blueprintDraft, gadgets, ctx }) {
-            const draftContract = blueprintDraft.contract;
-            // Handshake-time exact-key fast path. Runs BEFORE the BYOK
-            // creds resolve + LLM synth — a cache hit needs neither the
-            // operator's API key nor a model round-trip. When the agent's
-            // draft canonical-key-equals a registered blueprint, return
-            // `origin: 'cache'` with the matched blueprint's contract +
-            // componentCode hash so the paired push.accept short-circuits
-            // straight into commitCachedRender.
-            //
-            // No-match (or any throw) falls through to today's synth path
-            // — the negotiator stays useful when the registry is cold,
-            // when matchBlueprint hiccups, or when the deployment skipped
-            // the cache deps entirely.
-            // Cache match needs a SHAPE-VALID contract — a malformed draft
-            // (wrapper-nesting, bad type spelling, …) can't canonical-key-match
-            // a registered blueprint, so skip the probe and fall straight to
-            // validate/repair via ensureConformingContract.
-            const parsedDraft = dataContractSchema.safeParse(draftContract);
-            if (deps.cache && parsedDraft.success) {
-                try {
-                    const matchDeps = {
-                        registry: deps.cache,
-                        ...(deps.installedBlueprints ? { installedBlueprints: deps.installedBlueprints } : {}),
-                    };
-                    const matchResult = await matchBlueprint(matchDeps, ctx.appId, {
-                        intent,
-                        contract: parsedDraft.data,
-                    });
-                    if (matchResult.strategy === "exact-key") {
-                        const matched = matchResult.blueprint;
-                        const codeHash = createHash("sha256").update(matched.componentCode).digest("hex");
-                        const suggestion = {
-                            origin: "cache",
-                            rationale: matchResult.reason,
-                            blueprintMeta: {
-                                blueprintId: matched.id,
-                                contractHash: matched.contractKey,
-                                codeHash,
-                                generator: DEFAULT_GENERATOR_SLUG,
-                                variance: {},
-                                selectedReason: matchResult.reason,
-                            },
-                        };
-                        return {
-                            action: "reuse",
-                            reason: matchResult.reason,
-                            suggestion,
-                            effectiveContract: matched.contract,
-                        };
-                    }
-                    // Other strategies (no-match, semantic) fall through to
-                    // the negotiate() path below. Semantic doesn't fire when
-                    // a contract is supplied (the fuzzy-match gate blocks it);
-                    // listing it here is structural completeness, not a
-                    // reachable branch today.
-                }
-                catch (err) {
-                    if (!isOperationalError(err))
-                        throw err;
-                    // Registry hiccup — log + fall through to synth so the
-                    // handshake never crashes on a transient cache backend
-                    // issue.
-                    const message = err instanceof Error ? err.message : String(err);
-                    // eslint-disable-next-line no-console -- operator-visible signal
-                    console.warn(`[llm-backed-negotiator] matchBlueprint exact-key probe failed; falling through to synth: ${message}`);
-                }
-            }
+    // Capture the store so the adapter resolver closes over a concrete
+    // value (no `?.` chain inside the hot path; the spread below already
+    // gates on presence).
+    const catalogStore = deps.catalogStore;
+    const pools = assembleHandshakePools(deps);
+    const adapter = {
+        // BYOK seam: resolve per-ctx creds + wrap into an LLMCaller. No
+        // creds ⇒ undefined ⇒ the core returns a no-LLM create fallback.
+        resolveLlm: async (ctx) => {
             const creds = await deps.resolveLlm(ctx);
-            if (!creds) {
-                return buildCreateFallback(draftContract, "no-creds: no BYOK credentials resolved for the configured provider; ggui_render will surface the same error and the handshake stays a no-op create.", estimatedLatencyMs);
-            }
-            try {
-                const llm = buildLlmCaller(creds.selection, creds.providerKey);
-                // Create path (no cache hit): the agent's DRAFT is the basis.
-                // ensureConformingContract validates it against the deterministic
-                // gate (lintContract / validateContract) and, on errors, repairs
-                // it in place via the bounded LLM loop — GUARANTEEING a contract
-                // that passes the handshake backstop, so the handshake never
-                // hard-fails on a malformed draft. origin: 'agent' = draft was
-                // already clean; 'synth' = repaired (or minimal-conforming
-                // fallback when unrepairable).
-                const conforming = await ensureConformingContract({ llm }, {
-                    intent,
-                    draft: draftContract,
-                    ...(gadgets !== undefined ? { appGadgets: gadgets } : {}),
-                });
-                const contractHash = blueprintKey(conforming.contract);
-                const suggestion = {
-                    origin: conforming.origin,
-                    rationale: conforming.reasoning,
-                    blueprintMeta: {
-                        blueprintId: `bp_${randomUUID()}`,
-                        contractHash,
-                        generator: "ui-gen-default-haiku-4-5",
-                        variance: {},
-                    },
-                    ...(conforming.findings.length > 0
-                        ? { validationFindings: conforming.findings }
-                        : {}),
-                };
-                return {
-                    action: "create",
-                    reason: conforming.reasoning,
-                    suggestion,
-                    effectiveContract: conforming.contract,
-                };
-            }
-            catch (err) {
-                if (!isOperationalError(err))
-                    throw err;
-                const message = err instanceof Error ? err.message : String(err);
-                const errorClass = err instanceof Error ? err.name : "unknown";
-                return buildCreateFallback(draftContract, `negotiator-degraded: ${errorClass} during decision LLM call — ${message}. Falling back to bare-create; the paired ggui_render will still generate the UI.`, estimatedLatencyMs);
-            }
+            return creds
+                ? buildLlmCaller(creds.selection, creds.providerKey)
+                : undefined;
+        },
+        // Per-app pool first, then seed pools. No pools ⇒ the core takes
+        // the synth-only path.
+        ...(pools.length > 0 ? { pools } : {}),
+        warn: (message) => {
+            // eslint-disable-next-line no-console -- operator-visible signal
+            console.warn(message);
         },
+        // READ side of tool-identity canonicalization. When a catalog store
+        // is wired, the core resolves the per-app catalog by ctx.appId and
+        // runs canonicalizeToolIdentity before keying. Absent ⇒ the seam is
+        // a no-op (Tier 2).
+        ...(catalogStore
+            ? { toolIdentityCatalog: (ctx) => catalogStore.get(ctx.appId) }
+            : {}),
+    };
+    return {
+        decide: (input) => decideHandshake(adapter, input),
         // LLM-driven variant selection. Reads each candidate's
         // `variance` + `validatorScore` + `isOperatorDefault` + the
-        // generator slug, asks the LLM to pick the best fit for the
-        // current request's `intent` + `variance`, and returns a
+        // provenance (`source`), asks the LLM to pick the best fit for
+        // the current request's `intent` + `variance`, and returns a
         // calibrated decision. The caller (`selectVariantWithLlm`)
         // thresholds on `confidence`.
         //
@@ -395,7 +256,7 @@ export const VARIANT_SELECTION_SYSTEM_PROMPT = `You are the variant selector for
 
 Each variant carries:
   - blueprintId: stable identity (you MUST echo back exactly one of these).
-  - 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.
+  - 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.
   - validatorScore: optional 0-1 self-assessed quality from the advanced generator's validators. Higher is better, undefined ⇒ unknown.
   - isOperatorDefault: true ⇒ the human operator pinned this as the default. Strong signal.
   - variance.persona: free-form tag ("minimalist", "data-dense", "mobile-first"…).
@@ -452,7 +313,7 @@ const VARIANT_SELECTION_TOOL_SCHEMA = {
 export function buildVariantSelectionUserMessage(candidates, context) {
     const projectedCandidates = candidates.map((c) => ({
         blueprintId: c.blueprintId,
-        generator: c.generator,
+        source: c.source,
         ...(c.validatorScore !== undefined ? { validatorScore: c.validatorScore } : {}),
         ...(c.isOperatorDefault === true ? { isOperatorDefault: true } : {}),
         variance: {
@@ -530,7 +391,7 @@ async function runVariantSelectionLlm(llm, candidates, context) {
  *   `VariantSelectionResult.reason` for telemetry.
  */
 export function parseVariantSelectionResponse(raw) {
-    if (raw === null || typeof raw !== "object") {
+    if (!isRecord(raw)) {
         throw new Error("variant-selection: response is not an object");
     }
     const obj = raw;