@agent-native/core 0.116.0 → 0.117.0

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1529
+- core files: 1531
 - toolkit files: 145
 - template files: 6410

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @agent-native/core
 
+## 0.117.0
+
+### Minor Changes
+
+- d73eda3: Realtime sync: framework prerequisites for the hosted Realtime Sync Gateway. All new behavior is opt-in — apps without hosted-realtime config are unchanged.
+  - Refactor `poll.ts` into an `AppSyncState` class holding all previously module-global change-tracking state (version counter, ring buffer, poll emitter, watermarks, and the access cache). Module-level exports (`recordChange`, `getVersion`, `getPollEmitter`, `getChangesSinceForUser`, `canSeeChangeForUser`, `createPollHandler`, `invalidateCollabAccessCache`) delegate to a lazily-created default instance bound to the process DB, so self-hosted apps are unchanged. `createPollHandler` and `createPollEventsHandler` accept an optional injected `AppSyncState`.
+  - `AppSyncState` accepts an injected DB accessor, Postgres check, and access resolver, and exposes `getCombinedChangesSinceForUser`/`checkExternalDbChanges`/`persistSyncEvent` for reuse. `ddl-guard` helpers accept a `dialectIsPostgres` override so injected per-app clients get the guarded Postgres DDL path regardless of the process-global DB.
+  - The per-user access cache key now includes the active `orgId`, so a decision cached in one org is never reused under another org's session.
+  - Add `readMinSyncEventVersion()` (oldest retained durable version) for stale-cursor detection, and an opt-in `deterministicEventIds` mode so multiple processes detecting the same out-of-band write collapse to one durable row. Both off/unused by default.
+  - New public export subpaths: `./server/poll`, `./server/sse`, `./server/short-lived-token`.
+  - New realtime subscribe tokens: `signRealtimeSubscribeToken`/`verifyRealtimeSubscribeToken` — per-project HMAC key, identity-bearing claims (`owner`/`orgId` required), `projectId` channel binding, and a `typ` discriminator so they are not interchangeable with media tokens. Existing `signShortLivedToken`/`verifyShortLivedToken` are untouched.
+  - New session-gated, same-origin endpoint `GET /_agent-native/realtime-token` mounted by core-routes. Fail-closed: responds 404 unless the app is provisioned with a per-project signing secret (`AGENT_NATIVE_REALTIME_HMAC_SECRET`) and a Builder project id; responses are `Cache-Control: private, no-store`.
+  - New shared realtime wire protocol (`realtime-protocol.ts`, re-exported from `./server/sse`): named SSE `handshake`/`token` control frames; data/batch frames unchanged.
+  - Client transport (`useDbSync`/`subscribeSyncEvents`) gains an opt-in hosted-gateway mode, enabled only when the SSR config sets `realtime.transport = "hosted"` with an explicit gateway URL: token mint/rotation, jittered reconnects, and automatic health-gated fallback to the app's own `/poll` + `/events`. `onSseStateChange` callbacks now also receive the negotiated capability list (optional second parameter; existing callbacks are unaffected), which collab uses to keep its fast presence cadence on `no-awareness` streams.
+
 ## 0.116.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.116.0",
+  "version": "0.117.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -68,6 +68,9 @@
     "./server/agent-discovery": "./dist/server/agent-discovery.js",
     "./server/request-context": "./dist/server/request-context.js",
     "./server/design-token-utils": "./dist/server/design-token-utils.js",
+    "./server/poll": "./dist/server/poll.js",
+    "./server/sse": "./dist/server/sse.js",
+    "./server/short-lived-token": "./dist/server/short-lived-token.js",
     "./integrations": "./dist/integrations/index.js",
     "./integrations/runtime": "./dist/integrations/runtime.js",
     "./ingestion": "./dist/ingestion/index.js",

package/corpus/core/src/client/analytics.ts

@@ -50,6 +50,13 @@ declare global {
     __AGENT_NATIVE_CONFIG__?: {
       sentryDsn?: string;
       sentryEnvironment?: string;
+      /**
+       * Hosted Realtime Gateway config. Impersonal (same for every visitor),
+       * so it is safe inside the CDN-cached SSR shell — unlike the per-user
+       * subscribe token, which is minted client-side after load. Absent when
+       * the app uses the in-process (local) transport.
+       */
+      realtime?: { transport?: string; gatewayBaseUrl?: string };
     };
   }
 }

package/corpus/core/src/client/use-db-sync.ts

