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

package/dist/ggui-session-channel/outbound.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Outbound send / fan-out family for the live channel — the wire-write
+ * primitives every handler module shares (`send`, `sendError`,
+ * `sendChannelError`) plus the public fan-out surfaces
+ * (`sendToGguiSession`, `notifyGguiSessionCommit`, `sendPropsUpdate`,
+ * `sendDrainAck`, `externalBroadcast`) the channel server object
+ * delegates to.
+ *
+ * The behavior contracts for the public surfaces (validation posture,
+ * replay-buffer stamping, best-effort delivery) are documented on the
+ * `GguiSessionChannelServer` interface in `../ggui-session-channel.ts`;
+ * inline comments here cover impl-level decisions only.
+ */
+import type { GguiSessionStore, GguiSessionStreamBuffer, StreamEnvelopeInput, StreamFanout } from "@ggui-ai/mcp-server-core";
+import type { ErrorPayload, GguiSession, JsonObject, ReservedChannelValidator } from "@ggui-ai/protocol";
+import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
+import type { WebSocket } from "ws";
+import type { Logger } from "../logger.js";
+import type { Subscriber } from "./internal-types.js";
+/** Channel-scoped error codes carried on `channel_error` frames. */
+export type ChannelErrorCode = "CHANNEL_UNKNOWN" | "CHANNEL_NOT_LOCAL" | "SESSION_NOT_FOUND" | "SUBSCRIBE_UNAUTHORIZED" | "POLL_FAILED";
+export interface OutboundDeps {
+    readonly logger: Logger;
+    /** GguiSession backing store — streamSpec lookups for fan-out validation. */
+    readonly renderStore: GguiSessionStore;
+    /** Replay buffer — owns seq assignment + bounded replay storage. */
+    readonly streamBuffer: GguiSessionStreamBuffer;
+    /** Live-tail pub/sub seam for stream-envelope fan-out. */
+    readonly streamFanout: StreamFanout;
+    /**
+     * Flat set of all live WS subscribers — shared with the
+     * subscriber-lifecycle module (which owns membership); read-only
+     * here. Direct-to-WS frames (`props_update`, `render`, `drain_ack`,
+     * external broadcasts) iterate + filter by `sessionId`.
+     */
+    readonly wsSubscribers: ReadonlySet<Subscriber>;
+    /**
+     * Reserved-channel payload validators threaded from
+     * `GguiSessionChannelOptions.extraReservedValidators` — consulted by
+     * `assertStreamContract` ahead of the protocol built-ins.
+     */
+    readonly extraReservedValidators?: ReadonlyMap<string, ReservedChannelValidator>;
+}
+/** The send/fan-out helpers, bound to one channel instance. */
+export interface Outbound {
+    /** Low-level wire write — skips closed sockets, warn-logs send failures. */
+    send(ws: WebSocket, msg: WebSocketMessage): void;
+    /** Emit an `error` frame with the canonical payload shape. */
+    sendError(ws: WebSocket, code: string, message: string, requestId?: string, details?: ErrorPayload["details"]): void;
+    /**
+     * Emit a `channel_error` frame to a specific subscriber. Used by the
+     * `channel_subscribe` handler for both subscribe-time rejections
+     * (`CHANNEL_UNKNOWN`, `CHANNEL_NOT_LOCAL`, `SESSION_NOT_FOUND`,
+     * `SUBSCRIBE_UNAUTHORIZED`) AND poll-time failures (`POLL_FAILED`).
+     *
+     * Direct-to-WS, not via fanOut — channel_error frames are
+     * per-subscriber and not stored in the replay buffer. A new
+     * subscriber on the same render will re-subscribe and discover the
+     * same error itself.
+     */
+    sendChannelError(ws: WebSocket, sessionId: string, channelName: string, code: ChannelErrorCode, message: string, requestId?: string, details?: ErrorPayload["details"]): void;
+    /** Impl behind {@link GguiSessionChannelServer.sendToGguiSession}. */
+    sendToGguiSession(delivery: StreamEnvelopeInput): Promise<{
+        seq: number;
+    }>;
+    /** Impl behind {@link GguiSessionChannelServer.notifyGguiSessionCommit}. */
+    notifyGguiSessionCommit(sessionId: string, render: GguiSession, matchType?: string): void;
+    /** Impl behind {@link GguiSessionChannelServer.sendPropsUpdate}. */
+    sendPropsUpdate(sessionId: string, props: JsonObject): Promise<void>;
+    /** Impl behind {@link GguiSessionChannelServer.sendDrainAck}. */
+    sendDrainAck(args: {
+        readonly sessionId: string;
+        readonly appId: string;
+        readonly eventId: string;
+        readonly drainedAt: string;
+    }): void;
+    /** Impl behind {@link GguiSessionChannelServer.externalBroadcast}. */
+    externalBroadcast(sessionId: string, frame: WebSocketMessage): void;
+}
+export declare function createOutbound(deps: OutboundDeps): Outbound;
+//# sourceMappingURL=outbound.d.ts.map

