@ggui-ai/negotiator 0.25.0 → 0.26.0

package/dist/preserve-declared-members.js

@@ -0,0 +1,427 @@
+/**
+ * Declared-member preservation: the deterministic backstop that keeps a
+ * repair FAITHFUL to what the agent DECLARED (ggui#1421 for actions,
+ * ggui#1430 for every spec).
+ *
+ * The repair tool authors only a few members per entry:
+ *   - `label` / `schema` on an action;
+ *   - `schema` / `required` on a prop;
+ *   - `schema` / `default` on a context slot;
+ *   - `schema` / `source` on a stream channel;
+ *   - `toolInfo.inputSchema` / `toolInfo.outputSchema` / `usage` on a tool.
+ * Every other member is the agent's declaration: an action's `oneShot` (the
+ * one-shot line keys on it being ON THE SERVED CONTRACT, ggui#1108 →
+ * ggui#1223), a stream's `mode` / `replay` / `complete`, a prop's
+ * `default`, a tool's `toolInfo.description`. A repair that re-emits an entry
+ * from the tool's answer alone drops them silently. So the overlay below puts
+ * the draft's declarations back on the repaired candidate, under the SAME
+ * KEY, and names whatever it cannot keep.
+ *
+ * The toolbox is the agent's too. A repair that drops a tool entry the draft
+ * declared leaves every `nextStep` naming it dangling, so a draft tool the
+ * candidate lacks is restored WHOLE. Only tools: a repair may legitimately
+ * move or remove an action, prop, context or stream entry.
+ *
+ * Findings, each at its own path:
+ *   - `REPAIR_MEMBER_DROPPED` at `<spec>.<name>.<member>`: a declared
+ *     member the merged contract cannot carry (it fails its own schema, or
+ *     the gate refuses it there or, for `nextStep`, as `CTR_SCHEMA_INCOMPAT`
+ *     at the sibling `.schema`);
+ *   - `REPAIR_ENTRY_DROPPED` at `<spec>.<name>`: a draft action, prop,
+ *     context, stream or tool entry the proposal no longer carries under that
+ *     key (renamed, moved or removed), named ONCE; its members are not owed
+ *     one by one. A restored tool the gate refuses is named so, with the
+ *     gate's reason;
+ *   - `REPAIR_ENTRY_RESTORED` at `agentCapabilities.tools.<name>`
+ *     (severity `warn`): a draft tool the repair dropped and the overlay put
+ *     back, so a tool coming back is never silent.
+ *
+ * A member whose path a DRAFT finding already names is under repair: it is
+ * not restored, and its absence is named by that finding. A draft tool with a
+ * finding at or under its path is not restored. Paths follow the gate's
+ * convention (`propsSpec.<name>`, not `propsSpec.properties.<name>`).
+ * Model-independent: the overlay works whatever the repair LLM returns, and
+ * it never makes the proposal fail the gate BECAUSE of what it put back.
+ */
+import { actionEntrySchema, agentToolEntrySchema, contextEntrySchema, CTR_SCHEMA_INCOMPAT, lintContract, propEntrySchema, streamChannelEntrySchema, } from '@ggui-ai/protocol';
+/** A declared member the repair could not keep; path `<spec>.<name>.<member>`. */
+export const REPAIR_MEMBER_DROPPED = 'REPAIR_MEMBER_DROPPED';
+/** A draft entry the proposal no longer carries under its key; path `<spec>.<name>`. */
+export const REPAIR_ENTRY_DROPPED = 'REPAIR_ENTRY_DROPPED';
+/** A draft tool the repair dropped and the overlay restored; path `agentCapabilities.tools.<name>`. */
+export const REPAIR_ENTRY_RESTORED = 'REPAIR_ENTRY_RESTORED';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function recordAt(value, key) {
+    if (value === undefined)
+        return undefined;
+    const at = value[key];
+    return isRecord(at) ? at : undefined;
+}
+function memberDropped(prefix, name, member, reason) {
+    return {
+        code: REPAIR_MEMBER_DROPPED,
+        severity: 'error',
+        path: `${prefix}.${name}.${member}`,
+        message: `the repair could not keep the declared \`${member}\` on '${name}' (${prefix}): ${reason}`,
+    };
+}
+function gateReason(issue) {
+    return `refused by the gate as ${issue.code} at ${issue.path}: ${issue.message}`;
+}
+function specRunner(d) {
+    const topMembers = Object.keys(d.schema.shape).filter((k) => !d.authored.has(k) && k !== d.nested?.member);
+    const nestedMembers = d.nested === undefined ? [] : Object.keys(d.nested.schema.shape).filter((k) => !(d.nested?.authored.has(k) ?? false));
+    const nestedPrefix = d.nested?.member;
+    /** Every member path a finding can carry on an entry, exactly. */
+    const memberPaths = [
+        ...Object.keys(d.schema.shape),
+        ...(d.nested === undefined ? [] : Object.keys(d.nested.schema.shape).map((k) => `${d.nested?.member}.${k}`)),
+    ];
+    const entryPath = (name) => `${d.prefix}.${name}`;
+    /** `entry` without the member at `member` (`a` or `parent.a`), re-derived by the strict schema. */
+    const withoutMember = (entry, member) => {
+        const dot = member.indexOf('.');
+        if (dot === -1)
+            return d.schema.parse(Object.fromEntries(Object.entries(d.asRecord(entry)).filter(([k]) => k !== member)));
+        const parent = member.slice(0, dot);
+        const leaf = member.slice(dot + 1);
+        const copy = { ...d.asRecord(entry) };
+        const inner = recordAt(copy, parent);
+        if (inner !== undefined)
+            copy[parent] = Object.fromEntries(Object.entries(inner).filter(([k]) => k !== leaf));
+        return d.schema.parse(copy);
+    };
+    const withoutEntry = (contract, name) => {
+        const current = d.entries(contract) ?? {};
+        return d.withEntries(contract, Object.fromEntries(Object.entries(current).filter(([k]) => k !== name)));
+    };
+    /** Under repair at or under an entry: the entry path, a member path, or a path inside a member. */
+    const entryUnderRepair = (name, underRepair) => {
+        const base = entryPath(name);
+        if (underRepair.has(base))
+            return true;
+        for (const p of underRepair) {
+            for (const m of memberPaths)
+                if (p === `${base}.${m}` || p.startsWith(`${base}.${m}.`))
+                    return true;
+        }
+        return false;
+    };
+    const sameIssue = (a, b) => a.code === b.code && a.path === b.path;
+    return {
+        prefix: d.prefix,
+        noun: d.noun,
+        overlay(draft, contract, underRepair) {
+            const state = { members: new Map(), entries: new Set() };
+            const dropped = [];
+            const draftEntries = d.draftEntries(draft);
+            if (draftEntries === undefined)
+                return { contract, state, dropped };
+            const current = d.entries(contract) ?? {};
+            const merged = { ...current };
+            for (const [name, entry] of Object.entries(current)) {
+                const draftEntry = recordAt(draftEntries, name);
+                if (draftEntry === undefined)
+                    continue;
+                const next = { ...d.asRecord(entry) };
+                const put = new Set();
+                for (const member of topMembers) {
+                    const value = draftEntry[member];
+                    if (value === undefined || next[member] !== undefined || underRepair.has(`${entryPath(name)}.${member}`))
+                        continue;
+                    const parsed = d.schema.shape[member]?.safeParse(value);
+                    if (parsed === undefined)
+                        continue;
+                    if (!parsed.success) {
+                        dropped.push(memberDropped(d.prefix, name, member, parsed.error.issues[0]?.message ?? 'invalid'));
+                        continue;
+                    }
+                    next[member] = parsed.data;
+                    put.add(member);
+                }
+                if (d.nested !== undefined && nestedPrefix !== undefined) {
+                    const draftInner = recordAt(draftEntry, nestedPrefix);
+                    const inner = recordAt(next, nestedPrefix);
+                    if (draftInner !== undefined && inner !== undefined) {
+                        const nextInner = { ...inner };
+                        for (const member of nestedMembers) {
+                            const path = `${nestedPrefix}.${member}`;
+                            const value = draftInner[member];
+                            if (value === undefined || nextInner[member] !== undefined || underRepair.has(`${entryPath(name)}.${path}`))
+                                continue;
+                            const parsed = d.nested.schema.shape[member]?.safeParse(value);
+                            if (parsed === undefined)
+                                continue;
+                            if (!parsed.success) {
+                                dropped.push(memberDropped(d.prefix, name, path, parsed.error.issues[0]?.message ?? 'invalid'));
+                                continue;
+                            }
+                            nextInner[member] = parsed.data;
+                            put.add(path);
+                        }
+                        next[nestedPrefix] = nextInner;
+                    }
+                }
+                if (put.size === 0)
+                    continue;
+                const reparsed = d.schema.safeParse(next);
+                // The CANDIDATE's own authored members are not an entry yet: the loop's gate retries that.
+                if (!reparsed.success)
+                    continue;
+                merged[name] = reparsed.data;
+                state.members.set(name, put);
+            }
+            if (d.restoresEntries) {
+                // Sorted, so the outcome depends on the draft's content, never on its key order.
+                for (const name of Object.keys(draftEntries).sort()) {
+                    if (Object.hasOwn(current, name) || entryUnderRepair(name, underRepair))
+                        continue;
+                    const parsed = d.schema.safeParse(draftEntries[name]);
+                    if (!parsed.success)
+                        continue;
+                    merged[name] = parsed.data;
+                    state.entries.add(name);
+                }
+            }
+            if (state.members.size === 0 && state.entries.size === 0)
+                return { contract, state, dropped };
+            return { contract: d.withEntries(contract, merged), state, dropped };
+        },
+        unrestoreMembers(contract, state, errors) {
+            const dropped = [];
+            let next = contract;
+            for (const [name, members] of state.members) {
+                for (const member of [...members]) {
+                    const sib = d.sibling?.(member);
+                    const refusal = errors.find((issue) => issue.path === `${entryPath(name)}.${member}`) ??
+                        (sib !== undefined ? errors.find((issue) => issue.code === sib.code && issue.path === `${entryPath(name)}.${sib.segment}`) : undefined);
+                    if (refusal === undefined)
+                        continue;
+                    const entry = d.entries(next)?.[name];
+                    if (entry === undefined)
+                        continue;
+                    next = d.withEntries(next, { ...(d.entries(next) ?? {}), [name]: withoutMember(entry, member) });
+                    members.delete(member);
+                    dropped.push(memberDropped(d.prefix, name, member, gateReason(refusal)));
+                }
+                if (members.size === 0)
+                    state.members.delete(name);
+            }
+            return { contract: next, dropped };
+        },
+        unrestoreOneEntry(contract, state) {
+            if (state.entries.size === 0)
+                return undefined;
+            const withAll = lintContract(contract).errors;
+            // Sorted: when two restored tools fail only together, which one comes back out
+            // depends on their names, never on the draft's key order.
+            for (const name of [...state.entries].sort()) {
+                const without = withoutEntry(contract, name);
+                const base = lintContract(without).errors;
+                const added = withAll.find((issue) => !base.some((b) => sameIssue(b, issue)));
+                if (added === undefined)
+                    continue;
+                state.entries.delete(name);
+                return {
+                    contract: without,
+                    dropped: [
+                        {
+                            code: REPAIR_ENTRY_DROPPED,
+                            severity: 'error',
+                            path: entryPath(name),
+                            message: `the repair dropped the ${d.noun} '${name}' you declared, and restoring it from your draft would fail the gate (${gateReason(added)}); declare it again in a form the gate accepts, via ggui_render override or a corrected re-handshake`,
+                        },
+                    ],
+                };
+            }
+            return undefined;
+        },
+        restoredFindings(state) {
+            return [...state.entries].sort().map((name) => ({
+                code: REPAIR_ENTRY_RESTORED,
+                severity: 'warn',
+                path: entryPath(name),
+                message: `the repair dropped the ${d.noun} '${name}' you declared; it is restored from your draft, because the toolbox is yours to declare`,
+            }));
+        },
+        droppedKeys(draft, contract) {
+            const draftEntries = d.draftEntries(draft);
+            if (draftEntries === undefined)
+                return [];
+            const kept = d.entries(contract) ?? {};
+            return Object.keys(draftEntries).filter((name) => !Object.hasOwn(kept, name));
+        },
+        onSurvivingEntry(path, contract) {
+            const kept = d.entries(contract);
+            if (kept === undefined)
+                return false;
+            return Object.keys(kept).some((name) => {
+                const base = entryPath(name);
+                return path === base || memberPaths.some((m) => path === `${base}.${m}`);
+            });
+        },
+    };
+}
+/** The five specs, in the order a finding list names them. */
+const RUNNERS = [
+    specRunner({
+        prefix: 'actionSpec',
+        noun: 'action',
+        schema: actionEntrySchema,
+        authored: new Set(['label', 'schema']),
+        restoresEntries: false,
+        sibling: (member) => (member === 'nextStep' ? { segment: 'schema', code: CTR_SCHEMA_INCOMPAT } : undefined),
+        draftEntries: (draft) => recordAt(draft, 'actionSpec'),
+        asRecord: (entry) => ({ ...entry }),
+        entries: (contract) => contract.actionSpec,
+        withEntries: (contract, entries) => ({ ...contract, actionSpec: entries }),
+    }),
+    specRunner({
+        prefix: 'propsSpec',
+        noun: 'prop',
+        schema: propEntrySchema,
+        authored: new Set(['schema', 'required']),
+        restoresEntries: false,
+        draftEntries: (draft) => recordAt(recordAt(draft, 'propsSpec'), 'properties'),
+        asRecord: (entry) => ({ ...entry }),
+        entries: (contract) => contract.propsSpec?.properties,
+        withEntries: (contract, entries) => ({ ...contract, propsSpec: { ...contract.propsSpec, properties: entries } }),
+    }),
+    specRunner({
+        prefix: 'contextSpec',
+        noun: 'context slot',
+        schema: contextEntrySchema,
+        authored: new Set(['schema', 'default']),
+        restoresEntries: false,
+        draftEntries: (draft) => recordAt(draft, 'contextSpec'),
+        asRecord: (entry) => ({ ...entry }),
+        entries: (contract) => contract.contextSpec,
+        withEntries: (contract, entries) => ({ ...contract, contextSpec: entries }),
+    }),
+    specRunner({
+        prefix: 'streamSpec',
+        noun: 'stream channel',
+        schema: streamChannelEntrySchema,
+        authored: new Set(['schema', 'source']),
+        restoresEntries: false,
+        draftEntries: (draft) => recordAt(draft, 'streamSpec'),
+        asRecord: (entry) => ({ ...entry }),
+        entries: (contract) => contract.streamSpec,
+        withEntries: (contract, entries) => ({ ...contract, streamSpec: entries }),
+    }),
+    specRunner({
+        prefix: 'agentCapabilities.tools',
+        noun: 'tool',
+        schema: agentToolEntrySchema,
+        authored: new Set(['toolInfo', 'usage']),
+        nested: { member: 'toolInfo', schema: agentToolEntrySchema.shape.toolInfo, authored: new Set(['inputSchema', 'outputSchema']) },
+        restoresEntries: true,
+        draftEntries: (draft) => recordAt(recordAt(draft, 'agentCapabilities'), 'tools'),
+        asRecord: (entry) => ({ ...entry }),
+        entries: (contract) => contract.agentCapabilities?.tools,
+        withEntries: (contract, entries) => ({ ...contract, agentCapabilities: { ...contract.agentCapabilities, tools: entries } }),
+    }),
+];
+/**
+ * Overlay the draft's declarations onto the candidate: every declared member
+ * of every entry the candidate carries under the same key (keeping what the
+ * repair authors), and every draft tool the candidate dropped, whole. A
+ * member or tool whose 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`) and every
+ * restored tool whose presence adds a gate error, naming each one, so the
+ * returned contract never fails the gate BECAUSE of the overlay. A malformed
+ * candidate entry is left un-overlaid for the loop's own gate to retry;
+ * nothing here throws on the model's answer. Entries the candidate moved or
+ * removed (other than tools) get nothing back here: see
+ * {@link findDroppedEntries}.
+ */
+export function restoreDraftDeclaredMembers(draft, candidate, underRepair) {
+    if (!isRecord(draft))
+        return { contract: candidate, dropped: [] };
+    let contract = candidate;
+    const dropped = [];
+    const states = [];
+    for (const runner of RUNNERS) {
+        const result = runner.overlay(draft, contract, underRepair);
+        contract = result.contract;
+        dropped.push(...result.dropped);
+        states.push(result.state);
+    }
+    const restoredCount = () => states.reduce((n, s) => n + s.entries.size + [...s.members.values()].reduce((m, set) => m + set.size, 0), 0);
+    if (restoredCount() === 0)
+        return { contract, dropped };
+    // Cross-reference and compatibility errors exist only on the MERGED tree.
+    // Each pass un-restores at least one member or entry, or stops, so the
+    // loop is bounded by what was restored.
+    for (let pass = 0, budget = restoredCount() + 1; pass < budget; pass += 1) {
+        const errors = lintContract(contract).errors;
+        let changed = false;
+        RUNNERS.forEach((runner, i) => {
+            const state = states[i];
+            if (state === undefined)
+                return;
+            const result = runner.unrestoreMembers(contract, state, errors);
+            if (result.dropped.length > 0)
+                changed = true;
+            contract = result.contract;
+            dropped.push(...result.dropped);
+        });
+        if (!changed) {
+            for (const [i, runner] of RUNNERS.entries()) {
+                const state = states[i];
+                if (state === undefined)
+                    continue;
+                const result = runner.unrestoreOneEntry(contract, state);
+                if (result === undefined)
+                    continue;
+                contract = result.contract;
+                dropped.push(...result.dropped);
+                changed = true;
+                break;
+            }
+        }
+        if (!changed || restoredCount() === 0)
+            break;
+    }
+    RUNNERS.forEach((runner, i) => {
+        const state = states[i];
+        if (state !== undefined)
+            dropped.push(...runner.restoredFindings(state));
+    });
+    return { contract, dropped };
+}
+/**
+ * Whether `finding` sits on an entry `contract` still carries: at its exact
+ * entry path or one of its member paths, never by dotted prefix (an action
+ * named `a` is not a prefix of `a.b`). Used to keep a repair's member and
+ * restore findings only for entries the final proposal carries.
+ */
+export function isOnSurvivingEntry(finding, contract) {
+    return RUNNERS.some((runner) => runner.onSurvivingEntry(finding.path, contract));
+}
+/**
+ * One `REPAIR_ENTRY_DROPPED` per draft entry, on every spec, that the
+ * candidate no longer carries under its key: renamed, moved or removed by the
+ * repair, or pruned by the loop's own placement pass. Its members are not
+ * owed one by one. When the gate refused the NAME itself (`CTR_DUP_NAME` /
+ * `CTR_RESERVED_NAME` at `<spec>.<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.
+ */
+export function findDroppedEntries(draft, candidate, underRepair) {
+    if (!isRecord(draft))
+        return [];
+    return RUNNERS.flatMap((runner) => runner.droppedKeys(draft, candidate).map((name) => {
+        const path = `${runner.prefix}.${name}`;
+        const message = underRepair.has(path)
+            ? `the gate refused the ${runner.noun} name '${name}' (see the finding at this path) and the repair removed or renamed it; every member it carried went with it — declare those members again under a name the gate accepts, via ggui_render override or a corrected re-handshake`
+            : runner.prefix === 'actionSpec'
+                ? `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`
+                : `the repair no longer carries the ${runner.noun} '${name}' you declared under that key (renamed, moved or removed); every member it carried went with it — re-declare it via ggui_render override or a corrected re-handshake`;
+        return { code: REPAIR_ENTRY_DROPPED, severity: 'error', path, message };
+    }));
+}

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;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"}
+{"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;AAyRF;;;;;;;;;;;;;;;;;;;;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,CAuNnC;AA2VD;;;;;;;;;;;;;;;;;;;;;;;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,7 +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 { 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';
 /**
@@ -155,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.
@@ -461,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
@@ -743,11 +744,12 @@ export async function synthesizeContract(deps, intent, options) {
         }
         // `buildContract` normalizes every emitted schema (invalid `type`
         // 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);
+        // 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
@@ -844,17 +846,19 @@ export async function synthesizeContract(deps, intent, options) {
     };
 }
 /**
- * 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.
+ * 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(memberDrops, draft, finalContract, underRepair) {
-    const survivingEntries = Object.keys(finalContract.actionSpec ?? {});
+function droppedFor(overlayFindings, draft, finalContract, underRepair) {
+    const overlayEntryDrops = new Map(overlayFindings.filter((f) => f.code === REPAIR_ENTRY_DROPPED).map((f) => [f.path, f]));
     return [
-        ...memberDrops.filter((f) => isMemberDropOf(f, survivingEntries)),
-        ...findDroppedActionEntries(draft, finalContract, underRepair),
+        ...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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/negotiator",
-  "version": "0.25.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.25.0",
-    "@ggui-ai/protocol": "0.25.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

@@ -44,6 +44,7 @@ import type { LLMCaller } from './llm-caller.js';
 import { synthesizeContract } from './synthesize-contract.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`,
@@ -78,12 +79,14 @@ export interface EnsureConformingAccepted {
    * findings that rejected the agent's draft — so the agent-side model
    * learns what it got wrong, even though we repaired it. On
    * `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).
+   * 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
@@ -223,7 +226,8 @@ export async function ensureConformingContract(
     synth.contract !== null &&
     lintContract(synth.contract).errors.length === 0
   ) {
-    const droppedPaths = synth.dropped.map((d) => d.path);
+    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',
@@ -232,7 +236,10 @@ export async function ensureConformingContract(
       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`
+          ? `; 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`
           : ''),
     };
   }

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,7 +28,6 @@
  * consumers need. Each additive export carries semver weight.
  */
 
-export { hashContract, buildVariant } from './contract-hash.js';
 export type { LLMCaller, LLMCallerConfig, Metered, TokenUsage, ToolSchema } from './llm-caller.js';
 export { llmRerankJudge, rerankCandidates, RERANK_SYSTEM_PROMPT } from './llm-rerank.js';
 export type {