@ggui-ai/negotiator 0.2.0-alpha.1 → 0.2.0-alpha.4

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

@@ -0,0 +1,70 @@
+/**
+ * `ensureConformingContract` — the negotiator's create-path guarantee.
+ *
+ * Given the agent's PROPOSED draft, return a contract that is
+ * GUARANTEED to pass the deterministic gate (`lintContract` with zero
+ * errors), so the handshake backstop (`validateContract`) never throws
+ * on it. This is the "Propose vs Commit" forgiving-handshake core
+ * shared by every negotiator implementation (OSS llm-backed + cloud
+ * bedrock) so the behavior cannot drift between deployments:
+ *
+ *   - draft already conforms → return it verbatim          (origin: 'agent')
+ *   - draft has errors       → repair-in-place via the bounded LLM loop,
+ *                              seeded with the draft + the deterministic
+ *                              findings, looping until the gate is green
+ *                              (origin: 'synth')
+ *   - repair impossible      → minimal conforming contract (`{}`) + loud
+ *     (LLM down / provider      error findings; STILL origin 'synth';
+ *      can't synth / budget     NEVER throws.
+ *      exhausted)
+ *
+ * Determinism lives in the GATE (`lintContract`), never in the repair.
+ * The repair LLM is non-deterministic, but the loop only exits when the
+ * deterministic gate is green — the same shape ui-gen uses to tolerate
+ * non-deterministic code generation behind a deterministic self_check.
+ *
+ * Cache/blueprint matching is NOT this function's job — the caller
+ * (negotiator `decide()`) runs its deployment-specific cache match
+ * FIRST and only falls through to here on a miss. That preserves the
+ * "cache-first, repair-second" ordering the negotiator contract
+ * mandates.
+ */
+import { type DataContract, type GadgetDescriptor, type SuggestionFinding } from '@ggui-ai/protocol';
+import type { LLMCaller } from './llm-caller.js';
+export interface EnsureConformingResult {
+    /** A contract guaranteed to pass `lintContract` with zero errors. */
+    readonly contract: DataContract;
+    /**
+     * - `'agent'` — the draft was already conforming; returned verbatim.
+     * - `'synth'` — the draft had errors; this is the repaired result
+     *   (or the minimal-conforming fallback when repair was impossible).
+     */
+    readonly origin: 'agent' | 'synth';
+    /**
+     * How the conforming contract was produced — finer-grained than
+     * `origin`, for telemetry (the efficiency tiers):
+     *   - `verbatim`      — draft was clean; returned as-is (origin agent).
+     *   - `normalized`    — deterministic fix only, NO LLM (origin synth).
+     *   - `llm-repair`    — the bounded LLM repair loop ran (origin synth).
+     *   - `fallback-empty`— unrepairable; minimal `{}` contract (origin synth).
+     */
+    readonly method: 'verbatim' | 'normalized' | 'llm-repair' | 'fallback-empty';
+    /**
+     * Findings surfaced to the agent. On `origin: 'agent'`, any hygiene
+     * 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.
+     */
+    readonly findings: readonly SuggestionFinding[];
+    /** Operator- + LLM-readable explanation. */
+    readonly reasoning: string;
+}
+export declare function ensureConformingContract(deps: {
+    readonly llm: LLMCaller;
+}, args: {
+    /** Untrusted: the agent's draft may not be a valid DataContract. */
+    readonly draft: unknown;
+    readonly intent: string;
+    readonly appGadgets?: readonly GadgetDescriptor[];
+}): Promise<EnsureConformingResult>;
+//# sourceMappingURL=ensure-conforming-contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-conforming-contract.d.ts","sourceRoot":"","sources":["../src/ensure-conforming-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,gBAAgB,CAAC;IAC7E;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAKD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,IAAI,EAAE;IACJ,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD,GACA,OAAO,CAAC,sBAAsB,CAAC,CA4FjC"}

