@ggui-ai/negotiator 0.24.0 → 0.25.0

package/dist/preserve-action-members.js

@@ -0,0 +1,199 @@
+/**
+ * Action-entry member preservation — the deterministic backstop that
+ * keeps a repair FAITHFUL to what the agent DECLARED on its actions
+ * (ggui#1421).
+ *
+ * The repair tool authors exactly two members per action, `label` and
+ * `schema` (`SYNTHESIZE_TOOL`); every other member of an
+ * {@link ActionEntry} — `description`, `example`, `icon`, `confirm`,
+ * `oneShot`, `nextStep` — is the agent's declaration, and the whole
+ * one-shot line (ggui#1108 → ggui#1223: the runtime's second-dispatch
+ * guard, the server's spend record, ui-gen's `useActionSpent` binding)
+ * keys on `oneShot === true` being ON THE SERVED CONTRACT. A repair that
+ * re-emits an entry from the tool's answer alone serves a card with no
+ * guard, silently. So the overlay below puts the draft's declarations
+ * back on the repaired candidate, deterministically, and NAMES whatever
+ * it cannot keep:
+ *
+ *   - `REPAIR_MEMBER_DROPPED` at `actionSpec.<name>.<member>` — a
+ *     declared member the merged contract cannot carry (the gate refuses
+ *     it there, e.g. a `nextStep` whose tool the repair did not
+ *     re-declare, or a member that fails its own schema);
+ *   - `REPAIR_ENTRY_DROPPED` at `actionSpec.<name>` — a draft action the
+ *     candidate no longer carries under that name (renamed or removed),
+ *     which takes every member with it.
+ *
+ * A member whose path a DRAFT finding already names is under repair: it
+ * is not restored, and its absence is named by that finding, at the same
+ * path. Every other loss is named HERE, at the member's or the entry's
+ * own path, with the gate's reason in the message — so the invariant an
+ * agent can rely on is one sentence: a declared member or action missing
+ * from the served proposal always has a finding at its own path. The
+ * `CTR_*` codes say what the gate refused; the `REPAIR_*` codes say what
+ * the served proposal does not carry of the declaration, and why. The
+ * codes are handshake-decision codes like `COVERAGE_GAP` — declared where
+ * they are emitted, read by the agent as strings in `validationFindings`.
+ * Model-independent: the overlay works whatever the repair LLM returns.
+ */
+import { actionEntrySchema, CTR_SCHEMA_INCOMPAT, lintContract, } from '@ggui-ai/protocol';
+/** A declared action-entry member the repair could not keep; path `actionSpec.<name>.<member>`. */
+export const REPAIR_MEMBER_DROPPED = 'REPAIR_MEMBER_DROPPED';
+/** A draft action entry the repair no longer carries under its name; path `actionSpec.<name>`. */
+export const REPAIR_ENTRY_DROPPED = 'REPAIR_ENTRY_DROPPED';
+/**
+ * The members the agent declares — the protocol's action-entry schema
+ * minus the pair the repair tool authors. Derived, never listed, so a
+ * new schema member is preserved the day it lands.
+ */
+const DECLARED_MEMBERS = Object.keys(actionEntrySchema.shape).filter((k) => k !== 'label' && k !== 'schema');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The draft's `actionSpec` map when it is one; `undefined` otherwise (the draft is untrusted). */
+function draftActionSpec(draft) {
+    if (!isRecord(draft))
+        return undefined;
+    const actionSpec = draft['actionSpec'];
+    return isRecord(actionSpec) ? actionSpec : undefined;
+}
+/**
+ * `entry` without `member`. Removing an optional member from a parsed
+ * entry leaves a parsed entry, so the strict re-parse re-derives the
+ * typed shape without a cast.
+ */
+function withoutMember(entry, member) {
+    return actionEntrySchema.parse(Object.fromEntries(Object.entries(entry).filter(([key]) => key !== member)));
+}
+function memberDropped(name, member, reason) {
+    return {
+        code: REPAIR_MEMBER_DROPPED,
+        severity: 'error',
+        path: `actionSpec.${name}.${member}`,
+        message: `the repair could not keep the declared \`${member}\` on action '${name}': ${reason}`,
+    };
+}
+/**
+ * Whether `finding` is a member drop on one of `entryNames` — matched by
+ * the exact `actionSpec.<name>.<member>` path per declared member, never
+ * by a dotted prefix (an action named `a` is not a prefix of `a.b`).
+ */
+export function isMemberDropOf(finding, entryNames) {
+    return entryNames.some((name) => DECLARED_MEMBERS.some((member) => finding.path === `actionSpec.${name}.${member}`));
+}
+/**
+ * Overlay the draft's declared members onto the candidate's action
+ * entries (same name), keeping the candidate's `label` and `schema`. A
+ * member whose exact path a draft finding names is under repair and
+ * stays out. Then lint the merged contract and un-restore, until the
+ * tree is stable, every restored member the gate refuses — at its own
+ * path, or (for `nextStep`) as `CTR_SCHEMA_INCOMPAT` at the sibling
+ * `.schema`, the path the compatibility check reports on — naming each
+ * one, so the returned contract never fails the gate BECAUSE of the
+ * overlay. A malformed candidate entry (no `label`) is left un-overlaid
+ * for the loop's own gate to retry; nothing here throws on the model's
+ * answer. Entries the candidate does not carry get nothing back here —
+ * see {@link findDroppedActionEntries}.
+ */
+export function restoreDraftActionMembers(draft, candidate, underRepair) {
+    const draftActions = draftActionSpec(draft);
+    if (draftActions === undefined || candidate.actionSpec === undefined) {
+        return { contract: candidate, dropped: [] };
+    }
+    const dropped = [];
+    /** Per entry, the members the overlay put back. */
+    const restored = new Map();
+    const merged = {};
+    for (const [name, entry] of Object.entries(candidate.actionSpec)) {
+        const draftEntry = Object.hasOwn(draftActions, name) ? draftActions[name] : undefined;
+        if (!isRecord(draftEntry)) {
+            merged[name] = entry;
+            continue;
+        }
+        const next = { ...entry };
+        const put = new Set();
+        for (const member of DECLARED_MEMBERS) {
+            const value = draftEntry[member];
+            if (value === undefined || entry[member] !== undefined || underRepair.has(`actionSpec.${name}.${member}`))
+                continue;
+            const parsed = actionEntrySchema.shape[member].safeParse(value);
+            if (!parsed.success) {
+                dropped.push(memberDropped(name, member, parsed.error.issues[0]?.message ?? 'invalid'));
+                continue;
+            }
+            next[member] = parsed.data;
+            put.add(member);
+        }
+        const reparsed = actionEntrySchema.safeParse(next);
+        if (put.size === 0 || !reparsed.success) {
+            // Nothing to put back, or the CANDIDATE's own label/schema are not
+            // an entry yet — the loop's gate retries that; not this overlay's.
+            merged[name] = entry;
+            continue;
+        }
+        merged[name] = reparsed.data;
+        restored.set(name, put);
+    }
+    let actionSpec = merged;
+    if (restored.size === 0)
+        return { contract: { ...candidate, actionSpec }, dropped };
+    // Cross-reference and compatibility errors only exist on the MERGED
+    // tree. Un-restore exactly the members the gate names — at their own
+    // path, or a `nextStep` as `CTR_SCHEMA_INCOMPAT` at the sibling
+    // `.schema`, the path the compatibility check reports on — naming each
+    // at ITS OWN path with the gate's reason; re-lint, and stop when a pass
+    // changes nothing. Every pass removes at least one member, so the loop
+    // is bounded by what was restored.
+    for (let pass = 0; pass < DECLARED_MEMBERS.length * restored.size + 1; pass += 1) {
+        const errors = lintContract({ ...candidate, actionSpec }).errors;
+        let changed = false;
+        for (const [name, members] of restored) {
+            for (const member of [...members]) {
+                const refusal = errors.find((issue) => issue.path === `actionSpec.${name}.${member}`) ??
+                    (member === 'nextStep'
+                        ? errors.find((issue) => issue.code === CTR_SCHEMA_INCOMPAT && issue.path === `actionSpec.${name}.schema`)
+                        : undefined);
+                if (refusal === undefined)
+                    continue;
+                const entry = actionSpec[name];
+                if (entry === undefined)
+                    continue;
+                actionSpec = { ...actionSpec, [name]: withoutMember(entry, member) };
+                members.delete(member);
+                dropped.push(memberDropped(name, member, `refused by the gate as ${refusal.code} at ${refusal.path}: ${refusal.message}`));
+                changed = true;
+            }
+            if (members.size === 0)
+                restored.delete(name);
+        }
+        if (!changed || restored.size === 0)
+            break;
+    }
+    return { contract: { ...candidate, actionSpec }, dropped };
+}
+/**
+ * One `REPAIR_ENTRY_DROPPED` per draft action entry the candidate no
+ * longer carries under that name — renamed or removed by the repair (or
+ * pruned by the loop's own placement pass) — always, because the members
+ * it carried (`oneShot` above all) went with it and nothing else names
+ * that. When the gate refused the NAME itself (`CTR_DUP_NAME` /
+ * `CTR_RESERVED_NAME` at `actionSpec.<name>`, so the path is under
+ * repair) the message says so and does not send the agent back to a
+ * name the gate will refuse again. Empty when every draft entry survived,
+ * and for drafts that declare no actions.
+ */
+export function findDroppedActionEntries(draft, candidate, underRepair) {
+    const draftActions = draftActionSpec(draft);
+    if (draftActions === undefined)
+        return [];
+    const kept = candidate.actionSpec ?? {};
+    return Object.keys(draftActions)
+        .filter((name) => !Object.hasOwn(kept, name))
+        .map((name) => ({
+        code: REPAIR_ENTRY_DROPPED,
+        severity: 'error',
+        path: `actionSpec.${name}`,
+        message: underRepair.has(`actionSpec.${name}`)
+            ? `the gate refused the action name '${name}' (see the finding at this path) and the repair removed or renamed it; every member it carried, oneShot included, went with it — declare those members again under a name the gate accepts, via ggui_render override or a corrected re-handshake`
+            : `the repair no longer carries the action '${name}' you declared (renamed or removed); every member it carried, oneShot included, went with it — re-declare it via ggui_render override or a corrected re-handshake`,
+    }));
+}

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

