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

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

@@ -0,0 +1,33 @@
+/**
+ * Deterministic draft normalization — the cheap, faithful repair tier.
+ *
+ * Most agent-draft malformations are MECHANICAL: a stray illegal key on
+ * a spec wrapper (a JSON-Schema-reflex `required: [...]` array on the
+ * propsSpec wrapper, an `additionalProperties` key), or a non-canonical
+ * schema `type` spelling (`"enum"`, `"integer"`). None of these needs an
+ * LLM to fix — and routing them through the LLM repair loop is both
+ * wasteful (a full regeneration) and RISKY (the model may re-author and
+ * reshape a 95%-correct draft, e.g. drop a propsSpec seed surface).
+ *
+ * This pass fixes the mechanical classes deterministically, preserving
+ * the agent's intent exactly:
+ *   - strips keys the protocol's `.strict()` spec schemas would reject,
+ *     keeping only the allowed keys at each wrapper / entry level;
+ *   - canonicalizes every inner JSON Schema via {@link normalizeSchema}
+ *     (the same normalizer `buildContract` runs on synth output).
+ *
+ * The caller (`ensureConformingContract`) re-lints the result: if it now
+ * passes the gate, the draft is returned WITHOUT ever calling the LLM.
+ * Semantic deficiencies (wrong placement, missing data surface, dangling
+ * cross-refs) are deliberately out of scope — those still go to the
+ * repair loop, where reasoning earns its keep.
+ */
+/**
+ * Return a structurally-normalized copy of an untrusted draft: illegal
+ * wrapper/entry keys stripped, inner schemas canonicalized. Pure — never
+ * mutates the input, never throws. Unknown top-level fields ride through
+ * (the top-level DataContract schema is `.passthrough()`); only the
+ * `.strict()` spec wrappers and entries are cleaned.
+ */
+export declare function normalizeDraft(draft: unknown): unknown;
+//# sourceMappingURL=normalize-draft.d.ts.map

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

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

