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

package/dist/validation/name-invariants.js

@@ -40,7 +40,7 @@ import { RESERVED_CHANNEL_PREFIX, isReservedChannelName, } from './reserved-chan
  * Stable error code for collisions across the three inbound spec maps
  * (`actionSpec` / `streamSpec` / `contextSpec`). The boilerplate
  * generator emits identifiers from these keys; a collision is an
- * author bug that the protocol catches at push.
+ * author bug that the protocol catches at render.
  */
 export const CTR_DUP_NAME = 'CTR_DUP_NAME';
 /**
@@ -95,7 +95,7 @@ export function checkNameCollisions(contract) {
  * Validate that no `actionSpec` or `contextSpec` key uses the
  * `_ggui:` reserved namespace. `streamSpec` reserved-channel rejection
  * lives in `validateContractStructure` (the reserved namespace there
- * carries server-side semantics like the `_ggui:contract-error`
+ * carries server-side semantics like the `_ggui:lifecycle`
  * channel); this invariant extends the rule uniformly across the
  * other two inbound spec maps.
  *
@@ -137,7 +137,7 @@ export function checkNameInvariants(contract) {
 /**
  * Throwable form of {@link checkNameInvariants}. Use at protocol
  * boundaries where a name collision or reserved-namespace use is a
- * contract bug the caller must fix (push handler, blueprint
+ * contract bug the caller must fix (render handler, blueprint
  * registration).
  *
  * Carries the full violation list so error renderers can show every
@@ -159,7 +159,7 @@ export class NameInvariantError extends Error {
  * Throw-on-violation wrapper around {@link checkNameInvariants}.
  * No-op when the contract's names are consistent.
  *
- * Designed to slot alongside `assertCrossReferences` at push time:
+ * Designed to slot alongside `assertCrossReferences` at render time:
  * cross-reference invariants catch dangling pointers between specs;
  * name invariants catch malformed name spaces within specs. Both
  * surface author-recoverable failures before any state mutation.

package/dist/validation/reserved-channels.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Reserved channel namespace for server-emitted streams on the live channel.
+ *
+ * Agents may NOT declare channels whose names start with `_ggui:` in
+ * their `streamSpec`. The namespace is reserved for system
+ * channels the server emits directly — bypassing the agent's declared
+ * streamSpec because these channels are not part of the agent-authored
+ * contract.
+ *
+ * Concrete reservations today:
+ *
+ *   - {@link PREVIEW_CHANNEL} — provisional A2UI assembly stream
+ *     emitted during fresh-gen `ggui_render` flows. The integration
+ *     surface (A2UI message types, catalog, validators) lives in the
+ *     dedicated boundary package `@ggui-ai/preview-a2ui`; this module
+ *     owns only the protocol-level naming rule so `@ggui-ai/protocol`
+ *     stays free of A2UI-shaped types. Payload validation for this
+ *     channel is delivered via the INJECTION pattern documented on
+ *     {@link BUILTIN_RESERVED_VALIDATORS} — the server composes the
+ *     A2UI validator into `validateStreamData`'s
+ *     `extraReservedValidators` parameter.
+ *   - {@link LIFECYCLE_CHANNEL} — generation-progress lifecycle
+ *     envelopes the server emits for session-wide subscribers.
+ *     Payload is a PROTOCOL-OWNED shape, so the structural validator
+ *     ships inside this module as a built-in (see
+ *     {@link validateGguiLifecyclePayload} +
+ *     {@link BUILTIN_RESERVED_VALIDATORS}).
+ *
+ * Why here and not in `types/live-channel.ts`: `live-channel.ts` describes
+ * WIRE envelope shapes (`StreamEnvelope`, `SubscribePayload`). This
+ * file describes a NAMING POLICY that the contract-structure validator
+ * enforces. Separate concerns — easier to audit the boundary.
+ */
 import type { ValidationResult } from './contract-validator';
 /** Prefix that marks a channel as server-owned (reserved from agents). */
 export declare const RESERVED_CHANNEL_PREFIX = "_ggui:";
