@ggui-ai/negotiator 0.24.0 → 0.26.0

package/README.md

@@ -1,7 +1,7 @@
 # @ggui-ai/negotiator
 
 Contract-synthesis + match-judge engine for
-[ggui](https://github.com/ggui-ai/ggui)'s handshake.
+[GGUI](https://github.com/ggui-ai/ggui)'s handshake.
 
 Given an agent's draft contract + intent, this package synthesizes (or
 repairs) a conforming `DataContract`, judges blueprint-match candidates for
@@ -35,7 +35,14 @@ pnpm add @ggui-ai/negotiator
 - **`ensureConformingContract(...)`** — the create-path guarantee: validates
   an untrusted draft and, on errors, deterministically normalizes or
   LLM-repairs it so the handshake always returns a contract that passes the
-  backstop. Never throws.
+  backstop. Never throws. A repair keeps every member the draft declared on
+  each entry it keeps under the same key, on every spec (an action's
+  `oneShot` and `nextStep`, a stream's `mode` and `replay`, a tool's
+  `toolInfo.description`, …), puts back any tool the repair dropped
+  (`REPAIR_ENTRY_RESTORED`), and names anything it cannot keep at its own
+  path — the LLM repair as `REPAIR_MEMBER_DROPPED` / `REPAIR_ENTRY_DROPPED`
+  with the gate's reason in the message, the salvaged subset with the
+  gate's code at the cut path — so a declaration is never lost silently.
 - **`rerankCandidates(...)`** — LLM judge that re-ranks blueprint-match
   retrieval candidates (the semantic-match decision used by
   `decideHandshake`).

package/dist/ensure-conforming-contract.d.ts

@@ -62,7 +62,20 @@ export interface EnsureConformingAccepted {
      * warnings on the (valid) draft. On `origin: 'synth'`, the ERROR
      * findings that rejected the agent's draft — so the agent-side model
      * learns what it got wrong, even though we repaired it. On
-     * `salvaged-subset` they include one finding per dropped entry.
+     * `llm-repair` they additionally carry one `REPAIR_MEMBER_DROPPED` per
+     * declared member the repair could not keep, on any spec, one
+     * `REPAIR_ENTRY_DROPPED` per draft entry it no longer carries under its
+     * key, and one `REPAIR_ENTRY_RESTORED` (`warn`) per draft tool the repair
+     * dropped and the overlay put back (ggui#1421, ggui#1430 — a repair
+     * preserves the draft's declarations, `oneShot` above all, and names any
+     * it must drop, each at its own path with the gate's reason in the
+     * message; a member under repair is named by the gate's own finding at
+     * that same path).
+     * The error findings are the union of what the gate refused on the
+     * raw draft and on its normalized form (the gate stops after the
+     * shape phase, so the raw lint alone can hide a semantic finding). On
+     * `salvaged-subset` they include one finding per dropped entry, with
+     * the gate's own code at the cut path.
      */
     readonly findings: readonly SuggestionFinding[];
     /** Operator- + LLM-readable explanation. */

package/dist/ensure-conforming-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-conforming-contract.d.ts","sourceRoot":"","sources":["../src/ensure-conforming-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAC9B,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,iBAAiB,CAAC;AAEtB,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,GAAG,wBAAwB,CAAC;AAEzF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,IAAI,EAAE;IACJ,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD,GACA,OAAO,CAAC,sBAAsB,CAAC,CAkHjC"}
+{"version":3,"file":"ensure-conforming-contract.d.ts","sourceRoot":"","sources":["../src/ensure-conforming-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMjD;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAC9B,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,iBAAiB,CAAC;AAEtB,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,GAAG,wBAAwB,CAAC;AAEzF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,IAAI,EAAE;IACJ,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD,GACA,OAAO,CAAC,sBAAsB,CAAC,CAyJjC"}

package/dist/ensure-conforming-contract.js

@@ -35,8 +35,9 @@
  */
 import { lintContract, dataContractSchema, } from '@ggui-ai/protocol';
 import { synthesizeContract } from './synthesize-contract.js';
-import { normalizeDraft } from './normalize-draft.js';
+import { liftedRequiredNames, normalizeDraft } from './normalize-draft.js';
 import { salvageConformingSubset } from './salvage-draft.js';
+import { REPAIR_ENTRY_RESTORED } from './preserve-declared-members.js';
 export async function ensureConformingContract(deps, args) {
     const lint = lintContract(args.draft);
     const warnFindings = lint.warnings.map((w) => ({
@@ -58,11 +59,22 @@ export async function ensureConformingContract(deps, args) {
             reasoning: 'agent draft passed validateContract; accepted verbatim (origin: agent)',
         };
     }
+    // ggui#1454 — a wrapper-level `propsSpec.required: [...]` is refused by the
+    // gate as an unrecognized key and LIFTED by `normalizeDraft` onto the named
+    // entries (ggui#1432). The finding stays (the draft used a non-wire shape,
+    // and the agent should see that); its message says the key was honoured,
+    // so it reads as a repair, not a refusal to fix and re-handshake for.
+    const lifted = liftedRequiredNames(args.draft);
+    const liftNote = lifted.length > 0
+        ? ` — the wrapper-level \`required\` is not a wire key; it was lifted into ${lifted
+            .map((name) => `propsSpec.properties.${name}.required = true`)
+            .join(', ')} (repaired, not refused)`
+        : '';
     const errorFindings = lint.errors.map((e) => ({
         code: e.code,
         severity: 'error',
         path: e.path,
-        message: e.message,
+        message: e.code === 'CTR_SHAPE_UNRECOGNIZED_KEYS' && e.path === 'propsSpec' ? `${e.message}${liftNote}` : e.message,
     }));
     // L3 — deterministic normalization tier. Most agent malformations are
     // mechanical (stray illegal wrapper keys, non-canonical schema types).
@@ -72,6 +84,25 @@ export async function ensureConformingContract(deps, args) {
     // LLM call). Semantic deficiencies fall through to the repair loop.
     const normalized = normalizeDraft(args.draft);
     const normLint = lintContract(normalized);
+    // The gate stops after the shape phase, so the RAW draft's lint may
+    // name only its mechanical errors while the NORMALIZED draft's lint
+    // reaches the semantic ones (a dangling `nextStep`). Every path the
+    // gate refused on either tree is the agent's to see (ggui#1421): the
+    // union, raw first, one finding per (code, path).
+    const gateFindings = [...errorFindings];
+    for (const e of normLint.errors) {
+        if (!gateFindings.some((f) => f.code === e.code && f.path === e.path)) {
+            gateFindings.push({ code: e.code, severity: 'error', path: e.path, message: e.message });
+        }
+    }
+    /** `gateFindings` plus `more`, one finding per (code, path) — a drop the gate already named is not named twice. */
+    const withGateFindings = (more) => {
+        const out = [...gateFindings];
+        for (const f of more)
+            if (!out.some((g) => g.code === f.code && g.path === f.path))
+                out.push(f);
+        return out;
+    };
     if (normLint.errors.length === 0) {
         return {
             contract: dataContractSchema.parse(normalized),
@@ -95,12 +126,20 @@ export async function ensureConformingContract(deps, args) {
     });
     if (synth.contract !== null &&
         lintContract(synth.contract).errors.length === 0) {
+        const droppedPaths = synth.dropped.filter((d) => d.code !== REPAIR_ENTRY_RESTORED).map((d) => d.path);
+        const restoredPaths = synth.dropped.filter((d) => d.code === REPAIR_ENTRY_RESTORED).map((d) => d.path);
         return {
             contract: synth.contract,
             origin: 'synth',
             method: 'llm-repair',
-            findings: errorFindings,
-            reasoning: `repaired the agent draft to pass validateContract — ${synth.reason}`,
+            findings: withGateFindings(synth.dropped),
+            reasoning: `repaired the agent draft to pass validateContract — ${synth.reason}` +
+                (droppedPaths.length > 0
+                    ? `; dropped ${droppedPaths.length} declared ${droppedPaths.length === 1 ? 'member/entry' : 'members/entries'} the repair could not keep (${droppedPaths.join(', ')}) — each is a finding`
+                    : '') +
+                (restoredPaths.length > 0
+                    ? `; restored ${restoredPaths.length} declared ${restoredPaths.length === 1 ? 'tool' : 'tools'} the repair dropped (${restoredPaths.join(', ')}) — each is a finding`
+                    : ''),
         };
     }
     // Repair impossible (LLM down, provider can't synthesize, or the
@@ -115,7 +154,7 @@ export async function ensureConformingContract(deps, args) {
             contract: salvaged.contract,
             origin: 'synth',
             method: 'salvaged-subset',
-            findings: [...errorFindings, ...salvaged.dropped],
+            findings: withGateFindings(salvaged.dropped),
             reasoning: `could not repair the agent draft within budget (${synth.reason}); ` +
                 `proposing the conforming SUBSET of your draft — dropped ${droppedPaths.length} ` +
                 `entr${droppedPaths.length === 1 ? 'y' : 'ies'} the protocol refused (${droppedPaths.join(', ')}). ` +
@@ -129,7 +168,7 @@ export async function ensureConformingContract(deps, args) {
         contract: null,
         origin: 'agent',
         method: 'declined',
-        findings: errorFindings,
+        findings: gateFindings,
         reasoning: `declined: could not repair the agent draft within budget (${synth.reason}) and no entry of it ` +
             `passes the contract gate — nothing to propose. Fix the findings (every one names its path) ` +
             `and re-handshake; do not render against this handshake.`,

package/dist/index.d.ts

@@ -8,8 +8,11 @@
  *     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`).
+ *   - normalizes untrusted drafts (`normalizeDraft`).
+ *
+ * Contract identity is not this package's: the cache key is
+ * `blueprintKey(contract)` and the variant key is `variantKey(variance)`,
+ * both from `@ggui-ai/protocol/blueprint-key`.
  *
  * The HANDSHAKE DECISION itself (find-similar → reuse vs synth-create)
  * lives in the shared `decideHandshake` core in
@@ -24,9 +27,8 @@
  * 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 type { LLMCaller, LLMCallerConfig, ToolSchema } from './llm-caller.js';
-export { llmRerankJudge, rerankCandidates } from './llm-rerank.js';
+export type { LLMCaller, LLMCallerConfig, Metered, TokenUsage, ToolSchema } from './llm-caller.js';
+export { llmRerankJudge, rerankCandidates, RERANK_SYSTEM_PROMPT } 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';

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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACzF,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

@@ -8,8 +8,11 @@
  *     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`).
+ *   - normalizes untrusted drafts (`normalizeDraft`).
+ *
+ * Contract identity is not this package's: the cache key is
+ * `blueprintKey(contract)` and the variant key is `variantKey(variance)`,
+ * both from `@ggui-ai/protocol/blueprint-key`.
  *
  * The HANDSHAKE DECISION itself (find-similar → reuse vs synth-create)
  * lives in the shared `decideHandshake` core in
@@ -24,8 +27,7 @@
  * 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 { llmRerankJudge, rerankCandidates } from './llm-rerank.js';
+export { llmRerankJudge, rerankCandidates, RERANK_SYSTEM_PROMPT } 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

@@ -35,6 +35,15 @@
  *   that can't produce tool input at all simply omit this method;
  *   consumers fall back to `call` + regex JSON extraction. Absence is
  *   not an error.
+ * - `callStructuredMetered?(...)` is OPTIONAL: `callStructured`'s contract
+ *   (the tool input, or a throw), with the call's token usage beside it
+ *   as the provider reported it. `usage` is ABSENT when the provider
+ *   reported none, never zeros: a consumer reads absence as "unmetered".
+ *   A consumer that has it prefers it to `callStructured`; an
+ *   implementation that cannot read usage omits it, and every caller
+ *   written without it keeps compiling. It is a method rather than a
+ *   usage callback because judges run concurrently, and a result carries
+ *   its own usage where a callback would need correlating to its call.
  * - `ToolSchema.input_schema` follows the OpenAI tool-use JSON
  *   Schema convention. Implementations that use a different
  *   tool-use protocol (e.g., Anthropic's variant) MUST translate at
@@ -46,6 +55,16 @@ export interface ToolSchema {
     description: string;
     input_schema: Record<string, unknown>;
 }
+/** Tokens one provider call consumed, as the provider reported them. */
+export interface TokenUsage {
+    readonly input: number;
+    readonly output: number;
+}
+/** A call's result with the usage the provider reported for it; `usage` absent = unmetered. */
+export interface Metered<T> {
+    readonly value: T;
+    readonly usage?: TokenUsage;
+}
 /** Chat-model dispatcher consumed by the negotiator's synthesis + judge primitives. */
 export interface LLMCaller {
     /**
@@ -62,6 +81,13 @@ export interface LLMCaller {
      * extraction on the text path.
      */
     callStructured?(systemPrompt: string, userMessage: string, tool: ToolSchema, maxTokens?: number): Promise<unknown>;
+    /**
+     * {@link callStructured}, with the call's token usage beside the tool
+     * input (see the normative semantics above). Omit it when the provider's
+     * usage cannot be read; consumers then fall back to `callStructured` and
+     * treat the call as unmetered.
+     */
+    callStructuredMetered?(systemPrompt: string, userMessage: string, tool: ToolSchema, maxTokens?: number): Promise<Metered<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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../src/llm-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+FAA+F;AAC/F,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;CAC7B;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;IAEpB;;;;;OAKG;IACH,qBAAqB,CAAC,CACpB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9B;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

@@ -35,6 +35,15 @@
  *   that can't produce tool input at all simply omit this method;
  *   consumers fall back to `call` + regex JSON extraction. Absence is
  *   not an error.
+ * - `callStructuredMetered?(...)` is OPTIONAL: `callStructured`'s contract
+ *   (the tool input, or a throw), with the call's token usage beside it
+ *   as the provider reported it. `usage` is ABSENT when the provider
+ *   reported none, never zeros: a consumer reads absence as "unmetered".
+ *   A consumer that has it prefers it to `callStructured`; an
+ *   implementation that cannot read usage omits it, and every caller
+ *   written without it keeps compiling. It is a method rather than a
+ *   usage callback because judges run concurrently, and a result carries
+ *   its own usage where a callback would need correlating to its call.
  * - `ToolSchema.input_schema` follows the OpenAI tool-use JSON
  *   Schema convention. Implementations that use a different
  *   tool-use protocol (e.g., Anthropic's variant) MUST translate at

package/dist/llm-rerank.d.ts

@@ -1,4 +1,4 @@
-import type { LLMCaller, ToolSchema } from './llm-caller.js';
+import type { LLMCaller, TokenUsage, ToolSchema } from './llm-caller.js';
 /**
  * One candidate blueprint for the LLM judge to consider.
  *
@@ -53,15 +53,14 @@ export interface RerankDecision {
     /** Wall-clock latency of the LLM call. */
     readonly latencyMs: number;
     /**
-     * Token cost of the call — for the cache-trace sink and cost
-     * accounting. Implementations that can't surface token counts may
-     * report `{input: 0, output: 0}` and the cost-per-call gate will
-     * have to be measured externally.
+     * Tokens the decision cost, as the provider reported them — for the
+     * cache-trace sink and cost accounting. ABSENT means unmetered, never
+     * zero: the judge called a provider and has no count for the call (a
+     * caller without `callStructuredMetered`, a provider that reported no
+     * usage, or a call that threw). `{ input: 0, output: 0 }` is a true
+     * zero: the decision was made without a provider call (ggui#1418).
      */
-    readonly tokenCost: {
-        readonly input: number;
-        readonly output: number;
-    };
+    readonly tokenCost?: TokenUsage;
 }
 /** Query the user's request the judge is matching against. */
 export interface RerankQuery {

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"llm-rerank.d.ts","sourceRoot":"","sources":["../src/llm-rerank.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;;;;;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;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;CACjC;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,CAyDzB;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

@@ -137,7 +137,8 @@ export async function rerankCandidates(deps, query, candidates) {
     }
     const userMessage = buildUserMessage(query, candidates);
     const candidateIds = new Set(candidates.map((c) => c.id));
-    if (typeof deps.llm.callStructured !== 'function') {
+    const { callStructured, callStructuredMetered } = deps.llm;
+    if (typeof callStructuredMetered !== 'function' && typeof callStructured !== 'function') {
         return {
             matchId: null,
             confidence: 0,
@@ -146,9 +147,19 @@ export async function rerankCandidates(deps, query, candidates) {
             tokenCost: { input: 0, output: 0 },
         };
     }
+    // The metered method when the caller has it (its usage is the decision's
+    // cost), else the plain one (unmetered: no tokenCost).
     let toolInput;
+    let usage;
     try {
-        toolInput = await deps.llm.callStructured(RERANK_SYSTEM_PROMPT, userMessage, RERANK_TOOL, 512);
+        if (typeof callStructuredMetered === 'function') {
+            const metered = await callStructuredMetered.call(deps.llm, RERANK_SYSTEM_PROMPT, userMessage, RERANK_TOOL, 512);
+            toolInput = metered.value;
+            usage = metered.usage;
+        }
+        else if (typeof callStructured === 'function') {
+            toolInput = await callStructured.call(deps.llm, RERANK_SYSTEM_PROMPT, userMessage, RERANK_TOOL, 512);
+        }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -157,7 +168,6 @@ export async function rerankCandidates(deps, query, candidates) {
             confidence: 0,
             reason: `llm-rerank: callStructured threw — ${message}`,
             latencyMs: Date.now() - startedAt,
-            tokenCost: { input: 0, output: 0 },
         };
     }
     const parsed = parseToolInput(toolInput, candidateIds);
@@ -166,10 +176,7 @@ export async function rerankCandidates(deps, query, candidates) {
         confidence: parsed.confidence,
         reason: parsed.reason,
         latencyMs: Date.now() - startedAt,
-        // Token cost surfacing requires LLMCaller-level instrumentation
-        // we don't have today. Default to zero; the cost gate is measured
-        // out-of-band from billing data during the probe.
-        tokenCost: { input: 0, output: 0 },
+        ...(usage !== undefined ? { tokenCost: usage } : {}),
     };
 }
 /**

package/dist/normalize-draft.d.ts

@@ -11,6 +11,12 @@
  *
  * This pass fixes the mechanical classes deterministically, preserving
  * the agent's intent exactly:
+ *   - lifts a wrapper-level `propsSpec.required: [...]` (JSON Schema's
+ *     spelling of the same declaration) into each listed entry's
+ *     `required: true` before the key goes — the agent said which props
+ *     are required, and the served contract keeps saying it (ggui#1432);
+ *     an entry's own explicit `required` wins, and a name with no entry
+ *     lifts nothing;
  *   - 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}
@@ -29,5 +35,19 @@
  * (the top-level DataContract schema is `.passthrough()`); only the
  * `.strict()` spec wrappers and entries are cleaned.
  */
+/**
+ * The prop names a wrapper-level `propsSpec.required: [...]` will be
+ * lifted onto by {@link normalizeDraft} (ggui#1432): each listed name that
+ * has an entry and whose entry declares no `required` of its own, in the
+ * wrapper's order and de-duplicated. A ghost name (no entry) and an entry
+ * with its own word are skipped, exactly as the lift skips them. Empty when
+ * nothing lifts.
+ *
+ * One source of truth for the lift and for the finding that reports it
+ * (ggui#1454): the gate's `CTR_SHAPE_UNRECOGNIZED_KEYS` at `propsSpec` is
+ * a repair here, not a refusal, and its message says which entries gained
+ * `required: true`.
+ */
+export declare function liftedRequiredNames(draft: unknown): readonly string[];
 export declare function normalizeDraft(draft: unknown): unknown;
 //# sourceMappingURL=normalize-draft.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"normalize-draft.d.ts","sourceRoot":"","sources":["../src/normalize-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA2GH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA4CtD"}
+{"version":3,"file":"normalize-draft.d.ts","sourceRoot":"","sources":["../src/normalize-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgGH;;;;;;GAMG;AACH;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAUrE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuDtD"}

package/dist/normalize-draft.js

@@ -11,6 +11,12 @@
  *
  * This pass fixes the mechanical classes deterministically, preserving
  * the agent's intent exactly:
+ *   - lifts a wrapper-level `propsSpec.required: [...]` (JSON Schema's
+ *     spelling of the same declaration) into each listed entry's
+ *     `required: true` before the key goes — the agent said which props
+ *     are required, and the served contract keeps saying it (ggui#1432);
+ *     an entry's own explicit `required` wins, and a name with no entry
+ *     lifts nothing;
  *   - 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}
@@ -22,43 +28,23 @@
  * cross-refs) are deliberately out of scope — those still go to the
  * repair loop, where reasoning earns its keep.
  */
+import { actionEntrySchema, agentToolEntrySchema, contextEntrySchema, propEntrySchema, propsSpecSchema, streamChannelEntrySchema, } from '@ggui-ai/protocol';
 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']);
+// Allowed-key sets are DERIVED from the protocol's `.strict()` spec
+// schemas (schemas/data-contract.ts) — never hand-copied. A hand-copied
+// mirror drifts the day the schema grows: `oneShot` joined
+// `actionEntrySchema` on 2026-09-15 (ggui#1108) and a stale mirror here
+// stripped it from every repaired draft for eleven days (ggui#1421).
+// Stripping anything outside these sets is safe: the strict schema
+// would reject it as CTR_SHAPE_UNRECOGNIZED_KEYS.
+const PROPS_WRAPPER_KEYS = new Set(Object.keys(propsSpecSchema.shape));
+const PROP_ENTRY_KEYS = new Set(Object.keys(propEntrySchema.shape));
+const CONTEXT_ENTRY_KEYS = new Set(Object.keys(contextEntrySchema.shape));
+const ACTION_ENTRY_KEYS = new Set(Object.keys(actionEntrySchema.shape));
+const STREAM_ENTRY_KEYS = new Set(Object.keys(streamChannelEntrySchema.shape));
+const AGENT_TOOL_KEYS = new Set(Object.keys(agentToolEntrySchema.shape));
 /** Inner keys of an {@link AgentToolEntry.toolInfo} (the MCP descriptor). */
-const AGENT_TOOL_INFO_KEYS = new Set([
-    'inputSchema',
-    'description',
-    'outputSchema',
-]);
+const AGENT_TOOL_INFO_KEYS = new Set(Object.keys(agentToolEntrySchema.shape.toolInfo.shape));
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -121,21 +107,59 @@ function cleanAgentToolMap(map) {
  * (the top-level DataContract schema is `.passthrough()`); only the
  * `.strict()` spec wrappers and entries are cleaned.
  */
+/**
+ * The prop names a wrapper-level `propsSpec.required: [...]` will be
+ * lifted onto by {@link normalizeDraft} (ggui#1432): each listed name that
+ * has an entry and whose entry declares no `required` of its own, in the
+ * wrapper's order and de-duplicated. A ghost name (no entry) and an entry
+ * with its own word are skipped, exactly as the lift skips them. Empty when
+ * nothing lifts.
+ *
+ * One source of truth for the lift and for the finding that reports it
+ * (ggui#1454): the gate's `CTR_SHAPE_UNRECOGNIZED_KEYS` at `propsSpec` is
+ * a repair here, not a refusal, and its message says which entries gained
+ * `required: true`.
+ */
+export function liftedRequiredNames(draft) {
+    if (!isRecord(draft) || !isRecord(draft['propsSpec']))
+        return [];
+    const wrapper = draft['propsSpec'];
+    if (!Array.isArray(wrapper['required']) || !isRecord(wrapper['properties']))
+        return [];
+    const entries = wrapper['properties'];
+    // De-duplicated: a name the wrapper lists twice lifts once and is reported once.
+    return [...new Set(wrapper['required'].filter((name) => typeof name === 'string'))].filter((name) => {
+        const entry = entries[name];
+        return isRecord(entry) && entry['required'] === undefined;
+    });
+}
 export function normalizeDraft(draft) {
     if (!isRecord(draft))
         return draft;
     const out = { ...draft };
     // propsSpec wrapper: keep {description, properties}; clean each PropEntry.
+    // A wrapper-level `required: [...]` is the agent's declaration in JSON
+    // Schema's spelling — lift it into the listed entries before the key
+    // goes, so the served contract still says which props are required.
     if (isRecord(out['propsSpec'])) {
+        const wrapper = out['propsSpec'];
         const ps = {};
-        for (const [key, value] of Object.entries(out['propsSpec'])) {
+        for (const [key, value] of Object.entries(wrapper)) {
             if (PROPS_WRAPPER_KEYS.has(key))
                 ps[key] = value;
         }
         if (isRecord(ps['properties'])) {
-            ps['properties'] = cleanEntryMap(ps['properties'], PROP_ENTRY_KEYS, [
-                'schema',
-            ]);
+            const cleaned = cleanEntryMap(ps['properties'], PROP_ENTRY_KEYS, ['schema']);
+            // The same selection `liftedRequiredNames` reports (one source of truth);
+            // `cleanEntryMap` keeps an entry's own `required`, so the test is the same on
+            // the cleaned map as on the raw one.
+            for (const name of liftedRequiredNames(draft)) {
+                const entry = cleaned[name];
+                if (!isRecord(entry))
+                    continue;
+                cleaned[name] = { ...entry, required: true };
+            }
+            ps['properties'] = cleaned;
         }
         out['propsSpec'] = ps;
     }