@ggui-ai/protocol 0.1.0-rc.1

package/dist/recommended-prompts.js

@@ -0,0 +1,55 @@
+/**
+ * Recommended agent-side system prompts for hosts running ggui.
+ *
+ * The wire protocol already carries its own self-teaching surfaces:
+ *
+ *   - Per-tool `description` strings on every `ggui_*` MCP tool.
+ *   - The server's `InitializeResult.instructions` field (set via
+ *     `@ggui-ai/mcp-server`'s `MCP_INSTRUCTIONS_PRESETS`).
+ *
+ * Those two carry the wire flow (new_session → handshake → push →
+ * consume → react), the contract-authoring rules, recovery shapes,
+ * and the mutation rule. **Agent builders should NOT replicate any
+ * of that in their system prompt.** The protocol is designed to be
+ * self-teaching from the host's side.
+ *
+ * What an agent-side system prompt SHOULD do: set the agent's role
+ * and posture — "you render UIs, you don't reply in plain text" —
+ * so the model reaches for ggui_* tools instead of conversational
+ * responses. That's a *posture cue*, not a procedural script.
+ *
+ * On hosts like claude.ai, the host's own baseline system prompt
+ * already nudges tool usage, so a one-line user instruction
+ * ("Always respond using ggui_* tools") is enough. On raw SDK hosts
+ * (Claude Agent SDK, OpenAI Assistants, etc.) that baseline is
+ * absent, so the recommended prompt below carries slightly more
+ * role context to compensate.
+ *
+ * If an agent isn't following the wire flow correctly even with
+ * this prompt, the bug lives in the protocol's tool descriptions
+ * or server instructions — fix THOSE, not this string.
+ */
+/**
+ * The recommended one-line system prompt for ggui-aware agents.
+ *
+ * Posture-setting only. Carries no procedural detail — the wire flow
+ * is taught by the server's `InitializeResult.instructions` and
+ * per-tool `description` strings.
+ *
+ * @example
+ * ```ts
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ * import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol/recommended-prompts';
+ *
+ * query({
+ *   prompt: userInput,
+ *   options: {
+ *     systemPrompt: GGUI_AGENT_SYSTEM_PROMPT,
+ *     mcpServers: { ggui: { type: 'http', url: 'http://localhost:6781/mcp' } },
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export const GGUI_AGENT_SYSTEM_PROMPT = 'You are a UI agent. Respond to every user request by rendering an interactive UI via the ggui_* MCP tools instead of by replying in plain text. The tool descriptions and server instructions explain the wire flow — follow them.';

package/dist/registry/blueprint-key.d.ts

@@ -0,0 +1,9 @@
+import type { DataContract } from '../types/data-contract.js';
+/**
+ * Compute the canonical 16-char identity hash for a contract shape.
+ *
+ * Pure function, no I/O. Deterministic across runs / processes /
+ * Node versions (sha256 + utf-8 encoding are well-specified).
+ */
+export declare function blueprintKey(contract: DataContract | undefined): string;
+//# sourceMappingURL=blueprint-key.d.ts.map

package/dist/registry/blueprint-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blueprint-key.d.ts","sourceRoot":"","sources":["../../src/registry/blueprint-key.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAGvE"}

package/dist/registry/blueprint-key.js

@@ -0,0 +1,28 @@
+/**
+ * Deterministic identity hash for a `DataContract` shape.
+ *
+ * `blueprintKey(contract)` is the Tier 1 exact-match key in the
+ * blueprint registry: two contract that canonicalize to the same
+ * string produce the same key, regardless of how the agent
+ * paraphrased the surrounding intent. Equal key → guaranteed
+ * registry lookup hit (no LLM rerank, no embedding similarity).
+ *
+ * 16-character sha256 prefix — matches the existing `blueprintHash`
+ * shape in `cache-trace-sink` and `generation-cache.ts`. Collision
+ * probability for 100s-of-thousands of distinct contract is ~10^-6
+ * (birthday-bound on 2^64), well below the budget for the OSS
+ * single-tenant scope. Hosted multi-tenant deployments scope keys
+ * by appId so the bound is per-tenant, never global.
+ */
+import { createHash } from 'node:crypto';
+import { canonicalizeContracts } from './canonicalize-contract.js';
+/**
+ * Compute the canonical 16-char identity hash for a contract shape.
+ *
+ * Pure function, no I/O. Deterministic across runs / processes /
+ * Node versions (sha256 + utf-8 encoding are well-specified).
+ */
+export function blueprintKey(contract) {
+    const canonical = canonicalizeContracts(contract);
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}