@@ -9,27 +42,14 @@ export declare const RESERVED_CHANNEL_PREFIX = "_ggui:";
  */
 export declare const PREVIEW_CHANNEL = "_ggui:preview";
 /**
- * Reserved channel for canonical contract-error envelopes emitted by
- * the wiredActionRouter. Body shape is `ContractErrorPayload` (see
- * `types/data-contract.ts`). Agent-authored `streamSpec`
- * MUST NOT declare this channel — structural validation rejects it
- * alongside every other reserved-prefix name.
+ * Reserved channel for generation-progress lifecycle envelopes —
+ * handshake / render / consume lifecycle signals that drive
+ * client-side progress indicators.
  *
- * If future work adds richer contract observability (e.g., separate
- * `_ggui:wired-tool-invoked` success trace), each new name joins this
- * module with its own constant and the {@link KNOWN_RESERVED_CHANNELS}
- * set below.
- */
-export declare const CONTRACT_ERROR_CHANNEL = "_ggui:contract-error";
-/**
- * Reserved channel for canvas-mode session
- * lifecycle envelopes — handshake / push / consume lifecycle signals
- * that drive the ggui-animator's state machine.
- *
- * Body shape: `CanvasLifecyclePayload` (discriminated on `kind`). The
- * server emits; canvas iframes (subscribed session-wide) consume.
- * Inline iframes (pinned to a single stack item) do not receive
- * envelopes on this channel — delivery is gated by subscription scope.
+ * Body shape: `GguiLifecyclePayload` (discriminated on `kind`). The
+ * server emits; session-wide subscribers consume. Iframes pinned to a
+ * single GguiSession do not receive envelopes on this channel —
+ * delivery is gated by subscription scope.
  *
  * Agent-authored `streamSpec` MUST NOT declare this channel; the
  * structural validator rejects it alongside every other reserved-
@@ -80,7 +100,7 @@ export declare function isKnownReservedChannel(name: string): boolean;
  *
  *   1. `BUILTIN_RESERVED_VALIDATORS` — the PROTOCOL-OWNED payloads.
  *      Shipped in `@ggui-ai/protocol` because the protocol defines the
- *      shape (`ContractErrorPayload` is authored here; the validator
+ *      shape (`GguiLifecyclePayload` is authored here; the validator
  *      belongs here too). Always active, no composition needed.
  *   2. `extraReservedValidators` — INJECTION POINT for payloads whose
  *      shape the protocol does NOT own. Primary consumer today:
@@ -98,29 +118,6 @@ export declare function isKnownReservedChannel(name: string): boolean;
  * composition time.
  */
 export type ReservedChannelValidator = (payload: unknown) => ValidationResult;
-/**
- * Structural validator for {@link ContractErrorPayload} — the body the
- * server emits on `_ggui:contract-error`. PROTOCOL-OWNED shape; ships
- * as a built-in (see {@link BUILTIN_RESERVED_VALIDATORS}).
- *
- * Semantics:
- *   - Payload MUST be a non-null object (arrays rejected).
- *   - Required fields: `toolName: string`, `error.code: string`,
- *     `error.message: string`, `timestamp: string`.
- *   - Optional fields: `actionName: string`, `sourceAction: {type:
- *     string, dispatchedAt: string}`, `error.causedBy: string`,
- *     `schemaVersion: string`.
- *   - `error.code` accepts ANY string — the {@link ContractErrorCode}
- *     type is extensibly-closed per Item 2 (`(string & {})` branch),
- *     so forward-compat codes like `BOOTSTRAP_FAILED` /
- *     `RATE_LIMIT_EXCEEDED` MUST NOT be rejected at this layer.
- *   - `sourceAction.type` accepts ANY string — per F6 extensibility
- *     (`'wired-action' | 'refresh-stream' | (string & {})`).
- *
- * Returns `{valid: true, violations: []}` on conformance. Reject sets
- * `valid: false` with one violation per missing-or-mistyped field.
- */
-export declare function validateContractErrorPayload(payload: unknown): ValidationResult;
 /**
  * The PROTOCOL-OWNED reserved-channel validator registry.
  *
@@ -142,7 +139,7 @@ export declare const BUILTIN_RESERVED_VALIDATORS: ReadonlyMap<string, ReservedCh
 /**
  * Structural validator for {@link LIFECYCLE_CHANNEL} payloads. The
  * wire shape is the closed discriminated union
- * {@link CanvasLifecyclePayload}; we narrow on `kind` and check the
+ * {@link GguiLifecyclePayload}; we narrow on `kind` and check the
  * required fields per variant. Defines the failure mode the protocol
  * bar requires for reserved channels.
  *
@@ -152,5 +149,5 @@ export declare const BUILTIN_RESERVED_VALIDATORS: ReadonlyMap<string, ReservedCh
  *   - unknown `kind` values (closed union — new kinds bump protocol)
  *   - missing or wrong-typed variant-specific fields
  */