@@ -106,7 +106,7 @@ export function formatReport(report) {
         lines.push('Failed predictions:');
         for (const o of failed) {
             lines.push(`  [${o.pair.kind}] ${o.pair.id}: predicted=${o.predictedMatchId ?? 'null'}, gold=${o.pair.goldMatchId ?? 'null'}, conf=${o.decision.confidence.toFixed(2)}`);
-            lines.push(`    reason: ${o.decision.reason}`);
+            lines.push(`    reason: ${o.decision.reason ?? '(none)'}`);
         }
     }
     return lines.join('\n');

package/dist/synthesize-contract.d.ts

@@ -37,6 +37,7 @@
  * contract-aware agents skip synthesis entirely.
  */
 import { type DataContract, type GadgetDescriptor } from '@ggui-ai/protocol';
+import { type SuggestionFinding } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 import { type ContractValidationFinding } from './contract-validators.js';
 /** Result of one synthesis attempt. */
@@ -62,6 +63,16 @@ export interface SynthesizeContractResult {
      * findings without re-running the detector.
      */
     readonly findings: readonly ContractValidationFinding[];
+    /**
+     * What a repair-in-place could NOT keep of the agent's draft
+     * (ggui#1421): one `REPAIR_MEMBER_DROPPED` per declared action-entry
+     * member the merged contract cannot carry, one `REPAIR_ENTRY_DROPPED`
+     * per draft action the contract no longer carries under its name.
+     * Empty on the cold path (no draft) and whenever every declaration
+     * survived. The caller surfaces these to the agent beside the gate's
+     * own findings, so a drop is never silent.
+     */
+    readonly dropped: readonly SuggestionFinding[];
 }
 /**
  * Tool schema the synthesizer's structured-output call uses. The

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

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

package/dist/synthesize-contract.js

@@ -39,6 +39,7 @@
 import { dataContractSchema, gadgetExportName, } from '@ggui-ai/protocol';
 import { lintContract } from '@ggui-ai/protocol';
 import { normalizeSchema } from './normalize-schema.js';
+import { findDroppedActionEntries, isMemberDropOf, restoreDraftActionMembers } from './preserve-action-members.js';
 import { draftSeedPropKeys, findDroppedSeedSurfaces, } from './preserve-seed-surfaces.js';
 import { formatValidationFindings, validateActionsVsContext, validateContractCoherence, validateContractRedundancy, } from './contract-validators.js';
 /**
@@ -674,6 +675,7 @@ export async function synthesizeContract(deps, intent, options) {
             latencyMs: Date.now() - startedAt,
             attempts: 0,
             findings: [],
+            dropped: [],
         };
     }
     const gadgetsSection = composeAvailableGadgetsSection(options?.appGadgets);
@@ -706,6 +708,10 @@ export async function synthesizeContract(deps, intent, options) {
     // preservation never makes the result WORSE than the validity-only gate.
     const draftSeedKeys = options?.draft !== undefined ? draftSeedPropKeys(options.draft) : [];
     let lastValidContract = null;
+    /** The paths the draft's own findings name — members under repair are not restored. */
+    const underRepair = new Set((options?.draftFindings ?? []).map((f) => f.path));
+    /** The member drops of the attempt that produced `lastValidContract`. */
+    let lastValidDropped = [];
     for (let attempt = 1; attempt <= MAX_SYNTH_ATTEMPTS; attempt++) {
         const userPrompt = repairNote === undefined
             ? baseUserPrompt
@@ -736,8 +742,13 @@ export async function synthesizeContract(deps, intent, options) {
             continue;
         }
         // `buildContract` normalizes every emitted schema (invalid `type`
-        // spellings → canonical JSON Schema) before the gate sees it.
-        const contract = buildContract(parsed);
+        // spellings → canonical JSON Schema) before the gate sees it. On a
+        // repair-in-place it authors only `{label, schema}` per action; the
+        // agent's DECLARED members (`oneShot` above all) are put back from
+        // the draft deterministically, and anything the merged tree cannot
+        // carry is named rather than lost (ggui#1421).
+        const restored = restoreDraftActionMembers(options?.draft, buildContract(parsed), underRepair);
+        const contract = restored.contract;
         // Defensive gate: re-validate the assembled contract against the
         // canonical schema. Catches LLM outputs that pass the loose tool
         // input_schema but produce structurally invalid contracts. Without
@@ -797,6 +808,7 @@ export async function synthesizeContract(deps, intent, options) {
                 // Remember the best VALID candidate so an exhausted budget never
                 // returns WORSE than the validity-only gate did (a valid contract).
                 lastValidContract = validatedContract;
+                lastValidDropped = restored.dropped;
                 lastReason = `synthesize-preservation: candidate dropped agent-owned propsSpec seed surface(s) [${dropped.join(', ')}]`;
                 lastFindings = allFindings;
                 repairNote = buildPreservationRepairNote(validatedContract, dropped);
@@ -813,6 +825,7 @@ export async function synthesizeContract(deps, intent, options) {
             latencyMs: Date.now() - startedAt,
             attempts: attempt,
             findings: allFindings,
+            dropped: droppedFor(restored.dropped, options?.draft, validatedContract, underRepair),
         };
     }
     // Budget exhausted. If preservation retries never landed a contract
@@ -827,8 +840,23 @@ export async function synthesizeContract(deps, intent, options) {
         latencyMs: Date.now() - startedAt,
         attempts: MAX_SYNTH_ATTEMPTS,
         findings: lastFindings,
+        dropped: lastValidContract !== null ? droppedFor(lastValidDropped, options?.draft, lastValidContract, underRepair) : [],
     };
 }
