@ggui-ai/negotiator 0.22.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-caller.d.ts

@@ -24,9 +24,10 @@
  *   model text. Implementations MUST NOT inject tool-use blocks when
  *   the caller didn't request them — the text path is used as a
  *   regex-JSON fallback.
- * - `callStructured?<T>(...)` is OPTIONAL. When present, it MUST
- *   return the input of the supplied `ToolSchema`'s tool, parsed as
- *   `T`, or THROW — never return anything else. It forces the tool
+ * - `callStructured?(...)` is OPTIONAL. When present, it MUST
+ *   return the input of the supplied `ToolSchema`'s tool, as the model
+ *   produced it (`unknown`: the caller parses it; ggui#1317), or THROW —
+ *   never return anything else. It forces the tool
  *   where the model allows that; a model that refuses a forced tool
  *   (the always-thinking family) is asked for it without forcing, so
  *   the call can end with no tool input, and that ending is a throw.
@@ -60,7 +61,7 @@ export interface LLMCaller {
      * this method — consumers detect absence and fall back to regex JSON
      * extraction on the text path.
      */
-    callStructured?<T>(systemPrompt: string, userMessage: string, tool: ToolSchema, maxTokens?: number): Promise<T>;
+    callStructured?(systemPrompt: string, userMessage: string, tool: ToolSchema, maxTokens?: number): Promise<unknown>;
 }
 /**
  * Provider + model selector for factory-style LLM caller

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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;;;;;;;OAOG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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;;;;;;;OAOG;IACH,cAAc,CAAC,CACb,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;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

@@ -24,9 +24,10 @@
  *   model text. Implementations MUST NOT inject tool-use blocks when
  *   the caller didn't request them — the text path is used as a
  *   regex-JSON fallback.
- * - `callStructured?<T>(...)` is OPTIONAL. When present, it MUST
- *   return the input of the supplied `ToolSchema`'s tool, parsed as
- *   `T`, or THROW — never return anything else. It forces the tool
+ * - `callStructured?(...)` is OPTIONAL. When present, it MUST
+ *   return the input of the supplied `ToolSchema`'s tool, as the model
+ *   produced it (`unknown`: the caller parses it; ggui#1317), or THROW —
+ *   never return anything else. It forces the tool
  *   where the model allows that; a model that refuses a forced tool
  *   (the always-thinking family) is asked for it without forcing, so
  *   the call can end with no tool input, and that ending is a throw.

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;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"}
+{"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.22.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.22.0",
-    "@ggui-ai/protocol": "0.22.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-caller.ts

@@ -24,9 +24,10 @@
  *   model text. Implementations MUST NOT inject tool-use blocks when
  *   the caller didn't request them — the text path is used as a
  *   regex-JSON fallback.
- * - `callStructured?<T>(...)` is OPTIONAL. When present, it MUST
- *   return the input of the supplied `ToolSchema`'s tool, parsed as
- *   `T`, or THROW — never return anything else. It forces the tool
+ * - `callStructured?(...)` is OPTIONAL. When present, it MUST
+ *   return the input of the supplied `ToolSchema`'s tool, as the model
+ *   produced it (`unknown`: the caller parses it; ggui#1317), or THROW —
+ *   never return anything else. It forces the tool
  *   where the model allows that; a model that refuses a forced tool
  *   (the always-thinking family) is asked for it without forcing, so
  *   the call can end with no tool input, and that ending is a throw.
@@ -67,12 +68,12 @@ export interface LLMCaller {
    * this method — consumers detect absence and fall back to regex JSON
    * extraction on the text path.
    */
-  callStructured?<T>(
+  callStructured?(
     systemPrompt: string,
     userMessage: string,
     tool: ToolSchema,
     maxTokens?: number,
-  ): Promise<T>;
+  ): Promise<unknown>;
 }
 
 /**

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)}`);
@@ -153,6 +159,7 @@ function truncate(text: string, max: number): string {
   return `${text.slice(0, max - 1)}…`;
 }
 
+/** The rerank tool's input once {@link parseToolInput} has validated it. */
 interface RerankToolInput {
   matchId: string | null;
   confidence: number;
@@ -169,7 +176,7 @@ function clampConfidence(value: unknown): number {
 function parseToolInput(
   raw: unknown,
   candidateIds: ReadonlySet<string>,
-): { matchId: string | null; confidence: number; reason: string } {
+): RerankToolInput {
   if (raw === null || typeof raw !== 'object') {
     return { matchId: null, confidence: 0, reason: 'parse-failed: non-object tool input' };
   }
@@ -241,7 +248,7 @@ export async function rerankCandidates(
 
   let toolInput: unknown;
   try {
-    toolInput = await deps.llm.callStructured<RerankToolInput>(
+    toolInput = await deps.llm.callStructured(
       RERANK_SYSTEM_PROMPT,
       userMessage,
       RERANK_TOOL,
@@ -272,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(

package/src/synth-bench/cli-llm.ts

@@ -99,12 +99,12 @@ export function buildAnthropicLlmCaller(
         'negotiator dev caller: text-mode not exercised — use callStructured',
       );
     },
-    async callStructured<T>(
+    async callStructured(
       systemPrompt: string,
       userMessage: string,
       tool: ToolSchema,
       maxTokens?: number,
-    ): Promise<T> {
+    ): Promise<unknown> {
       // `temperature` deprecated on Haiku 4.5+ — Anthropic rejects with
       // HTTP 400. Residual stochasticity stays bounded via canonical-key
       // normalization downstream.
@@ -162,7 +162,7 @@ export function buildAnthropicLlmCaller(
           `anthropic: no tool_use block in response (stop_reason=${json.stop_reason ?? 'unknown'})`,
         );
       }
-      return toolBlock.input as T;
+      return toolBlock.input;
     },
   };
 }

package/src/synthesize-contract.ts

@@ -634,7 +634,7 @@ async function callSynthesizeTool(
   user: string,
 ): Promise<unknown> {
   if (typeof llm.callStructured === 'function') {
-    return llm.callStructured<SynthesizeToolInput>(
+    return llm.callStructured(
       system,
       user,
       SYNTHESIZE_TOOL,