@ggui-ai/protocol 0.2.0-alpha.4 → 0.3.0-rc.0

package/dist/integrations/mcp-apps.js

@@ -3,7 +3,7 @@
  *
  * This module is the **boundary** for MCP Apps outbound delivery. Anything
  * MCP-Apps-specific that ggui exposes to the rest of the codebase lives
- * here — never in `types/live-channel.ts`, `types/mcp.ts`, `types/session.ts`,
+ * here — never in `types/live-channel.ts`, `types/mcp.ts`, `types/render.ts`,
  * or any other core module. Consumers opt in via the subpath import:
  *
  * ```ts
@@ -21,12 +21,14 @@
  * drift is bounded to callers that explicitly import from here.
  *
  * Core still carries two fields that make the bootstrap flow work —
- * `SubscribePayload.bootstrap?: string` and `AckPayload.renderToken?:
+ * `SubscribePayload.wsToken?: string` and `AckPayload.sessionToken?:
  * string`. Those are deliberately framed as **general transport bootstrap
  * credentials** (opaque strings), not MCP-Apps-specific. Any future
  * bootstrap mechanism (short-code auto-login, signed-URL bootstrap, etc.)
  * reuses the same slots.
  */
+import { appThemeSchema } from '../schemas/app-theme.js';
+import { isRecord } from '../validation/is-record.js';
 /**
  * MCP capability name ggui servers advertise in their MCP `initialize`
  * response capabilities when they implement the MCP Apps outbound path.
@@ -92,14 +94,14 @@ export function deriveContextName(slotKey) {
 // ```jsonc
 // "_meta": {
 //   "ai.ggui/render": {
-//     renderId, appId, runtimeUrl,
+//     sessionId, appId, runtimeUrl,
 //     wsUrl?, wsToken?, expiresAt?,
 //     pollingUrl?,
-//     themeId?, themeMode?,
+//     themeId?, themeMode?, theme?,
 //     gadgets?, publicEnv?, streamWebSocketLocalTools?,
-//     appCallableTools?, permissionsPolicy?,
+//     permissionsPolicy?,
 //     lastSequence?,
-//     propsJson?, actionNextSteps?, contextSlots?,
+//     propsJson?, contextSlots?,
 //     contractHash?, validatorsUrl?,
 //     codeUrl?, codeHash?, kind?
 //   }
@@ -128,7 +130,7 @@ export const MCP_APP_AI_GGUI_RENDER_META_KEY = 'ai.ggui/render';
  * Read the `ai.ggui/render` slice off a parsed JSON-RPC `_meta` object.
  *
  * Structural validation only. Missing key returns `{ok: true, meta: undefined}`
- * — not a failure. Required-fields gate (renderId / appId / runtimeUrl)
+ * — not a failure. Required-fields gate (sessionId / appId / runtimeUrl)
  * fires only when the key is present. Field-level optional-field
  * defensive parsing (e.g. context-slot schema narrowing, expiresAt date
  * parse) lives downstream in the iframe-runtime's `validateMeta`.
@@ -136,21 +138,20 @@ export const MCP_APP_AI_GGUI_RENDER_META_KEY = 'ai.ggui/render';
  * @public
  */
 export function parseMcpAppAiGguiRenderMeta(meta) {
-    if (meta === null || typeof meta !== 'object') {
+    if (!isRecord(meta)) {
         return { ok: true };
     }
-    const m = meta;
-    const raw = m[MCP_APP_AI_GGUI_RENDER_META_KEY];
+    const raw = meta[MCP_APP_AI_GGUI_RENDER_META_KEY];
     if (raw === undefined) {
         return { ok: true };
     }
-    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    if (!isRecord(raw)) {
         return { ok: false, reason: 'MALFORMED_RENDER' };
     }
     const s = raw;
     // Identity — required when slice is present.
-    if (typeof s.renderId !== 'string' ||
-        s.renderId.length === 0 ||
+    if (typeof s.sessionId !== 'string' ||
+        s.sessionId.length === 0 ||
         typeof s.appId !== 'string' ||
         s.appId.length === 0 ||
         typeof s.runtimeUrl !== 'string' ||
@@ -200,8 +201,14 @@ export function parseMcpAppAiGguiRenderMeta(meta) {
         cHash.length > 0 &&
         typeof vUrl === 'string' &&
         vUrl.length > 0;
+    // Theme overlay — validated via the complete `appThemeSchema` so the
+    // parsed value is typed `AppTheme` without an unguarded cast. A
+    // malformed/absent overlay yields `undefined` and is dropped from the
+    // slice (tolerant degrade, consistent with the other optional fields).
+    const themeParse = s.theme !== undefined ? appThemeSchema.safeParse(s.theme) : undefined;
+    const parsedTheme = themeParse?.success === true ? themeParse.data : undefined;
     const slice = {
-        renderId: s.renderId,
+        sessionId: s.sessionId,
         appId: s.appId,
         runtimeUrl: s.runtimeUrl,
         ...(hasW && hasT ? { wsUrl: aw, wsToken: at } : {}),
@@ -211,6 +218,12 @@ export function parseMcpAppAiGguiRenderMeta(meta) {
         ...(s.themeMode !== undefined
             ? { themeMode: s.themeMode }
             : {}),
+        // `theme` is the only structured optional field on the slice, so
+        // it gets the schema as its parser (the rest are scalar/array
+        // casts). `appThemeSchema` is the complete validator — a malformed
+        // overlay degrades to "no overlay" rather than failing the whole
+        // slice, matching the tolerant posture of the other optional fields.
+        ...(parsedTheme !== undefined ? { theme: parsedTheme } : {}),
         ...(s.gadgets !== undefined
             ? { gadgets: s.gadgets }
             : {}),
@@ -222,19 +235,11 @@ export function parseMcpAppAiGguiRenderMeta(meta) {
                 streamWebSocketLocalTools: s.streamWebSocketLocalTools,
             }
             : {}),
-        ...(s.appCallableTools !== undefined
-            ? { appCallableTools: s.appCallableTools }
-            : {}),
         ...(s.permissionsPolicy !== undefined
             ? { permissionsPolicy: s.permissionsPolicy }
             : {}),
         ...(ls !== undefined ? { lastSequence: ls } : {}),
         ...(s.propsJson !== undefined ? { propsJson: s.propsJson } : {}),
-        ...(s.actionNextSteps !== undefined
-            ? {
-                actionNextSteps: s.actionNextSteps,
-            }
-            : {}),
         ...(s.contextSlots !== undefined
             ? {
                 contextSlots: s.contextSlots,
@@ -295,15 +300,14 @@ export const MCP_APP_AI_GGUI_HOST_SESSION_META_KEY = 'ai.ggui/host-session';
  * @public
  */
 export function parseMcpAppAiGguiHostSessionMeta(meta) {
-    if (meta === null || typeof meta !== 'object') {
+    if (!isRecord(meta)) {
         return { ok: true };
     }
-    const m = meta;
-    const raw = m[MCP_APP_AI_GGUI_HOST_SESSION_META_KEY];
+    const raw = meta[MCP_APP_AI_GGUI_HOST_SESSION_META_KEY];
     if (raw === undefined) {
         return { ok: true };
     }
-    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    if (!isRecord(raw)) {
         return { ok: false, reason: 'MALFORMED_HOST_SESSION' };
     }
     const r = raw;
@@ -322,41 +326,44 @@ export function parseMcpAppAiGguiHostSessionMeta(meta) {
     };
 }
 /**
- * Type guard: narrows a `Render` (or unknown) to {@link McpAppsRender}.
+ * Type guard: narrows a `GguiSession` (or unknown) to {@link McpAppsGguiSession}.
  * Uses the discriminator.
  */
-export function isMcpAppsRender(entry) {
+export function isMcpAppsGguiSession(entry) {
     return (entry !== null &&
         typeof entry === 'object' &&
         entry.type === 'mcpApps');
 }
 /**
- * Structural validator for an `McpAppsRender` — not a Zod schema
+ * Structural validator for an `McpAppsGguiSession` — not a Zod schema
  * so we don't force a Zod dependency here. Returns null on failure
  * (caller maps to an appropriate error code). Required when accepting
  * one over the wire from an agent: the discriminator alone isn't
  * enough.
  */
-export function validateMcpAppsRender(input) {
-    if (input === null || typeof input !== 'object')
-        return null;
-    const item = input;
-    if (item.type !== 'mcpApps')
-        return null;
-    if (typeof item.id !== 'string' || item.id.length === 0)
-        return null;
-    if (typeof item.createdAt !== 'string')
-        return null;
-    const source = item.source;
-    if (!source || typeof source !== 'object')
-        return null;
+export function validateMcpAppsGguiSession(input) {
+    return hasMcpAppsGguiSessionShape(input) ? input : null;
+}
+/** Structural predicate behind {@link validateMcpAppsGguiSession}. */
+function hasMcpAppsGguiSessionShape(input) {
+    if (!isRecord(input))
+        return false;
+    if (input.type !== 'mcpApps')
+        return false;
+    if (typeof input.id !== 'string' || input.id.length === 0)
+        return false;
+    if (typeof input.createdAt !== 'string')
+        return false;
+    const source = input.source;
+    if (!isRecord(source))
+        return false;
     if (typeof source.connectorId !== 'string' || source.connectorId.length === 0)
-        return null;
+        return false;
     if (typeof source.toolName !== 'string' || source.toolName.length === 0)
-        return null;
+        return false;
     if (typeof source.resourceUri !== 'string' || !source.resourceUri.startsWith('ui://'))
-        return null;
-    return input;
+        return false;
+    return true;
 }
 /**
  * The closed set of valid lifecycle states. Exposed as a `readonly`
@@ -380,7 +387,7 @@ export const MCP_APP_LIFECYCLE_STATES = [
  *   - Outer envelope is an object with `type === 'ggui:lifecycle'`.
  *   - `event` is an object with `state` matching {@link
  *     MCP_APP_LIFECYCLE_STATES}.
- *   - If `renderId` is present, it is a non-empty string.
+ *   - If `sessionId` is present, it is a non-empty string.
  *   - If `error` is present, it is an object with string `code` +
  *     `message`.
  *
@@ -400,8 +407,8 @@ export function isMcpAppLifecycleMessage(message) {
     if (!MCP_APP_LIFECYCLE_STATES.includes(e.state)) {
         return false;
     }
-    if (e.renderId !== undefined) {
-        if (typeof e.renderId !== 'string' || e.renderId.length === 0) {
+    if (e.sessionId !== undefined) {
+        if (typeof e.sessionId !== 'string' || e.sessionId.length === 0) {
             return false;
         }
     }
@@ -415,6 +422,43 @@ export function isMcpAppLifecycleMessage(message) {
     }
     return true;
 }
+// =============================================================================
+// Renderer → host postMessage envelope vocabulary
+//
+// The renderer (inside the MCP Apps iframe) speaks to its parent via a
+// small closed family of `{type: 'ggui:…'}` postMessage envelopes. The
+// DISCRIMINATOR vocabulary is protocol-owned and lives HERE, in one
+// place — hosts on every platform (web iframe hosts, React Native
+// WebView hosts) and the renderer itself import these constants rather
+// than re-encoding the strings, so a tag rename is a single-point
+// change and recognizer drift (a host classifying a tag no renderer
+// emits) is structurally impossible.
+//
+// Payload OWNERSHIP follows the vocabulary's semantics:
+//   - `ggui:lifecycle` — protocol-owned end to end (see
+//     {@link McpAppLifecycleMessage} above): the payload is a wire
+//     contract with host obligations.
+//   - `ggui:renderer-ready` / `ggui:bootstrap-failed` — envelope shape
+//     is protocol-owned ({@link McpAppRendererReadyMessage} /
+//     {@link McpAppBootstrapFailedMessage}); the renderer narrows
+//     `reason` to its own closed reason union at the emission site.
+//   - `ggui:observe` — only the TAG is protocol-owned. The event union
+//     it carries is renderer-internal telemetry vocabulary
+//     (`ObservabilityEvent` in the renderer package); hosts treat it
+//     as extensibly-closed.
+// =============================================================================
+/** Envelope tag: renderer alive + bundle evaluated (pre-`ui/initialize`). */
+export const MCP_APP_RENDERER_READY_TYPE = 'ggui:renderer-ready';
+/** Envelope tag: a boot-path failure (parse / initialize / handshake). */
+export const MCP_APP_BOOTSTRAP_FAILED_TYPE = 'ggui:bootstrap-failed';
+/** Envelope tag: renderer-internal observability event (telemetry). */
+export const MCP_APP_OBSERVE_TYPE = 'ggui:observe';
+/**
+ * Envelope tag: mount-lifecycle transition. Constant twin of the
+ * literal on {@link McpAppLifecycleMessage} — the annotation ties the
+ * two so they cannot drift.
+ */
+export const MCP_APP_LIFECYCLE_TYPE = 'ggui:lifecycle';
 /**
  * The three canonical gesture kinds — useful for exhaustiveness checks
  * in `switch (kind) { ... }` blocks. Frozen so consumers can safely use
@@ -438,12 +482,12 @@ export const SUBMIT_ACTION_KINDS = [
  * MUST validate shape before consuming.
  */
 export function isGguiSubmitActionInput(value) {
-    if (value === null || typeof value !== 'object')
+    if (!isRecord(value))
         return false;
     const v = value;
     if (typeof v.kind !== 'string' || v.kind.length === 0)
         return false;
-    if (typeof v.renderId !== 'string' || v.renderId.length === 0)
+    if (typeof v.sessionId !== 'string' || v.sessionId.length === 0)
         return false;
     if (typeof v.appId !== 'string' || v.appId.length === 0)
         return false;
@@ -451,7 +495,9 @@ export function isGguiSubmitActionInput(value) {
         return false;
     if (typeof v.firedAt !== 'string' || v.firedAt.length === 0)
         return false;
-    if (v.payload === null || typeof v.payload !== 'object')
+    // Payload-object presence is the invariant: a JSON OBJECT, never an
+    // array — array payloads reject even for unknown extension kinds.
+    if (!isRecord(v.payload))
         return false;
     // Per-kind payload narrowing for the closed primary set. Unknown
     // kinds pass through with whatever payload-object the caller supplied

package/dist/recommended-prompts.d.ts

@@ -39,7 +39,7 @@
  * @example
  * ```ts
  * import { query } from '@anthropic-ai/claude-agent-sdk';
- * import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol/recommended-prompts';
+ * import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol';
  *
  * query({
  *   prompt: userInput,

package/dist/recommended-prompts.js

@@ -39,7 +39,7 @@
  * @example
  * ```ts
  * import { query } from '@anthropic-ai/claude-agent-sdk';
- * import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol/recommended-prompts';
+ * import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol';
  *
  * query({
  *   prompt: userInput,

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

@@ -6,4 +6,7 @@ import type { DataContract } from '../types/data-contract.js';
  * Node versions (sha256 + utf-8 encoding are well-specified).
  */
 export declare function blueprintKey(contract: DataContract | undefined): string;
+export { variantKey } from './variant-key.js';
+export { toPortableBlueprint, fromPortableBlueprint, PORTABLE_BLUEPRINT_SCHEMA_VERSION, PORTABLE_BLUEPRINT_V1_REJECTION, type PortableBlueprintSource, type PortableBlueprintImportResult, } from './portable-blueprint.js';
+export * from './blueprint-stamp.js';
 //# sourceMappingURL=blueprint-key.d.ts.map

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

@@ -1 +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"}
+{"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;AAMD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,iCAAiC,EACjC,+BAA+B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,GACnC,MAAM,yBAAyB,CAAC;AAIjC,cAAc,sBAAsB,CAAC"}

package/dist/registry/blueprint-key.js

@@ -26,3 +26,12 @@ export function blueprintKey(contract) {
     const canonical = canonicalizeContracts(contract);
     return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
 }
+// The `@ggui-ai/protocol/blueprint-key` subpath maps to this single
+// file (NOT a barrel), so the variant axis of the reuse key must be
+// re-exported here to be importable at that subpath alongside
+// `blueprintKey`. See `variant-key.ts` for the implementation.
+export { variantKey } from './variant-key.js';
+export { toPortableBlueprint, fromPortableBlueprint, PORTABLE_BLUEPRINT_SCHEMA_VERSION, PORTABLE_BLUEPRINT_V1_REJECTION, } from './portable-blueprint.js';
+// `computeToolCatalogHash` pulls `node:crypto`, so it lives behind this
+// server-only subpath alongside `blueprintKey` rather than the root barrel.
+export * from './blueprint-stamp.js';

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

@@ -0,0 +1,12 @@
+/** Structural shape of a tool-identity catalog (handlers' ToolIdentityCatalog is assignable to this). */
+export type ToolCatalogShape = Record<string, {
+    readonly name: string;
+    readonly version?: string;
+}>;
+/**
+ * Deterministic 16-char hex hash of a tool-identity catalog. Key order is
+ * normalized so the hash is stable across deployments that build the catalog
+ * in different orders.
+ */
+export declare function computeToolCatalogHash(catalog: ToolCatalogShape): string;
+//# sourceMappingURL=blueprint-stamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blueprint-stamp.d.ts","sourceRoot":"","sources":["../../src/registry/blueprint-stamp.ts"],"names":[],"mappings":"AAEA,yGAAyG;AACzG,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEpG;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAKxE"}

package/dist/registry/blueprint-stamp.js

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+/**
+ * Deterministic 16-char hex hash of a tool-identity catalog. Key order is
+ * normalized so the hash is stable across deployments that build the catalog
+ * in different orders.
+ */
+export function computeToolCatalogHash(catalog) {
+    const normalized = Object.keys(catalog)
+        .sort()
+        .map((k) => [k, catalog[k].name, catalog[k].version ?? null]);
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 16);
+}

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

@@ -1,4 +1,5 @@
 import type { DataContract } from '../types/data-contract.js';
+import type { BlueprintVariance } from '../types/blueprint.js';
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -15,12 +16,19 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
  *
  * Exported for tests / debugging — production callers should use
  * `canonicalizeContracts()`.
+ *
+ * `stripProse` (default `true`) controls the `description`/`usage`
+ * STRIPPED_KEYS strip. The contract pipeline strips (prose is
+ * informational); the variance pipeline ({@link canonicalizeVariance})
+ * passes `false` because variance prose is load-bearing signal.
  */
-export declare function canonicalizeValue(value: unknown): JsonValue | undefined;
+export declare function canonicalizeValue(value: unknown, stripProse?: boolean): 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.
+ * paraphrase, key order, whitespace, description-only edits, and
+ * `serverInfo.version` (server-version metadata; `serverInfo.name` is
+ * identity and is preserved).
  *
  * Empty / undefined / `{}` all collapse to the same canonical bytes,
  * which produces a stable `blueprintKey` for the "no-contract" case.
@@ -31,5 +39,26 @@ export declare function canonicalizeValue(value: unknown): JsonValue | undefined
  * implementations using any JCS library produce the same bytes.
  */
 export declare function canonicalizeContracts(contract: DataContract | undefined): string;
+/**
+ * Canonical bytes for a {@link BlueprintVariance} block — the input to
+ * `variantKey()`. Same JCS + NFC pipeline as {@link canonicalizeContracts}
+ * with two DELIBERATE divergences from the contract pipeline:
+ *
+ *   1. **No `description`/`usage` strip.** For a contract, prose is
+ *      informational and stripped so a doc tweak doesn't invalidate a
+ *      cache key. For variance, the prose IS the signal: `seedPrompt`
+ *      and any `context` value steer the generated `componentCode`, so
+ *      stripping them would collapse genuinely distinct variants onto
+ *      one key (false reuse). This is the inverse of the contract rule.
+ *   2. **Self-normalizing (D9).** Empty-string fields, empty objects,
+ *      and empty arrays are elided internally so `undefined`, `{}`,
+ *      `{persona:''}`, and an all-empty block all collapse to the same
+ *      "default variant" canonical form. Callers never pre-normalize —
+ *      the accept path (verbatim `blueprintMeta.variance`) and the
+ *      override path produce identical keys for equivalent variance.
+ *
+ * Pure function — no I/O, no globals.
+ */
+export declare function canonicalizeVariance(variance: BlueprintVariance | undefined): string;
 export {};
 //# sourceMappingURL=canonicalize-contract.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"canonicalize-contract.d.ts","sourceRoot":"","sources":["../../src/registry/canonicalize-contract.ts"],"names":[],"mappings":"AAqFA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAY/D,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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,UAAU,UAAO,GAChB,SAAS,GAAG,SAAS,CAgDvB;AA+CD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAOhF;AA6BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GACtC,MAAM,CAQR"}

package/dist/registry/canonicalize-contract.js

@@ -34,7 +34,7 @@
  * 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.
+ * at render 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`
@@ -52,10 +52,22 @@
  *   - 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).
+ *     `toolInfo.inputSchema`/`toolInfo.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).
+ *
+ * # Domain rule: `agentCapabilities.tools[*].serverInfo.version` is stripped
+ *
+ * `serverInfo` ({name, version?}) records the owning MCP server identity.
+ * `(serverInfo.name, toolName)` is the canonical cross-framework identity and
+ * stays in the hash — it disambiguates two servers that expose a byte-identical
+ * bare tool name (Todoist's `todo_add` vs Google-Tasks' `todo_add` must NOT
+ * reuse one another's UI). `serverInfo.version` is METADATA, not identity — a
+ * server version bump MUST NOT invalidate a registered blueprint — so ONLY the
+ * `version` field is removed (structurally, context-scoped to the tool-catalog
+ * recursion) BEFORE the JCS pass. `toolInfo.inputSchema` / `toolInfo.outputSchema`
+ * stay — they ARE identity (they shape the data).
  *   - Inner JSON Schema fields under every `schema:` wrapper (`type`,
  *     `enum`, `properties`, `required`, `items`, `additionalProperties`,
  *     `nullable`, `format`, …).
@@ -71,6 +83,7 @@
  * Pure function — no I/O, no globals.
  */
 import canonicalize from 'canonicalize';
+import { isRecord } from '../validation/is-record.js';
 /**
  * Informational-prose field names removed from the canonical form —
  * but ONLY where they are string-valued (see `canonicalizeValue`); a
@@ -92,8 +105,13 @@ const STRIPPED_KEYS = new Set(['description', 'usage']);
  *
  * Exported for tests / debugging — production callers should use
  * `canonicalizeContracts()`.
+ *
+ * `stripProse` (default `true`) controls the `description`/`usage`
+ * STRIPPED_KEYS strip. The contract pipeline strips (prose is
+ * informational); the variance pipeline ({@link canonicalizeVariance})
+ * passes `false` because variance prose is load-bearing signal.
  */
-export function canonicalizeValue(value) {
+export function canonicalizeValue(value, stripProse = true) {
     if (value === undefined)
         return undefined;
     if (value === null)
@@ -107,13 +125,13 @@ export function canonicalizeValue(value) {
     if (Array.isArray(value)) {
         const out = [];
         for (const item of value) {
-            const c = canonicalizeValue(item);
+            const c = canonicalizeValue(item, stripProse);
             if (c !== undefined)
                 out.push(c);
         }
         return out;
     }
-    if (t === 'object') {
+    if (isRecord(value)) {
         const obj = value;
         // NFC-normalize keys before sort so two contracts with the same
         // key in different normalization forms (precomposed "café" vs
@@ -128,13 +146,14 @@ export function canonicalizeValue(value) {
             // 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'))
+            // contracts onto one blueprint cache key. Skipped entirely when
+            // `stripProse` is false (the variance pipeline).
+            .filter((k) => !(stripProse && 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]);
+            const c = canonicalizeValue(obj[source], stripProse);
             if (c !== undefined)
                 out[normalized] = c;
         }
@@ -143,10 +162,43 @@ export function canonicalizeValue(value) {
     // Functions, symbols, bigint — not JSON-serializable; treat as absent.
     return undefined;
 }
+/**
+ * Structurally reduce `agentCapabilities.tools[*].serverInfo` to its
+ * identity-bearing `name` before the generic JCS walk — `serverInfo.name`
+ * is load-bearing identity (it disambiguates two servers that expose a
+ * byte-identical bare tool name, e.g. Todoist vs Google-Tasks `todo_add`),
+ * while `serverInfo.version` is metadata that MUST NOT bust the cache key.
+ * Context-scoped to the tool catalog (NOT a global value-guard) so a spec
+ * slot / gadget package / tool literally named `serverInfo` elsewhere can
+ * never be collateral-stripped. Pure — returns a shallow-cloned projection;
+ * the input is never mutated. Returns the input unchanged when there is no
+ * `agentCapabilities.tools` to walk.
+ */
+function stripToolServerInfo(contract) {
+    const tools = contract.agentCapabilities?.tools;
+    if (!tools)
+        return contract;
+    const cleanedTools = {};
+    for (const [name, entry] of Object.entries(tools)) {
+        if (entry.serverInfo === undefined) {
+            cleanedTools[name] = entry;
+            continue;
+        }
+        // Keep serverInfo.name (identity); drop serverInfo.version (metadata).
+        const { version: _version, ...nameOnly } = entry.serverInfo;
+        cleanedTools[name] = { ...entry, serverInfo: nameOnly };
+    }
+    return {
+        ...contract,
+        agentCapabilities: { ...contract.agentCapabilities, tools: cleanedTools },
+    };
+}
 /**
  * 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.
+ * paraphrase, key order, whitespace, description-only edits, and
+ * `serverInfo.version` (server-version metadata; `serverInfo.name` is
+ * identity and is preserved).
  *
  * Empty / undefined / `{}` all collapse to the same canonical bytes,
  * which produces a stable `blueprintKey` for the "no-contract" case.
@@ -157,10 +209,70 @@ export function canonicalizeValue(value) {
  * implementations using any JCS library produce the same bytes.
  */
 export function canonicalizeContracts(contract) {
-    const stripped = canonicalizeValue(contract ?? {});
+    const stripped = canonicalizeValue(stripToolServerInfo(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 ?? '{}';
 }
+/**
+ * Recursively elide "absent-equivalent" fields so semantically-empty
+ * variance collapses to the empty-object canonical form. Empty strings
+ * (`''`), empty objects (`{}`), empty arrays, `null`, and `undefined`
+ * are all dropped; a primitive that survives is kept verbatim. This is
+ * the D9 self-normalization step — callers never pre-normalize.
+ */
+function elideEmpty(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value === '' ? undefined : value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const item of value) {
+            const e = elideEmpty(item);
+            if (e !== undefined)
+                out.push(e);
+        }
+        return out.length === 0 ? undefined : out;
+    }
+    const out = {};
+    for (const key of Object.keys(value)) {
+        const e = elideEmpty(value[key]);
+        if (e !== undefined)
+            out[key] = e;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/**
+ * Canonical bytes for a {@link BlueprintVariance} block — the input to
+ * `variantKey()`. Same JCS + NFC pipeline as {@link canonicalizeContracts}
+ * with two DELIBERATE divergences from the contract pipeline:
+ *
+ *   1. **No `description`/`usage` strip.** For a contract, prose is
+ *      informational and stripped so a doc tweak doesn't invalidate a
+ *      cache key. For variance, the prose IS the signal: `seedPrompt`
+ *      and any `context` value steer the generated `componentCode`, so
+ *      stripping them would collapse genuinely distinct variants onto
+ *      one key (false reuse). This is the inverse of the contract rule.
+ *   2. **Self-normalizing (D9).** Empty-string fields, empty objects,
+ *      and empty arrays are elided internally so `undefined`, `{}`,
+ *      `{persona:''}`, and an all-empty block all collapse to the same
+ *      "default variant" canonical form. Callers never pre-normalize —
+ *      the accept path (verbatim `blueprintMeta.variance`) and the
+ *      override path produce identical keys for equivalent variance.
+ *
+ * Pure function — no I/O, no globals.
+ */
+export function canonicalizeVariance(variance) {
+    // NFC-normalize + sort keys (canonicalizeValue), but withOUT the
+    // STRIPPED_KEYS prose strip (`stripProse: false`) — variance prose
+    // is load-bearing signal, the inverse of the contract rule.
+    const normalized = canonicalizeValue(variance ?? {}, false);
+    const elided = elideEmpty(normalized) ?? {};
+    const result = canonicalize(elided);
+    return result ?? '{}';
+}