@ggui-ai/iframe-runtime 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `@ggui-ai/iframe-runtime` package entry — type-export surface for
+ * non-iframe consumers (host apps, the `<McpAppIframe>` wrapper,
+ * tests). The runtime artifact is `dist/iframe-runtime.js` (built by
+ * `esbuild.config.mjs` from `src/runtime.ts`); this index does NOT
+ * re-export the runtime side-effects.
+ *
+ * Surface:
+ *   - `BootstrapParseFailureReason` — closed union of bootstrap-parse
+ *     failure reasons.
+ *   - `BootstrapParseResult` — discriminated union returned by
+ *     `parseBootstrap()`.
+ *   - `parseBootstrap` — the parser itself (consumers wanting to
+ *     validate a bootstrap before spawning the iframe).
+ *   - `RendererBootFailureReason` / `RendererBootFailedMessage` — the
+ *     postMessage envelope shape parents observe on boot failure.
+ *   - `ProtocolError` — canonical typed union for every failure
+ *     the renderer classifies outward, wired to the postMessage
+ *     envelope and the `_ggui:contract-error` WS channel.
+ *   - `BootstrapFailureReason` — extensibly-closed union of every
+ *     reason the 'bootstrap' variant can carry. Consolidates
+ *     parse-time and post-parse codes in one place.
+ *   - `ProtocolErrorEmitter` — function signature for the
+ *     caller-side sink.
+ *
+ * Deliberately NOT exported: `RendererWebSocketManager`, `subscribe`,
+ * `bootSequence`, `StackModel`. Those are the renderer's INTERNAL
+ * runtime contract and should not become a load-bearing public API.
+ */
+export type { BootstrapParseFailureReason, BootstrapParseResult, } from './types.js';
+export { parseBootstrap, parseBootstrapFromUiInitialize, parseBootstrapFromGlobal, parseBootstrapFromToolResult, validateBootstrapMeta, } from './bootstrap.js';
+export type { RendererBootFailureReason, RendererBootFailedMessage, SelfContainedBootstrap, } from './runtime.js';
+export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
+export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromContractErrorPayload, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, WiredToolInvokedEvent, ContractErrorEmittedEvent, SchemaVersionMismatchEvent, SubscribeFailedEvent, AuthRequiredEvent, UnknownObservabilityEvent, } from './observability.js';
+export { postObservabilityToParent } from './observability.js';
+export type { LifecycleEmitter } from './lifecycle.js';
+export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { parseBootstrap, parseBootstrapFromUiInitialize, parseBootstrapFromGlobal, parseBootstrapFromToolResult, validateBootstrapMeta, } from './bootstrap.js';
+export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromContractErrorPayload, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
+export { postObservabilityToParent } from './observability.js';
+export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Renderer-side emission of MCP App lifecycle events — the postMessage
+ * envelope the iframe posts to its parent on every mount-state
+ * transition. Mirrors the `<McpAppIframe>` host's outer-DOM mirror
+ * (`data-ggui-mcp-app-iframe-lifecycle="<state>"`); together they form
+ * a first-class wire surface so observers (E2E tests, accessibility
+ * scanners, third-party hosts, console inspectors) can read mount
+ * state without reaching into iframe-internal DOM.
+ *
+ * Lives here (not in `runtime.ts`) so spec-level tests can import the
+ * helper without dragging in the runtime's autostart side effects.
+ *
+ * **Producer obligations** (locked by
+ * {@link import('@ggui-ai/protocol/integrations/mcp-apps').McpAppLifecycleMessage}):
+ *   - `mounting` MUST fire before bundle eval / first WS attempt.
+ *   - Exactly one terminal state (`code-ready` or `error`) MUST follow
+ *     for every successful boot attempt.
+ *   - `disconnected` MAY follow `code-ready` on WS close; a subsequent
+ *     `code-ready` MAY follow on successful reconnect (not required).
+ *
+ * @public
+ */
+import type { McpAppLifecycleEvent, McpAppLifecycleState } from '@ggui-ai/protocol/integrations/mcp-apps';
+/**
+ * Caller sink for lifecycle events. Mirrors the
+ * {@link import('./observability.js').ObservabilityEmitter} posture —
+ * tests inject a recorder; production binds the postMessage-to-parent
+ * default {@link postLifecycleToParent}.
+ *
+ * Handlers MUST NOT throw — lifecycle events are fire-and-forget. A
+ * throwing handler would mask the underlying state transition (the
+ * renderer has already committed to the new state by the time emit
+ * runs).
+ *
+ * @public
+ */
+export type LifecycleEmitter = (event: McpAppLifecycleEvent) => void;
+/**
+ * Default emitter — posts a {@link McpAppLifecycleMessage} envelope to
+ * `window.parent`. Mirrors `postObservabilityToParent` /
+ * `postBootFailure` posture: swallows postMessage failure when the
+ * parent is unreachable so a detached parent doesn't crash the iframe.
+ *
+ * Non-browser import graphs (vitest+jsdom before a window mock lands)
+ * have no `window.parent`; the early return guards that case so tests
+ * importing this helper can do so before staging their `window` mocks.
+ *
+ * @public
+ */
+export declare function postLifecycleToParent(event: McpAppLifecycleEvent): void;
+/**
+ * Build a lifecycle event payload. Centralises the `state` →
+ * `McpAppLifecycleEvent` projection so call sites in
+ * `runtime.ts` don't repeat the `{state, ...optional}` shape and so
+ * the additive-extension semantic of `stackItemId` / `error` is
+ * single-sourced.
+ *
+ * @public
+ */
+export declare function makeLifecycleEvent(state: McpAppLifecycleState, options?: {
+    readonly stackItemId?: string;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}): McpAppLifecycleEvent;

