@agent-native/core 0.144.1 → 0.144.3

package/dist/client/dynamic-suggestions.js

@@ -1,14 +1,17 @@
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { readClientAppState } from "./application-state.js";
 import { useChangeVersions } from "./use-change-version.js";
+import { usePollLoop } from "./use-poll-loop.js";
 const SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
 const DEFAULT_MAX_SUGGESTIONS = 3;
+const DEFAULT_POLL_MS = 30_000;
 export function normalizeAgentDynamicSuggestionsConfig(option) {
     if (option === false) {
         return {
             enabled: false,
             max: DEFAULT_MAX_SUGGESTIONS,
             includeStatic: true,
+            pollMs: DEFAULT_POLL_MS,
         };
     }
     if (option === true || option === undefined) {
@@ -16,6 +19,7 @@ export function normalizeAgentDynamicSuggestionsConfig(option) {
             enabled: true,
             max: DEFAULT_MAX_SUGGESTIONS,
             includeStatic: true,
+            pollMs: DEFAULT_POLL_MS,
         };
     }
     return {
@@ -25,6 +29,9 @@ export function normalizeAgentDynamicSuggestionsConfig(option) {
             : DEFAULT_MAX_SUGGESTIONS,
         includeStatic: option.includeStatic !== false,
         ...(option.getSuggestions ? { getSuggestions: option.getSuggestions } : {}),
+        pollMs: typeof option.pollMs === "number" && Number.isFinite(option.pollMs)
+            ? Math.max(0, Math.floor(option.pollMs))
+            : DEFAULT_POLL_MS,
     };
 }
 function normalizeBrowserTabId(browserTabId) {
@@ -263,64 +270,59 @@ export function useAgentDynamicSuggestionsResult(options) {
     const enabled = options.enabled !== false && config.enabled;
     const [context, setContext] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
+    // Invalidates in-flight loads from a stale scope/browserTabId/enabled
+    // generation — shared between the leading load below and the safety-net
+    // poll so a slow response from an old generation can't clobber a newer one.
+    const loadGenerationRef = useRef(0);
+    const load = useCallback(async (showLoading) => {
+        const generation = loadGenerationRef.current;
+        if (showLoading)
+            setIsLoading(true);
+        try {
+            const [navigation, selection, pendingSelection, url] = await Promise.all([
+                readScopedAppState("navigation", browserTabId),
+                readScopedAppState("selection", browserTabId),
+                readScopedAppState("pending-selection-context", browserTabId),
+                readScopedAppState("__url__", browserTabId),
+            ]);
+            if (generation !== loadGenerationRef.current)
+                return;
+            setContext({ navigation, selection, pendingSelection, url, scope });
+        }
+        catch {
+            if (generation !== loadGenerationRef.current)
+                return;
+            setContext({
+                navigation: null,
+                selection: null,
+                pendingSelection: null,
+                url: null,
+                scope,
+            });
+        }
+        finally {
+            if (generation === loadGenerationRef.current && showLoading) {
+                setIsLoading(false);
+            }
+        }
+    }, [browserTabId, scope]);
     useEffect(() => {
+        loadGenerationRef.current += 1;
         if (!enabled) {
             setContext(null);
             setIsLoading(false);
             return;
         }
-        let cancelled = false;
-        const load = async (showLoading) => {
-            if (showLoading)
-                setIsLoading(true);
-            try {
-                const [navigation, selection, pendingSelection, url] = await Promise.all([
-                    readScopedAppState("navigation", browserTabId),
-                    readScopedAppState("selection", browserTabId),
-                    readScopedAppState("pending-selection-context", browserTabId),
-                    readScopedAppState("__url__", browserTabId),
-                ]);
-                if (cancelled)
-                    return;
-                setContext({
-                    navigation,
-                    selection,
-                    pendingSelection,
-                    url,
-                    scope,
-                });
-            }
-            catch {
-                if (cancelled)
-                    return;
-                setContext({
-                    navigation: null,
-                    selection: null,
-                    pendingSelection: null,
-                    url: null,
-                    scope,
-                });
-            }
-            finally {
-                if (!cancelled && showLoading)
-                    setIsLoading(false);
-            }
-        };
         void load(true);
-        const interval = setInterval(() => {
-            // The useEffect deps already include appStateVersion, so app-state
-            // changes trigger an immediate event-driven refresh above. This
-            // interval is only a slow safety net for updates that don't bump
-            // that version — skip ticks while the tab isn't visible.
-            if (document.hidden)
-                return;
-            void load(false);
-        }, 30_000);
-        return () => {
-            cancelled = true;
-            clearInterval(interval);
-        };
-    }, [appStateVersion, browserTabId, enabled, scope, scopeKey]);
+    }, [appStateVersion, enabled, load, scopeKey, config]);
+    // Slow safety net for app-state updates that don't bump `appStateVersion`
+    // (the effect above already handles the event-driven case). `pollMs <= 0`
+    // disables it.
+    usePollLoop(() => load(false), {
+        intervalMs: config.pollMs,
+        leading: false,
+        enabled: enabled && config.pollMs > 0,
+    });
     const suggestions = useMemo(() => {
         if (!enabled) {
             return options.staticSuggestions

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

@@ -10,3 +10,4 @@ export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { AppProviders, type AppProvidersProps } from "../app-providers.js";
 export { usePinchZoom, type UsePinchZoomOptions } from "../use-pinch-zoom.js";
 export { useAvatarUrl, uploadAvatar, invalidateAvatarCache, } from "../use-avatar.js";
+export { usePollLoop, type UsePollLoopOptions, type UsePollLoopHandle, } from "../use-poll-loop.js";

package/dist/client/hooks/index.js

@@ -10,3 +10,4 @@ export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { AppProviders } from "../app-providers.js";
 export { usePinchZoom } from "../use-pinch-zoom.js";
 export { useAvatarUrl, uploadAvatar, invalidateAvatarCache, } from "../use-avatar.js";
+export { usePollLoop, } from "../use-poll-loop.js";

package/dist/client/i18n.d.ts

@@ -14,6 +14,12 @@ export interface AgentNativeI18nCatalog {
     sourceLocale?: LocaleCode;
     messages?: LocaleMessages;
     loadMessages?: (locale: LocaleCode) => Promise<LocaleMessages | null>;
+    /**
+     * Locales this app actually ships translations for. Defaults to every
+     * framework-supported locale when omitted, which only matches apps whose
+     * `loadMessages` covers all of them.
+     */
+    supportedLocales?: readonly LocaleCode[];
 }
 export interface AgentNativeI18nProviderProps {
     children: React.ReactNode;
@@ -31,6 +37,7 @@ interface LocaleContextValue {
     metadata: LocaleMetadata;
     setPreference: (preference: LocalePreference) => Promise<void>;
     loading: boolean;
+    supportedLocales: readonly LocaleCode[];
 }
 declare global {
     var __AGENT_NATIVE_LOCALE_CONTEXT__: React.Context<LocaleContextValue | null> | undefined;

package/dist/client/i18n.js

@@ -155,6 +155,7 @@ export function AgentNativeI18nProvider({ children, catalog, initialLocale, init
     const sourceLocale = catalog?.sourceLocale ?? DEFAULT_LOCALE;
     const sourceMessages = catalog?.messages ?? {};
     const loadMessages = catalog?.loadMessages;
+    const supportedLocales = catalog?.supportedLocales ?? SUPPORTED_LOCALES;
     const hydration = readHydrationPayload();
     const initialState = useMemo(() => resolveInitialState({ initialLocale, initialPreference }), [initialLocale, initialPreference]);
     const [preference, setPreferenceState] = useState(initialState.preference);
@@ -305,7 +306,15 @@ export function AgentNativeI18nProvider({ children, catalog, initialLocale, init
         metadata: LOCALE_METADATA[locale],
         setPreference,
         loading,
-    }), [loading, locale, preference, setPreference, sourceLocale]);
+        supportedLocales,
+    }), [
+        loading,
+        locale,
+        preference,
+        setPreference,
+        sourceLocale,
+        supportedLocales,
+    ]);
     return (_jsx(LocaleContext.Provider, { value: context, children: _jsx(I18nextProvider, { i18n: i18n, children: children }) }));
 }
 export function useLocale() {
@@ -472,7 +481,7 @@ export function useFormatters() {
     }), [locale]);
 }
 export function LanguagePicker({ className, includeSystem = true, label, variant = "select", }) {
-    const { locale, preference, setPreference } = useLocale();
+    const { locale, preference, setPreference, supportedLocales } = useLocale();
     const [open, setOpen] = useState(false);
     const copy = LANGUAGE_PICKER_COPY[locale] ?? LANGUAGE_PICKER_COPY[DEFAULT_LOCALE];
     const resolvedLabel = label ?? copy.label;
@@ -486,7 +495,7 @@ export function LanguagePicker({ className, includeSystem = true, label, variant
                 },
             ]
             : []),
-        ...SUPPORTED_LOCALES.map((code) => ({
+        ...supportedLocales.map((code) => ({
             value: code,
             label: `${LOCALE_METADATA[code].nativeName} (${code})`,
             description: code,

package/dist/client/index.d.ts

@@ -18,7 +18,7 @@ export { DevDatabaseLink, type DevDatabaseLinkProps, } from "./db-admin/DevDatab
 export { DbAdminPage } from "./db-admin/DbAdminPage.js";
 export { installRouteChunkRecovery, reloadForStaleChunk, recoverFromStaleChunkError, } from "./route-chunk-recovery.js";
 export { AgentTerminal, type AgentTerminalProps } from "./terminal/index.js";
-export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type AgentChatLifecycleEvent, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayOptions, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "./analytics.js";
+export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, setAnalyticsSessionId, clearAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type AgentChatLifecycleEvent, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayOptions, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "./analytics.js";
 export { track } from "./track.js";
 export { useCollaborativeDoc, isReconcileLeadClient, emailToColor, emailToName, dedupeCollabUsersByEmail, type UseCollaborativeDocOptions, type UseCollaborativeDocResult, type CollabUser, } from "../collab/client.js";
 export { AGENT_CLIENT_ID } from "../collab/agent-identity.js";

package/dist/client/index.js

@@ -18,7 +18,7 @@ export { DevDatabaseLink, } from "./db-admin/DevDatabaseLink.js";
 export { DbAdminPage } from "./db-admin/DbAdminPage.js";
 export { installRouteChunkRecovery, reloadForStaleChunk, recoverFromStaleChunkError, } from "./route-chunk-recovery.js";
 export { AgentTerminal } from "./terminal/index.js";
-export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, 
+export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, setAnalyticsSessionId, clearAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, 
 // First-party, Sentry-style error capture (auto + manual API).
 AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, } from "./analytics.js";
 export { track } from "./track.js";

package/dist/client/integrations/useIntegrationStatus.d.ts

@@ -10,5 +10,5 @@ export interface IntegrationStatus {
 export declare function useIntegrationStatus(): {
     statuses: IntegrationStatus[];
     loading: boolean;
-    refetch: () => Promise<void>;
+    refetch: (signal?: AbortSignal) => Promise<void>;
 };

package/dist/client/integrations/useIntegrationStatus.js

@@ -1,37 +1,24 @@
-import { useState, useEffect, useCallback, useRef } from "react";
+import { useState, useCallback } from "react";
 import { agentNativePath } from "../api-path.js";
+import { usePollLoop } from "../use-poll-loop.js";
 export function useIntegrationStatus() {
     const [statuses, setStatuses] = useState([]);
     const [loading, setLoading] = useState(true);
-    const mountedRef = useRef(true);
-    const fetchStatuses = useCallback(async () => {
+    const fetchStatuses = useCallback(async (signal) => {
         try {
-            const res = await fetch(agentNativePath("/_agent-native/integrations/status"));
+            const res = await fetch(agentNativePath("/_agent-native/integrations/status"), { signal });
             if (!res.ok) {
-                if (mountedRef.current)
-                    setLoading(false);
+                setLoading(false);
                 return;
             }
             const data = await res.json();
-            if (mountedRef.current) {
-                setStatuses(Array.isArray(data) ? data : []);
-                setLoading(false);
-            }
+            setStatuses(Array.isArray(data) ? data : []);
+            setLoading(false);
         }
         catch {
-            if (mountedRef.current) {
-                setLoading(false);
-            }
+            setLoading(false);
         }
     }, []);
-    useEffect(() => {
-        mountedRef.current = true;
-        fetchStatuses();
-        const interval = setInterval(fetchStatuses, 30000);
-        return () => {
-            mountedRef.current = false;
-            clearInterval(interval);
-        };
-    }, [fetchStatuses]);
+    usePollLoop(fetchStatuses, { intervalMs: 30_000 });
     return { statuses, loading, refetch: fetchStatuses };
 }

package/dist/client/notifications/NotificationsBell.js

@@ -3,7 +3,7 @@ import { IconBell, IconBellRinging, IconLoader2, IconX, } from "@tabler/icons-re
 import { useCallback, useEffect, useRef, useState } from "react";
 import { agentNativePath, appPath } from "../api-path.js";
 import { Popover, PopoverContent, PopoverTrigger, } from "../components/ui/popover.js";
-import { usePausingInterval } from "../use-pausing-interval.js";
+import { usePollLoop } from "../use-poll-loop.js";
 const POLL_MS_DEFAULT = 10_000;
 const SUPPORTS_NOTIFICATION = typeof window !== "undefined" && "Notification" in window;
 /**
@@ -47,10 +47,10 @@ export function NotificationsBell({ pollMs = POLL_MS_DEFAULT, className, browser
     // the popup loop — no second /count request), and pop Notification() for
     // any new ids. When off, we fetch just /count. The unread-list branch also
     // opts out of visibility pause so popups still fire for backgrounded tabs.
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         if (browserNotifications) {
             try {
-                const res = await fetch(agentNativePath("/_agent-native/notifications?unread=true&limit=20"));
+                const res = await fetch(agentNativePath("/_agent-native/notifications?unread=true&limit=20"), { signal });
                 if (!res.ok)
                     return;
                 const rows = (await res.json());
@@ -74,19 +74,21 @@ export function NotificationsBell({ pollMs = POLL_MS_DEFAULT, className, browser
                         new Notification(n.title, { body: n.body, tag: n.id });
                     }
                     catch {
-                        // Safari / restricted contexts may throw even when permission
-                        // claims to be granted — silent no-op.
+                        // coercion-ok: Safari / restricted contexts may throw even when
+                        // permission claims to be granted; one failed OS notification
+                        // must not abort the unread sweep around it.
                     }
                 }
                 seenIdsRef.current = seen;
             }
             catch {
-                // best-effort
+                // coercion-ok: the bell renders from the rows it already has; a
+                // failed sweep is retried by the next poll tick.
             }
             return;
         }
         try {
-            const res = await fetch(agentNativePath("/_agent-native/notifications/count"));
+            const res = await fetch(agentNativePath("/_agent-native/notifications/count"), { signal });
             if (!res.ok)
                 return;
             const data = (await res.json());
@@ -96,8 +98,11 @@ export function NotificationsBell({ pollMs = POLL_MS_DEFAULT, className, browser
             // best-effort
         }
     }, [browserNotifications]);
-    usePausingInterval(refresh, pollMs, 
-    /* pauseWhenHidden */ !browserNotifications);
+    usePollLoop(refresh, {
+        intervalMs: pollMs,
+        enabled: pollMs > 0,
+        pauseWhenHidden: !browserNotifications,
+    });
     useEffect(() => {
         if (!open)
             return;

package/dist/client/progress/RunsTray.js

@@ -6,7 +6,7 @@ import { agentNativePath } from "../api-path.js";
 import { DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, } from "../components/ui/dropdown-menu.js";
 import { useFormatters, useT } from "../i18n.js";
 import { useChangeVersion } from "../use-change-version.js";
-import { usePausingInterval } from "../use-pausing-interval.js";
+import { usePollLoop } from "../use-poll-loop.js";
 import { cn } from "../utils.js";
 const RUN_CHANGE_SETTLE_MS = 250;
 function useRunsTrayState({ pollMs = 3000, limit = 5, hideWhenIdle = true, showRecent, }) {
@@ -14,19 +14,20 @@ function useRunsTrayState({ pollMs = 3000, limit = 5, hideWhenIdle = true, showR
     const [runs, setRuns] = useState([]);
     const includeRecent = showRecent ?? !hideWhenIdle;
     const runsVersion = useChangeVersion("runs");
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         try {
             const query = new URLSearchParams({ limit: String(limit) });
             if (!includeRecent)
                 query.set("active", "true");
-            const res = await fetch(agentNativePath(`/_agent-native/runs?${query.toString()}`));
+            const res = await fetch(agentNativePath(`/_agent-native/runs?${query.toString()}`), { signal });
             if (!res.ok)
                 return;
             const rows = (await res.json());
             setRuns(rows);
         }
         catch {
-            // best-effort
+            // coercion-ok: `runs` keeps its last good value rather than being
+            // cleared to an empty tray; the next poll tick retries.
         }
     }, [includeRecent, limit]);
     useEffect(() => {
@@ -38,7 +39,7 @@ function useRunsTrayState({ pollMs = 3000, limit = 5, hideWhenIdle = true, showR
         const timeout = window.setTimeout(() => void refresh(), RUN_CHANGE_SETTLE_MS);
         return () => window.clearTimeout(timeout);
     }, [refresh, runsVersion]);
-    usePausingInterval(refresh, pollMs);
+    usePollLoop(refresh, { intervalMs: pollMs, enabled: pollMs > 0 });
     const dismissRun = useCallback(async (runId) => {
         setRuns((current) => current.filter((run) => run.id !== runId));
         try {