package/dist/registry/canonicalize-contract.d.ts

@@ -0,0 +1,35 @@
+import type { DataContract } from '../types/data-contract.js';
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Walk `value` recursively and produce a structurally-equivalent
+ * tree with stripped keys removed and all strings NFC-normalized.
+ * Arrays preserved in order; primitives unchanged except for Unicode
+ * normalization on strings; `undefined` collapses to absent (mirrors
+ * JSON behavior). Object key sorting + JSON serialization happen in
+ * the downstream JCS pass — this function handles the domain-specific
+ * strip step PLUS Unicode normalization (RFC 8785 leaves NFC out of
+ * scope; we apply it ourselves so visually-identical contracts hash
+ * identically regardless of the agent's keyboard / IME composition).
+ *
+ * Exported for tests / debugging — production callers should use
+ * `canonicalizeContracts()`.
+ */
+export declare function canonicalizeValue(value: unknown): JsonValue | undefined;
+/**
+ * Produce the canonical bytes for a `DataContract` value, suitable
+ * for hashing or external content-address lookups. Stable across
+ * paraphrase, key order, whitespace, and description-only edits.
+ *
+ * Empty / undefined / `{}` all collapse to the same canonical bytes,
+ * which produces a stable `blueprintKey` for the "no-contract" case.
+ * That key isn't used for cache lookups (registry refuses to register
+ * contract-less pushes) but stays well-defined for completeness.
+ *
+ * The output is a UTF-8-encoded JSON string per RFC 8785. External
+ * implementations using any JCS library produce the same bytes.
+ */
+export declare function canonicalizeContracts(contract: DataContract | undefined): string;
+export {};
+//# sourceMappingURL=canonicalize-contract.d.ts.map

package/dist/registry/canonicalize-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize-contract.d.ts","sourceRoot":"","sources":["../../src/registry/canonicalize-contract.ts"],"names":[],"mappings":"AAyEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAW9D,KAAK,SAAS,GACV,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CA4CvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAOhF"}

package/dist/registry/canonicalize-contract.js

@@ -0,0 +1,166 @@
+/**
+ * Canonical, deterministic serialization of `DataContract` per
+ * RFC 8785 (JSON Canonicalization Scheme — JCS).
+ *
+ * Goal: two contracts with the same WIRE-OBSERVABLE shape produce
+ * the same canonical bytes, regardless of key order, whitespace, or
+ * description-only differences. The canonical string is the input to
+ * `blueprintKey()`; equal canonical strings → equal cache key →
+ * exact-match hit at handshake time.
+ *
+ * # Why RFC 8785
+ *
+ * JCS is the IETF standard for deterministic JSON serialization
+ * (published 2020). External implementers can compute the same hash
+ * we do using any JCS library (`canonicalize` on npm, `gocanon` in
+ * Go, `pyjcs` in Python, `serde_jcs` in Rust). That makes the
+ * `contractHash` field a portable identity claim — agents can verify
+ * a hash off-server without knowing our internal format.
+ *
+ * # Pipeline
+ *
+ *   stripDescriptions(contract)        ← domain rule, OURS
+ *     ↓
+ *   canonicalize(value)                ← RFC 8785, vendored library
+ *     ↓
+ *   utf-8 bytes, then sha256 + 16-char hex prefix (in `blueprint-key.ts`)
+ *
+ * # Domain rule: informational prose is stripped
+ *
+ * `description` and `usage` are informational only — they don't alter
+ * the wire surface (no React.Context is mounted from a description,
+ * no action gets routed by a usage hint). Stripping them means a
+ * documentation tweak doesn't invalidate a registered blueprint, and
+ * an agent's intent-prose override on a gadget export-use entry (the
+ * `description?` / `usage?` fields of each
+ * `clientCapabilities.gadgets[<package>][<exportName>]`, agent-authored
+ * at push time) does not pollute the cache key.
+ *
+ * The strip is keyed on `description`/`usage` as STRING-VALUED fields,
+ * never as map keys. A gadget package, an `agentCapabilities.tools`
+ * entry, or a spec slot may legitimately be NAMED `usage` (npm package
+ * names allow it) — that key maps to an object and MUST survive, or two
+ * distinct contracts collide onto one blueprint cache key and the wrong
+ * cached UI is served. Informational prose is always a string; a data
+ * map key named `usage`/`description` always maps to an object/array —
+ * so the value-type test cleanly separates the two. If QA later shows
+ * the prose affects LLM-generated copy enough to be load-bearing, flip
+ * `STRIPPED_KEYS`.
+ *
+ * # Preserved (load-bearing for behavior)
+ *
+ *   - The four typed specs: `propsSpec`, `actionSpec`, `contextSpec`,
+ *     `streamSpec` (including `streamSpec[*].source.tool` cross-refs).
+ *   - The two catalogs: `agentCapabilities.tools[*]` (key names + their
+ *     `inputSchema`/`outputSchema`) and `clientCapabilities.gadgets`
+ *     (package-keyed — npm package names as outer keys, export names as
+ *     the inner `exports` map keys; no `version`, no transport metadata
+ *     on the wire).
+ *   - Inner JSON Schema fields under every `schema:` wrapper (`type`,
+ *     `enum`, `properties`, `required`, `items`, `additionalProperties`,
+ *     `nullable`, `format`, …).
+ *   - `default` values, `required` flags, `nextStep` hints (cross-ref
+ *     identity), `confirm` / `icon` / `label` / `mode` / `replay` on
+ *     their respective spec entries.
+ *   - `enum` array order — order matters for select UIs; JCS preserves
+ *     array order so we don't pre-sort.
+ *   - Slot / action / stream channel / agent-capability tool names,
+ *     plus gadget package keys and per-package export names (every key
+ *     in the four specs + two catalogs).
+ *
+ * Pure function — no I/O, no globals.
+ */
+import canonicalize from 'canonicalize';
+/**
+ * Informational-prose field names removed from the canonical form —
+ * but ONLY where they are string-valued (see `canonicalizeValue`); a
+ * same-named map key is data and is preserved. Stripping happens
+ * BEFORE JCS — JCS itself has no concept of "ignorable fields"; that's
+ * the protocol's domain rule, not the serialization standard's.
+ */
+const STRIPPED_KEYS = new Set(['description', 'usage']);
+/**
+ * Walk `value` recursively and produce a structurally-equivalent
+ * tree with stripped keys removed and all strings NFC-normalized.
+ * Arrays preserved in order; primitives unchanged except for Unicode
+ * normalization on strings; `undefined` collapses to absent (mirrors
+ * JSON behavior). Object key sorting + JSON serialization happen in
+ * the downstream JCS pass — this function handles the domain-specific
+ * strip step PLUS Unicode normalization (RFC 8785 leaves NFC out of
+ * scope; we apply it ourselves so visually-identical contracts hash
+ * identically regardless of the agent's keyboard / IME composition).
+ *
+ * Exported for tests / debugging — production callers should use
+ * `canonicalizeContracts()`.
+ */
+export function canonicalizeValue(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === 'string')
+        return value.normalize('NFC');
+    if (t === 'number' || t === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const item of value) {
+            const c = canonicalizeValue(item);
+            if (c !== undefined)
+                out.push(c);
+        }
+        return out;
+    }
+    if (t === 'object') {
+        const obj = value;
+        // NFC-normalize keys before sort so two contracts with the same
+        // key in different normalization forms (precomposed "café" vs
+        // decomposed "café") collapse to one identity. Keep the original
+        // key for lookup; emit the normalized key in output. Keys sorted
+        // alphabetically here too — idempotent with the downstream JCS
+        // pass, but keeps the intermediate-form output predictable for
+        // tests/debugging that consume `canonicalizeValue` directly.
+        const entries = Object.keys(obj)
+            // Strip `description`/`usage` ONLY when string-valued — i.e. only
+            // where they are informational prose fields. A key that IS
+            // literally `description`/`usage` as a MAP key (a gadget package,
+            // an `agentCapabilities.tools` entry, a spec slot) maps to an
+            // object/array and MUST survive: stripping it collapses distinct
+            // contracts onto one blueprint cache key.
+            .filter((k) => !(STRIPPED_KEYS.has(k) && typeof obj[k] === 'string'))
+            .map((k) => ({ source: k, normalized: k.normalize('NFC') }))
+            .sort((a, b) => (a.normalized < b.normalized ? -1 : a.normalized > b.normalized ? 1 : 0));
+        const out = {};
+        for (const { source, normalized } of entries) {
+            const c = canonicalizeValue(obj[source]);
+            if (c !== undefined)
+                out[normalized] = c;
+        }
+        return out;
+    }
+    // Functions, symbols, bigint — not JSON-serializable; treat as absent.
+    return undefined;
+}
+/**
+ * Produce the canonical bytes for a `DataContract` value, suitable
+ * for hashing or external content-address lookups. Stable across
+ * paraphrase, key order, whitespace, and description-only edits.
+ *
+ * Empty / undefined / `{}` all collapse to the same canonical bytes,
+ * which produces a stable `blueprintKey` for the "no-contract" case.
+ * That key isn't used for cache lookups (registry refuses to register
+ * contract-less pushes) but stays well-defined for completeness.
+ *
+ * The output is a UTF-8-encoded JSON string per RFC 8785. External
+ * implementations using any JCS library produce the same bytes.
+ */
+export function canonicalizeContracts(contract) {
+    const stripped = canonicalizeValue(contract ?? {});
+    // `canonicalize` may return undefined if every field was stripped;
+    // fall back to the empty-object canonical form so the hash function
+    // always receives a stable string.
+    const result = canonicalize(stripped);
+    return result ?? '{}';
+}