package/dist/ensure-conforming-contract.js

@@ -0,0 +1,115 @@
+/**
+ * `ensureConformingContract` — the negotiator's create-path guarantee.
+ *
+ * Given the agent's PROPOSED draft, return a contract that is
+ * GUARANTEED to pass the deterministic gate (`lintContract` with zero
+ * errors), so the handshake backstop (`validateContract`) never throws
+ * on it. This is the "Propose vs Commit" forgiving-handshake core
+ * shared by every negotiator implementation (OSS llm-backed + cloud
+ * bedrock) so the behavior cannot drift between deployments:
+ *
+ *   - draft already conforms → return it verbatim          (origin: 'agent')
+ *   - draft has errors       → repair-in-place via the bounded LLM loop,
+ *                              seeded with the draft + the deterministic
+ *                              findings, looping until the gate is green
+ *                              (origin: 'synth')
+ *   - repair impossible      → minimal conforming contract (`{}`) + loud
+ *     (LLM down / provider      error findings; STILL origin 'synth';
+ *      can't synth / budget     NEVER throws.
+ *      exhausted)
+ *
+ * Determinism lives in the GATE (`lintContract`), never in the repair.
+ * The repair LLM is non-deterministic, but the loop only exits when the
+ * deterministic gate is green — the same shape ui-gen uses to tolerate
+ * non-deterministic code generation behind a deterministic self_check.
+ *
+ * Cache/blueprint matching is NOT this function's job — the caller
+ * (negotiator `decide()`) runs its deployment-specific cache match
+ * FIRST and only falls through to here on a miss. That preserves the
+ * "cache-first, repair-second" ordering the negotiator contract
+ * mandates.
+ */
+import { lintContract, dataContractSchema, } from '@ggui-ai/protocol';
+import { synthesizeContract } from './synthesize-contract.js';
+import { normalizeDraft } from './normalize-draft.js';
+/** Trivially-valid last-resort contract — all four specs omitted. */
+const EMPTY_CONTRACT = {};
+export async function ensureConformingContract(deps, args) {
+    const lint = lintContract(args.draft);
+    const warnFindings = lint.warnings.map((w) => ({
+        code: w.code,
+        severity: 'warn',
+        path: w.path,
+        message: w.message,
+    }));
+    // Fast path — draft already conforms. Deterministic, no LLM call.
+    // `lint.errors.length === 0` implies the shape phase passed, so the
+    // strict parse cannot throw — it just re-derives the typed DataContract
+    // from the untrusted input (validator returns the typed shape; no cast).
+    if (lint.errors.length === 0) {
+        return {
+            contract: dataContractSchema.parse(args.draft),
+            origin: 'agent',
+            method: 'verbatim',
+            findings: warnFindings,
+            reasoning: 'agent draft passed validateContract; accepted verbatim (origin: agent)',
+        };
+    }
+    const errorFindings = lint.errors.map((e) => ({
+        code: e.code,
+        severity: 'error',
+        path: e.path,
+        message: e.message,
+    }));
+    // L3 — deterministic normalization tier. Most agent malformations are
+    // mechanical (stray illegal wrapper keys, non-canonical schema types).
+    // Fix them WITHOUT an LLM: strip + canonicalize, re-lint, and if the
+    // draft now conforms, return it verbatim-but-cleaned. Faithful (no
+    // reshape risk — the agent's specs are preserved exactly) and free (no
+    // LLM call). Semantic deficiencies fall through to the repair loop.
+    const normalized = normalizeDraft(args.draft);
+    const normLint = lintContract(normalized);
+    if (normLint.errors.length === 0) {
+        return {
+            contract: dataContractSchema.parse(normalized),
+            origin: 'synth',
+            method: 'normalized',
+            findings: errorFindings,
+            reasoning: 'normalized the agent draft deterministically (stripped invalid keys / canonicalized schema types, no LLM) to pass validateContract',
+        };
+    }
+    // Repair loop on the NORMALIZED draft (mechanical errors already
+    // fixed) with only the REMAINING (semantic) findings — so the LLM
+    // patches what reasoning is genuinely needed for, from a clean start.
+    const synth = await synthesizeContract(deps, args.intent, {
+        ...(args.appGadgets ? { appGadgets: args.appGadgets } : {}),
+        draft: normalized,
+        draftFindings: normLint.errors.map((e) => ({
+            code: e.code,
+            path: e.path,
+            message: e.message,
+        })),
+    });
+    if (synth.contract !== null &&
+        lintContract(synth.contract).errors.length === 0) {
+        return {
+            contract: synth.contract,
+            origin: 'synth',
+            method: 'llm-repair',
+            findings: errorFindings,
+            reasoning: `repaired the agent draft to pass validateContract — ${synth.reason}`,
+        };
+    }
+    // Repair impossible (LLM down, provider can't synthesize, or the
+    // repair budget exhausted). We still MUST return a conforming
+    // contract — the handshake never hard-fails. Minimal conforming
+    // contract + loud findings so the agent can re-issue a corrected
+    // contract via ggui_render override if it needs the declared specs.
+    return {
+        contract: EMPTY_CONTRACT,
+        origin: 'synth',
+        method: 'fallback-empty',
+        findings: errorFindings,
+        reasoning: `could not repair the agent draft within budget (${synth.reason}); returning a minimal conforming contract — re-issue a corrected contract via ggui_render override if you need the declared specs`,
+    };
+}

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export { rerankCandidates } from './llm-rerank.js';
 export type { RerankCandidate, RerankDecision, RerankQuery, } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
 export type { SynthesizeContractResult } from './synthesize-contract.js';