@@ -1,6 +1,13 @@
 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 {
@@ -88,6 +95,64 @@ function resolveSseUrl(sseUrl: string | false | undefined): string | 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;
+
+interface RealtimeGatewayBinding {
+  /** Gateway SSE URL (token appended per connect). */
+  sseUrl: string;
+  /** Gateway poll URL (token appended per request). */
+  pollUrl: string;
+  /** Same-origin app endpoint that mints the subscribe token. */
+  tokenMintUrl: string;
+}
+
+function getRealtimeConfig():
+  | { transport?: string; gatewayBaseUrl?: string }
+  | undefined {
+  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: string | false,
+): RealtimeGatewayBinding | null {
+  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: number): number {
+  const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(delay + jitter));
+}
+
 function normalizeEventPayload(payload: unknown): SyncEvent[] {
   if (!payload || typeof payload !== "object") return [];
   const record = payload as { type?: unknown; events?: unknown };
@@ -158,6 +223,7 @@ async function fetchPollJson<T>(
   pollUrl: string,
   since: number,
   interval: number,
+  token?: string,
 ): Promise<T> {
   const controller =
     typeof AbortController === "undefined" ? null : new AbortController();
@@ -165,9 +231,16 @@ async function fetchPollJson<T>(
     ? 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}`,
+      url,
       controller ? { signal: controller.signal } : undefined,
     );
     if (!res.ok) throw new HttpStatusError(res.status);
@@ -215,7 +288,10 @@ interface TransportSubscription {
    * subscribers with their own fallback loops (e.g. the collab doc poll)
    * relax their cadence while the push path is healthy.
    */
-  onSseStateChange?: (connected: boolean) => void;
+  onSseStateChange?: (
+    connected: boolean,
+    capabilities?: readonly string[],
+  ) => void;
 }
 
 class SyncTransport {
@@ -229,11 +305,148 @@ class SyncTransport {
   private authFailureUntil = 0;
   private consecutiveFailures = 0;
   private activeChatIds = new Set<string>();
+  // 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.
+  private mode: "hosted" | "local";
+  private token: string | null = null;
+  private tokenMintInFlight: Promise<boolean> | null = null;
+  private gatewayReconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private capabilities: string[] = [];
 
   constructor(
     private readonly pollUrl: string,
     private readonly sseUrl: string | false,
-  ) {}
+    private readonly gateway: RealtimeGatewayBinding | null = null,
+  ) {
+    this.mode = gateway ? "hosted" : "local";
+  }
+
+  /** Capabilities advertised by the gateway handshake (e.g. `no-awareness`). */
+  getCapabilities(): readonly string[] {
+    return this.capabilities;
+  }
+
+  private get activeSseUrl(): string | false {
+    if (this.mode === "hosted" && this.gateway) {
+      return this.token
+        ? `${this.gateway.sseUrl}?token=${encodeURIComponent(this.token)}`
+        : this.gateway.sseUrl;
+    }
+    return this.sseUrl;
+  }
+
+  private get activePollUrl(): string {
+    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.
+   */
+  private mintToken(): Promise<boolean> {
+    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()) as { token?: unknown };
+          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.
+   */
+  private onGatewayTransientFailure(): void {
+    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.
+   */
+  private revertToLocal(): void {
+    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();
+    }
+  }
+
+  private scheduleGatewayReconnect(): void {
+    if (this.stopped || this.gatewayReconnectTimer) return;
+    this.gatewayReconnectTimer = setTimeout(() => {
+      this.gatewayReconnectTimer = null;
+      if (!this.stopped && !this.eventSource) this.connectEvents();
+    }, applyReconnectJitter(1000));
+  }
 
   // -------------------------------------------------------------------------
   // Subscriber management
@@ -253,7 +466,7 @@ class SyncTransport {
     } else {
       this.reschedule();
     }
-    sub.onSseStateChange?.(this.sseConnected);
+    sub.onSseStateChange?.(this.sseConnected, this.capabilities);
   }
 
   remove(id: symbol): void {
@@ -320,8 +533,18 @@ class SyncTransport {
   private setSseConnected(connected: boolean): void {
     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.
+   */
+  private notifySseState(): void {
     for (const sub of this.subscribers.values()) {
-      sub.onSseStateChange?.(connected);
+      sub.onSseStateChange?.(this.sseConnected, this.capabilities);
     }
   }
 
@@ -357,10 +580,14 @@ 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 =
+    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();
@@ -387,7 +614,6 @@ class SyncTransport {
   private connectEvents(): void {
     if (
       this.stopped ||
-      !this.sseUrl ||
       this.eventSource ||
       typeof EventSource === "undefined" ||
       (this.effectivePauseWhenHidden && isDocumentHidden())
@@ -395,10 +621,38 @@ class SyncTransport {
       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 = () => {
@@ -410,6 +664,19 @@ 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();
     };
@@ -425,6 +692,38 @@ 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 as MessageEvent).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 as MessageEvent).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();
+      });
+    }
   }
 
   /**
@@ -446,10 +745,17 @@ class SyncTransport {
     if (this.stopped || this.inFlight) return;
     this.inFlight = true;
     try {
+      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<PollResponse>(
-        this.pollUrl,
+        this.activePollUrl,
         this.versionRef,
         this.effectiveInterval,
+        this.mode === "hosted" ? (this.token ?? undefined) : undefined,
       );
       if (this.stopped) return;
       this.consecutiveFailures = 0;
@@ -459,7 +765,18 @@ class SyncTransport {
     } catch (err) {
       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();
       }
@@ -563,6 +880,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",
@@ -585,11 +906,14 @@ const transportRegistry = new Map<string, SyncTransport>();
 function getOrCreateTransport(
   pollUrl: string,
   sseUrl: string | false,
+  gateway: RealtimeGatewayBinding | null = null,
 ): SyncTransport {
+  // 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;
@@ -616,7 +940,10 @@ export interface SubscribeSyncEventsOptions {
   /** Receives every batch of change events (SSE push or poll). */
   onEvents: (events: SyncEvent[], version: number | undefined) => void;
   /** Notified when the shared SSE connection opens/closes (and once on join). */
-  onSseStateChange?: (connected: boolean) => void;
+  onSseStateChange?: (
+    connected: boolean,
+    capabilities?: readonly string[],
+  ) => void;
   pollUrl?: string;
   sseUrl?: string | false;
   pauseWhenHidden?: boolean;
@@ -645,7 +972,11 @@ export function subscribeSyncEvents(
 ): () => void {
   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,
@@ -988,7 +1319,11 @@ export function useDbSync(
       );
     }
 
-    const transport = getOrCreateTransport(pollUrl, sseUrl);
+    const transport = getOrCreateTransport(
+      pollUrl,
+      sseUrl,
+      resolveGatewayBinding(sseUrl),
+    );
     transport.add(id, {
       onEvents,
       pauseWhenHidden,
@@ -1094,7 +1429,11 @@ export function useScreenRefreshKey(
       );
     }
 
-    const transport = getOrCreateTransport(pollUrl, sseUrl);
+    const transport = getOrCreateTransport(
+      pollUrl,
+      sseUrl,
+      resolveGatewayBinding(sseUrl),
+    );
     transport.add(id, {
       onEvents,
       pauseWhenHidden,

package/corpus/core/src/collab/client.ts

@@ -45,6 +45,7 @@ import * as Y from "yjs";
 
 import { agentNativePath } from "../client/api-path.js";
 import { subscribeSyncEvents, type SyncEvent } from "../client/use-db-sync.js";
+import { REALTIME_CAP_NO_AWARENESS } from "../realtime-protocol.js";
 export {
   dedupeCollabUsersByEmail,
   emailToColor,
@@ -326,6 +327,12 @@ class CollabDocConnection {
   private pollVersion = 0;
   private lastPolledVersion = 0;
   private sseActive = false;
+  // Whether the active SSE stream actually forwards awareness. The hosted
+  // Realtime Gateway advertises `no-awareness` (it can't see the in-process
+  // awareness emitter), so on that transport we must NOT relax the presence
+  // poll cadence — otherwise remote cursors go stale. In-process SSE forwards
+  // awareness and sends no handshake, so this stays true there.
+  private sseAwarenessCovered = false;
   private sseSubscribedWithPause: boolean | null = null;
   private unsubscribeCollabEvents: (() => void) | null = null;
   private unsubscribeAwarenessEvents: (() => void) | null = null;
@@ -760,8 +767,22 @@ class CollabDocConnection {
         if (this.disposed || !this.syncActive) return;
         for (const change of events) this.handleSharedEvent(change);
       },
-      onSseStateChange: (connected) => {
+      onSseStateChange: (connected, capabilities) => {
+        const wasActive = this.sseActive;
         this.sseActive = connected;
+        // Only treat SSE as covering awareness when it's connected AND does not
+        // advertise `no-awareness` (the hosted gateway does). Drives whether we
+        // relax the presence poll — see getActivePollInterval.
+        const awarenessCovered =
+          connected && !capabilities?.includes(REALTIME_CAP_NO_AWARENESS);
+        const coverageFlipped = awarenessCovered !== this.sseAwarenessCovered;
+        this.sseAwarenessCovered = awarenessCovered;
+        // The gateway handshake lands AFTER onopen, so a relaxed poll timer
+        // scheduled at connect can already be pending when `no-awareness`
+        // arrives. Reschedule only for that mid-connection capability flip so
+        // the fast presence cadence applies immediately; connect/disconnect
+        // transitions keep the pre-existing next-natural-tick behavior.
+        if (coverageFlipped && connected === wasActive) this.reschedulePoll();
         if (connected) this.consecutiveErrors = 0;
       },
       pauseWhenHidden,
@@ -811,7 +832,10 @@ class CollabDocConnection {
   }
 
   private getActivePollInterval(): number {
-    return this.sseActive
+    // Relax to the slow cadence only when SSE is genuinely carrying awareness;
+    // on a `no-awareness` hosted stream keep the fast cadence so presence/
+    // cursor state doesn't go stale (the gateway doesn't forward awareness).
+    return this.sseActive && this.sseAwarenessCovered
       ? this.effectivePollIntervalWithSse
       : this.effectivePollInterval;
   }