package/dist/registry/summarize-contract.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One-line, paraphrase-stable summary of a `DataContract` shape.
+ *
+ * Two consumers share this string:
+ *   1. **Embedding input** — concatenated with the intent prose
+ *      before bge-small embedding. The structured summary anchors
+ *      retrieval to slot/action names that survive prose
+ *      paraphrase, while the prose half feeds bge-small's
+ *      topic-similarity awareness. Hybrid input.
+ *   2. **LLM rerank prompt** — shown to Haiku alongside the user's
+ *      query so the judge has the structural context it needs to
+ *      decide match-vs-no-match.
+ *
+ * Putting both consumers on the same string is load-bearing: if the
+ * embedded vector and the prompt-shown summary diverged, we'd get
+ * "RAG retrieved candidate X, but the prompt shows a different
+ * summary" — the judge would lose context the index used to
+ * retrieve. One source of truth eliminates that drift class.
+ *
+ * Format (deterministic):
+ *
+ *     slots=<name:type,...>;
+ *     actions=<name(payloadFields)?,...>; streams=<name,...>;
+ *     props=<name:type,...>
+ *
+ * Format details:
+ *   - slots: `name:type` (e.g. `count:number,draft:string`). Bare
+ *     `name` when the schema has no `type` field.
+ *   - actions: `name(field1,field2,...)` when the action's schema has
+ *     non-empty `properties`; bare `name` when payload-less. This
+ *     differentiation is load-bearing: a `sendChip` action with
+ *     `{chipText: string}` payload must NOT match a payload-less
+ *     `sendChip` cached blueprint, since the runtime-emitted action
+ *     would arrive with `data: {}` instead of `data: {chipText}` —
+ *     the agent loses the user's input. Surfacing payload field names
+ *     in the summary lets the judge see this distinction.
+ *   - streams: bare `name` (channel schemas vary a lot and are usually
+ *     emitted by the agent later; including them adds noise).
+ *   - props: `name:type` (initial render shape).
+ *
+ * Empty slots/actions/streams/props collapse to `∅`.
+ */
+import type { DataContract } from '../types/data-contract.js';
+/** Stable summary of `contract` for embedding + rerank input. */
+export declare function summarizeContract(contract: DataContract | undefined): string;
+//# sourceMappingURL=summarize-contract.d.ts.map