+export { ensureConformingContract } from './ensure-conforming-contract.js';
+export type { EnsureConformingResult } from './ensure-conforming-contract.js';
 export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
 export type { ContractValidationFinding, ContractValidationFindingKind, ContractValidationResult, ContractValidationNoveltyDeps, ContractValidationNoveltyOptions, } from './contract-validators.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -22,4 +22,5 @@ export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from
 export { negotiate } from './negotiate.js';
 export { rerankCandidates } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
+export { ensureConformingContract } from './ensure-conforming-contract.js';
 export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';

package/dist/normalize-draft.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Deterministic draft normalization — the cheap, faithful repair tier.
+ *
+ * Most agent-draft malformations are MECHANICAL: a stray illegal key on
+ * a spec wrapper (a JSON-Schema-reflex `required: [...]` array on the
+ * propsSpec wrapper, an `additionalProperties` key), or a non-canonical
+ * schema `type` spelling (`"enum"`, `"integer"`). None of these needs an
+ * LLM to fix — and routing them through the LLM repair loop is both
+ * wasteful (a full regeneration) and RISKY (the model may re-author and
+ * reshape a 95%-correct draft, e.g. drop a propsSpec seed surface).
+ *
+ * This pass fixes the mechanical classes deterministically, preserving
+ * the agent's intent exactly:
+ *   - 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}
+ *     (the same normalizer `buildContract` runs on synth output).
+ *
+ * The caller (`ensureConformingContract`) re-lints the result: if it now
+ * passes the gate, the draft is returned WITHOUT ever calling the LLM.
+ * Semantic deficiencies (wrong placement, missing data surface, dangling
+ * cross-refs) are deliberately out of scope — those still go to the
+ * repair loop, where reasoning earns its keep.
+ */
+/**
+ * Return a structurally-normalized copy of an untrusted draft: illegal
+ * wrapper/entry keys stripped, inner schemas canonicalized. Pure — never
+ * mutates the input, never throws. Unknown top-level fields ride through
+ * (the top-level DataContract schema is `.passthrough()`); only the
+ * `.strict()` spec wrappers and entries are cleaned.
+ */
+export declare function normalizeDraft(draft: unknown): unknown;
+//# sourceMappingURL=normalize-draft.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-draft.d.ts","sourceRoot":"","sources":["../src/normalize-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA8EH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA+CtD"}

