@ggui-ai/negotiator 0.1.0-rc.1

package/dist/contract-validators.js

@@ -0,0 +1,478 @@
+/**
+ * Programmatic safety validators for `DataContract` shapes.
+ *
+ * Two detectors live here:
+ *
+ *   - {@link validateContractStructure} — pure structural heuristics that
+ *     flag over-specified contracts without any runtime dependency. The
+ *     load-bearing finding is `redundant-action`: an empty-payload
+ *     `actionSpec` entry whose name parses as a mutator of an existing
+ *     `contextSpec` slot. Real example that motivated this module: a
+ *     synthesizer emitted both `actionSpec.increment` (empty payload)
+ *     and `contextSpec.count` for a counter widget. The generator wired
+ *     the increment button to `useAction("increment")`, dispatching to
+ *     the agent instead of locally bumping the count slot — a button
+ *     that looks right but does nothing. The structural fix is to
+ *     declare `actionSpec[X]` IFF X is a discrete event the agent must
+ *     witness; mutators of context slots use the slot setter.
+ *
+ *   - {@link validateContractNovelty} — embeds the contract via the
+ *     shared `summarizeContract` helper and computes cosine distance to
+ *     the nearest registered blueprint. Distance above the threshold
+ *     yields a `novel-shape` finding so operators can review before the
+ *     contract pollutes the registry's neighborhood.
+ *
+ * Both validators return a `ContractValidationResult` carrying readonly
+ * findings — callers (synthesizer, registerBlueprint) decide how to act
+ * on warnings vs errors. Findings are deterministic; no LLM judgment.
+ */
+import { summarizeContract } from '@ggui-ai/protocol';
+// =============================================================================
+// Mutator verb dictionary
+// =============================================================================
+/**
+ * Verbs whose presence at the START of an action name signals "this
+ * action mutates state the agent observes" — i.e., a candidate slot
+ * setter masquerading as an action.
+ *
+ * Scope decisions (in vs out):
+ *
+ *   IN: verbs that almost always mutate observable state in
+ *   counter/list/form/UI patterns we've seen in benchmark traces.
+ *
+ *   OUT: verbs that often LOOK like mutators but legitimately want
+ *   the agent in the loop:
+ *     - `submit`  — submit IS the discrete event; the agent must
+ *                   witness "user pressed submit" beyond the form's
+ *                   draft slot. Form pattern is `actionSpec.submit` +
+ *                   `contextSpec.formData` (legitimate pairing).
+ *     - `save`    — save typically triggers a wired tool (write to
+ *                   storage). Same pattern as submit.
+ *     - `cancel`  — discrete user gesture, not a slot mutation.
+ *     - `confirm` — discrete user gesture.
+ *     - `select`  — selection often IS the slot value (e.g., select
+ *                   reduces to setting `selectedId`), but it's also
+ *                   used as a discrete event ("user picked X, fetch
+ *                   detail"). Out by default; false-negatives here
+ *                   are cheaper than false-positives.
+ *     - `open`/`close` — often dialog gestures, not slot mutations.
+ *
+ * Authors who want a tighter or looser policy override the list at
+ * call site (option for future expansion — not exposed yet to keep
+ * the API minimal).
+ */
+const MUTATOR_VERBS = [
+    'increment',
+    'decrement',
+    'reset',
+    'set',
+    'add',
+    'remove',
+    'delete',
+    'update',
+    'change',
+    'toggle',
+    'flip',
+    'clear',
+    'append',
+    'prepend',
+    'insert',
+];
+/**
+ * Returns the mutator verb that prefixes `actionName`, or `null` when
+ * none does. Matches case-insensitively and only at the START — `set`
+ * matches `setCount` but not `unsetCount`; `reset` is its own verb (not
+ * `set` + `Count` with a leading `re`).
+ *
+ * Strict longest-match: when multiple verbs are valid prefixes (e.g.
+ * `reset` is also matched by `set`-with-`re`-prefix only via different
+ * boundary, but we don't allow that), we walk verbs longest-first so
+ * `reset*` is parsed as `reset|*` not `re|set*`.
+ */
+function stripMutatorVerb(actionName) {
+    if (actionName.length === 0)
+        return null;
+    const lower = actionName.toLowerCase();
+    // Longest-prefix-first to disambiguate `reset` vs (hypothetical) `re`.
+    const sorted = [...MUTATOR_VERBS].sort((a, b) => b.length - a.length);
+    for (const verb of sorted) {
+        if (!lower.startsWith(verb))
+            continue;
+        const tail = actionName.slice(verb.length);
+        // Boundary: either the verb consumed the whole name, or the
+        // character after the verb is a word boundary (uppercase letter,
+        // digit, or underscore — typical camelCase / snake_case break).
+        if (tail.length === 0) {
+            return { verb, remainder: '' };
+        }
+        const next = tail.charAt(0);
+        const isBoundary = (next >= 'A' && next <= 'Z') ||
+            (next >= '0' && next <= '9') ||
+            next === '_';
+        if (!isBoundary)
+            continue;
+        return { verb, remainder: tail };
+    }
+    return null;
+}
+/**
+ * Decide whether an action name with a mutator-verb prefix targets the
+ * given context slot.
+ *
+ * Algorithm:
+ *
+ *   1. Strip the verb prefix → remainder.
+ *   2. Empty remainder (action is just the verb, e.g., "increment")
+ *      AND the contract has exactly one context slot ⇒ flag.
+ *   3. Non-empty remainder ⇒ flag iff remainder contains slotName OR
+ *      slotName contains remainder, case-insensitively. This catches
+ *      `incrementCount` ↔ `count`, `setUserName` ↔ `userName`,
+ *      `addItem` ↔ `items`, etc., without false-positiving on
+ *      `setTheme` ↔ `count`.
+ *
+ * The single-slot case is the load-bearing one for the counter bug:
+ * `increment` (no remainder) + the only slot being `count` is the
+ * exact pattern.
+ */
+function nameImpliesMutation(args) {
+    const { actionName, slotName, totalSlots } = args;
+    const stripped = stripMutatorVerb(actionName);
+    if (!stripped)
+        return false;
+    if (stripped.remainder.length === 0) {
+        return totalSlots === 1;
+    }
+    const a = stripped.remainder.toLowerCase();
+    const b = slotName.toLowerCase();
+    return a.includes(b) || b.includes(a);
+}
+// =============================================================================
+// Empty-payload detection
+// =============================================================================
+/**
+ * True when an action's schema is "empty payload" — either omitted
+ * entirely or the canonical `{type:'object', properties:{},
+ * additionalProperties:false}` shape the synthesizer emits when the LLM
+ * declines to declare fields. Actions with declared payload fields
+ * (e.g., `{chipText: string}`) are NOT empty — those legitimately
+ * carry data the agent needs.
+ */
+function isEmptyPayloadSchema(schema) {
+    if (schema === undefined)
+        return true;
+    if (schema.type !== 'object')
+        return false;
+    if (schema.properties === undefined)
+        return true;
+    return Object.keys(schema.properties).length === 0;
+}
+// =============================================================================
+// Structural validator (synchronous, dependency-free)
+// =============================================================================
+/**
+ * Run the synchronous structural detectors against `contract`.
+ *
+ * Currently:
+ *   - `redundant-action`: empty-payload action whose name parses as a
+ *     mutator of an existing context slot.
+ *
+ * Returns an empty findings array for contracts that don't trip any
+ * heuristic.
+ */
+export function validateContractStructure(contract) {
+    const findings = [];
+    const actionSpec = contract.actionSpec;
+    const contextSpec = contract.contextSpec;
+    if (!actionSpec || !contextSpec) {
+        return { findings };
+    }
+    const slotNames = Object.keys(contextSpec);
+    if (slotNames.length === 0) {
+        return { findings };
+    }
+    for (const [actionName, entry] of Object.entries(actionSpec)) {
+        if (!isEmptyPayloadSchema(entry.schema))
+            continue;
+        for (const slotName of slotNames) {
+            if (!nameImpliesMutation({
+                actionName,
+                slotName,
+                totalSlots: slotNames.length,
+            })) {
+                continue;
+            }
+            findings.push({
+                kind: 'redundant-action',
+                severity: 'warn',
+                actionName,
+                slotName,
+                hint: `Action "${actionName}" has empty payload and looks like a mutator of context slot "${slotName}". Prefer setting the slot directly from the component instead of declaring an action — the agent observes slot changes without a discrete event.`,
+            });
+            break;
+        }
+    }
+    return { findings };
+}
+// =============================================================================
+// Actions-vs-context placement validator (synchronous, loose / advisory)
+// =============================================================================
+//
+// Loose self-check: every finding is `severity: 'warn'`. Synth's
+// pipeline can log warnings to telemetry without blocking output. The
+// rule being checked: actions drive agent turns, context observes
+// state, and there is no third category.
+//
+// Three checks, each scoped narrowly to avoid false positives:
+//
+//   1. Name collision across specs — same key in both actionSpec and
+//      contextSpec. Structurally a category error: synth couldn't
+//      decide which bucket. High-confidence rule.
+//
+//   2. State-y name in actionSpec — names matching common state-mirror
+//      patterns (autosave, draft, typing, change, focus, blur, …).
+//      These usually represent continuous state, not turn-driving
+//      events. Warning, not error — false positives possible (a real
+//      "submitDraft" action is legitimate).
+//
+//   3. Action-y name in contextSpec — names matching common terminal
+//      verbs (submit, send, confirm, cancel, next, done, apply, …).
+//      These usually represent discrete events, not state. Warning,
+//      not error — false positives possible (a "submitTime" timestamp
+//      slot is legitimate state).
+//
+// All three checks are intentionally LOOSE. They surface candidates;
+// consumers (synth, operator dashboards) decide to act on them.
+const STATE_LIKE_NAME_PATTERN = /^(auto|on)?(save|draft|change|update|sync|saved|typing|scroll|hover|focus|blur|input)/i;
+const ACTION_LIKE_NAME_PATTERN = /^(submit|send|confirm|cancel|next|back|done|apply|delete|create|approve|reject)$/i;
+/**
+ * Validate the actions-vs-context placement rule: actions drive agent
+ * turns, context observes state. Findings 1-3 are advisory `warn`;
+ * finding 4 (`context-props-name-collision`) is `error` — it is a
+ * SPEC §2.10 MUST. Synth pipelines use it as a self-check over their
+ * own output.
+ *
+ * Four findings:
+ *
+ *   - `actions-vs-context-name-collision` — same key appears in both
+ *     `actionSpec` AND `contextSpec`. Synth couldn't decide which
+ *     bucket. Pick one.
+ *
+ *   - `action-name-looks-state-y` — `actionSpec` entry name matches a
+ *     state-mirror pattern (autosave, draft, typing, change, …). The
+ *     thing might be observable state (continuous) rather than a
+ *     turn-driving event. Consider `contextSpec`.
+ *
+ *   - `context-name-looks-action-y` — `contextSpec` entry name matches
+ *     a discrete-event pattern (submit, send, confirm, …). The thing
+ *     might be a one-shot event the agent reacts to. Consider
+ *     `actionSpec`.
+ *
+ *   - `context-props-name-collision` (ERROR) — a `contextSpec` slot key
+ *     equals a `propsSpec` property name. SPEC §2.10 MUST: the
+ *     generated boilerplate would shadow the prop binding.
+ *
+ * Pure / synchronous / no dependencies. Safe to call on every synth
+ * output without measurable cost.
+ */
+export function validateActionsVsContext(contract) {
+    const findings = [];
+    const actionKeys = Object.keys(contract.actionSpec ?? {});
+    const contextKeys = Object.keys(contract.contextSpec ?? {});
+    // 1. Same key in both specs — category collision.
+    for (const k of actionKeys) {
+        if (contextKeys.includes(k)) {
+            findings.push({
+                kind: 'actions-vs-context-name-collision',
+                severity: 'warn',
+                actionName: k,
+                slotName: k,
+                hint: `"${k}" appears in both actionSpec and contextSpec. Pick one — actions drive agent turns; contextSpec is observed state.`,
+            });
+        }
+    }
+    // 2. State-y name in actionSpec.
+    for (const k of actionKeys) {
+        if (STATE_LIKE_NAME_PATTERN.test(k)) {
+            findings.push({
+                kind: 'action-name-looks-state-y',
+                severity: 'warn',
+                actionName: k,
+                hint: `actionSpec entry "${k}" sounds like state (autosave/draft/change/etc.). If it doesn't drive an agent turn, consider contextSpec instead.`,
+            });
+        }
+    }
+    // 3. Action-y name in contextSpec.
+    for (const k of contextKeys) {
+        if (ACTION_LIKE_NAME_PATTERN.test(k)) {
+            findings.push({
+                kind: 'context-name-looks-action-y',
+                severity: 'warn',
+                slotName: k,
+                hint: `contextSpec entry "${k}" sounds like a discrete event (submit/send/confirm/etc.). If it drives an agent turn, consider actionSpec instead.`,
+            });
+        }
+    }
+    // 4. contextSpec slot key collides with a propsSpec property name.
+    // SPEC §2.10 MUST — the generated boilerplate binds both into the
+    // same scope, so a collision would shadow the prop. The protocol's
+    // `CTR_DUP_NAME` only covers action/stream/context collisions, NOT
+    // props↔context — so this is the one cross-spec collision the synth
+    // gate would otherwise miss. `error` severity → the synth's repair
+    // loop fixes it.
+    const propKeys = Object.keys(contract.propsSpec?.properties ?? {});
+    for (const k of contextKeys) {
+        if (propKeys.includes(k)) {
+            findings.push({
+                kind: 'context-props-name-collision',
+                severity: 'error',
+                slotName: k,
+                hint: `contextSpec slot "${k}" collides with propsSpec.properties.${k} — the generated boilerplate would shadow the prop binding. Rename one of them.`,
+            });
+        }
+    }
+    return { findings };
+}
+// =============================================================================
+// Coherence validator (synchronous, intent-aware — the one validator
+// that reads the intent, not just the contract)
+// =============================================================================
+//
+// Catches the "degenerate contract" flake: the synthesizer occasionally
+// emits a contract that is JUST an actionSpec with no data surface at
+// all — no contextSpec, no propsSpec, no streamSpec, no
+// clientCapabilities. The agent then receives a contentless event it
+// cannot act on (a `finish` for a checkout it has no data for; a
+// `share` for an article it was never given).
+//
+// `{actionSpec: {confirm, cancel}}` with no data surface is the ONE
+// legitimate no-surface shape (a pure-decision modal) — so the rule is
+// gated on the intent: it fires only when the intent describes a UI
+// that demonstrably displays or collects data (a flow / form / article
+// / profile / …). A pure-decision modal intent matches none of those,
+// so it is never flagged.
+/**
+ * Intent signal for "this UI displays or collects data, so the
+ * contract MUST declare a data surface." Deliberately narrow — every
+ * keyword is an intent that genuinely cannot work as actionSpec-only.
+ */
+// `card` and `flow` are deliberately EXCLUDED — too common in English
+// ("a card to confirm this flow" is a legit pure-decision modal). The
+// flow-* corpus intents still match via `wizard` / `checkout` /
+// `onboard` / `multi-step`, so coverage is unchanged.
+const DATA_SURFACE_INTENT_PATTERN = /\bwizard\b|multi-?step|\d+-step|\bcheckout\b|\bonboard|\barticle\b|\bdocument\b|\bprofile\b|\bdashboard\b|\bform\b|\breport\b|\beditor\b/i;
+/**
+ * Validate that a contract is coherent with its intent. The only
+ * intent-aware validator: it reads the natural-language intent
+ * alongside the contract.
+ *
+ * One rule — `incoherent-no-data-surface`: the intent describes a
+ * data-bearing UI but the contract declares only EMPTY-payload
+ * actions, with no contextSpec / propsSpec / streamSpec /
+ * clientCapabilities. That contract is structurally degenerate — the
+ * agent gets a contentless event with nothing behind it. Emitted at
+ * `severity: 'error'` so the synth's repair loop retries (the
+ * contract is protocol-valid, so nothing else flags it).
+ *
+ * The empty-payload condition matters: an action that DOES carry a
+ * payload (e.g. an `autosave` action whose schema includes the draft
+ * text) gives the agent data through the payload — that is not
+ * degenerate and is NOT flagged.
+ *
+ * Pure / synchronous. The rule fires ONLY on the degenerate output —
+ * a correct contract for any data-bearing intent always has a
+ * surface, so it never false-positives on good output.
+ */
+export function validateContractCoherence(contract, intent) {
+    const findings = [];
+    const actions = contract.actionSpec ?? {};
+    const hasAction = Object.keys(actions).length > 0;
+    const allActionsEmptyPayload = Object.values(actions).every((a) => isEmptyPayloadSchema(a.schema));
+    const hasContext = contract.contextSpec !== undefined &&
+        Object.keys(contract.contextSpec).length > 0;
+    const hasProps = contract.propsSpec?.properties !== undefined &&
+        Object.keys(contract.propsSpec.properties).length > 0;
+    const hasStream = contract.streamSpec !== undefined &&
+        Object.keys(contract.streamSpec).length > 0;
+    const hasGadgets = contract.clientCapabilities?.gadgets !== undefined &&
+        Object.keys(contract.clientCapabilities.gadgets).length > 0;
+    if (hasAction &&
+        allActionsEmptyPayload &&
+        !hasContext &&
+        !hasProps &&
+        !hasStream &&
+        !hasGadgets &&
+        DATA_SURFACE_INTENT_PATTERN.test(intent)) {
+        findings.push({
+            kind: 'incoherent-no-data-surface',
+            severity: 'error',
+            hint: 'The intent describes a UI that displays or collects data, but the contract declares only an actionSpec — no contextSpec, propsSpec, or streamSpec. The agent would receive an event with nothing behind it. Declare the data surface: contextSpec for state the user enters / the UI tracks (a wizard\'s step + form fields), or propsSpec for content the agent supplies at render (an article, a profile).',
+        });
+    }
+    return { findings };
+}
+// =============================================================================
+// Novelty validator (async, depends on embedding + vector store)
+// =============================================================================
+const DEFAULT_NOVELTY_THRESHOLD_COSINE = 0.8;
+/**
+ * Run the cosine-distance novelty detector. Embeds the contract via
+ * `summarizeContract` and queries the vector store for the nearest
+ * neighbor in `scope`. Distance above `thresholdCosine` yields a
+ * `novel-shape` finding so operators see "this contract is far from
+ * anything we've registered — review encouraged" before it ships.
+ *
+ * Defaults to `severity: 'warn'`. Distance is computed as
+ * `1 - cosineSimilarity`; `VectorStore.query` returns
+ * cosine-similarity scores in `[0, 1]` per the seam contract.
+ *
+ * Empty index (no nearest neighbor in scope) ⇒ flag with
+ * `cosine: undefined` because a fresh registry will register
+ * everything as novel; operators learn that the registry is empty.
+ */
+export async function validateContractNovelty(contract, deps, options = {}) {
+    const threshold = options.thresholdCosine ?? DEFAULT_NOVELTY_THRESHOLD_COSINE;
+    const summary = summarizeContract(contract);
+    const queryEmbedding = await deps.embedding.embed(summary);
+    const results = await deps.vectorStore.query(deps.scope, queryEmbedding, 1);
+    if (results.length === 0) {
+        return {
+            findings: [
+                {
+                    kind: 'novel-shape',
+                    severity: 'warn',
+                    hint: `No registered blueprints in scope "${deps.scope}" — this contract has no neighbors. Review encouraged before it becomes the seed for the registry.`,
+                },
+            ],
+        };
+    }
+    const nearest = results[0];
+    if (!nearest) {
+        return { findings: [] };
+    }
+    const distance = 1 - nearest.score;
+    if (distance < threshold) {
+        return { findings: [] };
+    }
+    return {
+        findings: [
+            {
+                kind: 'novel-shape',
+                severity: 'warn',
+                cosine: nearest.score,
+                hint: `Cosine distance ${distance.toFixed(3)} from nearest registered blueprint exceeds threshold ${threshold.toFixed(3)} — review encouraged before the contract pollutes the registry's neighborhood.`,
+            },
+        ],
+    };
+}
+/**
+ * Render a findings array as a single human-readable line for use in
+ * synthesizer `reason` strings, cache trace events, and operator logs.
+ * Empty findings → empty string so callers can append unconditionally.
+ */
+export function formatValidationFindings(result) {
+    if (result.findings.length === 0)
+        return '';
+    return result.findings
+        .map((f) => `[${f.severity}:${f.kind}] ${f.hint}`)
+        .join(' | ');
+}