package/dist/registry/summarize-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize-contract.d.ts","sourceRoot":"","sources":["../../src/registry/summarize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,GAAG,SAAS,GACjC,MAAM,CA6CR"}

package/dist/registry/summarize-contract.js

@@ -0,0 +1,63 @@
+/** Stable summary of `contract` for embedding + rerank input. */
+export function summarizeContract(contract) {
+    if (!contract)
+        return 'slots=∅; actions=∅; streams=∅';
+    const slots = contract.contextSpec
+        ? Object.entries(contract.contextSpec)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, entry]) => {
+            const t = readType(entry.schema);
+            return t ? `${name}:${t}` : name;
+        })
+            .join(',')
+        : '';
+    const actions = contract.actionSpec
+        ? Object.entries(contract.actionSpec)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, entry]) => {
+            const fields = readPayloadFields(entry.schema);
+            return fields ? `${name}(${fields})` : name;
+        })
+            .join(',')
+        : '';
+    const streams = contract.streamSpec
+        ? Object.keys(contract.streamSpec).sort().join(',')
+        : '';
+    const props = contract.propsSpec?.properties
+        ? Object.entries(contract.propsSpec.properties)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, entry]) => {
+            const t = readType(entry.schema);
+            return t ? `${name}:${t}` : name;
+        })
+            .join(',')
+        : '';
+    const parts = [];
+    parts.push(`slots=${slots || '∅'}`);
+    parts.push(`actions=${actions || '∅'}`);
+    parts.push(`streams=${streams || '∅'}`);
+    if (props)
+        parts.push(`props=${props}`);
+    return parts.join('; ');
+}
+function readType(schema) {
+    if (typeof schema !== 'object' || schema === null)
+        return null;
+    const t = schema.type;
+    return typeof t === 'string' ? t : null;
+}
+/** Sorted comma-joined property names for an action's payload schema,
+ *  or `null` when the action takes no payload. Empty `properties` →
+ *  null (payload-less). */
+function readPayloadFields(schema) {
+    if (typeof schema !== 'object' || schema === null)
+        return null;
+    const props = schema.properties;
+    if (typeof props !== 'object' || props === null || Array.isArray(props)) {
+        return null;
+    }
+    const keys = Object.keys(props);
+    if (keys.length === 0)
+        return null;
+    return keys.sort().join(',');
+}

