@ggui-ai/negotiator 0.1.0-rc.1

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Negotiator types — open RAG-result projection shape.
+ *
+ * `NegotiatorOption` is the projected result shape `ragSearch`
+ * returns: one entry per candidate blueprint, with the contract
+ * + pro/con reasoning + pool provenance. The V3 decision engine
+ * reads these to populate `NegotiatorDecisionInput.blueprintCandidates`.
+ *
+ * `DataContract` is imported from `@ggui-ai/protocol` (already
+ * public). Do NOT re-export it — callers should import contract
+ * types from the protocol package directly.
+ */
+import type { DataContract } from '@ggui-ai/protocol';
+/** RAG-projected blueprint option surfaced to the decision engine. */
+export interface NegotiatorOption {
+    id: string;
+    type: 'brainstorm' | 'blueprint';
+    pattern?: string;
+    blueprintId?: string;
+    description: string;
+    pros: string[];
+    cons: string[];
+    renderTime: 'instant' | 'standard';
+    contract: DataContract;
+    /** Stored contract hash from embedding index — deterministic pool key. */
+    contractHash?: string;
+    /** Which pool this blueprint's code lives in. */
+    poolSource?: 'shared' | 'private';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,GAAG,WAAW,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,SAAS,GAAG,UAAU,CAAC;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Negotiator types — open RAG-result projection shape.
+ *
+ * `NegotiatorOption` is the projected result shape `ragSearch`
+ * returns: one entry per candidate blueprint, with the contract
+ * + pro/con reasoning + pool provenance. The V3 decision engine
+ * reads these to populate `NegotiatorDecisionInput.blueprintCandidates`.
+ *
+ * `DataContract` is imported from `@ggui-ai/protocol` (already
+ * public). Do NOT re-export it — callers should import contract
+ * types from the protocol package directly.
+ */
+export {};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@ggui-ai/negotiator",
+  "version": "0.1.0-rc.1",
+  "description": "UI decision engine for ggui. Given an agent's signal and the current session state, decides which UI to render (create / update / compose / replace) and synthesizes the data contract. Deployment-agnostic: concrete embedding and vector-store bindings plug in via the storage interfaces from @ggui-ai/mcp-server-core.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ggui",
+    "mcp",
+    "generative-ui",
+    "ai-agents",
+    "decision-engine"
+  ],
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/negotiator",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/negotiator"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "src",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.test-d.ts",
+    "!**/*.test-d.tsx",
+    "!**/*.test.js",
+    "!**/*.test.d.ts",
+    "!**/*.test.d.ts.map",
+    "!**/*.test.js.map",
+    "!**/*.test-d.js",
+    "!**/*.test-d.d.ts",
+    "!**/__tests__/**",
+    "!**/*.spec.ts",
+    "!**/*.spec.tsx"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ggui-ai/mcp-server-core": "0.1.0-rc.1",
+    "@ggui-ai/protocol": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "probe-rerank": "tsx src/rerank-eval/run-probe-cli.ts",
+    "bench-synth": "tsx src/synth-bench/run-bench-cli.ts"
+  }
+}

package/src/contract-hash.ts

@@ -0,0 +1,102 @@
+/**
+ * Contract Hashing — deterministic cache key from data contract.
+ *
+ * Uses RFC 8785 (JSON Canonicalization Scheme) for deterministic
+ * serialization, then SHA-256 for the hash.
+ *
+ * What's in the hash: intent only (the semantic identity).
+ * What's NOT in the hash: props, actions, stream (including per-channel source), adaptations.
+ *
+ * Why intent-only: The LLM generates slightly different prop descriptions
+ * each call, but the INTENT is deterministic (provided by the agent or
+ * generated once). Same intent = same component = same cached code.
+ * Props are passed at render time, not baked into the component.
+ *
+ * The `interaction` field was removed from `DataContract` in pre-launch
+ * cleanup (the four-spec surface — props/action/context/stream —
+ * describes the wire exhaustively); this function used to factor it in
+ * but no longer does. Old goldens were rotated when the field went away.
+ */
+
+import { createHash } from 'node:crypto';
+import type { DataContract } from '@ggui-ai/protocol';
+
+/**
+ * RFC 8785 JSON Canonicalization Scheme.
+ *
+ * Produces deterministic JSON by:
+ * - Sorting object keys lexicographically (recursive)
+ * - Normalizing numbers (no trailing zeros, no +0)
+ * - Removing undefined values
+ * - No whitespace
+ */
+function canonicalize(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') {
+    if (!isFinite(value)) return 'null';
+    return Object.is(value, -0) ? '0' : String(value);
+  }
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => canonicalize(v)).join(',') + ']';
+  }
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj)
+      .filter((k) => obj[k] !== undefined)
+      .sort();
+    const entries = keys.map((k) => JSON.stringify(k) + ':' + canonicalize(obj[k]));
+    return '{' + entries.join(',') + '}';
+  }
+  return 'null';
+}
+
+/**
+ * Hash a data contract to a deterministic cache key.
+ *
+ * Hashes intent only — the semantic identity of the UI. Props,
+ * actions, stream specs are for code generation, not caching.
+ *
+ * `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
+ * 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
+ * identical.
+ *
+ * The `contract` argument is retained on the signature for forward
+ * compatibility — future cache-key fields (e.g., a structural
+ * fingerprint of the four specs) can be folded in without breaking
+ * call sites — but is not consulted by the current implementation.
+ *
+ * @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.
+ * @returns Contract hash prefixed with `ch_` (e.g., `ch_a3f8b2c1e9d04567`)
+ */
+export function hashContract(
+  _contract: DataContract,
+  intent: string,
+): string {
+  const input: Record<string, unknown> = {};
+  if (intent) input.intent = intent;
+  const canonical = canonicalize(input);
+  const hash = createHash('sha256').update(canonical).digest('hex');
+  return `ch_${hash.slice(0, 16)}`;
+}
+
+/**
+ * Build a variant key from shell type and device category.
+ *
+ * @param shellType - Shell type (default: 'universal')
+ * @param deviceCategory - Device category (default: 'universal')
+ * @returns Variant string (e.g., 'fullscreen:mobile', 'universal:universal')
+ */
+export function buildVariant(
+  shellType = 'universal',
+  deviceCategory = 'universal',
+): string {
+  return `${shellType}:${deviceCategory}`;
+}