package/dist/decision-input.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `NegotiatorDecisionInput` — the full input to `makeDecision`.
+ *
+ * Kept in its own file so a typed re-export shim in
+ * `core/negotiation/src/types.ts` can keep the legacy import path
+ * alive without pulling the (bigger, commit-5) decision runtime
+ * into a types-only import.
+ *
+ * The `blueprintCandidates` entry shape is inlined intentionally —
+ * those five fields are the only projection `makeDecision` reads
+ * from a `NegotiatorOption`; extracting a named type here would
+ * grow public surface for no consumer.
+ */
+import type { GadgetDescriptor, DataContract } from '@ggui-ai/protocol';
+import type { SessionState } from './session.js';
+/** Input to the decision engine. */
+export interface NegotiatorDecisionInput {
+    agentData?: Record<string, unknown>;
+    agentPrompt?: string;
+    agentContext?: string | Record<string, unknown>;
+    /**
+     * MCP tools the AGENT invokes (catalog seed). The decision engine
+     * merges these into the resulting contract's
+     * `agentCapabilities.tools` catalog. Cross-references are authored
+     * by the LLM: the catalog is referenced from
+     * `actionSpec[*].nextStep` (post-action hint for the agent's next
+     * turn) and `streamSpec[*].source.tool` (channel data source). The
+     * component never calls these.
+     */
+    agentTools?: string[];
+    /**
+     * Browser-capability gadget catalog declared for the app. The
+     * handshake handler reads this from `app.gadgets` and
+     * threads it here so the decision LLM knows which gadget bindings
+     * the produced UI may reference (and so the merge step can enrich
+     * partial LLM output with canonical entries from the catalog).
+     */
+    gadgets?: readonly GadgetDescriptor[];
+    sessionState: SessionState;
+    blueprintCandidates: Array<{
+        blueprintId: string;
+        description: string;
+        contract?: DataContract;
+        similarity: number;
+        verdict: 'exact' | 'partial';
+    }>;
+}
+//# sourceMappingURL=decision-input.d.ts.map