package/dist/schema-learning/derive-contract.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Deterministic {@link DataContract} derivation from MCP tool schemas.
+ *
+ * Given a primary data tool (with `outputSchema`) and optional action tools
+ * (with `inputSchema`), produces a complete contract — no LLM needed.
+ *
+ * This is the Screen Designer's Tier 1 fast path: when a ggui-first-party MCP
+ * server ships native `outputSchema` on every tool, the contract falls out of
+ * the schema automatically. The agent supplies the wiring (data tool + action
+ * tools); ggui derives the rendering contract.
+ *
+ * Tier 2 (learned `generatedOutputSchema`) uses the same deriver — the caller
+ * passes the learned schema instead of the native one.
+ */
+import type { ActionSpec, DataContract, JsonSchema, PropsSpec } from "../types/data-contract.js";
+/** An MCP tool spec, as it appears in tools/list (subset we care about). */
+export interface McpToolSpec {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+}
+export interface DeriveContractInput {
+    /** Display name of the owning server, used to build the intent string. */
+    serverName: string;
+    /** Primary tool — its outputSchema becomes the component's props. */
+    dataTool: McpToolSpec;
+    /** Optional MCP tools the UI hints at on its gestures. Each becomes an ActionEntry with `nextStep` set to the tool name (advisory hint the agent reads on `ggui_consume` to decide which tool to call next). */
+    actionTools?: McpToolSpec[];
+    /** Optional intent override. Default: derived from serverName + dataTool.name. */
+    intent?: string;
+    /** Optional tool-name prefix to strip when generating action keys and labels.
+     * Only strips when the tool name actually starts with `${toolPrefix}`. Default: none —
+     * the full tool name is used. Supply this only for servers that prefix their tools
+     * (e.g. `toolPrefix: "gmail_"` turns `gmail_search_messages` into `searchMessages`).
+     * Bare-named tools (`get_task`, `complete_task`) must NOT use this. */
+    toolPrefix?: string;
+}
+/**
+ * Build a DataContract from native MCP tool schemas.
+ *
+ * Behavior:
+ * - `intent` — "<serverName> — <humanized tool verb>" unless overridden.
+ * - `props` — each top-level property of dataTool.outputSchema becomes a PropEntry.
+ *   If outputSchema is not an object schema, a single `data` prop wraps the whole thing.
+ * - `actions` — one ActionEntry per actionTool, with `tool` wired to the MCP tool name
+ *   and `schema` set to the tool's inputSchema (if present).
+ *
+ * Pure — deterministic given identical input.
+ */
+export declare function deriveContract(input: DeriveContractInput): DataContract;
+/** Convert an outputSchema into a PropsSpec. */
+export declare function propsFromOutputSchema(outputSchema: JsonSchema | undefined, description?: string): PropsSpec | undefined;
+/** Convert a list of action-tools into an ActionSpec, one entry per tool.
+ * Collisions (two tools camelCase-ing to the same key) are resolved by appending
+ * a numeric suffix — the raw tool name is always preserved on the
+ * entry's `nextStep` hint. */
+export declare function actionsFromTools(actionTools: McpToolSpec[], toolPrefix?: string): ActionSpec;
+/** Humanize a tool name, optionally stripping a known server prefix.
+ * `humanizeToolName("gmail_search_messages", "gmail_")` → "Search Messages".
+ * `humanizeToolName("get_task")` → "Get Task". */
+export declare function humanizeToolName(name: string, toolPrefix?: string): string;
+/** Strip `toolPrefix` iff `name` starts with it; otherwise return `name` unchanged. */
+export declare function stripPrefix(name: string, toolPrefix?: string): string;
+/** "search_messages" → "searchMessages". */
+export declare function camelKey(name: string): string;
+//# sourceMappingURL=derive-contract.d.ts.map

