@ggui-ai/negotiator 0.24.0 → 0.26.0

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 { findDroppedEntries, isOnSurvivingEntry, REPAIR_ENTRY_DROPPED, restoreDraftDeclaredMembers } from './preserve-declared-members.js';
 import { draftSeedPropKeys, findDroppedSeedSurfaces, } from './preserve-seed-surfaces.js';
 import { formatValidationFindings, validateActionsVsContext, validateContractCoherence, validateContractRedundancy, } from './contract-validators.js';
 /**
@@ -154,7 +155,7 @@ CONCRETE PATTERNS
     (a) Agent-owned — "show my todos", "an agent-backed todo list that persists across sessions", "render my cart", "the messages in this thread", "the directory contents"
         The AGENT owns the items: it fetched / persists / keeps them in sync. The collection is the agent's data → it goes on PROPSSPEC, seeded at render and refreshed via ggui_amend after each change. This is the ONLY shape that round-trips — contextSpec has no agent-push channel, so an agent-owned list placed there can never be seeded or updated (the UI renders empty). add / delete / toggle are discrete events the agent must witness to persist → declare them on actionSpec (with a matching agentCapabilities tool for each nextStep). Mutability is fine: ggui_amend is exactly how the agent pushes the change.
         propsSpec:   { properties: { todos: {schema: {type: "array", items: {type: "object", properties: {id: {type: "string"}, text: {type: "string"}, done: {type: "boolean"}}, required: ["id", "text", "done"]}}, required: true} } }
-        actionSpec:  { toggleTodo: {label: "Toggle todo", schema: {type: "object", properties: {id: {type: "string"}}, required: ["id"]}, nextStep: "todo_toggle"}, addTodo: {label: "Add todo", schema: {type: "object", properties: {text: {type: "string"}}, required: ["text"]}, nextStep: "todo_add"} }
+        actionSpec:  { toggleTodo: {label: "Toggle todo", schema: {type: "object", properties: {id: {type: "string"}}, required: ["id"]}}, addTodo: {label: "Add todo", schema: {type: "object", properties: {text: {type: "string"}}, required: ["text"]}} }
 
     (b) User-built local — "a todo list where I can add and remove items", "a shopping list", "a checklist I tick off"
         No agent-owned source: the USER assembles the list in the UI and the agent merely observes it. The items are client-originated state → a CONTEXTSPEC slot; OMIT actionSpec (the slot mirror IS the wire — the agent already sees every change). Only when the intent says the agent must persist / sync each change does it become the agent-owned case (a) above.
@@ -460,6 +461,7 @@ const REPAIR_PREAMBLE = `PATCH MODE — you are REPAIRING a contract the agent a
 - PRESERVE every spec the agent declared — ESPECIALLY every propsSpec property (agent-owned render-time seed data the UI needs). Never drop it.
 - Do NOT move data between specs (e.g. propsSpec → contextSpec) unless a finding explicitly requires it. A collection the agent supplies on propsSpec STAYS on propsSpec.
 - Keep the agent's names, shapes, and structure intact wherever the findings do not force a change.
+- KEEP the agent's TOOLBOX: every agentCapabilities.tools entry the draft declares, and every actionSpec[X].nextStep that names one of them. The rules below about tools (declare them only behind a streamSpec source; emit no nextStep) govern only what YOU synthesize from scratch — they never remove a tool or a nextStep the agent declared.
 The four-spec model and placement rules below still hold — but in PATCH MODE they are guardrails for the fix, not a license to re-author.`;
 /**
  * Preservation-failure repair note (L1) — drives a corrective retry when
@@ -674,6 +676,7 @@ export async function synthesizeContract(deps, intent, options) {
             latencyMs: Date.now() - startedAt,
             attempts: 0,
             findings: [],
+            dropped: [],
         };
     }
     const gadgetsSection = composeAvailableGadgetsSection(options?.appGadgets);
@@ -706,6 +709,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 +743,14 @@ 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 a few members per entry; the agent's
+        // DECLARED members (`oneShot` above all) are put back from the draft
+        // deterministically, on every spec, and so is any tool the repair
+        // dropped. Anything the merged tree cannot carry is named rather than
+        // lost (ggui#1421, ggui#1430).
+        const restored = restoreDraftDeclaredMembers(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 +810,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 +827,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 +842,25 @@ 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, or put back, against the contract it finally
+ * returns: the accepted attempt's member drops and restored tools, minus
+ * those on an entry the final contract no longer carries (the entry finding
+ * names that loss once), plus one entry finding per draft entry, on every
+ * spec, that the final contract no longer carries under its key. Where the
+ * overlay itself named an entry it had to un-restore, its finding (which
+ * carries the gate's reason) stands for that entry.
+ */
+function droppedFor(overlayFindings, draft, finalContract, underRepair) {
+    const overlayEntryDrops = new Map(overlayFindings.filter((f) => f.code === REPAIR_ENTRY_DROPPED).map((f) => [f.path, f]));
+    return [
+        ...overlayFindings.filter((f) => f.code !== REPAIR_ENTRY_DROPPED && isOnSurvivingEntry(f, finalContract)),
+        ...findDroppedEntries(draft, finalContract, underRepair).map((f) => overlayEntryDrops.get(f.path) ?? f),
+    ];
+}
 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.26.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.26.0",
+    "@ggui-ai/protocol": "0.26.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/ensure-conforming-contract.ts

@@ -42,8 +42,9 @@ 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';
+import { REPAIR_ENTRY_RESTORED } from './preserve-declared-members.js';
 
 /**
  * How a conforming contract was produced — finer-grained than `origin`,
@@ -77,7 +78,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. */
@@ -137,12 +151,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 +181,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 +226,21 @@ export async function ensureConformingContract(
     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`
+          : ''),
     };
   }
 
@@ -203,7 +256,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 +272,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

@@ -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
@@ -25,9 +28,8 @@
  * 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,

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 } : {}),
   };
 }
 

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;
   }