@agent-native/core 0.144.2 → 0.144.3

package/dist/server/interval-job.js

@@ -0,0 +1,19 @@
+import { createPollEngine } from "../shared/poll-engine.js";
+/**
+ * Run a background job on a recurring interval without hand-rolling a
+ * `running` overlap guard or a request timeout — see `createPollEngine` for
+ * the underlying guarantees. `runOnce` keeps its normal exported signature
+ * (serverless schedulers can still call it directly, bypassing the loop);
+ * this only replaces the `setInterval` + module-level flag wiring around it.
+ * The internal timer is `.unref()`'d so it never keeps the process alive on
+ * its own.
+ */
+export function startIntervalJob(runOnce, options) {
+    const engine = createPollEngine(runOnce, options);
+    engine.start();
+    return {
+        stop() {
+            engine.stop();
+        },
+    };
+}

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/shared/index.d.ts

@@ -9,6 +9,7 @@ export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnec
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, type WorkspaceAppRouteAccess, type WorkspaceAppRouteAccessFromConfig, type WorkspaceAppAudience, } from "./workspace-app-audience.js";
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { createPollEngine, type PollEngineOptions, type PollEngineHandle, } from "./poll-engine.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, type SocialMetaDescriptor, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";
 export { AGENT_ACCESS_PARAM, DEFAULT_AGENT_ACCESS_TTL_SECONDS, appendAgentAccessParam, buildAgentAccessApiUrl, buildAgentAccessUrl, normalizeAgentAccessBasePath, normalizeAgentAccessOrigin, scopedAgentAccessResourceId, toAgentAccessUrl, type AgentAccessApiUrlOptions, type AgentAccessResourceScope, type AgentAccessUrlOptions, } from "./agent-access.js";

package/dist/shared/index.js

@@ -9,6 +9,7 @@ export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, } from "./workspace-app-audience.js";
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { createPollEngine, } from "./poll-engine.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";
 export { AGENT_ACCESS_PARAM, DEFAULT_AGENT_ACCESS_TTL_SECONDS, appendAgentAccessParam, buildAgentAccessApiUrl, buildAgentAccessUrl, normalizeAgentAccessBasePath, normalizeAgentAccessOrigin, scopedAgentAccessResourceId, toAgentAccessUrl, } from "./agent-access.js";

package/dist/shared/poll-engine.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared recurring-poll engine used by both `usePollLoop` (client) and
+ * `startIntervalJob` (server) so every polling loop in the codebase gets the
+ * same three properties for free instead of hand-rolling them per call site:
+ *
+ * 1. Never overlaps: the next attempt is scheduled via `setTimeout` only
+ *    after the current one settles, not on a fixed `setInterval` cadence.
+ *    This also avoids the latency `setInterval` + skip-if-busy introduces —
+ *    a skipped tick there means waiting a full extra cadence before the next
+ *    retry; here the gap after completion is always exactly `intervalMs`.
+ * 2. Never stalls silently: every attempt is bounded by a timeout (paired
+ *    with an `AbortController` so a `fetch` can actually cancel, not just be
+ *    abandoned), and that timeout reports through `onError` the moment it
+ *    fires. An attempt that ignores its `signal` keeps holding the loop —
+ *    reported, not hidden — because releasing the slot to the next attempt
+ *    would trade a visible stall for a silent overlap.
+ * 3. Never double-fires: a single internal in-flight flag, owned by this
+ *    engine rather than duplicated in every caller.
+ */
+export interface PollEngineOptions {
+    /** Delay in ms before the next attempt. Evaluated fresh before each schedule. */
+    intervalMs: number | (() => number);
+    /** Per-attempt timeout. Default: `Math.max(timeoutFloorMs, intervalMs * 4)`. */
+    timeoutMs?: number | (() => number);
+    /** Floor used by the default `timeoutMs`. Default: 10_000. */
+    timeoutFloorMs?: number;
+    /** Called when an attempt throws or times out. Default: swallow. */
+    onError?: (err: unknown) => void;
+    /** Run the first attempt immediately on `start()`. Default: true. */
+    leading?: boolean;
+}
+export interface PollEngineHandle {
+    /** Arm the loop. No-op if already running. */
+    start(): void;
+    /** Halt the loop and abort any in-flight attempt; its eventual settlement is a no-op. */
+    stop(): void;
+    /** Cancel the pending wait and run now. No-op if not running or an attempt is already in flight. */
+    pollNow(): void;
+    /**
+     * Re-arm the pending wait using a freshly resolved `intervalMs`, without
+     * running an attempt. Use this when `intervalMs` is a function whose
+     * result can change externally (e.g. tab visibility) — otherwise a
+     * change only takes effect the next time an attempt completes. No-op if
+     * there's no pending wait (not running, or an attempt is in flight).
+     */
+    reschedule(): void;
+    readonly isRunning: boolean;
+}
+export declare function createPollEngine(attempt: (signal: AbortSignal) => Promise<void>, options: PollEngineOptions): PollEngineHandle;

package/dist/shared/poll-engine.js

