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

package/README.md

@@ -1,11 +1,19 @@
 # @ggui-ai/negotiator
 
-UI decision engine for [ggui](https://github.com/ggui-ai/ggui).
+Contract-synthesis + match-judge engine for
+[ggui](https://github.com/ggui-ai/ggui)'s handshake.
 
-Given an agent's signal (data, prompt, context, agent tools) and the current
-render state, the negotiator decides **which UI to render** — create a new
-interface, update an existing one, or replace it — and, on the cold path,
-synthesizes the data contract that drives it.
+Given an agent's draft contract + intent, this package synthesizes (or
+repairs) a conforming `DataContract`, judges blueprint-match candidates for
+reuse, and validates contract structure + novelty — the primitives the
+handshake composes to always return a valid contract.
+
+> The handshake **decision** itself (find-similar → reuse vs synth-create)
+> lives in the shared `decideHandshake` core in
+> [`@ggui-ai/mcp-server-handlers`](../mcp-server-handlers), which composes
+> the primitives below. The former in-package `negotiate()` RAG+decision
+> pipeline was retired in favor of that unified, adapter-injected core —
+> one decision spine; LLM and storage bindings plug in per deployment.
 
 The package is deployment-agnostic. It composes the storage interfaces
 defined in `@ggui-ai/mcp-server-core` (`EmbeddingProvider`, `VectorStore`),
@@ -20,28 +28,26 @@ pnpm add @ggui-ai/negotiator
 
 ## What's in the box
 
-- **`negotiate(deps, input)`** — top-level orchestrator. Runs RAG search over
-  registered blueprints, reads render state, fast-paths exact blueprint
-  hits, and otherwise calls the decision LLM.
-- **`makeDecision(...)`** — the decision step in isolation: pick an action
-  (`create` / `update` / `replace`) and a blueprint from the
-  candidate set.
 - **`synthesizeContract(...)`** — cold-path contract synthesizer. Turns an
   agent intent into a `DataContract` (props / context / action / stream
   specs, plus gadget references), with a repair loop and a schema-validation
   gate.
-- **`ragSearch(...)`** — embedding + vector-store retrieval over the
-  blueprint corpus, composing the `@ggui-ai/mcp-server-core` interfaces.
-- **`rerankCandidates(...)`** — LLM re-rank of retrieval candidates.
-- **`validateContractStructure` / `validateContractNovelty`** — advisory
+- **`ensureConformingContract(...)`** — the create-path guarantee: validates
+  an untrusted draft and, on errors, deterministically normalizes or
+  LLM-repairs it so the handshake always returns a contract that passes the
+  backstop. Never throws.
+- **`rerankCandidates(...)`** — LLM judge that re-ranks blueprint-match
+  retrieval candidates (the semantic-match decision used by
+  `decideHandshake`).
+- **`validateContractRedundancy` / `validateContractNovelty`** — advisory
   validators for the actions-vs-context placement rule.
 
 ```ts
-import { negotiate } from "@ggui-ai/negotiator";
+import { ensureConformingContract } from "@ggui-ai/negotiator";
 
-const result = await negotiate(deps, input);
-// result.action — "create" | "update" | "replace"
-// result.blueprint — the picked blueprint, if any
+const result = await ensureConformingContract({ llm }, { intent, draft });
+// result.origin — "agent" (clean) | "synth" (repaired)
+// result.contract — a DataContract guaranteed to pass the handshake backstop
 ```
 
 ## License

package/dist/contract-validators.d.ts

@@ -3,9 +3,12 @@
  *
  * Two detectors live here:
  *
- *   - {@link validateContractStructure} — pure structural heuristics that
- *     flag over-specified contracts without any runtime dependency. The
- *     load-bearing finding is `redundant-action`: an empty-payload
+ *   - {@link validateContractRedundancy} — pure redundancy heuristics that
+ *     flag over-specified contracts without any runtime dependency.
+ *     (Deliberately NOT named `validateContractStructure` — that name is
+ *     owned by `@ggui-ai/protocol`'s normative structural validator,
+ *     which returns `ContractViolation`s; this one returns advisory
+ *     findings.) The load-bearing finding is `redundant-action`: an empty-payload
  *     `actionSpec` entry whose name parses as a mutator of an existing
  *     `contextSpec` slot. Real example that motivated this module: a
  *     synthesizer emitted both `actionSpec.increment` (empty payload)
@@ -59,39 +62,40 @@ export interface ContractValidationResult {
 }
 /**
  * Dependencies the novelty detector needs. Embedding provider + vector
- * store are the same seams the negotiator's RAG path uses, so the
- * novelty check operates over the production index without any extra
- * infrastructure.
+ * store are the same seams the handshake's find-similar retrieval uses,
+ * so the novelty check operates over the production index without any
+ * extra infrastructure.
  */
 export interface ContractValidationNoveltyDeps {
     readonly embedding: EmbeddingProvider;
     readonly vectorStore: VectorStore;
     /** Tenant / partition the nearest-neighbor query runs against. Same
-     * semantics as `RagSearchInput.scope`. */
+     * semantics as the `scope` argument on `VectorStore.query` — the
+     * tenant / index partition, typically `appId`. */
     readonly scope: string;
 }
 export interface ContractValidationNoveltyOptions {
     /**
      * Cosine distance threshold above which the contract is flagged as
-     * novel. Distance is `1 - cosine_similarity`. Default `0.8` —
-     * matches the negotiator's `RETRIEVAL_MIN_SCORE = 0.15` (=cosine
-     * similarity 0.15, distance 0.85) one-tail boundary, with a small
-     * buffer so contracts that hover near retrieval but slightly above
-     * still flag for review.
+     * novel. Distance is `1 - cosine_similarity`. Default `0.8`: a
+     * contract whose nearest stored neighbor sits beyond distance 0.8
+     * is effectively outside retrieval range, with a small buffer below
+     * the hard one-tail boundary (distance 0.85) so contracts that
+     * hover near retrieval but slightly above still flag for review.
      */
     readonly thresholdCosine?: number;
 }
 /**
- * Run the synchronous structural detectors against `contract`.
+ * Run the synchronous redundancy detector against `contract`.
  *
- * Currently:
+ * One finding kind:
  *   - `redundant-action`: empty-payload action whose name parses as a
  *     mutator of an existing context slot.
  *
- * Returns an empty findings array for contracts that don't trip any
+ * Returns an empty findings array for contracts that don't trip the
  * heuristic.
  */
-export declare function validateContractStructure(contract: DataContract): ContractValidationResult;
+export declare function validateContractRedundancy(contract: DataContract): ContractValidationResult;
 /**
  * Validate the actions-vs-context placement rule: actions drive agent
  * turns, context observes state. Findings 1-3 are advisory `warn`;

package/dist/contract-validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-validators.d.ts","sourceRoot":"","sources":["../src/contract-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,GACrC,kBAAkB,GAClB,aAAa,GACb,mCAAmC,GACnC,2BAA2B,GAC3B,6BAA6B,GAC7B,4BAA4B,GAC5B,8BAA8B,GAC9B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;8CAC0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAwJD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CAkC1B;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CA8D1B;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb,wBAAwB,CAoC1B;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,6BAA6B,EACnC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,wBAAwB,CAAC,CAkCnC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAKR"}
+{"version":3,"file":"contract-validators.d.ts","sourceRoot":"","sources":["../src/contract-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,GACrC,kBAAkB,GAClB,aAAa,GACb,mCAAmC,GACnC,2BAA2B,GAC3B,6BAA6B,GAC7B,4BAA4B,GAC5B,8BAA8B,GAC9B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;sDAEkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAwJD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CAkC1B;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CA8D1B;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb,wBAAwB,CAoC1B;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,6BAA6B,EACnC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,wBAAwB,CAAC,CAkCnC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAKR"}

package/dist/contract-validators.js

@@ -3,9 +3,12 @@
  *
  * Two detectors live here:
  *
- *   - {@link validateContractStructure} — pure structural heuristics that
- *     flag over-specified contracts without any runtime dependency. The
- *     load-bearing finding is `redundant-action`: an empty-payload
+ *   - {@link validateContractRedundancy} — pure redundancy heuristics that
+ *     flag over-specified contracts without any runtime dependency.
+ *     (Deliberately NOT named `validateContractStructure` — that name is
+ *     owned by `@ggui-ai/protocol`'s normative structural validator,
+ *     which returns `ContractViolation`s; this one returns advisory
+ *     findings.) The load-bearing finding is `redundant-action`: an empty-payload
  *     `actionSpec` entry whose name parses as a mutator of an existing
  *     `contextSpec` slot. Real example that motivated this module: a
  *     synthesizer emitted both `actionSpec.increment` (empty payload)
@@ -167,19 +170,19 @@ function isEmptyPayloadSchema(schema) {
     return Object.keys(schema.properties).length === 0;
 }
 // =============================================================================
-// Structural validator (synchronous, dependency-free)
+// Redundancy validator (synchronous, dependency-free)
 // =============================================================================
 /**
- * Run the synchronous structural detectors against `contract`.
+ * Run the synchronous redundancy detector against `contract`.
  *
- * Currently:
+ * One finding kind:
  *   - `redundant-action`: empty-payload action whose name parses as a
  *     mutator of an existing context slot.
  *
- * Returns an empty findings array for contracts that don't trip any
+ * Returns an empty findings array for contracts that don't trip the
  * heuristic.
  */
-export function validateContractStructure(contract) {
+export function validateContractRedundancy(contract) {
     const findings = [];
     const actionSpec = contract.actionSpec;
     const contextSpec = contract.contextSpec;

package/dist/index.d.ts

@@ -1,38 +1,38 @@
 /**
- * @ggui-ai/negotiator — open-source UI decision engine for ggui.
+ * @ggui-ai/negotiator — open-source contract-synthesis + match-judge
+ * engine for ggui's handshake.
  *
- * Decides which UI to render (create/update/replace) given agent
- * signal (data/prompt/context/agentTools) and current render state.
+ * Given an agent's draft contract + intent, this package:
+ *   - synthesizes / repairs a conforming `DataContract`
+ *     (`synthesizeContract`, `ensureConformingContract`) so the
+ *     handshake always returns a valid contract;
+ *   - judges blueprint-match candidates for reuse (`rerankCandidates`);
+ *   - validates contract structure + novelty (`contract-validators`);
+ *   - hashes contracts into identity + variant keys (`hashContract`,
+ *     `buildVariant`) and normalizes untrusted drafts (`normalizeDraft`).
+ *
+ * The HANDSHAKE DECISION itself (find-similar → reuse vs synth-create)
+ * lives in the shared `decideHandshake` core in
+ * `@ggui-ai/mcp-server-handlers`, which composes these primitives; the
+ * former in-package `negotiate()` RAG+decision pipeline was retired in
+ * favor of that unified, adapter-injected core.
  *
  * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
- * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
- * semantics are open here; concrete cloud-vendor bindings (e.g. a
- * managed embedding service or vector store) live behind those seams
- * so this package stays deployment-agnostic.
+ * (`EmbeddingProvider`, `VectorStore`) so this package stays
+ * deployment-agnostic.
  *
  * This barrel stays narrow — it exports only the minimum surface
  * consumers need. Each additive export carries semver weight.
  */
 export { hashContract, buildVariant } from './contract-hash.js';
-export { computeIntentId, shouldSuppressSuggestion } from './intent.js';
-export { detectDataPatterns, buildSuggestion } from './suggestion.js';
-export type { NegotiatorSuggestion } from './suggestion.js';
-export { inferInteractionMode, inferJsonSchemaType } from './pure.js';
-export { ragSearch } from './rag-search.js';
-export type { RagSearchDeps, RagSearchInput, RagSearchResult, } from './rag-search.js';
-export type { NegotiatorOption } from './types.js';
 export type { LLMCaller, LLMCallerConfig, ToolSchema } from './llm-caller.js';
-export type { RenderState, RenderEntry } from './render.js';
-export type { NegotiatorDecisionInput } from './decision-input.js';
-export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
-export { negotiate } from './negotiate.js';
-export type { NegotiateDeps, NegotiateInput, NegotiateConfig, NegotiateResult, } from './negotiate.js';
 export { rerankCandidates } from './llm-rerank.js';
 export type { RerankCandidate, RerankDecision, RerankQuery, } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
 export type { SynthesizeContractResult } from './synthesize-contract.js';
 export { ensureConformingContract } from './ensure-conforming-contract.js';
 export type { EnsureConformingResult } from './ensure-conforming-contract.js';
-export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
+export { normalizeDraft } from './normalize-draft.js';
+export { validateContractRedundancy, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
 export type { ContractValidationFinding, ContractValidationFindingKind, ContractValidationResult, ContractValidationNoveltyDeps, ContractValidationNoveltyOptions, } from './contract-validators.js';
 //# 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":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,26 +1,32 @@
 /**
- * @ggui-ai/negotiator — open-source UI decision engine for ggui.
+ * @ggui-ai/negotiator — open-source contract-synthesis + match-judge
+ * engine for ggui's handshake.
  *
- * Decides which UI to render (create/update/replace) given agent
- * signal (data/prompt/context/agentTools) and current render state.
+ * Given an agent's draft contract + intent, this package:
+ *   - synthesizes / repairs a conforming `DataContract`
+ *     (`synthesizeContract`, `ensureConformingContract`) so the
+ *     handshake always returns a valid contract;
+ *   - judges blueprint-match candidates for reuse (`rerankCandidates`);
+ *   - validates contract structure + novelty (`contract-validators`);
+ *   - hashes contracts into identity + variant keys (`hashContract`,
+ *     `buildVariant`) and normalizes untrusted drafts (`normalizeDraft`).
+ *
+ * The HANDSHAKE DECISION itself (find-similar → reuse vs synth-create)
+ * lives in the shared `decideHandshake` core in
+ * `@ggui-ai/mcp-server-handlers`, which composes these primitives; the
+ * former in-package `negotiate()` RAG+decision pipeline was retired in
+ * favor of that unified, adapter-injected core.
  *
  * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
- * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
- * semantics are open here; concrete cloud-vendor bindings (e.g. a
- * managed embedding service or vector store) live behind those seams
- * so this package stays deployment-agnostic.
+ * (`EmbeddingProvider`, `VectorStore`) so this package stays
+ * deployment-agnostic.
  *
  * This barrel stays narrow — it exports only the minimum surface
  * consumers need. Each additive export carries semver weight.
  */
 export { hashContract, buildVariant } from './contract-hash.js';
-export { computeIntentId, shouldSuppressSuggestion } from './intent.js';
-export { detectDataPatterns, buildSuggestion } from './suggestion.js';
-export { inferInteractionMode, inferJsonSchemaType } from './pure.js';
-export { ragSearch } from './rag-search.js';
-export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
-export { negotiate } from './negotiate.js';
 export { rerankCandidates } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
 export { ensureConformingContract } from './ensure-conforming-contract.js';
-export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
+export { normalizeDraft } from './normalize-draft.js';
+export { validateContractRedundancy, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';

package/dist/llm-caller.d.ts

@@ -1,23 +1,23 @@
 /**
- * `LLMCaller` — the decision engine's LLM dispatcher.
+ * `LLMCaller` — the negotiator's LLM dispatcher.
  *
  * Narrow abstraction over "call a chat model, optionally with a forced
  * tool-use schema for guaranteed-JSON structured output." Kept public
  * so OSS consumers of `@ggui-ai/negotiator` can bring their own LLM
  * provider (Anthropic direct, OpenAI, Google, a local model, a
- * community LiteLLM wrapper) without touching the decision-engine
+ * community LiteLLM wrapper) without touching the synthesis / judge
  * source.
  *
  * **Why this lives in `@ggui-ai/negotiator`, not
  * `@ggui-ai/mcp-server-core`.** `mcp-server-core` contains the
  * storage + runtime seams an MCP server implementer binds against
  * (`VectorStore`, `EmbeddingProvider`, `KeyValueStore`,
- * `BlueprintProvider`, `Negotiator`). `LLMCaller` is an
- * engine-internal dispatcher — one level below `Negotiator` — so
- * lifting it to `mcp-server-core` would grow the public seam count
- * speculatively. If a second consumer outside the negotiator
- * surfaces later, the "where does `LLMCaller` live?" question can be
- * re-opened at that point.
+ * `BlueprintProvider`). `LLMCaller` is an engine-internal
+ * dispatcher — one level below the synthesis + judge primitives this
+ * package exports — so lifting it to `mcp-server-core` would grow the
+ * public seam count speculatively. If a second consumer outside the
+ * negotiator surfaces later, the "where does `LLMCaller` live?"
+ * question can be re-opened at that point.
  *
  * Normative semantics:
  * - `call(systemPrompt, userMessage, maxTokens?)` returns the raw
@@ -41,7 +41,7 @@ export interface ToolSchema {
     description: string;
     input_schema: Record<string, unknown>;
 }
-/** Chat-model dispatcher consumed by the negotiator decision engine. */
+/** Chat-model dispatcher consumed by the negotiator's synthesis + judge primitives. */
 export interface LLMCaller {
     /**
      * Call the model in plain-text mode. `maxTokens` defaults to

package/dist/llm-caller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../src/llm-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../src/llm-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/llm-caller.js

@@ -1,23 +1,23 @@
 /**
- * `LLMCaller` — the decision engine's LLM dispatcher.
+ * `LLMCaller` — the negotiator's LLM dispatcher.
  *
  * Narrow abstraction over "call a chat model, optionally with a forced
  * tool-use schema for guaranteed-JSON structured output." Kept public
  * so OSS consumers of `@ggui-ai/negotiator` can bring their own LLM
  * provider (Anthropic direct, OpenAI, Google, a local model, a
- * community LiteLLM wrapper) without touching the decision-engine
+ * community LiteLLM wrapper) without touching the synthesis / judge
  * source.
  *
  * **Why this lives in `@ggui-ai/negotiator`, not
  * `@ggui-ai/mcp-server-core`.** `mcp-server-core` contains the
  * storage + runtime seams an MCP server implementer binds against
  * (`VectorStore`, `EmbeddingProvider`, `KeyValueStore`,
- * `BlueprintProvider`, `Negotiator`). `LLMCaller` is an
- * engine-internal dispatcher — one level below `Negotiator` — so
- * lifting it to `mcp-server-core` would grow the public seam count
- * speculatively. If a second consumer outside the negotiator
- * surfaces later, the "where does `LLMCaller` live?" question can be
- * re-opened at that point.
+ * `BlueprintProvider`). `LLMCaller` is an engine-internal
+ * dispatcher — one level below the synthesis + judge primitives this
+ * package exports — so lifting it to `mcp-server-core` would grow the
+ * public seam count speculatively. If a second consumer outside the
+ * negotiator surfaces later, the "where does `LLMCaller` live?"
+ * question can be re-opened at that point.
  *
  * Normative semantics:
  * - `call(systemPrompt, userMessage, maxTokens?)` returns the raw

package/dist/llm-rerank.d.ts

@@ -12,7 +12,6 @@
  * judge restores precision. Combined break-even hit rate is ~10%;
  * realistic workloads observe 30-70%.
  */
-import { summarizeContract } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 /**
  * One candidate blueprint for the LLM judge to consider.
@@ -28,7 +27,7 @@ export interface RerankCandidate {
     readonly cachedIntent: string;
     /**
      * One-line summary of the blueprint's contract surface. Format
-     * matches `summarizeContract()` below — `slots=...; actions=...;
+     * matches `@ggui-ai/protocol`'s `summarizeContract()` — `slots=...; actions=...;
      * streams=...; props=...` so the judge sees the structural shape
      * without the JSON noise.
      */
@@ -49,10 +48,13 @@ export interface RerankDecision {
      */
     readonly matchId: string | null;
     /**
-     * Confidence on `[0, 1]`. Caller compares against a threshold (e.g.
-     * 0.6) before treating the decision as a hit. Returned even when
-     * matchId is null so callers can log "judge declined with
-     * confidence X."
+     * Confidence on `[0, 1]` — how strongly the matched candidate is in
+     * the same task-and-shape family as the request, NOT how completely
+     * its fields cover the request. Field/slot/action deltas are
+     * reconciled and reported to the agent separately; they never lower
+     * this score. Caller compares against a threshold (e.g. 0.6) before
+     * treating the decision as a hit. Returned even when matchId is null
+     * so callers can log "judge declined with confidence X."
      */
     readonly confidence: number;
     /**
@@ -79,9 +81,8 @@ export interface RerankQuery {
     readonly intent: string;
     readonly contractSummary: string;
 }
-declare const RERANK_SYSTEM_PROMPT = "You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate produces the SAME USEFUL UI for the current request.\n\nMATCH means the candidate would correctly satisfy the user's current request \u2014 same UI shape (component types, layout pattern), same wire surface (slot names, action names), same intended user task, and same load-bearing parameters (dates, months, ranges, enum values).\n\nNO-MATCH means the candidate would NOT satisfy the user's current request \u2014 different task (haiku composer vs tweet draft, login vs signup), different UI shape (form vs list vs dashboard), or load-bearing parameters differ (calendar-Jan vs calendar-Mar \u2014 same contract, different value).\n\nVisual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match \u2014 the user can refine those after they get a working UI.\n\nOutput exactly ONE tool call with your decision. confidence is a number in [0, 1]. matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.";
+declare const RERANK_SYSTEM_PROMPT = "You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate belongs to the SAME FAMILY as the current request \u2014 i.e. it would serve as a reasonable starting point that the requester can refine, not a pixel-exact replica.\n\nMATCH means the candidate is the same intended user task AND the same broad UI shape (component types, layout pattern). A candidate still MATCHES when the current request adds or omits fields, slots, or actions relative to the cached blueprint \u2014 a superset, a subset, or an overlapping wire surface all still match. Added or omitted fields/slots/actions DO NOT block a match and are NOT yours to judge: those wire-surface deltas are reconciled and reported to the agent separately, after you decide. Judge similarity of task and shape, never coverage of fields.\n\nNO-MATCH means the candidate is a fundamentally different thing \u2014 a different intended task (haiku composer vs tweet draft, login vs signup), a different UI shape (form vs list vs dashboard), OR a conflicting load-bearing fixed VALUE baked into the blueprint (calendar pinned to Jan vs a request for Mar \u2014 same contract shape, but the fixed value conflicts). Reserve NO-MATCH for these; do not decline a candidate merely because its fields, slots, or actions differ from the request.\n\nVisual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match \u2014 the user can refine those after they get a working UI.\n\nOutput exactly ONE tool call with your decision. confidence is a number in [0, 1] measuring how strongly the candidate is in the same task-and-shape family as the request (not how completely its fields cover the request). matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.";
 declare const RERANK_TOOL: ToolSchema;
-export { summarizeContract };
 /**
  * Run the rerank judge against a query + candidate list.
  *

package/dist/llm-rerank.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-rerank.d.ts","sourceRoot":"","sources":["../src/llm-rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,QAAA,MAAM,oBAAoB,spCAQkM,CAAC;AAE7N,QAAA,MAAM,WAAW,EAAE,UA4BlB,CAAC;AAsCF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AA8C7B;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,cAAc,CAAC,CAwDzB;AAGD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"llm-rerank.d.ts","sourceRoot":"","sources":["../src/llm-rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,QAAA,MAAM,oBAAoB,03DAQ6U,CAAC;AAExW,QAAA,MAAM,WAAW,EAAE,UA4BlB,CAAC;AA6EF;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,cAAc,CAAC,CAwDzB;AAGD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,CAAC"}

package/dist/llm-rerank.js

@@ -1,27 +1,12 @@
-/**
- * LLM rerank — Tier-2 precision oracle for the blueprint registry.
- *
- * Given a user's UI request (intent + contract structure) and a set
- * of candidate cached blueprints retrieved by RAG, ask a fast LLM
- * (Haiku 4.5) which candidate (if any) matches. Returns a structured
- * decision so the caller can branch deterministically.
- *
- * This module is the precision half of the blueprint-first
- * architecture: RAG retrieval is high-recall but low-precision (bge-
- * small confuses topic-similar but UI-divergent prompts); the LLM
- * judge restores precision. Combined break-even hit rate is ~10%;
- * realistic workloads observe 30-70%.
- */
-import { summarizeContract } from '@ggui-ai/protocol';
-const RERANK_SYSTEM_PROMPT = `You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate produces the SAME USEFUL UI for the current request.
+const RERANK_SYSTEM_PROMPT = `You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate belongs to the SAME FAMILY as the current request — i.e. it would serve as a reasonable starting point that the requester can refine, not a pixel-exact replica.
 
-MATCH means the candidate would correctly satisfy the user's current request — same UI shape (component types, layout pattern), same wire surface (slot names, action names), same intended user task, and same load-bearing parameters (dates, months, ranges, enum values).
+MATCH means the candidate is the same intended user task AND the same broad UI shape (component types, layout pattern). A candidate still MATCHES when the current request adds or omits fields, slots, or actions relative to the cached blueprint — a superset, a subset, or an overlapping wire surface all still match. Added or omitted fields/slots/actions DO NOT block a match and are NOT yours to judge: those wire-surface deltas are reconciled and reported to the agent separately, after you decide. Judge similarity of task and shape, never coverage of fields.
 
-NO-MATCH means the candidate would NOT satisfy the user's current request — different task (haiku composer vs tweet draft, login vs signup), different UI shape (form vs list vs dashboard), or load-bearing parameters differ (calendar-Jan vs calendar-Mar — same contract, different value).
+NO-MATCH means the candidate is a fundamentally different thing — a different intended task (haiku composer vs tweet draft, login vs signup), a different UI shape (form vs list vs dashboard), OR a conflicting load-bearing fixed VALUE baked into the blueprint (calendar pinned to Jan vs a request for Mar — same contract shape, but the fixed value conflicts). Reserve NO-MATCH for these; do not decline a candidate merely because its fields, slots, or actions differ from the request.
 
 Visual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match — the user can refine those after they get a working UI.
 
-Output exactly ONE tool call with your decision. confidence is a number in [0, 1]. matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.`;
+Output exactly ONE tool call with your decision. confidence is a number in [0, 1] measuring how strongly the candidate is in the same task-and-shape family as the request (not how completely its fields cover the request). matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.`;
 const RERANK_TOOL = {
     name: 'submit_rerank_decision',
     description: 'Submit your match-vs-no-match decision over the candidates.',
@@ -72,12 +57,6 @@ function truncate(text, max) {
         return text;
     return `${text.slice(0, max - 1)}…`;
 }
-// Re-export `summarizeContract` from protocol for backwards-compatible
-// access through `@ggui-ai/negotiator/llm-rerank` consumers (the
-// canonical home is `@ggui-ai/protocol` — both the registry storage
-// and the rerank prompt depend on it). Kept as a re-export so the
-// existing test imports here keep working.
-export { summarizeContract };
 function clampConfidence(value) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return 0;

package/dist/normalize-draft.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-draft.d.ts","sourceRoot":"","sources":["../src/normalize-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA8EH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA+CtD"}
+{"version":3,"file":"normalize-draft.d.ts","sourceRoot":"","sources":["../src/normalize-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA2GH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA4CtD"}

package/dist/normalize-draft.js

@@ -52,13 +52,12 @@ const ACTION_ENTRY_KEYS = new Set([
     'nextStep',
 ]);
 const STREAM_ENTRY_KEYS = new Set(['description', 'schema', 'source']);
-const AGENT_TOOL_KEYS = new Set([
-    'description',
-    'usage',
+const AGENT_TOOL_KEYS = new Set(['serverInfo', 'toolInfo', 'usage', 'example']);
+/** Inner keys of an {@link AgentToolEntry.toolInfo} (the MCP descriptor). */
+const AGENT_TOOL_INFO_KEYS = new Set([
     'inputSchema',
+    'description',
     'outputSchema',
-    'required',
-    'example',
 ]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -87,6 +86,34 @@ function cleanEntryMap(map, allowed, schemaFields) {
     }
     return out;
 }
+/** Clean a single `AgentToolEntry`: keep only the allowed outer keys
+ *  ({@link AGENT_TOOL_KEYS}), then clean the nested `toolInfo` to its
+ *  inner keys ({@link AGENT_TOOL_INFO_KEYS}) and normalize
+ *  `toolInfo.inputSchema` / `toolInfo.outputSchema` so the `.strict()`
+ *  schema doesn't reject a stray nested key. Non-record entries pass
+ *  through untouched. */
+function cleanAgentToolEntry(entry) {
+    if (!isRecord(entry))
+        return entry;
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (!AGENT_TOOL_KEYS.has(key))
+            continue; // strip the illegal outer key
+        out[key] =
+            key === 'toolInfo'
+                ? cleanEntry(value, AGENT_TOOL_INFO_KEYS, ['inputSchema', 'outputSchema'])
+                : value;
+    }
+    return out;
+}
+/** Apply {@link cleanAgentToolEntry} across the agent-tool catalog. */
+function cleanAgentToolMap(map) {
+    const out = {};
+    for (const [name, entry] of Object.entries(map)) {
+        out[name] = cleanAgentToolEntry(entry);
+    }
+    return out;
+}
 /**
  * Return a structurally-normalized copy of an untrusted draft: illegal
  * wrapper/entry keys stripped, inner schemas canonicalized. Pure — never
@@ -132,10 +159,7 @@ export function normalizeDraft(draft) {
         if (isRecord(ac['tools'])) {
             out['agentCapabilities'] = {
                 ...ac,
-                tools: cleanEntryMap(ac['tools'], AGENT_TOOL_KEYS, [
-                    'inputSchema',
-                    'outputSchema',
-                ]),
+                tools: cleanAgentToolMap(ac['tools']),
             };
         }
     }

package/dist/normalize-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-schema.d.ts","sourceRoot":"","sources":["../src/normalize-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkJH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CA2BxD"}
+{"version":3,"file":"normalize-schema.d.ts","sourceRoot":"","sources":["../src/normalize-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA6JH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CA2BxD"}

package/dist/normalize-schema.js

@@ -106,6 +106,18 @@ function normalizeTypeValue(value, enumSibling) {
         const alias = TYPE_ALIASES[lower];
         if (alias !== undefined)
             return alias;
+        if (lower.includes('|')) {
+            // Pipe-union string (`"STRING|null"`). Some models emit the union
+            // as one pipe-delimited string rather than the JSON Schema array
+            // form; recover the first valid non-null member, mirroring the
+            // array branch below (drops the nullable arm).
+            for (const member of lower.split('|')) {
+                const norm = normalizeTypeValue(member, enumSibling);
+                if (norm !== undefined && norm !== 'null')
+                    return norm;
+            }
+            return undefined;
+        }
         // Unrecognized garbage — drop the constraint rather than guess.
         return undefined;
     }

package/dist/synth-bench/cache-key-probe.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cache-key-probe.d.ts.map

package/dist/synth-bench/cache-key-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key-probe.d.ts","sourceRoot":"","sources":["../../src/synth-bench/cache-key-probe.ts"],"names":[],"mappings":""}