@ggui-ai/negotiator 0.1.0-rc.3 → 0.2.0-alpha.1

package/README.md

@@ -3,9 +3,9 @@
 UI decision engine for [ggui](https://github.com/ggui-ai/ggui).
 
 Given an agent's signal (data, prompt, context, agent tools) and the current
-session state, the negotiator decides **which UI to render** — create a new
-interface, update an existing one, compose with what's on screen, or replace
-it — and, on the cold path, synthesizes the data contract that drives it.
+render state, the negotiator decides **which UI to render** — create a new
+interface, update an existing one, or replace it — and, on the cold path,
+synthesizes the data contract that drives it.
 
 The package is deployment-agnostic. It composes the storage interfaces
 defined in `@ggui-ai/mcp-server-core` (`EmbeddingProvider`, `VectorStore`),
@@ -21,10 +21,10 @@ pnpm add @ggui-ai/negotiator
 ## What's in the box
 
 - **`negotiate(deps, input)`** — top-level orchestrator. Runs RAG search over
-  registered blueprints, reads session state, fast-paths exact blueprint
+  registered blueprints, reads render state, fast-paths exact blueprint
   hits, and otherwise calls the decision LLM.
 - **`makeDecision(...)`** — the decision step in isolation: pick an action
-  (`create` / `update` / `compose` / `replace`) and a blueprint from the
+  (`create` / `update` / `replace`) and a blueprint from the
   candidate set.
 - **`synthesizeContract(...)`** — cold-path contract synthesizer. Turns an
   agent intent into a `DataContract` (props / context / action / stream
@@ -40,7 +40,7 @@ pnpm add @ggui-ai/negotiator
 import { negotiate } from "@ggui-ai/negotiator";
 
 const result = await negotiate(deps, input);
-// result.action — "create" | "update" | "compose" | "replace"
+// result.action — "create" | "update" | "replace"
 // result.blueprint — the picked blueprint, if any
 ```
 

package/dist/contract-hash.d.ts

@@ -26,7 +26,7 @@ import type { DataContract } from '@ggui-ai/protocol';
  *
  * `intent` is passed separately because `DataContract` itself does
  * not carry an `intent` field — the outer pipeline owns intent
- * (`story.intent` on `ggui_push`, the operator prompt for harness
+ * (`story.intent` on `ggui_render`, the operator prompt for harness
  * benchmarks). Threading intent into the hash keeps cache identity
  * stable across negotiations: different intents produce different
  * generated code (labels, copy, layout) even when the wire surface is
@@ -39,7 +39,7 @@ import type { DataContract } from '@ggui-ai/protocol';
  *
  * @param contract - The data contract from negotiation (unused today)
  * @param intent - The outer pipeline's intent (story.intent on
- *   ggui_push). Empty/falsy values are dropped from the hash input.
+ *   ggui_render). Empty/falsy values are dropped from the hash input.
  * @returns Contract hash prefixed with `ch_` (e.g., `ch_a3f8b2c1e9d04567`)
  */
 export declare function hashContract(_contract: DataContract, intent: string): string;

package/dist/contract-hash.js

@@ -60,7 +60,7 @@ function canonicalize(value) {
  *
  * `intent` is passed separately because `DataContract` itself does
  * not carry an `intent` field — the outer pipeline owns intent
- * (`story.intent` on `ggui_push`, the operator prompt for harness
+ * (`story.intent` on `ggui_render`, the operator prompt for harness
  * benchmarks). Threading intent into the hash keeps cache identity
  * stable across negotiations: different intents produce different
  * generated code (labels, copy, layout) even when the wire surface is
@@ -73,7 +73,7 @@ function canonicalize(value) {
  *
  * @param contract - The data contract from negotiation (unused today)
  * @param intent - The outer pipeline's intent (story.intent on
- *   ggui_push). Empty/falsy values are dropped from the hash input.
+ *   ggui_render). Empty/falsy values are dropped from the hash input.
  * @returns Contract hash prefixed with `ch_` (e.g., `ch_a3f8b2c1e9d04567`)
  */
 export function hashContract(_contract, intent) {

package/dist/decision-input.d.ts

@@ -10,9 +10,12 @@
  * those five fields are the only projection `makeDecision` reads
  * from a `NegotiatorOption`; extracting a named type here would
  * grow public surface for no consumer.
+ *
+ * `renderState` is the decision engine's view of the live render
+ * (at most ONE current render — see {@link RenderState.currentRender}).
  */
 import type { GadgetDescriptor, DataContract } from '@ggui-ai/protocol';
-import type { SessionState } from './session.js';
+import type { RenderState } from './render.js';
 /** Input to the decision engine. */
 export interface NegotiatorDecisionInput {
     agentData?: Record<string, unknown>;
@@ -36,7 +39,7 @@ export interface NegotiatorDecisionInput {
      * partial LLM output with canonical entries from the catalog).
      */
     gadgets?: readonly GadgetDescriptor[];
-    sessionState: SessionState;
+    renderState: RenderState;
     blueprintCandidates: Array<{
         blueprintId: string;
         description: string;

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

@@ -1 +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"}
+{"version":3,"file":"decision-input.d.ts","sourceRoot":"","sources":["../src/decision-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,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,WAAW,EAAE,WAAW,CAAC;IACzB,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

@@ -10,5 +10,8 @@
  * those five fields are the only projection `makeDecision` reads
  * from a `NegotiatorOption`; extracting a named type here would
  * grow public surface for no consumer.
+ *
+ * `renderState` is the decision engine's view of the live render
+ * (at most ONE current render — see {@link RenderState.currentRender}).
  */
 export {};

package/dist/decision.d.ts

@@ -2,11 +2,15 @@
  * 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
+ * opinionated decision: `create` / `update` / `replace`. The LLM
+ * sees the agent's data, the current render (if any), any
  * `blueprintCandidates` from `ragSearch`, and returns a
  * {@link NegotiatorDecision} with a full {@link DataContract} payload.
  *
+ * Decision space is exactly `create | replace | update` — there is
+ * at most ONE current render per scope (flatten-render identity), so
+ * composition collapses into `replace` / `update`.
+ *
  * Contract shape — the returned `contract` always includes an
  * `intent` (semantic identity — same intent = cached component).
  * Other fields are populated opportunistically; `agentCapabilities` is
@@ -44,7 +48,7 @@
 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 const DECISION_SYSTEM_PROMPT = "You are a UI strategist for ggui, a generative UI platform. Given the agent's data, current render state, and blueprint candidates, decide the best way to show this information.\n\nRespond with a JSON object:\n{\n  \"action\": \"create\" | \"update\" | \"replace\",\n  \"reasoning\": \"1-2 sentences explaining why\",\n  \"blueprintId\": \"matched blueprint ID or null\",\n  \"targetRenderId\": \"existing render to update/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\": The current render has the same intent. Update its props in place.\n- \"replace\": The current render does NOT match this intent \u2014 swap it for a different UI.\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<{

package/dist/decision.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;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,4iMAqFiE,CAAC;AAErG,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAqG/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"}

package/dist/decision.js

@@ -2,11 +2,15 @@
  * 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
+ * opinionated decision: `create` / `update` / `replace`. The LLM
+ * sees the agent's data, the current render (if any), any
  * `blueprintCandidates` from `ragSearch`, and returns a
  * {@link NegotiatorDecision} with a full {@link DataContract} payload.
  *
+ * Decision space is exactly `create | replace | update` — there is
+ * at most ONE current render per scope (flatten-render identity), so
+ * composition collapses into `replace` / `update`.
+ *
  * Contract shape — the returned `contract` always includes an
  * `intent` (semantic identity — same intent = cached component).
  * Other fields are populated opportunistically; `agentCapabilities` is
@@ -43,14 +47,14 @@
  */
 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.
+export const DECISION_SYSTEM_PROMPT = `You are a UI strategist for ggui, a generative UI platform. Given the agent's data, current render state, and blueprint candidates, decide the best way to show this information.
 
 Respond with a JSON object:
 {
-  "action": "create" | "update" | "compose" | "replace",
+  "action": "create" | "update" | "replace",
   "reasoning": "1-2 sentences explaining why",
   "blueprintId": "matched blueprint ID or null",
-  "targetStackItemId": "existing page to update/compose/replace, or null",
+  "targetRenderId": "existing render to update/replace, or null",
   "contract": {
     "intent": "Concise purpose — e.g. 'Display current weather conditions for a quick daily check'",
     "propsSpec": {
@@ -84,9 +88,8 @@ INTENT RULES (most important):
 
 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.
+- "update": The current render has the same intent. Update its props in place.
+- "replace": The current render does NOT match this intent — swap it for a different UI.
 
 REUSE BIAS (critical for performance):
 - Reusing a blueprint = INSTANT render (cached code, <1 second).
@@ -145,19 +148,17 @@ export function buildDecisionUserMessage(input) {
             : 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}`);
+    // Render state
+    const { renderState } = input;
+    const current = renderState.currentRender;
+    if (current) {
+        parts.push(`Current render: [${current.id}] ${current.prompt ?? 'no prompt'}`);
     }
     else {
-        parts.push('Current UI stack: empty');
+        parts.push('Current render: none (cold start)');
     }
-    if (sessionState.conversationHistory.length > 0) {
-        const recent = sessionState.conversationHistory.slice(-5);
+    if (renderState.conversationHistory.length > 0) {
+        const recent = renderState.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.
@@ -236,8 +237,8 @@ const DECISION_TOOL = {
         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)',
+                enum: ['create', 'update', 'replace'],
+                description: 'What to do: create (new UI when nothing on screen), update (swap data on the current render), replace (swap the current render for a different UI)',
             },
             reasoning: { type: 'string', description: 'Brief explanation' },
             blueprintId: {
@@ -297,9 +298,9 @@ const DECISION_TOOL = {
                 },
                 required: ['intent'],
             },
-            targetStackItemId: {
+            targetRenderId: {
                 type: 'string',
-                description: 'Page to target (update/replace actions)',
+                description: 'Render to target (update/replace actions)',
             },
             adaptations: {
                 type: 'object',
@@ -327,7 +328,7 @@ export async function makeDecision(input, llmCaller) {
                     reasoning: parsed.reasoning ?? 'Structured output',
                     blueprintId: parsed.blueprintId ?? undefined,
                     contract: mergeGadgets(mergeAgentCapabilities({ ...parsed.contract }, input.agentTools), input.gadgets),
-                    targetStackItemId: parsed.targetStackItemId ?? undefined,
+                    targetRenderId: parsed.targetRenderId ?? undefined,
                     adaptations: parsed.adaptations ?? undefined,
                 },
                 alternatives: [],
@@ -351,7 +352,7 @@ export async function makeDecision(input, llmCaller) {
                 reasoning: parsed.reasoning ?? 'No reasoning provided',
                 blueprintId: parsed.blueprintId ?? undefined,
                 contract: mergeGadgets(mergeAgentCapabilities({ ...parsed.contract }, input.agentTools), input.gadgets),
-                targetStackItemId: parsed.targetStackItemId ?? undefined,
+                targetRenderId: parsed.targetRenderId ?? undefined,
                 adaptations: parsed.adaptations ?? undefined,
             },
             alternatives: [],

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * @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.
+ * Decides which UI to render (create/update/replace) given agent
+ * signal (data/prompt/context/agentTools) and current render state.
  *
  * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
  * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
@@ -22,7 +22,7 @@ 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 { RenderState, RenderEntry } from './render.js';
 export type { NegotiatorDecisionInput } from './decision-input.js';
 export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
 export { negotiate } from './negotiate.js';

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,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

@@ -1,8 +1,8 @@
 /**
  * @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.
+ * Decides which UI to render (create/update/replace) given agent
+ * signal (data/prompt/context/agentTools) and current render state.
  *
  * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
  * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision

package/dist/intent.d.ts

@@ -2,18 +2,18 @@
  * 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.
+ * within a render scope — 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 renderId   Scope. Intent ids are render-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;
+export declare function computeIntentId(renderId: string, data: Record<string, unknown> | undefined, action?: string): string;
 /**
- * True if the given intent id is already being handled in this session.
+ * True if the given intent id is already being handled in this scope.
  *
  * The suggestion engine uses this to avoid re-suggesting the same UI
  * while the agent is already preparing one.

package/dist/intent.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,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

@@ -3,22 +3,22 @@ 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.
+ * within a render scope — 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 renderId   Scope. Intent ids are render-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) {
+export function computeIntentId(renderId, data, action) {
     const dataShape = data ? Object.keys(data).sort().join(',') : 'no-data';
-    const raw = `${sessionId}:${dataShape}:${action ?? 'create'}`;
+    const raw = `${renderId}:${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.
+ * True if the given intent id is already being handled in this scope.
  *
  * The suggestion engine uses this to avoid re-suggesting the same UI
  * while the agent is already preparing one.

package/dist/negotiate.d.ts

@@ -6,10 +6,10 @@
  *   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).
+ *   2. Read render 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
+ *      current render; fold the picked blueprint's pool provenance into
  *      the return value.
  *
  * Timing logs (stable format — consumed by benchmarks):
@@ -23,7 +23,7 @@
  * Exported:
  *   - `negotiate(deps, input)` — runtime orchestrator.
  *   - `NegotiateDeps` — injection shape (embedding / vectors / llm +
- *     optional session-state reader + optional progress callback).
+ *     optional render-state reader + optional progress callback).
  *   - `NegotiateInput` — agent signal + config.
  *   - `NegotiateConfig` — minimum fields the orchestrator actually
  *     reads. Pool selection is expressed as `includeSharedPool:
@@ -43,19 +43,19 @@
 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';
+import type { RenderState } from './render.js';
 /**
  * Minimum config the orchestrator reads.
  *
  * `appId` is the primary RAG scope (per-app registered UIs live
- * here). `sessionId` keys the optional `readSessionState` callback.
+ * here). `renderId` keys the optional `readRenderState` 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;
+    renderId: string;
     /** Also search the shared (global) pool in parallel. Default `false`. */
     includeSharedPool?: boolean;
 }
@@ -112,8 +112,8 @@ export interface NegotiateDeps {
     embedding?: EmbeddingProvider;
     vectors?: VectorStore;
     llm: LLMCaller;
-    /** Optional: read current session state for stack-aware decisions. */
-    readSessionState?: (sessionId: string) => Promise<SessionState | null>;
+    /** Optional: read current render state for reuse-aware decisions. */
+    readRenderState?: (renderId: string) => Promise<RenderState | null>;
     /** Optional: surface pipeline progress to consumers. */
     onProgress?: (phase: string, summary: string) => void;
 }
@@ -134,8 +134,9 @@ export interface NegotiateResult {
     decisionLatencyMs: number;
 }
 /**
- * Orchestrate one negotiation call — RAG search, session read, fast
- * path, decision LLM. See module docstring for the pipeline outline.
+ * Orchestrate one negotiation call — RAG search, render-state 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

@@ -1 +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"}
+{"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,WAAW,EAAE,MAAM,aAAa,CAAC;AAU/C;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,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,qEAAqE;IACrE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACpE,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;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAqJ1B"}

package/dist/negotiate.js

@@ -6,10 +6,10 @@
  *   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).
+ *   2. Read render 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
+ *      current render; fold the picked blueprint's pool provenance into
  *      the return value.
  *
  * Timing logs (stable format — consumed by benchmarks):
@@ -23,7 +23,7 @@
  * Exported:
  *   - `negotiate(deps, input)` — runtime orchestrator.
  *   - `NegotiateDeps` — injection shape (embedding / vectors / llm +
- *     optional session-state reader + optional progress callback).
+ *     optional render-state reader + optional progress callback).
  *   - `NegotiateInput` — agent signal + config.
  *   - `NegotiateConfig` — minimum fields the orchestrator actually
  *     reads. Pool selection is expressed as `includeSharedPool:
@@ -42,14 +42,14 @@
  */
 import { ragSearch } from './rag-search.js';
 import { makeDecision } from './decision.js';
-/** Empty session state for cold starts and benchmarks. */
-const EMPTY_SESSION = {
-    stack: [],
+/** Empty render state for cold starts and benchmarks. */
+const EMPTY_RENDER_STATE = {
     conversationHistory: [],
 };
 /**
- * Orchestrate one negotiation call — RAG search, session read, fast
- * path, decision LLM. See module docstring for the pipeline outline.
+ * Orchestrate one negotiation call — RAG search, render-state read,
+ * fast path, decision LLM. See module docstring for the pipeline
+ * outline.
  */
 export async function negotiate(deps, input) {
     const { agent, config } = input;
@@ -88,15 +88,17 @@ export async function negotiate(deps, input) {
     deps.onProgress?.('blueprint_search', ragResult.options.length > 0
         ? `Found ${ragResult.options.length} blueprint candidate${ragResult.options.length > 1 ? 's' : ''}`
         : 'No blueprints found');
-    // Step 2: Read session state (falls back to EMPTY_SESSION).
-    const sessionState = deps.readSessionState
-        ? ((await deps.readSessionState(config.sessionId)) ?? EMPTY_SESSION)
-        : EMPTY_SESSION;
+    // Step 2: Read render state (falls back to EMPTY_RENDER_STATE).
+    const renderState = deps.readRenderState
+        ? ((await deps.readRenderState(config.renderId)) ?? EMPTY_RENDER_STATE)
+        : EMPTY_RENDER_STATE;
     // Step 3: Fast-path for high-confidence exact matches — skip decision LLM.
     const exactOpt = ragResult.options.find((opt) => opt.description.includes('exact'));
     if (exactOpt) {
-        const stackHasSameType = sessionState.stack.some((item) => item.prompt && agent.prompt && item.prompt === agent.prompt);
-        const action = stackHasSameType ? 'update' : 'create';
+        const currentMatches = Boolean(renderState.currentRender?.prompt &&
+            agent.prompt &&
+            renderState.currentRender.prompt === agent.prompt);
+        const action = currentMatches ? 'update' : 'create';
         const totalMs = Date.now() - negotiateStart;
         // eslint-disable-next-line no-console
         console.log(`[negotiate] FAST PATH: blueprint=${exactOpt.blueprintId?.slice(-8)} hash=${exactOpt.contractHash?.slice(0, 12) ?? 'none'} | LLM decision: 0ms | total: ${totalMs}ms`);
@@ -130,7 +132,7 @@ export async function negotiate(deps, input) {
         ...(agent.gadgets
             ? { gadgets: agent.gadgets }
             : {}),
-        sessionState,
+        renderState,
         blueprintCandidates: ragResult.options.map((opt) => ({
             blueprintId: opt.blueprintId ?? opt.id,
             description: opt.description,

package/dist/render.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `RenderState` — what the decision engine sees about the live
+ * render at the moment of a negotiation call.
+ *
+ * Captures the current render (if any), recent conversation, and
+ * optional interface context (viewport, device class). Consumed by
+ * `NegotiatorDecisionInput` to drive `create / update / replace`
+ * decisions — the current render tells the engine whether the
+ * already-on-screen UI can absorb this push as an `update`, and the
+ * conversation history feeds the decision LLM.
+ *
+ * The decision space is `create | replace | update`: there is at
+ * most ONE current render per negotiation call (flatten-render
+ * identity has no multi-entry stack), and `currentRender` captures
+ * that single live render when present.
+ *
+ * Kept in `@ggui-ai/negotiator` (not `mcp-server-core`): this is
+ * the decision engine's input shape, not a storage seam. An MCP
+ * server implementer binding against the public `Negotiator`
+ * interface sees `NegotiatorInput` / `NegotiatorResult` — never
+ * this internal input shape. Community adapters that want to
+ * call `makeDecision` directly (bypassing the `Negotiator` wrapper)
+ * import this type.
+ */
+import type { DataContract, InterfaceContext } from '@ggui-ai/protocol';
+/**
+ * One entry describing the render currently on screen — minimal
+ * shape: every field the decision engine actually reads to decide
+ * reuse vs. create.
+ *
+ * Mirrors the protocol's `ComponentRender` projection but stays
+ * intentionally narrower — the engine only consumes identity,
+ * authoring prompt, contract, and component code.
+ */
+export interface RenderEntry {
+    id: string;
+    prompt?: string;
+    contract?: DataContract;
+    componentCode: string;
+}
+/**
+ * Current state of the active render — at most ONE current render
+ * plus conversation history.
+ */
+export interface RenderState {
+    /**
+     * The render currently on screen for this scope, when any. Absent
+     * ⇒ no live render exists (cold start or post-clear).
+     */
+    currentRender?: RenderEntry;
+    conversationHistory: Array<{
+        role: 'user' | 'agent';
+        content: string;
+    }>;
+    interfaceContext?: InterfaceContext;
+}
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAExE;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,mBAAmB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC"}