package/dist/schema-learning/derive-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-contract.d.ts","sourceRoot":"","sources":["../../src/schema-learning/derive-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAEV,UAAU,EACV,YAAY,EACZ,UAAU,EAEV,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,WAAW,CAAC;IACtB,gNAAgN;IAChN,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;2EAIuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CAiBvE;AAED,gDAAgD;AAChD,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,UAAU,GAAG,SAAS,EACpC,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,GAAG,SAAS,CA2BvB;AAED;;;8BAG8B;AAC9B,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAkB5F;AAUD;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAO1E;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,4CAA4C;AAC5C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK7C"}

package/dist/schema-learning/derive-contract.js

@@ -0,0 +1,117 @@
+/**
+ * Build a DataContract from native MCP tool schemas.
+ *
+ * Behavior:
+ * - `intent` — "<serverName> — <humanized tool verb>" unless overridden.
+ * - `props` — each top-level property of dataTool.outputSchema becomes a PropEntry.
+ *   If outputSchema is not an object schema, a single `data` prop wraps the whole thing.
+ * - `actions` — one ActionEntry per actionTool, with `tool` wired to the MCP tool name
+ *   and `schema` set to the tool's inputSchema (if present).
+ *
+ * Pure — deterministic given identical input.
+ */
+export function deriveContract(input) {
+    const { dataTool, actionTools = [], toolPrefix } = input;
+    // `intent` is not a contract field. `input.intent` and `serverName`
+    // stay on the input so callers can describe the contract for their
+    // own purposes (logging, embedding-search keys); the returned
+    // contract carries no intent of its own. See {@link DataContract}.
+    const contract = {};
+    const props = propsFromOutputSchema(dataTool.outputSchema, dataTool.description);
+    if (props)
+        contract.propsSpec = props;
+    if (actionTools.length > 0) {
+        contract.actionSpec = actionsFromTools(actionTools, toolPrefix);
+    }
+    return contract;
+}
+/** Convert an outputSchema into a PropsSpec. */
+export function propsFromOutputSchema(outputSchema, description) {
+    if (!outputSchema)
+        return undefined;
+    // Object schema — one PropEntry per top-level property.
+    if (outputSchema.type === "object" && outputSchema.properties) {
+        const required = new Set(outputSchema.required ?? []);
+        const properties = {};
+        for (const [key, propSchema] of Object.entries(outputSchema.properties)) {
+            const entry = {
+                schema: propSchema,
+                required: required.has(key),
+            };
+            if (propSchema.description)
+                entry.description = propSchema.description;
+            if (propSchema.example !== undefined)
+                entry.example = propSchema.example;
+            properties[key] = entry;
+        }
+        const spec = { properties };
+        if (description)
+            spec.description = description;
+        return spec;
+    }
+    // Non-object schema (array, primitive, anyOf) — wrap as single `data` prop.
+    const entry = { schema: outputSchema, required: true };
+    if (outputSchema.description)
+        entry.description = outputSchema.description;
+    const spec = { properties: { data: entry } };
+    if (description)
+        spec.description = description;
+    return spec;
+}
+/** Convert a list of action-tools into an ActionSpec, one entry per tool.
+ * Collisions (two tools camelCase-ing to the same key) are resolved by appending
+ * a numeric suffix — the raw tool name is always preserved on the
+ * entry's `nextStep` hint. */
+export function actionsFromTools(actionTools, toolPrefix) {
+    const actions = {};
+    for (const tool of actionTools) {
+        let actionKey = camelKey(stripPrefix(tool.name, toolPrefix));
+        if (actionKey in actions) {
+            // Fall back to the full tool name (camelCased) before disambiguating with a suffix.
+            const full = camelKey(tool.name);
+            actionKey = full in actions ? uniqueKey(actions, full) : full;
+        }
+        const entry = {
+            label: humanizeToolName(tool.name, toolPrefix),
+            nextStep: tool.name,
+        };
+        if (tool.description)
+            entry.description = tool.description;
+        if (tool.inputSchema)
+            entry.schema = tool.inputSchema;
+        actions[actionKey] = entry;
+    }
+    return actions;
+}
+function uniqueKey(existing, base) {
+    let i = 2;
+    while (`${base}${i}` in existing)
+        i++;
+    return `${base}${i}`;
+}
+// ────────────────────────── naming helpers ──────────────────────────
+/** Humanize a tool name, optionally stripping a known server prefix.
+ * `humanizeToolName("gmail_search_messages", "gmail_")` → "Search Messages".
+ * `humanizeToolName("get_task")` → "Get Task". */
+export function humanizeToolName(name, toolPrefix) {
+    const stripped = stripPrefix(name, toolPrefix);
+    return stripped
+        .split(/[_\-\s]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join(" ");
+}
+/** Strip `toolPrefix` iff `name` starts with it; otherwise return `name` unchanged. */
+export function stripPrefix(name, toolPrefix) {
+    if (!toolPrefix)
+        return name;
+    return name.startsWith(toolPrefix) ? name.slice(toolPrefix.length) : name;
+}
+/** "search_messages" → "searchMessages". */
+export function camelKey(name) {
+    const parts = name.split(/[_\-\s]+/).filter(Boolean);
+    if (parts.length === 0)
+        return name;
+    return parts[0].toLowerCase() +
+        parts.slice(1).map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join("");
+}

package/dist/schema-learning/merge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Incremental JSON Schema learning — type union over observed samples.
+ *
+ * Used by the Screen Designer to build `generatedOutputSchema` from real MCP tool
+ * responses when the server doesn't ship a native `outputSchema`. Each captured
+ * response is merged into the running schema via {@link mergeSchema}; the result
+ * converges as more samples arrive.
+ *
+ * Algorithm:
+ * - Object properties: union of keys. A property present in one sample but missing
+ *   from another is marked optional (dropped from `required`).
+ * - Array items: recursive merge across element schemas from all samples.
+ * - Primitives of the same type: identity.
+ * - `null` + any type: sets `nullable: true` on that type.
+ * - Type conflicts (e.g. string + number): collapsed into `anyOf`.
+ *
+ * Pure — no I/O, no DB, no clock. Safe to call from Lambda, edge, or tests.
+ */
+import type { JsonSchema, JsonValue } from "../types/data-contract.js";
+/** Infer a JSON Schema from a single JSON value. */
+export declare function inferSchema(value: JsonValue): JsonSchema;
+/**
+ * Merge a new observed sample into an existing schema. If `existing` is null,
+ * returns the schema inferred from `sample` alone.
+ */
+export declare function mergeSchema(existing: JsonSchema | null | undefined, sample: JsonValue): JsonSchema;
+/**
+ * Merge two schemas into one that accepts values satisfying either. Exported
+ * for the seeder path (combining two known schemas without sampling).
+ */
+export declare function mergeTwoSchemas(a: JsonSchema, b: JsonSchema): JsonSchema;
+//# sourceMappingURL=merge.d.ts.map

package/dist/schema-learning/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/schema-learning/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAc,UAAU,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEnF,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA4BxD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,UAAU,CAIlG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CA0BxE"}