package/dist/lifecycle.js

@@ -0,0 +1,49 @@
+/**
+ * Default emitter — posts a {@link McpAppLifecycleMessage} envelope to
+ * `window.parent`. Mirrors `postObservabilityToParent` /
+ * `postBootFailure` posture: swallows postMessage failure when the
+ * parent is unreachable so a detached parent doesn't crash the iframe.
+ *
+ * Non-browser import graphs (vitest+jsdom before a window mock lands)
+ * have no `window.parent`; the early return guards that case so tests
+ * importing this helper can do so before staging their `window` mocks.
+ *
+ * @public
+ */
+export function postLifecycleToParent(event) {
+    if (typeof window === 'undefined' || window.parent === null)
+        return;
+    const message = { type: 'ggui:lifecycle', event };
+    try {
+        window.parent.postMessage(message, '*');
+    }
+    catch {
+        // Parent unreachable (detached window) — best-effort fire-and-
+        // forget. Matches postObservabilityToParent's swallow posture.
+    }
+}
+/**
+ * Build a lifecycle event payload. Centralises the `state` →
+ * `McpAppLifecycleEvent` projection so call sites in
+ * `runtime.ts` don't repeat the `{state, ...optional}` shape and so
+ * the additive-extension semantic of `stackItemId` / `error` is
+ * single-sourced.
+ *
+ * @public
+ */
+export function makeLifecycleEvent(state, options) {
+    // Avoid emitting `undefined` keys — the protocol's structural lock
+    // (mcp-apps.test.ts "shape lock") asserts a populated event has
+    // exactly state + stackItemId + error keys, not an Object.keys-
+    // observable `undefined` field.
+    if (options === undefined)
+        return { state };
+    const { stackItemId, error } = options;
+    return {
+        state,
+        ...(typeof stackItemId === 'string' && stackItemId.length > 0
+            ? { stackItemId }
+            : {}),
+        ...(error !== undefined ? { error } : {}),
+    };
+}