package/dist/ggui-session-channel/outbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/outbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,wBAAwB,EAEzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,GACxB,aAAa,CAAC;AAElB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;IAC/C,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CAClF;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjD,8DAA8D;IAC9D,SAAS,CACP,EAAE,EAAE,SAAS,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,GAChC,IAAI,CAAC;IACR;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,EAAE,EAAE,SAAS,EACb,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,GAChC,IAAI,CAAC;IACR,sEAAsE;IACtE,iBAAiB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,4EAA4E;IAC5E,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1F,oEAAoE;IACpE,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,iEAAiE;IACjE,YAAY,CAAC,IAAI,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,GAAG,IAAI,CAAC;IACT,sEAAsE;IACtE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACrE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAsM3D"}

package/dist/ggui-session-channel/outbound.js

@@ -0,0 +1,174 @@
+/**
+ * Outbound send / fan-out family for the live channel — the wire-write
+ * primitives every handler module shares (`send`, `sendError`,
+ * `sendChannelError`) plus the public fan-out surfaces
+ * (`sendToGguiSession`, `notifyGguiSessionCommit`, `sendPropsUpdate`,
+ * `sendDrainAck`, `externalBroadcast`) the channel server object
+ * delegates to.
+ *
+ * The behavior contracts for the public surfaces (validation posture,
+ * replay-buffer stamping, best-effort delivery) are documented on the
+ * `GguiSessionChannelServer` interface in `../ggui-session-channel.ts`;
+ * inline comments here cover impl-level decisions only.
+ */
+import { assertStreamContract } from "@ggui-ai/mcp-server-handlers/renders";
+export function createOutbound(deps) {
+    function send(ws, msg) {
+        if (ws.readyState !== ws.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify(msg));
+        }
+        catch (err) {
+            deps.logger.warn("render_channel_send_failed", { error: String(err) });
+        }
+    }
+    function sendError(ws, code, message, requestId, details) {
+        send(ws, {
+            type: "error",
+            payload: { code, message, ...(details !== undefined ? { details } : {}) },
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    function sendChannelError(ws, sessionId, channelName, code, message, requestId, details) {
+        send(ws, {
+            type: "channel_error",
+            payload: {
+                sessionId,
+                channelName,
+                code,
+                message,
+                ...(details !== undefined ? { details } : {}),
+            },
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    /**
+     * Stamp a delivery through the replay buffer and fan it out to every
+     * subscriber of the render, honoring the per-subscriber replay
+     * cursor. Backs the public `sendToGguiSession` entry point.
+     *
+     * Caller is responsible for validating `delivery.payload` against
+     * the active streamSpec BEFORE calling — the fan-out here trusts
+     * its input. Reserved-channel deliveries (e.g. `_ggui:lifecycle`)
+     * bypass the streamSpec check upstream via
+     * `assertStreamContract`.
+     */
+    async function fanOut(delivery, activeStreamSpec) {
+        const { envelope } = await deps.streamBuffer.record(delivery, activeStreamSpec);
+        // Publish to the seam — InProcessStreamFanout walks its subscriber
+        // queues synchronously inside publish(), so no real async hop. The
+        // pump loop on each WS subscriber yields the envelope, applies the
+        // per-sub replay-cursor filter, and sends to the WS. Fire-and-forget
+        // because publish() never throws on the in-process impl, and an
+        // external pubsub-fanout failure here would already be persisted to
+        // the GguiSessionStreamBuffer for replay-recovery on reconnect.
+        void deps.streamFanout.publish({ sessionId: envelope.sessionId, envelope });
+        return { seq: envelope.seq };
+    }
+    async function sendToGguiSession(delivery) {
+        // Outbound fan-out enforcement (defense-in-depth parity with
+        // hosted `handle-data.ts`). Re-validates the delivery's payload
+        // against the render's streamSpec BEFORE delivery — so a future
+        // OSS mutation handler that bypasses the emit-side check can't
+        // fan out malformed data to subscribers. Throws
+        // ContractViolationError{tool:'ggui_emit'} on violation;
+        // caller decides what to do (log, rethrow, wrap).
+        const stored = await deps.renderStore.get(delivery.sessionId);
+        const activeEntry = stored?.render;
+        const streamSpec = activeEntry !== undefined && activeEntry.type !== "mcpApps" && activeEntry.type !== "system"
+            ? activeEntry.streamSpec
+            : undefined;
+        assertStreamContract(streamSpec, delivery.channel, delivery.payload, deps.extraReservedValidators);
+        return fanOut(delivery, streamSpec);
+    }
+    function notifyGguiSessionCommit(sessionId, render, matchType) {
+        // Best-effort fan-out to every live subscriber bound to this
+        // render. NOT routed through the replay buffer — see the
+        // `notifyGguiSessionCommit` JSDoc on the public interface for why
+        // fresh subscribers rely on `ack.render` instead of a replay frame.
+        // NOT routed through StreamFanout either — `type: 'render'` is a
+        // distinct WebSocket message type. Filter the flat WS-subscriber
+        // set by sessionId; N is typically 1-2 (multi-tab render sharing).
+        const payload = matchType !== undefined ? { session: render, matchType } : { session: render };
+        for (const sub of deps.wsSubscribers) {
+            if (sub.sessionId !== sessionId)
+                continue;
+            send(sub.ws, { type: "render", payload });
+        }
+    }
+    /**
+     * Best-effort + orphan-tolerant per the docstring on the public
+     * `sendPropsUpdate` method.
+     */
+    async function sendPropsUpdate(sessionId, props) {
+        let stored;
+        try {
+            stored = await deps.renderStore.get(sessionId);
+        }
+        catch (err) {
+            deps.logger.warn("render_channel_props_update_lookup_failed", {
+                sessionId,
+                error: String(err),
+            });
+            return;
+        }
+        if (!stored) {
+            deps.logger.warn("render_channel_props_update_orphan", {
+                sessionId,
+            });
+            return;
+        }
+        // Filter the flat WS-subscriber set by sessionId; same posture as
+        // `notifyGguiSessionCommit`. `send()` already silently skips closed sockets
+        // and logs (but doesn't throw on) per-subscriber send failures, so
+        // the calling handler can't be made to fail by a dead WebSocket.
+        for (const sub of deps.wsSubscribers) {
+            if (sub.sessionId !== sessionId)
+                continue;
+            send(sub.ws, {
+                type: "props_update",
+                payload: { sessionId, props },
+            });
+        }
+    }
+    function sendDrainAck({ sessionId, appId, eventId, drainedAt, }) {
+        // Server-side fan-out for the action-drain ack.
+        // Filter the flat WS-subscriber set by sessionId (same posture
+        // as `sendPropsUpdate`). No persistence; subscribers that
+        // missed the frame fall back to their 10s claim timer, which
+        // the atomic pop resolves cleanly.
+        for (const sub of deps.wsSubscribers) {
+            if (sub.sessionId !== sessionId)
+                continue;
+            send(sub.ws, {
+                type: "drain_ack",
+                payload: { sessionId, appId, eventId, drainedAt },
+            });
+        }
+    }
+    function externalBroadcast(sessionId, frame) {
+        // Walk the flat subscriber set; filter to matching sessionId.
+        // `send()` already guards closed sockets and logs (but doesn't
+        // throw on) per-subscriber failures, so the caller (an external
+        // pubsub on-message handler) can't be made to fail by a dead
+        // WebSocket. No GguiSessionStore lookup — the publisher already
+        // validated; this seam is the cross-process delivery path, not
+        // the re-validation point.
+        for (const sub of deps.wsSubscribers) {
+            if (sub.sessionId !== sessionId)
+                continue;
+            send(sub.ws, frame);
+        }
+    }
+    return {
+        send,
+        sendError,
+        sendChannelError,
+        sendToGguiSession,
+        notifyGguiSessionCommit,
+        sendPropsUpdate,
+        sendDrainAck,
+        externalBroadcast,
+    };
+}

package/dist/ggui-session-channel/socket-router.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-socket message routing + WS lifecycle wiring for the live
+ * channel — the `connection` handler (with the per-socket inbound
+ * ordering chain), the pre-subscribe identity / cookie bindings, the
+ * `onMessage` type dispatcher, and the observation-message ingress
+ * (`host_context_observed`) it routes.
+ */
+import type { GguiSessionStore } from "@ggui-ai/mcp-server-core";
+import type { WebSocket, WebSocketServer } from "ws";
+import type { Logger } from "../logger.js";
+import type { ActionIngress } from "./action-ingress.js";
+import type { ChannelSubscriptions } from "./channel-subscriptions.js";
+import type { Subscriber } from "./internal-types.js";
+import type { Outbound } from "./outbound.js";
+import type { SubscribeHandlers } from "./subscribe.js";
+import type { SubscriberLifecycle } from "./subscriber-lifecycle.js";
+export interface SocketRouterDeps {
+    readonly logger: Logger;
+    /** GguiSession backing store — observation-message patches persist here. */
+    readonly renderStore: GguiSessionStore;
+    /** ws → subscriber reverse index — the dispatcher's per-frame lookup. */
+    readonly subscribersByWs: WeakMap<WebSocket, Subscriber>;
+    readonly send: Outbound["send"];
+    readonly sendError: Outbound["sendError"];
+    readonly unregister: SubscriberLifecycle["unregister"];
+    readonly handleSubscribe: SubscribeHandlers["handleSubscribe"];
+    readonly handleInboundAction: ActionIngress["handleInboundAction"];
+    readonly handleChannelSubscribe: ChannelSubscriptions["handleChannelSubscribe"];
+    readonly handleChannelUnsubscribe: ChannelSubscriptions["handleChannelUnsubscribe"];
+}
+/**
+ * Wire the channel's `connection` handling onto `wss`. Reads the
+ * upgrade-time identity / cookie bindings the upgrade phase stashed on
+ * the request (see {@link UpgradeBindings}) and serializes inbound
+ * frame processing per socket.
+ */
+export declare function attachSocketRouter(wss: WebSocketServer, deps: SocketRouterDeps): void;
+//# sourceMappingURL=socket-router.d.ts.map

package/dist/ggui-session-channel/socket-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-router.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/socket-router.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAInF,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IACvD,QAAQ,CAAC,eAAe,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IAC/D,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;IACnE,QAAQ,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,wBAAwB,CAAC,CAAC;IAChF,QAAQ,CAAC,wBAAwB,EAAE,oBAAoB,CAAC,0BAA0B,CAAC,CAAC;CACrF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAkQrF"}

package/dist/ggui-session-channel/socket-router.js

@@ -0,0 +1,213 @@
+/**
+ * Per-socket message routing + WS lifecycle wiring for the live
+ * channel — the `connection` handler (with the per-socket inbound
+ * ordering chain), the pre-subscribe identity / cookie bindings, the
+ * `onMessage` type dispatcher, and the observation-message ingress
+ * (`host_context_observed`) it routes.
+ */
+/**
+ * Wire the channel's `connection` handling onto `wss`. Reads the
+ * upgrade-time identity / cookie bindings the upgrade phase stashed on
+ * the request (see {@link UpgradeBindings}) and serializes inbound
+ * frame processing per socket.
+ */
+export function attachSocketRouter(wss, deps) {
+    /**
+     * Tenancy guard for client-emitted observation messages
+     * (`host_context_observed` today). Returns `false`
+     * AND emits the appropriate error frame when:
+     *
+     *   - the socket has no bound subscriber (NOT_SUBSCRIBED)
+     *   - payload.sessionId doesn't match the subscriber binding
+     *     (SESSION_MISMATCH)
+     *
+     * Subscriber binding is the authoritative tenancy scope. The wire
+     * payload's sessionId is belt-and-suspenders so the error message
+     * can be specific; appId narrows transparently via the binding.
+     */
+    function checkSubscriberTenancy(ws, sub, payload, messageType, requestId) {
+        if (!sub) {
+            deps.sendError(ws, "NOT_SUBSCRIBED", `Send a 'subscribe' message first before '${messageType}'`, requestId);
+            return false;
+        }
+        if (payload.sessionId !== sub.sessionId) {
+            deps.sendError(ws, "SESSION_MISMATCH", `${messageType} payload id '${payload.sessionId ?? "<missing>"}' does not match subscriber render '${sub.sessionId}'`, requestId);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Persist an observation-message-driven render patch. Fire-and-
+     * forget at the wire layer (no response frame); warn-logs persistence
+     * errors so transient store failures stay observable without
+     * disrupting the iframe. The iframe's local state is already in the
+     * new shape; the next round-trip re-emits whatever the persistence
+     * layer lost.
+     */
+    async function applyGguiSessionPatch(sessionId, appId, messageType, patch) {
+        try {
+            await deps.renderStore.update(sessionId, patch);
+        }
+        catch (err) {
+            deps.logger.warn("render_channel_observation_persist_failed", {
+                messageType,
+                sessionId,
+                appId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    async function onMessage(ws, raw) {
+        const sub = deps.subscribersByWs.get(ws);
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            deps.sendError(ws, "INVALID_JSON", "Message is not valid JSON");
+            return;
+        }
+        if (!message || typeof message !== "object" || typeof message.type !== "string") {
+            deps.sendError(ws, "INVALID_MESSAGE", "Message is missing a `type` discriminator");
+            return;
+        }
+        switch (message.type) {
+            case "subscribe": {
+                // `subscribe` is the only message allowed before identity is
+                // bound to a render. Identity was already resolved at upgrade
+                // time; we just need to register the subscriber.
+                const identity = pendingIdentity.get(ws);
+                if (!identity) {
+                    deps.sendError(ws, "UNAUTHENTICATED", "No identity bound to this socket", message.requestId);
+                    return;
+                }
+                // Cookie-scope enforcement: when the upgrade was authenticated
+                // via an console cookie, the subscribe payload MUST target
+                // the render the cookie was issued for. A valid cookie for
+                // render A can't be used to open render B.
+                const cookieBound = pendingCookieBinding.get(ws);
+                if (cookieBound) {
+                    if (message.payload.sessionId !== cookieBound.sessionId) {
+                        deps.sendError(ws, "DEVTOOL_COOKIE_SESSION_MISMATCH", `Embedded-ui cookie is bound to render '${cookieBound.sessionId}' but subscribe targets '${message.payload.sessionId}'`, message.requestId);
+                        return;
+                    }
+                    // `appId` is optional on the wire (SPEC §12.2): absent
+                    // resolves to the cookie's bound appId inside
+                    // `handleSubscribe` — only a PRESENT contradicting value is
+                    // a mismatch.
+                    if (message.payload.appId !== undefined && message.payload.appId !== cookieBound.appId) {
+                        deps.sendError(ws, "DEVTOOL_COOKIE_APP_MISMATCH", `Embedded-ui cookie is bound to app '${cookieBound.appId}' but subscribe targets '${message.payload.appId}'`, message.requestId);
+                        return;
+                    }
+                }
+                await deps.handleSubscribe(ws, identity, message, cookieBound);
+                pendingIdentity.delete(ws);
+                pendingCookieBinding.delete(ws);
+                return;
+            }
+            case "ping":
+                deps.send(ws, {
+                    type: "pong",
+                    payload: {},
+                    ...(message.requestId ? { requestId: message.requestId } : {}),
+                });
+                return;
+            case "action":
+                if (!sub) {
+                    deps.sendError(ws, "NOT_SUBSCRIBED", "Send a 'subscribe' message first before 'action'", message.requestId);
+                    return;
+                }
+                await deps.handleInboundAction(ws, sub, message);
+                return;
+            case "channel_subscribe":
+                if (!sub) {
+                    deps.sendError(ws, "NOT_SUBSCRIBED", "Send a 'subscribe' message first before 'channel_subscribe'", message.requestId);
+                    return;
+                }
+                await deps.handleChannelSubscribe(ws, sub, message);
+                return;
+            case "channel_unsubscribe":
+                if (!sub) {
+                    // No subscriber → nothing was subscribed → no-op silently.
+                    // Returning an error would leak "is this socket subscribed"
+                    // state for unauthenticated clients.
+                    return;
+                }
+                deps.handleChannelUnsubscribe(ws, sub, message);
+                return;
+            case "host_context_observed":
+                // The iframe-runtime echoes its captured `McpUiHostContext`
+                // after `ui/initialize` resolves and on every
+                // `ui/notifications/host-context-changed` notification. Persist
+                // on `GguiSession.hostContext` so `ggui_handshake` and
+                // `ggui_consume` can surface it to the agent on subsequent
+                // turns. Fire-and-forget on the client side; no response.
+                if (!checkSubscriberTenancy(ws, sub, message.payload, message.type, message.requestId)) {
+                    return;
+                }
+                await applyGguiSessionPatch(sub.sessionId, sub.appId, message.type, {
+                    hostContext: message.payload.hostContext,
+                    lastActivityAt: Date.now(),
+                });
+                return;
+            default:
+                deps.sendError(ws, "UNSUPPORTED_MESSAGE", `Unsupported message type: ${String(message.type)}`, message.requestId);
+        }
+    }
+    /**
+     * During the pre-subscribe window, a ws has a resolved identity but
+     * no render-bound subscriber yet. We hold the identity here until
+     * the first `subscribe` lands; once it does, the subscriber record
+     * owns the identity and this entry is cleared.
+     */
+    const pendingIdentity = new WeakMap();
+    /**
+     * Embedded-ui cookie binding established at upgrade. When present,
+     * `handleSubscribe` enforces `subscribe.sessionId === bound.sessionId`
+     * so a valid cookie can't be used to open a render it wasn't
+     * issued for. Parallel to {@link pendingIdentity} — same lifetime,
+     * same WeakMap rationale.
+     */
+    const pendingCookieBinding = new WeakMap();
+    wss.on("connection", (ws, req) => {
+        // Bind the resolved identity from the upgrade phase. It was
+        // attached to the request object in handleUpgrade.
+        const identity = req.__gguiIdentity;
+        if (identity)
+            pendingIdentity.set(ws, identity);
+        // Likewise for any cookie binding.
+        const cookieBound = req.__gguiCookieBound;
+        if (cookieBound)
+            pendingCookieBinding.set(ws, cookieBound);
+        // Per-socket inbound processing chain. The WebSocket wire is an
+        // ORDERED frame stream, so inbound handling must observe arrival
+        // order even though the handlers are async: without the chain, a
+        // client that pipelines `subscribe` + `action` in one TCP segment
+        // (both `message` events fire in the same macrotask) gets the
+        // action handled while `handleSubscribe` is parked at its first
+        // `await` — the socket has no bound subscriber yet, and a
+        // correctly-ordered client is rejected with NOT_SUBSCRIBED.
+        // Serializing per socket restores the wire's ordering on the
+        // processing side; distinct sockets stay fully concurrent.
+        let inboundChain = Promise.resolve();
+        ws.on("message", (raw) => {
+            // `ws.on('message')` delivers Buffer/ArrayBuffer/Buffer[] depending
+            // on frame type; normalize to string.
+            const text = typeof raw === "string" ? raw : raw.toString("utf8");
+            inboundChain = inboundChain.then(() => onMessage(ws, text).catch((err) => {
+                // Catch INSIDE the chain link so one failed message never
+                // poisons the chain for subsequent frames.
+                deps.logger.error("render_channel_message_failed", {
+                    error: String(err),
+                });
+            }));
+        });
+        ws.on("close", () => {
+            deps.unregister(ws);
+            pendingIdentity.delete(ws);
+        });
+        ws.on("error", (err) => {
+            deps.logger.warn("render_channel_socket_error", { error: String(err) });
+        });
+    });
+}