@agent-native/core 0.115.4 → 0.117.0

package/dist/client/use-db-sync.d.ts.map

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

package/dist/client/use-db-sync.js

@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState } from "react";
 import { ensureDemoModeFetchInterceptor } from "../demo/fetch-interceptor.js";
+import { parseHandshakeFrame, parseTokenFrame, REALTIME_PROTOCOL_VERSION, REALTIME_SSE_HANDSHAKE_EVENT, REALTIME_SSE_TOKEN_EVENT, } from "../realtime-protocol.js";
 import { agentNativePath } from "./api-path.js";
 import { getBrowserTabId } from "./browser-tab-id.js";
 import { ensureEmbedAuthFetchInterceptor, isEmbedAuthActive, } from "./embed-auth.js";
@@ -10,6 +11,7 @@ const POLL_ABORT_MIN_MS = 10_000;
 // four times per minute forever. Focus and active agent work still poll now.
 const SSE_FALLBACK_INTERVAL_MS = 60_000;
 const IDLE_POLL_INTERVAL_MS = 60_000;
+const HIDDEN_POLL_INTERVAL_MS = 10_000;
 const POLL_AUTH_FAILURE_COOLDOWN_MS = 60_000;
 /**
  * Max cadence for SSE/poll-driven query invalidation in `useDbSync`. Events
@@ -38,6 +40,51 @@ function resolveSseUrl(sseUrl) {
         return false;
     return agentNativePath(sseUrl ?? "/_agent-native/events");
 }
+// --- Hosted Realtime Gateway binding ----------------------------------------
+//
+// When the app is configured for the hosted gateway, the transport connects to
+// the gateway (cross-origin) instead of the Netlify app, carrying a short-lived
+// subscribe token minted from the app's own same-origin endpoint. All of this
+// is gated on a non-null binding — apps without hosted config keep the exact
+// local behavior below.
+const REALTIME_GATEWAY_SSE_PATH = "/stream";
+const REALTIME_GATEWAY_POLL_PATH = "/poll";
+const REALTIME_TOKEN_MINT_PATH = "/_agent-native/realtime-token";
+/** Consecutive gateway failures before health-gating back to the local app. */
+const HOSTED_UNHEALTHY_THRESHOLD = 3;
+function getRealtimeConfig() {
+    if (typeof window === "undefined")
+        return undefined;
+    return window.__AGENT_NATIVE_CONFIG__?.realtime;
+}
+/**
+ * Resolve the hosted-gateway binding, or null to stay on the local app. Gated
+ * on: SSE enabled (the gateway is push-first), not embed auth (needs the
+ * same-origin session to mint), and `transport: "hosted"` with a base URL in
+ * the impersonal SSR config.
+ */
+function resolveGatewayBinding(localSseUrl) {
+    if (localSseUrl === false)
+        return null;
+    if (isEmbedAuthActive())
+        return null;
+    const config = getRealtimeConfig();
+    if (config?.transport !== "hosted")
+        return null;
+    const base = config.gatewayBaseUrl?.replace(/\/+$/, "");
+    if (!base)
+        return null;
+    return {
+        sseUrl: `${base}${REALTIME_GATEWAY_SSE_PATH}`,
+        pollUrl: `${base}${REALTIME_GATEWAY_POLL_PATH}`,
+        tokenMintUrl: agentNativePath(REALTIME_TOKEN_MINT_PATH),
+    };
+}
+/** ±20% jitter so gateway timeout/deploy-driven reconnects don't stampede. */
+function applyReconnectJitter(delay) {
+    const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+    return Math.max(0, Math.round(delay + jitter));
+}
 function normalizeEventPayload(payload) {
     if (!payload || typeof payload !== "object")
         return [];
@@ -90,13 +137,19 @@ export function isInteractionCriticalSyncEvent(event) {
             INTERACTION_CRITICAL_APP_STATE_KEYS.some((key) => event.key === key ||
                 (typeof event.key === "string" && event.key.startsWith(`${key}:`)))));
 }