package/dist/mcp-app-iframe-host.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Vanilla-TS port of
+ * `@ggui-ai/react::components/McpAppsStackItemRenderer.tsx`. Used
+ * when a ggui stack item's `kind === 'mcpApps'` — the renderer
+ * mounts a nested iframe that embeds a foreign MCP App.
+ *
+ * The iframe plays the MCP Apps HOST role for the embedded content:
+ *
+ *   - `ui/initialize` → respond with minimal context (theme +
+ *     containerDimensions + locale).
+ *   - `tools/call` → forward to the ggui server's
+ *     `/mcp-apps/tools-call` endpoint. The server enforces source
+ *     connector scoping + `_meta.ui.visibility: ['app']`.
+ *   - any other method → respond with `method_not_supported`.
+ *
+ * Adapter-boundary rule (ENFORCED):
+ *   - MCP Apps lifecycle messages from the embedded iframe do NOT
+ *     mutate the outer ggui session state / contracts — the host
+ *     never forwards them to ggui-server as session-level events.
+ *   - `ui/initialize` intentionally DOES NOT forward outer ggui
+ *     session state (stack, actionSpec, streamSpec) to the iframe.
+ *
+ * On detach, a host-initiated `ui/resource-teardown` notification
+ * is posted to the iframe BEFORE the element leaves the DOM so the
+ * embedded app can persist state / release resources cleanly. Post-
+ * detach the contentWindow is null in browsers + jsdom; we cache it
+ * at mount so the teardown message can still reach the view.
+ *
+ * Recursive mount safety: a foreign MCP App loaded inside this
+ * iframe can in turn render a `ui://ggui/session` resource via its
+ * own host implementation. That recursion stays bounded because
+ * each nested iframe runs the same adapter-boundary rule — outer
+ * ggui state never leaks into the inner renderer's session through
+ * this host path. Host-to-host sandboxing is browser-enforced by
+ * the iframe's `sandbox="allow-scripts"` attribute.
+ */
+import type { McpAppsStackItem } from '@ggui-ai/protocol/integrations/mcp-apps';
+export interface McpAppIframeMountOptions {
+    readonly stackItem: McpAppsStackItem;
+    /** Session id — threaded into the proxy URL so server-side
+     *  connector scoping works. */
+    readonly sessionId: string;
+    /**
+     * Base URL of the ggui server (origin). The host appends
+     *  `/mcp-apps/resource` + `/mcp-apps/tools-call` to this. Should
+     *  NOT have a trailing slash. Empty string = same-origin.
+     */
+    readonly serverBaseUrl?: string;
+    /** Optional theme override for the `ui/initialize` context. */
+    readonly theme?: Readonly<Record<string, string>>;
+    /** Optional locale; defaults to `navigator.language` when
+     *  available. */
+    readonly locale?: string;
+}
+export interface McpAppIframeMount {
+    /** Tear down — posts `ui/resource-teardown` then removes the iframe. */
+    unmount(): void;
+    /** The mounted iframe element — exposed for test assertions. */
+    readonly element: HTMLIFrameElement;
+}
+/**
+ * Mount the MCP Apps iframe into `container`. The container is
+ * cleared; the iframe becomes its sole child.
+ *
+ * The host-bridge listener attaches to `window.message` globally;
+ * `source !== iframe.contentWindow` guard ensures we only respond
+ * to our own iframe's messages.
+ */
+export declare function mountMcpAppIframe(container: HTMLElement, opts: McpAppIframeMountOptions): McpAppIframeMount;

package/dist/mcp-app-iframe-host.js

