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

package/dist/ggui-session-channel/action-ingress.js

@@ -0,0 +1,228 @@
+/**
+ * Inbound `action` ingress + consume bridge for the live channel —
+ * contract enforcement on user gestures arriving over WS, the
+ * dual-write onto the retained event ledger + the pending-events pipe
+ * (`ggui_consume`'s queue), and the ack carrying the ledger seq back
+ * to the client.
+ */
+import { assertActionContract } from "@ggui-ai/mcp-server-handlers/renders";
+import { ContractViolationError } from "@ggui-ai/protocol";
+import { randomBytes } from "node:crypto";
+/**
+ * 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 `ComponentGguiSession` is active).
+ */
+function resolveActiveGguiSession(render) {
+    if (!render)
+        return undefined;
+    if (render.type === "mcpApps" || render.type === "system")
+        return undefined;
+    return render;
+}
+/**
+ * Stamp the `tool` hint onto a `data:submit` envelope's
+ * `ActionEventValue` payload before it persists onto the retained
+ * event ledger (`user.submitted`).
+ *
+ * The hint derives server-side from the active render's
+ * `actionSpec[action].nextStep` — the single authoritative source —
+ * and only fills the gap when the inbound payload carries no `tool`
+ * of its own. It rides the LEDGER copy only (operator surfaces —
+ * console timeline, inspector feeds — read it); the consume-pipe
+ * entry is the relay-identical {@link ConsumeEventEntry}, which
+ * carries no tool slot — the agent reads `nextStep` from the
+ * contract it authored.
+ *
+ * Pass-through (returns the envelope unchanged) when:
+ *   - the envelope is not `data:submit`,
+ *   - no `ComponentGguiSession` is active (mcpApps / system),
+ *   - the payload lacks a string `action` or already carries a
+ *     non-empty `tool`,
+ *   - the named action declares no `nextStep`.
+ */
+function withDerivedToolHint(envelope, activeItem) {
+    if (envelope.type !== "data:submit" || !activeItem)
+        return envelope;
+    if (activeItem.type === "mcpApps" || activeItem.type === "system")
+        return envelope;
+    const payload = envelope.payload;
+    if (payload === null ||
+        payload === undefined ||
+        typeof payload !== "object" ||
+        Array.isArray(payload)) {
+        return envelope;
+    }
+    if (typeof payload.action !== "string" || payload.action.length === 0)
+        return envelope;
+    if (typeof payload.tool === "string" && payload.tool.length > 0)
+        return envelope;
+    const nextStep = activeItem.actionSpec?.[payload.action]?.nextStep;
+    if (typeof nextStep !== "string" || nextStep.length === 0)
+        return envelope;
+    return { ...envelope, payload: { ...payload, tool: nextStep } };
+}
+/**
+ * Project an accepted `data:submit` {@link ActionEnvelope} onto the
+ * canonical {@link ConsumeEventEntry} shape the pending-events pipe
+ * stores — the SAME shape `ggui_runtime_submit_action`'s dispatch
+ * branch appends, so `ggui_consume` drains WS-originated gestures
+ * and tools/call-relayed gestures identically.
+ *
+ * Field mapping:
+ *   - `intent`     ← `payload.action` (the actionSpec key).
+ *   - `actionData` ← `payload.data ?? null` (already validated by
+ *     {@link assertActionContract} when a spec is declared).
+ *   - `uiContext`  ← `{}` — WS clients don't mirror a contextSpec
+ *     snapshot (that's the iframe-runtime observer's job); the empty
+ *     object is the type's canonical "no slots mirrored" value.
+ *   - `actionId`   ← server-minted 8-hex correlation id. The WS wire
+ *     envelope carries none (only the iframe-runtime computes a
+ *     gesture-side FNV-1a hash); minting here keeps the pipe entry's
+ *     `drain_ack` keying well-formed.
+ *   - `firedAt`    ← server clock — the WS envelope deliberately
+ *     carries no client timestamp (see {@link ActionEnvelope}).
+ *
+ * Returns `null` when the payload lacks a non-empty string `action`
+ * (possible only on spec-less renders, where the contract gate is
+ * permissive) — there is no intent to key the entry on, so the
+ * gesture stays ledger-only.
+ */
+function toConsumeEventEntry(envelope, sessionId) {
+    const payload = envelope.payload;
+    if (payload === null ||
+        payload === undefined ||
+        typeof payload !== "object" ||
+        Array.isArray(payload)) {
+        return null;
+    }
+    const action = payload.action;
+    if (typeof action !== "string" || action.length === 0)
+        return null;
+    return {
+        type: "action",
+        sessionId,
+        intent: action,
+        actionData: payload.data ?? null,
+        uiContext: {},
+        actionId: randomBytes(4).toString("hex"),
+        firedAt: new Date().toISOString(),
+    };
+}
+export function createActionIngress(deps) {
+    async function handleInboundAction(ws, sub, message) {
+        const envelope = message.payload;
+        // Spoof guard — envelope.sessionId is REQUIRED on the wire and
+        // MUST match the subscriber's bound render.
+        if (envelope.sessionId !== sub.sessionId) {
+            deps.sendError(ws, "SESSION_MISMATCH", `Action targets render '${envelope.sessionId}' but this socket is subscribed to '${sub.sessionId}'`, message.requestId);
+            return;
+        }
+        const stored = await deps.renderStore.get(sub.sessionId);
+        if (!stored) {
+            deps.sendError(ws, "SESSION_NOT_FOUND", `GguiSession ${sub.sessionId} 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 = resolveActiveGguiSession(stored.render);
+        // Contract enforcement: actionSpec payload check via
+        // assertActionContract (data:submit only). Envelope.payload for
+        // data:submit carries the ActionEventValue shape
+        // (`{action, data?, tool?}`).
+        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) {
+                    deps.logger.warn("render_channel_contract_violation", {
+                        sessionId: sub.sessionId,
+                        violations: err.violations,
+                        envelope: "action",
+                    });
+                    deps.sendError(ws, "CONTRACT_VIOLATION", err.message, message.requestId, err.toErrorData());
+                    return;
+                }
+                throw err;
+            }
+        }
+        // Dual-write, mirroring `ggui_runtime_submit_action`'s dispatch
+        // branch (`createGguiSubmitActionHandler`):
+        //
+        //   1. Ledger — `GguiSessionStore.appendEvent` assigns a monotonic
+        //      seq the client acks back with so reconnects can resume via
+        //      `fromSeq`. This retained copy is also the single build site
+        //      for the operator-facing `tool` hint — see
+        //      {@link withDerivedToolHint}.
+        //   2. Pipe — for `data:submit` envelopes, the consume-entry
+        //      projection ({@link toConsumeEventEntry}) lands on the
+        //      pending-events pipe so the agent's `ggui_consume` long-poll
+        //      drains it mid-turn. The ledger and the pipe are two
+        //      different streams (queue vs append-only retained — see
+        //      `pending-event-consumer.ts`); without this write a WS
+        //      gesture would never reach the agent.
+        //
+        // Both writes fire concurrently via `Promise.allSettled` so each
+        // outcome is inspected independently: a ledger rejection is the
+        // load-bearing `APPEND_FAILED` error path (unchanged ack
+        // semantics); a pipe rejection (pipe never opened / already
+        // reaped) degrades to ledger-only with a warn — the WS client has
+        // no `ui/message` fallback to branch on, so a new error frame
+        // would be vocabulary without a consumer.
+        const consumeWrite = (() => {
+            if (deps.pendingEventConsumer === undefined || envelope.type !== "data:submit") {
+                return Promise.resolve();
+            }
+            const entry = toConsumeEventEntry(envelope, sub.sessionId);
+            if (entry === null)
+                return Promise.resolve();
+            return deps.pendingEventConsumer.append(sub.sessionId, {
+                // The pipe entry's stable id doubles as the `drain_ack` key —
+                // same convention as the relay path's iframe-supplied id.
+                id: entry.actionId,
+                envelope: entry,
+                createdAt: entry.firedAt,
+            });
+        })();
+        const [ledgerResult, pipeResult] = await Promise.allSettled([
+            deps.renderStore.appendEvent({
+                sessionId: sub.sessionId,
+                type: "user.submitted",
+                data: withDerivedToolHint(envelope, activeItem),
+            }),
+            consumeWrite,
+        ]);
+        if (pipeResult.status === "rejected") {
+            deps.logger.warn("render_channel_consume_append_failed", {
+                sessionId: sub.sessionId,
+                error: pipeResult.reason instanceof Error
+                    ? pipeResult.reason.message
+                    : String(pipeResult.reason),
+            });
+        }
+        if (ledgerResult.status === "rejected") {
+            const err = ledgerResult.reason;
+            deps.logger.error("render_channel_append_failed", {
+                sessionId: sub.sessionId,
+                error: String(err),
+            });
+            deps.sendError(ws, "APPEND_FAILED", err instanceof Error ? err.message : String(err), message.requestId);
+            return;
+        }
+        const seq = ledgerResult.value;
+        deps.send(ws, {
+            type: "ack",
+            payload: { sequence: seq, timestamp: Date.now() },
+            ...(message.requestId ? { requestId: message.requestId } : {}),
+        });
+    }
+    return { handleInboundAction };
+}

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

@@ -0,0 +1,97 @@
+/**
+ * `channel_subscribe` / source-poll family for the live channel —
+ * server-side polling of `streamSpec[ch].source.tool` for the subset
+ * of tools the operator listed on `streamWebSocketLocalTools`, fanned
+ * to the subscriber as `channel_payload` frames. Includes the
+ * symmetric `channel_unsubscribe` handler; WS close tears down any
+ * remaining polling loops via the subscriber-lifecycle module.
+ */
+import type { GguiSessionStore } from "@ggui-ai/mcp-server-core";
+import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
+import type { WebSocket } from "ws";
+import type { Logger } from "../logger.js";
+import type { Subscriber } from "./internal-types.js";
+import type { Outbound } from "./outbound.js";
+/**
+ * Opt-in plumbing for the `channel_subscribe` polling loop. When this
+ * field is set on `GguiSessionChannelOptions`, channel subscribes
+ * whose `source.tool` is in {@link 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.
+ */
+export interface GguiSessionChannelLocalToolsOptions {
+    /**
+     * Whitelist of `source.tool` names this channel can poll. Must mirror
+     * the value the host advertises on
+     * `handshake.serverCapabilities.streamWebSocketLocalTools` so the
+     * iframe + server agree on which channels use the WS fan-out path.
+     * Tools NOT in this list are rejected with `CHANNEL_NOT_LOCAL` (the
+     * iframe falls back to direct polling).
+     */
+    readonly allowlist: readonly string[];
+    /**
+     * Synchronous resolver invoked at poll time. Returns the tool's
+     * structured output (validated against `streamSpec[ch].schema`
+     * client-side; server-side schema validation is deferred to the
+     * future `validateContract` slice). Implementations typically
+     * delegate to the same in-process tool registry that backs `/mcp`.
+     *
+     * Throwing surfaces `POLL_FAILED` on the subscriber's
+     * `channel_error` channel without canceling the poll loop —
+     * transient tool failures are recoverable.
+     */
+    invoke(name: string, input: unknown): Promise<unknown>;
+    /**
+     * Optional poll cadence policy. `defaultMs` applies when the client
+     * doesn't supply a `pollIntervalMs`; `floorMs`/`ceilingMs` clamp
+     * client-supplied values. Defaults:
+     * `{floorMs: 1000, ceilingMs: 60000, defaultMs: 10000}`.
+     */
+    readonly pollCadence?: {
+        readonly floorMs?: number;
+        readonly ceilingMs?: number;
+        readonly defaultMs?: number;
+    };
+}
+export interface ChannelSubscriptionsDeps {
+    readonly logger: Logger;
+    readonly renderStore: GguiSessionStore;
+    /**
+     * Channel-subscribe local-tool poll plumbing, straight from
+     * `GguiSessionChannelOptions.streamWebSocketLocalTools`. Absent ⇒
+     * all channel subscribes reject with `CHANNEL_NOT_LOCAL`.
+     */
+    readonly localTools: GguiSessionChannelLocalToolsOptions | undefined;
+    /**
+     * ws → subscriber reverse index — the zombie-timer guard reads it at
+     * callback fire-time to self-clean intervals that outlived their
+     * subscriber.
+     */
+    readonly subscribersByWs: WeakMap<WebSocket, Subscriber>;
+    readonly send: Outbound["send"];
+    readonly sendChannelError: Outbound["sendChannelError"];
+}
+export interface ChannelSubscriptions {
+    /**
+     * 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
+     * `${sessionId}:${channelName}` — a re-subscribe replaces any
+     * existing interval rather than running two in parallel.
+     */
+    handleChannelSubscribe(ws: WebSocket, sub: Subscriber, message: WebSocketMessage & {
+        type: "channel_subscribe";
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    handleChannelUnsubscribe(ws: WebSocket, sub: Subscriber, message: WebSocketMessage & {
+        type: "channel_unsubscribe";
+    }): void;
+}
+export declare function createChannelSubscriptions(deps: ChannelSubscriptionsDeps): ChannelSubscriptions;
+//# sourceMappingURL=channel-subscriptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel-subscriptions.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/channel-subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAA4B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C;;;;;;;GAOG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,mCAAmC,GAAG,SAAS,CAAC;IACrE;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,sBAAsB,CACpB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;OAKG;IACH,wBAAwB,CACtB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,GAC1D,IAAI,CAAC;CACT;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAiQ/F"}

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

@@ -0,0 +1,224 @@
+/**
+ * `channel_subscribe` / source-poll family for the live channel —
+ * server-side polling of `streamSpec[ch].source.tool` for the subset
+ * of tools the operator listed on `streamWebSocketLocalTools`, fanned
+ * to the subscriber as `channel_payload` frames. Includes the
+ * symmetric `channel_unsubscribe` handler; WS close tears down any
+ * remaining polling loops via the subscriber-lifecycle module.
+ */
+import { sanitizeCausedBy } from "@ggui-ai/protocol";
+/**
+ * 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 GguiSessionChannelLocalToolsOptions.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;
+export function createChannelSubscriptions(deps) {
+    // Poll plumbing resolved once at composition so the
+    // `channel_subscribe` handler doesn't pay the option-spread cost per
+    // request.
+    const localTools = deps.localTools;
+    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;
+    /**
+     * 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;
+            deps.send(sub.ws, {
+                type: "channel_payload",
+                payload: {
+                    sessionId: sub.sessionId,
+                    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;
+            deps.sendChannelError(sub.ws, sub.sessionId, state.channelName, "POLL_FAILED", err instanceof Error ? err.message : String(err), undefined, 
+            // causedBy slot — the raw stack is redacted (Bearer tokens,
+            // query-param secrets, env-var dumps, 2 KB truncation) before
+            // it reaches the wire; raw `err.stack` verbatim is a
+            // credential-leak footgun.
+            sanitizeCausedBy(err instanceof Error ? err.stack ?? err.message : String(err)));
+            deps.logger.warn("render_channel_channel_poll_failed", {
+                sessionId: sub.sessionId,
+                appId: sub.appId,
+                channelName: state.channelName,
+                toolName: state.toolName,
+                error: String(err),
+            });
+        }
+    }
+    async function handleChannelSubscribe(ws, sub, message) {
+        const payload = message.payload;
+        // sessionId match — the spoof guard at every wire-input boundary.
+        // A subscriber bound to render A can't drive a subscribe for
+        // render B even if they crafted the inbound payload.
+        if (payload.sessionId !== sub.sessionId) {
+            deps.sendChannelError(ws, payload.sessionId, payload.channelName, "SUBSCRIBE_UNAUTHORIZED", `Subscriber is bound to render '${sub.sessionId}' but channel_subscribe targets '${payload.sessionId}'`, 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) {
+            deps.sendChannelError(ws, payload.sessionId, 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 deps.renderStore.get(payload.sessionId);
+        if (!stored || stored.id !== sub.sessionId) {
+            deps.sendChannelError(ws, payload.sessionId, payload.channelName, "SESSION_NOT_FOUND", `GguiSession '${payload.sessionId}' not found on subscriber '${sub.sessionId}'`, 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) {
+            deps.sendChannelError(ws, payload.sessionId, payload.channelName, "CHANNEL_UNKNOWN", `streamSpec['${payload.channelName}'] not declared OR has no source.tool on render '${payload.sessionId}'`, message.requestId);
+            return;
+        }
+        const sourceTool = channelEntry.source.tool;
+        if (!localToolsAllowlist.has(sourceTool)) {
+            deps.sendChannelError(ws, payload.sessionId, 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.sessionId}:${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 || !deps.subscribersByWs.has(sub.ws)) {
+                clearInterval(timer);
+                return;
+            }
+            void pollChannelOnce(sub, live);
+        }, pollIntervalMs);
+        const state = {
+            pollIntervalMs,
+            toolName: sourceTool,
+            sessionId: payload.sessionId,
+            channelName: payload.channelName,
+            args: mergedArgs,
+            seq: 0,
+            timer,
+        };
+        sub.channelSubs.set(channelKey, state);
+        deps.logger.info("render_channel_channel_subscribe", {
+            sessionId: sub.sessionId,
+            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);
+    }
+    function handleChannelUnsubscribe(_ws, sub, message) {
+        const payload = message.payload;
+        if (payload.sessionId !== sub.sessionId) {
+            // No-op silently — the canonical "spoof guard" code path is in
+            // channel_subscribe; unsubscribe gets no error frame to avoid
+            // leaking cross-render existence.
+            return;
+        }
+        const channelKey = `${payload.sessionId}:${payload.channelName}`;
+        const existing = sub.channelSubs.get(channelKey);
+        if (!existing)
+            return;
+        clearInterval(existing.timer);
+        sub.channelSubs.delete(channelKey);
+        deps.logger.info("render_channel_channel_unsubscribe", {
+            sessionId: sub.sessionId,
+            appId: sub.appId,
+            channelName: payload.channelName,
+        });
+    }
+    return { handleChannelSubscribe, handleChannelUnsubscribe };
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Internal shared types for the live-channel handler modules. NOT part
+ * of the package's public surface — everything publishable is exported
+ * (or re-exported) from `../ggui-session-channel.ts`.
+ */
+import type { AuthResult, BufferedStreamEnvelope } from "@ggui-ai/mcp-server-core";
+import type { JsonObject } from "@ggui-ai/protocol";
+import type { WebSocket } from "ws";
+/**
+ * A single connected subscriber (one client, one render). Held live in
+ * the per-channel subscriber map; torn down on socket close or explicit
+ * `close` message.
+ */
+export interface Subscriber {
+    readonly ws: WebSocket;
+    readonly sessionId: string;
+    readonly appId: string;
+    readonly identity: AuthResult;
+    readonly connectedAt: number;
+    /**
+     * Largest outbound `seq` the initial replay (or subscribe snapshot)
+     * covered for this subscriber. Live fan-out skips envelopes with
+     * `seq <= replayCompletedSeq` to prevent double delivery — those
+     * were (or will be) delivered via the replay phase.
+     *
+     * For fresh subscribers (no `fromSeq`), this is the stream cursor
+     * at subscribe time; they never see the pre-existing buffer, only
+     * new deliveries.
+     */
+    readonly replayCompletedSeq: number;
+    /**
+     * Per-subscriber live-tail iterator from `streamFanout.subscribe`.
+     * Owned by the subscriber for its full lifetime; ending it (via
+     * `iter.return()`) terminates the pump loop AND unregisters from
+     * the StreamFanout. `unregister(ws)` is the single point that
+     * does this teardown.
+     */
+    readonly iter: AsyncIterator<BufferedStreamEnvelope>;
+    /**
+     * Active `channel_subscribe` polling loops for this subscriber.
+     * Keyed by `${sessionId}:${channelName}` so a reconnect that
+     * re-subscribes to the same (render, channel) pair replaces the
+     * existing timer rather than minting a duplicate (idempotent
+     * semantics on the wire). Torn down en masse by `unregister(ws)` on
+     * WS close.
+     *
+     * Populated by the `channel_subscribe` handler when the composing
+     * host wired a `streamWebSocketLocalTools` allowlist; empty
+     * otherwise.
+     */
+    readonly channelSubs: Map<string, ChannelSubscriptionState>;
+}
+/**
+ * Per-(subscriber, sessionId, channelName) polling-loop state.
+ * Created on `channel_subscribe` accept, torn down on `channel_unsubscribe`
+ * / WS close / re-subscribe-replace.
+ *
+ * Server-side polling of `streamSpec[ch].source.tool` for the
+ * subset of tools the operator listed on `streamWebSocketLocalTools`.
+ * Channels whose `source.tool` isn't in the allowlist are rejected
+ * with `CHANNEL_NOT_LOCAL` so the iframe falls back to direct polling
+ * over the MCP host proxy.
+ */
+export interface ChannelSubscriptionState {
+    /** Server-clamped poll cadence in ms (within configured floor/ceiling). */
+    readonly pollIntervalMs: number;
+    /** Source tool name resolved from `streamSpec[channelName].source.tool`. */
+    readonly toolName: string;
+    /** GguiSession this subscription is bound to (for fan-out scoping). */
+    readonly sessionId: string;
+    /** Channel name (key into `streamSpec`). */
+    readonly channelName: string;
+    /**
+     * Merged args used on each poll call. Layered as `{...source.args,
+     * ...client.args}` so client wins on key collisions — matches the
+     * docstring on `ChannelSubscribePayload.args`.
+     */
+    readonly args: JsonObject;
+    /**
+     * Channel-scoped monotonic counter stamped into every
+     * `channel_payload` frame's `seq`. Starts at 1 and advances per
+     * successful poll for client-side gap detection.
+     */
+    seq: number;
+    /** Active `setInterval` handle — cleared on teardown. */
+    readonly timer: ReturnType<typeof setInterval>;
+}
+/**
+ * Upgrade-time piggyback slots on the Node request object — the
+ * standard ws per-request pattern. The upgrade phase resolves identity
+ * (and, for console-cookie upgrades, the bound render/app) BEFORE the
+ * WebSocket exists, stashes them on the request, and the `connection`
+ * handler picks them up to seed the pre-subscribe bindings.
+ */
+export interface UpgradeBindings {
+    __gguiIdentity?: AuthResult;
+    __gguiCookieBound?: {
+        sessionId: string;
+        appId: string;
+    };
+}
+//# sourceMappingURL=internal-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal-types.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/internal-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACrD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;CAChD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,iBAAiB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D"}

package/dist/ggui-session-channel/internal-types.js

@@ -0,0 +1,6 @@
+/**
+ * Internal shared types for the live-channel handler modules. NOT part
+ * of the package's public surface — everything publishable is exported
+ * (or re-exported) from `../ggui-session-channel.ts`.
+ */
+export {};