@ggui-ai/protocol 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Loqu, Inc. (Guuey)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,46 @@
+# @ggui-ai/protocol
+
+TypeScript source of truth for the ggui protocol — the open wire format between agents and generated user interfaces. Ships the envelope types (`ActionEnvelope`, `StreamEnvelope`, `ContractErrorPayload`), the canonical error-code union, the WebSocket + MCP transport bindings, and the DTCG design-token contract.
+
+The full normative spec lives at [docs.ggui.ai](https://docs.ggui.ai). This package is what an implementer actually imports.
+
+```bash
+npm install @ggui-ai/protocol
+```
+
+## How the protocol works
+
+An agent declares a contract. A user clicks a button. The right MCP tool runs. No SDK glue.
+
+Here is what happens when a user clicks "Add" on a generated todo UI:
+
+1. **LLM wrote the hook** — `const addTodo = useAction('addTodo');` bound to the button's `onClick`.
+2. **User clicks** — React fires `onClick`, which calls `addTodo(data)`.
+3. **Hook dispatches** — `useAction` (from `@ggui-ai/wire`) sends an `ActionEnvelope` on the live channel.
+4. **WS transport** — the server receives the envelope on the session's live-channel WebSocket.
+5. **Router looks up the tool** — `wiredActionRouter` reads `actionSpec.addTodo.nextStep === 'todo.add'`.
+6. **MCP tool invoked** — the router calls `todo.add` with the validated payload.
+7. **Tool responds** — `todo.add` returns; the response travels back as a `StreamEnvelope` on the live channel.
+8. **UI absorbs the update** — the component's `useStream` callback fires, state updates, no regeneration.
+
+**No SDK glue.** Every step has a named, typed enforcement layer — schema-subset check at push time, `ContractErrorPayload` on `_ggui:contract-error` at runtime, `@ggui-ai/protocol-conformance` at CI time, TypeScript narrowing at author time. Nothing about this pipeline assumes a specific SDK: a third-party implementer honoring the envelope + channel contracts inherits all four enforcement tiers for free.
+
+## Implementer guide
+
+Building a third-party MCP host that renders ggui sessions, a non-React viewer, or any runtime that speaks the ggui wire contract? The implementer guide at [docs.ggui.ai](https://docs.ggui.ai) covers the three-way quickstart (React via `<McpAppIframe>` / vanilla iframe + postMessage / MCP-host install), the full `ProtocolError` recipe with suggested UX per variant, `ObservabilityEvent` kinds, and version negotiation.
+
+## What this package exports
+
+| Surface                                     | What it is                                                       |
+| ------------------------------------------- | ---------------------------------------------------------------- |
+| `@ggui-ai/protocol`                         | Root barrel — envelope types, `StackItem`, `StreamSpec`, actions |
+| `@ggui-ai/protocol/content-hash`            | Deterministic hashing for cache keys                             |
+| `@ggui-ai/protocol/blueprint-key`           | Server-only blueprint cache-key derivation (uses `node:crypto`)  |
+| `@ggui-ai/protocol/transport/websocket`     | Live-channel WS binding — subscribe / ack / resume types         |
+| `@ggui-ai/protocol/integrations/mcp-apps`   | MCP Apps host integration types — bootstrap + lifecycle protocol |
+| `@ggui-ai/protocol/version`                 | Protocol version constant + negotiation helpers                  |
+| `@ggui-ai/protocol/errors/version-mismatch` | Typed error for version-negotiation failures                     |
+
+## License
+
+Apache-2.0.

package/dist/bridge/invoke-agent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent invocation helper for the bridge agent pattern.
+ *
+ * Cloud-provider agnostic — uses standard fetch API. Can be used by any
+ * platform implementation (serverless function, self-hosted server, etc.) that needs
+ * to forward messages to an agent's HTTP endpoint.
+ *
+ * Handles both JSON and SSE streaming responses using stream-parser.
+ */
+import type { InterfaceContext } from '../types/interface-context';
+import type { ConversationTurn } from '../types/session';
+export interface InvokeAgentOptions {
+    /** The agent's HTTP endpoint URL */
+    connectorEndpointUrl: string;
+    /** Session ID (omit for 'start' flow — agent creates session) */
+    sessionId?: string;
+    /** Invocation type: 'start' creates a new session, 'message' continues one */
+    type: 'start' | 'message';
+    /** User message text */
+    message?: string;
+    /** App ID to include in the request */
+    appId: string;
+    /** Client interface context (device, viewport, shell type) */
+    interfaceContext?: InterfaceContext;
+    /** Conversation history for multi-turn context */
+    conversationHistory?: ConversationTurn[];
+    /** Callback to forward streaming text chunks to the user */
+    onStreamChunk?: (text: string) => Promise<void>;
+    /** Callback when the stream is done */
+    onStreamDone?: () => Promise<void>;
+    /** Callback when the agent returns a sessionId (start flow, SSE) */
+    onSessionId?: (sessionId: string) => Promise<void>;
+    /** Callback for structured agent events (stream, push, etc.) from the events array */
+    onAgentEvent?: (event: {
+        type: string;
+        payload: unknown;
+    }) => Promise<void>;
+    /** Request timeout in milliseconds (default: 90000) */
+    timeoutMs?: number;
+}
+export interface InvokeAgentResult {
+    /** Session ID returned by the agent (start flow) */
+    sessionId?: string;
+    /** Full text response (JSON responses only — streaming uses callbacks) */
+    text?: string;
+    /** Whether the response was streamed via SSE */
+    streamed: boolean;
+    /** Outcome status */
+    status: 'ok' | 'error';
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Invoke an agent's HTTP endpoint and handle the response.
+ *
+ * Supports two response formats:
+ *   1. JSON — returns the parsed body as InvokeAgentResult
+ *   2. SSE stream — forwards chunks via callbacks, returns when stream ends
+ *
+ * The request body shape follows the ggui bridge protocol:
+ *   - start:   { type: 'start', message, appId, interfaceContext }
+ *   - message: { type: 'message', sessionId, appId, message, conversationHistory, interfaceContext }
+ */
+export declare function invokeAgentEndpoint(options: InvokeAgentOptions): Promise<InvokeAgentResult>;
+//# sourceMappingURL=invoke-agent.d.ts.map

package/dist/bridge/invoke-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-agent.d.ts","sourceRoot":"","sources":["../../src/bridge/invoke-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAgBzD,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,kDAAkD;IAClD,mBAAmB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACzC,4DAA4D;IAC5D,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,oEAAoE;IACpE,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,EAAE,OAAO,CAAC;IAClB,qBAAqB;IACrB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA4G5B"}

package/dist/bridge/invoke-agent.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { isStreamingContentType } from '../stream/stream-parser.js';
+/** Schema for agent HTTP response data — validates untrusted external input. */
+const agentResponseSchema = z.object({
+    sessionId: z.string().optional(),
+    text: z.string().optional(),
+    events: z.array(z.object({
+        type: z.string(),
+        payload: z.unknown(),
+    }).passthrough()).optional(),
+}).passthrough();
+// ── Implementation ──
+/**
+ * Invoke an agent's HTTP endpoint and handle the response.
+ *
+ * Supports two response formats:
+ *   1. JSON — returns the parsed body as InvokeAgentResult
+ *   2. SSE stream — forwards chunks via callbacks, returns when stream ends
+ *
+ * The request body shape follows the ggui bridge protocol:
+ *   - start:   { type: 'start', message, appId, interfaceContext }
+ *   - message: { type: 'message', sessionId, appId, message, conversationHistory, interfaceContext }
+ */
+export async function invokeAgentEndpoint(options) {
+    const { connectorEndpointUrl, type, appId, sessionId, message, interfaceContext, conversationHistory, onStreamChunk, onStreamDone, onSessionId, timeoutMs = 90_000, } = options;
+    // Build request body based on invocation type
+    const body = { type, appId };
+    if (type === 'start') {
+        if (sessionId)
+            body.sessionId = sessionId;
+        body.message = message || 'Start a new session';
+        if (interfaceContext)
+            body.interfaceContext = interfaceContext;
+    }
+    else {
+        body.sessionId = sessionId;
+        body.message = message;
+        if (interfaceContext)
+            body.interfaceContext = interfaceContext;
+        if (conversationHistory && conversationHistory.length > 0) {
+            body.conversationHistory = conversationHistory;
+        }
+    }
+    // Build headers
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Ggui-App-Id': appId,
+    };
+    if (sessionId) {
+        headers['X-Ggui-Session-Id'] = sessionId;
+    }
+    // POST to agent endpoint
+    let response;
+    try {
+        response = await fetch(connectorEndpointUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : 'Agent invocation failed';
+        return { status: 'error', error: errMsg, streamed: false };
+    }
+    if (!response.ok) {
+        return {
+            status: 'error',
+            error: `Agent returned ${response.status}`,
+            streamed: false,
+        };
+    }
+    // Determine response format
+    const contentType = response.headers.get('content-type') || '';
+    const transferEncoding = response.headers.get('transfer-encoding') || '';
+    // Read the full response body (SSE or JSON)
+    const responseText = await response.text();
+    // Parse the response — handle SSE format (strip `data: ` prefix)
+    let agentData;
+    try {
+        // SSE responses have `data: {...}` lines
+        const lines = responseText.split('\n').filter(l => l.startsWith('data: '));
+        const raw = lines.length > 0
+            ? JSON.parse(lines[lines.length - 1].slice(6).trim())
+            : JSON.parse(responseText);
+        agentData = agentResponseSchema.parse(raw);
+    }
+    catch {
+        // Couldn't parse or validate — forward raw text
+        await onStreamChunk?.(responseText);
+        await onStreamDone?.();
+        return { status: 'ok', streamed: true };
+    }
+    // Extract sessionId
+    if (agentData.sessionId) {
+        await onSessionId?.(agentData.sessionId);
+    }
+    // Forward structured agent events
+    if (agentData.events && options.onAgentEvent) {
+        for (const event of agentData.events) {
+            await options.onAgentEvent(event);
+        }
+    }
+    // Extract text for conversation history
+    const resultText = agentData.text;
+    await onStreamDone?.();
+    return {
+        sessionId: agentData.sessionId,
+        text: resultText,
+        status: 'ok',
+        streamed: isStreamingContentType(contentType, transferEncoding),
+    };
+}

package/dist/envelope-adapters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Envelope adapters — storage-side helpers for the consume pipe.
+ *
+ * `PendingEvent.envelope` carries the per-gesture {@link ConsumeEventEntry}
+ * row written by `submit_action`'s `kind:"dispatch"` branch. Storage is
+ * single-shaped (the same shape `ggui_consume` returns verbatim on drain).
+ *
+ * The only bounded adapter that lives here now is
+ * {@link parsePendingEnvelope} — a shape-neutral reader for stored
+ * `PendingEvent.envelope` values that may arrive as raw objects (direct
+ * DDB writes) or as JSON strings (AppSync `a.json()` semantics).
+ */
+import type { ConsumeEventEntry } from './types/mcp';
+/**
+ * Parse a {@link PendingEvent.envelope} that may arrive as either a raw
+ * object (direct DDB writes) or a JSON-stringified object (AppSync
+ * `a.json()` semantics). Returns the parsed entry unchanged when
+ * already an object.
+ *
+ * Throws `SyntaxError` when a string input is malformed JSON. Does NOT
+ * validate the entry shape — that's the caller's job.
+ */
+export declare function parsePendingEnvelope(stored: ConsumeEventEntry | string): ConsumeEventEntry;
+//# sourceMappingURL=envelope-adapters.d.ts.map

package/dist/envelope-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-adapters.d.ts","sourceRoot":"","sources":["../src/envelope-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GACjC,iBAAiB,CAGnB"}

package/dist/envelope-adapters.js

@@ -0,0 +1,14 @@
+/**
+ * Parse a {@link PendingEvent.envelope} that may arrive as either a raw
+ * object (direct DDB writes) or a JSON-stringified object (AppSync
+ * `a.json()` semantics). Returns the parsed entry unchanged when
+ * already an object.
+ *
+ * Throws `SyntaxError` when a string input is malformed JSON. Does NOT
+ * validate the entry shape — that's the caller's job.
+ */
+export function parsePendingEnvelope(stored) {
+    if (typeof stored !== 'string')
+        return stored;
+    return JSON.parse(stored);
+}

package/dist/envelopes/builders.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Central envelope builders — single stamp point for `schemaVersion`
+ * across every producer path.
+ *
+ * **Why centralize.** The `schemaVersion` forward-compat stamp is
+ * emitted from many producer sites (wire helper, React-SDK emit
+ * paths, OSS in-memory stream buffer, session-channel contract-error
+ * router, hosted server paths). Spreading stamp logic across N sites
+ * causes drift — producers silently skip the stamp. These builders
+ * remove the drift surface by giving every producer a single function
+ * to call; the default stamp happens inside the builder.
+ *
+ * **Override semantics.** Each builder accepts `schemaVersion` in the
+ * input object:
+ *
+ *   - **Key omitted** → the builder stamps {@link PROTOCOL_SCHEMA_VERSION}.
+ *   - **Explicit string** → used as-is (cross-version test scenarios,
+ *     replay fidelity when forwarding an already-stamped envelope).
+ *   - **Explicit `undefined`** (`makeXxx({ schemaVersion: undefined,
+ *     ... })`) → the builder OMITS the field entirely (no
+ *     `schemaVersion` key on the returned envelope). This is a
+ *     test-only pattern used by consumer-side tests that assert
+ *     behavior when the field is absent on the wire. Production
+ *     producers MUST NOT pass `undefined` explicitly.
+ *
+ * Key-present-vs-absent is distinguished via the `in` operator —
+ * `'schemaVersion' in parts` is `true` iff the caller wrote the key,
+ * even as `undefined`. The builders rely on that distinction so the
+ * test-only omit path does not require a separate escape-hatch flag.
+ *
+ * **Exactly which key is set** matters. The builder omits `undefined`
+ * optional fields entirely (it does not emit `{key: undefined}`) so
+ * that `JSON.stringify` produces the same bytes as the old manual
+ * `if (x !== undefined) envelope.x = x` pattern — byte-equivalence
+ * with every pre-refactor stamp site is a load-bearing claim of the
+ * centralization.
+ *
+ * **Scope.** These builders stamp and shape; they do NOT validate.
+ * Validators live in `@ggui-ai/protocol/validation/*`. The division
+ * is deliberate: stamping is part of the wire-shape contract (a
+ * producer obligation), validation is part of the behavior contract
+ * (an observable-violation obligation). Keeping them separate keeps
+ * each module's surface narrow.
+ *
+ * @see PROTOCOL_SCHEMA_VERSION on `@ggui-ai/protocol`
+ */
+import type { ActionEnvelope, EventType } from '../types/events.js';
+import type { ErrorPayload, StreamEnvelope } from '../types/live-channel.js';
+import type { ContractErrorCode, ContractErrorPayload, JsonValue, StreamChannelMode } from '../types/data-contract.js';
+/** Input type for {@link makeActionEnvelope}. */
+export interface MakeActionEnvelopeInput<TPayload = JsonValue> {
+    readonly sessionId: string;
+    readonly type: EventType;
+    readonly payload?: TPayload;
+    readonly stackIndex?: number;
+    readonly stackItemId?: string;
+    readonly clientSeq?: number;
+    /**
+     * `schemaVersion` override. See the module docstring for the three
+     * semantic paths (omit key → default stamp; pass string → stamp
+     * that value; pass explicit `undefined` → omit stamp entirely —
+     * test-only).
+     */
+    readonly schemaVersion?: string;
+}
+/** Input type for {@link makeStreamEnvelope}. */
+export interface MakeStreamEnvelopeInput {
+    readonly sessionId: string;
+    readonly channel: string;
+    readonly mode: StreamChannelMode;
+    readonly payload: JsonValue;
+    readonly complete?: boolean;
+    readonly seq?: number;
+    /** See {@link MakeActionEnvelopeInput.schemaVersion}. */
+    readonly schemaVersion?: string;
+}
+/** Input type for {@link makeErrorPayload}. */
+export interface MakeErrorPayloadInput {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: JsonValue;
+}
+/** Input type for {@link makeContractErrorPayload}. */
+export interface MakeContractErrorPayloadInput {
+    readonly toolName: string;
+    readonly actionName?: string;
+    readonly sourceAction?: {
+        readonly type: 'wired-action' | 'refresh-stream' | (string & {});
+        readonly dispatchedAt: string;
+    };
+    readonly error: {
+        readonly code: ContractErrorCode;
+        readonly message: string;
+        readonly causedBy?: string;
+    };
+    readonly timestamp: string;
+    /** See {@link MakeActionEnvelopeInput.schemaVersion}. */
+    readonly schemaVersion?: string;
+}
+/**
+ * Build an {@link ActionEnvelope} with `schemaVersion` stamped to
+ * {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
+ *
+ * Filters `undefined` optional fields so the serialized wire message
+ * omits them (matches the producer convention that "absent field =
+ * default").
+ */
+export declare function makeActionEnvelope<TPayload = JsonValue>(parts: MakeActionEnvelopeInput<TPayload>): ActionEnvelope<TPayload>;
+/**
+ * Build a {@link StreamEnvelope} with `schemaVersion` stamped to
+ * {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
+ *
+ * Filters `undefined` optional fields (`complete`, `seq`) so the
+ * serialized wire message omits them. `seq` is server-assigned in
+ * practice — callers pass the value the buffer hands them.
+ */
+export declare function makeStreamEnvelope(parts: MakeStreamEnvelopeInput): StreamEnvelope;
+/**
+ * Build an {@link ErrorPayload} for the `{type: 'error'}` wire frame.
+ *
+ * Does NOT stamp `schemaVersion` — `ErrorPayload` is the wire-level
+ * error envelope (free-form `code: string`), not an envelope that
+ * opts into the forward-compat stamp (see {@link ActionEnvelope} /
+ * {@link StreamEnvelope} / {@link ContractErrorPayload}). Keeping
+ * `ErrorPayload` stamp-free preserves byte-equivalence with every
+ * existing server-side error emission that pre-dates the central
+ * builders.
+ *
+ * The builder exists so first-party subscribe / handshake paths emit
+ * canonical codes (e.g. `UPGRADE_REQUIRED`) via a single helper
+ * instead of spreading `{code, message}` object literals. `details`
+ * is filtered when `undefined` so the serialized frame matches the
+ * pre-builder `{code, message}` shape byte-for-byte.
+ */
+export declare function makeErrorPayload(parts: MakeErrorPayloadInput): ErrorPayload;
+/**
+ * Build a {@link ContractErrorPayload} with `schemaVersion` stamped
+ * to {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
+ *
+ * Filters `undefined` optional fields so the emitted payload keeps
+ * byte-equivalence with the pre-refactor session-channel router
+ * code.
+ */
+export declare function makeContractErrorPayload(parts: MakeContractErrorPayloadInput): ContractErrorPayload;
+//# sourceMappingURL=builders.d.ts.map

package/dist/envelopes/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/envelopes/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAGnC,iDAAiD;AACjD,MAAM,WAAW,uBAAuB,CAAC,QAAQ,GAAG,SAAS;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAmBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAG,SAAS,EACrD,KAAK,EAAE,uBAAuB,CAAC,QAAQ,CAAC,GACvC,cAAc,CAAC,QAAQ,CAAC,CAY1B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,cAAc,CAYhB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,oBAAoB,CAatB"}