@@ -0,0 +1,214 @@
+/** Default permissive-but-safe theme for iframes that don't override. */
+const DEFAULT_THEME = {
+    '--color-primary': '#0284c7',
+    '--color-surface': '#ffffff',
+    '--color-text': '#111111',
+    '--font-family': 'system-ui, -apple-system, sans-serif',
+    '--border-radius-md': '8px',
+};
+// =============================================================================
+// Helpers
+// =============================================================================
+function composeResourceUrl(opts) {
+    const base = opts.serverBaseUrl.replace(/\/$/, '');
+    const qs = new URLSearchParams({
+        session: opts.sessionId,
+        item: opts.itemId,
+    });
+    return `${base}/mcp-apps/resource?${qs.toString()}`;
+}
+function composeToolsCallUrl(serverBaseUrl) {
+    return `${serverBaseUrl.replace(/\/$/, '')}/mcp-apps/tools-call`;
+}
+function buildSandboxAttr() {
+    // MCP Apps hosts grant the minimum sandbox tokens needed. V1 keeps
+    // us permissive-enough for scripted + form-submitting content but
+    // does NOT grant same-origin (that would let the iframe read the
+    // host document). Ports the host-SDK version verbatim.
+    return 'allow-scripts allow-forms';
+}
+function buildAllowAttr(stackItem) {
+    const perms = stackItem.permissions;
+    if (!perms)
+        return undefined;
+    const parts = [];
+    if (perms.camera)
+        parts.push("camera 'self'");
+    if (perms.microphone)
+        parts.push("microphone 'self'");
+    if (perms.geolocation)
+        parts.push("geolocation 'self'");
+    if (perms.clipboardWrite)
+        parts.push("clipboard-write 'self'");
+    return parts.length > 0 ? parts.join('; ') : undefined;
+}
+// =============================================================================
+// Mount
+// =============================================================================
+/**
+ * Mount the MCP Apps iframe into `container`. The container is
+ * cleared; the iframe becomes its sole child.
+ *
+ * The host-bridge listener attaches to `window.message` globally;
+ * `source !== iframe.contentWindow` guard ensures we only respond
+ * to our own iframe's messages.
+ */
+export function mountMcpAppIframe(container, opts) {
+    container.replaceChildren();
+    const serverBaseUrl = opts.serverBaseUrl ?? '';
+    const resourceUrl = composeResourceUrl({
+        serverBaseUrl,
+        sessionId: opts.sessionId,
+        itemId: opts.stackItem.id,
+    });
+    const toolsCallUrl = composeToolsCallUrl(serverBaseUrl);
+    const dims = {
+        width: opts.stackItem.containerDimensions?.width,
+        height: opts.stackItem.containerDimensions?.height,
+        maxWidth: opts.stackItem.containerDimensions?.maxWidth,
+        maxHeight: opts.stackItem.containerDimensions?.maxHeight,
+    };
+    const iframe = container.ownerDocument.createElement('iframe');
+    iframe.setAttribute('data-ggui-mcp-apps', 'iframe');
+    iframe.setAttribute('data-ggui-stack-item-id', opts.stackItem.id);
+    iframe.setAttribute('data-ggui-connector-id', opts.stackItem.source.connectorId);
+    iframe.src = resourceUrl;
+    iframe.title = opts.stackItem.description ?? 'MCP App';
+    iframe.setAttribute('sandbox', buildSandboxAttr());
+    const allowAttr = buildAllowAttr(opts.stackItem);
+    if (allowAttr !== undefined)
+        iframe.setAttribute('allow', allowAttr);
+    iframe.style.width = dims.width !== undefined ? `${dims.width}px` : '100%';
+    iframe.style.height = dims.height !== undefined ? `${dims.height}px` : '480px';
+    iframe.style.maxWidth = dims.maxWidth !== undefined ? `${dims.maxWidth}px` : '100%';
+    if (dims.maxHeight !== undefined)
+        iframe.style.maxHeight = `${dims.maxHeight}px`;
+    iframe.style.border = '1px solid #e5e5e5';
+    iframe.style.borderRadius = '8px';
+    iframe.style.display = 'block';
+    container.appendChild(iframe);
+    // Cache contentWindow — on detach, `iframe.contentWindow` is null
+    // so the cached handle is the only way `ui/resource-teardown` can
+    // still reach the view.
+    let cachedIframeWindow = iframe.contentWindow;
+    const listener = (ev) => {
+        void handleHostBridgeRequest(ev);
+    };
+    async function handleHostBridgeRequest(ev) {
+        // Adapter-boundary guard: only our own iframe's contentWindow is
+        // allowed. This matches the ref-guard in
+        // McpAppsStackItemRenderer.tsx.
+        if (iframe.contentWindow === null || ev.source !== iframe.contentWindow)
+            return;
+        const req = ev.data;
+        if (req === null || typeof req !== 'object')
+            return;
+        if (req.jsonrpc !== '2.0' || typeof req.method !== 'string')
+            return;
+        const id = req.id ?? 0;
+        let response;
+        switch (req.method) {
+            case 'ui/initialize': {
+                response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        theme: opts.theme ?? DEFAULT_THEME,
+                        containerDimensions: dims,
+                        locale: opts.locale ??
+                            (typeof navigator !== 'undefined' ? navigator.language : 'en-US'),
+                    },
+                };
+                break;
+            }
+            case 'tools/call': {
+                const tool = typeof req.params?.['name'] === 'string' ? req.params['name'] : '';
+                const rawArgs = req.params?.['arguments'];
+                const args = rawArgs !== null && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+                    ? rawArgs
+                    : {};
+                if (tool.length === 0) {
+                    response = {
+                        jsonrpc: '2.0',
+                        id,
+                        error: { code: -32602, message: 'tools/call requires params.name' },
+                    };
+                    break;
+                }
+                try {
+                    const resp = await fetch(toolsCallUrl, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            session: opts.sessionId,
+                            item: opts.stackItem.id,
+                            tool,
+                            arguments: args,
+                        }),
+                    });
+                    if (!resp.ok) {
+                        const body = (await resp.json().catch(() => ({})));
+                        response = {
+                            jsonrpc: '2.0',
+                            id,
+                            error: {
+                                code: resp.status === 403 ? -32003 : -32000,
+                                message: body.error ?? `proxy_error_${resp.status}`,
+                            },
+                        };
+                    }
+                    else {
+                        const result = (await resp.json());
+                        response = { jsonrpc: '2.0', id, result };
+                    }
+                }
+                catch (err) {
+                    response = {
+                        jsonrpc: '2.0',
+                        id,
+                        error: {
+                            code: -32000,
+                            message: `proxy_fetch_failed: ${String(err)}`,
+                        },
+                    };
+                }
+                break;
+            }
+            default: {
+                response = {
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32601, message: 'method_not_supported' },
+                };
+            }
+        }
+        iframe.contentWindow?.postMessage(response, '*');
+    }
+    window.addEventListener('message', listener);
+    return {
+        element: iframe,
+        unmount() {
+            window.removeEventListener('message', listener);
+            // Host-initiated `ui/resource-teardown` — posted BEFORE the
+            // iframe leaves the DOM so its contentWindow is still live.
+            // Post-detach the contentWindow is null; the cached handle is
+            // a belt-and-suspenders fallback.
+            const win = iframe.contentWindow ?? cachedIframeWindow;
+            try {
+                win?.postMessage({
+                    jsonrpc: '2.0',
+                    method: 'ui/resource-teardown',
+                    params: { reason: 'host_unmount' },
+                }, '*');
+            }
+            catch {
+                // Best-effort — teardown notification is a courtesy, not a
+                // correctness contract. A thrown postMessage (detached win)
+                // silently falls through to element removal.
+            }
+            cachedIframeWindow = null;
+            if (iframe.parentNode !== null)
+                iframe.parentNode.removeChild(iframe);
+        },
+    };
+}