@@ -0,0 +1,148 @@
+/**
+ * Shared recurring-poll engine used by both `usePollLoop` (client) and
+ * `startIntervalJob` (server) so every polling loop in the codebase gets the
+ * same three properties for free instead of hand-rolling them per call site:
+ *
+ * 1. Never overlaps: the next attempt is scheduled via `setTimeout` only
+ *    after the current one settles, not on a fixed `setInterval` cadence.
+ *    This also avoids the latency `setInterval` + skip-if-busy introduces —
+ *    a skipped tick there means waiting a full extra cadence before the next
+ *    retry; here the gap after completion is always exactly `intervalMs`.
+ * 2. Never stalls silently: every attempt is bounded by a timeout (paired
+ *    with an `AbortController` so a `fetch` can actually cancel, not just be
+ *    abandoned), and that timeout reports through `onError` the moment it
+ *    fires. An attempt that ignores its `signal` keeps holding the loop —
+ *    reported, not hidden — because releasing the slot to the next attempt
+ *    would trade a visible stall for a silent overlap.
+ * 3. Never double-fires: a single internal in-flight flag, owned by this
+ *    engine rather than duplicated in every caller.
+ */
+const DEFAULT_TIMEOUT_FLOOR_MS = 10_000;
+function resolve(value) {
+    return typeof value === "function" ? value() : value;
+}
+function maybeUnref(timer) {
+    if (timer &&
+        typeof timer === "object" &&
+        "unref" in timer &&
+        typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+export function createPollEngine(attempt, options) {
+    const timeoutFloorMs = options.timeoutFloorMs ?? DEFAULT_TIMEOUT_FLOOR_MS;
+    const getTimeoutMs = () => options.timeoutMs != null
+        ? resolve(options.timeoutMs)
+        : Math.max(timeoutFloorMs, resolve(options.intervalMs) * 4);
+    const onError = options.onError ?? (() => { });
+    const leading = options.leading ?? true;
+    let generation = 0;
+    let running = false;
+    let inFlight = false;
+    let timer = null;
+    let activeController = null;
+    function clearTimer() {
+        if (timer != null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function schedule(gen) {
+        clearTimer();
+        timer = setTimeout(() => {
+            timer = null;
+            void tick(gen);
+        }, resolve(options.intervalMs));
+        maybeUnref(timer);
+    }
+    async function tick(gen) {
+        if (gen !== generation || !running)
+            return;
+        if (inFlight) {
+            // An attempt from a superseded generation is still settling — stop()
+            // aborted it but the caller has not returned yet. Its own `finally`
+            // sees a stale generation and will not reschedule, so re-arming here
+            // is what keeps a stop()/start() cycle (tab hidden then visible) from
+            // leaving the engine alive-but-timerless, i.e. permanently dead.
+            schedule(gen);
+            return;
+        }
+        inFlight = true;
+        const controller = new AbortController();
+        activeController = controller;
+        const timeoutMs = getTimeoutMs();
+        const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
+        maybeUnref(abortTimer);
+        let reported = false;
+        const report = (err) => {
+            if (reported)
+                return;
+            reported = true;
+            onError(err);
+        };
+        // The attempt is retained separately from the timeout race below. The
+        // timeout reports a slow attempt immediately, but the in-flight slot is
+        // only released once the attempt itself settles: releasing on the
+        // timeout would let the next tick start while an attempt that ignores
+        // `signal` is still doing work, which is the overlap (duplicate external
+        // requests, racing writes) this engine exists to prevent. An attempt that
+        // never settles blocks further attempts by design — `onError` has already
+        // fired, so it is loud rather than silent.
+        const settled = Promise.resolve()
+            .then(() => attempt(controller.signal))
+            .then(() => { }, (err) => report(err));
+        try {
+            await Promise.race([
+                settled,
+                new Promise((_, reject) => {
+                    controller.signal.addEventListener("abort", () => reject(new Error(`poll attempt timed out after ${timeoutMs}ms`)), { once: true });
+                }),
+            ]);
+        }
+        catch (err) {
+            report(err);
+        }
+        finally {
+            await settled;
+            clearTimeout(abortTimer);
+            if (activeController === controller)
+                activeController = null;
+            inFlight = false;
+            if (gen === generation && running)
+                schedule(gen);
+        }
+    }
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            generation++;
+            const gen = generation;
+            if (leading)
+                void tick(gen);
+            else
+                schedule(gen);
+        },
+        stop() {
+            running = false;
+            generation++;
+            clearTimer();
+            activeController?.abort();
+        },
+        pollNow() {
+            if (!running || inFlight)
+                return;
+            clearTimer();
+            void tick(generation);
+        },
+        reschedule() {
+            if (!running || inFlight || timer == null)
+                return;
+            schedule(generation);
+        },
+        get isRunning() {
+            return running;
+        },
+    };
+}

package/dist/templates/default/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

package/dist/templates/workspace-core/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

package/dist/tracking/providers.js

@@ -38,7 +38,16 @@ function setTimer(t) {
 function enqueue(url, body, headers, options) {
     const queue = getQueue();
     queue.push({ url, body, headers });
-    if (options?.flushImmediately || queue.length >= MAX_BATCH_SIZE) {
+    // The batch timer is unref'd so it never keeps a long-lived server alive —
+    // but on Netlify/Vercel/Lambda the execution environment can freeze the
+    // moment the event loop looks empty, which is exactly when an unref'd timer
+    // doesn't count. Without a signal, a warm container freezing between
+    // invocations never fires that timer, silently dropping every provider's
+    // queued events for a request that ends in a crash. Default to flushing
+    // synchronously with the response in that environment; a caller (e.g.
+    // Agent Native Analytics' flush-mode override) can still force either way.
+    const flushImmediately = options?.flushImmediately ?? isServerlessRuntime();
+    if (flushImmediately || queue.length >= MAX_BATCH_SIZE) {
         void drainQueue();
     }
     else if (!getTimer()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.144.2",
+  "version": "0.144.3",
   "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": {
@@ -72,6 +72,7 @@
     "./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/interval-job": "./dist/server/interval-job.js",
     "./server/sse": "./dist/server/sse.js",
     "./server/short-lived-token": "./dist/server/short-lived-token.js",
     "./integrations": "./dist/integrations/index.js",
@@ -411,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.3"
+    "@agent-native/toolkit": "^0.13.3",
+    "@agent-native/recap-cli": "0.5.3"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/default/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

package/src/templates/workspace-core/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.