@ggui-ai/iframe-runtime 0.6.3 → 0.7.0

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './m
 export type { RendererBootFailureReason, RendererBootFailedMessage, } from './runtime.js';
 export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, AuthRequiredEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, UiFeedbackEvent, UnknownObservabilityEvent, } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayIncapabilityEvent, UnknownObservabilityEvent, } from './observability.js';
 export { postObservabilityToParent } from './observability.js';
 export type { LifecycleEmitter } from './lifecycle.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

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

@@ -116,7 +116,14 @@ export function mountMcpAppIframe(container, opts) {
                 const result = {
                     protocolVersion: requested,
                     hostInfo: { name: 'ggui-iframe-runtime-embed-host', version: EMBED_HOST_VERSION },
-                    hostCapabilities: {},
+                    // Advertise exactly what the `switch` below implements
+                    // (ggui#440). `serverTools`: the `tools/call` case proxies
+                    // guest tool calls to the MCP server. NOT `message`: there is
+                    // no `ui/message` case here, so a doorbell would be dropped —
+                    // and the runtime now surfaces that to the user rather than
+                    // claiming the gesture reached the agent. If a `ui/message`
+                    // case is ever added, advertise `message` in the same change.
+                    hostCapabilities: { serverTools: {} },
                     hostContext: {
                         locale: opts.locale ??
                             (typeof navigator !== 'undefined' ? navigator.language : 'en-US'),

package/dist/observability.d.ts

@@ -33,7 +33,7 @@ import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
  *
  * @public
  */
-export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | AuthRequiredEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | UiFeedbackEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -61,57 +61,6 @@ export interface SubscribeFailedEvent {
     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 its tool call 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
@@ -152,6 +101,50 @@ export interface ChannelTransportResubscribedEvent {
     readonly sessionId: string;
     readonly channelName: string;
 }
+/**
+ * Fired by the channel-transport router when a polling channel's
+ * `tools/call` fails for a reason the router classifies as STRUCTURAL
+ * — the failure will repeat identically until the underlying
+ * condition changes, so spending a full-cadence poll on it is waste.
+ *
+ * The channel drops to a slower probe cadence; it never stops. That
+ * distinction is the fail-safe: recovery is a property of the running
+ * loop, not of an external nudge, so a host that regains the missing
+ * capability sees its channels come back on their own.
+ *
+ * Emitted ONCE per healthy→degraded transition, never per probe tick
+ * — a channel degraded for an hour emits one event, not 120.
+ *
+ * @public
+ */
+export interface ChannelPollDegradedEvent {
+    readonly kind: 'channel-poll-degraded';
+    readonly sessionId: string;
+    readonly channelName: string;
+    /**
+     * What the router classified. `'relay-incapable'` = the runtime has
+     * confirmed this host cannot relay `tools/call` to the MCP server
+     * (see `RelayIncapableError`), so every poll fails before reaching
+     * the transport.
+     */
+    readonly reason: 'relay-incapable';
+    /** Cadence (ms) the channel probes at while degraded. */
+    readonly probeIntervalMs: number;
+}
+/**
+ * Fired by the channel-transport router when a previously-degraded
+ * channel's `tools/call` succeeds again. The channel returns to its
+ * normal cadence. Emitted once per degraded→healthy transition.
+ *
+ * @public
+ */
+export interface ChannelPollRecoveredEvent {
+    readonly kind: 'channel-poll-recovered';
+    readonly sessionId: string;
+    readonly channelName: string;
+    /** Cadence (ms) the channel returns to. */
+    readonly pollIntervalMs: number;
+}
 /**
  * Fired when the end user submits the runtime's in-iframe UI-feedback
  * affordance ("did this generated UI work for you?"). Field semantics
@@ -190,6 +183,37 @@ export interface UiFeedbackEvent {
     /** Tool that produced the render (e.g. `ggui_render`). */
     readonly toolName?: string;
 }
+/**
+ * Fired at the two transition edges of the renderer's
+ * relay-incapability latch — the runtime's confirmed determination
+ * that the host cannot relay `tools/call` to the MCP server:
+ *
+ *   - `'latched'` — a real user gesture just failed relay-shaped (no
+ *     well-formed result envelope came back at all) on a host whose
+ *     captured capability handshake never advertised `serverTools`.
+ *     The runtime now treats relay as confirmed-unavailable: it shows
+ *     one persistent explanation instead of a per-gesture error toast,
+ *     and channel polls fail fast without a transport round-trip.
+ *   - `'cleared'` — a later well-formed result envelope arrived
+ *     (`ok:true` and `ok:false` alike — either proves the host relayed
+ *     the call there and back), so the determination no longer holds;
+ *     per-gesture feedback and channel transport attempts resume.
+ *
+ * Emitted once per edge, never per channel poll tick: repeated failing
+ * gestures while latched emit nothing further, and the router's
+ * fail-fast ticks emit nothing at all — the edges carry the full
+ * information.
+ *
+ * Always emitted via the postMessage-to-parent default — the emission
+ * sites live in module-level gesture-dispatch code outside the boot
+ * graph, so they never flow through an injected `onObserve` sink.
+ *
+ * @public
+ */
+export interface RelayIncapabilityEvent {
+    readonly kind: 'relay-incapability';
+    readonly state: 'latched' | 'cleared';
+}
 /**
  * Catch-all branch for event kinds the host's typings don't recognize.
  * Lets the union stay extensible without forcing protocol-version

package/dist/relay-incapability.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Relay-incapability failure vocabulary.
+ *
+ * Two modules need to agree on ONE fact: whether a failed
+ * `tools/call` failed because this host structurally cannot relay
+ * calls to the MCP server, or because something transient went wrong
+ * on an otherwise-working relay.
+ *
+ *   - `runtime.ts` is the THROWER. It owns the relay-incapability
+ *     latch (set only after a real user gesture failed relay-shaped
+ *     on a host that never advertised `serverTools`) and throws
+ *     {@link RelayIncapableError} from `channelToolsCall` before
+ *     spending a transport round-trip.
+ *   - `channel-transport.ts` is the CLASSIFIER. Its poll tick reads
+ *     the thrown value to decide between "back off to a probe
+ *     cadence" and "stay quiet, next tick may succeed".
+ *
+ * The vocabulary lives in its own module rather than in either party
+ * because `runtime.ts` already imports `channel-transport.ts` — a
+ * reverse import would close a cycle. Naming it for the CONCEPT
+ * (relay incapability) rather than for either party keeps the
+ * dependency direction obvious.
+ *
+ * Classification is by type, never by message string: a thrown
+ * `Error` whose text happens to mention relaying is NOT a structural
+ * failure, and re-wording a message must never silently re-classify
+ * a channel.
+ */
+/**
+ * Canonical code carried by {@link RelayIncapableError}.
+ *
+ * Package-internal. Nothing in this module reaches a host: it is not
+ * re-exported from `index.ts`, so an embedding app can neither catch
+ * this class nor read this code. The host-facing surface for the same
+ * information is the `channel-poll-degraded` / `channel-poll-recovered`
+ * observability pair, which IS exported.
+ */
+export declare const RELAY_INCAPABLE = "RELAY_INCAPABLE";
+/**
+ * Thrown when the runtime has CONFIRMED (not merely suspected) that
+ * the surrounding host cannot relay `tools/call` to the MCP server,
+ * so an attempt would be spent for a guaranteed failure.
+ *
+ * "Confirmed" is load-bearing. Absence of an advertised `serverTools`
+ * capability is NOT confirmation — plenty of hosts under-advertise
+ * and relay perfectly well. Only a real gesture that failed
+ * relay-shaped sets the latch this error reports, and any later
+ * well-formed result envelope clears it.
+ *
+ * Consumers MUST classify by `instanceof` (or by `code`), never by
+ * parsing {@link Error.message}.
+ */
+export declare class RelayIncapableError extends Error {
+    /** Canonical classification code. */
+    readonly code: typeof RELAY_INCAPABLE;
+    constructor();
+}
+/**
+ * Type guard for the structural-failure class. Thrower and classifier
+ * are bundled together into one iframe artifact, so `instanceof` is
+ * exact here — there is no module-realm boundary between them to
+ * defend against.
+ */
+export declare function isRelayIncapableError(err: unknown): err is RelayIncapableError;

package/dist/relay-incapability.js

@@ -0,0 +1,69 @@
+/**
+ * Relay-incapability failure vocabulary.
+ *
+ * Two modules need to agree on ONE fact: whether a failed
+ * `tools/call` failed because this host structurally cannot relay
+ * calls to the MCP server, or because something transient went wrong
+ * on an otherwise-working relay.
+ *
+ *   - `runtime.ts` is the THROWER. It owns the relay-incapability
+ *     latch (set only after a real user gesture failed relay-shaped
+ *     on a host that never advertised `serverTools`) and throws
+ *     {@link RelayIncapableError} from `channelToolsCall` before
+ *     spending a transport round-trip.
+ *   - `channel-transport.ts` is the CLASSIFIER. Its poll tick reads
+ *     the thrown value to decide between "back off to a probe
+ *     cadence" and "stay quiet, next tick may succeed".
+ *
+ * The vocabulary lives in its own module rather than in either party
+ * because `runtime.ts` already imports `channel-transport.ts` — a
+ * reverse import would close a cycle. Naming it for the CONCEPT
+ * (relay incapability) rather than for either party keeps the
+ * dependency direction obvious.
+ *
+ * Classification is by type, never by message string: a thrown
+ * `Error` whose text happens to mention relaying is NOT a structural
+ * failure, and re-wording a message must never silently re-classify
+ * a channel.
+ */
+/**
+ * Canonical code carried by {@link RelayIncapableError}.
+ *
+ * Package-internal. Nothing in this module reaches a host: it is not
+ * re-exported from `index.ts`, so an embedding app can neither catch
+ * this class nor read this code. The host-facing surface for the same
+ * information is the `channel-poll-degraded` / `channel-poll-recovered`
+ * observability pair, which IS exported.
+ */
+export const RELAY_INCAPABLE = 'RELAY_INCAPABLE';
+/**
+ * Thrown when the runtime has CONFIRMED (not merely suspected) that
+ * the surrounding host cannot relay `tools/call` to the MCP server,
+ * so an attempt would be spent for a guaranteed failure.
+ *
+ * "Confirmed" is load-bearing. Absence of an advertised `serverTools`
+ * capability is NOT confirmation — plenty of hosts under-advertise
+ * and relay perfectly well. Only a real gesture that failed
+ * relay-shaped sets the latch this error reports, and any later
+ * well-formed result envelope clears it.
+ *
+ * Consumers MUST classify by `instanceof` (or by `code`), never by
+ * parsing {@link Error.message}.
+ */
+export class RelayIncapableError extends Error {
+    /** Canonical classification code. */
+    code = RELAY_INCAPABLE;
+    constructor() {
+        super('tools/call unavailable: host did not advertise serverTools');
+        this.name = 'RelayIncapableError';
+    }
+}
+/**
+ * Type guard for the structural-failure class. Thrower and classifier
+ * are bundled together into one iframe artifact, so `instanceof` is
+ * exact here — there is no module-realm boundary between them to
+ * defend against.
+ */
+export function isRelayIncapableError(err) {
+    return err instanceof RelayIncapableError;
+}

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { DrainAckPayload, GguiSession } from '@ggui-ai/protocol';
+import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type McpAppRendererReadyMessage } from '@ggui-ai/protocol/integrations/mcp-apps';
 import type { GguiSessionSeedInput } from './types.js';
@@ -71,6 +71,19 @@ export interface RendererBootFailedMessage extends McpAppBootstrapFailedMessage
     readonly reason: RendererBootFailureReason;
 }
 export interface BootSequenceOptions {
+    /**
+     * Document the boot path mounts into — the render root, and the
+     * toast announcer's live regions.
+     *
+     * MUST be the global `document` in any real deployment. The toast +
+     * cue surface reads the global directly, and production passes the
+     * global here (see `runBootProduction`), so the two are one object.
+     * A caller handing a DIFFERENT document pre-registers the live
+     * regions somewhere no announcement will ever reach; the surface then
+     * falls back to creating them in the global document at the moment of
+     * the first message, which is precisely the same-tick creation that
+     * loses that first announcement.
+     */
     readonly doc: Document;
     /**
      * Spec-canonical {@link App} instance + its {@link Transport}.
@@ -119,14 +132,17 @@ export interface BootSequenceOptions {
      *     emission on UPGRADE_REQUIRED.
      *   - `subscribe-failed` — forwarded from subscribe's emission on
      *     transient reconnect transitions.
-     *   - `auth-required` — fired by the system channel handler when an
-     *     `auth_required` system frame arrives.
      *   - `channel-transport-*` — fired by the channel-transport router
      *     on per-channel transport picks / fallbacks / resubscribes.
      *
-     * Absent = observability emission skipped entirely (matches the
-     * ProtocolError posture; the `<McpAppIframe>` host wrapper decides
-     * whether to bind this via its `onObserve` prop).
+     * Absent = observability emission for the events above is skipped
+     * entirely (matches the ProtocolError posture; the `<McpAppIframe>`
+     * host wrapper decides whether to bind this via its `onObserve`
+     * prop). Exception: `relay-incapability` events do NOT flow through
+     * this seam — they originate in module-level gesture-dispatch code
+     * outside the boot graph (it runs independently of any given boot
+     * call) and always ride the postMessage-to-parent default, whether
+     * or not this option is bound.
      */
     readonly onObserve?: ObservabilityEmitter;
     /**
@@ -204,9 +220,8 @@ export interface RendererHooks {
      * with `StackRenderer`.
      *
      * `onObserve` — optional observability emitter threaded down to
-     * the channel handlers (system `auth-required`) and the
-     * channel-transport router (`channel-transport-*`). Absent = those
-     * sites run silent (the connect-time emission sites —
+     * the channel-transport router (`channel-transport-*`). Absent =
+     * those sites run silent (the connect-time emission sites —
      * `connectViaRegistry`'s version + subscribe events — still fire
      * via their own emitters).
      */
@@ -271,7 +286,7 @@ export interface RendererHandle {
     /**
      * Channel-client registry holding handlers for every WS frame type
      * the iframe routes (`render`, `data`, `props_update`, `drain_ack`,
-     * `channel_payload`, `channel_error`, `system`). The
+     * `channel_payload`, `channel_error`). The
      * registry-bound transport is the sole dispatch surface — frames
      * arrive directly through registered handlers, no longer through a
      * separate `onMessage` callback.
@@ -391,6 +406,45 @@ export declare function emitAudit(args: {
     readonly actionId: string;
     readonly firedAt: string;
 }): void;
+/**
+ * The announcer's two live regions, keyed by politeness (ggui#447).
+ *
+ * Two regions rather than one with a swapped `aria-live`: politeness is
+ * read when a region is REGISTERED, so a screen reader that already
+ * mapped a node as polite is not guaranteed to notice it turning
+ * assertive in the same mutation that delivers the text. Fixed
+ * politeness per node removes the question.
+ */
+interface ToastLiveRegions {
+    /** `role="status"` — queued behind whatever is being read. */
+    readonly polite: HTMLElement;
+    /** `role="alert"` — interrupts. Failure + action-required classes. */
+    readonly assertive: HTMLElement;
+}
+/**
+ * Ensure the pair of live regions the toast surface announces through.
+ *
+ * MUST be called before the first message can land — a live region
+ * created in the same tick as its first content is a region the screen
+ * reader was never watching, and that first announcement is lost. The
+ * boot path calls this at the same point it mounts the render root, so
+ * every toast (at minimum a user gesture away) lands in a region that
+ * has been registered for many frames. The toast + cue paths call it
+ * again defensively; it is idempotent per document.
+ *
+ * Visually hidden rather than `display:none`: a region that is not
+ * rendered is not in the accessibility tree, and content added to it is
+ * never announced. The clip rectangle keeps it out of the visual layout
+ * while leaving it live.
+ *
+ * Returns `null` when the document has no body yet — nothing to attach
+ * to, and no announcement is possible.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
+/** @internal — exported for unit tests to reset module state. */
+export declare function __resetRelayNoticeForTest(): void;
 /**
  * Dispatch a submit-action via the empirically-validated bridge
  * chain (validated against claude.ai): a `tools/call` to
@@ -411,6 +465,65 @@ export declare function dispatchSubmitAction(args: {
     readonly sessionId: string;
     readonly appId: string;
 }): void;
+/**
+ * Channel-transport router's `tools/call` invoker (ggui#440) —
+ * iframe-polling transport, `tools/call` against the parent MCP host
+ * via `app.callServerTool` (spec-canonical) when the App handle is
+ * set; falls back to raw postMessage pre-handshake or in tests.
+ * Direct call (no LLM consent loop). Returns the tool's
+ * structuredContent (or `content[0]` if that's where the payload
+ * landed) as a `JsonValue`. On RPC error we throw — the router
+ * catches and silently retries on the next tick.
+ *
+ * Once a REAL gesture has confirmed this host can't relay (the latch
+ * above — set only after {@link dispatchSubmitAction} actually tried
+ * and failed on a host with no `serverTools` advertised, with
+ * capabilities already captured, AND the failure was relay-shaped —
+ * not a well-formed `{ok:false}` result; see `isRelayShapedFailure`),
+ * every subsequent poll will fail identically.
+ *
+ * This guard does NOT stop the router's poll loop, and nothing here
+ * should ever be written so that it could (ggui#443). It does two
+ * things. It makes each doomed tick CHEAP — the poll throws before
+ * the `callServerToolSpec` round-trip. And, by throwing the typed
+ * {@link RelayIncapableError} rather than a bare `Error`, it tells
+ * the router WHICH KIND of failure this is: `channel-transport.ts`'s
+ * tick classifies structural rejections apart from transient ones and
+ * drops the channel to a slow probe cadence, emitting one
+ * `channel-poll-degraded` event per transition. The first poll that
+ * succeeds after the latch clears restores the normal cadence and
+ * emits `channel-poll-recovered`.
+ *
+ * The channel keeps probing throughout, which is what makes that
+ * recovery possible: the latch clears only when a call succeeds, and
+ * only an attempt can discover that. A channel stopped on structural
+ * failure could never come back.
+ *
+ * Keyed on the LATCH, not on `hostCanRelayToolCalls()` directly: raw
+ * advertisement absence never changes after boot, so gating on it
+ * here would throw pre-attempt for the LIFE OF THE SESSION on any
+ * host that under-advertises but genuinely proxies `tools/call`
+ * (ggui's own embed host pre-Task-2 is exactly this case) — silently
+ * killing working channel polls forever. That is "absence of a
+ * capability blocks an attempt", which the fail-safe constraint
+ * forbids. The latch implies `!hostCanRelayToolCalls()` (it only
+ * ever sets inside that guard), so testing it alone is sufficient —
+ * a host that never fails a real gesture never latches, and its
+ * channels keep working.
+ *
+ * Extracted to a named export (rather than an inline closure inside
+ * `bootProduction`) so unit tests can drive it directly through the
+ * lightweight `MockTransport` harness — `bootProduction` dynamic-
+ * imports the full react/design/wire module graph, which is too
+ * heavy to exercise from a spec file (see
+ * `boot-production-context.test.ts`'s docstring for precedent).
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export declare function channelToolsCall(args: {
+    readonly toolName: string;
+    readonly args: JsonObject;
+}): Promise<JsonValue>;
 /**
  * Resolve the name of the spec-canonical submit-action receiver tool
  * the dispatch path targets with `tools/call`.