@ggui-ai/negotiator 0.1.0-rc.1

package/dist/synthesize-contract.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Contract synthesis.
+ *
+ * When an agent calls `ggui_handshake({story: {intent}})` without
+ * authoring a `contract`, the negotiator's cold path used to stamp an
+ * empty stub on `plan.contract`. The stub survived the handshake →
+ * push hop but failed downstream: the generator emitted
+ * `useAction(...)` / `useGguiContext(...)` calls that didn't match
+ * any declared `actionSpec` / `contextSpec`, and the validator
+ * stripped them, leaving dead buttons on the rendered UI.
+ *
+ * `synthesizeContract` closes that gap. Given an LLM caller and an
+ * intent string, it asks the model to infer a plausible
+ * `DataContract` from the natural-language ask: which actions a user
+ * might fire, which context slots the agent would observe, which
+ * stream channels would carry live updates. The resulting contract
+ * feeds the negotiator's `plan.contract`, rides through to the
+ * paired push, and arrives at the generator with a real wire surface
+ * that the validator accepts.
+ *
+ * **Conservative by design.** The synthesized contract emits only
+ * what the LLM is confident about — better to under-declare than to
+ * fabricate actions the UI doesn't actually need. Operators who want
+ * a richer surface should author the contract themselves on the
+ * handshake input; synthesis is a fallback, not a replacement.
+ *
+ * **Failure modes collapse to null.** LLM throws, parse fails,
+ * provider doesn't support `callStructured` → return `null`. Caller
+ * falls back to an empty stub; behavior regresses to pre-synth but
+ * doesn't crash.
+ *
+ * **Cost.** ~$0.0005-0.001 per call (Haiku 4.5, ~500 input + ~300
+ * output tokens). Latency ~1.5s. Fires only on cold-path Tier 3
+ * AND when the agent omitted the contract — most pushes from
+ * contract-aware agents skip synthesis entirely.
+ */
+import { type DataContract, type GadgetDescriptor } from '@ggui-ai/protocol';
+import type { LLMCaller, ToolSchema } from './llm-caller.js';
+import { type ContractValidationFinding } from './contract-validators.js';
+/** Result of one synthesis attempt. */
+export interface SynthesizeContractResult {
+    /** Synthesized contract, or `null` when synthesis declined / failed. */
+    readonly contract: DataContract | null;
+    /** Human-readable reason for the synthesis decision. */
+    readonly reason: string;
+    /** Wall-clock latency across every attempt. */
+    readonly latencyMs: number;
+    /**
+     * Number of LLM attempts the synthesizer made — `1` on the common
+     * already-valid path, up to {@link MAX_SYNTH_ATTEMPTS} when the
+     * validate-and-repair loop had to retry. `0` for the early-skip
+     * paths (empty intent, provider lacks structured output).
+     */
+    readonly attempts: number;
+    /**
+     * Structural-validator findings produced when the synthesizer ran the
+     * `validateContractStructure` gate against its assembled contract.
+     * Empty when validator didn't run (early skip / decline). Surfaced
+     * so callers (cache-trace emit site, ops dashboards) can render
+     * findings without re-running the detector.
+     */
+    readonly findings: readonly ContractValidationFinding[];
+}
+/**
+ * Tool schema the synthesizer's structured-output call uses. The
+ * shape mirrors `DataContract` but stays loose at the ToolSchema
+ * layer — Anthropic's tool-use adapter doesn't enforce nested
+ * required-field rules deeply, and we re-validate on the return path.
+ */
+export declare const SYNTHESIZE_TOOL: ToolSchema;
+/**
+ * Run the synthesizer for a contract-less cold-path handshake.
+ *
+ * Empty / whitespace intent short-circuits to null with a reason —
+ * no contract can be inferred from nothing.
+ *
+ * Provider lacking `callStructured` (test stubs, providers without
+ * tool-use) collapses to null.
+ *
+ * Each attempt is self-checked against the validation gate; a failure
+ * feeds the precise error back for up to {@link MAX_SYNTH_ATTEMPTS}
+ * attempts (a transient `callStructured` throw re-runs the same
+ * prompt). Only when the budget is exhausted does it collapse to null
+ * — the caller then falls back to an empty contract stub.
+ */
+export declare function synthesizeContract(deps: {
+    readonly llm: LLMCaller;
+}, intent: string, options?: {
+    /**
+     * Per-app gadget catalog (`App.gadgets`) — when bound, synth
+     * emits an "AVAILABLE GADGETS" section on the user prompt (NOT
+     * the system prompt, so the system-prompt cache stays warm)
+     * listing each registered package's exports — hook AND component
+     * — with description + usage. The LLM uses this to decide which
+     * (if any) `clientCapabilities.gadgets[<package>][<export>]`
+     * entries to declare on the synthesized contract. Per-export
+     * budget ~300 chars; total budget ~3 KB.
+     *
+     * When omitted, synth still uses the static stdlib hint baked
+     * into SYNTHESIZE_SYSTEM_PROMPT (preserves behavior on the OSS
+     * no-app-registry path).
+     */
+    readonly appGadgets?: readonly GadgetDescriptor[];
+}): Promise<SynthesizeContractResult>;
+/**
+ * Compose the "AVAILABLE GADGETS" section appended to synth's user
+ * prompt (and the decision-engine user message — both paths share
+ * this one composer). Flattens the package-keyed
+ * {@link GadgetDescriptor} catalog into one line per export:
+ *
+ *     - hook `useGeolocation` (package `@ggui-ai/gadgets`) — <desc> (usage: <usage>)
+ *     - component `Chart` (package `@acme/charts`) — <desc> (usage: <usage>)
+ *
+ * The leading `hook` / `component` tag teaches the LLM the two render
+ * idioms (a hook is CALLED, a component is RENDERED as JSX); the
+ * `(package …)` tag carries the npm package name the LLM needs to
+ * author the package-keyed
+ * `clientCapabilities.gadgets[<package>][<export>]` wire entry.
+ *
+ * Budget enforcement: per-export text capped at
+ * {@link SYNTH_PER_LIBRARY_BUDGET}, total section capped at
+ * {@link SYNTH_TOTAL_BUDGET}.
+ *
+ * Returns `undefined` when the catalog is empty / every export lacks
+ * teaching text — the caller then omits the section entirely
+ * (preserves the no-registry prompt verbatim for cache hit).
+ *
+ * Pure helper; exported for the prompt-builder unit test.
+ */
+export declare function composeAvailableGadgetsSection(gadgets: readonly GadgetDescriptor[] | undefined): string | undefined;
+//# sourceMappingURL=synthesize-contract.d.ts.map

package/dist/synthesize-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-contract.d.ts","sourceRoot":"","sources":["../src/synthesize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAsBlC,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AA+ND;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UA+I7B,CAAC;AAsGF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD,GACA,OAAO,CAAC,wBAAwB,CAAC,CAiKnC;AAgUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,GAC/C,MAAM,GAAG,SAAS,CA+CpB"}