@@ -0,0 +1,167 @@
+/**
+ * Deterministic draft normalization — the cheap, faithful repair tier.
+ *
+ * Most agent-draft malformations are MECHANICAL: a stray illegal key on
+ * a spec wrapper (a JSON-Schema-reflex `required: [...]` array on the
+ * propsSpec wrapper, an `additionalProperties` key), or a non-canonical
+ * schema `type` spelling (`"enum"`, `"integer"`). None of these needs an
+ * LLM to fix — and routing them through the LLM repair loop is both
+ * wasteful (a full regeneration) and RISKY (the model may re-author and
+ * reshape a 95%-correct draft, e.g. drop a propsSpec seed surface).
+ *
+ * This pass fixes the mechanical classes deterministically, preserving
+ * the agent's intent exactly:
+ *   - strips keys the protocol's `.strict()` spec schemas would reject,
+ *     keeping only the allowed keys at each wrapper / entry level;
+ *   - canonicalizes every inner JSON Schema via {@link normalizeSchema}
+ *     (the same normalizer `buildContract` runs on synth output).
+ *
+ * The caller (`ensureConformingContract`) re-lints the result: if it now
+ * passes the gate, the draft is returned WITHOUT ever calling the LLM.
+ * Semantic deficiencies (wrong placement, missing data surface, dangling
+ * cross-refs) are deliberately out of scope — those still go to the
+ * repair loop, where reasoning earns its keep.
+ */
+import { normalizeSchema } from './normalize-schema.js';
+// Allowed-key sets mirror the protocol `.strict()` schemas
+// (schemas/data-contract.ts). Stripping anything outside these is safe:
+// the strict schema would reject it as CTR_SHAPE_UNRECOGNIZED_KEYS.
+const PROPS_WRAPPER_KEYS = new Set(['description', 'properties']);
+const PROP_ENTRY_KEYS = new Set([
+    'description',
+    'schema',
+    'required',
+    'default',
+    'example',
+    'sourceTool',
+]);
+const CONTEXT_ENTRY_KEYS = new Set([
+    'description',
+    'schema',
+    'default',
+    'debounceMs',
+    'example',
+]);
+const ACTION_ENTRY_KEYS = new Set([
+    'description',
+    'label',
+    'schema',
+    'example',
+    'icon',
+    'confirm',
+    'nextStep',
+]);
+const STREAM_ENTRY_KEYS = new Set(['description', 'schema', 'source']);
+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',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Keep only `allowed` keys; normalize the schema-bearing fields named
+ *  in `schemaFields`. Non-record entries pass through untouched. */
+function cleanEntry(entry, allowed, schemaFields) {
+    if (!isRecord(entry))
+        return entry;
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (!allowed.has(key))
+            continue; // strip the illegal key
+        out[key] =
+            schemaFields.includes(key) && value !== undefined
+                ? normalizeSchema(value)
+                : value;
+    }
+    return out;
+}
+/** Apply {@link cleanEntry} across a `Record<name, entry>` spec map. */
+function cleanEntryMap(map, allowed, schemaFields) {
+    const out = {};
+    for (const [name, entry] of Object.entries(map)) {
+        out[name] = cleanEntry(entry, 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
+ * mutates the input, never throws. Unknown top-level fields ride through
+ * (the top-level DataContract schema is `.passthrough()`); only the
+ * `.strict()` spec wrappers and entries are cleaned.
+ */
+export function normalizeDraft(draft) {
+    if (!isRecord(draft))
+        return draft;
+    const out = { ...draft };
+    // propsSpec wrapper: keep {description, properties}; clean each PropEntry.
+    if (isRecord(out['propsSpec'])) {
+        const ps = {};
+        for (const [key, value] of Object.entries(out['propsSpec'])) {
+            if (PROPS_WRAPPER_KEYS.has(key))
+                ps[key] = value;
+        }
+        if (isRecord(ps['properties'])) {
+            ps['properties'] = cleanEntryMap(ps['properties'], PROP_ENTRY_KEYS, [
+                'schema',
+            ]);
+        }
+        out['propsSpec'] = ps;
+    }
+    if (isRecord(out['contextSpec'])) {
+        out['contextSpec'] = cleanEntryMap(out['contextSpec'], CONTEXT_ENTRY_KEYS, [
+            'schema',
+        ]);
+    }
+    if (isRecord(out['actionSpec'])) {
+        out['actionSpec'] = cleanEntryMap(out['actionSpec'], ACTION_ENTRY_KEYS, [
+            'schema',
+        ]);
+    }
+    if (isRecord(out['streamSpec'])) {
+        out['streamSpec'] = cleanEntryMap(out['streamSpec'], STREAM_ENTRY_KEYS, [
+            'schema',
+        ]);
+    }
+    if (isRecord(out['agentCapabilities'])) {
+        const ac = out['agentCapabilities'];
+        if (isRecord(ac['tools'])) {
+            out['agentCapabilities'] = {
+                ...ac,
+                tools: cleanAgentToolMap(ac['tools']),
+            };
+        }
+    }
+    return out;
+}

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/preserve-seed-surfaces.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Seed-surface preservation — the deterministic backstop that keeps the
+ * repair loop FAITHFUL.
+ *
+ * The agent's draft declares its agent-owned render-time data as
+ * `propsSpec.properties` (the only agent→client seed channel —
+ * `contextSpec` has no runtime seed path). A repair that drops or
+ * reshapes one of those keys away from propsSpec (the canonical
+ * `propsSpec.X → contextSpec.X` regression) produces a contract that is
+ * VALID (`lintContract` passes) yet round-trip-BROKEN: the agent can no
+ * longer seed X at render, so the UI renders empty.
+ *
+ * `lintContract` + the placement validators can't catch this — none of
+ * them sees the agent's DRAFT. These helpers do: they compare the
+ * repaired candidate against the draft and report which agent-owned seed
+ * surfaces went missing, so the synth loop can drive a corrective retry.
+ * Model-independent — it works even when a weak model keeps reshaping.
+ */
+import type { DataContract } from '@ggui-ai/protocol';
+/**
+ * The `propsSpec.properties` keys an agent declared on a (possibly
+ * malformed) draft — its agent-owned render-time SEED surfaces.
+ * Defensive: the draft is untrusted, so every level is probed before
+ * access. Returns `[]` for any non-propsSpec-bearing draft.
+ */
+export declare function draftSeedPropKeys(draft: unknown): string[];
+/**
+ * Agent-owned seed surfaces (propsSpec property keys) present in `draft`
+ * that the repaired `candidate` DROPPED — i.e. they are no longer
+ * seedable as a propsSpec property. Reshaping `propsSpec.X` to
+ * `contextSpec.X`, or dropping it entirely, both surface here (contextSpec
+ * is not an agent-seedable home). Returns `[]` when every declared seed
+ * surface survived (preservation holds).
+ *
+ * Preservation-biased on purpose: keeping a seed key the intent turned
+ * out not to need is harmless (an unsent optional prop); DROPPING one the
+ * agent relies on is the round-trip break. So we only ever flag drops.
+ */
+export declare function findDroppedSeedSurfaces(draft: unknown, candidate: DataContract): string[];
+//# sourceMappingURL=preserve-seed-surfaces.d.ts.map

package/dist/preserve-seed-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-seed-surfaces.d.ts","sourceRoot":"","sources":["../src/preserve-seed-surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAMtD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAO1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,YAAY,GACtB,MAAM,EAAE,CAKV"}

package/dist/preserve-seed-surfaces.js

@@ -0,0 +1,57 @@
+/**
+ * Seed-surface preservation — the deterministic backstop that keeps the
+ * repair loop FAITHFUL.
+ *
+ * The agent's draft declares its agent-owned render-time data as
+ * `propsSpec.properties` (the only agent→client seed channel —
+ * `contextSpec` has no runtime seed path). A repair that drops or
+ * reshapes one of those keys away from propsSpec (the canonical
+ * `propsSpec.X → contextSpec.X` regression) produces a contract that is
+ * VALID (`lintContract` passes) yet round-trip-BROKEN: the agent can no
+ * longer seed X at render, so the UI renders empty.
+ *
+ * `lintContract` + the placement validators can't catch this — none of
+ * them sees the agent's DRAFT. These helpers do: they compare the
+ * repaired candidate against the draft and report which agent-owned seed
+ * surfaces went missing, so the synth loop can drive a corrective retry.
+ * Model-independent — it works even when a weak model keeps reshaping.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The `propsSpec.properties` keys an agent declared on a (possibly
+ * malformed) draft — its agent-owned render-time SEED surfaces.
+ * Defensive: the draft is untrusted, so every level is probed before
+ * access. Returns `[]` for any non-propsSpec-bearing draft.
+ */
+export function draftSeedPropKeys(draft) {
+    if (!isRecord(draft))
+        return [];
+    const propsSpec = draft['propsSpec'];
+    if (!isRecord(propsSpec))
+        return [];
+    const properties = propsSpec['properties'];
+    if (!isRecord(properties))
+        return [];
+    return Object.keys(properties);
+}
+/**
+ * Agent-owned seed surfaces (propsSpec property keys) present in `draft`
+ * that the repaired `candidate` DROPPED — i.e. they are no longer
+ * seedable as a propsSpec property. Reshaping `propsSpec.X` to
+ * `contextSpec.X`, or dropping it entirely, both surface here (contextSpec
+ * is not an agent-seedable home). Returns `[]` when every declared seed
+ * surface survived (preservation holds).
+ *
+ * Preservation-biased on purpose: keeping a seed key the intent turned
+ * out not to need is harmless (an unsent optional prop); DROPPING one the
+ * agent relies on is the round-trip break. So we only ever flag drops.
+ */
+export function findDroppedSeedSurfaces(draft, candidate) {
+    const seedKeys = draftSeedPropKeys(draft);
+    if (seedKeys.length === 0)
+        return [];
+    const candidateProps = candidate.propsSpec?.properties ?? {};
+    return seedKeys.filter((key) => candidateProps[key] === 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":""}

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/cli-llm.d.ts

@@ -0,0 +1,20 @@
+import type { LLMCaller } from '../llm-caller.js';
+/** Default bench model — matches the `ui-gen-default-haiku-4-5` slug. */
+export declare const DEFAULT_MODEL = "claude-haiku-4-5";
+/** Haiku 4.5 token pricing (USD per token) for the cost report. */
+export declare const HAIKU_4_5_PRICE_INPUT_PER_TOKEN: number;
+export declare const HAIKU_4_5_PRICE_OUTPUT_PER_TOKEN: number;
+/**
+ * Resolve the Anthropic API key: `ANTHROPIC_API_KEY` env var first, then
+ * `~/.ggui/credentials.json` at `apps.global.anthropic`. `scriptName`
+ * prefixes the error hints so a failure names the bench that needs it.
+ */
+export declare function resolveAnthropicKey(scriptName: string): string;
+/** Running token usage accumulated across `callStructured` calls in this
+ *  process — read after a run for the cost line. */
+export declare function getTokenUsage(): {
+    readonly input: number;
+    readonly output: number;
+};
+export declare function buildAnthropicLlmCaller(apiKey: string, model: string): LLMCaller;
+//# sourceMappingURL=cli-llm.d.ts.map

package/dist/synth-bench/cli-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-llm.d.ts","sourceRoot":"","sources":["../../src/synth-bench/cli-llm.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,kBAAkB,CAAC;AAI9D,yEAAyE;AACzE,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,QAAkB,CAAC;AAC/D,eAAO,MAAM,gCAAgC,QAAkB,CAAC;AAMhE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAmB9D;AAmBD;oDACoD;AACpD,wBAAgB,aAAa,IAAI;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAEA;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,SAAS,CA2DX"}