@ggui-ai/negotiator 0.23.0 → 0.24.0

package/dist/index.d.ts

@@ -26,8 +26,8 @@
  */
 export { hashContract, buildVariant } from './contract-hash.js';
 export type { LLMCaller, LLMCallerConfig, ToolSchema } from './llm-caller.js';
-export { rerankCandidates } from './llm-rerank.js';
-export type { RerankCandidate, RerankDecision, RerankQuery, } from './llm-rerank.js';
+export { llmRerankJudge, rerankCandidates } from './llm-rerank.js';
+export type { RerankCandidate, RerankDecision, RerankJudge, 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';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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,EACV,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAItD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC;AAC5B,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"}
+{"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,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,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,EACV,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAItD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC;AAC5B,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

@@ -25,7 +25,7 @@
  * consumers need. Each additive export carries semver weight.
  */
 export { hashContract, buildVariant } from './contract-hash.js';
-export { rerankCandidates } from './llm-rerank.js';
+export { llmRerankJudge, rerankCandidates } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
 export { ensureConformingContract } from './ensure-conforming-contract.js';
 export { normalizeDraft } from './normalize-draft.js';

package/dist/llm-rerank.d.ts

@@ -1,17 +1,3 @@
-/**
- * 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 type { LLMCaller, ToolSchema } from './llm-caller.js';
 /**
  * One candidate blueprint for the LLM judge to consider.
@@ -58,11 +44,12 @@ export interface RerankDecision {
      */
     readonly confidence: number;
     /**
-     * Free-text reason from the judge. Surface in trace logs so
+     * Free-text reason from the judge, when it gives one — a judge that
+     * decides without prose sends none (ggui#1235). Surface in trace logs so
      * operators can debug "why didn't this hit." Truncate at the
      * persistence boundary if cardinality is a concern.
      */
-    readonly reason: string;
+    readonly reason?: string;
     /** Wall-clock latency of the LLM call. */
     readonly latencyMs: number;
     /**
@@ -98,5 +85,20 @@ declare const RERANK_TOOL: ToolSchema;
 export declare function rerankCandidates(deps: {
     readonly llm: LLMCaller;
 }, query: RerankQuery, candidates: readonly RerankCandidate[]): Promise<RerankDecision>;
+/**
+ * The judge seam (ggui#1235): one function from a query and its candidates
+ * to a {@link RerankDecision}. The matcher takes a judge together with the
+ * confidence threshold it was measured on (the pair), so a judge on
+ * another scale never meets a cut calibrated for a different one.
+ * `matchId: null` is a judge's only decline; `confidence` is the judge's
+ * own, compared by the caller against the pair's threshold.
+ */
+export type RerankJudge = (query: RerankQuery, candidates: readonly RerankCandidate[]) => Promise<RerankDecision>;
+/**
+ * Today's judge as a {@link RerankJudge}: {@link rerankCandidates} bound to
+ * an {@link LLMCaller} — the same prompt, the same tool, the same decision,
+ * so a caller that injects nothing else behaves exactly as before.
+ */
+export declare function llmRerankJudge(llm: LLMCaller): RerankJudge;
 export { RERANK_SYSTEM_PROMPT, RERANK_TOOL };
 //# sourceMappingURL=llm-rerank.d.ts.map

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,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;AA8EF;;;;;;;;;;;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":"AAeA,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;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,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;AAkFF;;;;;;;;;;;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;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,SAAS,eAAe,EAAE,KACnC,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,WAAW,CAE1D;AAED,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,CAAC"}

package/dist/llm-rerank.js

@@ -1,3 +1,18 @@
+/**
+ * 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 { MATCHED_INTENT_MAX_CHARS } 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 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 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.
@@ -42,7 +57,11 @@ function buildUserMessage(query, candidates) {
     for (const c of candidates) {
         lines.push('---');
         lines.push(`  id: ${c.id}`);
-        lines.push(`  intent: ${truncate(c.cachedIntent, 280)}`);
+        // The cap is the protocol's `MATCHED_INTENT_MAX_CHARS`: the same
+        // string the judge reads here is what a judged hit hands back to the
+        // agent as `blueprintMeta.matchedIntent` (ggui#1336), so the two cuts
+        // are one constant, not two literals that happen to agree.
+        lines.push(`  intent: ${truncate(c.cachedIntent, MATCHED_INTENT_MAX_CHARS)}`);
         lines.push(`  contract: ${c.cachedContractSummary}`);
         if (typeof c.cosine === 'number') {
             lines.push(`  cosine: ${c.cosine.toFixed(3)}`);
@@ -153,5 +172,12 @@ export async function rerankCandidates(deps, query, candidates) {
         tokenCost: { input: 0, output: 0 },
     };
 }
-// Re-exports for the eval harness — keep public surface explicit.
+/**
+ * Today's judge as a {@link RerankJudge}: {@link rerankCandidates} bound to
+ * an {@link LLMCaller} — the same prompt, the same tool, the same decision,
+ * so a caller that injects nothing else behaves exactly as before.
+ */
+export function llmRerankJudge(llm) {
+    return (query, candidates) => rerankCandidates({ llm }, query, candidates);
+}
 export { RERANK_SYSTEM_PROMPT, RERANK_TOOL };

package/dist/rerank-eval/run-probe-cli.js

@@ -65,7 +65,10 @@ async function main() {
     const usage = getTokenUsage();
     const totalCost = usage.input * HAIKU_4_5_PRICE_INPUT_PER_TOKEN +
         usage.output * HAIKU_4_5_PRICE_OUTPUT_PER_TOKEN;
-    const callsMade = report.outcomes.filter((o) => !/short-circuited/.test(o.decision.reason)).length;
+    const callsMade = report.outcomes.filter(
+    // ggui#1235 — `reason` is optional on the seam; a judge with no prose
+    // still made a call.
+    (o) => !/short-circuited/.test(o.decision.reason ?? '')).length;
     const costPerCall = callsMade === 0 ? 0 : totalCost / callsMade;
     process.stdout.write(`Tokens:         input=${usage.input} · output=${usage.output}\n`);
     process.stdout.write(`Cost:           total=$${totalCost.toFixed(4)} · per-call=$${costPerCall.toFixed(4)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/negotiator",
-  "version": "0.23.0",
+  "version": "0.24.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": [
@@ -47,8 +47,8 @@
     }
   },
   "dependencies": {
-    "@ggui-ai/mcp-server-core": "0.23.0",
-    "@ggui-ai/protocol": "0.23.0"
+    "@ggui-ai/mcp-server-core": "0.24.0",
+    "@ggui-ai/protocol": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/index.ts

@@ -27,10 +27,11 @@
 
 export { hashContract, buildVariant } from './contract-hash.js';
 export type { LLMCaller, LLMCallerConfig, ToolSchema } from './llm-caller.js';
-export { rerankCandidates } from './llm-rerank.js';
+export { llmRerankJudge, rerankCandidates } from './llm-rerank.js';
 export type {
   RerankCandidate,
   RerankDecision,
+  RerankJudge,
   RerankQuery,
 } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';

package/src/llm-rerank.ts

@@ -12,6 +12,7 @@
  * judge restores precision. Combined break-even hit rate is ~10%;
  * realistic workloads observe 30-70%.
  */
+import { MATCHED_INTENT_MAX_CHARS } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 
 /**
@@ -60,11 +61,12 @@ export interface RerankDecision {
    */
   readonly confidence: number;
   /**
-   * Free-text reason from the judge. Surface in trace logs so
+   * Free-text reason from the judge, when it gives one — a judge that
+   * decides without prose sends none (ggui#1235). Surface in trace logs so
    * operators can debug "why didn't this hit." Truncate at the
    * persistence boundary if cardinality is a concern.
    */
-  readonly reason: string;
+  readonly reason?: string;
   /** Wall-clock latency of the LLM call. */
   readonly latencyMs: number;
   /**
@@ -135,7 +137,11 @@ function buildUserMessage(
   for (const c of candidates) {
     lines.push('---');
     lines.push(`  id: ${c.id}`);
-    lines.push(`  intent: ${truncate(c.cachedIntent, 280)}`);
+    // The cap is the protocol's `MATCHED_INTENT_MAX_CHARS`: the same
+    // string the judge reads here is what a judged hit hands back to the
+    // agent as `blueprintMeta.matchedIntent` (ggui#1336), so the two cuts
+    // are one constant, not two literals that happen to agree.
+    lines.push(`  intent: ${truncate(c.cachedIntent, MATCHED_INTENT_MAX_CHARS)}`);
     lines.push(`  contract: ${c.cachedContractSummary}`);
     if (typeof c.cosine === 'number') {
       lines.push(`  cosine: ${c.cosine.toFixed(3)}`);
@@ -273,4 +279,26 @@ export async function rerankCandidates(
 }
 
 // Re-exports for the eval harness — keep public surface explicit.
+/**
+ * The judge seam (ggui#1235): one function from a query and its candidates
+ * to a {@link RerankDecision}. The matcher takes a judge together with the
+ * confidence threshold it was measured on (the pair), so a judge on
+ * another scale never meets a cut calibrated for a different one.
+ * `matchId: null` is a judge's only decline; `confidence` is the judge's
+ * own, compared by the caller against the pair's threshold.
+ */
+export type RerankJudge = (
+  query: RerankQuery,
+  candidates: readonly RerankCandidate[],
+) => Promise<RerankDecision>;
+
+/**
+ * Today's judge as a {@link RerankJudge}: {@link rerankCandidates} bound to
+ * an {@link LLMCaller} — the same prompt, the same tool, the same decision,
+ * so a caller that injects nothing else behaves exactly as before.
+ */
+export function llmRerankJudge(llm: LLMCaller): RerankJudge {
+  return (query, candidates) => rerankCandidates({ llm }, query, candidates);
+}
+
 export { RERANK_SYSTEM_PROMPT, RERANK_TOOL };

package/src/rerank-eval/run-probe-cli.ts

@@ -79,7 +79,9 @@ async function main(): Promise<void> {
     usage.input * HAIKU_4_5_PRICE_INPUT_PER_TOKEN +
     usage.output * HAIKU_4_5_PRICE_OUTPUT_PER_TOKEN;
   const callsMade = report.outcomes.filter(
-    (o) => !/short-circuited/.test(o.decision.reason),
+    // ggui#1235 — `reason` is optional on the seam; a judge with no prose
+    // still made a call.
+    (o) => !/short-circuited/.test(o.decision.reason ?? ''),
   ).length;
   const costPerCall = callsMade === 0 ? 0 : totalCost / callsMade;
   process.stdout.write(