@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/session-channel.d.ts

@@ -0,0 +1,651 @@
+/**
+ * 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/session-mutations` 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
+ *     SessionStore as a typed session event.
+ *   - `ping`/`pong` → heartbeat parity with hosted.
+ *   - `close`/socket-close → clean subscriber teardown.
+ *   - `sendToSession(sessionId, 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(stackItemId, 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_push-gated.
+ *     Dev-mode auth (any bearer via existing AuthAdapter) matches the
+ *     `/mcp` endpoint's shape and is operator-replaceable.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { JsonObject, ReservedChannelValidator, SanitizeCausedBy, SessionStackEntry } from '@ggui-ai/protocol';
+import type { AuthAdapter, SessionStore, SessionStreamBuffer, StreamEnvelopeInput, StreamFanout, TelemetrySink } from '@ggui-ai/mcp-server-core';
+import type { Logger } from './logger.js';
+/** Default URL path for the channel endpoint. Operators can override. */
+export declare const DEFAULT_SESSION_CHANNEL_PATH = "/ws";
+/**
+ * Opt-in plumbing for the `channel_subscribe` polling loop. When this
+ * field is set on {@link SessionChannelOptions}, 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 SessionChannelLocalToolsOptions {
+    /**
+     * 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;
+    };
+}
+/**
+ * Bootstrap-auth plumbing for the live-channel endpoint.
+ *
+ * The channel accepts a bootstrap credential on the `subscribe`
+ * message (`SubscribePayload.bootstrap`). When present:
+ *
+ *   1. `verify(token)` is called. Must return the bound
+ *      `{sessionId, appId}` on success, or `null` on any failure
+ *      (invalid sig, expired, wrong kind, replayed, etc.).
+ *   2. The bound `sessionId` MUST match the one on the subscribe
+ *      payload. Mismatches are rejected with a clean error.
+ *   3. On success, the server mints a reconnect credential via
+ *      `issueSessionToken(sessionId, appId)` and returns it in
+ *      `AckPayload.sessionToken`. The iframe stores this for WS
+ *      reconnects via the normal bearer path.
+ *
+ * Bootstrap auth is MUTUALLY EXCLUSIVE with the upstream `AuthAdapter`
+ * bearer path at subscribe time — when a bootstrap token is present,
+ * the identity resolved at the HTTP upgrade is IGNORED in favor of
+ * the bootstrap-derived identity. This is intentional: MCP Apps
+ * iframes don't have a long-lived bearer; the bootstrap IS the auth.
+ */
+/**
+ * Verify failure shape — distinguished so the channel server can map
+ * `'expired'` to `BOOTSTRAP_EXPIRED` (client SHOULD refresh) vs
+ * `'invalid'` to `BOOTSTRAP_INVALID` (client MUST re-handshake).
+ *
+ * G14 (2026-05-23): bootstrap envelopes are no longer single-use. A
+ * signature-valid + unexpired token authenticates EVERY subscribe
+ * within the TTL window; transient WS drops reconnect without a fresh
+ * handshake. Past expiry, the iframe MAY refresh via the
+ * {@link refresh} surface; past the refresh window, fresh handshake.
+ */
+export type SessionChannelBootstrapVerifyResult = {
+    readonly ok: true;
+    readonly sessionId: string;
+    readonly appId: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'expired' | 'invalid';
+};
+/**
+ * Result of {@link SessionChannelBootstrap.refresh}.
+ *
+ *   - `ok: true`: caller swaps the old envelope for `token` and resumes.
+ *   - `ok: false`: caller MUST re-handshake (refresh window closed,
+ *     tampered envelope, etc.).
+ */
+export type SessionChannelBootstrapRefreshResult = {
+    readonly ok: true;
+    readonly token: string;
+    readonly expiresAt: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'window_closed' | 'invalid';
+};
+export interface SessionChannelBootstrap {
+    /**
+     * Verify a `SubscribePayload.bootstrap` token.
+     *
+     * Returns the bound identity on success, or a discriminated failure.
+     * The channel server maps `'expired'` to `BOOTSTRAP_EXPIRED` so the
+     * iframe can branch on refresh-vs-rehandshake, and `'invalid'` to
+     * `BOOTSTRAP_INVALID` for tamper / format / kind failures (no
+     * refresh on those).
+     */
+    verify(token: string): SessionChannelBootstrapVerifyResult;
+    /**
+     * Mint a longer-lived reconnect credential to return in
+     * `AckPayload.sessionToken`. Called only after a successful
+     * `verify()` on a bootstrap subscribe.
+     */
+    issueSessionToken(sessionId: string, appId: string): string;
+    /**
+     * Refresh a (possibly-expired-but-signature-valid) bootstrap envelope
+     * into a new envelope with a fresh TTL. Used by the
+     * `ggui_runtime_refresh_bootstrap` MCP tool — iframes that see their
+     * bootstrap drift out of the TTL window swap in the refreshed
+     * envelope without going back through `ggui_push`.
+     *
+     * Stateless: verifies HMAC against the same secret used at mint,
+     * checks the refresh window against the ORIGINAL `iat`, and mints
+     * a fresh bootstrap envelope bound to the SAME `(sessionId, appId)`.
+     * Past the refresh window the result is `{ok:false, reason:
+     * 'window_closed'}`; tampered envelopes are `{ok:false, reason:
+     * 'invalid'}`.
+     */
+    refresh(token: string): SessionChannelBootstrapRefreshResult;
+}
+/**
+ * Default timeout for a single wired-tool invocation, in ms. Operators
+ * override via {@link SessionChannelOptions.wiredActionTimeoutMs}; the
+ * 30 s ceiling is a honest non-promise: long-running tools MUST design
+ * their own completion path (streaming, polling).
+ */
+export declare const DEFAULT_WIRED_TOOL_TIMEOUT_MS = 30000;
+/**
+ * Opt-in wired-action dispatch surface. When present on a session
+ * channel, `data:submit` envelopes whose declared `actionSpec
+ * [name].tool` resolves against this router fire the named tool
+ * in-process after validation, and the router's return value flows
+ * back onto the session through a refresh-stream emission (see the
+ * {@link import('@ggui-ai/protocol').StreamChannelEntry.tool} field).
+ *
+ * This is the agent-free contract-execution path — "zero agent code"
+ * lands here. In OSS `ggui serve`, the CLI composes a router that
+ * delegates to the same handler bundle `/mcp` uses (ggui-native +
+ * mounts). Hosted deployments that want the same behavior compose
+ * their own.
+ *
+ * Intentionally minimal surface:
+ *   - `has(name)` separates "tool absent" (TOOL_NOT_FOUND envelope,
+ *     recoverable) from "tool handler threw" (TOOL_THREW envelope,
+ *     isolated). The channel server uses the split to pick the error
+ *     code BEFORE invoking.
+ *   - `invoke(name, input)` returns `unknown` — the router doesn't
+ *     impose a shape, the refresh emission validates against the
+ *     declared `streamSpec[*].schema`.
+ *
+ * Thread-safety: implementations MUST tolerate concurrent invocations
+ * for the same or different tools. The session channel fires no retry;
+ * the router's handler is the sole execution.
+ */
+/**
+ * Per-invocation context the wired-action dispatcher hands the router.
+ * The session-channel server constructs this at dispatch time from
+ * the active session + stack item, then closes
+ * `sendPropsUpdate` over the channel's outbound fan-out so the mount
+ * handler can push a `props_update` frame to live subscribers without
+ * routing through a refresh-stream tool.
+ *
+ * Why this is its own type, not threaded through `HandlerContext`:
+ * `HandlerContext` (in `@ggui-ai/mcp-server-handlers`) is the canonical
+ * shape every shared handler — ggui-native AND mounted — accepts. It
+ * stays narrow on purpose (`appId`, `requestId`, optional `apiKeyHash`)
+ * so the surface a host implements is stable. Wired-action runtime
+ * fields (`sessionId`, `stackItemId`, `sendPropsUpdate`) are dispatcher-
+ * specific — only mount tools invoked through the wired-action router
+ * see them, only at dispatch time. Passing them as a third arg to
+ * `invoke` keeps the canonical handler shape untouched and makes
+ * "this code reaches a wired dispatch path" syntactically obvious.
+ *
+ * The composer in `mcp-mounts.ts::composeWiredActionRouterFromMounts`
+ * synthesizes a runtime ctx for the mount handler that satisfies
+ * `HandlerContext` AND structurally carries these wired fields, so a
+ * mount fixture can read `ctx.sendPropsUpdate` / `ctx.stackItemId` from the
+ * same `ctx` argument the canonical `HandlerContext` sig types — no
+ * cast, no widening of the static type.
+ */
+export interface WiredActionContext {
+    /** The session this dispatch is bound to. Sourced from the live
+     * subscriber + the action envelope's spoof-guarded `sessionId`. */
+    readonly sessionId: string;
+    /** The active stack item's stackItemId at dispatch time. Mounts that
+     * fire `sendPropsUpdate` typically pass this verbatim — only a
+     * mount that intentionally targets a sibling stack entry would
+     * pick a different value. */
+    readonly stackItemId: string;
+    /**
+     * Push a `{type:'props_update', payload:{stackItemId, props}}` frame to
+     * every live subscriber bound to this dispatcher's `sessionId`. The
+     * call closes over the `SessionChannelServer.sendPropsUpdate` method,
+     * scoped to the active session for safety — even if a buggy mount
+     * picks a `stackItemId` that doesn't exist on the session, the channel
+     * server's own validation no-ops the fan-out (same posture as
+     * `notifyStackPush` orphan handling).
+     *
+     * Best-effort: per-subscriber send failures are swallowed; a closed
+     * socket is a no-op.
+     */
+    sendPropsUpdate(stackItemId: string, props: JsonObject): void;
+}
+export interface WiredActionRouter {
+    /** Returns `true` when the named tool has a registered handler. Used
+     * to emit a clean `TOOL_NOT_FOUND` envelope before invoking — an
+     * "invoke unknown tool" would throw through router internals, but
+     * the error surface would be less specific. */
+    has(toolName: string): boolean;
+    /**
+     * Invoke the named tool with the given input + per-dispatch wired
+     * context. The channel server wraps this call in a timeout +
+     * try/catch; implementations SHOULD NOT add their own retry or
+     * timeout layer on top.
+     *
+     * `ctx.sendPropsUpdate` is closed over the active session — mounts
+     * fire it to push props to live subscribers without an extra refresh
+     * round-trip. Refresh-stream invocations (the post-action pass that
+     * fires every declared `streamSpec[*].tool`) reuse the SAME ctx —
+     * a refresh tool that wants to emit a props_update can do so, though
+     * the canonical surface is the action tool itself.
+     */
+    invoke(toolName: string, input: Record<string, unknown>, ctx: WiredActionContext): Promise<unknown>;
+}
+export interface SessionChannelOptions {
+    /** Required — the session backing store (typically `InMemorySessionStore`). */
+    readonly sessionStore: SessionStore;
+    /**
+     * 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. Defaults to
+     * `defaultAppIdFromIdentity` — same mapping the `/mcp` endpoint uses.
+     */
+    /** Structured logger. */
+    readonly logger: Logger;
+    /** URL path to mount on. Defaults to `/ws`. */
+    readonly path?: string;
+    /**
+     * Outbound stream replay buffer. Defaults to a fresh
+     * `InMemorySessionStreamBuffer` when omitted — fine for OSS
+     * zero-config / dev. Persistent adapters bind via the same
+     * `SessionStreamBuffer` 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?: SessionStreamBuffer;
+    /**
+     * Live-tail pub/sub for outbound live-channel frames. Defaults to a
+     * fresh `InProcessStreamFanout` (in-memory, single-process). Hosted
+     * deployments bind a `RedisPubSubFanout` here for multi-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.bootstrap` and issues reconnect
+     * credentials in `AckPayload.sessionToken`. When absent, bootstrap
+     * tokens are rejected with `BOOTSTRAP_NOT_SUPPORTED`.
+     */
+    readonly bootstrap?: SessionChannelBootstrap;
+    /**
+     * 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?: SessionChannelCookieAuth;
+    /**
+     * Opt-in wired-action dispatch router. When present, validated
+     * `data:submit` envelopes whose declared `actionSpec[name]
+     * .tool` names a tool the router knows fire the tool in-process and
+     * emit any declared refresh on the session. See
+     * {@link WiredActionRouter}.
+     *
+     * Absent (the default) = the server relays inbound actions to the
+     * session store for agent pickup and emits no synthetic stream
+     * frames. Matches pre-Slice-11.5 behavior — no regression surface.
+     */
+    readonly wiredActionRouter?: WiredActionRouter;
+    /**
+     * Per-call timeout for wired-tool invocations, in milliseconds.
+     * Defaults to {@link DEFAULT_WIRED_TOOL_TIMEOUT_MS} (30 s). Applied
+     * identically to the initial action tool AND to each refresh-stream
+     * tool. On timeout, a `TOOL_TIMEOUT` envelope emits on
+     * `_ggui:contract-error` and the session channel keeps running.
+     */
+    readonly wiredActionTimeoutMs?: number;
+    /**
+     * Override the default sanitizer applied to the stringified original
+     * error before it's written to `ContractErrorPayload.error.causedBy`.
+     *
+     * Defaults to `@ggui-ai/protocol::sanitizeCausedBy` (redacts Bearer
+     * tokens, query-param secrets, common env-var patterns, truncates at
+     * 2KB). Operators running in locked-down environments can pass a
+     * stricter function — e.g., one that returns an empty string to
+     * disable `causedBy` entirely, or one that layers additional
+     * patterns on top of the defaults.
+     *
+     * The contract-error envelope flows on `_ggui:contract-error` with
+     * `replay: 'all'`, so anything that lands in `causedBy` persists in
+     * the session ring buffer and surfaces in SessionInspector. Accepting
+     * raw `err.stack` verbatim is a credential-leak footgun; the default
+     * sanitizer is load-bearing.
+     */
+    readonly sanitizeCausedBy?: SanitizeCausedBy;
+    /**
+     * 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:contract-error`), 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:contract-
+     * error` is always validated via the built-in.
+     */
+    readonly extraReservedValidators?: ReadonlyMap<string, ReservedChannelValidator>;
+    /**
+     * Optional {@link TelemetrySink} for live-channel operational signals
+     * (C12). When present, the channel emits `wired-tool.invoked` events
+     * on successful wired-tool dispatches — operational counts +
+     * durations for OTLP / CloudWatch / Datadog forwarders. Defaults
+     * to {@link NoopTelemetrySink} (swallow silently).
+     *
+     * Deliberately separate from the renderer's client-side
+     * `ObservabilityEvent` surface: same event name, two independent
+     * consumers (backend metrics vs host inspector UI). See C12 plan +
+     * 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?: SessionChannelLocalToolsOptions;
+    /**
+     * 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 session. 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 stack, 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';
+}
+/**
+ * Cookie-based authentication for the live-channel upgrade. Used
+ * exclusively by the same-origin console viewer; see
+ * `console-auth.ts` for the single consumer today.
+ */
+export interface SessionChannelCookieAuth {
+    /**
+     * Read the raw cookie value for THIS server's console cookie
+     * from the incoming request headers. Returns `null` when the
+     * cookie is absent or malformed.
+     */
+    readCookie(headers: import('node:http').IncomingHttpHeaders): string | null;
+    /**
+     * Verify a cookie value and return the bound session/app. Returns
+     * `null` on any failure (signature, expiry, wrong kind). Never
+     * throws.
+     */
+    verify(cookieValue: string): {
+        sessionId: string;
+        appId: string;
+    } | null;
+}
+export interface SessionChannelServer {
+    /** 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 stack item's streamSpec via
+     * `assertStreamContract` before any subscriber receives it.
+     *
+     * Sequencing + replay behavior:
+     *   1. Payload validated against the active stack item's streamSpec.
+     *   2. The replay buffer assigns a session-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
+     *      session, 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).
+     */
+    sendToSession(delivery: StreamEnvelopeInput): Promise<{
+        seq: number;
+    }>;
+    /**
+     * Fan a `{type:'push', payload:{stackItem, matchType?}}` wire frame
+     * to every subscriber currently bound to `sessionId`. Use this to
+     * notify already-subscribed clients about a stack mutation that
+     * happened AFTER they subscribed — the initial `ack.stack` snapshot
+     * covers state at subscribe time only, so without an explicit notify
+     * a second-turn `appendStackItem` is invisible to the live client.
+     *
+     * The `B1` regression context (2026-04-22 QA pass): the chat surface
+     * in `/chat` reuses one session across turns. The first turn's push
+     * subscribed AFTER `appendStackItem` ran, so the ack carried the
+     * entry. The second turn's push appended on the live session — the
+     * subscriber never heard about the new entry, the inline UI slot
+     * stayed in "Waiting for session channel replay…" indefinitely.
+     * `notifyStackPush` closes that gap. Best-effort: per-subscriber
+     * send failures are swallowed (same posture as `sendToSession`).
+     *
+     * NOT durable. Frames are not stamped through the replay buffer —
+     * fresh subscribers still get the current stack via `ack.stack` on
+     * subscribe. A new tab opening mid-session reads the latest stack
+     * from the snapshot; live tabs read the delta from this notify.
+     *
+     * Subscribers received via `register()` are tracked in
+     * `subscribersBySession`; 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
+     * `sessionStore.appendStackItem` resolves so the snapshot a
+     * concurrent fresh subscriber observes still includes the entry.
+     */
+    notifyStackPush(sessionId: string, stackItem: SessionStackEntry, matchType?: string): void;
+    /**
+     * Prime every declared streamSpec channel on `stackItem` that carries a
+     * `tool` refresh hint. Invokes each refresh tool via the bound
+     * wiredActionRouter with the empty refresh input, validates the result
+     * against the channel's schema, and fans it out so subscribers see an
+     * initial value instead of `latest = undefined`.
+     *
+     * Intended for seed-a-session mount paths (console try-live, agent-
+     * initiated bootstraps that append a stack item without a driving
+     * action). Without this, blueprints with `streamSpec[channel].tool`
+     * render their empty-state branch because the channel has no live
+     * delivery — operators see "waiting for data" UI even when the
+     * refresh tool would have produced initial content.
+     *
+     * Same isolation posture as the action-driven refresh pass: one
+     * broken refresh MUST NOT block others; per-channel failures log a
+     * warning but don't throw. No-op when no wiredActionRouter is
+     * configured, when `stackItem.streamSpec` is absent, or when every
+     * channel lacks a `.tool` hint.
+     *
+     * Ordering: callers should invoke AFTER the stack item is persisted
+     * so `sendToSession`'s active-stack-item lookup resolves. The
+     * `try-live` endpoint awaits this before returning the shortCode so
+     * the viewer SPA subscribes with the initial envelope already
+     * buffered on the session's stream-buffer replay state.
+     */
+    primeStreams(sessionId: string, stackItem: SessionStackEntry): Promise<void>;
+    /**
+     * Fan a `{type:'props_update', payload:{stackItemId, props}}` wire frame
+     * to every subscriber currently bound to `sessionId`. Mount tools
+     * dispatched through {@link WiredActionRouter} call this via
+     * `WiredActionContext.sendPropsUpdate` so a wired action that
+     * mutates server-side state can replace renderer props in-place
+     * without going through a refresh-stream tool.
+     *
+     * Validation posture (mirrors `notifyStackPush`'s "best-effort orphan
+     * no-op"):
+     *   1. Look up the session via `sessionStore.get`. Absent → log
+     *      `session_channel_props_update_orphan` and return — the wire
+     *      validator on the renderer side would reject a frame for an
+     *      unknown session anyway.
+     *   2. Look up the target stack entry by `stackItemId` in the loaded
+     *      session's stack. Absent → log
+     *      `session_channel_props_update_pageid_unknown` and return.
+     *   3. 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 `notifyStackPush`'s pattern
+     * (live-only, no replay-buffer stamping). A new subscriber that
+     * connects mid-session reads current `props` from the stack
+     * snapshot delivered in `ack.stack`.
+     *
+     * Schema validation against `propsSpec`: NOT enforced server-side
+     * here. The renderer validates inbound props via
+     * `validateInboundPropsPayload` against the cached
+     * `stackItem.propsSpec` before applying — defense-in-depth at the
+     * receiving boundary. Server-side enforcement is reserved for the
+     * future agent-driven `ggui_update` path; the mount-tool seam is
+     * trusted-runtime today (mounts execute in-process, same trust
+     * boundary as ggui-native handlers).
+     */
+    sendPropsUpdate(sessionId: string, stackItemId: string, props: JsonObject): Promise<void>;
+    /**
+     * Fan a `{type:'drain_ack', payload:{sessionId, appId, stackItemId,
+     * 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 `notifyStackPush` / `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 stackItemId: string;
+        readonly eventId: string;
+        readonly drainedAt: string;
+    }): void;
+    /** Number of live subscribers. Useful for health / debug introspection. */
+    readonly subscriberCount: number;
+    /** Number of distinct sessions with at least one subscriber. */
+    readonly sessionCount: 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 createSessionChannelServer(opts: SessionChannelOptions): SessionChannelServer;
+/** Fabricate a request id for live-channel ops so logs correlate. */
+export declare function newRequestId(): string;
+//# sourceMappingURL=session-channel.d.ts.map

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

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