@ggui-ai/iframe-runtime 0.6.3 → 0.7.0

package/dist/channel-transport.d.ts

@@ -54,17 +54,30 @@
  */
 import type { JsonObject, JsonValue, StreamSpec } from '@ggui-ai/protocol';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
-import type { ChannelTransportFallbackEvent, ChannelTransportPickedEvent, ChannelTransportResubscribedEvent } from './observability.js';
+import type { ChannelPollDegradedEvent, ChannelPollRecoveredEvent, ChannelTransportFallbackEvent, ChannelTransportPickedEvent, ChannelTransportResubscribedEvent } from './observability.js';
 import type { StreamBus } from './wire-config.js';
 /**
  * Default polling cadence for the iframe-polling transport (ms).
- * Mirrors the server-side default on
- * {@link DEFAULT_CHANNEL_POLL_DEFAULT_MS} in
- * `packages/mcp-server/src/render-channel.ts`. Conservative: 10s
- * matches a "data is fresh enough" bar without burning the parent
- * host's `tools/call` quota.
+ * Mirrors the server-side default (`DEFAULT_CHANNEL_POLL_DEFAULT_MS`
+ * in `mcp-server/src/ggui-session-channel/channel-subscriptions.ts`).
+ * Conservative: 10s matches a "data is fresh enough" bar without
+ * burning the parent host's `tools/call` quota.
  */
 export declare const DEFAULT_IFRAME_POLL_INTERVAL_MS = 10000;
