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

package/dist/ggui-session-channel/subscriber-lifecycle.js

@@ -0,0 +1,123 @@
+/**
+ * WS subscriber lifecycle for the live channel — registration into the
+ * shared subscriber set, the per-subscriber live-tail pump loop, and
+ * the symmetric teardown path (`unregister`) that ends the pump,
+ * unhooks the StreamFanout subscription, and clears every
+ * `channel_subscribe` polling loop the subscriber owned.
+ *
+ * Owns the per-render subscriber counter that drives the
+ * `onFirstSubscriber` / `onLastSubscriberGone` 0↔1 transition hooks —
+ * no other module reads it.
+ */
+export function createSubscriberLifecycle(deps) {
+    /**
+     * Per-render local subscriber count. Drives the
+     * `onFirstSubscriber` / `onLastSubscriberGone` 0↔1 transition hooks
+     * multi-process deployments use for per-render cross-process pub/sub
+     * channel scoping. Distinct from the channel server's `renderCount`
+     * getter — that walks `wsSubscribers` on demand; this map is the
+     * registration-time counter the hooks key off.
+     */
+    const renderCountById = 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;
+                }
+                deps.send(sub.ws, { type: "data", payload: value });
+            }
+        }
+        catch (err) {
+            deps.logger.warn("render_channel_pump_failed", {
+                sessionId: sub.sessionId,
+                error: String(err),
+            });
+        }
+    }
+    function register(sub) {
+        deps.wsSubscribers.add(sub);
+        deps.subscribersByWs.set(sub.ws, sub);
+        // Per-render 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 = renderCountById.get(sub.sessionId) ?? 0;
+        renderCountById.set(sub.sessionId, prevCount + 1);
+        if (prevCount === 0 && deps.onFirstSubscriber) {
+            try {
+                deps.onFirstSubscriber(sub.sessionId);
+            }
+            catch (err) {
+                // Best-effort: a thrown hook MUST NOT corrupt the
+                // wsSubscribers set vs the real socket lifecycle.
+                deps.logger.warn("render_channel_on_first_subscriber_threw", {
+                    sessionId: sub.sessionId,
+                    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 = deps.subscribersByWs.get(ws);
+        if (!sub)
+            return;
+        deps.subscribersByWs.delete(ws);
+        deps.wsSubscribers.delete(sub);
+        // Per-render count bookkeeping + 1→0 hook (symmetric with register).
+        const prevCount = renderCountById.get(sub.sessionId) ?? 0;
+        if (prevCount <= 1) {
+            renderCountById.delete(sub.sessionId);
+            if (prevCount === 1 && deps.onLastSubscriberGone) {
+                try {
+                    deps.onLastSubscriberGone(sub.sessionId);
+                }
+                catch (err) {
+                    deps.logger.warn("render_channel_on_last_subscriber_gone_threw", {
+                        sessionId: sub.sessionId,
+                        error: String(err),
+                    });
+                }
+            }
+        }
+        else {
+            renderCountById.set(sub.sessionId, 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();
+    }
+    return { register, unregister };
+}

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

@@ -0,0 +1,425 @@
+/**
+ * OSS live channel — live render 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
+ * `@ggui-ai/mcp-server-handlers/renders` helpers, so every
+ * deployment of this server family enforces the same contracts.
+ *
+ * Scope:
+ *
+ *   - `subscribe` → auth, resolve-or-create render, register subscriber,
+ *     reply `ack` with the render's current snapshot + sequence.
+ *   - `action` → inbound user action carried as an {@link ActionEnvelope}.
+ *     Gated through `assertActionContract` (payload, for data:submit).
+ *     Persisted to GguiSessionStore as a typed render event.
+ *   - `ping`/`pong` → heartbeat parity with hosted.
+ *   - `close`/socket-close → clean subscriber teardown.
+ *   - `sendToGguiSession(sessionId, data)` → outbound fan-out API for
+ *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
+ *     through `assertStreamContract` before delivery.
+ *
+ * `props_update`: the agent-driven `ggui_update` handler calls
+ * `channel.sendPropsUpdate(sessionId, props)` (wired as its
+ * `propsUpdateNotifier`) to fan a `{type:'props_update'}` frame to
+ * live subscribers. Reaches the renderer's existing `props_update`
+ * branch in `iframe-runtime` and applies new props in-place.
+ *
+ * Not handled here:
+ *
+ *   - Pattern-B daemon-agent notification stream (GET /mcp SSE).
+ *   - Short-lived render-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.
+ *
+ * Module layout: this file owns the public surface (options, server
+ * interface, composer). The handler families live in
+ * `./ggui-session-channel/` as factories taking explicit typed deps:
+ *
+ *   - `outbound.ts` — send/fan-out primitives + the public fan-out
+ *     surfaces (`sendToGguiSession`, `sendPropsUpdate`, …).
+ *   - `subscriber-lifecycle.ts` — register / live-tail pump /
+ *     unregister + the 0↔1 subscriber-count hooks.
+ *   - `subscribe.ts` — upgrade-time identity resolution (bearer /
+ *     bootstrap / console cookie) + the `subscribe` handler.
+ *   - `action-ingress.ts` — `action` contract gate + ledger/pipe
+ *     dual-write + ack.
+ *   - `channel-subscriptions.ts` — `channel_subscribe` source-tool
+ *     polling loops.
+ *   - `socket-router.ts` — `connection` wiring with the per-socket
+ *     inbound ordering chain + the message-type dispatcher.
+ */
+import type { AuthAdapter, AuthResult, PendingEventConsumer, GguiSessionStore, GguiSessionStreamBuffer, StreamEnvelopeInput, StreamFanout, TelemetrySink } from "@ggui-ai/mcp-server-core";
+import type { JsonObject, GguiSession, ReservedChannelValidator } from "@ggui-ai/protocol";
+import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import { type GguiSessionChannelLocalToolsOptions } from "./ggui-session-channel/channel-subscriptions.js";
+import { type GguiSessionChannelBootstrap, type GguiSessionChannelCookieAuth } from "./ggui-session-channel/subscribe.js";
+import type { Logger } from "./logger.js";
+/** Default URL path for the channel endpoint. Operators can override. */
+export declare const DEFAULT_RENDER_CHANNEL_PATH = "/ws";
+export type { GguiSessionChannelLocalToolsOptions } from "./ggui-session-channel/channel-subscriptions.js";
+export type { GguiSessionChannelBootstrap, GguiSessionChannelBootstrapRefreshResult, GguiSessionChannelBootstrapVerifyResult, GguiSessionChannelCookieAuth, } from "./ggui-session-channel/subscribe.js";
+export interface GguiSessionChannelOptions {
+    /** Required — the render backing store (typically `InMemoryGguiSessionStore`). */
+    readonly renderStore: GguiSessionStore;
+    /**
+     * Optional pending-events pipe — the SAME `PendingEventConsumer`
+     * instance the `ggui_consume` handler drains and the
+     * `ggui_runtime_submit_action` relay appends to. When wired, the WS
+     * `action` ingress dual-writes every accepted `data:submit` envelope:
+     *
+     *   1. `renderStore.appendEvent({type:'user.submitted', …})` — the
+     *      append-only retained ledger (load-bearing for the ack `seq`
+     *      and reconnect resume, exactly as before).
+     *   2. `pendingEventConsumer.append(sessionId, {id, envelope,
+     *      createdAt})` — the queue that wakes the agent's `ggui_consume`
+     *      long-poll. The entry mirrors the relay's consume-entry shape
+     *      (`ConsumeEventEntry`), so WS-originated gestures and
+     *      tools/call-relayed gestures drain identically.
+     *
+     * A failed pipe append (e.g. the pipe was never opened because the
+     * render didn't come from `ggui_render`) degrades to ledger-only with
+     * a `render_channel_consume_append_failed` warn — ack semantics are
+     * unchanged either way.
+     *
+     * Absent → ledger-only ingress (audit-only deployments, conformance
+     * harnesses, and composers that registered no `ggui_consume`).
+     * `createGguiServer` threads its shared instance here whenever it
+     * composed the default handler set.
+     */
+    readonly pendingEventConsumer?: PendingEventConsumer;
+    /**
+     * Required — the same `AuthAdapter` the `/mcp` endpoint uses. Any
+     * failure during `subscribe` rejects the upgrade with HTTP 401.
+     */
+    readonly auth: AuthAdapter;
+    /**
+     * Maps resolved identity → tenant appId for subscribes that omit
+     * `payload.appId` (SPEC §12.2 identity-default resolution). Defaults
+     * to `defaultAppIdFromIdentity` — same mapping the `/mcp` endpoint
+     * uses. Token-bound subscribes (wsToken / console cookie) never
+     * consult this seam: their credential already binds the appId.
+     */
+    readonly appIdFromIdentity?: (result: AuthResult) => string;
+    /** Structured logger. */
+    readonly logger: Logger;
+    /** URL path to mount on. Defaults to `/ws`. */
+    readonly path?: string;
+    /**
+     * Outbound stream replay buffer. Defaults to a fresh
+     * `InMemoryGguiSessionStreamBuffer` when omitted — fine for OSS
+     * zero-config / dev. Persistent adapters bind via the same
+     * `GguiSessionStreamBuffer` interface when they land.
+     *
+     * Each channel instance owns its own seq cursor space; sharing a
+     * buffer across two channels in the same process would couple their
+     * sequences in confusing ways.
+     */
+    readonly streamBuffer?: GguiSessionStreamBuffer;
+    /**
+     * Live-tail pub/sub for outbound live-channel frames. Defaults to a
+     * fresh `InProcessStreamFanout` (in-memory, single-process).
+     * Multi-process deployments bind a pubsub-backed `StreamFanout`
+     * implementation (e.g. Redis) behind this seam for cross-process
+     * fan-out.
+     *
+     * The channel server uses the seam to publish every fanout-eligible
+     * envelope and to subscribe one async iterator per WebSocket
+     * subscriber — no in-process Map walk; the seam owns routing.
+     */
+    readonly streamFanout?: StreamFanout;
+    /**
+     * Optional bootstrap-auth plumbing. When present, the channel
+     * accepts `SubscribePayload.wsToken` and issues reconnect
+     * credentials in `AckPayload.sessionToken`. When absent, bootstrap
+     * tokens are rejected with `BOOTSTRAP_NOT_SUPPORTED`.
+     */
+    readonly bootstrap?: GguiSessionChannelBootstrap;
+    /**
+     * Optional console cookie-auth plumbing. When present, the
+     * channel upgrade looks for the configured cookie on the incoming
+     * request. A valid cookie binds the identity as a `builder` and
+     * scopes the subscriber to the cookie's `sessionId` — any
+     * `subscribe.sessionId` mismatch is rejected with
+     * `DEVTOOL_COOKIE_SESSION_MISMATCH`.
+     *
+     * Absent = cookie auth disabled on this channel. Cookies are never
+     * auto-enabled; the server's console composition decides.
+     *
+     * Design boundary: this auth plane is MUTUALLY EXCLUSIVE with
+     * bootstrap auth at upgrade time. When both are configured, the
+     * bootstrap path (via `?bootstrap=` query) wins; cookie is only
+     * consulted for standard upgrades.
+     */
+    readonly cookieAuth?: GguiSessionChannelCookieAuth;
+    /**
+     * Reserved-channel payload validators for channels whose shape is
+     * NOT protocol-owned (Item 4 injection pattern). The primary
+     * consumer is `_ggui:preview` — the server composes a
+     * {@link ReservedChannelValidator} adapting
+     * `@ggui-ai/preview-a2ui::parseServerMessage` so malformed A2UI
+     * frames emitted on the preview channel reject at the fan-out
+     * boundary instead of landing in the subscriber's renderer.
+     *
+     * Lookup inside {@link validateStreamData} consults this map FIRST,
+     * then the protocol-shipped `BUILTIN_RESERVED_VALIDATORS` (which
+     * validates `_ggui:lifecycle`), then falls through to
+     * `{valid: true}` when a known reserved channel has no validator.
+     *
+     * Absent = no `_ggui:preview` validation (documented degradation for
+     * implementations without the preview package); `_ggui:lifecycle`
+     * is always validated via the built-in.
+     */
+    readonly extraReservedValidators?: ReadonlyMap<string, ReservedChannelValidator>;
+    /**
+     * Optional {@link TelemetrySink} for live-channel operational
+     * signals (C12) — operational counts + durations for OTLP /
+     * CloudWatch / Datadog forwarders. Reserved seam: the channel
+     * defines the binding point but emits no signals of its own today;
+     * future operational counts (e.g. subscribe / poll failure rates)
+     * bind here so operator sink wiring composes uniformly with the
+     * server's `server.composed` signal.
+     *
+     * Deliberately separate from the renderer's client-side
+     * `ObservabilityEvent` surface — two independent consumers (backend
+     * metrics vs host inspector UI). See the TelemetrySink docstring
+     * for the sync/lossy contract.
+     */
+    readonly telemetry?: TelemetrySink;
+    /**
+     * Opt-in `channel_subscribe` plumbing for `streamSpec[*].source.tool`
+     * fan-out. When present, channel subscribes whose
+     * `source.tool` is in `allowlist` are accepted and the server begins
+     * polling. When absent, every `channel_subscribe` returns
+     * `CHANNEL_NOT_LOCAL` so the iframe falls back to direct polling via
+     * the MCP host proxy.
+     *
+     * Same `allowlist` MUST be advertised on
+     * `handshake.serverCapabilities.streamWebSocketLocalTools` so iframe
+     * + server agree on which channels use the WS fan-out path.
+     */
+    readonly streamWebSocketLocalTools?: GguiSessionChannelLocalToolsOptions;
+    /**
+     * Protocol-version handshake policy. Governs server behavior when a
+     * subscribe declares a `supportedVersions` list that does NOT
+     * contain this server's {@link PROTOCOL_SCHEMA_VERSION}.
+     *
+     *   - `'reject'` (default): server emits
+     *     `{type:'error', payload.code: 'UPGRADE_REQUIRED'}` AND closes
+     *     the underlying WebSocket. The caller cannot accidentally
+     *     proceed against a version-mismatched render. This is the
+     *     canonical posture for first-party servers.
+     *   - `'advisory'` (opt-out): server emits `UPGRADE_REQUIRED`
+     *     but keeps the connection open — the subscribe stops (no ack,
+     *     no snapshot, no replay). Existing clients that ignore the error
+     *     code continue to interoperate exactly as pre-handshake.
+     *     Use only for controlled migration windows during which
+     *     legacy-version clients must remain attached.
+     *
+     * Absent `payload.supportedVersions` always passes through — the
+     * handshake is fully opt-in on the client side. `serverVersion` is
+     * stamped into every successful ack regardless of policy.
+     *
+     * Switching between `'advisory'` and `'reject'` is a config change,
+     * not a schema change — the wire fields and error code ship
+     * identically in both modes.
+     */
+    readonly versionPolicy?: "advisory" | "reject";
+    /**
+     * Optional hook fired synchronously when the local subscriber count
+     * for `sessionId` transitions 0 → 1 (the first subscriber for that
+     * render connects to this server instance).
+     *
+     * Hosted deployments use this to lazily SUBSCRIBE to the per-render
+     * cross-pod broadcast channel (e.g. Redis pub/sub); OSS has no use
+     * for it (in-process broadcasts already route via
+     * {@link GguiSessionChannelServer.sendPropsUpdate}). Bounding pubsub
+     * fan-in to only renders a pod actually holds connections for is a
+     * correctness requirement, not an optimization — without it every
+     * pod receives every other pod's broadcast for every active render.
+     *
+     * Best-effort: a thrown callback is logged and swallowed.
+     * `register()` MUST NOT fail because of a hook error or the
+     * `wsSubscribers` set would drift out of sync with the real socket
+     * lifecycle.
+     *
+     * Concurrent register/unregister for the same sessionId are serialized
+     * by the channel's single-threaded WS event loop; hook implementations
+     * do not need their own mutex for the 0↔1 transition.
+     */
+    readonly onFirstSubscriber?: (sessionId: string) => void;
+    /**
+     * Optional hook fired synchronously when the local subscriber count
+     * for `sessionId` transitions 1 → 0 (the last subscriber for that
+     * render disconnects).
+     *
+     * Symmetric with {@link onFirstSubscriber}; same best-effort posture
+     * and single-threaded serialization guarantee.
+     */
+    readonly onLastSubscriberGone?: (sessionId: string) => void;
+}
+export interface GguiSessionChannelServer {
+    /** The URL path the channel accepts upgrade requests on. */
+    readonly path: string;
+    /**
+     * Wire this into the HTTP server's `upgrade` event. Rejects with 401
+     * on auth failure; otherwise completes the WS handshake and wires
+     * the subscriber.
+     */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    /**
+     * Deliver a stream envelope to every subscriber of `delivery.sessionId`.
+     *
+     * Outbound fan-out enforcement point — the delivery's `payload` is
+     * validated against the active render's streamSpec via
+     * `assertStreamContract` before any subscriber receives it.
+     *
+     * Sequencing + replay behavior:
+     *   1. Payload validated against the active render's streamSpec.
+     *   2. The replay buffer assigns a render-scoped monotonic `seq` and
+     *      (conditionally) stores the stamped envelope per the channel's
+     *      replay policy (`'none'` skip / `'latest'` single-slot /
+     *      `'all'` FIFO ring).
+     *   3. The stamped envelope fans out to every subscriber for the
+     *      render, skipping any whose initial replay already covered
+     *      this seq (prevents double delivery on reconnect).
+     *
+     * The caller supplies `StreamEnvelopeInput` (no seq); the server
+     * stamps. Returns the stamped `seq` for callers that need to thread
+     * ordering back to their own response (e.g., `ggui_emit`'s wire
+     * output). When the channel's replay policy was `'none'`, seq is
+     * still assigned (so fan-out has a stable cursor) but nothing is
+     * stored — the seq still surfaces here so the caller has the same
+     * shape regardless of replay policy.
+     *
+     * Throws `ContractViolationError` on payload mismatch; transport
+     * errors are logged but not propagated (per-subscriber best-effort).
+     */
+    sendToGguiSession(delivery: StreamEnvelopeInput): Promise<{
+        seq: number;
+    }>;
+    /**
+     * Fan a `{type:'render', payload:{render, matchType?}}` wire frame
+     * to every subscriber currently bound to `sessionId`. Use this to
+     * notify already-subscribed clients about a render-commit that
+     * happened AFTER they subscribed — the initial `ack.render` snapshot
+     * covers state at subscribe time only, so without an explicit notify
+     * a second-turn `commit` is invisible to the live client.
+     *
+     * The `B1` regression context (2026-04-22 QA pass): the chat surface
+     * in `/chat` reuses one render across turns. The first turn's render
+     * subscribed AFTER `commit` ran, so the ack carried the
+     * entry. The second turn's commit landed on the live render — the
+     * subscriber never heard about the new entry, the inline UI slot
+     * stayed in "Waiting for render channel replay…" indefinitely.
+     * `notifyGguiSessionCommit` closes that gap. Best-effort: per-subscriber
+     * send failures are swallowed (same posture as `sendToGguiSession`).
+     *
+     * NOT durable. Frames are not stamped through the replay buffer —
+     * fresh subscribers still get the current render via `ack.render` on
+     * subscribe. A new tab opening mid-render reads the latest render
+     * from the snapshot; live tabs read the delta from this notify.
+     *
+     * Subscribers received via `register()` are tracked in
+     * `subscribersByRender`; this helper iterates the bound set and
+     * skips closed sockets via the `send()` helper's existing guard.
+     * Callers ARE responsible for ordering — call after the underlying
+     * `renderStore.commit` resolves so the snapshot a
+     * concurrent fresh subscriber observes still includes the entry.
+     */
+    notifyGguiSessionCommit(sessionId: string, render: GguiSession, matchType?: string): void;
+    /**
+     * Fan a `{type:'props_update', payload:{sessionId, props}}` wire frame
+     * to every subscriber currently bound to `sessionId`. The agent-driven
+     * `ggui_update` handler calls this (wired as its `propsUpdateNotifier`)
+     * so a props patch replaces renderer props in-place on live
+     * subscribers without waiting for a resubscribe.
+     *
+     * Validation posture (mirrors `notifyGguiSessionCommit`'s "best-effort orphan
+     * no-op"):
+     *   1. Look up the render via `renderStore.get`. Absent → log
+     *      `render_channel_props_update_orphan` and return — the wire
+     *      validator on the renderer side would reject a frame for an
+     *      unknown render anyway.
+     *   2. Iterate the flat WS-subscriber set, filter to subscribers
+     *      whose `sessionId` matches, and `send()` the frame. Closed
+     *      sockets are skipped silently by `send()`.
+     *
+     * NOT routed through StreamFanout — `type: 'props_update'` is a
+     * distinct WebSocket message type, not a stream envelope. Stream
+     * envelopes flow on `data` frames and have a `seq` cursor; props
+     * updates are ephemeral and follow `notifyGguiSessionCommit`'s pattern
+     * (live-only, no replay-buffer stamping). A new subscriber that
+     * connects mid-render reads current `props` from the render
+     * snapshot delivered in `ack.render`.
+     *
+     * Schema validation against `propsSpec`: NOT enforced server-side
+     * here. The `ggui_update` handler validates the patch against the
+     * render's `propsSpec` BEFORE persisting and notifying, and the
+     * renderer re-validates inbound props via
+     * `validateInboundPropsPayload` against the cached
+     * `render.propsSpec` before applying — defense-in-depth at the
+     * receiving boundary.
+     */
+    sendPropsUpdate(sessionId: string, props: JsonObject): Promise<void>;
+    /**
+     * Fan a `{type:'drain_ack', payload:{sessionId, appId,
+     * eventId, drainedAt}}` wire frame to every subscriber currently
+     * bound to `sessionId`.
+     *
+     * Fired by `createGguiConsumeHandler` once per drained
+     * `PendingEvent` so the iframe-runtime can cancel the matching
+     * per-action 10s claim timer + resolve the toast as `consumed`.
+     * Implements the `DrainAckNotifier` contract from
+     * `@ggui-ai/mcp-server-handlers`.
+     *
+     * Same posture as `notifyGguiSessionCommit` / `sendPropsUpdate` — live-only,
+     * no replay-buffer stamping. Subscribers that connect AFTER the
+     * drain see the next consume's snapshot rather than the missed
+     * frame; the iframe's claim timer + atomic-pop primitive backstop
+     * any frame loss.
+     */
+    sendDrainAck(args: {
+        readonly sessionId: string;
+        readonly appId: string;
+        readonly eventId: string;
+        readonly drainedAt: string;
+    }): void;
+    /**
+     * Fan a server-frame to every local WS subscriber bound to
+     * `sessionId`. Skips replay-buffer stamping, GguiSessionStore lookups,
+     * and contract validation — the caller is the one that originally
+     * validated + persisted the underlying mutation. This surface is the
+     * delivery path for already-validated frames that arrived via an
+     * external pubsub layer (e.g. Redis from another process of a
+     * multi-process deployment).
+     *
+     * Internal adapter use only. NOT part of the published ggui
+     * protocol, NOT stable across versions, NOT exposed to MCP / wire
+     * callers. The publisher is responsible for ensuring `frame` is
+     * wire-valid; this method does not re-validate.
+     *
+     * No-op when no local subscriber is bound to `sessionId`. Closed
+     * sockets are skipped silently by the underlying `send()` helper —
+     * same posture as `sendPropsUpdate` / `notifyGguiSessionCommit`. Per-
+     * subscriber send failures are logged but never propagated.
+     */
+    externalBroadcast(sessionId: string, frame: WebSocketMessage): void;
+    /** Number of live subscribers. Useful for health / debug introspection. */
+    readonly subscriberCount: number;
+    /** Number of distinct renders with at least one subscriber. */
+    readonly renderCount: number;
+    /**
+     * Close every live subscriber + the underlying ws server. Idempotent.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Build an OSS live-channel server. The returned object is designed to be
+ * composed into `createGguiServer` — see `server.ts` for the wire-up.
+ */
+export declare function createGguiSessionChannelServer(opts: GguiSessionChannelOptions): GguiSessionChannelServer;
+//# sourceMappingURL=ggui-session-channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ggui-session-channel.d.ts","sourceRoot":"","sources":["../src/ggui-session-channel.ts"],"names":[],"mappings":"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"}