+/**
+ * What a repair could not keep, against the contract it finally
+ * returns: the member drops of the accepted attempt, minus those on an
+ * entry the loop's own placement pass pruned afterwards (the entry
+ * finding names that loss once, with every member), plus one entry
+ * finding per draft action the final contract no longer carries.
+ */
+function droppedFor(memberDrops, draft, finalContract, underRepair) {
+    const survivingEntries = Object.keys(finalContract.actionSpec ?? {});
+    return [
+        ...memberDrops.filter((f) => isMemberDropOf(f, survivingEntries)),
+        ...findDroppedActionEntries(draft, finalContract, underRepair),
+    ];
+}
 function parseToolInput(raw) {
     if (typeof raw !== 'object' || raw === null)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/negotiator",
-  "version": "0.24.0",
+  "version": "0.25.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.24.0",
-    "@ggui-ai/protocol": "0.24.0"
+    "@ggui-ai/mcp-server-core": "0.25.0",
+    "@ggui-ai/protocol": "0.25.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/ensure-conforming-contract.ts

@@ -42,7 +42,7 @@ import {
 } from '@ggui-ai/protocol';
 import type { LLMCaller } from './llm-caller.js';
 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';
 
 /**
@@ -77,7 +77,18 @@ 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 action-entry member the repair could not keep and one
+   * `REPAIR_ENTRY_DROPPED` per draft action it no longer carries
+   * (ggui#1421 — 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. */
@@ -137,12 +148,25 @@ export async function ensureConformingContract(
     };
   }
 
