@ggui-ai/negotiator 0.1.0-rc.1

package/src/llm-caller.ts

@@ -0,0 +1,82 @@
+/**
+ * `LLMCaller` — the decision engine's LLM dispatcher.
+ *
+ * Narrow abstraction over "call a chat model, optionally with a forced
+ * tool-use schema for guaranteed-JSON structured output." Kept public
+ * so OSS consumers of `@ggui-ai/negotiator` can bring their own LLM
+ * provider (Anthropic direct, OpenAI, Google, a local model, a
+ * community LiteLLM wrapper) without touching the decision-engine
+ * source.
+ *
+ * **Why this lives in `@ggui-ai/negotiator`, not
+ * `@ggui-ai/mcp-server-core`.** `mcp-server-core` contains the
+ * storage + runtime seams an MCP server implementer binds against
+ * (`VectorStore`, `EmbeddingProvider`, `KeyValueStore`,
+ * `BlueprintProvider`, `Negotiator`). `LLMCaller` is an
+ * engine-internal dispatcher — one level below `Negotiator` — so
+ * lifting it to `mcp-server-core` would grow the public seam count
+ * speculatively. If a second consumer outside the negotiator
+ * surfaces later, the "where does `LLMCaller` live?" question can be
+ * re-opened at that point.
+ *
+ * Normative semantics:
+ * - `call(systemPrompt, userMessage, maxTokens?)` returns the raw
+ *   model text. Implementations MUST NOT inject tool-use blocks when
+ *   the caller didn't request them — the text path is used as a
+ *   regex-JSON fallback.
+ * - `callStructured?<T>(...)` is OPTIONAL. When present, it MUST
+ *   force tool use against the supplied `ToolSchema` and return the
+ *   tool input, parsed as `T`. Implementations that don't support
+ *   forced structured output simply omit this method; consumers
+ *   fall back to `call` + regex JSON extraction. Absence is not an
+ *   error.
+ * - `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
+ *   the adapter boundary.
+ */
+
+/** Tool schema for structured output via forced tool use. */
+export interface ToolSchema {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+/** Chat-model dispatcher consumed by the negotiator decision engine. */
+export interface LLMCaller {
+  /**
+   * Call the model in plain-text mode. `maxTokens` defaults to
+   * something implementation-appropriate (usually 2048).
+   */
+  call(
+    systemPrompt: string,
+    userMessage: string,
+    maxTokens?: number,
+  ): Promise<string>;
+
+  /**
+   * Call with forced tool use for guaranteed structured JSON output.
+   * Implementations that can't force tool use should omit this
+   * method — consumers detect absence and fall back to regex JSON
+   * extraction on the text path.
+   */
+  callStructured?<T>(
+    systemPrompt: string,
+    userMessage: string,
+    tool: ToolSchema,
+    maxTokens?: number,
+  ): Promise<T>;
+}
+
+/**
+ * Provider + model selector for factory-style LLM caller
+ * construction. The `provider` enum stays narrow to the ones
+ * ggui supports today; community adapters can extend by widening
+ * the union at their own boundary.
+ */
+export interface LLMCallerConfig {
+  provider: 'anthropic' | 'openai' | 'google' | 'openrouter' | 'bedrock';
+  model: string;
+  apiKey?: string;
+}

package/src/llm-rerank.ts

@@ -0,0 +1,280 @@
+/**
+ * LLM rerank — Tier-2 precision oracle for the blueprint registry.
+ *
+ * Given a user's UI request (intent + contract structure) and a set
+ * of candidate cached blueprints retrieved by RAG, ask a fast LLM
+ * (Haiku 4.5) which candidate (if any) matches. Returns a structured
+ * decision so the caller can branch deterministically.
+ *
+ * This module is the precision half of the blueprint-first
+ * architecture: RAG retrieval is high-recall but low-precision (bge-
+ * small confuses topic-similar but UI-divergent prompts); the LLM
+ * judge restores precision. Combined break-even hit rate is ~10%;
+ * realistic workloads observe 30-70%.
+ */
+import { summarizeContract } from '@ggui-ai/protocol';
+import type { LLMCaller, ToolSchema } from './llm-caller.js';
+
+/**
+ * One candidate blueprint for the LLM judge to consider.
+ *
+ * Keep this struct narrow — the prompt sees only what's necessary
+ * to decide match-vs-no-match. componentCode is intentionally
+ * absent (huge, distracting, doesn't change the decision).
+ */
+export interface RerankCandidate {
+  /** Stable blueprint id — echoed back as `matchId` on a hit. */
+  readonly id: string;
+  /** The intent prose that originally produced this blueprint. */
+  readonly cachedIntent: string;
+  /**
+   * One-line summary of the blueprint's contract surface. Format
+   * matches `summarizeContract()` below — `slots=...; actions=...;
+   * streams=...; props=...` so the judge sees the structural shape
+   * without the JSON noise.
+   */
+  readonly cachedContractSummary: string;
+  /**
+   * Optional retrieval signal. Higher cosine biases the prior, but
+   * the judge's decision is the source of truth. Pass-through so
+   * the prompt can include "candidate retrieved at cosine X" if the
+   * judge would benefit (default: omit).
+   */
+  readonly cosine?: number;
+}
+
+/** Decision returned by the LLM judge. */
+export interface RerankDecision {
+  /**
+   * The matched candidate's id, or `null` if no candidate matches.
+   * `null` means "all candidates rejected — generate fresh."
+   */
+  readonly matchId: string | null;
+  /**
+   * Confidence on `[0, 1]`. Caller compares against a threshold (e.g.
+   * 0.6) before treating the decision as a hit. Returned even when
+   * matchId is null so callers can log "judge declined with
+   * confidence X."
+   */
+  readonly confidence: number;
+  /**
+   * Free-text reason from the judge. Surface in trace logs so
+   * operators can debug "why didn't this hit." Truncate at the
+   * persistence boundary if cardinality is a concern.
+   */
+  readonly reason: string;
+  /** 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.
+   */
+  readonly tokenCost: { readonly input: number; readonly output: number };
+}
+
+/** Query the user's request the judge is matching against. */
+export interface RerankQuery {
+  readonly intent: string;
+  readonly contractSummary: string;
+}
+
+const RERANK_SYSTEM_PROMPT = `You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate produces the SAME USEFUL UI for the current request.
+
+MATCH means the candidate would correctly satisfy the user's current request — same UI shape (component types, layout pattern), same wire surface (slot names, action names), same intended user task, and same load-bearing parameters (dates, months, ranges, enum values).
+
+NO-MATCH means the candidate would NOT satisfy the user's current request — different task (haiku composer vs tweet draft, login vs signup), different UI shape (form vs list vs dashboard), or load-bearing parameters differ (calendar-Jan vs calendar-Mar — same contract, different value).
+
+Visual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match — the user can refine those after they get a working UI.
+
+Output exactly ONE tool call with your decision. confidence is a number in [0, 1]. matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.`;
+
+const RERANK_TOOL: ToolSchema = {
+  name: 'submit_rerank_decision',
+  description:
+    'Submit your match-vs-no-match decision over the candidates.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      matchId: {
+        type: ['string', 'null'],
+        description:
+          "ID of the matching candidate, or null when no candidate matches. MUST be one of the candidate ids supplied in the user message, or null.",
+      },
+      confidence: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        description:
+          'Confidence in the decision on [0, 1]. Caller will compare against a threshold before treating it as a hit.',
+      },
+      reason: {
+        type: 'string',
+        description:
+          'Brief explanation — one sentence — that the operator can use to debug match decisions.',
+      },
+    },
+    required: ['matchId', 'confidence', 'reason'],
+  },
+};
+
+function buildUserMessage(
+  query: RerankQuery,
+  candidates: readonly RerankCandidate[],
+): string {
+  const lines: string[] = [];
+  lines.push('CURRENT REQUEST');
+  lines.push(`  intent: ${query.intent}`);
+  lines.push(`  contract: ${query.contractSummary}`);
+  lines.push('');
+  lines.push(`CANDIDATES (${candidates.length})`);
+  for (const c of candidates) {
+    lines.push('---');
+    lines.push(`  id: ${c.id}`);
+    lines.push(`  intent: ${truncate(c.cachedIntent, 280)}`);
+    lines.push(`  contract: ${c.cachedContractSummary}`);
+    if (typeof c.cosine === 'number') {
+      lines.push(`  cosine: ${c.cosine.toFixed(3)}`);
+    }
+  }
+  lines.push('');
+  lines.push(
+    'Decide: does any candidate match the current request? Submit via the tool.',
+  );
+  return lines.join('\n');
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1)}…`;
+}
+
+// Re-export `summarizeContract` from protocol for backwards-compatible
+// access through `@ggui-ai/negotiator/llm-rerank` consumers (the
+// canonical home is `@ggui-ai/protocol` — both the registry storage
+// and the rerank prompt depend on it). Kept as a re-export so the
+// existing test imports here keep working.
+export { summarizeContract };
+
+interface RerankToolInput {
+  matchId: string | null;
+  confidence: number;
+  reason: string;
+}
+
+function clampConfidence(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+function parseToolInput(
+  raw: unknown,
+  candidateIds: ReadonlySet<string>,
+): { matchId: string | null; confidence: number; reason: string } {
+  if (raw === null || typeof raw !== 'object') {
+    return { matchId: null, confidence: 0, reason: 'parse-failed: non-object tool input' };
+  }
+  const obj = raw as Record<string, unknown>;
+  const reason = typeof obj['reason'] === 'string' ? obj['reason'] : '';
+  const confidence = clampConfidence(obj['confidence']);
+  const rawMatchId = obj['matchId'];
+  if (rawMatchId === null || rawMatchId === undefined) {
+    return { matchId: null, confidence, reason };
+  }
+  if (typeof rawMatchId !== 'string') {
+    return {
+      matchId: null,
+      confidence: 0,
+      reason: `parse-failed: matchId was ${typeof rawMatchId}, not string|null`,
+    };
+  }
+  if (!candidateIds.has(rawMatchId)) {
+    return {
+      matchId: null,
+      confidence: 0,
+      reason: `judge returned matchId='${rawMatchId}' but that id is not in the candidate set — treating as no-match`,
+    };
+  }
+  return { matchId: rawMatchId, confidence, reason };
+}
+
+/**
+ * Run the rerank judge against a query + candidate list.
+ *
+ * Empty candidate list short-circuits without an LLM call — the
+ * caller's RAG step decided there's nothing close enough; we don't
+ * burn tokens to confirm it.
+ *
+ * Operational errors (LLM throws, parse fails) collapse to a `null`
+ * match with confidence=0 and a diagnostic reason. The caller treats
+ * confidence-below-threshold as no-match anyway, so the failure mode
+ * lands on the cold-gen path automatically.
+ */
+export async function rerankCandidates(
+  deps: { readonly llm: LLMCaller },
+  query: RerankQuery,
+  candidates: readonly RerankCandidate[],
+): Promise<RerankDecision> {
+  const startedAt = Date.now();
+  if (candidates.length === 0) {
+    return {
+      matchId: null,
+      confidence: 0,
+      reason: 'no candidates — short-circuited without LLM call',
+      latencyMs: Date.now() - startedAt,
+      tokenCost: { input: 0, output: 0 },
+    };
+  }
+
+  const userMessage = buildUserMessage(query, candidates);
+  const candidateIds = new Set(candidates.map((c) => c.id));
+
+  if (typeof deps.llm.callStructured !== 'function') {
+    return {
+      matchId: null,
+      confidence: 0,
+      reason:
+        'llm-rerank: provider does not support callStructured (forced tool-use). Bind a structured-capable LLMCaller (Anthropic adapter via mcp-server) for rerank.',
+      latencyMs: Date.now() - startedAt,
+      tokenCost: { input: 0, output: 0 },
+    };
+  }
+
+  let toolInput: unknown;
+  try {
+    toolInput = await deps.llm.callStructured<RerankToolInput>(
+      RERANK_SYSTEM_PROMPT,
+      userMessage,
+      RERANK_TOOL,
+      512,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      matchId: null,
+      confidence: 0,
+      reason: `llm-rerank: callStructured threw — ${message}`,
+      latencyMs: Date.now() - startedAt,
+      tokenCost: { input: 0, output: 0 },
+    };
+  }
+
+  const parsed = parseToolInput(toolInput, candidateIds);
+  return {
+    matchId: parsed.matchId,
+    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 },
+  };
+}
+
+// Re-exports for the eval harness — keep public surface explicit.
+export { RERANK_SYSTEM_PROMPT, RERANK_TOOL };

package/src/negotiate.ts

@@ -0,0 +1,312 @@
+/**
+ * Negotiator — top-level orchestrator over the public storage +
+ * decision-engine seams.
+ *
+ * Pipeline:
+ *   1. RAG search (per-scope + optional shared pool) via
+ *      {@link ragSearch} — composes `EmbeddingProvider.embed` +
+ *      `VectorStore.query` from `@ggui-ai/mcp-server-core`.
+ *   2. Read session state (optional injectable).
+ *   3. Fast-path for exact blueprint hits — skip the decision LLM.
+ *   4. Otherwise call {@link makeDecision} with the RAG candidates and
+ *      session stack; fold the picked blueprint's pool provenance into
+ *      the return value.
+ *
+ * Timing logs (stable format — consumed by benchmarks):
+ *   [negotiate] embedding: Xms | search: Xms | candidates: N
+ *   [negotiate] candidate: <id8> | <description> | hash=<h16>
+ *   [negotiate] FAST PATH: blueprint=<id8> hash=<h12> | LLM decision: 0ms | total: Xms
+ *   [negotiate] LLM PATH: action=X blueprint=<id8> hash=<h12> | LLM decision: Xms | total: Xms
+ *
+ * ### Public surface + semver weight
+ *
+ * Exported:
+ *   - `negotiate(deps, input)` — runtime orchestrator.
+ *   - `NegotiateDeps` — injection shape (embedding / vectors / llm +
+ *     optional session-state reader + optional progress callback).
+ *   - `NegotiateInput` — agent signal + config.
+ *   - `NegotiateConfig` — minimum fields the orchestrator actually
+ *     reads. Pool selection is expressed as `includeSharedPool:
+ *     boolean` rather than a `poolMode` enum, so callers decide
+ *     shared-pool inclusion explicitly at each call site.
+ *   - `NegotiateResult` — the decision result returned to callers.
+ *
+ * ### Why this package, not `mcp-server-core`
+ *
+ * `mcp-server-core` locks storage/runtime seams MCP server
+ * implementers bind against (`EmbeddingProvider`, `VectorStore`,
+ * `Negotiator`). `negotiate()` is a *composition* over those seams —
+ * decision-engine semantics, not a new seam. Adding it to
+ * `mcp-server-core` would drag the LLM prompts + tool-schemas into a
+ * package whose job is to stay minimal and runtime-agnostic.
+ */
+
+import type {
+  DataContract,
+  NegotiatorAlternative,
+  NegotiatorDecision,
+} from '@ggui-ai/protocol';
+import type {
+  EmbeddingProvider,
+  VectorStore,
+} from '@ggui-ai/mcp-server-core';
+import type { LLMCaller } from './llm-caller.js';
+import type { SessionState } from './session.js';
+import type { NegotiatorDecisionInput } from './decision-input.js';
+import { ragSearch } from './rag-search.js';
+import { makeDecision } from './decision.js';
+
+/** Empty session state for cold starts and benchmarks. */
+const EMPTY_SESSION: SessionState = {
+  stack: [],
+  conversationHistory: [],
+};
+
+/**
+ * Minimum config the orchestrator reads.
+ *
+ * `appId` is the primary RAG scope (per-app registered UIs live
+ * here). `sessionId` keys the optional `readSessionState` callback.
+ * `includeSharedPool` (default `false`) gates whether to also search
+ * the global `"shared"` pool in parallel and fold its hits into the
+ * candidate set.
+ */
+export interface NegotiateConfig {
+  appId: string;
+  sessionId: string;
+  /** Also search the shared (global) pool in parallel. Default `false`. */
+  includeSharedPool?: boolean;
+}
+
+/**
+ * Agent signal + config for a single negotiation call. Bundled as one
+ * object so future additive fields don't force yet another positional
+ * arg on the public API.
+ */
+export interface NegotiateInput {
+  agent: {
+    /** Raw data the agent wants to render. */
+    data?: Record<string, unknown>;
+    /** Natural-language prompt. Used as RAG query when present. */
+    prompt?: string;
+    /** Free-form context string or structured map. Forwarded to the decision LLM. */
+    context?: string | Record<string, unknown>;
+    /**
+     * Names of MCP tools the agent invokes (catalog seed). Merged
+     * into the decision's `agentCapabilities.tools` deterministically
+     * (see {@link makeDecision}).
+     */
+    agentTools?: string[];
+    /**
+     * Browser-capability gadget catalog the app exposes (default
+     * `STDLIB_GADGETS`, operator-extensible). Forwarded to
+     * the decision LLM so it knows which gadget bindings are
+     * available; canonical entries enrich partial LLM output
+     * downstream (see {@link mergeGadgets}).
+     */
+    gadgets?: readonly import('@ggui-ai/protocol').GadgetDescriptor[];
+  };
+  config: NegotiateConfig;
+}
+
+/**
+ * Dependencies injected into {@link negotiate}. Public field names
+ * (`embedding` / `vectors` / `llm`) align with {@link ragSearch}'s
+ * already-shipped deps shape.
+ */
+export interface NegotiateDeps {
+  /**
+   * Embedding provider for the RAG search step. **Optional** —
+   * when omitted (paired with omitted `vectors`), the negotiator
+   * skips RAG entirely and runs the decision LLM against an empty
+   * candidate list. OSS without vector-store infrastructure binds
+   * with `embedding: undefined, vectors: undefined` and still gets
+   * useful negotiation via the decision LLM alone.
+   *
+   * `embedding` and `vectors` are paired — both must be present for
+   * RAG to fire, or both must be absent. A half-bound config (one
+   * present, one missing) is a configuration bug; the search step
+   * skips and logs a warn rather than erroring, but consumers
+   * should fix the binding.
+   */
+  embedding?: EmbeddingProvider;
+  vectors?: VectorStore;
+  llm: LLMCaller;
+  /** Optional: read current session state for stack-aware decisions. */
+  readSessionState?: (sessionId: string) => Promise<SessionState | null>;
+  /** Optional: surface pipeline progress to consumers. */
+  onProgress?: (phase: string, summary: string) => void;
+}
+
+/**
+ * Output shape — mirrors the legacy `DecisionResult` so the
+ * back-compat shim can return the object verbatim. See `NegotiateDeps`
+ * semver note.
+ */
+export interface NegotiateResult {
+  decision: NegotiatorDecision;
+  alternatives: NegotiatorAlternative[];
+  /** Stored contract hash from blueprint match — deterministic pool key. */
+  storedContractHash?: string;
+  /** Which pool the matched blueprint's code lives in. */
+  storedPoolSource?: 'shared' | 'private';
+  embeddingLatencyMs: number;
+  searchLatencyMs: number;
+  decisionLatencyMs: number;
+}
+
+/**
+ * Orchestrate one negotiation call — RAG search, session read, fast
+ * path, decision LLM. See module docstring for the pipeline outline.
+ */
+export async function negotiate(
+  deps: NegotiateDeps,
+  input: NegotiateInput,
+): Promise<NegotiateResult> {
+  const { agent, config } = input;
+  const negotiateStart = Date.now();
+  deps.onProgress?.('negotiating', 'Analyzing request...');
+
+  // Step 1: RAG search (per-app + optional shared pool in parallel).
+  // `embedding` + `vectors` are optional. When either is missing,
+  // ragSearch is a no-op (returns empty options + 0 latency); the
+  // decision LLM runs against zero candidates and falls back to
+  // "create" via its standard branching. OSS without RAG infrastructure
+  // gets useful negotiation from the decision LLM alone.
+  const queryText = agent.prompt ?? JSON.stringify(agent.data ?? {});
+  const emptyResult = { options: [], embeddingLatencyMs: 0, searchLatencyMs: 0 };
+  const ragDeps =
+    deps.embedding !== undefined && deps.vectors !== undefined
+      ? { embedding: deps.embedding, vectors: deps.vectors }
+      : undefined;
+  const [appResult, sharedResult] = await Promise.all([
+    ragDeps
+      ? ragSearch(ragDeps, { prompt: queryText, scope: config.appId })
+      : Promise.resolve(emptyResult),
+    ragDeps && config.includeSharedPool
+      ? ragSearch(ragDeps, { prompt: queryText, scope: 'shared' })
+      : Promise.resolve(emptyResult),
+  ]);
+
+  const ragResult = {
+    options: [...appResult.options, ...sharedResult.options],
+    embeddingLatencyMs: Math.max(
+      appResult.embeddingLatencyMs,
+      sharedResult.embeddingLatencyMs,
+    ),
+    searchLatencyMs: Math.max(
+      appResult.searchLatencyMs,
+      sharedResult.searchLatencyMs,
+    ),
+  };
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `[negotiate] embedding: ${ragResult.embeddingLatencyMs}ms | search: ${ragResult.searchLatencyMs}ms | candidates: ${ragResult.options.length}`,
+  );
+  for (const opt of ragResult.options) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `[negotiate] candidate: ${opt.blueprintId?.slice(-8) ?? 'none'} | ${opt.description.slice(0, 80)} | hash=${opt.contractHash?.slice(0, 16) ?? 'none'}`,
+    );
+  }
+
+  deps.onProgress?.(
+    'blueprint_search',
+    ragResult.options.length > 0
+      ? `Found ${ragResult.options.length} blueprint candidate${ragResult.options.length > 1 ? 's' : ''}`
+      : 'No blueprints found',
+  );
+
+  // Step 2: Read session state (falls back to EMPTY_SESSION).
+  const sessionState = deps.readSessionState
+    ? ((await deps.readSessionState(config.sessionId)) ?? EMPTY_SESSION)
+    : EMPTY_SESSION;
+
+  // Step 3: Fast-path for high-confidence exact matches — skip decision LLM.
+  const exactOpt = ragResult.options.find((opt) =>
+    opt.description.includes('exact'),
+  );
+  if (exactOpt) {
+    const stackHasSameType = sessionState.stack.some(
+      (item) => item.prompt && agent.prompt && item.prompt === agent.prompt,
+    );
+    const action = stackHasSameType ? ('update' as const) : ('create' as const);
+    const totalMs = Date.now() - negotiateStart;
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[negotiate] FAST PATH: blueprint=${exactOpt.blueprintId?.slice(-8)} hash=${exactOpt.contractHash?.slice(0, 12) ?? 'none'} | LLM decision: 0ms | total: ${totalMs}ms`,
+    );
+    deps.onProgress?.('deciding', 'Exact match found — fast path');
+
+    // The agent's prompt is the outer-pipeline intent (`intent` is not
+    // a contract field). Fallback contract is the empty contract — the
+    // four-spec surface is omitted entirely (no props, no actions, no
+    // streams, no context).
+    const fallbackContract: DataContract = {};
+    return {
+      decision: {
+        action,
+        reasoning: `Exact blueprint match (high confidence). ${action === 'update' ? 'Updating existing view.' : 'Creating new view.'}`,
+        blueprintId: exactOpt.blueprintId,
+        contract: exactOpt.contract ?? fallbackContract,
+      },
+      alternatives: [],
+      storedContractHash: exactOpt.contractHash,
+      storedPoolSource: exactOpt.poolSource,
+      embeddingLatencyMs: ragResult.embeddingLatencyMs,
+      searchLatencyMs: ragResult.searchLatencyMs,
+      decisionLatencyMs: 0,
+    };
+  }
+
+  // Step 4: Build decision input + call the LLM.
+  const decisionInput: NegotiatorDecisionInput = {
+    agentData: agent.data,
+    agentPrompt: agent.prompt,
+    agentContext: agent.context,
+    agentTools: agent.agentTools,
+    ...(agent.gadgets
+      ? { gadgets: agent.gadgets }
+      : {}),
+    sessionState,
+    blueprintCandidates: ragResult.options.map((opt) => ({
+      blueprintId: opt.blueprintId ?? opt.id,
+      description: opt.description,
+      contract: opt.contract,
+      similarity:
+        parseFloat(opt.description.match(/similarity: (\d+)%/)?.[1] ?? '0') / 100,
+      verdict: (opt.description.includes('exact') ? 'exact' : 'partial') as
+        | 'exact'
+        | 'partial',
+    })),
+  };
+
+  deps.onProgress?.('deciding', 'Choosing the best UI approach...');
+  const decisionStart = Date.now();
+  const { decision, alternatives } = await makeDecision(decisionInput, deps.llm);
+  const decisionLatencyMs = Date.now() - decisionStart;
+  const totalMs = Date.now() - negotiateStart;
+
+  const pickedBlueprint = decision.blueprintId
+    ? ragResult.options.find(
+        (opt) => (opt.blueprintId ?? opt.id) === decision.blueprintId,
+      )
+    : undefined;
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `[negotiate] LLM PATH: action=${decision.action} blueprint=${decision.blueprintId?.slice(-8) ?? 'none'} hash=${pickedBlueprint?.contractHash?.slice(0, 12) ?? 'none'} | LLM decision: ${decisionLatencyMs}ms | total: ${totalMs}ms`,
+  );
+
+  return {
+    decision,
+    alternatives,
+    storedContractHash: pickedBlueprint?.contractHash,
+    storedPoolSource: pickedBlueprint?.poolSource,
+    embeddingLatencyMs: ragResult.embeddingLatencyMs,
+    searchLatencyMs: ragResult.searchLatencyMs,
+    decisionLatencyMs,
+  };
+}