@ggui-ai/negotiator 0.1.0-rc.1

package/dist/decision.js

@@ -0,0 +1,500 @@
+/**
+ * Decision Engine — one LLM call, one UI decision.
+ *
+ * Replaces the V2 brainstorm/option-picker pattern with a single
+ * opinionated decision: `create` / `update` / `compose` / `replace`.
+ * The LLM sees the agent's data, the current session stack, any
+ * `blueprintCandidates` from `ragSearch`, and returns a
+ * {@link NegotiatorDecision} with a full {@link DataContract} payload.
+ *
+ * Contract shape — the returned `contract` always includes an
+ * `intent` (semantic identity — same intent = cached component).
+ * Other fields are populated opportunistically; `agentCapabilities` is
+ * always populated deterministically from `input.agentTools` after
+ * the LLM returns (see {@link mergeAgentCapabilities}). The
+ * `clientCapabilities.gadgets` catalog is similarly enriched from
+ * the per-app gadget list (see {@link mergeGadgets}).
+ *
+ * Structured output — prefers `llmCaller.callStructured?` with a
+ * forced-tool-use schema (guaranteed JSON). Falls back to text + regex
+ * JSON extraction if the caller doesn't support structured output, or
+ * if the structured call throws. On total parse failure, emits a
+ * fallback decision with `action: 'create'` built from the agent's
+ * data shape.
+ *
+ * ## Public surface + semver weight
+ *
+ * Exported:
+ *   - `DECISION_SYSTEM_PROMPT` — the system prompt constant. Its
+ *     content is part of the behavioral contract: changing the prompt
+ *     changes what the model emits and therefore changes the cache
+ *     identity of downstream generated blueprints. Treat content
+ *     changes like `CRITERIA` ordering: CHANGELOG-worthy.
+ *   - `buildDecisionUserMessage(input)` — pure string builder. Stable
+ *     output for stable input.
+ *   - `makeDecision(input, llmCaller)` — runtime orchestrator.
+ *
+ * Intentionally **not** exported:
+ *   - `DECISION_TOOL` — the OpenAI-style tool schema handed to
+ *     `callStructured`. Pinning its shape in the public API would
+ *     freeze the tool-schema format consumers never need to see.
+ *   - `mergeAgentCapabilities`, `mergeGadgets`, `buildFallbackDecision`,
+ *     `inferType` — engine-internal helpers.
+ */
+import { gadgetExportName, gadgetIdentityKey } from '@ggui-ai/protocol';
+import { composeAvailableGadgetsSection } from './synthesize-contract.js';
+export const DECISION_SYSTEM_PROMPT = `You are a UI strategist for ggui, a generative UI platform. Given the agent's data, current session state, and blueprint candidates, decide the best way to show this information.
+
+Respond with a JSON object:
+{
+  "action": "create" | "update" | "compose" | "replace",
+  "reasoning": "1-2 sentences explaining why",
+  "blueprintId": "matched blueprint ID or null",
+  "targetStackItemId": "existing page to update/compose/replace, or null",
+  "contract": {
+    "intent": "Concise purpose — e.g. 'Display current weather conditions for a quick daily check'",
+    "propsSpec": {
+      "properties": {
+        "fieldName": {
+          "description": "what this field is",
+          "schema": { "type": "string" },
+          "required": true,
+          "example": "sample value"
+        }
+      }
+    }
+  },
+  "adaptations": {
+    "fontSize": "compact" | "default" | "large",
+    "density": "dense" | "default" | "spacious",
+    "complexity": "simplified" | "default" | "detailed"
+  }
+}
+
+INTENT RULES (most important):
+- The "intent" field captures WHY this UI exists in one sentence.
+- Include: the user's goal (why), what data is shown (what), and how they interact (how).
+- Be abstract enough to match reusable patterns — "Display current weather conditions" not "Display Tokyo weather at 3pm".
+- Same intent = same component can be reused with different data.
+- Examples:
+  - "Display current weather conditions for a quick daily check"
+  - "Collect user feedback via a multi-field survey form"
+  - "Show real-time stock prices with live updates"
+  - "Compare two products side by side for purchase decision"
+
+DECISION RULES:
+- "create": No existing UI or blueprint matches this intent. Show something new.
+- "update": An existing UI on the stack has the same intent. Update its props.
+- "compose": An existing UI could incorporate this data as a section.
+- "replace": Two or more related UIs would be better as a single unified view.
+
+REUSE BIAS (critical for performance):
+- Reusing a blueprint = INSTANT render (cached code, <1 second).
+- Creating new = 20+ seconds of generation. The user waits.
+- Default to reuse. Only "create" when NO candidate can reasonably serve the request.
+- A candidate that shows the SAME KIND of data (e.g., weather, stock prices, user profiles) is a match — even if the specific data differs (Tokyo vs Seoul, AAPL vs GOOG).
+- Ask yourself: "Can this candidate display the agent's data with different prop values?" If yes → reuse it.
+- When reusing a blueprint, copy its contract EXACTLY as-is (including its intent). Do NOT rephrase the intent.
+
+CONTRACT RULES:
+- Always include an "intent" field — it's required.
+- If reusing a blueprint: use that blueprint's contract verbatim. Do not modify intent or propsSpec.
+- If no blueprint match: infer propsSpec.properties from the agent's data shape. Each key becomes a prop.
+- Use the data values as examples.
+
+ACTION SPEC — declare interactive affordances WHENEVER you see them in the data:
+- The discrimination is local-state vs persistent-state, NOT "did the agent declare agentTools".
+- LOCAL STATE (counter value, theme toggle, slider position, picker selection, search-as-you-type, form draft fields): contextSpec only. NO actionSpec. The slot mirror IS the wire — the agent observes context via its next ggui_consume.
+- PERSISTENT STATE (items with identity / IDs + mutable fields, draft submissions awaiting save, deletions of agent-owned rows): actionSpec required. Each gesture is a discrete event the agent must witness.
+- Inference signals for persistent state:
+  • Items with \`id\`/\`itemId\`/\`uuid\` fields + boolean toggle fields like \`done\`/\`completed\`/\`checked\`/\`pinned\`/\`enabled\` → toggle action (e.g. \`toggleTodo\`, \`togglePin\`).
+  • Lists where the data shape implies the agent maintains identity → add/delete actions.
+  • Form data with mutable fields + a submit gesture → submit action.
+  • A click that would cause a server-side side-effect (publish, archive, send, delete-from-database) → action.
+- nextStep is OPTIONAL on actionSpec entries:
+  • Bind \`nextStep: "tool_name"\` ONLY when input.agentTools contains a matching tool (exact or close name match — \`todo_toggle\` matches the \`toggleTodo\` action).
+  • If no agentTools match, OMIT nextStep. Events drain via ggui_consume on the agent's next turn — the agent's reasoning loop sees the event and decides what to do.
+- Examples:
+  • agentTools=["todo_toggle","todo_delete"] + todo data → actionSpec: { "toggleTodo": { label: "Toggle", schema: {type:"object",properties:{id:{type:"string"}},required:["id"]}, nextStep: "todo_toggle" }, "deleteTodo": {...nextStep: "todo_delete"} }
+  • agentTools=[] + todo data → SAME actionSpec entries WITHOUT nextStep. The agent's next turn reads the event and reacts.
+  • agentTools=[] + counter prompt → contextSpec.count only. NO actionSpec.
+
+AGENT CAPABILITIES (catalog):
+- You do NOT need to emit contract.agentCapabilities — it is populated deterministically from input.agentTools after you return.
+- Focus on actionSpec entries + their optional nextStep bindings; the catalog auto-populates.
+
+ANTI-PATTERNS — DO NOT EMIT (cross-ref linter rejects at push):
+- "props" / "props.properties" as a CONTRACT field      (retired contract-side spelling — the contract field is propsSpec; the wire field on push/update is still "props" but carries VALUES, not the spec)
+- "wiredTools" / "agentTools" / "clientTools" catalog names  (retired; use agentCapabilities.tools / clientCapabilities.gadgets)
+- clientCapabilities.capabilities                       (retired inner key; use clientCapabilities.gadgets)
+- ActionEntry.tool / ActionEntry.dispatch.kind          (retired discriminated union; use the flat nextStep field)
+- mode: 'host-routed' / mode: 'agent-routed'            (retired; all actions are agent-routed)
+- broadcast: { ... } as a top-level field               (retired; use streamSpec[X].source instead)`;
+export function buildDecisionUserMessage(input) {
+    const parts = [];
+    // Agent's data
+    if (input.agentData) {
+        parts.push(`Agent's data:\n${JSON.stringify(input.agentData, null, 2)}`);
+    }
+    if (input.agentPrompt) {
+        parts.push(`Agent's hint: "${input.agentPrompt}"`);
+    }
+    if (input.agentContext) {
+        const ctx = typeof input.agentContext === 'string'
+            ? input.agentContext
+            : JSON.stringify(input.agentContext);
+        parts.push(`Agent's context: ${ctx}`);
+    }
+    // Session state
+    const { sessionState } = input;
+    if (sessionState.stack.length > 0) {
+        const stackSummary = sessionState.stack
+            .map((item) => `  [${item.id}] ${item.prompt ?? 'no prompt'}`)
+            .join('\n');
+        parts.push(`Current UI stack (${sessionState.stack.length} items):\n${stackSummary}`);
+    }
+    else {
+        parts.push('Current UI stack: empty');
+    }
+    if (sessionState.conversationHistory.length > 0) {
+        const recent = sessionState.conversationHistory.slice(-5);
+        parts.push(`Recent conversation:\n${recent.map((t) => `  ${t.role}: ${t.content}`).join('\n')}`);
+    }
+    // Agent tools — MCP tools the agent invokes; component never calls these.
+    // When tools ARE listed, prefer binding matching actionSpec entries to them
+    // via `nextStep`. When tools are absent BUT the data implies interactivity,
+    // still declare actionSpec — events drain via ggui_consume on the next turn.
+    if (input.agentTools?.length) {
+        parts.push(`Agent-side MCP tools (bind matching actionSpec entries' nextStep to these names; the agent invokes the tool on its next turn):\n` +
+            input.agentTools.map((t) => `  • ${t}`).join('\n'));
+    }
+    else {
+        parts.push(`Agent-side MCP tools: none declared. If the data implies interactivity (items with id + mutable fields, draft submissions, deletions of agent-owned rows), STILL declare actionSpec entries — just omit nextStep. The agent's next turn drains events via ggui_consume and reacts.`);
+    }
+    // Client-side gadget catalog — browser-capability hooks AND
+    // operator-registered 3rd-party plugins (Leaflet, Mapbox, Stripe, …)
+    // the runtime can serve for this app. Declare bindings under
+    // `clientCapabilities.gadgets` ONLY when the produced UI actually
+    // imports the hook.
+    //
+    // Routes through {@link composeAvailableGadgetsSection} so the
+    // decision LLM sees the same teaching text the synth-only path
+    // does — `description` (what), `usage` (when), with bounded
+    // per-entry + total budget. Both the decision path and the
+    // synth-only path share this one composer, so they agree on what
+    // the LLM is told about each gadget.
+    if (input.gadgets?.length) {
+        // `composeAvailableGadgetsSection` is component-aware — it
+        // flattens the package-keyed `GadgetDescriptor[]` catalog itself
+        // and renders hook AND component exports with their render idiom
+        // (call vs JSX) + package name. No pre-filter / pre-flatten here.
+        const gadgetsSection = composeAvailableGadgetsSection(input.gadgets);
+        if (gadgetsSection !== undefined) {
+            // Suffix the binding rule the previous flat-loop carried — the
+            // composer's section header doesn't say "declare under
+            // clientCapabilities.gadgets"; preserve that authoring nudge
+            // for the LLM. The permission column is intentionally dropped
+            // from the LLM's view: the operator's `App.gadgets`
+            // catalog still owns permission policy at registration time and
+            // push-time enrichment merges it back in.
+            parts.push(`${gadgetsSection}\n\nDeclare each chosen gadget under clientCapabilities.gadgets[<packageName>][<exportName>] = {} — the package name keys the outer map, the export name (use-prefixed hook or PascalCase component) keys the inner map. Declare ONLY when the produced UI imports the export.`);
+        }
+    }
+    // Blueprint candidates (with contract + intents when available)
+    if (input.blueprintCandidates.length > 0) {
+        const candidates = input.blueprintCandidates
+            .map((c) => {
+            let line = `  [${c.blueprintId}] ${c.description} (${c.verdict}, ${Math.round(c.similarity * 100)}% match)`;
+            line += ` — REUSE = instant render, CREATE NEW = 20s wait`;
+            if (c.contract) {
+                line += `\n    contract: ${JSON.stringify(c.contract)}`;
+            }
+            return line;
+        })
+            .join('\n');
+        parts.push(`Blueprint candidates (reuse any of these for instant render):\n${candidates}`);
+    }
+    else {
+        parts.push('Blueprint candidates: none (no cached components — "create" will generate new)');
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Tool schema for structured decision output.
+ *
+ * Matches @ggui-ai/protocol's NegotiatorDecision + DataContract types.
+ * Uses forced tool_choice to guarantee valid JSON output from the LLM.
+ *
+ * Module-internal — intentionally NOT exported. See the public-surface
+ * section of the top docstring.
+ */
+const DECISION_TOOL = {
+    name: 'ui_decision',
+    description: 'Output the UI decision with a full data contract.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['create', 'update', 'compose', 'replace'],
+                description: 'What to do: create (new UI), update (swap data), compose (add to stack), replace (swap UI type)',
+            },
+            reasoning: { type: 'string', description: 'Brief explanation' },
+            blueprintId: {
+                type: 'string',
+                description: 'Blueprint ID from candidates to reuse. Omit to generate new.',
+            },
+            contract: {
+                type: 'object',
+                description: 'Data contract — defines the UI shape and the four wire surfaces (propsSpec / actionSpec / contextSpec / streamSpec)',
+                properties: {
+                    intent: {
+                        type: 'string',
+                        description: 'Concise reusable purpose — e.g. "Display weather conditions". Same intent = cached component.',
+                    },
+                    propsSpec: {
+                        type: 'object',
+                        description: 'Props contract — initial render data',
+                        properties: {
+                            description: { type: 'string', description: 'What this data represents' },
+                            properties: {
+                                type: 'object',
+                                description: 'Per-prop definitions keyed by name. Each: { description, schema: { type }, required, example }',
+                                additionalProperties: {
+                                    type: 'object',
+                                    properties: {
+                                        description: { type: 'string' },
+                                        schema: { type: 'object', properties: { type: { type: 'string' } } },
+                                        required: { type: 'boolean' },
+                                        example: {},
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    actionSpec: {
+                        type: 'object',
+                        description: 'Action contract — flat map keyed by actionId. Each value describes one user-interaction event the UI can emit. Every action is agent-routed. Optional "nextStep" names the MCP tool the AGENT should invoke on its next turn after the event fires.',
+                        additionalProperties: {
+                            type: 'object',
+                            properties: {
+                                description: { type: 'string' },
+                                label: { type: 'string', description: 'Button label' },
+                                schema: { type: 'object' },
+                                icon: { type: 'string', description: 'Icon hint (emoji or name)' },
+                                nextStep: {
+                                    type: 'string',
+                                    description: 'MCP tool name the agent SHOULD call after the user fires this action (must appear in agentCapabilities.tools).',
+                                },
+                            },
+                        },
+                    },
+                    streamSpec: {
+                        type: 'object',
+                        description: 'Stream contract — flat map keyed by channel name. Declares typed live channels the component consumes. Each value is a StreamChannelEntry describing schema + optional source.tool (the agent-tool name whose deliveries feed this channel).',
+                        additionalProperties: { type: 'object' },
+                    },
+                },
+                required: ['intent'],
+            },
+            targetStackItemId: {
+                type: 'string',
+                description: 'Page to target (update/replace actions)',
+            },
+            adaptations: {
+                type: 'object',
+                description: 'UI adaptations based on device/context',
+                properties: {
+                    fontSize: { type: 'string', enum: ['compact', 'default', 'large'] },
+                    density: { type: 'string', enum: ['dense', 'default', 'spacious'] },
+                    complexity: { type: 'string', enum: ['simplified', 'default', 'detailed'] },
+                },
+            },
+        },
+        required: ['action', 'reasoning', 'contract'],
+    },
+};
+/** Make the UI decision via one LLM call with all context. */
+export async function makeDecision(input, llmCaller) {
+    const userMessage = buildDecisionUserMessage(input);
+    // Prefer structured output (tool use) — guaranteed valid JSON
+    if (llmCaller.callStructured) {
+        try {
+            const parsed = await llmCaller.callStructured(DECISION_SYSTEM_PROMPT, userMessage, DECISION_TOOL, 2048);
+            return {
+                decision: {
+                    action: parsed.action ?? 'create',
+                    reasoning: parsed.reasoning ?? 'Structured output',
+                    blueprintId: parsed.blueprintId ?? undefined,
+                    contract: mergeGadgets(mergeAgentCapabilities({ ...parsed.contract }, input.agentTools), input.gadgets),
+                    targetStackItemId: parsed.targetStackItemId ?? undefined,
+                    adaptations: parsed.adaptations ?? undefined,
+                },
+                alternatives: [],
+            };
+        }
+        catch (err) {
+            console.warn('[decision] Structured output failed, falling back to text:', err.message);
+        }
+    }
+    // Fallback: regex JSON extraction from raw text
+    const raw = await llmCaller.call(DECISION_SYSTEM_PROMPT, userMessage, 2048);
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+        return { decision: buildFallbackDecision(input), alternatives: [] };
+    }
+    try {
+        const parsed = JSON.parse(jsonMatch[0]);
+        return {
+            decision: {
+                action: parsed.action ?? 'create',
+                reasoning: parsed.reasoning ?? 'No reasoning provided',
+                blueprintId: parsed.blueprintId ?? undefined,
+                contract: mergeGadgets(mergeAgentCapabilities({ ...parsed.contract }, input.agentTools), input.gadgets),
+                targetStackItemId: parsed.targetStackItemId ?? undefined,
+                adaptations: parsed.adaptations ?? undefined,
+            },
+            alternatives: [],
+        };
+    }
+    catch {
+        return { decision: buildFallbackDecision(input), alternatives: [] };
+    }
+}
+/**
+ * Deterministically populate `contract.agentCapabilities.tools` from
+ * `input.agentTools`.
+ *
+ * The LLM decides which agent tools become user-triggered actions
+ * (`actionSpec[*].nextStep`), but the contract-level catalog — the
+ * canonical list of tool names the agent MAY invoke — is a superset
+ * of the input and not something the LLM needs to restate. Populating
+ * it here closes the gap where the contract under-declared its
+ * agent-tool surface.
+ *
+ * Merge behavior:
+ * - If the LLM returned a `contract.agentCapabilities`, union its entries with input names.
+ * - Input-only names get a minimal `AgentToolEntry` (description only).
+ * - LLM-declared entries are preserved verbatim (may carry richer schema metadata).
+ */
+function mergeAgentCapabilities(contract, inputAgentTools) {
+    if (!inputAgentTools?.length && !contract.agentCapabilities)
+        return contract;
+    const existing = contract.agentCapabilities?.tools ?? {};
+    const merged = { ...existing };
+    for (const name of inputAgentTools ?? []) {
+        if (!merged[name]) {
+            merged[name] = { description: `Agent-provided MCP tool: ${name}` };
+        }
+    }
+    const spec = {
+        tools: merged,
+    };
+    return { ...contract, agentCapabilities: spec };
+}
+/**
+ * Deterministically enrich `contract.clientCapabilities.gadgets` from
+ * the per-app gadget catalog (`app.gadgets`).
+ *
+ * Per-app `gadgets` declares which browser-capability gadgets the
+ * runtime can serve for the app. The LLM authors a per-contract subset
+ * (only the gadgets the produced UI actually uses) on the
+ * package-keyed wire map (`Record<package, Record<exportName,
+ * GadgetExportUse>>`), but partial entries (no `description` / `usage`
+ * override) are common — this merge fills in the canonical teaching
+ * text from the app catalog.
+ *
+ * Merge behavior:
+ * - Each wire `(package, exportName)` use that resolves to an
+ *   app-catalog export inherits the registered export's
+ *   `description` / `usage` (when the wire use didn't override them).
+ * - Wire uses that do NOT resolve to any app-catalog export are
+ *   preserved verbatim (the app may carry a third-party gadget the
+ *   catalog passed in here doesn't include).
+ * - The contract's set of declared `(package, export)` uses stays
+ *   exactly what the LLM authored — we don't append every app-catalog
+ *   export, since the contract only declares what the produced UI
+ *   references.
+ * - LLM-authored fields win on conflict (operator may have authored a
+ *   richer description/usage for the use at this specific call site).
+ *
+ * Identity keying routes through `gadgetIdentityKey` so the merge
+ * agrees byte-for-byte with the push-time gates on what "the same
+ * gadget export" means.
+ */
+function mergeGadgets(contract, appGadgets) {
+    if (!appGadgets?.length || !contract.clientCapabilities?.gadgets) {
+        return contract;
+    }
+    // Index every registered export by its `(name, package)` identity
+    // tuple. A descriptor-side `GadgetExport` carries no package
+    // identity, so combine `gadgetExportName(exp)` with the descriptor's
+    // own `package` to form the key the wire side keys by too.
+    const byExport = new Map();
+    for (const pkg of appGadgets) {
+        for (const exp of pkg.exports) {
+            byExport.set(gadgetIdentityKey({
+                name: gadgetExportName(exp),
+                package: pkg.package,
+            }), exp);
+        }
+    }
+    const enriched = {};
+    for (const [pkgName, packageUse] of Object.entries(contract.clientCapabilities.gadgets)) {
+        const enrichedPackage = {};
+        for (const [exportName, use] of Object.entries(packageUse)) {
+            const canonical = byExport.get(gadgetIdentityKey({ name: exportName, package: pkgName }));
+            if (canonical) {
+                enrichedPackage[exportName] = {
+                    // Registered export's teaching text as the base...
+                    ...(canonical.description !== undefined
+                        ? { description: canonical.description }
+                        : {}),
+                    ...(canonical.usage !== undefined ? { usage: canonical.usage } : {}),
+                    // ...then the wire use — LLM-authored fields win on conflict.
+                    ...use,
+                };
+            }
+            else {
+                enrichedPackage[exportName] = use;
+            }
+        }
+        enriched[pkgName] = enrichedPackage;
+    }
+    return {
+        ...contract,
+        clientCapabilities: { gadgets: enriched },
+    };
+}
+function buildFallbackDecision(input) {
+    const props = input.agentData
+        ? Object.fromEntries(Object.entries(input.agentData).map(([key, value]) => [
+            key,
+            {
+                description: key,
+                schema: { type: inferType(value) },
+                required: true,
+                example: value,
+            },
+        ]))
+        : {};
+    const contract = {
+        propsSpec: { properties: props },
+    };
+    return {
+        action: 'create',
+        reasoning: 'Fallback: creating new UI (decision LLM failed to parse)',
+        contract: mergeGadgets(mergeAgentCapabilities(contract, input.agentTools), input.gadgets),
+    };
+}
+function inferType(value) {
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'object' && value !== null)
+        return 'object';
+    return 'string';
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @ggui-ai/negotiator — open-source UI decision engine for ggui.
+ *
+ * Decides which UI to render (create/update/compose/replace) given agent
+ * signal (data/prompt/context/agentTools) and current session state.
+ *
+ * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
+ * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
+ * semantics are open here; concrete cloud-vendor bindings (e.g. a
+ * managed embedding service or vector store) live behind those seams
+ * so this package stays deployment-agnostic.
+ *
+ * This barrel stays narrow — it exports only the minimum surface
+ * consumers need. Each additive export carries semver weight.
+ */
+export { hashContract, buildVariant } from './contract-hash.js';
+export { computeIntentId, shouldSuppressSuggestion } from './intent.js';
+export { detectDataPatterns, buildSuggestion } from './suggestion.js';
+export type { NegotiatorSuggestion } from './suggestion.js';
+export { inferInteractionMode, inferJsonSchemaType } from './pure.js';
+export { ragSearch } from './rag-search.js';
+export type { RagSearchDeps, RagSearchInput, RagSearchResult, } from './rag-search.js';
+export type { NegotiatorOption } from './types.js';
+export type { LLMCaller, LLMCallerConfig, ToolSchema } from './llm-caller.js';
+export type { SessionState, SessionStackEntry } from './session.js';
+export type { NegotiatorDecisionInput } from './decision-input.js';
+export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
+export { negotiate } from './negotiate.js';
+export type { NegotiateDeps, NegotiateInput, NegotiateConfig, NegotiateResult, } from './negotiate.js';
+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 { 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

@@ -0,0 +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,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACpE,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"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @ggui-ai/negotiator — open-source UI decision engine for ggui.
+ *
+ * Decides which UI to render (create/update/compose/replace) given agent
+ * signal (data/prompt/context/agentTools) and current session state.
+ *
+ * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
+ * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
+ * semantics are open here; concrete cloud-vendor bindings (e.g. a
+ * managed embedding service or vector store) live behind those seams
+ * so this package stays deployment-agnostic.
+ *
+ * This barrel stays narrow — it exports only the minimum surface
+ * consumers need. Each additive export carries semver weight.
+ */
+export { hashContract, buildVariant } from './contract-hash.js';
+export { computeIntentId, shouldSuppressSuggestion } from './intent.js';
+export { detectDataPatterns, buildSuggestion } from './suggestion.js';
+export { inferInteractionMode, inferJsonSchemaType } from './pure.js';
+export { ragSearch } from './rag-search.js';
+export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
+export { negotiate } from './negotiate.js';
+export { rerankCandidates } from './llm-rerank.js';
+export { synthesizeContract } from './synthesize-contract.js';
+export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';

package/dist/intent.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Deterministic identifier for a negotiation intent.
+ *
+ * Used by the suggestion engine to deduplicate auto-suggested UIs
+ * within a session — two prompts that would produce the same intent
+ * collapse to a single suggestion. SHA-256 truncated to 16 hex chars
+ * (64 bits) gives collision-resistant ids without being wastefully
+ * large in logs.
+ *
+ * @param sessionId  Scope. Intent ids are session-local.
+ * @param data       Data shape (keys only — values ignored). Undefined → 'no-data'.
+ * @param action     Optional action verb. Defaults to 'create'.
+ */
+export declare function computeIntentId(sessionId: string, data: Record<string, unknown> | undefined, action?: string): string;
+/**
+ * True if the given intent id is already being handled in this session.
+ *
+ * The suggestion engine uses this to avoid re-suggesting the same UI
+ * while the agent is already preparing one.
+ */
+export declare function shouldSuppressSuggestion(intentId: string, activeIntentIds: Set<string>): boolean;
+//# sourceMappingURL=intent.d.ts.map

package/dist/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,OAAO,CAET"}

package/dist/intent.js

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+/**
+ * Deterministic identifier for a negotiation intent.
+ *
+ * Used by the suggestion engine to deduplicate auto-suggested UIs
+ * within a session — two prompts that would produce the same intent
+ * collapse to a single suggestion. SHA-256 truncated to 16 hex chars
+ * (64 bits) gives collision-resistant ids without being wastefully
+ * large in logs.
+ *
+ * @param sessionId  Scope. Intent ids are session-local.
+ * @param data       Data shape (keys only — values ignored). Undefined → 'no-data'.
+ * @param action     Optional action verb. Defaults to 'create'.
+ */
+export function computeIntentId(sessionId, data, action) {
+    const dataShape = data ? Object.keys(data).sort().join(',') : 'no-data';
+    const raw = `${sessionId}:${dataShape}:${action ?? 'create'}`;
+    return createHash('sha256').update(raw).digest('hex').slice(0, 16);
+}
+/**
+ * True if the given intent id is already being handled in this session.
+ *
+ * The suggestion engine uses this to avoid re-suggesting the same UI
+ * while the agent is already preparing one.
+ */
+export function shouldSuppressSuggestion(intentId, activeIntentIds) {
+    return activeIntentIds.has(intentId);
+}