package/dist/observability.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Observability events emitted by the renderer iframe → surfaced to
+ * the MCP Apps host via the `<McpAppIframe>` wrapper's `onObserve`
+ * prop. Complementary to `ProtocolError`:
+ *
+ *   - `ProtocolError` fires on FAILURES (typed classification of a
+ *     protocol violation or transport error).
+ *   - `ObservabilityEvent` fires on HAPPY PATHS + failures alike
+ *     (telemetry + inspection signal the host can display in a
+ *     SessionInspector-style view).
+ *
+ * The host wrapper passes events through to `onObserve` opaquely.
+ *
+ * Design:
+ *
+ *   - Discriminated union on `kind`. Each arm carries only the fields
+ *     the event semantically requires — no optional everything-bags.
+ *   - Extensibly closed via the `(string & {})` tail on `kind`. Adding
+ *     a new arm does NOT bump the protocol version —
+ *     hosts built against older typings fall through to the unknown
+ *     branch and MUST render gracefully (e.g., `JSON.stringify(event)`
+ *     fallback in an inspector row).
+ *   - `@ggui-ai/iframe-runtime` owns this union, NOT `@ggui-ai/protocol`.
+ *     Observability events are a renderer ↔ host implementation seam,
+ *     not a wire-format contract between arbitrary protocol peers, so
+ *     they stay out of the protocol package.
+ *
+ * @public
+ */
+export type ObservabilityEvent = WiredToolInvokedEvent | ContractErrorEmittedEvent | SchemaVersionMismatchEvent | SubscribeFailedEvent | AuthRequiredEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | UnknownObservabilityEvent;
+/**
+ * Fired when a wired action successfully dispatched to a registered
+ * MCP tool. Hosts surface this as a dispatch row in SessionInspector.
+ * Emitted by the server-side router (session-channel.ts) via
+ * postMessage relay through the renderer.
+ *
+ * @public
+ */
+export interface WiredToolInvokedEvent {
+    readonly kind: 'wired-tool-invoked';
+    readonly toolName: string;
+    readonly actionName?: string;
+    readonly dispatchedAt: string;
+    readonly latencyMs?: number;
+}
+/**
+ * Fired when the server emits a `_ggui:contract-error` envelope on
+ * the live channel. Mirrors the envelope's `code` field for host-side
+ * inspection without requiring the host to parse channel frames.
+ *
+ * @public
+ */
+export interface ContractErrorEmittedEvent {
+    readonly kind: 'contract-error-emitted';
+    readonly code: string;
+    readonly toolName: string;
+    readonly actionName?: string;
+}
+/**
+ * Fired when the protocol-version handshake rejects the connection.
+ * Parallel to `UpgradeRequiredError` — the host can choose to render
+ * an inline upgrade prompt instead of treating it as a terminal
+ * failure.
+ *
+ * @public
+ */
+export interface SchemaVersionMismatchEvent {
+    readonly kind: 'schema-version-mismatch';
+    readonly observedVersion: string;
+    readonly acceptedVersions: readonly string[];
+    readonly observedBy: 'client' | 'server';
+}
+/**
+ * Fired when subscribe fails for any reason the renderer classifies
+ * as non-fatal to the session (e.g., transient network jitter that
+ * the reconnect ladder is handling). Terminal subscribe failures
+ * still route through `ProtocolError`.
+ *
+ * @public
+ */
+export interface SubscribeFailedEvent {
+    readonly kind: 'subscribe-failed';
+    readonly reason: string;
+    readonly message?: string;
+}
+/**
+ * Fired when the server emits a `system` frame with
+ * `action: 'auth_required'` — the agent needs the end-user to authorize
+ * an OAuth service (Google, Slack, etc.) before a wired tool can
+ * proceed. The host listens via `<McpAppIframe onObserve>` and renders
+ * a consent overlay OUTSIDE the iframe, then redirects the user to
+ * `authUrl` to complete the OAuth flow.
+ *
+ * Observability-only — the wire signal is already fully typed on
+ * `@ggui-ai/protocol`'s `SystemPayload` (live-channel.ts). This event is a
+ * renderer↔host projection of that payload, not a new protocol surface,
+ * matching the vendor-neutral-separation posture of every
+ * other `ObservabilityEvent` kind.
+ *
+ * Fields map 1:1 from `SystemPayload`:
+ *   - `provider` ← `serviceId` (canonical identifier the credential
+ *     store keys off — e.g., `"google"`, `"slack"`).
+ *   - `authUrl` ← `consentUrl` (URL the host opens in a popup / new tab
+ *     to initiate the OAuth consent flow).
+ *   - `displayName` / `scopes` / `message` are optional hints the host
+ *     can surface in the consent overlay; absent means "render with
+ *     generic copy".
+ *
+ * @public
+ */
+export interface AuthRequiredEvent {
+    readonly kind: 'auth-required';
+    /**
+     * Canonical identifier of the service needing authorization (e.g.
+     * `"google"`, `"slack"`). Maps to `SystemPayload.serviceId`.
+     */
+    readonly provider: string;
+    /**
+     * URL the host opens in a popup / new tab to initiate the OAuth
+     * consent flow. Maps to `SystemPayload.consentUrl`.
+     */
+    readonly authUrl: string;
+    /**
+     * Human-readable service name (e.g. `"Google"`, `"Slack"`). Optional
+     * — absent when the server doesn't supply one.
+     */
+    readonly displayName?: string;
+    /**
+     * OAuth scopes the agent is requesting. Optional.
+     */
+    readonly scopes?: readonly string[];
+    /**
+     * Human-readable message explaining why access is needed. Optional.
+     */
+    readonly message?: string;
+}
+/**
+ * Fired by the channel-transport router when it picks a transport
+ * for a `streamSpec[ch].source.tool` channel. Hosts can inspect the
+ * WS-vs-poll decision per channel in the SessionInspector activity
+ * feed.
+ *
+ * @public
+ */
+export interface ChannelTransportPickedEvent {
+    readonly kind: 'channel-transport-picked';
+    readonly stackItemId: string;
+    readonly channelName: string;
+    readonly transport: 'ws' | 'poll';
+}
+/**
+ * Fired by the channel-transport router when a WS-bound channel
+ * falls back to iframe polling. `'ws-disconnect'`
+ * = WS dropped, transient. `'channel-not-local'` = server explicitly
+ * said it can't subscribe-for this tool (sticky for the channel's
+ * lifetime).
+ *
+ * @public
+ */
+export interface ChannelTransportFallbackEvent {
+    readonly kind: 'channel-transport-fallback';
+    readonly stackItemId: string;
+    readonly channelName: string;
+    readonly reason: 'ws-disconnect' | 'channel-not-local';
+}
+/**
+ * Fired by the channel-transport router when it re-sends
+ * `channel_subscribe` for a channel after the WS reconnects.
+ *
+ * @public
+ */
+export interface ChannelTransportResubscribedEvent {
+    readonly kind: 'channel-transport-resubscribed';
+    readonly stackItemId: string;
+    readonly channelName: string;
+}
+/**
+ * Catch-all branch for event kinds the host's typings don't recognize.
+ * Lets the union stay extensible without forcing protocol-version
+ * bumps when new kinds are added. Hosts MUST render unknown events
+ * gracefully — default: show as raw JSON in the inspector.
+ *
+ * @public
+ */
+export interface UnknownObservabilityEvent {
+    readonly kind: string & {};
+    readonly [field: string]: unknown;
+}
+/**
+ * Shape of the postMessage envelope the renderer emits to its parent
+ * when an observability event fires. `<McpAppIframe>` listens for this
+ * and forwards the `event` field to `onObserve`.
+ *
+ * @public
+ */
+export interface ObservabilityMessage {
+    readonly type: 'ggui:observe';
+    readonly event: ObservabilityEvent;
+}
+/**
+ * Caller sink for every {@link ObservabilityEvent} the renderer
+ * classifies. Mirrors the {@link import('./protocol-error.js').ProtocolErrorEmitter}
+ * posture — injection slot so tests can record, production binds a
+ * postMessage-to-parent default.
+ *
+ * Handlers MUST NOT throw. Observability is fire-and-forget — the
+ * renderer has already completed the observed side-effect by the time
+ * the emitter runs; a throwing handler would mask the real signal.
+ *
+ * @public
+ */
+export type ObservabilityEmitter = (event: ObservabilityEvent) => void;
+/**
+ * Default emitter — posts an {@link ObservabilityMessage} to
+ * `window.parent`. Mirrors `postBootFailure` / `postRendererReady`
+ * posture in `runtime.ts`: swallows postMessage failure so a detached
+ * parent doesn't crash the iframe.
+ *
+ * Lives here (not in `runtime.ts`) so tests exercising individual
+ * emission sites can import the same default without dragging in the
+ * runtime's module side-effects.
+ *
+ * @public
+ */
+export declare function postObservabilityToParent(event: ObservabilityEvent): void;