@agent-native/core 0.144.1 → 0.144.3

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -77,6 +77,7 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
 }, z.core.$strip>>, {
     id?: undefined;
     deleted?: undefined;
+    found?: undefined;
     providers: {
         id: string;
         label: string;
@@ -88,15 +89,14 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }[];
     count: number;
     provider?: undefined;
-    found?: undefined;
     registered?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
     id?: undefined;
     deleted?: undefined;
-    count?: undefined;
     providers?: undefined;
+    count?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
@@ -104,8 +104,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     deleted?: undefined;
-    count?: undefined;
     providers?: undefined;
+    count?: undefined;
     provider?: undefined;
     found: boolean;
     id: string;
@@ -113,10 +113,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
-    count?: undefined;
+    found?: undefined;
     providers?: undefined;
+    count?: undefined;
     provider?: undefined;
-    found?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
@@ -124,10 +124,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     deleted?: undefined;
-    count?: undefined;
+    found?: undefined;
     providers?: undefined;
+    count?: undefined;
     provider?: undefined;
-    found?: undefined;
     registered: boolean;
     id: string;
     label: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,10 +311,10 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        message?: undefined;
         id?: undefined;
         provider?: undefined;
         deleted?: undefined;
+        found?: undefined;
         providers: {
             id: string;
             label: string;
@@ -325,45 +325,45 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
-        found?: undefined;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        count?: undefined;
+    } | {
         id?: undefined;
         deleted?: undefined;
+        count?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        count?: undefined;
+    } | {
         provider?: undefined;
         deleted?: undefined;
+        count?: undefined;
         providers?: undefined;
         found: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        count?: undefined;
+    } | {
         provider?: undefined;
-        providers?: undefined;
         found?: undefined;
+        count?: undefined;
+        providers?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
+        message?: undefined;
     } | {
-        count?: undefined;
         provider?: undefined;
         deleted?: undefined;
-        providers?: undefined;
         found?: undefined;
+        count?: undefined;
+        providers?: undefined;
         registered: boolean;
         id: string;
         label: string;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/action-routes.js

@@ -7,7 +7,7 @@ import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
 import { actionCallIsReadOnly, notifyActionChange } from "./action-change.js";
-import { seedAgentRunOwnerContext, } from "./agent-run-context.js";
+import { readBrowserSessionIdHeader, seedAgentRunOwnerContext, } from "./agent-run-context.js";
 import { captureError } from "./capture-error.js";
 import { getAllowedCorsOrigin as resolveAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { resolveEmbedSessionFromRequest, resolvedEmbedCapabilityScope, } from "./embed-session.js";
@@ -158,7 +158,7 @@ function handleOptionsRequest(event) {
         }
         setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
         setResponseHeader(event, "Access-Control-Allow-Headers", cors.credentials
-            ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,${EMBED_TARGET_HEADER}`
+            ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Session-Id,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,${EMBED_TARGET_HEADER}`
             : `${MCP_EMBED_CORS_ALLOW_HEADERS},X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id`);
     }
     setResponseStatus(event, 204);
@@ -350,12 +350,14 @@ export function mountActionRoutes(nitroApp, actions, options) {
                     : undefined;
             }
             const timezone = readTimezoneHeader(event);
+            const browserSessionId = readBrowserSessionIdHeader(event);
             return runWithRequestContext({
                 userEmail,
                 userName,
                 orgId,
                 authCapability,
                 timezone,
+                browserSessionId,
                 requestOrigin: getRequestURL(event).origin,
                 // Captured here because this is the last layer that still holds
                 // the h3 event; everything below reads it off the request store.

package/dist/server/agent-chat-plugin.js

@@ -41,6 +41,7 @@ import { captureError } from "./capture-error.js";
 import { getH3App, markDefaultPluginProvided, trackPluginInit, } from "./framework-request-handler.js";
 import { getOrigin } from "./google-oauth.js";
 import { readBody } from "./h3-helpers.js";
+import { startIntervalJob } from "./interval-job.js";
 import { getModelFamilyOverlay } from "./prompts/index.js";
 import { mountRealtimeVoiceRoutes } from "./realtime-voice.js";
 import { runWithRequestContext, getRequestContext, getRequestOrgId, getRequestUserEmail, getRequestRunContext, ensureRequestRunContext, } from "./request-context.js";
@@ -4966,35 +4967,31 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 setTimeout(() => {
                     (async () => {
                         const { UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS } = await import("../agent/run-store.js");
-                        setInterval(() => {
-                            (async () => {
-                                const { listUnclaimedBackgroundRunRows, shouldRedispatchUnclaimedBackgroundRun, reapAllStaleRuns, } = await import("../agent/run-store.js");
-                                // The unclaimed-background sweep below only matches
-                                // dispatch_mode='background' — handoffs a worker never
-                                // claimed. Once a worker CLAIMS a row nothing periodic looked
-                                // at it again, so a dead producer was only reaped when some
-                                // client request path or an unrelated run's cleanup happened
-                                // to notice (prod: 24 minutes after the last heartbeat,
-                                // against a 45s window). `reapAllStaleRuns` is per-row,
-                                // idempotent, re-checks staleness at UPDATE time and honours
-                                // the in-flight grace, so it is safe on this cadence.
-                                await reapAllStaleRuns().catch(() => { });
-                                let rows;
-                                try {
-                                    rows = await listUnclaimedBackgroundRunRows();
-                                }
-                                catch {
-                                    return; // Table may not exist yet on first boot
-                                }
-                                for (const row of rows) {
-                                    if (!shouldRedispatchUnclaimedBackgroundRun(row))
-                                        continue;
-                                    await attemptUnclaimedBackgroundRunRedispatch(row).catch(() => { });
-                                }
-                            })().catch(() => {
-                                // best-effort — never break the server
-                            });
-                        }, UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS);
+                        startIntervalJob(async () => {
+                            const { listUnclaimedBackgroundRunRows, shouldRedispatchUnclaimedBackgroundRun, reapAllStaleRuns, } = await import("../agent/run-store.js");
+                            // The unclaimed-background sweep below only matches
+                            // dispatch_mode='background' — handoffs a worker never
+                            // claimed. Once a worker CLAIMS a row nothing periodic looked
+                            // at it again, so a dead producer was only reaped when some
+                            // client request path or an unrelated run's cleanup happened
+                            // to notice (prod: 24 minutes after the last heartbeat,
+                            // against a 45s window). `reapAllStaleRuns` is per-row,
+                            // idempotent, re-checks staleness at UPDATE time and honours
+                            // the in-flight grace, so it is safe on this cadence.
+                            await reapAllStaleRuns().catch(() => { });
+                            let rows;
+                            try {
+                                rows = await listUnclaimedBackgroundRunRows();
+                            }
+                            catch {
+                                return; // Table may not exist yet on first boot
+                            }
+                            for (const row of rows) {
+                                if (!shouldRedispatchUnclaimedBackgroundRun(row))
+                                    continue;
+                                await attemptUnclaimedBackgroundRunRedispatch(row).catch(() => { });
+                            }
+                        }, { intervalMs: UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS });
                     })().catch(() => {
                         // best-effort — if run-store fails to load, the slow sweep below
                         // still provides eventual (loud) recovery.

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/agent-run-context.d.ts

@@ -14,9 +14,11 @@ export declare function readAgentRunTimezone(event: H3Event): string | undefined
  *
  * Emitted as PostHog's `$session_id` on the run's `$ai_*` events so an agent
  * trace joins to the session replay it happened in. Distinct from
- * `$ai_session_id`, which is the conversation thread.
+ * `$ai_session_id`, which is the conversation thread. Read by both the agent
+ * run path and the HTTP action route, so one visit correlates across the UI's
+ * action calls and the agent's.
  */
-export declare function readAgentRunBrowserSessionId(event: H3Event): string | undefined;
+export declare function readBrowserSessionIdHeader(event: H3Event): string | undefined;
 export declare function seedAgentRunOwnerContext(event: H3Event, ownerContext: AgentRunOwnerContext): AgentRunOwnerContext;
 export declare function seedBackgroundAgentRunOwnerContext(event: H3Event, runId: string): Promise<AgentRunOwnerContext | null>;
 export declare function resolveAgentRunOwnerContext(event: H3Event, options?: {

package/dist/server/agent-run-context.js

@@ -49,9 +49,11 @@ export function readAgentRunTimezone(event) {
  *
  * Emitted as PostHog's `$session_id` on the run's `$ai_*` events so an agent
  * trace joins to the session replay it happened in. Distinct from
- * `$ai_session_id`, which is the conversation thread.
+ * `$ai_session_id`, which is the conversation thread. Read by both the agent
+ * run path and the HTTP action route, so one visit correlates across the UI's
+ * action calls and the agent's.
  */
-export function readAgentRunBrowserSessionId(event) {
+export function readBrowserSessionIdHeader(event) {
     const raw = readHeaderValue(event, "x-agent-native-session-id");
     const value = Array.isArray(raw) ? raw[0] : raw;
     return typeof value === "string" &&
@@ -140,7 +142,7 @@ export async function resolveAgentRunOrgId(options) {
 export async function resolveAgentRunRequestContext(options) {
     const orgId = await resolveAgentRunOrgId(options);
     const timezone = readAgentRunTimezone(options.event);
-    const browserSessionId = readAgentRunBrowserSessionId(options.event);
+    const browserSessionId = readBrowserSessionIdHeader(options.event);
     const waitUntil = requestWaitUntil(options.event);
     const run = {
         ...(options.isBackgroundWorker ? { isBackgroundWorker: true } : {}),

package/dist/server/core-routes-plugin.js

@@ -33,6 +33,7 @@ import { registerBuiltinProviders } from "../tracking/providers.js";
 import { validateTrackPayload } from "../tracking/route.js";
 import { createAutomationsHandler } from "../triggers/routes.js";
 import { createAgentEngineApiKeyHandler } from "./agent-engine-api-key-route.js";
+import { readBrowserSessionIdHeader } from "./agent-run-context.js";
 import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
 import { getAppName } from "./app-name.js";
 import { getSession } from "./auth.js";
@@ -2544,6 +2545,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 try {
                     track(validation.name, properties, {
                         userId: userEmail,
+                        sessionId: readBrowserSessionIdHeader(event),
                     });
                 }
                 catch {

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export { createServer, type CreateServerOptions, type EnvKeyConfig, } from "./create-server.js";
+export { startIntervalJob, type IntervalJobOptions, type IntervalJobHandle, } from "./interval-job.js";
 export { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, isInBackgroundFunctionRuntime, resolveDurableBackgroundDispatchPath, } from "../agent/durable-background.js";
 export { readBody, readBodyWithSizeLimit, streamFile, DEFAULT_CHAT_MAX_BODY_BYTES, DEFAULT_UPLOAD_MAX_FILE_BYTES, MAX_CHAT_ATTACHMENTS_PER_MESSAGE, isAllowedUploadMimeType, } from "./h3-helpers.js";
 export { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, OPEN_ROUTE_SUBPATH, DESKTOP_OPEN_URL, VSCODE_OPEN_URL, type DeepLinkInput, } from "./deep-link.js";

package/dist/server/index.js

@@ -1,4 +1,5 @@
 export { createServer, } from "./create-server.js";
+export { startIntervalJob, } from "./interval-job.js";
 export { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, isInBackgroundFunctionRuntime, resolveDurableBackgroundDispatchPath, } from "../agent/durable-background.js";
 export { readBody, readBodyWithSizeLimit, streamFile, DEFAULT_CHAT_MAX_BODY_BYTES, DEFAULT_UPLOAD_MAX_FILE_BYTES, MAX_CHAT_ATTACHMENTS_PER_MESSAGE, isAllowedUploadMimeType, } from "./h3-helpers.js";
 export { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, OPEN_ROUTE_SUBPATH, DESKTOP_OPEN_URL, VSCODE_OPEN_URL, } from "./deep-link.js";

package/dist/server/interval-job.d.ts

@@ -0,0 +1,25 @@
+export interface IntervalJobOptions {
+    /** Delay in ms between runs. */
+    intervalMs: number;
+    /** Per-run timeout. Default: `Math.max(timeoutFloorMs, intervalMs * 4)`. */
+    timeoutMs?: number;
+    /** Floor used by the default `timeoutMs`. Default: 10_000. */
+    timeoutFloorMs?: number;
+    /** Called when a run throws or times out. Default: swallow (a background job shouldn't crash the host process). */
+    onError?: (err: unknown) => void;
+    /** Run immediately on start. Default: true. */
+    leading?: boolean;
+}
+export interface IntervalJobHandle {
+    stop(): void;
+}
+/**
+ * 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 declare function startIntervalJob(runOnce: (signal: AbortSignal) => Promise<void>, options: IntervalJobOptions): IntervalJobHandle;

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/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 }}`.