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

package/dist/synth-bench/cache-key-probe.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Blueprint cache-key stability probe.
+ *
+ * The handshake blueprint cache hits ONLY on exact canonical-contract
+ * equality: `blueprintKey(contract)` = sha256 of `canonicalizeContracts`
+ * (RFC 8785), which preserves spec placement, action/slot/tool NAMES and
+ * schema shapes (it only normalizes key order / whitespace and strips
+ * `description`/`usage`). The semantic/fuzzy match is disabled whenever a
+ * contract is present. So two requests for the SAME intent reuse a cached
+ * blueprint only if the LLM authored a byte-identical canonical contract
+ * both times.
+ *
+ * This probe synthesizes one intent N times and reports:
+ *   1. how many DISTINCT blueprintKeys result (distinct > 1 ⇒ the
+ *      exact-key cache structurally cannot hit on re-runs);
+ *   2. the KEY-AFFECTING diff — every leaf path where the runs disagree
+ *      (descriptions/usage stripped, since the key ignores them) — so we
+ *      can see WHETHER the variance is trivial (normalizable: required
+ *      order, additionalProperties, optional fields) or semantic
+ *      (property names / structure → only a semantic match can bridge it).
+ *
+ * Usage:
+ *   pnpm -F @ggui-ai/negotiator cache-probe -- --intent "my todo items" --n 5
+ *   pnpm -F @ggui-ai/negotiator cache-probe -- --n 5 --dump /tmp/cache-probe.json
+ */
+import { writeFileSync } from 'node:fs';
+import { blueprintKey } from '@ggui-ai/protocol/blueprint-key';
+import { synthesizeContract } from '../synthesize-contract.js';
+import { DEFAULT_MODEL, buildAnthropicLlmCaller, resolveAnthropicKey, } from './cli-llm.js';
+function parseArgs(argv) {
+    let intent = 'my todo items';
+    let n = 3;
+    let model = DEFAULT_MODEL;
+    let dump;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--intent' && argv[i + 1])
+            intent = argv[++i];
+        else if (a === '--n' && argv[i + 1])
+            n = Number(argv[++i]);
+        else if (a === '--model' && argv[i + 1])
+            model = argv[++i];
+        else if (a === '--dump' && argv[i + 1])
+            dump = argv[++i];
+    }
+    return { intent, n, model, ...(dump !== undefined ? { dump } : {}) };
+}
+/** One-line canonical-surface summary — the bits blueprintKey is sensitive to. */
+function shapeSummary(c) {
+    const parts = [];
+    const props = Object.keys(c.propsSpec?.properties ?? {});
+    const ctx = Object.keys(c.contextSpec ?? {});
+    const act = Object.keys(c.actionSpec ?? {});
+    const str = Object.keys(c.streamSpec ?? {});
+    const tools = Object.keys(c.agentCapabilities?.tools ?? {});
+    if (props.length)
+        parts.push(`props{${props.join(',')}}`);
+    if (ctx.length)
+        parts.push(`context{${ctx.join(',')}}`);
+    if (act.length)
+        parts.push(`action{${act.join(',')}}`);
+    if (str.length)
+        parts.push(`stream{${str.join(',')}}`);
+    if (tools.length)
+        parts.push(`tools{${tools.join(',')}}`);
+    return parts.join(' ') || '(empty)';
+}
+/**
+ * Flatten a contract to `path → json-encoded leaf`, applying the same
+ * domain rule the cache key does: drop string-valued `description` /
+ * `usage` (informational — `canonicalizeContracts` strips them). Objects
+ * recurse; arrays are encoded whole (order is key-affecting under JCS,
+ * which sorts object keys but NOT array elements).
+ */
+function flattenKeyAffecting(value, prefix, out) {
+    if (Array.isArray(value)) {
+        out.set(prefix, JSON.stringify(value));
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            if ((k === 'description' || k === 'usage') && typeof v === 'string') {
+                continue; // stripped by the cache key
+            }
+            flattenKeyAffecting(v, prefix ? `${prefix}.${k}` : k, out);
+        }
+        return;
+    }
+    out.set(prefix, JSON.stringify(value));
+}
+/** Every leaf path where the N contracts do not all agree, with the
+ *  distinct per-run values (or `∅` when a run omits the path). */
+function crossRunDiff(contracts) {
+    const flat = contracts.map((c) => {
+        const m = new Map();
+        flattenKeyAffecting(c, '', m);
+        return m;
+    });
+    const allPaths = new Set();
+    for (const m of flat)
+        for (const p of m.keys())
+            allPaths.add(p);
+    const divergent = [];
+    for (const path of [...allPaths].sort()) {
+        const values = flat.map((m) => m.get(path) ?? '∅');
+        if (new Set(values).size > 1)
+            divergent.push({ path, values });
+    }
+    return divergent;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const llm = buildAnthropicLlmCaller(resolveAnthropicKey('cache-probe'), args.model);
+    process.stdout.write(`cache-probe: intent=${JSON.stringify(args.intent)} n=${args.n} model=${args.model}\n\n`);
+    const contracts = [];
+    const keys = [];
+    for (let i = 0; i < args.n; i++) {
+        const synth = await synthesizeContract({ llm }, args.intent);
+        if (synth.contract === null) {
+            process.stdout.write(`  run ${i + 1}: synth declined — ${synth.reason}\n`);
+            continue;
+        }
+        const key = blueprintKey(synth.contract);
+        contracts.push(synth.contract);
+        keys.push(key);
+        process.stdout.write(`  run ${i + 1}: ${key}  ${shapeSummary(synth.contract)}\n`);
+    }
+    const distinct = new Set(keys);
+    process.stdout.write(`\nDistinct blueprintKeys: ${distinct.size}/${keys.length}\n`);
+    if (distinct.size <= 1 && keys.length > 1) {
+        process.stdout.write('STABLE → the exact-key cache WOULD hit on a re-run of this intent.\n');
+    }
+    else if (keys.length > 1) {
+        process.stdout.write('UNSTABLE → same intent yields different canonical contracts → the exact-key\n' +
+            'cache cannot hit; each request cold-gens a new blueprint.\n');
+    }
+    // Key-affecting cross-run diff — the "what varies" the user asked for.
+    if (contracts.length > 1) {
+        const diff = crossRunDiff(contracts);
+        process.stdout.write(`\n=== KEY-AFFECTING DIFF (${diff.length} divergent paths; descriptions stripped) ===\n`);
+        for (const { path, values } of diff) {
+            process.stdout.write(`  ${path}\n`);
+            values.forEach((v, i) => {
+                const capped = v.length > 100 ? `${v.slice(0, 100)}…` : v;
+                process.stdout.write(`    run${i + 1}: ${capped}\n`);
+            });
+        }
+        // Heuristic taxonomy hint.
+        const isArrayOrderOnly = diff.every(({ values }) => {
+            const parsed = values
+                .filter((v) => v !== '∅')
+                .map((v) => {
+                try {
+                    return JSON.stringify([...JSON.parse(v)].sort());
+                }
+                catch {
+                    return v;
+                }
+            });
+            return new Set(parsed).size === 1;
+        });
+        process.stdout.write(`\nHint: ${diff.length === 0
+            ? 'no key-affecting differences — variance must be elsewhere'
+            : isArrayOrderOnly
+                ? 'ALL divergent paths are arrays differing only in ORDER → a canonical sort in canonicalizeContracts would collapse these keys (cheap fix, no semantic match needed).'
+                : 'divergent paths include non-array-order differences (names / types / structure / presence) → a semantic intent-match is needed to bridge them (canonicalization alone cannot).'}\n`);
+    }
+    if (args.dump !== undefined) {
+        writeFileSync(args.dump, JSON.stringify({ intent: args.intent, model: args.model, keys, contracts }, null, 2));
+        process.stdout.write(`\nDumped ${contracts.length} contracts → ${args.dump}\n`);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`cache-probe failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/synth-bench/corpus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../../src/synth-bench/corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;+DAG2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;2DAIuD;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;0EAGsE;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;;OASG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtD;;;;;sEAKkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;qDAEiD;IACjD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAOhE;AAoDD,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAs8B7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EA8Q9C,CAAC"}
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../../src/synth-bench/corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;+DAG2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;2DAIuD;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;0EAGsE;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;;OASG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtD;;;;;sEAKkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;qDAEiD;IACjD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAOhE;AAoDD,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAs8B7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EAsR9C,CAAC"}

package/dist/synth-bench/corpus.js

@@ -1091,19 +1091,23 @@ export const REPAIR_CORPUS = [
             agentCapabilities: {
                 tools: {
                     todo_toggle: {
-                        description: 'Flip a todo done/undone',
-                        inputSchema: {
-                            type: 'object',
-                            properties: { id: { type: 'string' } },
-                            required: ['id'],
+                        toolInfo: {
+                            description: 'Flip a todo done/undone',
+                            inputSchema: {
+                                type: 'object',
+                                properties: { id: { type: 'string' } },
+                                required: ['id'],
+                            },
                         },
                     },
                     todo_add: {
-                        description: 'Append a new todo',
-                        inputSchema: {
-                            type: 'object',
-                            properties: { text: { type: 'string' } },
-                            required: ['text'],
+                        toolInfo: {
+                            description: 'Append a new todo',
+                            inputSchema: {
+                                type: 'object',
+                                properties: { text: { type: 'string' } },
+                                required: ['text'],
+                            },
                         },
                     },
                 },
@@ -1178,19 +1182,23 @@ export const REPAIR_CORPUS = [
             agentCapabilities: {
                 tools: {
                     todo_toggle: {
-                        description: 'Flip a todo done/undone',
-                        inputSchema: {
-                            type: 'object',
-                            properties: { id: { type: 'string' } },
-                            required: ['id'],
+                        toolInfo: {
+                            description: 'Flip a todo done/undone',
+                            inputSchema: {
+                                type: 'object',
+                                properties: { id: { type: 'string' } },
+                                required: ['id'],
+                            },
                         },
                     },
                     todo_add: {
-                        description: 'Append a new todo',
-                        inputSchema: {
-                            type: 'object',
-                            properties: { text: { type: 'string' } },
-                            required: ['text'],
+                        toolInfo: {
+                            description: 'Append a new todo',
+                            inputSchema: {
+                                type: 'object',
+                                properties: { text: { type: 'string' } },
+                                required: ['text'],
+                            },
                         },
                     },
                 },

package/dist/synth-bench/run-bench.js

@@ -34,7 +34,7 @@
  */
 import { listContractGadgets } from '@ggui-ai/protocol';
 import { synthesizeContract } from '../synthesize-contract.js';
-import { validateContractStructure, } from '../contract-validators.js';
+import { validateContractRedundancy, } from '../contract-validators.js';
 import { BENCH_CORPUS, contractShape, } from './corpus.js';
 /**
  * Failure kinds that are ADVISORY — surfaced in the report but do NOT
@@ -246,7 +246,7 @@ export async function evaluateAgainstCorpus(deps, options = {}, corpus = BENCH_C
             };
         }
         else {
-            const findings = validateContractStructure(synth.contract).findings;
+            const findings = validateContractRedundancy(synth.contract).findings;
             const score = scoreSynthesizedContract(synth.contract, entry.expected);
             outcome = {
                 entry,

package/dist/synthesize-contract.d.ts

@@ -56,7 +56,7 @@ export interface SynthesizeContractResult {
     readonly attempts: number;
     /**
      * Structural-validator findings produced when the synthesizer ran the
-     * `validateContractStructure` gate against its assembled contract.
+     * `validateContractRedundancy` gate against its assembled contract.
      * Empty when validator didn't run (early skip / decline). Surfaced
      * so callers (cache-trace emit site, ops dashboards) can render
      * findings without re-running the detector.
@@ -136,8 +136,7 @@ export declare function synthesizeContract(deps: {
 }): Promise<SynthesizeContractResult>;
 /**
  * Compose the "AVAILABLE GADGETS" section appended to synth's user
- * prompt (and the decision-engine user message — both paths share
- * this one composer). Flattens the package-keyed
+ * prompt. Flattens the package-keyed
  * {@link GadgetDescriptor} catalog into one line per export:
  *
  *     - hook `useGeolocation` (package `@ggui-ai/gadgets`) — <desc> (usage: <usage>)

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

@@ -1 +1 @@
-{"version":3,"file":"synthesize-contract.d.ts","sourceRoot":"","sources":["../src/synthesize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAsBlC,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAuOD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UA+I7B,CAAC;AAwRF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS;QAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;CACL,GACA,OAAO,CAAC,wBAAwB,CAAC,CAyMnC;AAgUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,GAC/C,MAAM,GAAG,SAAS,CA+CpB"}
+{"version":3,"file":"synthesize-contract.d.ts","sourceRoot":"","sources":["../src/synthesize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAEtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAsBlC,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAuOD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UA+I7B,CAAC;AAwRF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS;QAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;CACL,GACA,OAAO,CAAC,wBAAwB,CAAC,CAyMnC;AAmUD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,GAC/C,MAAM,GAAG,SAAS,CA+CpB"}

package/dist/synthesize-contract.js

@@ -40,7 +40,7 @@ import { dataContractSchema, gadgetExportName, } from '@ggui-ai/protocol';
 import { lintContract } from '@ggui-ai/protocol';
 import { normalizeSchema } from './normalize-schema.js';
 import { draftSeedPropKeys, findDroppedSeedSurfaces, } from './preserve-seed-surfaces.js';
-import { formatValidationFindings, validateActionsVsContext, validateContractCoherence, validateContractStructure, } from './contract-validators.js';
+import { formatValidationFindings, validateActionsVsContext, validateContractCoherence, validateContractRedundancy, } from './contract-validators.js';
 /**
  * Map a protocol-linter {@link ContractIssue} into the negotiator's
  * existing {@link ContractValidationFinding} shape so phase-2/3/4
@@ -257,7 +257,7 @@ Several retired field/hook names appear in older training data. The cross-ref li
   - clientCapabilities.capabilities                    (retired inner key; use clientCapabilities.gadgets)
   - useWiredTool(...) / useClientTool(...) / useAgentTool(...)  (retired hooks; the contract layer doesn't reference these at all)
   - "@ggui-ai/client-tools" as a package import        (retired package; use @ggui-ai/gadgets)
-  - PushStory / story.* on handshake input             (retired wire shape; handshake input is flat — {renderId, intent, contract?, hint?, forceCreate?})
+  - PushStory / story.* on handshake input             (retired wire shape; handshake input is flat — {sessionId, intent, contract?, hint?, forceCreate?})
   - story.adapters / declaredAdapters                  (retired adapter gate; permissions are a registry-side descriptor field — the wire clientCapabilities.gadgets map carries identity only)
   - dispatch: {kind: 'tool', tool: ...}               (retired discriminated union on actionSpec entries — actions carry NO tool wiring)
   - dispatch: {kind: 'agent', intendedTool: ...}      (retired — same; do not wire actions to tools)
@@ -622,7 +622,7 @@ function pruneRedundantActions(contract) {
     if (actionSpec === undefined)
         return contract;
     const redundant = new Set();
-    for (const f of validateContractStructure(contract).findings) {
+    for (const f of validateContractRedundancy(contract).findings) {
         if (f.kind === 'redundant-action' && typeof f.actionName === 'string') {
             redundant.add(f.actionName);
         }
@@ -764,7 +764,7 @@ export async function synthesizeContract(deps, intent, options) {
         // get it right every draw. Subtractive, so the contract stays
         // schema-valid.
         const validatedContract = pruneRedundantActions(validated.data);
-        const structureSafety = validateContractStructure(validatedContract);
+        const structureSafety = validateContractRedundancy(validatedContract);
         const placementSafety = validateActionsVsContext(validatedContract);
         // Intent-aware coherence — the one validator that reads `trimmed`.
         // Catches the degenerate "actionSpec-only, no data surface"
@@ -1015,20 +1015,26 @@ function buildContract(input) {
         for (const [name, entry] of Object.entries(input.agentCapabilities.tools)) {
             if (!entry || typeof entry !== 'object')
                 continue;
+            // The LLM authors the ergonomic flat shape ({inputSchema?,
+            // outputSchema?, usage?}); the wire shape nests the MCP descriptor
+            // under `toolInfo` with a REQUIRED `inputSchema` (default the
+            // void-object schema when the LLM omitted it). `usage` stays on the
+            // ggui authoring layer alongside the descriptor.
+            const inputSchema = (entry.inputSchema !== undefined
+                ? normalizeSchema(entry.inputSchema)
+                : { type: 'object' });
             built[name] = {
-                ...(entry.inputSchema !== undefined
-                    ? { inputSchema: normalizeSchema(entry.inputSchema) }
-                    : {}),
-                ...(entry.outputSchema !== undefined
-                    ? { outputSchema: normalizeSchema(entry.outputSchema) }
-                    : {}),
+                toolInfo: {
+                    inputSchema,
+                    ...(entry.outputSchema !== undefined
+                        ? { outputSchema: normalizeSchema(entry.outputSchema) }
+                        : {}),
+                },
                 ...(typeof entry.usage === 'string' ? { usage: entry.usage } : {}),
             };
         }
         if (Object.keys(built).length > 0) {
-            contract.agentCapabilities = {
-                tools: built,
-            };
+            contract.agentCapabilities = { tools: built };
         }
     }
     // clientCapabilities.gadgets — browser-capability gadgets the
@@ -1090,8 +1096,7 @@ const SYNTH_PER_LIBRARY_BUDGET = 300;
 const SYNTH_TOTAL_BUDGET = 3_000;
 /**
  * Compose the "AVAILABLE GADGETS" section appended to synth's user
- * prompt (and the decision-engine user message — both paths share
- * this one composer). Flattens the package-keyed
+ * prompt. Flattens the package-keyed
  * {@link GadgetDescriptor} catalog into one line per export:
  *
  *     - hook `useGeolocation` (package `@ggui-ai/gadgets`) — <desc> (usage: <usage>)

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@ggui-ai/negotiator",
-  "version": "0.2.0-alpha.4",
-  "description": "UI decision engine for ggui. Given an agent's signal and the current render state, decides which UI to render (create / update / replace) and synthesizes the data contract. Deployment-agnostic: concrete embedding and vector-store bindings plug in via the storage interfaces from @ggui-ai/mcp-server-core.",
+  "version": "0.3.0-rc.0",
+  "description": "Contract-synthesis + match-judge engine for ggui's handshake. Synthesizes or repairs a conforming DataContract from an agent's draft, judges blueprint-match candidates for reuse, and validates contract structure + novelty — the primitives composed by decideHandshake in @ggui-ai/mcp-server-handlers. Deployment-agnostic: concrete embedding and vector-store bindings plug in via the storage interfaces from @ggui-ai/mcp-server-core.",
   "license": "Apache-2.0",
   "keywords": [
     "ggui",
     "mcp",
     "generative-ui",
     "ai-agents",
-    "decision-engine"
+    "contract-synthesis"
   ],
   "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/negotiator",
   "repository": {
@@ -47,8 +47,8 @@
     }
   },
   "dependencies": {
-    "@ggui-ai/mcp-server-core": "0.2.0-alpha.4",
-    "@ggui-ai/protocol": "0.2.0-alpha.4"
+    "@ggui-ai/protocol": "0.3.0-rc.0",
+    "@ggui-ai/mcp-server-core": "0.3.0-rc.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -63,13 +63,14 @@
   },
   "author": "ggui contributors <hello@ggui.ai>",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "probe-rerank": "tsx src/rerank-eval/run-probe-cli.ts",
     "bench-synth": "tsx src/synth-bench/run-bench-cli.ts",
-    "bench-repair": "tsx src/synth-bench/run-repair-bench-cli.ts"
+    "bench-repair": "tsx src/synth-bench/run-repair-bench-cli.ts",
+    "cache-probe": "tsx src/synth-bench/cache-key-probe.ts"
   }
 }

package/src/contract-validators.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)
@@ -80,26 +83,27 @@ 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;
 }
@@ -251,20 +255,20 @@ function isEmptyPayloadSchema(schema: JsonSchema | undefined): boolean {
 }
 
 // =============================================================================
-// 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(
+export function validateContractRedundancy(
   contract: DataContract,
 ): ContractValidationResult {
   const findings: ContractValidationFinding[] = [];

package/src/index.ts

@@ -1,46 +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 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,
@@ -51,8 +37,9 @@ 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 { normalizeDraft } from './normalize-draft.js';
 export {
-  validateContractStructure,
+  validateContractRedundancy,
   validateContractNovelty,
   formatValidationFindings,
 } from './contract-validators.js';

package/src/llm-caller.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
@@ -43,7 +43,7 @@ export interface ToolSchema {
   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