@ggui-ai/negotiator 0.24.0 → 0.25.0

package/src/normalize-draft.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}
@@ -23,44 +29,33 @@
  * 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: ReadonlySet<string> = new Set(Object.keys(propsSpecSchema.shape));
+const PROP_ENTRY_KEYS: ReadonlySet<string> = new Set(Object.keys(propEntrySchema.shape));
+const CONTEXT_ENTRY_KEYS: ReadonlySet<string> = new Set(Object.keys(contextEntrySchema.shape));
+const ACTION_ENTRY_KEYS: ReadonlySet<string> = new Set(Object.keys(actionEntrySchema.shape));
+const STREAM_ENTRY_KEYS: ReadonlySet<string> = new Set(Object.keys(streamChannelEntrySchema.shape));
+const AGENT_TOOL_KEYS: ReadonlySet<string> = 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: ReadonlySet<string> = new Set(
+  Object.keys(agentToolEntrySchema.shape.toolInfo.shape),
+);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -135,20 +130,56 @@ function cleanAgentToolMap(
  * (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: unknown): readonly string[] {
+  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): name is string => typeof name === 'string'))].filter((name) => {
+    const entry = entries[name];
+    return isRecord(entry) && entry['required'] === undefined;
+  });
+}
+
 export function normalizeDraft(draft: unknown): unknown {
   if (!isRecord(draft)) return draft;
   const out: Record<string, unknown> = { ...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: Record<string, unknown> = {};
-    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;
   }

package/src/preserve-action-members.ts

@@ -0,0 +1,224 @@
+/**
+ * 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,
+  type DataContract,
+  type SuggestionFinding,
+} 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' as const;
+/** A draft action entry the repair no longer carries under its name; path `actionSpec.<name>`. */
+export const REPAIR_ENTRY_DROPPED = 'REPAIR_ENTRY_DROPPED' as const;
+
+type ActionEntry = NonNullable<DataContract['actionSpec']>[string];
+type ActionMember = Exclude<keyof typeof actionEntrySchema.shape, 'label' | 'schema'>;
+
+/**
+ * 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: readonly ActionMember[] = (
+  Object.keys(actionEntrySchema.shape) as (keyof typeof actionEntrySchema.shape)[]
+).filter((k): k is ActionMember => k !== 'label' && k !== 'schema');
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  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: unknown): Record<string, unknown> | undefined {
+  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: ActionEntry, member: ActionMember): ActionEntry {
+  return actionEntrySchema.parse(
+    Object.fromEntries(Object.entries(entry).filter(([key]) => key !== member)),
+  );
+}
+
+function memberDropped(name: string, member: ActionMember, reason: string): SuggestionFinding {
+  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: SuggestionFinding, entryNames: readonly string[]): boolean {
+  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: unknown,
+  candidate: DataContract,
+  underRepair: ReadonlySet<string>,
+): { readonly contract: DataContract; readonly dropped: readonly SuggestionFinding[] } {
+  const draftActions = draftActionSpec(draft);
+  if (draftActions === undefined || candidate.actionSpec === undefined) {
+    return { contract: candidate, dropped: [] };
+  }
+  const dropped: SuggestionFinding[] = [];
+  /** Per entry, the members the overlay put back. */
+  const restored = new Map<string, Set<ActionMember>>();
+  const merged: Record<string, ActionEntry> = {};
+  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: Record<string, unknown> = { ...entry };
+    const put = new Set<ActionMember>();
+    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: Record<string, ActionEntry> = 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: unknown,
+  candidate: DataContract,
+  underRepair: ReadonlySet<string>,
+): readonly SuggestionFinding[] {
+  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/src/rerank-eval/run-probe.ts

@@ -190,7 +190,7 @@ export function formatReport(report: ProbeReport): string {
       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)'}`);
     }
   }
 

package/src/synthesize-contract.ts

@@ -44,9 +44,10 @@ import {
   type GadgetDescriptor,
   type JsonSchema,
 } from '@ggui-ai/protocol';
-import { lintContract, type ContractIssue } from '@ggui-ai/protocol';
+import { lintContract, type ContractIssue, type SuggestionFinding } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 import { normalizeSchema } from './normalize-schema.js';
+import { findDroppedActionEntries, isMemberDropOf, restoreDraftActionMembers } from './preserve-action-members.js';
 import {
   draftSeedPropKeys,
   findDroppedSeedSurfaces,
@@ -102,6 +103,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[];
 }
 
 /**
@@ -837,6 +848,7 @@ export async function synthesizeContract(
       latencyMs: Date.now() - startedAt,
       attempts: 0,
       findings: [],
+      dropped: [],
     };
   }
 
@@ -878,6 +890,10 @@ export async function synthesizeContract(
   const draftSeedKeys =
     options?.draft !== undefined ? draftSeedPropKeys(options.draft) : [];
   let lastValidContract: DataContract | null = null;
+  /** The paths the draft's own findings name — members under repair are not restored. */
+  const underRepair: ReadonlySet<string> = new Set((options?.draftFindings ?? []).map((f) => f.path));
+  /** The member drops of the attempt that produced `lastValidContract`. */
+  let lastValidDropped: readonly SuggestionFinding[] = [];
 
   for (let attempt = 1; attempt <= MAX_SYNTH_ATTEMPTS; attempt++) {
     const userPrompt =
@@ -916,8 +932,13 @@ export async function synthesizeContract(
     }
 
     // `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
@@ -991,6 +1012,7 @@ export async function synthesizeContract(
         // 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);
@@ -1011,6 +1033,7 @@ export async function synthesizeContract(
       latencyMs: Date.now() - startedAt,
       attempts: attempt,
       findings: allFindings,
+      dropped: droppedFor(restored.dropped, options?.draft, validatedContract, underRepair),
     };
   }
 
@@ -1027,9 +1050,30 @@ export async function synthesizeContract(
     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: readonly SuggestionFinding[],
+  draft: unknown,
+  finalContract: DataContract,
+  underRepair: ReadonlySet<string>,
+): readonly SuggestionFinding[] {
+  const survivingEntries = Object.keys(finalContract.actionSpec ?? {});
+  return [
+    ...memberDrops.filter((f) => isMemberDropOf(f, survivingEntries)),
+    ...findDroppedActionEntries(draft, finalContract, underRepair),
+  ];
+}
+
 function parseToolInput(raw: unknown): SynthesizeToolInput | null {
   if (typeof raw !== 'object' || raw === null) return null;
   const obj = raw as Record<string, unknown>;