+  // 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: SuggestionFinding[] = lint.errors.map(
     (e): SuggestionFinding => ({
       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,
     }),
   );
 
@@ -154,6 +178,23 @@ export async function ensureConformingContract(
   // 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: SuggestionFinding[] = [...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: readonly SuggestionFinding[]): SuggestionFinding[] => {
+    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),
@@ -182,12 +223,17 @@ export async function ensureConformingContract(
     synth.contract !== null &&
     lintContract(synth.contract).errors.length === 0
   ) {
+    const droppedPaths = synth.dropped.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 action ${droppedPaths.length === 1 ? 'member/entry' : 'members/entries'} the repair could not keep (${droppedPaths.join(', ')}) — each is a finding`
+          : ''),
     };
   }
 
@@ -203,7 +249,7 @@ export async function ensureConformingContract(
       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} ` +
@@ -219,7 +265,7 @@ export async function ensureConformingContract(
     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) ` +

package/src/index.ts

@@ -26,8 +26,8 @@
  */
 
 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,

package/src/llm-caller.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
@@ -48,6 +57,18 @@ export interface ToolSchema {
   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 {
   /**
@@ -74,6 +95,19 @@ export interface LLMCaller {
     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>>;
 }
 
 /**

package/src/llm-rerank.ts

@@ -13,7 +13,7 @@
  * realistic workloads observe 30-70%.
  */
 import { MATCHED_INTENT_MAX_CHARS } from '@ggui-ai/protocol';
-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.
@@ -70,12 +70,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. */
@@ -235,7 +237,8 @@ export async function rerankCandidates(
   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,
@@ -246,14 +249,18 @@ export async function rerankCandidates(
     };
   }
 
+  // The metered method when the caller has it (its usage is the decision's
+  // cost), else the plain one (unmetered: no tokenCost).
   let toolInput: unknown;
+  let usage: TokenUsage | undefined;
   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);
     return {
@@ -261,7 +268,6 @@ export async function rerankCandidates(
       confidence: 0,
       reason: `llm-rerank: callStructured threw — ${message}`,
       latencyMs: Date.now() - startedAt,
-      tokenCost: { input: 0, output: 0 },
     };
   }
 
@@ -271,10 +277,7 @@ export async function rerankCandidates(
     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 } : {}),
   };
 }