package/dist/decision-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-input.d.ts","sourceRoot":"","sources":["../src/decision-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,oCAAoC;AACpC,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,YAAY,EAAE,YAAY,CAAC;IAC3B,mBAAmB,EAAE,KAAK,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;KAC9B,CAAC,CAAC;CACJ"}

package/dist/decision-input.js

@@ -0,0 +1,14 @@
+/**
+ * `NegotiatorDecisionInput` — the full input to `makeDecision`.
+ *
+ * Kept in its own file so a typed re-export shim in
+ * `core/negotiation/src/types.ts` can keep the legacy import path
+ * alive without pulling the (bigger, commit-5) decision runtime
+ * into a types-only import.
+ *
+ * The `blueprintCandidates` entry shape is inlined intentionally —
+ * those five fields are the only projection `makeDecision` reads
+ * from a `NegotiatorOption`; extracting a named type here would
+ * grow public surface for no consumer.
+ */
+export {};

package/dist/decision.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { NegotiatorAlternative, NegotiatorDecision } from '@ggui-ai/protocol';
+import type { NegotiatorDecisionInput } from './decision-input.js';
+import type { LLMCaller } from './llm-caller.js';
+export declare 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.\n\nRespond with a JSON object:\n{\n  \"action\": \"create\" | \"update\" | \"compose\" | \"replace\",\n  \"reasoning\": \"1-2 sentences explaining why\",\n  \"blueprintId\": \"matched blueprint ID or null\",\n  \"targetStackItemId\": \"existing page to update/compose/replace, or null\",\n  \"contract\": {\n    \"intent\": \"Concise purpose \u2014 e.g. 'Display current weather conditions for a quick daily check'\",\n    \"propsSpec\": {\n      \"properties\": {\n        \"fieldName\": {\n          \"description\": \"what this field is\",\n          \"schema\": { \"type\": \"string\" },\n          \"required\": true,\n          \"example\": \"sample value\"\n        }\n      }\n    }\n  },\n  \"adaptations\": {\n    \"fontSize\": \"compact\" | \"default\" | \"large\",\n    \"density\": \"dense\" | \"default\" | \"spacious\",\n    \"complexity\": \"simplified\" | \"default\" | \"detailed\"\n  }\n}\n\nINTENT RULES (most important):\n- The \"intent\" field captures WHY this UI exists in one sentence.\n- Include: the user's goal (why), what data is shown (what), and how they interact (how).\n- Be abstract enough to match reusable patterns \u2014 \"Display current weather conditions\" not \"Display Tokyo weather at 3pm\".\n- Same intent = same component can be reused with different data.\n- Examples:\n  - \"Display current weather conditions for a quick daily check\"\n  - \"Collect user feedback via a multi-field survey form\"\n  - \"Show real-time stock prices with live updates\"\n  - \"Compare two products side by side for purchase decision\"\n\nDECISION RULES:\n- \"create\": No existing UI or blueprint matches this intent. Show something new.\n- \"update\": An existing UI on the stack has the same intent. Update its props.\n- \"compose\": An existing UI could incorporate this data as a section.\n- \"replace\": Two or more related UIs would be better as a single unified view.\n\nREUSE BIAS (critical for performance):\n- Reusing a blueprint = INSTANT render (cached code, <1 second).\n- Creating new = 20+ seconds of generation. The user waits.\n- Default to reuse. Only \"create\" when NO candidate can reasonably serve the request.\n- A candidate that shows the SAME KIND of data (e.g., weather, stock prices, user profiles) is a match \u2014 even if the specific data differs (Tokyo vs Seoul, AAPL vs GOOG).\n- Ask yourself: \"Can this candidate display the agent's data with different prop values?\" If yes \u2192 reuse it.\n- When reusing a blueprint, copy its contract EXACTLY as-is (including its intent). Do NOT rephrase the intent.\n\nCONTRACT RULES:\n- Always include an \"intent\" field \u2014 it's required.\n- If reusing a blueprint: use that blueprint's contract verbatim. Do not modify intent or propsSpec.\n- If no blueprint match: infer propsSpec.properties from the agent's data shape. Each key becomes a prop.\n- Use the data values as examples.\n\nACTION SPEC \u2014 declare interactive affordances WHENEVER you see them in the data:\n- The discrimination is local-state vs persistent-state, NOT \"did the agent declare agentTools\".\n- 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 \u2014 the agent observes context via its next ggui_consume.\n- 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.\n- Inference signals for persistent state:\n  \u2022 Items with `id`/`itemId`/`uuid` fields + boolean toggle fields like `done`/`completed`/`checked`/`pinned`/`enabled` \u2192 toggle action (e.g. `toggleTodo`, `togglePin`).\n  \u2022 Lists where the data shape implies the agent maintains identity \u2192 add/delete actions.\n  \u2022 Form data with mutable fields + a submit gesture \u2192 submit action.\n  \u2022 A click that would cause a server-side side-effect (publish, archive, send, delete-from-database) \u2192 action.\n- nextStep is OPTIONAL on actionSpec entries:\n  \u2022 Bind `nextStep: \"tool_name\"` ONLY when input.agentTools contains a matching tool (exact or close name match \u2014 `todo_toggle` matches the `toggleTodo` action).\n  \u2022 If no agentTools match, OMIT nextStep. Events drain via ggui_consume on the agent's next turn \u2014 the agent's reasoning loop sees the event and decides what to do.\n- Examples:\n  \u2022 agentTools=[\"todo_toggle\",\"todo_delete\"] + todo data \u2192 actionSpec: { \"toggleTodo\": { label: \"Toggle\", schema: {type:\"object\",properties:{id:{type:\"string\"}},required:[\"id\"]}, nextStep: \"todo_toggle\" }, \"deleteTodo\": {...nextStep: \"todo_delete\"} }\n  \u2022 agentTools=[] + todo data \u2192 SAME actionSpec entries WITHOUT nextStep. The agent's next turn reads the event and reacts.\n  \u2022 agentTools=[] + counter prompt \u2192 contextSpec.count only. NO actionSpec.\n\nAGENT CAPABILITIES (catalog):\n- You do NOT need to emit contract.agentCapabilities \u2014 it is populated deterministically from input.agentTools after you return.\n- Focus on actionSpec entries + their optional nextStep bindings; the catalog auto-populates.\n\nANTI-PATTERNS \u2014 DO NOT EMIT (cross-ref linter rejects at push):\n- \"props\" / \"props.properties\" as a CONTRACT field      (retired contract-side spelling \u2014 the contract field is propsSpec; the wire field on push/update is still \"props\" but carries VALUES, not the spec)\n- \"wiredTools\" / \"agentTools\" / \"clientTools\" catalog names  (retired; use agentCapabilities.tools / clientCapabilities.gadgets)\n- clientCapabilities.capabilities                       (retired inner key; use clientCapabilities.gadgets)\n- ActionEntry.tool / ActionEntry.dispatch.kind          (retired discriminated union; use the flat nextStep field)\n- mode: 'host-routed' / mode: 'agent-routed'            (retired; all actions are agent-routed)\n- broadcast: { ... } as a top-level field               (retired; use streamSpec[X].source instead)";
+export declare function buildDecisionUserMessage(input: NegotiatorDecisionInput): string;
+/** Make the UI decision via one LLM call with all context. */
+export declare function makeDecision(input: NegotiatorDecisionInput, llmCaller: LLMCaller): Promise<{
+    decision: NegotiatorDecision;
+    alternatives: NegotiatorAlternative[];
+}>;
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAQV,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,eAAO,MAAM,sBAAsB,8nMAsFiE,CAAC;AAErG,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAwG/E;AAuGD,8DAA8D;AAC9D,wBAAsB,YAAY,CAChC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,YAAY,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAAC,CAkElF"}