+/**
+ * Cadence (ms) a channel falls back to once its `tools/call` has
+ * failed STRUCTURALLY — a failure the router knows will repeat
+ * identically on the next tick (see {@link ToolsCallInvoker}).
+ *
+ * Deliberately a slower cadence and NOT a stop. A structural failure
+ * is a statement about the host's current capability, not a permanent
+ * property of the universe: the relay-incapability latch upstream
+ * clears the moment a real call succeeds, and the only thing that can
+ * observe that is an attempt. A stopped channel could never recover
+ * on its own; a slow one recovers within one probe interval, for
+ * ~1/3 the cost of a healthy channel at the 10s default.
+ */
+export declare const DEFAULT_IFRAME_PROBE_POLL_INTERVAL_MS = 30000;
 /**
  * Sender for outbound WS frames. Any structurally-fitting send fn
  * works — post-B3b the registry wires the `@ggui-ai/live-channel`
@@ -74,8 +87,29 @@ export type WsSender = (msg: WebSocketMessage) => void;
 /**
  * Iframe → parent `tools/call` invoker. Resolves with the tool's
  * structured-content output (parsed `JsonValue`) or rejects on
- * transport-level failure. The router will swallow the failure +
- * keep the poll loop running (next tick may succeed).
+ * failure.
+ *
+ * **Rejection contract.** The router classifies every rejection into
+ * exactly two kinds, and the invoker chooses which by the TYPE of the
+ * value it throws:
+ *
+ *   - **Structural** — reject with `RelayIncapableError` (see
+ *     `relay-incapability.ts`). Says: this failed for a reason that
+ *     will repeat identically on the next tick, so polling at full
+ *     cadence buys nothing. The router drops the channel to
+ *     {@link ChannelTransportRouterOptions.probePollIntervalMs} and
+ *     emits `channel-poll-degraded` once.
+ *   - **Transient** — reject with anything else. Says: the next tick
+ *     may well succeed. The router stays quiet and keeps the current
+ *     cadence; per-tick network jitter must not turn into bus noise
+ *     or a cadence change.
+ *
+ * Classification is by type only. An invoker cannot signal structural
+ * failure through an error MESSAGE, and re-wording a message cannot
+ * change how a channel is treated.
+ *
+ * Neither kind ever stops the loop — see
+ * {@link DEFAULT_IFRAME_PROBE_POLL_INTERVAL_MS}.
  */
 export type ToolsCallInvoker = (args: {
     readonly toolName: string;
@@ -102,15 +136,38 @@ export interface ChannelTransportRouterOptions {
     /** StreamBus the router emits envelopes onto. */
     readonly streamBus: StreamBus;
     /**
-     * Default poll cadence (ms) for the iframe-polling transport.
-     * Overridden per-channel via `streamSpec[name].source.pollIntervalMs`
-     * when authored. Falls back to {@link DEFAULT_IFRAME_POLL_INTERVAL_MS}
-     * when neither the spec nor the option supplies one.
+     * Poll cadence (ms) shared by EVERY iframe-polled channel on this
+     * router. Uniform by construction: `StreamChannelEntry.source`
+     * declares `tool` + `args` only, so a contract author has no way to
+     * ask one channel to poll faster than another. Giving channels
+     * individual cadences would be a protocol change (a new contract
+     * field plus server-side clamping — placement, on the channel entry
+     * or on `source`, is still open), not a router option — the
+     * per-subscription `pollIntervalMs` that does exist belongs to the
+     * WS transport's `channel_subscribe` payload, which this polling
+     * fallback never sends.
+     *
+     * Falls back to {@link DEFAULT_IFRAME_POLL_INTERVAL_MS} when
+     * omitted. The only cadence that varies between channels at runtime
+     * is the degraded probe cadence ({@link
+     * ChannelTransportRouterOptions.probePollIntervalMs}), which follows
+     * observed poll health rather than authored config.
      */
     readonly defaultPollIntervalMs?: number;
     /**
-     * Observability sink — fires once per transport pick + once per
-     * disconnect/reconnect-fallback transition. Optional; absent ⇒
+     * Cadence (ms) a channel probes at after a structural poll failure.
+     * Falls back to {@link DEFAULT_IFRAME_PROBE_POLL_INTERVAL_MS}.
+     *
+     * Clamped UP to the channel's normal cadence: degrading must never
+     * make a channel poll MORE often than it did while healthy, which a
+     * naive value would do for any deployment whose normal cadence is
+     * already slower than the probe default.
+     */
+    readonly probePollIntervalMs?: number;
+    /**
+     * Observability sink — fires once per transport pick, once per
+     * disconnect/reconnect-fallback transition, and once per
+     * poll-health transition in each direction. Optional; absent ⇒
      * silent.
      */
     readonly onObserve?: (event: ChannelTransportEvent) => void;
@@ -118,12 +175,12 @@ export interface ChannelTransportRouterOptions {
 /**
  * Observability events the router emits. Hosts that wire `onObserve`
  * see these alongside the renderer's other observability events
- * (`subscribe-failed`, `auth-required`, …). The arm interfaces live in
- * `observability.ts` (they are members of the exported
- * `ObservabilityEvent` union); this alias is the router-scoped subset,
- * so the two surfaces cannot drift.
+ * (`subscribe-failed`, `schema-version-mismatch`, …). The arm
+ * interfaces live in `observability.ts` (they are members of the
+ * exported `ObservabilityEvent` union); this alias is the
+ * router-scoped subset, so the two surfaces cannot drift.
  */
-export type ChannelTransportEvent = ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent;
+export type ChannelTransportEvent = ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent;
 /**
  * Router handle returned by {@link createChannelTransportRouter}.
  */

package/dist/channel-transport.js

@@ -1,12 +1,26 @@
+import { isRelayIncapableError } from './relay-incapability.js';
 /**
  * Default polling cadence for the iframe-polling transport (ms).
- * Mirrors the server-side default on
- * {@link DEFAULT_CHANNEL_POLL_DEFAULT_MS} in
- * `packages/mcp-server/src/render-channel.ts`. Conservative: 10s
- * matches a "data is fresh enough" bar without burning the parent
- * host's `tools/call` quota.
+ * Mirrors the server-side default (`DEFAULT_CHANNEL_POLL_DEFAULT_MS`
+ * in `mcp-server/src/ggui-session-channel/channel-subscriptions.ts`).
+ * Conservative: 10s matches a "data is fresh enough" bar without
+ * burning the parent host's `tools/call` quota.
  */
 export const DEFAULT_IFRAME_POLL_INTERVAL_MS = 10_000;
+/**
+ * Cadence (ms) a channel falls back to once its `tools/call` has
+ * failed STRUCTURALLY — a failure the router knows will repeat
+ * identically on the next tick (see {@link ToolsCallInvoker}).
+ *
+ * Deliberately a slower cadence and NOT a stop. A structural failure
+ * is a statement about the host's current capability, not a permanent
+ * property of the universe: the relay-incapability latch upstream
+ * clears the moment a real call succeeds, and the only thing that can
+ * observe that is an attempt. A stopped channel could never recover
+ * on its own; a slow one recovers within one probe interval, for
+ * ~1/3 the cost of a healthy channel at the 10s default.
+ */
+export const DEFAULT_IFRAME_PROBE_POLL_INTERVAL_MS = 30_000;
 /**
  * Factory.
  *
@@ -23,6 +37,9 @@ export function createChannelTransportRouter(opts) {
     const channels = new Map();
     const allowlist = new Set(opts.streamWebSocketLocalTools ?? []);
     const defaultPollMs = opts.defaultPollIntervalMs ?? DEFAULT_IFRAME_POLL_INTERVAL_MS;
+    // Clamped up — a degraded channel must never poll more eagerly than
+    // a healthy one. See `probePollIntervalMs`.
+    const probePollMs = Math.max(defaultPollMs, opts.probePollIntervalMs ?? DEFAULT_IFRAME_PROBE_POLL_INTERVAL_MS);
     /**
      * WS lifecycle flag. We start in `'connected'` because the router
      * is created AFTER the subscribe ack — the runtime's bootSequence
@@ -53,40 +70,130 @@ export function createChannelTransportRouter(opts) {
         };
         opts.streamBus.emit(envelope);
     }
+    /**
+     * (Re-)arm a channel's recurring timer at `intervalMs`. Only ever
+     * called for a channel that is already polling — never resurrects a
+     * stopped loop.
+     */
+    function armTimer(state, intervalMs) {
+        if (state.pollTimer !== null)
+            clearInterval(state.pollTimer);
+        state.pollTimer = setInterval(() => {
+            void tick(state);
+        }, intervalMs);
+    }
+    /**
+     * Healthy → degraded. Slows the channel to the probe cadence and
+     * announces the transition ONCE.
+     *
+     * No-ops when the channel isn't polling: an in-flight call can
+     * resolve after `stopPolling` (WS payload arrived, channel removed,
+     * router disposed), and a degraded channel with no loop to slow
+     * down is not a transition worth announcing.
+     */
+    function degradePolling(state) {
+        if (state.pollDegraded)
+            return;
+        if (state.pollTimer === null)
+            return;
+        state.pollDegraded = true;
+        armTimer(state, probePollMs);
+        observe({
+            kind: 'channel-poll-degraded',
+            sessionId: state.sessionId,
+            channelName: state.channelName,
+            reason: 'relay-incapable',
+            probeIntervalMs: probePollMs,
+        });
+    }
+    /**
+     * Degraded → healthy. Any successful poll proves the structural
+     * condition has lifted, so the channel returns to its normal
+     * cadence. Announced ONCE per recovery, not per subsequent success.
+     */
+    function restorePolling(state) {
+        if (!state.pollDegraded)
+            return;
+        state.pollDegraded = false;
+        if (state.pollTimer !== null)
+            armTimer(state, defaultPollMs);
+        observe({
+            kind: 'channel-poll-recovered',
+            sessionId: state.sessionId,
+            channelName: state.channelName,
+            pollIntervalMs: defaultPollMs,
+        });
+    }
+    /**
+     * One poll of one channel: call the tool, classify the outcome,
+     * emit the payload.
+     *
+     * The two failure kinds are the `ToolsCallInvoker` rejection
+     * contract, classified by TYPE (never by message text):
+     *
+     *   - Structural (`RelayIncapableError`) — the next tick would fail
+     *     identically, so slow to the probe cadence and say so once.
+     *   - Transient (anything else) — stay quiet and keep the cadence.
+     *     The renderer's observability path already surfaces transport
+     *     failures via the WS error route; per-tool poll failures do
+     *     not also become bus noise during a passing outage.
+     *
+     * Neither kind stops the loop. That is the fail-safe: a channel
+     * whose host regains the ability to relay recovers on its own,
+     * within one probe interval, with no external nudge.
+     */
+    const tick = async (state) => {
+        if (disposed)
+            return;
+        try {
+            const payload = await opts.toolsCall({
+                toolName: state.toolName,
+                args: { ...(state.args ?? {}) },
+            });
+            if (disposed)
+                return;
+            // Restore BEFORE emitting: a throwing bus subscriber must not
+            // be mistaken for a failed poll (it would land in the catch
+            // below and read as transient), and it must not cost this
+            // channel its recovery.
+            restorePolling(state);
+            emitToBus(state, payload);
+        }
+        catch (err) {
+            if (disposed)
+                return;
+            if (isRelayIncapableError(err))
+                degradePolling(state);
+        }
+    };
     /**
      * Start an iframe-polling loop for one channel. Idempotent — if a
      * timer is already running we leave it alone. Fires the first poll
      * IMMEDIATELY (no `setInterval` lead-in delay) so the first
      * `useStream` render isn't blocked on a 10-second wait.
+     *
+     * A channel that was already degraded when its loop last stopped
+     * re-arms at the probe cadence — the condition that degraded it
+     * belongs to the host, and a WS reconnect cycle is no evidence it
+     * has lifted. Only a successful poll is.
      */
     function startPolling(state) {
         if (state.pollTimer !== null)
             return;
-        const tick = async () => {
-            if (disposed)
-                return;
-            try {
-                const payload = await opts.toolsCall({
-                    toolName: state.toolName,
-                    args: { ...(state.args ?? {}) },
-                });
-                if (disposed)
-                    return;
-                emitToBus(state, payload);
-            }
-            catch {
-                // Swallow — next tick may succeed. The renderer's
-                // observability path already surfaces transport failures
-                // via the WS error route; per-tool poll failures stay quiet
-                // to avoid a noisy bus during transient outages.
-            }
-        };
-        // Fire-and-forget the leading tick + schedule the recurring
-        // ticks. Both are wrapped in the `disposed` guard above.
-        void tick();
+        // Arm BEFORE firing the leading tick. `ToolsCallInvoker` is
+        // declared to return a promise, but a non-async implementation
+        // that throws satisfies that type, and its failure reaches the
+        // tick's catch during THIS function's own synchronous execution.
+        // Arming second would leave `pollTimer` null at that moment, and
+        // `degradePolling`'s stopped-channel guard would (correctly, for
+        // what it can see) ignore it — costing the channel a full degrade
+        // cycle. Order here is the only thing that closes that window.
         state.pollTimer = setInterval(() => {
-            void tick();
-        }, defaultPollMs);
+            void tick(state);
+        }, state.pollDegraded ? probePollMs : defaultPollMs);
+        // Fire-and-forget the leading tick. Wrapped in the `disposed`
+        // guard above.
+        void tick(state);
     }
     /**
      * Send a `channel_subscribe` WS frame. Server-side bookkeeping is
@@ -204,6 +311,7 @@ export function createChannelTransportRouter(opts) {
                     pollTimer: null,
                     hasReceivedWsPayload: false,
                     permanentPollFallback: false,
+                    pollDegraded: false,
                 };
                 channels.set(k, state);
                 activate(state);

package/dist/channels/index.d.ts

@@ -3,4 +3,3 @@ export { createDrainAckHandler, type DrainAckHandlerDeps, } from './drain-ack.js
 export { createRenderHandler, type RenderHandlerDeps } from './render-frame.js';
 export { createDataHandler, type DataHandlerDeps } from './data.js';
 export { createChannelPayloadHandler, createChannelErrorHandler, type ChannelRouterHandlerDeps, } from './channel-payload.js';
-export { createSystemHandler, type SystemHandlerDeps } from './system.js';

package/dist/channels/index.js

@@ -3,4 +3,3 @@ export { createDrainAckHandler, } from './drain-ack.js';
 export { createRenderHandler } from './render-frame.js';
 export { createDataHandler } from './data.js';
 export { createChannelPayloadHandler, createChannelErrorHandler, } from './channel-payload.js';
-export { createSystemHandler } from './system.js';

package/dist/host-capabilities.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What can the host we are embedded in actually do? (ggui#440)
+ *
+ * MCP Apps hosts advertise their capabilities on the `ui/initialize`
+ * result. The `App` class captures them; this module is where the
+ * runtime keeps that capture so the two decision points that care —
+ * the gesture-failure explanation and the `ui/message` doorbell — can
+ * consult one source instead of re-deriving it.
+ *
+ * FAIL-SAFE BY CONTRACT: absence of a capability MUST NOT stop the
+ * runtime from attempting the operation. Hosts under-advertise in
+ * practice — ggui's own embed host (`./mcp-app-iframe-host.ts`) proxies
+ * `tools/call` while advertising nothing — so treating silence as
+ * "cannot" would break working paths. These accessors exist to explain
+ * a failure that already happened, never to pre-empt an attempt.
+ *
+ * PRESENCE, NOT VALUE: on `McpUiHostCapabilities` both fields are
+ * optional OBJECTS (`serverTools?: { listChanged?: boolean }`,
+ * `message?: McpUiSupportedContentBlockModalities`). An empty object is
+ * a positive advertisement; `=== true` is never correct here.
+ */
+import type { McpUiHostCapabilities } from "@modelcontextprotocol/ext-apps";
+/**
+ * Record the host's advertised capabilities. Called once at boot, from
+ * `bootSequence`, immediately after `connectApp` resolves — before that
+ * point `App.getHostCapabilities()` returns `undefined`.
+ */
+export declare function setHostCapabilities(caps: McpUiHostCapabilities | undefined): void;
+/**
+ * Did the host advertise that it can proxy a guest `tools/call` to the
+ * MCP server? `false` also covers "we have not connected yet" and "the
+ * host advertised nothing" — callers must treat it as *unconfirmed*,
+ * not as *impossible*.
+ */
+export declare function hostCanRelayToolCalls(): boolean;
+/**
+ * Did the host advertise that it accepts `ui/message` from the view?
+ * This is the only view→host method that can start an agent turn, so a
+ * host without it cannot be woken by the doorbell — the user has to
+ * send a message themselves.
+ */
+export declare function hostCanReceiveMessages(): boolean;
+/**
+ * Has the handshake resolved capabilities at all yet? See {@link captured}.
+ * Callers that treat capability absence as confirmed incapability (as
+ * opposed to merely unconfirmed) must gate on this first — otherwise
+ * the pre-handshake window (where absence is just "not asked yet") is
+ * indistinguishable from a host that answered and advertised nothing.
+ */
+export declare function hostCapabilitiesCaptured(): boolean;
+/** @internal — exported for unit tests to reset module state. */
+export declare function __resetHostCapabilitiesForTest(): void;

package/dist/host-capabilities.js

@@ -0,0 +1,54 @@
+let hostCapabilities;
+/**
+ * Has {@link setHostCapabilities} run yet? Distinct from "the host
+ * advertised nothing" — before boot's `connectApp` resolves, this is
+ * `false` AND `hostCanRelayToolCalls()` is `false`, which look
+ * identical to a silent host unless a caller checks this too. A
+ * gesture that fails in that mount-to-handshake window is a timing
+ * artifact, not evidence about the host, so callers that latch on
+ * confirmed incapability (ggui#440) MUST require this before trusting
+ * capability absence.
+ */
+let captured = false;
+/**
+ * Record the host's advertised capabilities. Called once at boot, from
+ * `bootSequence`, immediately after `connectApp` resolves — before that
+ * point `App.getHostCapabilities()` returns `undefined`.
+ */
+export function setHostCapabilities(caps) {
+    hostCapabilities = caps;
+    captured = true;
+}
+/**
+ * Did the host advertise that it can proxy a guest `tools/call` to the
+ * MCP server? `false` also covers "we have not connected yet" and "the
+ * host advertised nothing" — callers must treat it as *unconfirmed*,
+ * not as *impossible*.
+ */
+export function hostCanRelayToolCalls() {
+    return hostCapabilities?.serverTools !== undefined;
+}
+/**
+ * Did the host advertise that it accepts `ui/message` from the view?
+ * This is the only view→host method that can start an agent turn, so a
+ * host without it cannot be woken by the doorbell — the user has to
+ * send a message themselves.
+ */
+export function hostCanReceiveMessages() {
+    return hostCapabilities?.message !== undefined;
+}
+/**
+ * Has the handshake resolved capabilities at all yet? See {@link captured}.
+ * Callers that treat capability absence as confirmed incapability (as
+ * opposed to merely unconfirmed) must gate on this first — otherwise
+ * the pre-handshake window (where absence is just "not asked yet") is
+ * indistinguishable from a host that answered and advertised nothing.
+ */
+export function hostCapabilitiesCaptured() {
+    return captured;
+}
+/** @internal — exported for unit tests to reset module state. */
+export function __resetHostCapabilitiesForTest() {
+    hostCapabilities = undefined;
+    captured = false;
+}