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

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

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ *
+ * ## What this binding does
+ *
+ * On every `ggui_handshake` call:
+ *
+ *   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`.
+ *
+ * ## Failure modes
+ *
+ * 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.
+ *
+ * ## Cost posture
+ *
+ * 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
+ * negotiator (e.g., the cache-backed one for read-only cache
+ * lookups) via `createGguiServer({handshake: {negotiator: ...}})`.
+ *
+ * ## 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.
+ */
+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';
+/**
+ * Wrap a resolved BYOK credential pair into an `LLMCaller` the
+ * negotiator can call. The adapter is chosen via `selectAdapter`
+ * (anthropic / openai / google / openrouter / bedrock). `call` runs
+ * one `complete()` round-trip on the underlying adapter.
+ *
+ * `callStructured` is wired for Anthropic only. Anthropic's
+ * `/v1/messages` natively supports forced tool use via `tools[] +
+ * tool_choice: {type:'tool', name}`, so we hit the API directly here
+ * instead of expanding the `ProviderAdapter` interface for one
+ * provider. Other providers (OpenAI, Google, OpenRouter, Bedrock)
+ * omit `callStructured`; consumers detect absence and fall back to
+ * regex-JSON extraction on the text path. When this story shifts —
+ * e.g., we want OpenAI tool use too — promote `completeWithTool`
+ * onto `ProviderAdapter` as an optional method and wire each
+ * adapter; this in-place implementation stays the bridge until then.
+ *
+ * Used by:
+ *   - `@ggui-ai/negotiator/llm-rerank` (Tier 2 RAG match judge)
+ *   - `@ggui-ai/negotiator/synthesize-contract` (cold-path contract
+ *     synthesizer)
+ */
+export declare function buildLlmCaller(selection: LlmSelection, providerKey: ProviderKeyRef): LLMCaller;
+/**
+ * Dependencies for `createLlmBackedHandshakeNegotiator`. Only
+ * `resolveLlm` is required; the rest carry default fallbacks.
+ */
+export interface LlmBackedHandshakeNegotiatorDeps {
+    /**
+     * Per-call BYOK resolver. Returns `null` when no creds are
+     * available — the negotiator falls back to a "create" result with
+     * a clear reason rather than failing the handshake. Sync-or-async
+     * to match `GenerationDeps.resolveLlm`'s wider shape (in-process
+     * dispatchers can return synchronously).
+     */
+    resolveLlm: (ctx: HandlerContext) => {
+        selection: LlmSelection;
+        providerKey: ProviderKeyRef;
+    } | Promise<{
+        selection: LlmSelection;
+        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.
+     *
+     * 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
+     * `generationWithCache.cache` value threads into both seams.
+     */
+    cache?: {
+        readonly embedding: EmbeddingProvider;
+        readonly vectorStore: VectorStore;
+    };
+    /**
+     * Marketplace-install bridge. When wired alongside
+     * `cache`, handshake-time exact-key matches consult the installed-
+     * blueprint pool too — the provider lazily compiles + caches each
+     * installed blueprint on first ensureCached per scope, so the same
+     * canonical key the agent draft hashes to becomes a cache hit
+     * without a separate synth round-trip.
+     */
+    installedBlueprints?: InstalledBlueprintsProvider;
+}
+/**
+ * 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).
+ *
+ * @public
+ */
+export declare function createLlmBackedHandshakeNegotiator(deps: LlmBackedHandshakeNegotiatorDeps): HandshakeNegotiator;
+/**
+ * The system prompt for the variant-selection LLM call. Calibration
+ * is load-bearing — the model is explicitly told to surface low
+ * confidence when signals are weak so the deterministic-ladder
+ * fallback takes over. The prompt is intentionally short: high
+ * 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.";
+/**
+ * Build the user-message payload for the variant-selection prompt.
+ * The candidate list is projected to a compact JSON shape that
+ * surfaces the decision-relevant fields only — full contract
+ * embedding is too much surface area for a sub-second pick.
+ *
+ * Exposed for testing — the prompt structure is load-bearing, so
+ * snapshot tests against this output anchor regressions.
+ */
+export declare function buildVariantSelectionUserMessage(candidates: readonly Blueprint[], context: VariantSelectionContext): string;
+/**
+ * Parse + validate the LLM-tool-use response shape. Exposed for
+ * testing; in production it is only called via `runVariantSelectionLlm`.
+ *
+ * @throws Error on any shape violation. The caller catches and falls
+ *   through to the deterministic ladder; the message is surfaced in
+ *   `VariantSelectionResult.reason` for telemetry.
+ */
+export declare function parseVariantSelectionResponse(raw: unknown): VariantSelectionDecision;
+//# sourceMappingURL=llm-backed-negotiator.d.ts.map

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

@@ -0,0 +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"}