-async function fetchPollJson(pollUrl, since, interval) {
+async function fetchPollJson(pollUrl, since, interval, token) {
     const controller = typeof AbortController === "undefined" ? null : new AbortController();
     const timeout = controller
         ? setTimeout(() => controller.abort(), getPollAbortMs(interval))
         : null;
+    // Local path stays exactly `?since=N`; the hosted gateway also carries the
+    // subscribe token on the query string (a cross-origin fetch can't set the
+    // Authorization header for the SSE sibling either, so both use the query).
+    const url = token
+        ? `${pollUrl}${pollUrl.includes("?") ? "&" : "?"}since=${since}&token=${encodeURIComponent(token)}`
+        : `${pollUrl}?since=${since}`;
     try {
-        const res = await fetch(`${pollUrl}?since=${since}`, controller ? { signal: controller.signal } : undefined);
+        const res = await fetch(url, controller ? { signal: controller.signal } : undefined);
         if (!res.ok)
             throw new HttpStatusError(res.status);
         // Await the json before the finally so a body-stream abort doesn't
@@ -111,6 +164,7 @@ async function fetchPollJson(pollUrl, since, interval) {
 class SyncTransport {
     pollUrl;
     sseUrl;
+    gateway;
     subscribers = new Map();
     versionRef = 0;
     timer = null;
@@ -121,9 +175,145 @@ class SyncTransport {
     authFailureUntil = 0;
     consecutiveFailures = 0;
     activeChatIds = new Set();
-    constructor(pollUrl, sseUrl) {
+    // Hosted-gateway state. `mode` starts "hosted" when a binding is present and
+    // flips to "local" on health-gate revert; `token` is the current subscribe
+    // token (minted from the app, rotated over the stream), never part of any
+    // registry key.
+    mode;
+    token = null;
+    tokenMintInFlight = null;
+    gatewayReconnectTimer = null;
+    capabilities = [];
+    constructor(pollUrl, sseUrl, gateway = null) {
         this.pollUrl = pollUrl;
         this.sseUrl = sseUrl;
+        this.gateway = gateway;
+        this.mode = gateway ? "hosted" : "local";
+    }
+    /** Capabilities advertised by the gateway handshake (e.g. `no-awareness`). */
+    getCapabilities() {
+        return this.capabilities;
+    }
+    get activeSseUrl() {
+        if (this.mode === "hosted" && this.gateway) {
+            return this.token
+                ? `${this.gateway.sseUrl}?token=${encodeURIComponent(this.token)}`
+                : this.gateway.sseUrl;
+        }
+        return this.sseUrl;
+    }
+    get activePollUrl() {
+        return this.mode === "hosted" && this.gateway
+            ? this.gateway.pollUrl
+            : this.pollUrl;
+    }
+    /**
+     * Mint a subscribe token from the app's same-origin endpoint.
+     *
+     * Only TERMINAL outcomes health-gate to local: 404 (gateway not provisioned)
+     * and 401/403 (not authorized) — retrying those for this tab is pointless.
+     * TRANSIENT failures (5xx/429 from a cold Netlify function, network errors)
+     * keep the hosted intent and ride the jittered reconnect + unhealthy-threshold
+     * path, so a deploy / scale-to-zero blip doesn't permanently abandon the
+     * gateway for the tab.
+     */
+    mintToken() {
+        if (!this.gateway || this.mode !== "hosted")
+            return Promise.resolve(false);
+        if (this.tokenMintInFlight)
+            return this.tokenMintInFlight;
+        const mintUrl = this.gateway.tokenMintUrl;
+        this.tokenMintInFlight = (async () => {
+            // Bound the mint like fetchPollJson bounds polls: a black-holed request
+            // must resolve as a transient failure, not hang tokenMintInFlight forever
+            // (poll() awaits this while holding inFlight, so a hung mint would stall
+            // the whole transport with no timer pending).
+            const controller = typeof AbortController === "undefined" ? null : new AbortController();
+            const timeout = controller
+                ? setTimeout(() => controller.abort(), POLL_ABORT_MIN_MS)
+                : null;
+            try {
+                const res = await fetch(mintUrl, {
+                    credentials: "same-origin",
+                    ...(controller ? { signal: controller.signal } : {}),
+                });
+                if (res.ok) {
+                    const data = (await res.json());
+                    if (typeof data?.token === "string" && data.token) {
+                        this.token = data.token;
+                        // Deliberately NOT resetting consecutiveFailures here: minting
+                        // succeeds via the app origin even when the GATEWAY is down, so a
+                        // reset would let a mint-ok -> stream-fail loop run forever below
+                        // the unhealthy threshold. Only real gateway connectivity (stream
+                        // onopen / poll success) clears the count.
+                        return true;
+                    }
+                    // 2xx without a token is a terminal misconfiguration.
+                    this.revertToLocal();
+                    return false;
+                }
+                if (res.status === 404 || res.status === 401 || res.status === 403) {
+                    this.revertToLocal();
+                    return false;
+                }
+                this.onGatewayTransientFailure();
+                return false;
+            }
+            catch {
+                this.onGatewayTransientFailure();
+                return false;
+            }
+            finally {
+                if (timeout)
+                    clearTimeout(timeout);
+                this.tokenMintInFlight = null;
+            }
+        })();
+        return this.tokenMintInFlight;
+    }
+    /**
+     * A transient gateway failure (mint 5xx/429, network). Keep hosted intent but
+     * count toward the unhealthy threshold; revert to local only once it trips.
+     */
+    onGatewayTransientFailure() {
+        this.consecutiveFailures++;
+        if (this.consecutiveFailures >= HOSTED_UNHEALTHY_THRESHOLD) {
+            this.revertToLocal();
+        }
+    }
+    /**
+     * Health-gate back to the app's own /poll + /events with the cursor intact
+     * (versionRef is untouched), so delivery stays poll-equivalent — never a
+     * silent stall.
+     */
+    revertToLocal() {
+        if (this.mode === "local")
+            return;
+        this.mode = "local";
+        this.token = null;
+        // The local in-process SSE path sends no handshake, so hosted capabilities
+        // (e.g. no-awareness) must not survive the fallback — stale caps would keep
+        // collab on its fast presence cadence against the local stream. Subscribers
+        // are re-notified via the close/connect cycle below.
+        this.capabilities = [];
+        if (this.gatewayReconnectTimer) {
+            clearTimeout(this.gatewayReconnectTimer);
+            this.gatewayReconnectTimer = null;
+        }
+        this.closeEvents();
+        if (!this.stopped) {
+            this.connectEvents();
+            this.schedulePoll();
+        }
+    }
+    scheduleGatewayReconnect() {
+        if (this.stopped || this.gatewayReconnectTimer)
+            return;
+        this.gatewayReconnectTimer = setTimeout(() => {
+            this.gatewayReconnectTimer = null;
+            if (!this.stopped && !this.eventSource)
+                this.connectEvents();
+        }, applyReconnectJitter(1000));
     }
     // -------------------------------------------------------------------------
     // Subscriber management
@@ -144,7 +334,7 @@ class SyncTransport {
         else {
             this.reschedule();
         }
-        sub.onSseStateChange?.(this.sseConnected);
+        sub.onSseStateChange?.(this.sseConnected, this.capabilities);
     }
     remove(id) {
         this.subscribers.delete(id);
@@ -207,8 +397,17 @@ class SyncTransport {
         if (this.sseConnected === connected)
             return;
         this.sseConnected = connected;
+        this.notifySseState();
+    }
+    /**
+     * Notify subscribers of the current SSE state AND the negotiated gateway
+     * capabilities. Called on connect/disconnect and again once the handshake
+     * arrives, so a consumer (e.g. collab) can decide — for instance — not to
+     * relax its presence cadence on a `no-awareness` hosted stream.
+     */
+    notifySseState() {
         for (const sub of this.subscribers.values()) {
-            sub.onSseStateChange?.(connected);
+            sub.onSseStateChange?.(this.sseConnected, this.capabilities);
         }
     }
     // -------------------------------------------------------------------------
@@ -232,18 +431,25 @@ class SyncTransport {
             }, authDelay);
             return;
         }
-        const base = this.isActive
+        const visibleBase = this.isActive
             ? this.effectiveInterval
             : this.sseConnected
                 ? this.effectiveFallbackInterval
                 : this.effectiveIdleInterval;
+        const base = isDocumentHidden()
+            ? Math.max(visibleBase, HIDDEN_POLL_INTERVAL_MS)
+            : visibleBase;
         // Exponential backoff while polls keep failing (500s during a deploy,
         // DNS blips, a struggling DB). Auth failures have their own cooldown
         // above; this covers everything else so a down server isn't hammered at
         // full cadence. Resets on the first successful poll.
-        const delay = this.consecutiveFailures > 0
+        const backoff = this.consecutiveFailures > 0
             ? Math.min(base * 2 ** Math.min(this.consecutiveFailures, 5), 300_000)
             : base;
+        // Jitter only for gateway-capable transports so reconnect/poll retries
+        // don't stampede a gateway deploy; apps with no gateway config keep the
+        // exact deterministic cadence.
+        const delay = this.gateway ? applyReconnectJitter(backoff) : backoff;
         this.timer = setTimeout(() => {
             this.timer = null;
             void this.poll();
@@ -267,16 +473,44 @@ class SyncTransport {
     }
     connectEvents() {
         if (this.stopped ||
-            !this.sseUrl ||
             this.eventSource ||
             typeof EventSource === "undefined" ||
             (this.effectivePauseWhenHidden && isDocumentHidden())) {
             return;
         }
-        const source = new EventSource(this.sseUrl);
+        // Hosted gateway needs a subscribe token before the stream can open.
+        // EventSource can't set headers, so the token rides the connect query
+        // string (see activeSseUrl). Mint first, then connect.
+        if (this.mode === "hosted" && this.gateway && !this.token) {
+            void this.mintToken().then((ok) => {
+                if (this.stopped)
+                    return;
+                if (ok && !this.eventSource) {
+                    this.connectEvents();
+                }
+                else if (!ok && this.mode === "hosted") {
+                    // Transient mint failure (terminal ones already reverted to local,
+                    // flipping mode). Without a retry timer nothing would ever reopen
+                    // SSE — connectEvents is only reachable from focus/visibility/run
+                    // events — leaving the tab poll-only at the idle cadence.
+                    this.scheduleGatewayReconnect();
+                }
+            });
+            return;
+        }
+        const url = this.activeSseUrl;
+        if (!url)
+            return;
+        const source = new EventSource(url);
         this.eventSource = source;
         source.onopen = () => {
             this.setSseConnected(true);
+            if (this.mode === "hosted") {
+                // A live gateway stream is the real health signal: clear failure
+                // counts accumulated by mint/stream retries. Local mode keeps main's
+                // semantics (only a successful poll resets the poll backoff).
+                this.consecutiveFailures = 0;
+            }
             this.schedulePoll();
         };
         source.onerror = () => {
@@ -288,6 +522,20 @@ class SyncTransport {
             // we'd be stuck on polling-only forever.
             if (source.readyState === EventSource.CLOSED) {
                 this.eventSource = null;
+                if (this.mode === "hosted" && this.gateway) {
+                    // A closed gateway stream is most likely an expired token or a
+                    // request-timeout/deploy cycle. Re-mint and reconnect with jitter;
+                    // this is NOT the poll-401 cooldown path. Each closed stream counts
+                    // toward the unhealthy threshold so a hard-down gateway (or one
+                    // rejecting our tokens) health-gates to local instead of looping
+                    // mint+connect forever; a successful reconnect resets the count in
+                    // onopen above.
+                    this.token = null;
+                    this.onGatewayTransientFailure();
+                    if (this.mode === "hosted")
+                        this.scheduleGatewayReconnect();
+                    return;
+                }
             }
             this.schedulePoll();
         };
@@ -303,6 +551,37 @@ class SyncTransport {
                 // Ignore malformed SSE frames; polling is the safety net.
             }
         };
+        if (this.mode === "hosted" && this.gateway) {
+            // Control frames ride NAMED SSE events so they never reach onmessage /
+            // normalizeEventPayload as spurious data events.
+            source.addEventListener(REALTIME_SSE_HANDSHAKE_EVENT, (e) => {
+                const hs = parseHandshakeFrame(e.data);
+                if (!hs)
+                    return;
+                if (hs.protocol !== REALTIME_PROTOCOL_VERSION) {
+                    // Surface an unexpected protocol rather than silently adopting its
+                    // capabilities; keep the conservative (no advertised capabilities)
+                    // stance so downstream (collab) does not relax on assumptions.
+                    console.warn(`[agent-native] unsupported realtime protocol ${hs.protocol} (expected ${REALTIME_PROTOCOL_VERSION})`);
+                    return;
+                }
+                this.capabilities = hs.capabilities;
+                // Re-notify subscribers now that capabilities are known — the initial
+                // connected notification fired before the handshake arrived.
+                this.notifySseState();
+            });
+            source.addEventListener(REALTIME_SSE_TOKEN_EVENT, (e) => {
+                const frame = parseTokenFrame(e.data);
+                if (!frame?.token)
+                    return;
+                this.token = frame.token;
+                // EventSource can't change a live stream's URL, and its auto-reconnect
+                // reuses the original (old-token) URL. Close and reconnect (jittered) so
+                // the rotated token is actually used on the next connect.
+                this.closeEvents();
+                this.scheduleGatewayReconnect();
+            });
+        }
     }
     /**
      * Advance the transport's shared version cursor. Subscribers receive the
@@ -325,7 +604,14 @@ class SyncTransport {
             return;
         this.inFlight = true;
         try {
-            const data = await fetchPollJson(this.pollUrl, this.versionRef, this.effectiveInterval);
+            if (this.mode === "hosted" && this.gateway && !this.token) {
+                // No token yet — mint before polling the gateway. A failed mint has
+                // already reverted us to local; a scheduled poll will pick it up.
+                const ok = await this.mintToken();
+                if (!ok || this.stopped)
+                    return;
+            }
+            const data = await fetchPollJson(this.activePollUrl, this.versionRef, this.effectiveInterval, this.mode === "hosted" ? (this.token ?? undefined) : undefined);
             if (this.stopped)
                 return;
             this.consecutiveFailures = 0;
@@ -337,7 +623,19 @@ class SyncTransport {
             if (this.stopped)
                 return;
             this.consecutiveFailures++;
-            if (isAuthFailure(err)) {
+            if (this.mode === "hosted" && this.gateway) {
+                // Gateway auth failure → re-mint (expired/rotated token), WITHOUT
+                // tripping the poll-401 cooldown. Persistent failures of any kind
+                // health-gate back to the local app.
+                if (isAuthFailure(err)) {
+                    this.token = null;
+                    void this.mintToken();
+                }
+                if (this.consecutiveFailures >= HOSTED_UNHEALTHY_THRESHOLD) {
+                    this.revertToLocal();
+                }
+            }
+            else if (isAuthFailure(err)) {
                 this.authFailureUntil = Date.now() + POLL_AUTH_FAILURE_COOLDOWN_MS;
                 this.closeEvents();
             }
@@ -374,6 +672,12 @@ class SyncTransport {
                 this.timer = null;
             }
         }
+        else {
+            // Keep push connected and the polling safety net alive in backgrounded
+            // tabs, but relax an active chat's cadence so hidden work stays current
+            // without polling as aggressively as the visible surface.
+            this.reschedule();
+        }
     };
     handleFocus = () => {
         this.pollNow();
@@ -427,6 +731,10 @@ class SyncTransport {
             clearTimeout(this.timer);
             this.timer = null;
         }
+        if (this.gatewayReconnectTimer) {
+            clearTimeout(this.gatewayReconnectTimer);
+            this.gatewayReconnectTimer = null;
+        }
         window.removeEventListener("focus", this.handleFocus);
         window.removeEventListener("agentNative.chatRunning", this.handleChatRunning);
         document.removeEventListener("visibilitychange", this.handleVisibilityChange);
@@ -438,11 +746,13 @@ class SyncTransport {
  * hook instances in the same browser tab.
  */
 const transportRegistry = new Map();
-function getOrCreateTransport(pollUrl, sseUrl) {
+function getOrCreateTransport(pollUrl, sseUrl, gateway = null) {
+    // Key on the LOCAL urls only — a transport may flip hosted→local at runtime,
+    // and the token must never fragment the registry, so neither is in the key.
     const key = `${pollUrl}\0${String(sseUrl)}`;
     let transport = transportRegistry.get(key);
     if (!transport) {
-        transport = new SyncTransport(pollUrl, sseUrl);
+        transport = new SyncTransport(pollUrl, sseUrl, gateway);
         transportRegistry.set(key, transport);
     }
     return transport;
@@ -475,12 +785,12 @@ export function _resetSyncTransportRegistryForTests() {
 export function subscribeSyncEvents(options) {
     const pollUrl = agentNativePath(options.pollUrl ?? "/_agent-native/poll");
     const sseUrl = resolveSseUrl(options.sseUrl);
-    const transport = getOrCreateTransport(pollUrl, sseUrl);
+    const transport = getOrCreateTransport(pollUrl, sseUrl, resolveGatewayBinding(sseUrl));
     const id = Symbol("subscribeSyncEvents");
     transport.add(id, {
         onEvents: options.onEvents,
         onSseStateChange: options.onSseStateChange,
-        pauseWhenHidden: options.pauseWhenHidden ?? true,
+        pauseWhenHidden: options.pauseWhenHidden ?? false,
         interval: options.interval ?? 60_000,
         idleInterval: options.interval ?? 60_000,
         fallbackInterval: options.fallbackInterval ?? 60_000,
@@ -513,8 +823,9 @@ export function subscribeSyncEvents(options) {
  * @param options.interval - Poll interval in ms. Default: 2000
  * @param options.fallbackInterval - Poll interval while SSE is connected.
  *   Default: 60000
- * @param options.pauseWhenHidden - Pause polling while the tab is hidden.
- *   Default: true
+ * @param options.pauseWhenHidden - Pause sync while the tab is hidden.
+ *   Default: false. Hidden tabs keep SSE connected and poll no faster than
+ *   every 10 seconds while active; idle polling remains at 60 seconds.
  * @param options.ignoreSource - Skip events whose `requestSource` matches this
  *   value. Use a per-tab ID so the UI ignores its own writes while still
  *   picking up changes from other tabs, agents, and scripts.
@@ -527,7 +838,7 @@ export function subscribeSyncEvents(options) {
  *   background actions that perform their own narrow client invalidation.
  */
 export function useDbSync(options = {}) {
-    const { queryClient, pollUrl = agentNativePath(options.eventsUrl ?? "/_agent-native/poll"), sseUrl = resolveSseUrl(options.sseUrl), interval = 2000, fallbackInterval = Math.max(options.fallbackInterval ?? SSE_FALLBACK_INTERVAL_MS, interval), pauseWhenHidden = true, } = options;
+    const { queryClient, pollUrl = agentNativePath(options.eventsUrl ?? "/_agent-native/poll"), sseUrl = resolveSseUrl(options.sseUrl), interval = 2000, fallbackInterval = Math.max(options.fallbackInterval ?? SSE_FALLBACK_INTERVAL_MS, interval), pauseWhenHidden = false, } = options;
     const idleInterval = options.interval === undefined ? IDLE_POLL_INTERVAL_MS : interval;
     const onEventRef = useRef(options.onEvent);
     onEventRef.current = options.onEvent;
@@ -730,7 +1041,7 @@ export function useDbSync(options = {}) {
             const maxEventVersion = freshEvents.reduce((max, event) => Math.max(max, typeof event.version === "number" ? event.version : 0), 0);
             subscriberVersion = Math.max(subscriberVersion, version ?? 0, maxEventVersion);
         }
-        const transport = getOrCreateTransport(pollUrl, sseUrl);
+        const transport = getOrCreateTransport(pollUrl, sseUrl, resolveGatewayBinding(sseUrl));
         transport.add(id, {
             onEvents,
             pauseWhenHidden,
@@ -786,7 +1097,7 @@ export const useFileWatcher = useDbSync;
  *   );
  */
 export function useScreenRefreshKey(options = {}) {
-    const { pollUrl = agentNativePath(options.pollUrl ?? "/_agent-native/poll"), sseUrl = resolveSseUrl(options.sseUrl), interval = 2000, fallbackInterval = Math.max(options.fallbackInterval ?? SSE_FALLBACK_INTERVAL_MS, interval), pauseWhenHidden = true, } = options;
+    const { pollUrl = agentNativePath(options.pollUrl ?? "/_agent-native/poll"), sseUrl = resolveSseUrl(options.sseUrl), interval = 2000, fallbackInterval = Math.max(options.fallbackInterval ?? SSE_FALLBACK_INTERVAL_MS, interval), pauseWhenHidden = false, } = options;
     const idleInterval = options.interval === undefined ? IDLE_POLL_INTERVAL_MS : interval;
     const [key, setKey] = useState(0);
     useEffect(() => {
@@ -804,7 +1115,7 @@ export function useScreenRefreshKey(options = {}) {
             const maxEventVersion = freshEvents.reduce((max, event) => Math.max(max, typeof event.version === "number" ? event.version : 0), 0);
             subscriberVersion = Math.max(subscriberVersion, version ?? 0, maxEventVersion);
         }
-        const transport = getOrCreateTransport(pollUrl, sseUrl);
+        const transport = getOrCreateTransport(pollUrl, sseUrl, resolveGatewayBinding(sseUrl));
         transport.add(id, {
             onEvents,
             pauseWhenHidden,