@agent-native/core 0.144.1 → 0.144.3

package/dist/client/MultiTabAssistantChat.js

@@ -17,6 +17,7 @@ import { callAction } from "./use-action.js";
 import { useChangeVersion } from "./use-change-version.js";
 import { CHAT_MODEL_SELECTION_CHANGED_EVENT } from "./use-chat-models.js";
 import { useChatThreads, } from "./use-chat-threads.js";
+import { usePollLoop } from "./use-poll-loop.js";
 import { cn } from "./utils.js";
 /** The single path that hands a queued send to a mounted chat ref. */
 function deliverPendingSend(ref, send) {
@@ -275,6 +276,7 @@ function chatTabStatusFromAgentTeamStatus(status) {
     return isActiveAgentTeamStatus(status) ? "running" : "completed";
 }
 const STALE_THREAD_THRESHOLD_MS = 12 * 60 * 60 * 1000;
+const DEFAULT_AGENT_TEAM_POLL_MS = 3000;
 const DEFAULT_THREAD_URL_PARAM = "thread";
 const THREAD_URL_CHANGED_EVENT = "agent-chat:url-thread-changed";
 const hasOwn = Object.prototype.hasOwnProperty;
@@ -373,7 +375,7 @@ function runToAgentTeamTabInfo(run) {
         status: run.status ?? "unknown",
     };
 }
-export function MultiTabAssistantChat({ showTabBar = true, renderHeader, renderOverlay, contentHidden = false, apiUrl = agentNativePath("/_agent-native/agent-chat"), storageKey, restoreActiveThread = true, browserTabId, threadUrlSync = false, scope = null, ...props }) {
+export function MultiTabAssistantChat({ showTabBar = true, renderHeader, renderOverlay, contentHidden = false, apiUrl = agentNativePath("/_agent-native/agent-chat"), storageKey, restoreActiveThread = true, browserTabId, threadUrlSync = false, scope = null, agentTeamPollMs = DEFAULT_AGENT_TEAM_POLL_MS, ...props }) {
     const { enabled: threadUrlSyncEnabled, paramName: threadUrlParamName, routeThreadId, getPath: getThreadPath, navigate: navigateThreadUrl, } = resolveThreadUrlSync(threadUrlSync);
     const threadRouteControlsActiveThread = threadUrlSyncEnabled &&
         threadUrlSync !== true &&
@@ -896,107 +898,92 @@ export function MultiTabAssistantChat({ showTabBar = true, renderHeader, renderO
             });
         }
     }, [isLoading, openTabIds, activeThreadId, createThread, writeThreadUrl]);
