@ggui-ai/negotiator 0.1.0-rc.1

package/dist/llm-caller.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `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;
+}
+//# sourceMappingURL=llm-caller.d.ts.map

package/dist/llm-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../src/llm-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/llm-caller.js

@@ -0,0 +1,38 @@
+/**
+ * `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.
+ */
+export {};

package/dist/llm-rerank.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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;
+}
+declare 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.\n\nMATCH means the candidate would correctly satisfy the user's current request \u2014 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).\n\nNO-MATCH means the candidate would NOT satisfy the user's current request \u2014 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 \u2014 same contract, different value).\n\nVisual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match \u2014 the user can refine those after they get a working UI.\n\nOutput 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.";
+declare const RERANK_TOOL: ToolSchema;
+export { summarizeContract };
+/**
+ * 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 declare function rerankCandidates(deps: {
+    readonly llm: LLMCaller;
+}, query: RerankQuery, candidates: readonly RerankCandidate[]): Promise<RerankDecision>;
+export { RERANK_SYSTEM_PROMPT, RERANK_TOOL };
+//# sourceMappingURL=llm-rerank.d.ts.map

package/dist/llm-rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-rerank.d.ts","sourceRoot":"","sources":["../src/llm-rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,QAAA,MAAM,oBAAoB,spCAQkM,CAAC;AAE7N,QAAA,MAAM,WAAW,EAAE,UA4BlB,CAAC;AAsCF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AA8C7B;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,OAAO,CAAC,cAAc,CAAC,CAwDzB;AAGD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,CAAC"}

package/dist/llm-rerank.js

@@ -0,0 +1,178 @@
+/**
+ * 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';
+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 = {
+    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, candidates) {
+    const lines = [];
+    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, max) {
+    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 };
+function clampConfidence(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 0;
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+function parseToolInput(raw, candidateIds) {
+    if (raw === null || typeof raw !== 'object') {
+        return { matchId: null, confidence: 0, reason: 'parse-failed: non-object tool input' };
+    }
+    const obj = raw;
+    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, query, candidates) {
+    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;
+    try {
+        toolInput = await deps.llm.callStructured(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/dist/negotiate.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { 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';
+/**
+ * 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 declare function negotiate(deps: NegotiateDeps, input: NegotiateInput): Promise<NegotiateResult>;
+//# sourceMappingURL=negotiate.d.ts.map

package/dist/negotiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../src/negotiate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAWjD;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE;QACL,0CAA0C;QAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,+DAA+D;QAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iFAAiF;QACjF,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3C;;;;WAIG;QACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB;;;;;;WAMG;QACH,OAAO,CAAC,EAAE,SAAS,OAAO,mBAAmB,EAAE,gBAAgB,EAAE,CAAC;KACnE,CAAC;IACF,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACvE,wDAAwD;IACxD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,YAAY,EAAE,qBAAqB,EAAE,CAAC;IACtC,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACxC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAmJ1B"}