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

package/dist/render-channel.js

@@ -1,1775 +0,0 @@
-/**
- * OSS live channel — live session plane over WebSocket.
- *
- * The live channel is where the typed-channel contract is enforced on
- * live traffic between the server and the user. It co-hosts on the
- * same Express server as `/mcp` and reuses the same
- * `@ggui-ai/mcp-server-handlers/renders` helpers that the
- * closed hosted server consumes.
- *
- * Scope:
- *
- *   - `subscribe` → auth, resolve-or-create session, register subscriber,
- *     reply `ack` with the session's current stack + sequence.
- *   - `action` → inbound user action carried as an {@link ActionEnvelope}.
- *     Gated through `assertEventAllowed` (allowlist) +
- *     `assertActionContract` (payload, for data:submit). Persisted to
- *     RenderStore as a typed session event.
- *   - `ping`/`pong` → heartbeat parity with hosted.
- *   - `close`/socket-close → clean subscriber teardown.
- *   - `sendToSession(renderId, data)` → outbound fan-out API for
- *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
- *     through `assertStreamContract` before delivery.
- *
- * `props_update`: mount handlers dispatched through the wired-action
- * router can call `ctx.sendPropsUpdate(renderId, props)` to fan a
- * `{type:'props_update'}` frame to live subscribers without going
- * through a refresh-stream path. Reaches the renderer's existing
- * `props_update` branch in `iframe-runtime` and applies new props
- * in-place. This seam is scoped to mount tools; the agent-driven
- * `ggui_update` path is handled separately.
- *
- * Not handled here:
- *
- *   - Pattern-B daemon-agent notification stream (GET /mcp SSE).
- *   - Short-lived session-token mint/consume — that's ggui_render-gated.
- *     Dev-mode auth (any bearer via existing AuthAdapter) matches the
- *     `/mcp` endpoint's shape and is operator-replaceable.
- */
-import { InMemorySessionStreamBuffer, InProcessStreamFanout, NoopTelemetrySink, } from "@ggui-ai/mcp-server-core/in-memory";
-import { assertActionContract, assertStreamContract } from "@ggui-ai/mcp-server-handlers/renders";
-import { CONTRACT_ERROR_CHANNEL, ContractViolationError, sanitizeCausedBy as defaultSanitizeCausedBy, EMPTY_REFRESH_INPUT, makeContractErrorPayload, PROTOCOL_SCHEMA_VERSION, UPGRADE_REQUIRED, } from "@ggui-ai/protocol";
-import { randomUUID } from "node:crypto";
-import { WebSocketServer } from "ws";
-import { resolveIdentityFromHeaders, UnauthenticatedError } from "./auth.js";
-// `assertEventAllowed` + `EventNotAllowedError` were removed from
-// `@ggui-ai/mcp-server-handlers/renders` in Phase B alongside
-// the session-stack collapse — the event-allowlist concept on a
-// `StackItem.subscription` no longer has a wire shape to bind to.
-// Local stand-ins keep the inbound-action allowlist call sites
-// compiling until the event-allowlist semantics are re-thought in a
-// follow-up slice (see "B.2d render-channel inbound-action allowlist
-// deferred" in the report).
-class EventNotAllowedError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "EventNotAllowedError";
-    }
-}
-function assertEventAllowed(_subscription, _type) {
-    // No-op: pre-Phase-B this read `StackItem.subscription` and rejected
-    // event types not on the allowlist. Post-collapse there's no
-    // subscription field on `Render`; the gate is deferred to a follow-up
-    // slice that defines per-render event policy on the new wire shape.
-}
-/** Default URL path for the channel endpoint. Operators can override. */
-export const DEFAULT_RENDER_CHANNEL_PATH = "/ws";
-/**
- * Default + boundary cadence for the channel-subscribe polling loop.
- * Server-authoritative: clients propose `pollIntervalMs` on
- * `channel_subscribe`, server clamps to [floorMs, ceilingMs] and
- * defaults to `defaultMs` when absent. Conservative defaults — operators
- * tune via {@link RenderChannelLocalToolsOptions.pollCadence}.
- */
-const DEFAULT_CHANNEL_POLL_FLOOR_MS = 1_000;
-const DEFAULT_CHANNEL_POLL_CEILING_MS = 60_000;
-const DEFAULT_CHANNEL_POLL_DEFAULT_MS = 10_000;
-/**
- * Default timeout for a single wired-tool invocation, in ms. Operators
- * override via {@link RenderChannelOptions.wiredActionTimeoutMs}; the
- * 30 s ceiling is a honest non-promise: long-running tools MUST design
- * their own completion path (streaming, polling).
- */
-export const DEFAULT_WIRED_TOOL_TIMEOUT_MS = 30_000;
-/**
- * Raised by `invokeWithTimeout` when a wired-tool call exceeds its
- * per-call budget. Internal — surfaces as a `TOOL_TIMEOUT` code on
- * {@link ContractErrorPayload} before the caller sees any channel
- * output.
- */
-class WiredToolTimeoutError extends Error {
-    toolName;
-    timeoutMs;
-    constructor(toolName, timeoutMs) {
-        super(`Wired tool '${toolName}' did not complete within ${timeoutMs}ms`);
-        this.name = "WiredToolTimeoutError";
-        this.toolName = toolName;
-        this.timeoutMs = timeoutMs;
-    }
-}
-/**
- * Build an OSS live-channel server. The returned object is designed to be
- * composed into `createGguiServer` — see `server.ts` for the wire-up.
- */
-export function createRenderChannelServer(opts) {
-    const path = opts.path ?? DEFAULT_RENDER_CHANNEL_PATH;
-    // Outbound stream buffer — owns seq assignment + bounded replay
-    // storage. Default is in-memory; operators swap via `opts.streamBuffer`.
-    const streamBuffer = opts.streamBuffer ?? new InMemorySessionStreamBuffer();
-    // Live-tail pub/sub. Default in-process; hosted binds RedisPubSubFanout.
-    const streamFanout = opts.streamFanout ?? new InProcessStreamFanout();
-    // `causedBy` sanitizer applied to every contract-error emission.
-    // Defaults to the protocol's pattern-based redactor (Bearer tokens,
-    // query-param secrets, env-var dumps, 2 KB truncation). Operators
-    // pass their own to tighten or broaden coverage.
-    const sanitize = opts.sanitizeCausedBy ?? defaultSanitizeCausedBy;
-    // Operational telemetry — default no-op. Fires `wired-tool.invoked`
-    // on every successful wired-action dispatch (C12); future sites
-    // (refresh-stream success / failure counts) reuse the same sink.
-    const telemetry = opts.telemetry ?? new NoopTelemetrySink();
-    // Channel-subscribe local-tool poll plumbing. Resolved once
-    // at composition so the `channel_subscribe` handler doesn't pay the
-    // option-spread cost per request. Absent ⇒ all channel subscribes
-    // reject with `CHANNEL_NOT_LOCAL`.
-    const localTools = opts.streamWebSocketLocalTools;
-    const localToolsAllowlist = localTools
-        ? new Set(localTools.allowlist)
-        : new Set();
-    const pollFloorMs = localTools?.pollCadence?.floorMs ?? DEFAULT_CHANNEL_POLL_FLOOR_MS;
-    const pollCeilingMs = localTools?.pollCadence?.ceilingMs ?? DEFAULT_CHANNEL_POLL_CEILING_MS;
-    const pollDefaultMs = localTools?.pollCadence?.defaultMs ?? DEFAULT_CHANNEL_POLL_DEFAULT_MS;
-    // `noServer: true` means we own the upgrade wiring (see handleUpgrade);
-    // ws won't try to bind its own port.
-    const wss = new WebSocketServer({ noServer: true });
-    /**
-     * Flat set of all live WS subscribers. Replaces the per-session
-     * `subscribersBySession` Map — routing is now StreamFanout's job;
-     * this set tracks WS-specific bookkeeping (stats, shutdown-broadcast)
-     * that the seam can't see (and shouldn't).
-     */
-    const wsSubscribers = new Set();
-    /** ws → subscriber reverse index so socket-close can look up cheaply. */
-    const subscribersByWs = new WeakMap();
-    /**
-     * Per-session local subscriber count. Drives the {@link
-     * RenderChannelOptions.onFirstSubscriber} / `onLastSubscriberGone`
-     * 0↔1 transition hooks used by cloud adapters for per-session
-     * cross-pod pub/sub channel scoping. Distinct from the
-     * `sessionCount` getter — that walks `wsSubscribers` on demand;
-     * this map is the registration-time counter the hooks key off.
-     */
-    const sessionCountById = new Map();
-    /**
-     * Pump live frames from the StreamFanout iterator out to this
-     * subscriber's WS. Started fire-and-forget by `register`; ends when
-     * the iterator yields done (close() on the seam) OR `unregister`
-     * calls `iter.return()`. Per-subscriber seq filter applied here:
-     * frames with `seq <= replayCompletedSeq` were (or will be)
-     * delivered via the replay path on subscribe.
-     *
-     * The pump's first action is `await iter.next()`, which yields
-     * control back to the event loop. This is what preserves the
-     * subscribe-handler ordering invariant: ack → replay frames →
-     * live frames. The replay-frame send loop completes synchronously
-     * before the pump can ever send anything, regardless of fanout
-     * timing.
-     */
-    async function pumpSubscriber(sub) {
-        try {
-            for (;;) {
-                const { value, done } = await sub.iter.next();
-                if (done)
-                    return;
-                if (value.seq <= sub.replayCompletedSeq)
-                    continue;
-                if (sub.ws.readyState !== sub.ws.OPEN) {
-                    await sub.iter.return?.();
-                    return;
-                }
-                send(sub.ws, { type: "data", payload: value });
-            }
-        }
-        catch (err) {
-            opts.logger.warn("session_channel_pump_failed", {
-                renderId: sub.renderId,
-                error: String(err),
-            });
-        }
-    }
-    function register(sub) {
-        wsSubscribers.add(sub);
-        subscribersByWs.set(sub.ws, sub);
-        // Per-session count bookkeeping + 0→1 hook for cloud pubsub
-        // adapter scoping. Increment FIRST so the hook sees the up-to-date
-        // state; hook fires only on the transition (prevCount === 0).
-        const prevCount = sessionCountById.get(sub.renderId) ?? 0;
-        sessionCountById.set(sub.renderId, prevCount + 1);
-        if (prevCount === 0 && opts.onFirstSubscriber) {
-            try {
-                opts.onFirstSubscriber(sub.renderId);
-            }
-            catch (err) {
-                // Best-effort: a thrown hook MUST NOT corrupt the
-                // wsSubscribers set vs the real socket lifecycle.
-                opts.logger.warn("session_channel_on_first_subscriber_threw", {
-                    renderId: sub.renderId,
-                    error: String(err),
-                });
-            }
-        }
-        // Start the pump loop. Fire-and-forget — pump errors are logged
-        // inside pumpSubscriber, never propagated.
-        void pumpSubscriber(sub);
-    }
-    function unregister(ws) {
-        const sub = subscribersByWs.get(ws);
-        if (!sub)
-            return;
-        subscribersByWs.delete(ws);
-        wsSubscribers.delete(sub);
-        // Per-session count bookkeeping + 1→0 hook (symmetric with register).
-        const prevCount = sessionCountById.get(sub.renderId) ?? 0;
-        if (prevCount <= 1) {
-            sessionCountById.delete(sub.renderId);
-            if (prevCount === 1 && opts.onLastSubscriberGone) {
-                try {
-                    opts.onLastSubscriberGone(sub.renderId);
-                }
-                catch (err) {
-                    opts.logger.warn("session_channel_on_last_subscriber_gone_threw", {
-                        renderId: sub.renderId,
-                        error: String(err),
-                    });
-                }
-            }
-        }
-        else {
-            sessionCountById.set(sub.renderId, prevCount - 1);
-        }
-        // Ending the iter terminates pumpSubscriber AND unregisters this
-        // subscriber from the StreamFanout. Idempotent on the seam side
-        // (close-after-return is a no-op).
-        void sub.iter.return?.();
-        // Tear down every `channel_subscribe` polling loop owned
-        // by this subscriber. Symmetric with stream-iterator teardown
-        // above. clearInterval is idempotent on already-cleared handles,
-        // so a concurrent channel_unsubscribe + WS close is safe.
-        for (const state of sub.channelSubs.values()) {
-            clearInterval(state.timer);
-        }
-        sub.channelSubs.clear();
-    }
-    function send(ws, msg) {
-        if (ws.readyState !== ws.OPEN)
-            return;
-        try {
-            ws.send(JSON.stringify(msg));
-        }
-        catch (err) {
-            opts.logger.warn("session_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 } : {}),
-        });
-    }
-    /**
-     * Shared tenancy guard for client-emitted observation messages
-     * (`host_context_observed`, `canvas_navigated`). Returns `false`
-     * AND emits the appropriate error frame when:
-     *
-     *   - the socket has no bound subscriber (NOT_SUBSCRIBED)
-     *   - payload.renderId doesn't match the subscriber binding
-     *     (SESSION_MISMATCH)
-     *
-     * Subscriber binding is the authoritative tenancy scope. The wire
-     * payload's renderId 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) {
-            sendError(ws, "NOT_SUBSCRIBED", `Send a 'subscribe' message first before '${messageType}'`, requestId);
-            return false;
-        }
-        if (payload.renderId !== sub.renderId) {
-            sendError(ws, "SESSION_MISMATCH", `${messageType} payload id '${payload.renderId ?? "<missing>"}' does not match subscriber render '${sub.renderId}'`, requestId);
-            return false;
-        }
-        return true;
-    }
-    /**
-     * Persist an observation-message-driven session 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 applySessionPatch(renderId, appId, messageType, patch) {
-        try {
-            await opts.renderStore.update(renderId, patch);
-        }
-        catch (err) {
-            opts.logger.warn("session_channel_observation_persist_failed", {
-                messageType,
-                renderId,
-                appId,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-    }
-    /**
-     * 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`, `RENDER_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.
-     */
-    function sendChannelError(ws, renderId, channelName, code, message, requestId, details) {
-        send(ws, {
-            type: "channel_error",
-            payload: {
-                renderId,
-                channelName,
-                code,
-                message,
-                ...(details !== undefined ? { details } : {}),
-            },
-            ...(requestId ? { requestId } : {}),
-        });
-    }
-    /**
-     * Clamp a client-supplied `pollIntervalMs` against the configured
-     * floor / ceiling. Absent (or non-finite) ⇒ default. Server is
-     * authoritative per the `ChannelSubscribePayload.pollIntervalMs`
-     * docstring — clients propose, server clamps.
-     */
-    function clampPollInterval(supplied) {
-        if (typeof supplied !== "number" || !Number.isFinite(supplied)) {
-            return pollDefaultMs;
-        }
-        if (supplied < pollFloorMs)
-            return pollFloorMs;
-        if (supplied > pollCeilingMs)
-            return pollCeilingMs;
-        return supplied;
-    }
-    /**
-     * Run one poll of `state.toolName` and fan its result onto the
-     * subscriber's WS as a `channel_payload`. Throws never escape — a
-     * thrown invocation surfaces as a `channel_error{code:'POLL_FAILED'}`
-     * but the polling loop keeps running so transient tool failures are
-     * recoverable.
-     *
-     * Tool registry is guaranteed-present by the caller — channel
-     * subscribes whose `source.tool` isn't in `localTools.allowlist`
-     * never reach this function.
-     */
-    async function pollChannelOnce(sub, state) {
-        if (!localTools)
-            return;
-        if (sub.ws.readyState !== sub.ws.OPEN)
-            return;
-        try {
-            const output = await localTools.invoke(state.toolName, state.args);
-            // Skip emission if the socket closed during the poll — closing-
-            // raced timers fire at most once, and emitting onto a closing
-            // socket is a `send_failed` warning at best.
-            if (sub.ws.readyState !== sub.ws.OPEN)
-                return;
-            state.seq += 1;
-            send(sub.ws, {
-                type: "channel_payload",
-                payload: {
-                    renderId: sub.renderId,
-                    appId: sub.appId,
-                    channelName: state.channelName,
-                    seq: state.seq,
-                    ts: new Date().toISOString(),
-                    // Default mode for source-fed channels is `replace` — each
-                    // poll is a fresh snapshot, not a delta. Channels that need
-                    // append semantics declare `mode: 'append'` on streamSpec;
-                    // honoring that is the iframe-runtime's concern at fold
-                    // time. See `ChannelPayloadFrame.mode`.
-                    mode: "replace",
-                    payload: output,
-                },
-            });
-        }
-        catch (err) {
-            if (sub.ws.readyState !== sub.ws.OPEN)
-                return;
-            sendChannelError(sub.ws, sub.renderId, state.channelName, "POLL_FAILED", err instanceof Error ? err.message : String(err), undefined, 
-            // causedBy slot — sanitized for credential safety in the same
-            // posture as wired-tool's TOOL_THREW emission.
-            sanitize(err instanceof Error ? (err.stack ?? err.message) : String(err)));
-            opts.logger.warn("session_channel_channel_poll_failed", {
-                renderId: sub.renderId,
-                appId: sub.appId,
-                channelName: state.channelName,
-                toolName: state.toolName,
-                error: String(err),
-            });
-        }
-    }
-    /**
-     * Handle a `channel_subscribe` message. Validates the request,
-     * resolves the channel's `source.tool` against the configured
-     * allowlist, and schedules a polling loop. Idempotent on
-     * `${renderId}:${channelName}` — a re-subscribe replaces any
-     * existing interval rather than running two in parallel.
-     */
-    async function handleChannelSubscribe(ws, sub, message) {
-        const payload = message.payload;
-        // renderId match — the spoof guard at every wire-input boundary.
-        // A subscriber bound to session A can't drive a subscribe for
-        // session B even if they crafted the inbound payload.
-        if (payload.renderId !== sub.renderId) {
-            sendChannelError(ws, payload.renderId, payload.channelName, "SUBSCRIBE_UNAUTHORIZED", `Subscriber is bound to session '${sub.renderId}' but channel_subscribe targets '${payload.renderId}'`, message.requestId);
-            return;
-        }
-        // Without an `streamWebSocketLocalTools` allowlist, no channel
-        // can be subscribed locally. The iframe must fall back to direct
-        // polling via the MCP host proxy.
-        if (!localTools) {
-            sendChannelError(ws, payload.renderId, payload.channelName, "CHANNEL_NOT_LOCAL", "This server has no streamWebSocketLocalTools allowlist; iframe must poll the source tool directly.", message.requestId);
-            return;
-        }
-        // Phase B: a render IS the addressable unit. The prior
-        // reverse-index lookup collapses — `renderStore.get` resolves
-        // the render directly.
-        const stored = await opts.renderStore.get(payload.renderId);
-        if (!stored || stored.id !== sub.renderId) {
-            sendChannelError(ws, payload.renderId, payload.channelName, "RENDER_NOT_FOUND", `Render '${payload.renderId}' not found on subscriber '${sub.renderId}'`, message.requestId);
-            return;
-        }
-        const render = stored.render;
-        // Channel entry resolution. mcpApps / system variants have no
-        // streamSpec so the field reads back as undefined — same code
-        // path as a component variant without the channel declared.
-        const streamSpec = render.type === "mcpApps" || render.type === "system"
-            ? undefined
-            : render.streamSpec;
-        const channelEntry = streamSpec?.[payload.channelName];
-        if (!channelEntry || !channelEntry.source) {
-            sendChannelError(ws, payload.renderId, payload.channelName, "CHANNEL_UNKNOWN", `streamSpec['${payload.channelName}'] not declared OR has no source.tool on render '${payload.renderId}'`, message.requestId);
-            return;
-        }
-        const sourceTool = channelEntry.source.tool;
-        if (!localToolsAllowlist.has(sourceTool)) {
-            sendChannelError(ws, payload.renderId, payload.channelName, "CHANNEL_NOT_LOCAL", `source.tool '${sourceTool}' is not in streamWebSocketLocalTools; iframe must poll directly`, message.requestId);
-            return;
-        }
-        // Validation passed — schedule (or re-schedule) the polling loop.
-        const channelKey = `${payload.renderId}:${payload.channelName}`;
-        // Idempotent replace: a reconnect that re-subscribes the same
-        // (render, channel) pair gets a fresh timer + zeroed seq. The
-        // client's gap-detection treats it as a new stream from the
-        // server's perspective; client-side reconnect logic owns
-        // continuity if the channel was declared `mode: 'append'`.
-        const existing = sub.channelSubs.get(channelKey);
-        if (existing) {
-            clearInterval(existing.timer);
-            sub.channelSubs.delete(channelKey);
-        }
-        const pollIntervalMs = clampPollInterval(payload.pollIntervalMs);
-        // Layered args: source.args defines defaults; client args override
-        // per ChannelSubscribePayload.args docstring.
-        const mergedArgs = {
-            ...(channelEntry.source.args ?? {}),
-            ...(payload.args ?? {}),
-        };
-        // Resolve the channelKey lookup at callback fire-time. The
-        // timer callback reads `sub.channelSubs.get(channelKey)` so
-        // `state` doesn't have to be referenced through a closure
-        // before it's actually inserted into the tracker. Also self-
-        // cleans on the zombie-timer path: if the subscription was
-        // already torn down (channel_unsubscribe / WS close / replace),
-        // the lookup returns undefined and we clearInterval ourselves.
-        const timer = setInterval(() => {
-            const live = sub.channelSubs.get(channelKey);
-            if (!live || !subscribersByWs.has(sub.ws)) {
-                clearInterval(timer);
-                return;
-            }
-            void pollChannelOnce(sub, live);
-        }, pollIntervalMs);
-        const state = {
-            pollIntervalMs,
-            toolName: sourceTool,
-            renderId: payload.renderId,
-            channelName: payload.channelName,
-            args: mergedArgs,
-            seq: 0,
-            timer,
-        };
-        sub.channelSubs.set(channelKey, state);
-        opts.logger.info("render_channel_channel_subscribe", {
-            renderId: sub.renderId,
-            appId: sub.appId,
-            channelName: payload.channelName,
-            toolName: sourceTool,
-            pollIntervalMs,
-        });
-        // Eager-poll — fire one invocation immediately so the iframe sees
-        // an initial value without waiting `pollIntervalMs`. Matches the
-        // user-expected "subscribe then see data" cadence; the interval
-        // takes over from there.
-        void pollChannelOnce(sub, state);
-    }
-    /**
-     * Handle a `channel_unsubscribe` message. Idempotent: a no-op
-     * unsubscribe on an unknown channelKey returns silently. WS close
-     * implicitly unsubscribes every channel; this message is for
-     * mid-session cancellation.
-     */
-    function handleChannelUnsubscribe(_ws, sub, message) {
-        const payload = message.payload;
-        if (payload.renderId !== sub.renderId) {
-            // No-op silently — the canonical "spoof guard" code path is in
-            // channel_subscribe; unsubscribe gets no error frame to avoid
-            // leaking cross-session existence.
-            return;
-        }
-        const channelKey = `${payload.renderId}:${payload.channelName}`;
-        const existing = sub.channelSubs.get(channelKey);
-        if (!existing)
-            return;
-        clearInterval(existing.timer);
-        sub.channelSubs.delete(channelKey);
-        opts.logger.info("render_channel_channel_unsubscribe", {
-            renderId: sub.renderId,
-            appId: sub.appId,
-            channelName: payload.channelName,
-        });
-    }
-    /**
-     * Stamp a delivery through the replay buffer and fan it out to every
-     * subscriber of the session, honoring the per-subscriber replay
-     * cursor. Shared by the public `sendToSession` entry point AND by
-     * the wiredActionRouter's refresh/error emissions — extracting this
-     * avoids duplicating the seq-stamp + subscriber-iteration logic in
-     * two places.
-     *
-     * Caller is responsible for validating `delivery.payload` against
-     * the active streamSpec BEFORE calling — the fan-out here trusts
-     * its input. Reserved-channel emissions (e.g. `_ggui:contract-
-     * error`) bypass the streamSpec check upstream via
-     * `assertStreamContract`.
-     */
-    async function fanOut(delivery, activeStreamSpec) {
-        const { envelope } = await 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 a hosted
-        // RedisPubSubFanout failure here would already be persisted to the
-        // SessionStreamBuffer for replay-recovery on reconnect.
-        void streamFanout.publish({ renderId: envelope.renderId, envelope });
-        return { seq: envelope.seq };
-    }
-    /**
-     * Emit a canonical {@link ContractErrorPayload} on the reserved
-     * `_ggui:contract-error` channel. Never throws — the wiredActionRouter
-     * dispatch path calls this from `catch` branches; a second failure
-     * would be a footgun.
-     */
-    function emitContractError(renderId, activeStreamSpec, payload) {
-        try {
-            // Central stamp — re-emit through makeContractErrorPayload so
-            // every contract-error envelope carries the current stamped
-            // schemaVersion regardless of which dispatch branch produced
-            // `payload`. Byte-equivalent to the pre-Item-1 inline stamp
-            // (`{...payload, schemaVersion: PROTOCOL_SCHEMA_VERSION}`) which
-            // also always clobbered to the current version — the local
-            // dispatch paths never forward pre-stamped payloads, so any
-            // incoming schemaVersion on `payload` is discarded by design.
-            const stamped = makeContractErrorPayload({
-                toolName: payload.toolName,
-                error: payload.error,
-                timestamp: payload.timestamp,
-                ...(payload.actionName !== undefined ? { actionName: payload.actionName } : {}),
-                ...(payload.sourceAction !== undefined ? { sourceAction: payload.sourceAction } : {}),
-            });
-            // Fire-and-forget: emitContractError is called from sync `catch`
-            // branches and a second async failure here would be a footgun.
-            // Promise rejection logs but doesn't propagate; the seam contract
-            // says publish never throws on InProcess impl, and a hosted
-            // RedisPubSubFanout failure is recoverable via replay-on-reconnect.
-            void fanOut({
-                renderId,
-                channel: CONTRACT_ERROR_CHANNEL,
-                mode: "append",
-                payload: stamped,
-            }, activeStreamSpec).catch((err) => {
-                opts.logger.error("session_channel_contract_error_emit_failed", {
-                    renderId,
-                    toolName: payload.toolName,
-                    code: payload.error.code,
-                    error: String(err),
-                });
-            });
-        }
-        catch (err) {
-            opts.logger.error("session_channel_contract_error_emit_failed", {
-                renderId,
-                toolName: payload.toolName,
-                code: payload.error.code,
-                error: String(err),
-            });
-        }
-    }
-    /**
-     * Race a wired-tool invocation against a timeout. On timeout, the
-     * underlying promise is abandoned (we do NOT cancel the tool —
-     * handlers are trusted to clean up their own resources) but the
-     * caller sees a {@link WiredToolTimeoutError} and emits
-     * `TOOL_TIMEOUT`.
-     */
-    async function invokeWithTimeout(router, toolName, 
-    // Accepts either a validated wired-action payload (Record) OR the
-    // typed empty refresh input ({@link RefreshInput} /
-    // {@link EMPTY_REFRESH_INPUT}). The two call sites upstream are
-    // the only producers; nothing else should widen this.
-    input, ctx, timeoutMs) {
-        let timer;
-        try {
-            return await Promise.race([
-                router.invoke(toolName, input, ctx),
-                new Promise((_, reject) => {
-                    timer = setTimeout(() => {
-                        reject(new WiredToolTimeoutError(toolName, timeoutMs));
-                    }, timeoutMs);
-                }),
-            ]);
-        }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-        }
-    }
-    /**
-     * Internal impl behind the public {@link RenderChannelServer.sendPropsUpdate}.
-     * Extracted as a closure-level function so the wired-action dispatcher
-     * can build a `WiredActionContext.sendPropsUpdate` that closes over the
-     * same logic without forward-referencing the returned object. Best-
-     * effort + orphan-tolerant per the docstring on the public method.
-     */
-    async function sendPropsUpdateImpl(renderId, props) {
-        let stored;
-        try {
-            stored = await opts.renderStore.get(renderId);
-        }
-        catch (err) {
-            opts.logger.warn("render_channel_props_update_lookup_failed", {
-                renderId,
-                error: String(err),
-            });
-            return;
-        }
-        if (!stored) {
-            opts.logger.warn("render_channel_props_update_orphan", {
-                renderId,
-            });
-            return;
-        }
-        // Filter the flat WS-subscriber set by renderId; same posture as
-        // `notifyRenderPush`. `send()` already silently skips closed sockets
-        // and logs (but doesn't throw on) per-subscriber send failures, so
-        // the caller's mount-handler path can't be made to fail by a dead
-        // WebSocket.
-        for (const sub of wsSubscribers) {
-            if (sub.renderId !== renderId)
-                continue;
-            send(sub.ws, {
-                type: "props_update",
-                payload: { renderId, props },
-            });
-        }
-    }
-    /**
-     * Dispatch a wired action after inbound validation has passed.
-     * Called synchronously inside `handleInboundAction` — the caller
-     * awaits so the UI's ack arrives AFTER any refresh-stream frames
-     * land (honest ordering: "when you see the ack, your action
-     * completed + the screen reflects it").
-     *
-     * No-ops when:
-     *   - no wiredActionRouter is configured on this channel
-     *   - the action didn't resolve to a tool name (plain agent-routed
-     *     action that we persist + forward as-is)
-     *   - the resolved tool isn't registered (emits `TOOL_NOT_FOUND`)
-     *
-     * On successful tool invocation, every declared channel on the
-     * active stack item's streamSpec with a `tool` refresh hint fires
-     * that tool + emits its return value on the channel. Refresh tools
-     * are invoked with an empty argument object (`{}`); authors who
-     * need filter args should inline the action + refresh into a single
-     * tool that returns the new state.
-     */
-    async function dispatchWiredAction(stored, activeItem, envelope, dispatchedAt) {
-        // Post-Phase-B, the active "session" is just the stored render's
-        // id. Keep a `session` alias inside the body so the existing
-        // `session.id` references stay readable without a wholesale
-        // re-name pass.
-        const session = stored;
-        const router = opts.wiredActionRouter;
-        if (!router || !activeItem || envelope.type !== "data:submit")
-            return;
-        const payload = envelope.payload;
-        if (!payload || typeof payload.action !== "string")
-            return;
-        // Disagreement policy — the server-side enforcement point for the
-        // `client wins` rule documented on `ActionEventValue.tool`. Prefer
-        // the envelope's client-populated `tool` (useAction fills it from
-        // the same contract lookup the server would redo). Fall back to the
-        // actionSpec declaration so a client that omits the wire hint still
-        // gets the expected routing. If the two disagree, client wins — the
-        // client is the source of truth for what the user actually saw.
-        // Cross-validation against the agent's tracked contract happens on
-        // the agent-SDK side, not here.
-        // actionSpec / streamSpec only exist on ComponentRender. The
-        // mcpApps / system variants narrow them to undefined.
-        const componentItem = activeItem.type === "mcpApps" || activeItem.type === "system" ? undefined : activeItem;
-        const actionEntry = componentItem?.actionSpec?.[payload.action];
-        const serverDeclaredTool = actionEntry?.nextStep;
-        const declaredTool = (typeof payload.tool === "string" && payload.tool.length > 0 ? payload.tool : undefined) ??
-            serverDeclaredTool;
-        if (!declaredTool)
-            return;
-        const actionName = payload.action;
-        const input = payload.data && typeof payload.data === "object" && !Array.isArray(payload.data)
-            ? payload.data
-            : {};
-        const timeoutMs = opts.wiredActionTimeoutMs ?? DEFAULT_WIRED_TOOL_TIMEOUT_MS;
-        const streamSpec = componentItem?.streamSpec;
-        if (!router.has(declaredTool)) {
-            emitContractError(session.id, streamSpec, {
-                toolName: declaredTool,
-                actionName,
-                sourceAction: { type: "wired-action", dispatchedAt },
-                error: {
-                    code: "TOOL_NOT_FOUND",
-                    message: `wiredActionRouter has no handler for tool '${declaredTool}'`,
-                },
-                timestamp: new Date().toISOString(),
-            });
-            opts.logger.warn("session_channel_wired_tool_not_found", {
-                renderId: session.id,
-                toolName: declaredTool,
-                actionName,
-            });
-            return;
-        }
-        // Build the wired-action context the router hands the mount tool.
-        // `sendPropsUpdate` closes over the active
-        // `session.id` so a buggy mount can't accidentally cross-deliver to
-        // another session by passing a foreign renderId. The same ctx is
-        // reused for the refresh-stream pass below — a refresh tool that
-        // wants to fire props_update can do so, though the canonical site
-        // is the action tool itself.
-        const wiredCtx = {
-            renderId: session.id,
-            sendPropsUpdate(props) {
-                void sendPropsUpdateImpl(session.id, props);
-            },
-        };
-        const invokeStartedAt = Date.now();
-        try {
-            await invokeWithTimeout(router, declaredTool, input, wiredCtx, timeoutMs);
-        }
-        catch (err) {
-            const code = err instanceof WiredToolTimeoutError ? "TOOL_TIMEOUT" : "TOOL_THREW";
-            emitContractError(session.id, streamSpec, {
-                toolName: declaredTool,
-                actionName,
-                sourceAction: { type: "wired-action", dispatchedAt },
-                error: {
-                    code,
-                    message: err instanceof Error ? err.message : String(err),
-                    ...(err instanceof Error && err.stack ? { causedBy: sanitize(err.stack) } : {}),
-                },
-                timestamp: new Date().toISOString(),
-            });
-            opts.logger.warn("session_channel_wired_tool_failed", {
-                renderId: session.id,
-                toolName: declaredTool,
-                actionName,
-                code,
-                error: String(err),
-            });
-            return;
-        }
-        // Operational telemetry — record the successful dispatch. Lossy
-        // by contract (TelemetrySink.emit is sync + non-throwing); a bad
-        // sink MUST NOT block the refresh pass. Attribute set is kept
-        // flat + primitive-only per TelemetryEvent.attributes shape.
-        telemetry.emit({
-            name: "wired-tool.invoked",
-            at: Date.now(),
-            attributes: {
-                toolName: declaredTool,
-                actionName,
-                renderId: session.id,
-                latencyMs: Date.now() - invokeStartedAt,
-            },
-        });
-        // Refresh pass — every declared channel with a `tool` hint fires a
-        // fresh read and emits the result on that channel. Each refresh
-        // tool gets its own timeout + isolation: one broken refresh MUST
-        // NOT block others from completing.
-        if (!streamSpec)
-            return;
-        for (const [channelName, channelEntry] of Object.entries(streamSpec)) {
-            const refreshTool = channelEntry?.tool;
-            if (!refreshTool)
-                continue;
-            if (!router.has(refreshTool)) {
-                emitContractError(session.id, streamSpec, {
-                    toolName: refreshTool,
-                    actionName,
-                    sourceAction: { type: "refresh-stream", dispatchedAt },
-                    error: {
-                        code: "TOOL_NOT_FOUND",
-                        message: `wiredActionRouter has no handler for refresh tool '${refreshTool}' (channel '${channelName}')`,
-                    },
-                    timestamp: new Date().toISOString(),
-                });
-                continue;
-            }
-            let output;
-            try {
-                // Refresh input is v1-locked to the empty shape via
-                // EMPTY_REFRESH_INPUT. DO NOT replace with an inline `{}`
-                // literal — the named constant is what keeps this contract
-                // grep-able and future-proofs v2 evolution (see
-                // {@link RefreshInput}).
-                output = await invokeWithTimeout(router, refreshTool, EMPTY_REFRESH_INPUT, wiredCtx, timeoutMs);
-            }
-            catch (err) {
-                const code = err instanceof WiredToolTimeoutError ? "TOOL_TIMEOUT" : "TOOL_THREW";
-                emitContractError(session.id, streamSpec, {
-                    toolName: refreshTool,
-                    actionName,
-                    sourceAction: { type: "refresh-stream", dispatchedAt },
-                    error: {
-                        code,
-                        message: err instanceof Error ? err.message : String(err),
-                        ...(err instanceof Error && err.stack ? { causedBy: sanitize(err.stack) } : {}),
-                    },
-                    timestamp: new Date().toISOString(),
-                });
-                opts.logger.warn("session_channel_refresh_tool_failed", {
-                    renderId: session.id,
-                    toolName: refreshTool,
-                    channel: channelName,
-                    code,
-                    error: String(err),
-                });
-                continue;
-            }
-            try {
-                assertStreamContract(streamSpec, channelName, output, opts.extraReservedValidators);
-            }
-            catch (err) {
-                if (err instanceof ContractViolationError) {
-                    emitContractError(session.id, streamSpec, {
-                        toolName: refreshTool,
-                        actionName,
-                        sourceAction: { type: "refresh-stream", dispatchedAt },
-                        error: {
-                            code: "SCHEMA_VIOLATION",
-                            message: err.message,
-                        },
-                        timestamp: new Date().toISOString(),
-                    });
-                    opts.logger.warn("session_channel_refresh_schema_violation", {
-                        renderId: session.id,
-                        toolName: refreshTool,
-                        channel: channelName,
-                        violations: err.violations,
-                    });
-                    continue;
-                }
-                throw err;
-            }
-            try {
-                await fanOut({
-                    renderId: session.id,
-                    channel: channelName,
-                    mode: channelEntry?.mode ?? "append",
-                    payload: output,
-                }, streamSpec);
-            }
-            catch (err) {
-                // fanOut swallows per-subscriber transport errors; a throw here
-                // is buffer-internal (e.g., record() invariant violation). Log
-                // but don't propagate — a single broken channel must not take
-                // down the session.
-                opts.logger.error("session_channel_refresh_emit_failed", {
-                    renderId: session.id,
-                    toolName: refreshTool,
-                    channel: channelName,
-                    error: String(err),
-                });
-            }
-        }
-    }
-    async function resolveIdentityFromUpgrade(req) {
-        const url = new URL(req.url ?? "/", "http://localhost");
-        // WS-token gate: when `?wsToken=` is present AND the channel is
-        // configured with ws-token-auth plumbing, skip the AuthAdapter
-        // entirely at upgrade. The real identity is established in
-        // handleSubscribe when the subscribe payload's `wsToken` is
-        // verified. This is how MCP Apps iframes connect — they can't set
-        // Authorization headers, and the token model is subscribe-scoped
-        // anyway.
-        //
-        // URL-gate here is NOT verification — it's a "don't reject the
-        // upgrade for missing bearer" signal. The real verify runs at
-        // subscribe time; an invalid token reaches that point and is
-        // rejected with BOOTSTRAP_INVALID.
-        if (opts.bootstrap && url.searchParams.has("wsToken")) {
-            return {
-                identity: {
-                    kind: "user",
-                    userId: "__bootstrap_pending__",
-                    workspaceId: "__bootstrap_pending__",
-                    roles: [],
-                },
-                source: "apikey",
-            };
-        }
-        // Embedded-ui cookie gate. Consulted ONLY when the channel is
-        // configured with cookie-auth plumbing AND no bootstrap is in
-        // play. Unlike bootstrap, cookies ARE verified here: the single
-        // consumer (console SPA) sets the cookie out-of-band via
-        // `POST /ggui/console/render-cookie` and we do want to
-        // reject the upgrade cleanly (HTTP 401 → browser WS error) when
-        // the cookie is stale/missing, not carry a doomed handshake into
-        // subscribe where the error surface is worse.
-        //
-        // On success, we stash the bound `{renderId, appId}` on the
-        // request so `handleSubscribe` can enforce that the subscribe
-        // payload targets exactly those values. No synthesis from the
-        // AuthAdapter — cookies ARE the auth signal.
-        if (opts.cookieAuth) {
-            const raw = opts.cookieAuth.readCookie(req.headers);
-            if (raw) {
-                const bound = opts.cookieAuth.verify(raw);
-                if (bound) {
-                    req.__gguiCookieBound = bound;
-                    return {
-                        identity: { kind: "builder" },
-                        source: "apikey",
-                    };
-                }
-                // Cookie present but invalid — do NOT fall through to the
-                // bearer path. An invalid cookie is a same-origin user error,
-                // not a pass-through condition.
-                throw new UnauthenticatedError("console cookie invalid");
-            }
-            // No cookie present → fall through to bearer path below. Mixed
-            // deployments (pairing-token bearer + same-origin cookie for
-            // viewer) are legal.
-        }
-        // Browsers can't set Authorization on native WebSocket. Fall back
-        // to `?token=<jwt>` for web clients, matching the convention most
-        // session-channel endpoints ship with. Server-side clients (Node
-        // `ws`, tests) continue to set the header directly.
-        if (!req.headers["authorization"]) {
-            const token = url.searchParams.get("token");
-            if (token) {
-                req.headers["authorization"] = `Bearer ${token}`;
-            }
-        }
-        return resolveIdentityFromHeaders(opts.auth, req.headers, req.socket?.remoteAddress ?? undefined);
-    }
-    /**
-     * Resolve the active render variant for contract enforcement. Phase
-     * B collapsed the prior (stack, currentStackIndex) lookup — a render
-     * IS the addressable unit, so the active render is the stored render
-     * itself. MCP Apps / system variants narrow to `undefined` so
-     * upstream enforcement skips (allowlist + actionSpec checks are
-     * no-ops when no `ComponentRender` is active).
-     */
-    function resolveActiveRender(render) {
-        if (!render)
-            return undefined;
-        if (render.type === "mcpApps" || render.type === "system")
-            return undefined;
-        return render;
-    }
-    /**
-     * Handle an inbound `action` message — the canonical flat
-     * {@link ActionEnvelope} shape.
-     *
-     * Two-step enforcement: (1) allowlist via {@link assertEventAllowed}
-     * against the active stack item's `subscription.events`; (2)
-     * actionSpec payload check via {@link assertActionContract} for
-     * `data:submit` types. Both helpers are shared with the hosted
-     * `handle-action.ts` ingress.
-     */
-    async function handleInboundAction(ws, sub, message) {
-        const envelope = message.payload;
-        // Spoof guard — envelope.renderId is REQUIRED on the wire and
-        // MUST match the subscriber's bound session.
-        if (envelope.renderId !== sub.renderId) {
-            sendError(ws, "SESSION_MISMATCH", `Action targets session '${envelope.renderId}' but this socket is subscribed to '${sub.renderId}'`, message.requestId);
-            return;
-        }
-        const stored = await opts.renderStore.get(sub.renderId);
-        if (!stored) {
-            sendError(ws, "RENDER_NOT_FOUND", `Render ${sub.renderId} no longer exists`, message.requestId);
-            return;
-        }
-        // Phase B: a render IS the addressable unit. The prior stack
-        // routing (stackIndex / cross-stack pickIds) collapses — the
-        // resolved render itself is the active item.
-        const activeItem = resolveActiveRender(stored.render);
-        // ── Two-step enforcement ──
-        //   1. allowlist via assertEventAllowed (Phase B: no-op stub —
-        //      Render no longer carries a `subscription` allowlist;
-        //      reinstating per-render event policy is deferred.)
-        //   2. actionSpec payload check via assertActionContract (data:submit)
-        // Envelope.payload for data:submit carries the ActionEventValue
-        // shape (`{action, data?, tool?}`).
-        try {
-            assertEventAllowed(undefined, envelope.type);
-        }
-        catch (err) {
-            if (err instanceof EventNotAllowedError) {
-                opts.logger.warn("render_channel_event_not_allowed", {
-                    renderId: sub.renderId,
-                    envelope: "action",
-                    error: err.message,
-                });
-                sendError(ws, "EVENT_NOT_ALLOWED", err.message, message.requestId);
-                return;
-            }
-            throw err;
-        }
-        if (envelope.type === "data:submit") {
-            try {
-                const activeActionSpec = activeItem && activeItem.type !== "mcpApps" && activeItem.type !== "system"
-                    ? activeItem.actionSpec
-                    : undefined;
-                assertActionContract(activeActionSpec, envelope.payload);
-            }
-            catch (err) {
-                if (err instanceof ContractViolationError) {
-                    opts.logger.warn("session_channel_contract_violation", {
-                        renderId: sub.renderId,
-                        violations: err.violations,
-                        envelope: "action",
-                    });
-                    sendError(ws, "CONTRACT_VIOLATION", err.message, message.requestId, err.toErrorData());
-                    return;
-                }
-                throw err;
-            }
-        }
-        // Persist the envelope. RenderStore.appendEvent assigns a monotonic
-        // seq the client acks back with so reconnects can resume via `fromSeq`.
-        const dispatchedAt = new Date().toISOString();
-        let seq;
-        try {
-            seq = await opts.renderStore.appendEvent({
-                renderId: sub.renderId,
-                type: "user.submitted",
-                data: envelope,
-            });
-        }
-        catch (err) {
-            opts.logger.error("session_channel_append_failed", {
-                renderId: sub.renderId,
-                error: String(err),
-            });
-            sendError(ws, "APPEND_FAILED", err instanceof Error ? err.message : String(err), message.requestId);
-            return;
-        }
-        // wiredActionRouter — fire any declared action-tool +
-        // stream-refresh tools BEFORE acking the user. Honest ordering:
-        // when the ack lands, any refresh frames the tool produced have
-        // already fanned out, so the client can treat "ack received" as
-        // "UI state reflects my action". No-op when no router is
-        // configured OR when the action didn't declare a tool.
-        //
-        // Awaited (not fire-and-forget): dispatchWiredAction internally
-        // catches every failure and emits contract-error envelopes; a
-        // throw out of this call would be a platform bug and we'd rather
-        // see it in tests than silently drop.
-        await dispatchWiredAction(stored, activeItem, envelope, dispatchedAt);
-        // StreamFanout pump-drain: dispatchWiredAction's internal fanOut
-        // calls `streamFanout.publish()` which queues envelopes into the
-        // pump's async iterator. The pump's `await iter.next()` resolves
-        // on the microtask queue — without this drain, the synchronous
-        // `send(ws, ack)` below races ahead of the pump's `send(ws, data)`,
-        // and the data-before-ack invariant fails. `setImmediate` waits for
-        // the next macrotask, which is strictly after all pending
-        // microtasks (the pump iterations) drain. OSS-only invariant —
-        // hosted Path A's RedisPubSubFanout can't preserve cross-pod
-        // ordering by construction; clients on hosted treat data + ack as
-        // independent signals.
-        await new Promise((resolve) => setImmediate(resolve));
-        send(ws, {
-            type: "ack",
-            payload: { sequence: seq, timestamp: Date.now() },
-            ...(message.requestId ? { requestId: message.requestId } : {}),
-        });
-    }
-    async function handleSubscribe(ws, identity, message) {
-        const payload = message.payload;
-        // Protocol-version handshake. Opt-in on the client side: absent
-        // `supportedVersions` is legacy-pass-through. When present,
-        // require the server's PROTOCOL_SCHEMA_VERSION to be in the
-        // declared set — otherwise emit UPGRADE_REQUIRED.
-        //
-        //   - 'reject' (default): emit + close the connection. Canonical
-        //     posture for first-party servers.
-        //   - 'advisory' (opt-out): emit + keep the connection
-        //     open (but stop the subscribe; no ack, no session work).
-        //     Clients that ignore the code continue exactly as
-        //     pre-handshake.
-        //
-        // Placed FIRST — before bootstrap verify (which consumes the
-        // single-use bootstrap token per the RenderChannelBootstrap
-        // docstring) and before session lookup/creation (DB work).
-        // Bootstrap iframes with a version mismatch must retry with a
-        // fresh bootstrap token; burning the token on a mismatch the
-        // client could detect by reading the version-negotiation spec
-        // would be a footgun.
-        if (Array.isArray(payload.supportedVersions) &&
-            payload.supportedVersions.length > 0 &&
-            !payload.supportedVersions.includes(PROTOCOL_SCHEMA_VERSION)) {
-            const policy = opts.versionPolicy ?? "reject";
-            sendError(ws, UPGRADE_REQUIRED, `Server speaks ${PROTOCOL_SCHEMA_VERSION}; client declared ` +
-                `supportedVersions=[${payload.supportedVersions.join(", ")}].`, message.requestId, {
-                serverVersion: PROTOCOL_SCHEMA_VERSION,
-                clientSupportedVersions: payload.supportedVersions,
-                policy,
-            });
-            opts.logger.warn("session_channel_version_mismatch", {
-                renderId: payload.renderId,
-                appId: payload.appId,
-                serverVersion: PROTOCOL_SCHEMA_VERSION,
-                clientSupportedVersions: payload.supportedVersions,
-                policy,
-            });
-            if (policy === "reject") {
-                try {
-                    ws.close();
-                }
-                catch {
-                    // best-effort — socket may already be closing
-                }
-            }
-            return;
-        }
-        // WS-token-auth path. When `payload.wsToken` is present, the MCP
-        // Apps iframe is asking us to authenticate it via the short-lived
-        // token minted by `ggui_render`. This REPLACES the upgrade-time
-        // AuthAdapter identity — iframes don't carry bearer tokens.
-        // Mutually-exclusive on purpose.
-        let effectiveIdentity = identity;
-        let mintedSessionToken;
-        if (typeof payload.wsToken === "string" && payload.wsToken.length > 0) {
-            if (!opts.bootstrap) {
-                sendError(ws, "BOOTSTRAP_NOT_SUPPORTED", "This server was not configured with ws-token-auth plumbing", message.requestId);
-                return;
-            }
-            const verifyResult = opts.bootstrap.verify(payload.wsToken);
-            if (!verifyResult.ok) {
-                opts.logger.warn("session_channel_bootstrap_rejected", {
-                    renderId: payload.renderId,
-                    appId: payload.appId,
-                    reason: verifyResult.reason,
-                });
-                // G14 (2026-05-23): distinguish `expired` from `invalid` so the
-                // iframe-side handler can branch on refresh-vs-rehandshake.
-                // Tamper / format / kind failures collapse into BOOTSTRAP_INVALID
-                // (no refresh path); expired-but-signed envelopes emit the
-                // dedicated BOOTSTRAP_EXPIRED so the client knows to call
-                // `ggui_runtime_refresh_bootstrap`.
-                if (verifyResult.reason === "expired") {
-                    sendError(ws, "BOOTSTRAP_EXPIRED", "Bootstrap token expired — call ggui_runtime_refresh_bootstrap or re-handshake", message.requestId);
-                }
-                else {
-                    sendError(ws, "BOOTSTRAP_INVALID", "Bootstrap token invalid (bad signature, malformed, or wrong kind)", message.requestId);
-                }
-                return;
-            }
-            const bound = { renderId: verifyResult.renderId, appId: verifyResult.appId };
-            if (bound.renderId !== payload.renderId) {
-                sendError(ws, "BOOTSTRAP_SESSION_MISMATCH", `Bootstrap token is bound to session '${bound.renderId}' but subscribe targets '${payload.renderId}'`, message.requestId);
-                return;
-            }
-            if (bound.appId !== payload.appId) {
-                sendError(ws, "BOOTSTRAP_APP_MISMATCH", `Bootstrap token is bound to app '${bound.appId}' but subscribe targets '${payload.appId}'`, message.requestId);
-                return;
-            }
-            // Synthesize a minimal AuthResult from the bootstrap claims.
-            // The subscriber row needs an identity for logging and roster
-            // inspection; the bootstrap-derived identity is a first-class
-            // citizen for the lifetime of this subscription.
-            effectiveIdentity = {
-                identity: {
-                    kind: "user",
-                    userId: bound.renderId,
-                    workspaceId: bound.appId,
-                    roles: [],
-                },
-                source: "apikey",
-            };
-            // Mint the reconnect credential now — before create/observe
-            // work — so a downstream failure doesn't leave the client with
-            // no way to resume.
-            mintedSessionToken = opts.bootstrap.issueSessionToken(bound.renderId, bound.appId);
-            opts.logger.info("session_channel_bootstrap_accepted", {
-                renderId: bound.renderId,
-                appId: bound.appId,
-            });
-        }
-        // Dev-mode session provisioning: look up first; if not present,
-        // create with the client-provided id via the widened
-        // CreateSessionInput.id seam. Matches the hosted model's shape
-        // (agent creates via ggui_render → client subscribes) in a single
-        // step — production deployments tighten this by supplying an
-        // AuthAdapter that mints session-scoped tokens on render.
-        let session = await opts.renderStore.get(payload.renderId);
-        if (session) {
-            if (session.appId !== payload.appId) {
-                sendError(ws, "APP_MISMATCH", `Session ${payload.renderId} belongs to a different app`, message.requestId);
-                return;
-            }
-        }
-        else {
-            try {
-                session = await opts.renderStore.create({
-                    id: payload.renderId,
-                    appId: payload.appId,
-                });
-            }
-            catch (err) {
-                sendError(ws, "SESSION_CREATE_FAILED", err instanceof Error ? err.message : String(err), message.requestId);
-                return;
-            }
-        }
-        // Snapshot the outbound-stream cursor BEFORE registering the
-        // subscriber. Any concurrent producer that calls sendToSession
-        // between here and registration gets seq > snapshotSeq, so the
-        // subscriber will receive it via live fan-out (not via replay).
-        //
-        // This is race-safe in single-threaded JS: the next few lines run
-        // synchronously up to `register(sub)`, and fan-out's per-subscriber
-        // `seq <= replayCompletedSeq` guard takes care of the window.
-        // Local alias for the resolved row (handleSubscribe's `session`
-        // local IS a `StoredRender` post-collapse; rename kept narrow to
-        // avoid a wholesale identifier sweep in this slice).
-        const stored = session;
-        const snapshotSeq = await streamBuffer.currentSeq(stored.id);
-        // Phase B: a render IS the addressable unit, so the active item
-        // is the resolved render's visible-bits surface itself.
-        const activeItem = stored.render;
-        // Reconnect: `fromSeq` present → replay per policy on declared
-        // AND reserved channels. Fresh subscribe: `fromSeq` absent →
-        // call with `fromSeq=0` + NO spec, so the buffer's spec-channel
-        // walk contributes nothing (preserving the "initial state comes
-        // from ack.render.props; stream channels are for updates after"
-        // doctrine for agent-declared channels) but the reserved-channel
-        // walk still surfaces server-pushed state that landed before the
-        // subscriber attached.
-        const activeStreamSpec = activeItem.type !== "mcpApps" && activeItem.type !== "system"
-            ? activeItem.streamSpec
-            : undefined;
-        const replay = payload.fromSeq !== undefined
-            ? await streamBuffer.replay(stored.id, payload.fromSeq, activeStreamSpec)
-            : await streamBuffer.replay(stored.id, 0, undefined);
-        // Subscribe to the StreamFanout BEFORE constructing the Subscriber:
-        // the seam returns an AsyncIterable whose iterator we hand off; the
-        // pump loop in `register` consumes it. Eager registration on the
-        // seam side means any concurrent `streamFanout.publish` from this
-        // point onward queues into our iterator — paired with the
-        // replayCompletedSeq cursor below, that's race-free.
-        const fanoutIter = streamFanout.subscribe(stored.id)[Symbol.asyncIterator]();
-        const sub = {
-            ws,
-            renderId: stored.id,
-            appId: stored.appId,
-            identity: effectiveIdentity,
-            connectedAt: Date.now(),
-            replayCompletedSeq: snapshotSeq,
-            iter: fanoutIter,
-            // Per-subscriber channel-subscribe tracker. Populated
-            // lazily by the `channel_subscribe` handler when the operator
-            // wired `streamWebSocketLocalTools`; stays empty otherwise.
-            channelSubs: new Map(),
-        };
-        register(sub);
-        opts.logger.info("render_channel_subscribed", {
-            renderId: stored.id,
-            appId: stored.appId,
-            identityKind: effectiveIdentity.identity.kind,
-            fromSeq: payload.fromSeq,
-            snapshotSeq,
-            replayCount: replay?.envelopes.length ?? 0,
-            replayTruncated: replay?.truncated ?? false,
-            bootstrap: mintedSessionToken !== undefined,
-        });
-        const ackPayload = {
-            sequence: stored.eventSequence,
-            timestamp: Date.now(),
-            render: stored.render,
-            streamSeq: snapshotSeq,
-            // Advertise the server's protocol version on every successful
-            // subscribe ack (SPEC §11.2.2). Clients whose
-            // CLIENT_SUPPORTED_VERSIONS doesn't contain this string surface
-            // UpgradeRequiredError to their caller; clients that don't wire
-            // the handshake ignore the field (legacy-pass-through).
-            serverVersion: PROTOCOL_SCHEMA_VERSION,
-            ...(replay?.truncated ? { replayTruncated: true } : {}),
-            ...(mintedSessionToken !== undefined ? { renderToken: mintedSessionToken } : {}),
-        };
-        send(ws, {
-            type: "ack",
-            payload: ackPayload,
-            ...(message.requestId ? { requestId: message.requestId } : {}),
-        });
-        // R7 — RenderEvent ledger replay. When `payload.sinceSequence` is
-        // present, fetch events with `seq > sinceSequence` from the per-
-        // render ledger and emit each as a `render_event` wire frame
-        // BEFORE the per-channel stream-buffer replay. Consumers dispatch
-        // by `event.type` to fold the wire-frame-equivalent handler
-        // (push/props_update/etc.) — same cursor model as the HTTP
-        // `/api/renders/:id/events?sinceSequence=N` endpoint.
-        //
-        // Horizon gate: a cursor below the server's replay horizon OR
-        // above `lastSequence` (stale from a different deployment) emits
-        // an error frame with `code: 'REPLAY_HORIZON_PASSED'` and skips
-        // the replay. Client recovery: re-mount from a fresh /state read.
-        if (payload.sinceSequence !== undefined) {
-            const sinceSeq = payload.sinceSequence;
-            if (sinceSeq < 0 || !Number.isInteger(sinceSeq)) {
-                sendError(ws, "INVALID_SINCE_SEQUENCE", "sinceSequence must be a non-negative integer", message.requestId);
-            }
-            else {
-                const ledger = await opts.renderStore.listEventsSince(session.id, sinceSeq, 
-                // Server-side cap matches the HTTP route's default (100).
-                // Stress + replay-from-zero workloads cap here.
-                100);
-                if (ledger === null) {
-                    // Session disappeared between resolve and ledger read —
-                    // already handled by the broader error envelope path; nothing
-                    // to do here.
-                }
-                else if (sinceSeq > ledger.lastSequence || sinceSeq < ledger.horizonSeq) {
-                    sendError(ws, "REPLAY_HORIZON_PASSED", `cursor ${sinceSeq} is outside replayable range [${ledger.horizonSeq}, ${ledger.lastSequence}]`, message.requestId, { currentSequence: ledger.lastSequence });
-                }
-                else {
-                    for (const event of ledger.events) {
-                        // RenderEvent is now the wire-shape ledger primitive
-                        // (Wave 7 of flatten-render-identity, 2026-05-28); no
-                        // projection — emit the store's row directly.
-                        send(ws, {
-                            type: "render_event",
-                            payload: event,
-                        });
-                    }
-                }
-            }
-        }
-        // Send replay frames AFTER the ack. Ordering by `seq` ASC — the
-        // buffer returns them pre-sorted. Client sees ack(streamSeq=N) →
-        // up to N replay `data` frames → live tail (seq > N). No explicit
-        // "replay end" marker is needed; the client uses envelope.seq as
-        // the single source of truth for ordering.
-        if (replay) {
-            for (const env of replay.envelopes) {
-                send(ws, { type: "data", payload: env });
-            }
-        }
-    }
-    async function onMessage(ws, raw) {
-        const sub = subscribersByWs.get(ws);
-        let message;
-        try {
-            message = JSON.parse(raw);
-        }
-        catch {
-            sendError(ws, "INVALID_JSON", "Message is not valid JSON");
-            return;
-        }
-        if (!message || typeof message !== "object" || typeof message.type !== "string") {
-            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 session. Identity was already resolved at upgrade
-                // time; we just need to register the subscriber.
-                const identity = pendingIdentity.get(ws);
-                if (!identity) {
-                    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 session the cookie was issued for. A valid cookie for
-                // session A can't be used to open session B.
-                const cookieBound = pendingCookieBinding.get(ws);
-                if (cookieBound) {
-                    if (message.payload.renderId !== cookieBound.renderId) {
-                        sendError(ws, "DEVTOOL_COOKIE_SESSION_MISMATCH", `Embedded-ui cookie is bound to session '${cookieBound.renderId}' but subscribe targets '${message.payload.renderId}'`, message.requestId);
-                        return;
-                    }
-                    if (message.payload.appId !== cookieBound.appId) {
-                        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 handleSubscribe(ws, identity, message);
-                pendingIdentity.delete(ws);
-                pendingCookieBinding.delete(ws);
-                return;
-            }
-            case "ping":
-                send(ws, {
-                    type: "pong",
-                    payload: {},
-                    ...(message.requestId ? { requestId: message.requestId } : {}),
-                });
-                return;
-            case "close":
-                // Explicit close from client — unregister + close the socket.
-                if (sub)
-                    unregister(ws);
-                ws.close(1000, "client_close");
-                return;
-            case "action":
-                if (!sub) {
-                    sendError(ws, "NOT_SUBSCRIBED", "Send a 'subscribe' message first before 'action'", message.requestId);
-                    return;
-                }
-                await handleInboundAction(ws, sub, message);
-                return;
-            case "channel_subscribe":
-                if (!sub) {
-                    sendError(ws, "NOT_SUBSCRIBED", "Send a 'subscribe' message first before 'channel_subscribe'", message.requestId);
-                    return;
-                }
-                await 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;
-                }
-                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 `Session.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 applySessionPatch(sub.renderId, sub.appId, message.type, {
-                    hostContext: message.payload.hostContext,
-                    lastActivityAt: Date.now(),
-                });
-                return;
-            case "feedback":
-                // Require an active subscription for operational messages.
-                if (!sub) {
-                    sendError(ws, "NOT_SUBSCRIBED", `Send a 'subscribe' message first before '${message.type}'`, message.requestId);
-                    return;
-                }
-                // These OSS channel handlers land incrementally once the
-                // matching shared handlers exist in @ggui-ai/mcp-server-handlers.
-                // For now the ingress point is documented but rejected with a
-                // clear code so clients don't assume silent success.
-                sendError(ws, "NOT_IMPLEMENTED", `'${message.type}' not yet handled on the OSS channel server`, message.requestId);
-                return;
-            default:
-                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 session-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.renderId === bound.renderId`
-     * so a valid cookie can't be used to open a session 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);
-        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");
-            onMessage(ws, text).catch((err) => {
-                opts.logger.error("session_channel_message_failed", {
-                    error: String(err),
-                });
-            });
-        });
-        ws.on("close", () => {
-            unregister(ws);
-            pendingIdentity.delete(ws);
-        });
-        ws.on("error", (err) => {
-            opts.logger.warn("session_channel_socket_error", { error: String(err) });
-        });
-    });
-    return {
-        path,
-        handleUpgrade(req, socket, head) {
-            resolveIdentityFromUpgrade(req)
-                .then((identity) => {
-                // Stash identity on the request so the 'connection' handler
-                // can wire it onto the socket. This is the standard ws
-                // per-request piggyback pattern.
-                req.__gguiIdentity = identity;
-                wss.handleUpgrade(req, socket, head, (ws) => {
-                    // Expose `upgradeReq` for the connection handler.
-                    wss.emit("connection", ws, req);
-                });
-            })
-                .catch((err) => {
-                if (err instanceof UnauthenticatedError) {
-                    opts.logger.warn("session_channel_auth_failed", {
-                        reason: err.message,
-                    });
-                    socket.write("HTTP/1.1 401 Unauthorized\r\n" +
-                        "Connection: close\r\n" +
-                        "Content-Type: text/plain\r\n\r\n" +
-                        "Unauthorized: " +
-                        err.message +
-                        "\r\n");
-                }
-                else {
-                    opts.logger.error("session_channel_upgrade_failed", {
-                        error: String(err),
-                    });
-                    socket.write("HTTP/1.1 500 Internal Server Error\r\n" + "Connection: close\r\n\r\n");
-                }
-                socket.destroy();
-            });
-        },
-        async sendToSession(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 opts.renderStore.get(delivery.renderId);
-            const activeEntry = stored?.render;
-            const streamSpec = activeEntry !== undefined && activeEntry.type !== "mcpApps" && activeEntry.type !== "system"
-                ? activeEntry.streamSpec
-                : undefined;
-            assertStreamContract(streamSpec, delivery.channel, delivery.payload, opts.extraReservedValidators);
-            return fanOut(delivery, streamSpec);
-        },
-        notifyRenderPush(renderId, render, matchType) {
-            // Best-effort fan-out to every live subscriber bound to this
-            // render. NOT routed through the replay buffer — see the
-            // `notifyRenderPush` JSDoc on the 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 renderId; N is typically 1-2 (multi-tab render sharing).
-            const payload = matchType !== undefined ? { render, matchType } : { render };
-            for (const sub of wsSubscribers) {
-                if (sub.renderId !== renderId)
-                    continue;
-                send(sub.ws, { type: "render", payload });
-            }
-        },
-        async primeStreams(renderId, render) {
-            const router = opts.wiredActionRouter;
-            const streamSpec = "streamSpec" in render ? render.streamSpec : undefined;
-            if (!router || !streamSpec)
-                return;
-            const timeoutMs = opts.wiredActionTimeoutMs ?? DEFAULT_WIRED_TOOL_TIMEOUT_MS;
-            // Build the same wired-action ctx the dispatcher uses.
-            // Prime-time invocations reuse the seam so a refresh tool that
-            // fires `sendPropsUpdate` on cold-start works the same way as
-            // one fired post-action.
-            const wiredCtx = {
-                renderId,
-                sendPropsUpdate(props) {
-                    void sendPropsUpdateImpl(renderId, props);
-                },
-            };
-            for (const [channelName, channelEntry] of Object.entries(streamSpec)) {
-                const refreshTool = channelEntry?.tool;
-                if (!refreshTool)
-                    continue;
-                if (!router.has(refreshTool)) {
-                    opts.logger.warn("render_channel_prime_tool_not_found", {
-                        renderId,
-                        toolName: refreshTool,
-                        channel: channelName,
-                    });
-                    continue;
-                }
-                let output;
-                try {
-                    output = await invokeWithTimeout(router, refreshTool, EMPTY_REFRESH_INPUT, wiredCtx, timeoutMs);
-                }
-                catch (err) {
-                    opts.logger.warn("render_channel_prime_tool_failed", {
-                        renderId,
-                        toolName: refreshTool,
-                        channel: channelName,
-                        error: String(err),
-                    });
-                    continue;
-                }
-                try {
-                    assertStreamContract(streamSpec, channelName, output, opts.extraReservedValidators);
-                }
-                catch (err) {
-                    opts.logger.warn("render_channel_prime_schema_violation", {
-                        renderId,
-                        toolName: refreshTool,
-                        channel: channelName,
-                        error: String(err),
-                    });
-                    continue;
-                }
-                try {
-                    await fanOut({
-                        renderId,
-                        channel: channelName,
-                        mode: channelEntry?.mode ?? "append",
-                        payload: output,
-                    }, streamSpec);
-                }
-                catch (err) {
-                    opts.logger.error("render_channel_prime_emit_failed", {
-                        renderId,
-                        toolName: refreshTool,
-                        channel: channelName,
-                        error: String(err),
-                    });
-                }
-            }
-        },
-        sendPropsUpdate(renderId, props) {
-            // Public entry point — delegates to the closure-level impl that
-            // the wired-action dispatcher's `WiredActionContext.sendPropsUpdate`
-            // also calls. Returns the impl's promise so the caller can await
-            // store-lookup completion if desired (the wiredCtx call site
-            // fire-and-forgets via `void`).
-            return sendPropsUpdateImpl(renderId, props);
-        },
-        sendDrainAck({ renderId, appId, eventId, drainedAt }) {
-            // Server-side fan-out for the action-drain ack.
-            // Filter the flat WS-subscriber set by renderId (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 wsSubscribers) {
-                if (sub.renderId !== renderId)
-                    continue;
-                send(sub.ws, {
-                    type: "drain_ack",
-                    payload: { renderId, appId, eventId, drainedAt },
-                });
-            }
-        },
-        externalBroadcast(renderId, frame) {
-            // Walk the flat subscriber set; filter to matching renderId.
-            // `send()` already guards closed sockets and logs (but doesn't
-            // throw on) per-subscriber failures, so the caller (a cloud
-            // pubsub on-message handler) can't be made to fail by a dead
-            // WebSocket. No RenderStore lookup — the publisher already
-            // validated; this seam is the cross-pod delivery path, not the
-            // re-validation point.
-            for (const sub of wsSubscribers) {
-                if (sub.renderId !== renderId)
-                    continue;
-                send(sub.ws, frame);
-            }
-        },
-        get subscriberCount() {
-            return wsSubscribers.size;
-        },
-        get sessionCount() {
-            // Distinct session count across live WS subscribers. With
-            // multi-tab sessions, two subscribers may share a renderId —
-            // dedupe before counting.
-            const sessions = new Set();
-            for (const sub of wsSubscribers)
-                sessions.add(sub.renderId);
-            return sessions.size;
-        },
-        async close() {
-            // Close every open socket + drain its StreamFanout subscription.
-            // `wss.close` terminates the server but not in-flight sockets,
-            // so walk them explicitly. Each `iter.return()` unregisters
-            // the subscriber from the seam (idempotent on the in-process impl).
-            //
-            // Close code 1012 ("Service Restart", RFC 6455 + IANA registry)
-            // signals to clients that the server is restarting and they
-            // should reconnect immediately rather than treat the close as
-            // permanent. The pod's K8s rolling update fits this exactly:
-            // a new pod is already accepting connections behind the same
-            // load balancer; iframe-runtime + console viewer should
-            // reconnect on next message instead of blinking "disconnected".
-            // Code 1001 (used previously) means "endpoint going away" with
-            // no reconnect hint — semantically inaccurate for the pod-roll
-            // case and the wrong signal for client reconnect logic.
-            const sessions = new Set();
-            for (const sub of wsSubscribers) {
-                sessions.add(sub.renderId);
-                try {
-                    sub.ws.close(1012, "service_restart");
-                }
-                catch {
-                    /* best-effort */
-                }
-                void sub.iter.return?.();
-            }
-            wsSubscribers.clear();
-            // Defensive: also close any sessions on the seam that no longer
-            // have local WS subscribers (e.g. orphaned sessions from a partial
-            // unregister race). For InProcessStreamFanout this is a no-op
-            // when there are no subscribers; for hosted bindings it ensures
-            // the per-session pub/sub channel teardown fires.
-            await Promise.all(Array.from(sessions, (renderId) => streamFanout.close(renderId).catch(() => {
-                /* best-effort */
-            })));
-            await new Promise((resolve) => {
-                wss.close(() => resolve());
-            });
-        },
-    };
-}
-/** Fabricate a request id for live-channel ops so logs correlate. */
-export function newRequestId() {
-    return randomUUID();
-}