-    useEffect(() => {
-        let stopped = false;
-        let timer = null;
+    usePollLoop(async (signal) => {
         const runsUrl = `${apiUrl.replace(/\/$/, "")}/runs/list?goalId=agent-team`;
-        async function hydrateAgentTeamTabs() {
-            try {
-                const res = await fetch(runsUrl);
-                if (res.ok) {
-                    const data = (await res.json());
-                    const infos = Array.isArray(data.runs)
-                        ? data.runs
-                            .map(runToAgentTeamTabInfo)
-                            .filter((info) => Boolean(info))
-                        : [];
-                    setSubAgentStatuses((prev) => {
-                        let changed = false;
-                        const next = {};
-                        for (const info of infos) {
-                            next[info.threadId] = info.status;
-                            if (prev[info.threadId] !== info.status)
-                                changed = true;
-                        }
-                        if (Object.keys(prev).length !== Object.keys(next).length) {
+        try {
+            const res = await fetch(runsUrl, { signal });
+            if (res.ok) {
+                const data = (await res.json());
+                const infos = Array.isArray(data.runs)
+                    ? data.runs
+                        .map(runToAgentTeamTabInfo)
+                        .filter((info) => Boolean(info))
+                    : [];
+                setSubAgentStatuses((prev) => {
+                    let changed = false;
+                    const next = {};
+                    for (const info of infos) {
+                        next[info.threadId] = info.status;
+                        if (prev[info.threadId] !== info.status)
                             changed = true;
+                    }
+                    if (Object.keys(prev).length !== Object.keys(next).length) {
+                        changed = true;
+                    }
+                    return changed ? next : prev;
+                });
+                const openSet = new Set(openTabIdsRef.current);
+                const candidates = infos.filter((info) => !dismissedSubAgentTabsRef.current.has(info.threadId) &&
+                    (openSet.has(info.parentThreadId) || openSet.has(info.threadId)));
+                if (candidates.length > 0) {
+                    const shouldRefreshThreads = candidates.some((info) => !openSet.has(info.threadId) && openSet.has(info.parentThreadId));
+                    const candidateParents = new Map(candidates.map((info) => [info.threadId, info.parentThreadId]));
+                    setParentMap((prev) => {
+                        let next = prev;
+                        for (const info of candidates) {
+                            if (next[info.threadId] === info.parentThreadId)
+                                continue;
+                            next =
+                                next === prev
+                                    ? { ...prev, [info.threadId]: info.parentThreadId }
+                                    : { ...next, [info.threadId]: info.parentThreadId };
                         }
-                        return changed ? next : prev;
+                        return next;
                     });
-                    const openSet = new Set(openTabIdsRef.current);
-                    const candidates = infos.filter((info) => !dismissedSubAgentTabsRef.current.has(info.threadId) &&
-                        (openSet.has(info.parentThreadId) || openSet.has(info.threadId)));
-                    if (candidates.length > 0) {
-                        const shouldRefreshThreads = candidates.some((info) => !openSet.has(info.threadId) && openSet.has(info.parentThreadId));
-                        const candidateParents = new Map(candidates.map((info) => [info.threadId, info.parentThreadId]));
-                        setParentMap((prev) => {
-                            let next = prev;
-                            for (const info of candidates) {
-                                if (next[info.threadId] === info.parentThreadId)
-                                    continue;
-                                next =
-                                    next === prev
-                                        ? { ...prev, [info.threadId]: info.parentThreadId }
-                                        : { ...next, [info.threadId]: info.parentThreadId };
-                            }
-                            return next;
-                        });
-                        setSubAgentNames((prev) => {
-                            let next = prev;
-                            for (const info of candidates) {
-                                if (!info.name || next[info.threadId] === info.name)
-                                    continue;
-                                next =
-                                    next === prev
-                                        ? { ...prev, [info.threadId]: info.name }
-                                        : { ...next, [info.threadId]: info.name };
-                            }
-                            return next;
-                        });
-                        setOpenTabIds((prev) => {
-                            let next = prev;
-                            for (const info of candidates) {
-                                if (next.includes(info.threadId))
-                                    continue;
-                                const parentIdx = next.indexOf(info.parentThreadId);
-                                if (parentIdx === -1)
-                                    continue;
-                                if (next === prev)
-                                    next = [...prev];
-                                let insertIdx = parentIdx + 1;
-                                while (insertIdx < next.length) {
-                                    const siblingParent = parentMapRef.current[next[insertIdx]] ||
-                                        candidateParents.get(next[insertIdx]);
-                                    if (siblingParent !== info.parentThreadId)
-                                        break;
-                                    insertIdx++;
-                                }
-                                next.splice(insertIdx, 0, info.threadId);
+                    setSubAgentNames((prev) => {
+                        let next = prev;
+                        for (const info of candidates) {
+                            if (!info.name || next[info.threadId] === info.name)
+                                continue;
+                            next =
+                                next === prev
+                                    ? { ...prev, [info.threadId]: info.name }
+                                    : { ...next, [info.threadId]: info.name };
+                        }
+                        return next;
+                    });
+                    setOpenTabIds((prev) => {
+                        let next = prev;
+                        for (const info of candidates) {
+                            if (next.includes(info.threadId))
+                                continue;
+                            const parentIdx = next.indexOf(info.parentThreadId);
+                            if (parentIdx === -1)
+                                continue;
+                            if (next === prev)
+                                next = [...prev];
+                            let insertIdx = parentIdx + 1;
+                            while (insertIdx < next.length) {
+                                const siblingParent = parentMapRef.current[next[insertIdx]] ||
+                                    candidateParents.get(next[insertIdx]);
+                                if (siblingParent !== info.parentThreadId)
+                                    break;
+                                insertIdx++;
                             }
-                            return next;
-                        });
-                        if (shouldRefreshThreads) {
-                            refreshThreads();
+                            next.splice(insertIdx, 0, info.threadId);
                         }
+                        return next;
+                    });
+                    if (shouldRefreshThreads) {
+                        refreshThreads();
                     }
                 }
             }
-            catch {
-                // Best effort: task cards and manual history still work if this poll fails.
-            }
-            finally {
-                if (!stopped) {
-                    timer = setTimeout(hydrateAgentTeamTabs, 3000);
-                }
-            }
         }
-        hydrateAgentTeamTabs();
-        return () => {
-            stopped = true;
-            if (timer)
-                clearTimeout(timer);
-        };
-    }, [apiUrl, refreshThreads]);
+        catch {
+            // Best effort: task cards and manual history still work if this poll fails.
+        }
+    }, { intervalMs: agentTeamPollMs, pauseWhenHidden: true });
     // Focus the composer when switching tabs
     useEffect(() => {
         if (!activeThreadId)

package/dist/client/analytics/index.d.ts

@@ -1,2 +1,2 @@
-export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, type AgentChatLifecycleEvent, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "../analytics.js";
+export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, clearAnalyticsSessionId, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setAnalyticsSessionId, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, type AgentChatLifecycleEvent, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "../analytics.js";
 export { track } from "../track.js";

package/dist/client/analytics/index.js

@@ -1,2 +1,2 @@
-export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, } from "../analytics.js";
+export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, clearAnalyticsSessionId, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setAnalyticsSessionId, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, } from "../analytics.js";
 export { track } from "../track.js";

package/dist/client/analytics-session.d.ts

@@ -1,2 +1,15 @@
 export declare function getOrCreateAnalyticsAnonymousId(): string | undefined;
+/**
+ * Pin the browser session id an app wants every analytics event, agent run, and
+ * action request in this tab to carry. Returns the stored id, or `undefined`
+ * when there is no browser storage to pin it in (SSR) — the caller can tell
+ * those apart.
+ *
+ * Throws on an id the transport cannot carry rather than storing it.
+ */
+export declare function setAnalyticsSessionId(sessionId: string): string | undefined;
+/**
+ * Drop a pinned id and let the next read start a fresh rotating session.
+ */
+export declare function clearAnalyticsSessionId(): void;
 export declare function getOrCreateAnalyticsSessionId(): string | undefined;

package/dist/client/analytics-session.js

@@ -1,10 +1,17 @@
 import { serializeAnalyticsAnonymousIdCookie } from "../shared/analytics-anonymous-id.js";
 const ANONYMOUS_ID_STORAGE_KEY = "agent-native.anonymous_id";
 const SESSION_ID_STORAGE_KEY = "agent-native.session_id";
+const SESSION_ID_PIN_STORAGE_KEY = "agent-native.session_id_pin";
 const SESSION_LAST_ACTIVITY_STORAGE_KEY = "agent-native.session_last_activity";
 // 30-minute idle timeout matches GA4 / Mixpanel defaults: a tab left open
 // overnight starts a new session in the morning instead of stretching one visit.
 const SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+// The server drops the session header at 128 characters
+// (`readBrowserSessionIdHeader`), and `fetch` throws on a header value with
+// non-ASCII or newline bytes. Both are rejected at the point the id is set so a
+// bad id fails once, loudly, instead of silently unlinking every later request.
+const MAX_SESSION_ID_LENGTH = 127;
+const SAFE_SESSION_ID = /^[!-~]+$/;
 function generateVisitorId() {
     try {
         if (typeof crypto !== "undefined" &&
@@ -35,6 +42,15 @@ function safeStorageSet(key, value) {
         // private browsing / storage disabled -- best-effort
     }
 }
+function safeStorageRemove(key) {
+    try {
+        window.localStorage.removeItem(key);
+        // coercion-ok: storage that refuses writes holds no key to clear, so the caller's end state already holds
+    }
+    catch {
+        // private browsing / storage disabled -- best-effort
+    }
+}
 function syncAnalyticsAnonymousIdCookie(id) {
     try {
         const cookie = serializeAnalyticsAnonymousIdCookie(id);
@@ -57,10 +73,51 @@ export function getOrCreateAnalyticsAnonymousId() {
     syncAnalyticsAnonymousIdCookie(id);
     return id;
 }
+/**
+ * Pin the browser session id an app wants every analytics event, agent run, and
+ * action request in this tab to carry. Returns the stored id, or `undefined`
+ * when there is no browser storage to pin it in (SSR) — the caller can tell
+ * those apart.
+ *
+ * Throws on an id the transport cannot carry rather than storing it.
+ */
+export function setAnalyticsSessionId(sessionId) {
+    const trimmed = typeof sessionId === "string" ? sessionId.trim() : "";
+    if (!trimmed ||
+        trimmed.length > MAX_SESSION_ID_LENGTH ||
+        !SAFE_SESSION_ID.test(trimmed)) {
+        throw new Error(`Invalid analytics session id: expected 1-${MAX_SESSION_ID_LENGTH} printable ASCII characters with no whitespace`);
+    }
+    if (typeof window === "undefined")
+        return undefined;
+    safeStorageSet(SESSION_ID_PIN_STORAGE_KEY, trimmed);
+    safeStorageSet(SESSION_ID_STORAGE_KEY, trimmed);
+    safeStorageSet(SESSION_LAST_ACTIVITY_STORAGE_KEY, String(Date.now()));
+    return trimmed;
+}
+/**
+ * Drop a pinned id and let the next read start a fresh rotating session.
+ */
+export function clearAnalyticsSessionId() {
+    if (typeof window === "undefined")
+        return;
+    safeStorageRemove(SESSION_ID_PIN_STORAGE_KEY);
+    safeStorageRemove(SESSION_ID_STORAGE_KEY);
+    safeStorageRemove(SESSION_LAST_ACTIVITY_STORAGE_KEY);
+}
 export function getOrCreateAnalyticsSessionId() {
     if (typeof window === "undefined")
         return undefined;
     const now = Date.now();
+    // A pinned id opts out of idle rotation: the app chose it to correlate its
+    // own runs, so expiring it mid-workflow would split one correlated session
+    // into two that nothing can join back together.
+    const pinned = safeStorageGet(SESSION_ID_PIN_STORAGE_KEY);
+    if (pinned) {
+        safeStorageSet(SESSION_ID_STORAGE_KEY, pinned);
+        safeStorageSet(SESSION_LAST_ACTIVITY_STORAGE_KEY, String(now));
+        return pinned;
+    }
     const lastActivityRaw = safeStorageGet(SESSION_LAST_ACTIVITY_STORAGE_KEY);
     const lastActivity = lastActivityRaw
         ? Number.parseInt(lastActivityRaw, 10)

package/dist/client/analytics.d.ts

@@ -1,3 +1,4 @@
+export { clearAnalyticsSessionId, setAnalyticsSessionId, } from "./analytics-session.js";
 import type { SessionReplayOptions, SessionReplayStartResult } from "./session-replay.js";
 export { scrubUrl } from "./url-scrub.js";
 export { addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, type CaptureExceptionContext, type CapturedExceptionEvent, type ExceptionBreadcrumb, type ExceptionLevel, } from "./error-capture.js";

package/dist/client/analytics.js

@@ -1,6 +1,7 @@
 import { llmConnectionTrackingProperties, } from "../shared/llm-connection.js";
 import { toPostHogExceptionProperties } from "../tracking/posthog-exception.js";
 import { getOrCreateAnalyticsAnonymousId, getOrCreateAnalyticsSessionId, } from "./analytics-session.js";
+export { clearAnalyticsSessionId, setAnalyticsSessionId, } from "./analytics-session.js";
 import { fetchAgentEngineStatus, fetchAuthSessionStatus, } from "./client-status-requests.js";
 import { installErrorCapture, } from "./error-capture.js";
 import { isDynamicImportFailureMessage } from "./route-chunk-recovery.js";

package/dist/client/browser-session-bridge.js

@@ -1,11 +1,27 @@
+import { createPollEngine } from "../shared/poll-engine.js";
 import { agentNativePath } from "./api-path.js";
 import { announceAgentNativeFrameReady, defaultAgentNativeHostCommands, requestAgentNativeHostActions, requestAgentNativeHostContext, runAgentNativeHostAction, sendAgentNativeHostCommand, } from "./host-bridge.js";
 const DEFAULT_ENDPOINT = "/_agent-native/browser-sessions";
 const DEFAULT_HEARTBEAT_MS = 5_000;
 const DEFAULT_POLL_MS = 500;
+const REQUEST_ABORT_MIN_MS = 10_000;
+// Relaxed cadence floor applied while the tab is hidden — mirrors
+// use-poll-loop.ts's `pauseWhenHidden: false` default so a backgrounded tab
+// keeps heartbeating (the server-side session TTL still needs refreshing)
+// instead of going fully silent.
+const HIDDEN_INTERVAL_FLOOR_MS = 10_000;
+function isDocumentHidden() {
+    return (typeof document !== "undefined" && document.visibilityState === "hidden");
+}
 function browserSessionId() {
     return `browser-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 }
+// Bounds a single request so a hung fetch can't leave the caller waiting
+// forever on a wedged connection.
+function requestAbortMs(options) {
+    const cadence = Math.min(options.pollMs ?? DEFAULT_POLL_MS, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+    return Math.max(REQUEST_ABORT_MIN_MS, cadence * 4);
+}
 function messageError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -35,26 +51,48 @@ async function readJsonResponse(response) {
     return body;
 }
 async function postJson(options, path, body) {
-    const response = await fetchImpl(options)(endpointPath(options, path), {
-        method: "POST",
-        credentials: "include",
-        headers: {
-            "Content-Type": "application/json",
-            "X-Agent-Native-CSRF": "1",
-        },
-        body: JSON.stringify(body ?? {}),
-    });
-    return readJsonResponse(response);
+    const controller = typeof AbortController === "undefined" ? null : new AbortController();
+    const timeoutId = controller
+        ? setTimeout(() => controller.abort(), requestAbortMs(options))
+        : null;
+    try {
+        const response = await fetchImpl(options)(endpointPath(options, path), {
+            method: "POST",
+            credentials: "include",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Agent-Native-CSRF": "1",
+            },
+            body: JSON.stringify(body ?? {}),
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+        return readJsonResponse(response);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
 }
 async function deleteJson(options, path) {
-    const response = await fetchImpl(options)(endpointPath(options, path), {
-        method: "DELETE",
-        credentials: "include",
-        headers: {
-            "X-Agent-Native-CSRF": "1",
-        },
-    });
-    await readJsonResponse(response);
+    const controller = typeof AbortController === "undefined" ? null : new AbortController();
+    const timeoutId = controller
+        ? setTimeout(() => controller.abort(), requestAbortMs(options))
+        : null;
+    try {
+        const response = await fetchImpl(options)(endpointPath(options, path), {
+            method: "DELETE",
+            credentials: "include",
+            headers: {
+                "X-Agent-Native-CSRF": "1",
+            },
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+        await readJsonResponse(response);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
 }
 function hostRequestOptions(options) {
     const { endpoint: _endpoint, sessionId: _sessionId, session: _session, getContext: _getContext, actions: _actions, commands: _commands, origin: _origin, label: _label, heartbeatMs: _heartbeatMs, pollMs: _pollMs, ttlMs: _ttlMs, fetch: _fetch, ...hostOptions } = options;
@@ -224,10 +262,7 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
     let currentSessionId = options.sessionId ?? null;
     let fallbackSessionId = null;
     let started = false;
-    let heartbeatTimer;
-    let pollTimer;
-    let refreshing = false;
-    let polling = false;
+    let onVisibility;
     async function refreshRegistration() {
         const direct = hasDirectHost(options);
         const hostOptions = hostRequestOptions(options);
@@ -256,17 +291,6 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
         });
         return body.session;
     }
-    async function heartbeat() {
-        if (refreshing)
-            return;
-        refreshing = true;
-        try {
-            await refreshRegistration();
-        }
-        finally {
-            refreshing = false;
-        }
-    }
     async function claimOnce() {
         if (!currentSessionId) {
             await refreshRegistration();
@@ -286,17 +310,27 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
         }
         return request;
     }
-    async function poll() {
-        if (polling)
-            return;
-        polling = true;
-        try {
-            await claimOnce();
-        }
-        finally {
-            polling = false;
-        }
-    }
+    // This is a plain factory function, not a React component, so it can't use
+    // the usePollLoop hook — createPollEngine gives each loop the same
+    // never-overlaps/never-stalls guarantees imperatively. The relaxed hidden
+    // cadence + visibilitychange wiring below mirrors what use-poll-loop.ts
+    // does internally for `pauseWhenHidden: false`.
+    const heartbeatEngine = createPollEngine(() => refreshRegistration().then(() => { }), {
+        intervalMs: () => {
+            const base = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+            return isDocumentHidden()
+                ? Math.max(base, HIDDEN_INTERVAL_FLOOR_MS)
+                : base;
+        },
+    });
+    const pollEngine = createPollEngine(() => claimOnce().then(() => { }), {
+        intervalMs: () => {
+            const base = options.pollMs ?? DEFAULT_POLL_MS;
+            return isDocumentHidden()
+                ? Math.max(base, HIDDEN_INTERVAL_FLOOR_MS)
+                : base;
+        },
+    });
     const bridge = {
         get sessionId() {
             return currentSessionId;
@@ -308,22 +342,31 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
             if (!hasDirectHost(options)) {
                 announceAgentNativeFrameReady(hostRequestOptions(options));
             }
-            void heartbeat();
-            void poll();
-            heartbeatTimer = setInterval(() => void heartbeat(), options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
-            pollTimer = setInterval(() => void poll(), options.pollMs ?? DEFAULT_POLL_MS);
+            heartbeatEngine.start();
+            pollEngine.start();
+            onVisibility = () => {
+                if (isDocumentHidden()) {
+                    heartbeatEngine.reschedule();
+                    pollEngine.reschedule();
+                }
+                else {
+                    heartbeatEngine.pollNow();
+                    pollEngine.pollNow();
+                }
+            };
+            document.addEventListener("visibilitychange", onVisibility);
             return bridge;
         },
         stop() {
             if (!started)
                 return;
             started = false;
-            if (heartbeatTimer)
-                clearInterval(heartbeatTimer);
-            if (pollTimer)
-                clearInterval(pollTimer);
-            heartbeatTimer = undefined;
-            pollTimer = undefined;
+            heartbeatEngine.stop();
+            pollEngine.stop();
+            if (onVisibility) {
+                document.removeEventListener("visibilitychange", onVisibility);
+                onVisibility = undefined;
+            }
             if (currentSessionId) {
                 void deleteJson(options, `/${encodePathSegment(currentSessionId)}`).catch(() => { });
             }

package/dist/client/db-admin/useAgentSync.js

@@ -16,6 +16,7 @@ import { useEffect, useRef } from "react";
 import { removeAgentChatContextItem, setAgentChatContextItem, } from "../agent-chat.js";
 import { agentNativePath } from "../api-path.js";
 import { deleteClientAppState, readClientAppState, setClientAppState, } from "../application-state.js";
+import { usePollLoop } from "../use-poll-loop.js";
 const NAVIGATION_PATH = agentNativePath("/_agent-native/application-state/navigation");
 const NAVIGATE_PATH = agentNativePath("/_agent-native/application-state/navigate");
 const POLL_INTERVAL_MS = 1500;
@@ -137,50 +138,40 @@ export function useDbAdminAgentSync({ table, mode, enabled = true, }) {
 export function useNavigateConsumer(onNavigate, enabled = true) {
     const handlerRef = useRef(onNavigate);
     handlerRef.current = onNavigate;
+    const mountedRef = useRef(true);
     useEffect(() => {
-        if (!enabled)
-            return;
-        let active = true;
-        let timer;
-        const tick = async () => {
-            if (!active)
-                return;
-            try {
-                const res = await fetch(NAVIGATE_PATH, {
-                    method: "GET",
-                    credentials: "include",
-                    headers: headers(),
-                });
-                if (active && res.ok) {
-                    const data = (await res.json());
-                    if (data &&
-                        data.view === "database" &&
-                        typeof data.table === "string" &&
-                        data.table) {
-                        const target = data.table;
-                        // Clear the one-shot command before acting so it fires once.
-                        fetch(NAVIGATE_PATH, {
-                            method: "DELETE",
-                            credentials: "include",
-                            headers: headers({ "X-Agent-Native-CSRF": "1" }),
-                        }).catch(() => { });
-                        handlerRef.current(target);
-                    }
-                }
-            }
-            catch {
-                // Ignore transient errors; the next tick retries.
-            }
-            finally {
-                if (active)
-                    timer = setTimeout(tick, POLL_INTERVAL_MS);
-            }
-        };
-        timer = setTimeout(tick, POLL_INTERVAL_MS);
+        mountedRef.current = true;
         return () => {
-            active = false;
-            if (timer)
-                clearTimeout(timer);
+            mountedRef.current = false;
         };
-    }, [enabled]);
+    }, []);
+    usePollLoop(async (signal) => {
+        const res = await fetch(NAVIGATE_PATH, {
+            method: "GET",
+            credentials: "include",
+            headers: headers(),
+            signal,
+        });
+        if (!mountedRef.current || !res.ok)
+            return;
+        const data = (await res.json());
+        if (data &&
+            data.view === "database" &&
+            typeof data.table === "string" &&
+            data.table) {
+            const target = data.table;
+            // Clear the one-shot command before acting so it fires once.
+            fetch(NAVIGATE_PATH, {
+                method: "DELETE",
+                credentials: "include",
+                headers: headers({ "X-Agent-Native-CSRF": "1" }),
+            }).catch(() => { });
+            handlerRef.current(target);
+        }
+    }, {
+        intervalMs: POLL_INTERVAL_MS,
+        leading: false,
+        pauseWhenHidden: true,
+        enabled,
+    });
 }

package/dist/client/dynamic-suggestions.d.ts

@@ -15,6 +15,8 @@ export interface AgentDynamicSuggestionsConfig {
     includeStatic?: boolean;
     /** Optional app-specific deterministic suggestion builder. */
     getSuggestions?: (context: AgentDynamicSuggestionContext) => string[];
+    /** Safety-net refresh cadence in ms, for updates that don't bump app-state version. Default 30_000. */
+    pollMs?: number;
 }
 export type AgentDynamicSuggestionsOption = boolean | AgentDynamicSuggestionsConfig;
 export interface AgentDynamicSuggestionsResult {
@@ -33,6 +35,7 @@ interface NormalizedAgentDynamicSuggestionsConfig {
     max: number;
     includeStatic: boolean;
     getSuggestions?: (context: AgentDynamicSuggestionContext) => string[];
+    pollMs: number;
 }
 export declare function normalizeAgentDynamicSuggestionsConfig(option?: AgentDynamicSuggestionsOption): NormalizedAgentDynamicSuggestionsConfig;
 export declare function buildDynamicAgentSuggestions(context: AgentDynamicSuggestionContext): string[];