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

package/dist/render-channel.d.ts

@@ -1,694 +0,0 @@
-/**
- * OSS live channel — live session plane over WebSocket.
- *
- * The live channel is where the typed-channel contract is enforced on
- * live traffic between the server and the user. It co-hosts on the
- * same Express server as `/mcp` and reuses the same
- * `@ggui-ai/mcp-server-handlers/renders` helpers that the
- * closed hosted server consumes.
- *
- * Scope:
- *
- *   - `subscribe` → auth, resolve-or-create session, register subscriber,
- *     reply `ack` with the session's current stack + sequence.
- *   - `action` → inbound user action carried as an {@link ActionEnvelope}.
- *     Gated through `assertEventAllowed` (allowlist) +
- *     `assertActionContract` (payload, for data:submit). Persisted to
- *     RenderStore as a typed session event.
- *   - `ping`/`pong` → heartbeat parity with hosted.
- *   - `close`/socket-close → clean subscriber teardown.
- *   - `sendToSession(renderId, data)` → outbound fan-out API for
- *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
- *     through `assertStreamContract` before delivery.
- *
- * `props_update`: mount handlers dispatched through the wired-action
- * router can call `ctx.sendPropsUpdate(renderId, props)` to fan a
- * `{type:'props_update'}` frame to live subscribers without going
- * through a refresh-stream path. Reaches the renderer's existing
- * `props_update` branch in `iframe-runtime` and applies new props
- * in-place. This seam is scoped to mount tools; the agent-driven
- * `ggui_update` path is handled separately.
- *
- * Not handled here:
- *
- *   - Pattern-B daemon-agent notification stream (GET /mcp SSE).
- *   - Short-lived session-token mint/consume — that's ggui_render-gated.
- *     Dev-mode auth (any bearer via existing AuthAdapter) matches the
- *     `/mcp` endpoint's shape and is operator-replaceable.
- */
-import type { AuthAdapter, RenderStore, SessionStreamBuffer, StreamEnvelopeInput, StreamFanout, TelemetrySink } from "@ggui-ai/mcp-server-core";
-import type { JsonObject, Render, ReservedChannelValidator, SanitizeCausedBy } 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 { Logger } from "./logger.js";
-/** Default URL path for the channel endpoint. Operators can override. */
-export declare const DEFAULT_RENDER_CHANNEL_PATH = "/ws";
-/**
- * Opt-in plumbing for the `channel_subscribe` polling loop. When this
- * field is set on {@link RenderChannelOptions}, 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 RenderChannelLocalToolsOptions {
-    /**
-     * 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
- *      `{renderId, appId}` on success, or `null` on any failure
- *      (invalid sig, expired, wrong kind, replayed, etc.).
- *   2. The bound `renderId` 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(renderId, appId)` and returns it in
- *      `AckPayload.renderToken`. 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 RenderChannelBootstrapVerifyResult = {
-    readonly ok: true;
-    readonly renderId: string;
-    readonly appId: string;
-} | {
-    readonly ok: false;
-    readonly reason: "expired" | "invalid";
-};
-/**
- * Result of {@link RenderChannelBootstrap.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 RenderChannelBootstrap {
-    /**
-     * 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): RenderChannelBootstrapVerifyResult;
-    /**
-     * Mint a longer-lived reconnect credential to return in
-     * `AckPayload.renderToken`. Called only after a successful
-     * `verify()` on a bootstrap subscribe.
-     */
-    issueSessionToken(renderId: 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_render`.
-     *
-     * 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 `(renderId, 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 RenderChannelOptions.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 (`renderId`, `renderId`, `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.renderId` from the
- * same `ctx` argument the canonical `HandlerContext` sig types — no
- * cast, no widening of the static type.
- */
-export interface WiredActionContext {
-    /** The render this dispatch is bound to. Sourced from the live
-     * subscriber + the action envelope's spoof-guarded `renderId`. */
-    readonly renderId: string;
-    /**
-     * Push a `{type:'props_update', payload:{renderId, props}}` frame to
-     * every live subscriber bound to this dispatcher's `renderId`. The
-     * call closes over the `RenderChannelServer.sendPropsUpdate` method,
-     * scoped to the active render for safety.
-     *
-     * Best-effort: per-subscriber send failures are swallowed; a closed
-     * socket is a no-op.
-     */
-    sendPropsUpdate(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 RenderChannelOptions {
-    /** Required — the render backing store (typically `InMemoryRenderStore`). */
-    readonly renderStore: RenderStore;
-    /**
-     * 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.renderToken`. When absent, bootstrap
-     * tokens are rejected with `BOOTSTRAP_NOT_SUPPORTED`.
-     */
-    readonly bootstrap?: RenderChannelBootstrap;
-    /**
-     * 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 `renderId` — any
-     * `subscribe.renderId` 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?: RenderChannelCookieAuth;
-    /**
-     * 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 RenderInspector. 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?: RenderChannelLocalToolsOptions;
-    /**
-     * 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";
-    /**
-     * Optional hook fired synchronously when the local subscriber count
-     * for `renderId` transitions 0 → 1 (the first subscriber for that
-     * session connects to this server instance).
-     *
-     * Hosted deployments use this to lazily SUBSCRIBE to the per-session
-     * cross-pod broadcast channel (e.g. Redis pub/sub); OSS has no use
-     * for it (in-process broadcasts already route via
-     * {@link RenderChannelServer.sendPropsUpdate}). Bounding pubsub
-     * fan-in to only sessions 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 session.
-     *
-     * 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 renderId 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?: (renderId: string) => void;
-    /**
-     * Optional hook fired synchronously when the local subscriber count
-     * for `renderId` transitions 1 → 0 (the last subscriber for that
-     * session disconnects).
-     *
-     * Symmetric with {@link onFirstSubscriber}; same best-effort posture
-     * and single-threaded serialization guarantee.
-     */
-    readonly onLastSubscriberGone?: (renderId: string) => void;
-}
-/**
- * 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 RenderChannelCookieAuth {
-    /**
-     * 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): {
-        renderId: string;
-        appId: string;
-    } | null;
-}
-export interface RenderChannelServer {
-    /** 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.renderId`.
-     *
-     * 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:'render', payload:{render, matchType?}}` wire frame
-     * to every subscriber currently bound to `renderId`. 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.
-     * `notifyRenderPush` 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 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
-     * `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
-     * `renderStore.commit` resolves so the snapshot a
-     * concurrent fresh subscriber observes still includes the entry.
-     */
-    notifyRenderPush(renderId: string, render: Render, matchType?: string): void;
-    /**
-     * Prime every declared streamSpec channel on `render` 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-render mount paths (console try-live, agent-
-     * initiated bootstraps that mint a render 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 `render.streamSpec` is absent, or when every
-     * channel lacks a `.tool` hint.
-     *
-     * Ordering: callers should invoke AFTER the render is persisted
-     * so `sendToSession`'s active-render 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 render's stream-buffer replay state.
-     */
-    primeStreams(renderId: string, render: Render): Promise<void>;
-    /**
-     * Fan a `{type:'props_update', payload:{renderId, props}}` wire frame
-     * to every subscriber currently bound to `renderId`. 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 `notifyRenderPush`'s "best-effort orphan
-     * no-op"):
-     *   1. Look up the session via `renderStore.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 `renderId` 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 `renderId` 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 `notifyRenderPush`'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
-     * `render.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(renderId: string, props: JsonObject): Promise<void>;
-    /**
-     * Fan a `{type:'drain_ack', payload:{renderId, appId, renderId,
-     * eventId, drainedAt}}` wire frame to every subscriber currently
-     * bound to `renderId`.
-     *
-     * 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 `notifyRenderPush` / `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 renderId: string;
-        readonly appId: string;
-        readonly eventId: string;
-        readonly drainedAt: string;
-    }): void;
-    /**
-     * Fan a server-frame to every local WS subscriber bound to
-     * `renderId`. Skips replay-buffer stamping, RenderStore lookups,
-     * and contract validation — the caller is the one that originally
-     * validated + persisted the underlying mutation. This surface is the
-     * cloud adapter's path for delivering already-validated frames that
-     * arrived via an external pubsub layer (Redis from another pod).
-     *
-     * 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 `renderId`. Closed
-     * sockets are skipped silently by the underlying `send()` helper —
-     * same posture as `sendPropsUpdate` / `notifyRenderPush`. Per-
-     * subscriber send failures are logged but never propagated.
-     */
-    externalBroadcast(renderId: string, frame: WebSocketMessage): 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 createRenderChannelServer(opts: RenderChannelOptions): RenderChannelServer;
-/** Fabricate a request id for live-channel ops so logs correlate. */
-export declare function newRequestId(): string;
-//# sourceMappingURL=render-channel.d.ts.map