-export declare function validateCanvasLifecyclePayload(payload: unknown): ValidationResult;
+export declare function validateGguiLifecyclePayload(payload: unknown): ValidationResult;
 //# sourceMappingURL=reserved-channels.d.ts.map

package/dist/validation/reserved-channels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reserved-channels.d.ts","sourceRoot":"","sources":["../../src/validation/reserved-channels.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAItD,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,gBAAgB,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GACf,gBAAgB,CAuIlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,MAAM,EACN,wBAAwB,CAKxB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,OAAO,GACf,gBAAgB,CA4FlB"}
+{"version":3,"file":"reserved-channels.d.ts","sourceRoot":"","sources":["../../src/validation/reserved-channels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAGtD,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,gBAAgB,CAAC;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,MAAM,EACN,wBAAwB,CAIxB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GACf,gBAAgB,CA4FlB"}

package/dist/validation/reserved-channels.js

@@ -1,3 +1,4 @@
+import { isRecord } from './is-record.js';
 /** Prefix that marks a channel as server-owned (reserved from agents). */
 export const RESERVED_CHANNEL_PREFIX = '_ggui:';
 /**
@@ -8,27 +9,14 @@ export const RESERVED_CHANNEL_PREFIX = '_ggui:';
  */
 export const PREVIEW_CHANNEL = '_ggui:preview';
 /**
- * Reserved channel for canonical contract-error envelopes emitted by
- * the wiredActionRouter. Body shape is `ContractErrorPayload` (see
- * `types/data-contract.ts`). Agent-authored `streamSpec`
- * MUST NOT declare this channel — structural validation rejects it
- * alongside every other reserved-prefix name.
+ * Reserved channel for generation-progress lifecycle envelopes —
+ * handshake / render / consume lifecycle signals that drive
+ * client-side progress indicators.
  *
- * If future work adds richer contract observability (e.g., separate
- * `_ggui:wired-tool-invoked` success trace), each new name joins this
- * module with its own constant and the {@link KNOWN_RESERVED_CHANNELS}
- * set below.
- */
-export const CONTRACT_ERROR_CHANNEL = '_ggui:contract-error';
-/**
- * Reserved channel for canvas-mode session
- * lifecycle envelopes — handshake / push / consume lifecycle signals
- * that drive the ggui-animator's state machine.
- *
- * Body shape: `CanvasLifecyclePayload` (discriminated on `kind`). The
- * server emits; canvas iframes (subscribed session-wide) consume.
- * Inline iframes (pinned to a single stack item) do not receive
- * envelopes on this channel — delivery is gated by subscription scope.
+ * Body shape: `GguiLifecyclePayload` (discriminated on `kind`). The
+ * server emits; session-wide subscribers consume. Iframes pinned to a
+ * single GguiSession do not receive envelopes on this channel —
+ * delivery is gated by subscription scope.
  *
  * Agent-authored `streamSpec` MUST NOT declare this channel; the
  * structural validator rejects it alongside every other reserved-
@@ -51,7 +39,6 @@ export const LIFECYCLE_CHANNEL = '_ggui:lifecycle';
  */
 export const KNOWN_RESERVED_CHANNELS = new Set([
     PREVIEW_CHANNEL,
-    CONTRACT_ERROR_CHANNEL,
     LIFECYCLE_CHANNEL,
 ]);
 /**
@@ -79,155 +66,6 @@ export function isReservedChannelName(name) {
 export function isKnownReservedChannel(name) {
     return KNOWN_RESERVED_CHANNELS.has(name);
 }
-/**
- * Structural validator for {@link ContractErrorPayload} — the body the
- * server emits on `_ggui:contract-error`. PROTOCOL-OWNED shape; ships
- * as a built-in (see {@link BUILTIN_RESERVED_VALIDATORS}).
- *
- * Semantics:
- *   - Payload MUST be a non-null object (arrays rejected).
- *   - Required fields: `toolName: string`, `error.code: string`,
- *     `error.message: string`, `timestamp: string`.
- *   - Optional fields: `actionName: string`, `sourceAction: {type:
- *     string, dispatchedAt: string}`, `error.causedBy: string`,
- *     `schemaVersion: string`.
- *   - `error.code` accepts ANY string — the {@link ContractErrorCode}
- *     type is extensibly-closed per Item 2 (`(string & {})` branch),
- *     so forward-compat codes like `BOOTSTRAP_FAILED` /
- *     `RATE_LIMIT_EXCEEDED` MUST NOT be rejected at this layer.
- *   - `sourceAction.type` accepts ANY string — per F6 extensibility
- *     (`'wired-action' | 'refresh-stream' | (string & {})`).
- *
- * Returns `{valid: true, violations: []}` on conformance. Reject sets
- * `valid: false` with one violation per missing-or-mistyped field.
- */
-export function validateContractErrorPayload(payload) {
-    const violations = [];
-    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
-        return {
-            valid: false,
-            violations: [
-                {
-                    field: 'payload',
-                    message: `${CONTRACT_ERROR_CHANNEL} payload must be a non-null object`,
-                    expected: 'object',
-                    received: payload === null ? 'null' : Array.isArray(payload) ? 'array' : typeof payload,
-                },
-            ],
-        };
-    }
-    const p = payload;
-    // ── Required: toolName ──
-    if (typeof p.toolName !== 'string') {
-        violations.push({
-            field: 'toolName',
-            message: "Required field 'toolName' must be a string",
-            expected: 'string',
-            received: p.toolName === undefined ? 'undefined' : typeof p.toolName,
-        });
-    }
-    // ── Optional: actionName ──
-    if (p.actionName !== undefined && typeof p.actionName !== 'string') {
-        violations.push({
-            field: 'actionName',
-            message: "Optional field 'actionName' must be a string when present",
-            expected: 'string',
-            received: typeof p.actionName,
-        });
-    }
-    // ── Optional: sourceAction ──
-    if (p.sourceAction !== undefined) {
-        if (typeof p.sourceAction !== 'object' ||
-            p.sourceAction === null ||
-            Array.isArray(p.sourceAction)) {
-            violations.push({
-                field: 'sourceAction',
-                message: "Optional field 'sourceAction' must be an object when present",
-                expected: 'object',
-                received: p.sourceAction === null ? 'null' : Array.isArray(p.sourceAction) ? 'array' : typeof p.sourceAction,
-            });
-        }
-        else {
-            const sa = p.sourceAction;
-            if (typeof sa.type !== 'string') {
-                // Accepts any string — extensibility per F6. Type presence is
-                // required, VALUE is open.
-                violations.push({
-                    field: 'sourceAction.type',
-                    message: "Field 'sourceAction.type' must be a string",
-                    expected: 'string',
-                    received: sa.type === undefined ? 'undefined' : typeof sa.type,
-                });
-            }
-            if (typeof sa.dispatchedAt !== 'string') {
-                violations.push({
-                    field: 'sourceAction.dispatchedAt',
-                    message: "Field 'sourceAction.dispatchedAt' must be a string (ISO 8601)",
-                    expected: 'string',
-                    received: sa.dispatchedAt === undefined ? 'undefined' : typeof sa.dispatchedAt,
-                });
-            }
-        }
-    }
-    // ── Required: error.code + error.message ──
-    if (typeof p.error !== 'object' || p.error === null || Array.isArray(p.error)) {
-        violations.push({
-            field: 'error',
-            message: "Required field 'error' must be a non-null object",
-            expected: 'object',
-            received: p.error === undefined ? 'undefined' : p.error === null ? 'null' : Array.isArray(p.error) ? 'array' : typeof p.error,
-        });
-    }
-    else {
-        const err = p.error;
-        if (typeof err.code !== 'string') {
-            // Accepts any string — ContractErrorCode is extensibly-closed per
-            // Item 2. Rejecting by name-set here would force a version bump
-            // every time a new code ships.
-            violations.push({
-                field: 'error.code',
-                message: "Required field 'error.code' must be a string",
-                expected: 'string',
-                received: err.code === undefined ? 'undefined' : typeof err.code,
-            });
-        }
-        if (typeof err.message !== 'string') {
-            violations.push({
-                field: 'error.message',
-                message: "Required field 'error.message' must be a string",
-                expected: 'string',
-                received: err.message === undefined ? 'undefined' : typeof err.message,
-            });
-        }
-        if (err.causedBy !== undefined && typeof err.causedBy !== 'string') {
-            violations.push({
-                field: 'error.causedBy',
-                message: "Optional field 'error.causedBy' must be a string when present",
-                expected: 'string',
-                received: typeof err.causedBy,
-            });
-        }
-    }
-    // ── Required: timestamp ──
-    if (typeof p.timestamp !== 'string') {
-        violations.push({
-            field: 'timestamp',
-            message: "Required field 'timestamp' must be a string (ISO 8601)",
-            expected: 'string',
-            received: p.timestamp === undefined ? 'undefined' : typeof p.timestamp,
-        });
-    }
-    // ── Optional: schemaVersion ──
-    if (p.schemaVersion !== undefined && typeof p.schemaVersion !== 'string') {
-        violations.push({
-            field: 'schemaVersion',
-            message: "Optional field 'schemaVersion' must be a string when present",
-            expected: 'string',
-            received: typeof p.schemaVersion,
-        });
-    }
-    return { valid: violations.length === 0, violations };
-}
 /**
  * The PROTOCOL-OWNED reserved-channel validator registry.
  *
@@ -246,14 +84,13 @@ export function validateContractErrorPayload(payload) {
  * Readonly `ReadonlyMap` so consumers can't mutate the global registry.
  */
 export const BUILTIN_RESERVED_VALIDATORS = new Map([
-    [CONTRACT_ERROR_CHANNEL, validateContractErrorPayload],
-    [LIFECYCLE_CHANNEL, validateCanvasLifecyclePayload],
+    [LIFECYCLE_CHANNEL, validateGguiLifecyclePayload],
     // PREVIEW_CHANNEL intentionally absent — injected at composition time.
 ]);
 /**
  * Structural validator for {@link LIFECYCLE_CHANNEL} payloads. The
  * wire shape is the closed discriminated union
- * {@link CanvasLifecyclePayload}; we narrow on `kind` and check the
+ * {@link GguiLifecyclePayload}; we narrow on `kind` and check the
  * required fields per variant. Defines the failure mode the protocol
  * bar requires for reserved channels.
  *
@@ -263,9 +100,9 @@ export const BUILTIN_RESERVED_VALIDATORS = new Map([
  *   - unknown `kind` values (closed union — new kinds bump protocol)
  *   - missing or wrong-typed variant-specific fields
  */