package/dist/normalize-draft.js

@@ -0,0 +1,143 @@
+/**
+ * Deterministic draft normalization — the cheap, faithful repair tier.
+ *
+ * Most agent-draft malformations are MECHANICAL: a stray illegal key on
+ * a spec wrapper (a JSON-Schema-reflex `required: [...]` array on the
+ * propsSpec wrapper, an `additionalProperties` key), or a non-canonical
+ * schema `type` spelling (`"enum"`, `"integer"`). None of these needs an
+ * LLM to fix — and routing them through the LLM repair loop is both
+ * wasteful (a full regeneration) and RISKY (the model may re-author and
+ * reshape a 95%-correct draft, e.g. drop a propsSpec seed surface).
+ *
+ * This pass fixes the mechanical classes deterministically, preserving
+ * the agent's intent exactly:
+ *   - 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}
+ *     (the same normalizer `buildContract` runs on synth output).
+ *
+ * The caller (`ensureConformingContract`) re-lints the result: if it now
+ * passes the gate, the draft is returned WITHOUT ever calling the LLM.
+ * Semantic deficiencies (wrong placement, missing data surface, dangling
+ * cross-refs) are deliberately out of scope — those still go to the
+ * repair loop, where reasoning earns its keep.
+ */
+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([
+    'description',
+    'usage',
+    'inputSchema',
+    'outputSchema',
+    'required',
+    'example',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Keep only `allowed` keys; normalize the schema-bearing fields named
+ *  in `schemaFields`. Non-record entries pass through untouched. */
+function cleanEntry(entry, allowed, schemaFields) {
+    if (!isRecord(entry))
+        return entry;
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (!allowed.has(key))
+            continue; // strip the illegal key
+        out[key] =
+            schemaFields.includes(key) && value !== undefined
+                ? normalizeSchema(value)
+                : value;
+    }
+    return out;
+}
+/** Apply {@link cleanEntry} across a `Record<name, entry>` spec map. */
+function cleanEntryMap(map, allowed, schemaFields) {
+    const out = {};
+    for (const [name, entry] of Object.entries(map)) {
+        out[name] = cleanEntry(entry, allowed, schemaFields);
+    }
+    return out;
+}
+/**
+ * Return a structurally-normalized copy of an untrusted draft: illegal
+ * wrapper/entry keys stripped, inner schemas canonicalized. Pure — never
+ * mutates the input, never throws. Unknown top-level fields ride through
+ * (the top-level DataContract schema is `.passthrough()`); only the
+ * `.strict()` spec wrappers and entries are cleaned.
+ */
+export function normalizeDraft(draft) {
+    if (!isRecord(draft))
+        return draft;
+    const out = { ...draft };
+    // propsSpec wrapper: keep {description, properties}; clean each PropEntry.
+    if (isRecord(out['propsSpec'])) {
+        const ps = {};
+        for (const [key, value] of Object.entries(out['propsSpec'])) {
+            if (PROPS_WRAPPER_KEYS.has(key))
+                ps[key] = value;
+        }
+        if (isRecord(ps['properties'])) {
+            ps['properties'] = cleanEntryMap(ps['properties'], PROP_ENTRY_KEYS, [
+                'schema',
+            ]);
+        }
+        out['propsSpec'] = ps;
+    }
+    if (isRecord(out['contextSpec'])) {
+        out['contextSpec'] = cleanEntryMap(out['contextSpec'], CONTEXT_ENTRY_KEYS, [
+            'schema',
+        ]);
+    }
+    if (isRecord(out['actionSpec'])) {
+        out['actionSpec'] = cleanEntryMap(out['actionSpec'], ACTION_ENTRY_KEYS, [
+            'schema',
+        ]);
+    }
+    if (isRecord(out['streamSpec'])) {
+        out['streamSpec'] = cleanEntryMap(out['streamSpec'], STREAM_ENTRY_KEYS, [
+            'schema',
+        ]);
+    }
+    if (isRecord(out['agentCapabilities'])) {
+        const ac = out['agentCapabilities'];
+        if (isRecord(ac['tools'])) {
+            out['agentCapabilities'] = {
+                ...ac,
+                tools: cleanEntryMap(ac['tools'], AGENT_TOOL_KEYS, [
+                    'inputSchema',
+                    'outputSchema',
+                ]),
+            };
+        }
+    }
+    return out;
+}

package/dist/preserve-seed-surfaces.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Seed-surface preservation — the deterministic backstop that keeps the
+ * repair loop FAITHFUL.
+ *
+ * The agent's draft declares its agent-owned render-time data as
+ * `propsSpec.properties` (the only agent→client seed channel —
+ * `contextSpec` has no runtime seed path). A repair that drops or
+ * reshapes one of those keys away from propsSpec (the canonical
+ * `propsSpec.X → contextSpec.X` regression) produces a contract that is
+ * VALID (`lintContract` passes) yet round-trip-BROKEN: the agent can no
+ * longer seed X at render, so the UI renders empty.
+ *
+ * `lintContract` + the placement validators can't catch this — none of
+ * them sees the agent's DRAFT. These helpers do: they compare the
+ * repaired candidate against the draft and report which agent-owned seed
+ * surfaces went missing, so the synth loop can drive a corrective retry.
+ * Model-independent — it works even when a weak model keeps reshaping.
+ */
+import type { DataContract } from '@ggui-ai/protocol';
+/**
+ * The `propsSpec.properties` keys an agent declared on a (possibly
+ * malformed) draft — its agent-owned render-time SEED surfaces.
+ * Defensive: the draft is untrusted, so every level is probed before
+ * access. Returns `[]` for any non-propsSpec-bearing draft.
+ */
+export declare function draftSeedPropKeys(draft: unknown): string[];
+/**
+ * Agent-owned seed surfaces (propsSpec property keys) present in `draft`
+ * that the repaired `candidate` DROPPED — i.e. they are no longer
+ * seedable as a propsSpec property. Reshaping `propsSpec.X` to
+ * `contextSpec.X`, or dropping it entirely, both surface here (contextSpec
+ * is not an agent-seedable home). Returns `[]` when every declared seed
+ * surface survived (preservation holds).
+ *
+ * Preservation-biased on purpose: keeping a seed key the intent turned
+ * out not to need is harmless (an unsent optional prop); DROPPING one the
+ * agent relies on is the round-trip break. So we only ever flag drops.
+ */
+export declare function findDroppedSeedSurfaces(draft: unknown, candidate: DataContract): string[];
+//# sourceMappingURL=preserve-seed-surfaces.d.ts.map

package/dist/preserve-seed-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-seed-surfaces.d.ts","sourceRoot":"","sources":["../src/preserve-seed-surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAMtD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAO1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,YAAY,GACtB,MAAM,EAAE,CAKV"}

package/dist/preserve-seed-surfaces.js

@@ -0,0 +1,57 @@
+/**
+ * Seed-surface preservation — the deterministic backstop that keeps the
+ * repair loop FAITHFUL.
+ *
+ * The agent's draft declares its agent-owned render-time data as
+ * `propsSpec.properties` (the only agent→client seed channel —
+ * `contextSpec` has no runtime seed path). A repair that drops or
+ * reshapes one of those keys away from propsSpec (the canonical
+ * `propsSpec.X → contextSpec.X` regression) produces a contract that is
+ * VALID (`lintContract` passes) yet round-trip-BROKEN: the agent can no
+ * longer seed X at render, so the UI renders empty.
+ *
+ * `lintContract` + the placement validators can't catch this — none of
+ * them sees the agent's DRAFT. These helpers do: they compare the
+ * repaired candidate against the draft and report which agent-owned seed
+ * surfaces went missing, so the synth loop can drive a corrective retry.
+ * Model-independent — it works even when a weak model keeps reshaping.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The `propsSpec.properties` keys an agent declared on a (possibly
+ * malformed) draft — its agent-owned render-time SEED surfaces.
+ * Defensive: the draft is untrusted, so every level is probed before
+ * access. Returns `[]` for any non-propsSpec-bearing draft.
+ */
+export function draftSeedPropKeys(draft) {
+    if (!isRecord(draft))
+        return [];
+    const propsSpec = draft['propsSpec'];
+    if (!isRecord(propsSpec))
+        return [];
+    const properties = propsSpec['properties'];
+    if (!isRecord(properties))
+        return [];
+    return Object.keys(properties);
+}
+/**
+ * Agent-owned seed surfaces (propsSpec property keys) present in `draft`
+ * that the repaired `candidate` DROPPED — i.e. they are no longer
+ * seedable as a propsSpec property. Reshaping `propsSpec.X` to
+ * `contextSpec.X`, or dropping it entirely, both surface here (contextSpec
+ * is not an agent-seedable home). Returns `[]` when every declared seed
+ * surface survived (preservation holds).
+ *
+ * Preservation-biased on purpose: keeping a seed key the intent turned
+ * out not to need is harmless (an unsent optional prop); DROPPING one the
+ * agent relies on is the round-trip break. So we only ever flag drops.
+ */
+export function findDroppedSeedSurfaces(draft, candidate) {
+    const seedKeys = draftSeedPropKeys(draft);
+    if (seedKeys.length === 0)
+        return [];
+    const candidateProps = candidate.propsSpec?.properties ?? {};
+    return seedKeys.filter((key) => candidateProps[key] === undefined);
+}

package/dist/synth-bench/cli-llm.d.ts

@@ -0,0 +1,20 @@
+import type { LLMCaller } from '../llm-caller.js';
+/** Default bench model — matches the `ui-gen-default-haiku-4-5` slug. */
+export declare const DEFAULT_MODEL = "claude-haiku-4-5";
+/** Haiku 4.5 token pricing (USD per token) for the cost report. */
+export declare const HAIKU_4_5_PRICE_INPUT_PER_TOKEN: number;
+export declare const HAIKU_4_5_PRICE_OUTPUT_PER_TOKEN: number;
+/**
+ * Resolve the Anthropic API key: `ANTHROPIC_API_KEY` env var first, then
+ * `~/.ggui/credentials.json` at `apps.global.anthropic`. `scriptName`
+ * prefixes the error hints so a failure names the bench that needs it.
+ */
+export declare function resolveAnthropicKey(scriptName: string): string;
+/** Running token usage accumulated across `callStructured` calls in this
+ *  process — read after a run for the cost line. */
+export declare function getTokenUsage(): {
+    readonly input: number;
+    readonly output: number;
+};
+export declare function buildAnthropicLlmCaller(apiKey: string, model: string): LLMCaller;
+//# sourceMappingURL=cli-llm.d.ts.map

package/dist/synth-bench/cli-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-llm.d.ts","sourceRoot":"","sources":["../../src/synth-bench/cli-llm.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,kBAAkB,CAAC;AAI9D,yEAAyE;AACzE,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,QAAkB,CAAC;AAC/D,eAAO,MAAM,gCAAgC,QAAkB,CAAC;AAMhE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAmB9D;AAmBD;oDACoD;AACpD,wBAAgB,aAAa,IAAI;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAEA;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,SAAS,CA2DX"}

package/dist/synth-bench/cli-llm.js

@@ -0,0 +1,97 @@
+/**
+ * Shared CLI LLM plumbing for the synth-bench family of live probes
+ * (bench-synth, bench-repair). Builds an Anthropic-backed
+ * {@link LLMCaller} with forced tool-use, resolves the API key from env
+ * or `~/.ggui/credentials.json`, and accumulates token usage for the
+ * per-run cost line. Bench-only — not exported from the package index.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve as pathResolve } from 'node:path';
+const ANTHROPIC_API = 'https://api.anthropic.com/v1/messages';
+/** Default bench model — matches the `ui-gen-default-haiku-4-5` slug. */
+export const DEFAULT_MODEL = 'claude-haiku-4-5';
+/** Haiku 4.5 token pricing (USD per token) for the cost report. */
+export const HAIKU_4_5_PRICE_INPUT_PER_TOKEN = 1.0 / 1_000_000;
+export const HAIKU_4_5_PRICE_OUTPUT_PER_TOKEN = 5.0 / 1_000_000;
+/**
+ * Resolve the Anthropic API key: `ANTHROPIC_API_KEY` env var first, then
+ * `~/.ggui/credentials.json` at `apps.global.anthropic`. `scriptName`
+ * prefixes the error hints so a failure names the bench that needs it.
+ */
+export function resolveAnthropicKey(scriptName) {
+    const envKey = process.env['ANTHROPIC_API_KEY'];
+    if (envKey && envKey.length > 0)
+        return envKey;
+    const credsPath = pathResolve(homedir(), '.ggui', 'credentials.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(credsPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${scriptName}: could not read ${credsPath} (${err instanceof Error ? err.message : String(err)}). Set ANTHROPIC_API_KEY env var or run \`ggui auth set anthropic\`.`);
+    }
+    const key = parsed.apps?.global?.anthropic;
+    if (typeof key !== 'string' || key.length === 0) {
+        throw new Error(`${scriptName}: no anthropic key found at apps.global.anthropic in ${credsPath}.`);
+    }
+    return key;
+}
+let totalInputTokens = 0;
+let totalOutputTokens = 0;
+/** Running token usage accumulated across `callStructured` calls in this
+ *  process — read after a run for the cost line. */
+export function getTokenUsage() {
+    return { input: totalInputTokens, output: totalOutputTokens };
+}
+export function buildAnthropicLlmCaller(apiKey, model) {
+    return {
+        async call() {
+            throw new Error('synth-bench: text-mode not exercised — synth uses callStructured');
+        },
+        async callStructured(systemPrompt, userMessage, tool, maxTokens) {
+            // `temperature` deprecated on Haiku 4.5+ — Anthropic rejects with
+            // HTTP 400. `tool_choice: { type: 'tool', name }` below already
+            // binds output to the input_schema; residual stochasticity stays
+            // bounded via canonical-key normalization downstream.
+            const body = {
+                model,
+                max_tokens: maxTokens ?? 1024,
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userMessage }],
+                tools: [
+                    {
+                        name: tool.name,
+                        description: tool.description,
+                        input_schema: tool.input_schema,
+                    },
+                ],
+                tool_choice: { type: 'tool', name: tool.name },
+            };
+            const res = await fetch(ANTHROPIC_API, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify(body),
+            });
+            const json = (await res.json());
+            if (!res.ok) {
+                const errType = json.error?.type ?? 'unknown';
+                const errMsg = json.error?.message ?? `HTTP ${res.status}`;
+                throw new Error(`anthropic ${errType}: ${errMsg}`);
+            }
+            if (json.usage) {
+                totalInputTokens += json.usage.input_tokens ?? 0;
+                totalOutputTokens += json.usage.output_tokens ?? 0;
+            }
+            const toolBlock = json.content?.find((b) => b.type === 'tool_use');
+            if (!toolBlock || toolBlock.input === undefined) {
+                throw new Error(`anthropic: no tool_use block in response (stop_reason=${json.stop_reason ?? 'unknown'})`);
+            }
+            return toolBlock.input;
+        },
+    };
+}