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

package/src/normalize-draft.ts

@@ -0,0 +1,156 @@
+/**
+ * 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: unknown): value is Record<string, unknown> {
+  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: unknown,
+  allowed: ReadonlySet<string>,
+  schemaFields: readonly string[],
+): unknown {
+  if (!isRecord(entry)) return entry;
+  const out: Record<string, unknown> = {};
+  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: Record<string, unknown>,
+  allowed: ReadonlySet<string>,
+  schemaFields: readonly string[],
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  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: unknown): unknown {
+  if (!isRecord(draft)) return draft;
+  const out: Record<string, unknown> = { ...draft };
+
+  // propsSpec wrapper: keep {description, properties}; clean each PropEntry.
+  if (isRecord(out['propsSpec'])) {
+    const ps: Record<string, unknown> = {};
+    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/src/preserve-seed-surfaces.ts

@@ -0,0 +1,61 @@
+/**
+ * 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';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  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: unknown): string[] {
+  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: unknown,
+  candidate: DataContract,
+): string[] {
+  const seedKeys = draftSeedPropKeys(draft);
+  if (seedKeys.length === 0) return [];
+  const candidateProps = candidate.propsSpec?.properties ?? {};
+  return seedKeys.filter((key) => candidateProps[key] === undefined);
+}

package/src/synth-bench/cli-llm.ts

@@ -0,0 +1,140 @@
+/**
+ * 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';
+import type { LLMCaller, ToolSchema } from '../llm-caller.js';
+
+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;
+
+interface CredsFile {
+  apps?: { global?: { anthropic?: string } };
+}
+
+/**
+ * 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: string): string {
+  const envKey = process.env['ANTHROPIC_API_KEY'];
+  if (envKey && envKey.length > 0) return envKey;
+  const credsPath = pathResolve(homedir(), '.ggui', 'credentials.json');
+  let parsed: CredsFile;
+  try {
+    parsed = JSON.parse(readFileSync(credsPath, 'utf8')) as CredsFile;
+  } 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;
+}
+
+interface AnthropicContentBlock {
+  type: string;
+  name?: string;
+  input?: unknown;
+  text?: string;
+}
+
+interface AnthropicResponse {
+  content?: AnthropicContentBlock[];
+  usage?: { input_tokens?: number; output_tokens?: number };
+  stop_reason?: string;
+  error?: { type?: string; message?: string };
+}
+
+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(): {
+  readonly input: number;
+  readonly output: number;
+} {
+  return { input: totalInputTokens, output: totalOutputTokens };
+}
+
+export function buildAnthropicLlmCaller(
+  apiKey: string,
+  model: string,
+): LLMCaller {
+  return {
+    async call(): Promise<string> {
+      throw new Error(
+        'synth-bench: text-mode not exercised — synth uses callStructured',
+      );
+    },
+    async callStructured<T>(
+      systemPrompt: string,
+      userMessage: string,
+      tool: ToolSchema,
+      maxTokens?: number,
+    ): Promise<T> {
+      // `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()) as AnthropicResponse;
+      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 as T;
+    },
+  };
+}