-export function validateCanvasLifecyclePayload(payload) {
+export function validateGguiLifecyclePayload(payload) {
     const violations = [];
-    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+    if (!isRecord(payload)) {
         return {
             valid: false,
             violations: [
@@ -330,11 +167,11 @@ export function validateCanvasLifecyclePayload(payload) {
             }
             break;
         case 'render_started':
-            requireString('renderId');
+            requireString('sessionId');
             requireString('intent');
             break;
         case 'consume_polling':
-            requireString('renderId');
+            requireString('sessionId');
             if (p.state !== 'open') {
                 violations.push({
                     field: 'state',

package/dist/validation/resolve-stream-channel.d.ts

@@ -23,7 +23,7 @@
  * Returns `undefined` for two distinct cases, both of which are
  * "nothing to enforce" at call sites:
  *
- *   - `spec === undefined` — the stack item has no stream contract.
+ *   - `spec === undefined` — the render has no stream contract.
  *   - `spec.channels[channelName]` is missing — the channel isn't
  *     declared. Callers MUST NOT assume this means "permissive";
  *     rejection is the downstream responsibility of
@@ -53,12 +53,6 @@ export interface ResolvedStreamChannel {
     readonly description?: string;
     /** Optional passthrough — channel's example payload. */
     readonly example?: JsonValue;
-    /** Optional passthrough — refresh tool declared for this channel.
-     * Server-side action dispatch (WS-direct agent-less deployments)
-     * fires this after a wired action succeeds; absence means "no
-     * refresh fires." Distinct from the `source` poll/push feed on
-     * `StreamChannelEntry`. See `StreamChannelEntry.tool`. */
-    readonly tool?: string;
 }
 /**
  * Look up a channel's declared semantics in a {@link StreamSpec} and
@@ -66,8 +60,8 @@ export interface ResolvedStreamChannel {
  * (`mode` / `replay` / `complete`) are filled with their locked
  * defaults.
  *
- * @param spec        The active stack item's stream contract, or undefined
- *                    when the item has no `streamSpec` at all.
+ * @param spec        The active render's stream contract, or undefined
+ *                    when the render has no `streamSpec` at all.
  * @param channelName The channel name to resolve — typically read
  *                    from the outbound envelope's `channel` field.
  * @returns `ResolvedStreamChannel` when the channel is declared;

package/dist/validation/resolve-stream-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-stream-channel.d.ts","sourceRoot":"","sources":["../../src/validation/resolve-stream-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B;;;;8DAI0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAClB,qBAAqB,GAAG,SAAS,CAcnC"}
+{"version":3,"file":"resolve-stream-channel.d.ts","sourceRoot":"","sources":["../../src/validation/resolve-stream-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAClB,qBAAqB,GAAG,SAAS,CAanC"}

package/dist/validation/resolve-stream-channel.js

@@ -23,7 +23,7 @@
  * Returns `undefined` for two distinct cases, both of which are
  * "nothing to enforce" at call sites:
  *
- *   - `spec === undefined` — the stack item has no stream contract.
+ *   - `spec === undefined` — the render has no stream contract.
  *   - `spec.channels[channelName]` is missing — the channel isn't
  *     declared. Callers MUST NOT assume this means "permissive";
  *     rejection is the downstream responsibility of
@@ -37,8 +37,8 @@ import { DEFAULT_STREAM_CHANNEL_COMPLETE, DEFAULT_STREAM_CHANNEL_MODE, DEFAULT_S
  * (`mode` / `replay` / `complete`) are filled with their locked
  * defaults.
  *
- * @param spec        The active stack item's stream contract, or undefined
- *                    when the item has no `streamSpec` at all.
+ * @param spec        The active render's stream contract, or undefined
+ *                    when the render has no `streamSpec` at all.
  * @param channelName The channel name to resolve — typically read
  *                    from the outbound envelope's `channel` field.
  * @returns `ResolvedStreamChannel` when the channel is declared;
@@ -59,6 +59,5 @@ export function resolveStreamChannel(spec, channelName) {
         complete: entry.complete ?? DEFAULT_STREAM_CHANNEL_COMPLETE,
         ...(entry.description !== undefined ? { description: entry.description } : {}),
         ...(entry.example !== undefined ? { example: entry.example } : {}),
-        ...(entry.tool !== undefined ? { tool: entry.tool } : {}),
     };
 }

package/dist/validation/sanitize-error.d.ts

@@ -1,13 +1,13 @@
 /**
- * Patterns stripped from stringified errors before emission on
- * `_ggui:contract-error`. The default set covers the common credential
+ * Patterns stripped from stringified errors before they ride a wire
+ * frame. The default set covers the common credential
  * shapes that show up in stack traces by accident (URLs with token query
  * params, Bearer headers captured by retry libraries, env-var dumps).
  *
  * Each regex replaces the matched span with `[REDACTED]`. Replacement is
  * conservative — we'd rather over-redact than leak. Operators who need
- * finer control inject a custom sanitizer via
- * `createSessionChannelServer({ sanitizeCausedBy })`.
+ * finer control supply a custom {@link SanitizeCausedBy} function (or
+ * pass a stricter pattern set to {@link sanitizeCausedBy}).
  */
 export declare const DEFAULT_CREDENTIAL_PATTERNS: readonly RegExp[];
 /** Default max length for a sanitized `causedBy` string. */
@@ -16,7 +16,8 @@ export declare const DEFAULT_CAUSED_BY_MAX_LENGTH = 2048;
 export declare const TRUNCATION_MARKER = "\n\u2026[truncated]";
 /**
  * Sanitize a stringified error (typically `err.stack`) before it's
- * written to `ContractErrorPayload.error.causedBy`.
+ * written to a wire-visible diagnostic slot (e.g. the `channel_error`
+ * frame's `details`).
  *
  * Applies every pattern in {@link DEFAULT_CREDENTIAL_PATTERNS} in order,
  * replacing matches with `[REDACTED]`. If the result exceeds `maxLength`,
@@ -34,11 +35,11 @@ export declare const TRUNCATION_MARKER = "\n\u2026[truncated]";
  */
 export declare function sanitizeCausedBy(raw: string, maxLength?: number, patterns?: readonly RegExp[]): string;
 /**
- * Signature of the sanitizer hook operators can inject into
- * `createSessionChannelServer`. Receives the raw stringified error
- * (typically `err.stack`) and MUST return a safe-to-emit string.
+ * Signature of a `causedBy` sanitizer hook. Receives the raw
+ * stringified error (typically `err.stack`) and MUST return a
+ * safe-to-emit string.
  *
- * Defaults to {@link sanitizeCausedBy} when no override is supplied. A
+ * {@link sanitizeCausedBy} is the canonical implementation. A
  * pass-through function that returns `raw` unchanged is valid but
  * discouraged — it re-enables the leak this module was added to close.
  */

package/dist/validation/sanitize-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize-error.d.ts","sourceRoot":"","sources":["../../src/validation/sanitize-error.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAWxD,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,wBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,MAAqC,EAChD,QAAQ,GAAE,SAAS,MAAM,EAAgC,GACxD,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC"}
+{"version":3,"file":"sanitize-error.d.ts","sourceRoot":"","sources":["../../src/validation/sanitize-error.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAWxD,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,wBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,MAAqC,EAChD,QAAQ,GAAE,SAAS,MAAM,EAAgC,GACxD,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC"}

package/dist/validation/sanitize-error.js

@@ -1,22 +1,22 @@
 // packages/protocol/src/validation/sanitize-error.ts
 //
-// Credential-leak sanitizer for `ContractErrorPayload.error.causedBy`.
+// Credential-leak sanitizer for stringified errors bound for the wire.
 //
-// The `causedBy` field on a contract-error envelope carries the
-// stringified original error — typically `Error.stack`. Stacks frequently
+// A diagnostic cause string carries the stringified original error —
+// typically `Error.stack`. Stacks frequently
 // contain URLs with query-param tokens (`?token=...`, `?api_key=...`),
 // Authorization header values captured by over-eager logging libraries,
-// and env-var dumps. The envelope flows on the reserved
-// `_ggui:contract-error` channel with `replay: 'all'`, so anything that
-// lands in `causedBy` persists in the session ring buffer and is visible
-// in operator tools (RenderInspector activity panels). If an operator
-// shares a bug report with that data, the credential leaks externally.
+// and env-var dumps. The primary consumer is the live channel's
+// `channel_error` frame: a `POLL_FAILED` emission threads the polled
+// tool's failure into the frame's `details` slot, where it is visible
+// to the subscribed client and in operator tools (RenderInspector
+// activity panels). If an operator shares a bug report with that data,
+// the credential leaks externally.
 //
-// This module's default posture is "sanitize before emission": the
-// session-channel router pipes every `err.stack` through
-// {@link sanitizeCausedBy} before populating `causedBy`. Operators who
-// need stricter sanitization can inject their own function via
-// `createSessionChannelServer({ sanitizeCausedBy })`.
+// This module's default posture is "sanitize before emission": every
+// producer pipes the raw `err.stack` through {@link sanitizeCausedBy}
+// before putting it on the wire. Producers that need stricter
+// sanitization substitute their own {@link SanitizeCausedBy} function.
 //
 // Scope: this is a DEFENSE-IN-DEPTH belt, not the sole line. Libraries
 // that handle secrets should already avoid embedding them in error
@@ -24,15 +24,15 @@
 // opportunistically by code that didn't think about leaking and we'd
 // rather redact conservatively than ship raw stacks.
 /**
- * Patterns stripped from stringified errors before emission on
- * `_ggui:contract-error`. The default set covers the common credential
+ * Patterns stripped from stringified errors before they ride a wire
+ * frame. The default set covers the common credential
  * shapes that show up in stack traces by accident (URLs with token query
  * params, Bearer headers captured by retry libraries, env-var dumps).
  *
  * Each regex replaces the matched span with `[REDACTED]`. Replacement is
  * conservative — we'd rather over-redact than leak. Operators who need
- * finer control inject a custom sanitizer via
- * `createSessionChannelServer({ sanitizeCausedBy })`.
+ * finer control supply a custom {@link SanitizeCausedBy} function (or
+ * pass a stricter pattern set to {@link sanitizeCausedBy}).
  */
 export const DEFAULT_CREDENTIAL_PATTERNS = [
     // Bearer / Basic header values. `Bearer <token>` / `Authorization: Basic <base64>`.
@@ -52,7 +52,8 @@ export const DEFAULT_CAUSED_BY_MAX_LENGTH = 2048;
 export const TRUNCATION_MARKER = '\n…[truncated]';
 /**
  * Sanitize a stringified error (typically `err.stack`) before it's
- * written to `ContractErrorPayload.error.causedBy`.
+ * written to a wire-visible diagnostic slot (e.g. the `channel_error`
+ * frame's `details`).
  *
  * Applies every pattern in {@link DEFAULT_CREDENTIAL_PATTERNS} in order,
  * replacing matches with `[REDACTED]`. If the result exceeds `maxLength`,

package/dist/validation/schema-compat-invariants.d.ts

@@ -131,7 +131,7 @@ export declare class SchemaCompatInvariantError extends Error {
  * agentCapabilities catalog.
  *
  * Slots alongside `assertCrossReferences` + `assertNameInvariants`
- * at push time. Different scope from the server-level
+ * at render time. Different scope from the server-level
  * `SchemaCompatError` thrown by `checkRenderSchemaCompat` in
  * `@ggui-ai/mcp-server`: this check uses ONLY the contract's own
  * catalog; the server-level check uses the runtime tool registry.

package/dist/validation/schema-compat-invariants.js

@@ -88,7 +88,7 @@ export function checkActionSchemaCompat(actionSpec, agentCapabilities) {
         const tool = tools.get(toolName);
         if (!tool)
             continue; // CTR_REF_NEXT_STEP covers this
-        const toolInput = tool.inputSchema;
+        const toolInput = tool.toolInfo.inputSchema;
         if (!toolInput)
             continue; // catalog entry incomplete — no anchor
         const actionSchema = entry.schema ?? {
@@ -143,7 +143,7 @@ export function checkStreamSchemaCompat(streamSpec, agentCapabilities) {
         const tool = tools.get(toolName);
         if (!tool)
             continue; // CTR_REF_STREAM_SOURCE covers this
-        const toolOutput = tool.outputSchema;
+        const toolOutput = tool.toolInfo.outputSchema;
         if (!toolOutput)
             continue;
         const channelSchema = entry.schema;
@@ -207,7 +207,7 @@ export class SchemaCompatInvariantError extends Error {
  * agentCapabilities catalog.
  *
  * Slots alongside `assertCrossReferences` + `assertNameInvariants`
- * at push time. Different scope from the server-level
+ * at render time. Different scope from the server-level
  * `SchemaCompatError` thrown by `checkRenderSchemaCompat` in
  * `@ggui-ai/mcp-server`: this check uses ONLY the contract's own
  * catalog; the server-level check uses the runtime tool registry.