@agent-native/core 0.116.0 → 0.117.0

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";
@@ -39,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 [];
@@ -91,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
@@ -112,6 +164,7 @@ async function fetchPollJson(pollUrl, since, interval) {
 class SyncTransport {
     pollUrl;
     sseUrl;
+    gateway;
     subscribers = new Map();
     versionRef = 0;
     timer = null;
@@ -122,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
@@ -145,7 +334,7 @@ class SyncTransport {
         else {
             this.reschedule();
         }
-        sub.onSseStateChange?.(this.sseConnected);
+        sub.onSseStateChange?.(this.sseConnected, this.capabilities);
     }
     remove(id) {
         this.subscribers.delete(id);
@@ -208,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);
         }
     }
     // -------------------------------------------------------------------------
@@ -245,9 +443,13 @@ class SyncTransport {
         // 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();
@@ -271,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 = () => {
@@ -292,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();
         };
@@ -307,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
@@ -329,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;
@@ -341,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();
             }
@@ -437,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);
@@ -448,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;
@@ -485,7 +785,7 @@ 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,
@@ -741,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,
@@ -815,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,