@agent-native/core 0.144.2 → 0.144.3

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/integrations/google-docs-poller.js

@@ -7,6 +7,7 @@ import { buildAssistantMessage, extractThreadMeta, } from "../agent/thread-data-
 import { attachToolSearch } from "../agent/tool-search.js";
 import { createThread, getThread, setThreadSourceIfMissing, updateThreadData, } from "../chat-threads/store.js";
 import { resolveOrgIdForEmail } from "../org/context.js";
+import { startIntervalJob, } from "../server/interval-job.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import { getServiceAccountAccessToken, getServiceAccountEmail, getStartPageToken, googleDocsAdapter, listChanges, listDocComments, } from "./adapters/google-docs.js";
 import { getIntegrationConfig, integrationConfigWriteEpoch, saveIntegrationConfig, } from "./config-store.js";
@@ -17,7 +18,13 @@ const DEFAULT_TRIGGER = "@agent";
 const processedComments = new Set();
 /** Track last-checked time per document for comment filtering */
 const lastCheckedTimes = new Map();
-let pollerInterval = null;
+let pollerJob = null;
+// Held only for the startup delay below. It counts as "already running" for
+// both the idempotency guard and stop(): `pollerJob` is still null during that
+// window, so without this a second start() would build a second independent
+// poller, and a stop() inside the window could not prevent the loop from
+// arming itself afterwards.
+let pollerStartTimer = null;
 let activeOptions = null;
 // ─── Watch Channel Management ───────────────────────────────────────────────
 /** How long a watch channel lasts (Google max is ~24h, we use 23h to renew early) */
@@ -429,7 +436,7 @@ async function persistThreadData(threadId, userText, completedRun, thread) {
  *    in case a push notification is missed
  */
 export async function startGoogleDocsPoller(options) {
-    if (pollerInterval) {
+    if (pollerJob || pollerStartTimer) {
         console.warn("[google-docs] Already running");
         return;
     }
@@ -490,8 +497,16 @@ function startPollLoop(options, intervalMs) {
             console.error("[google-docs] Poller error:", detail);
         }
     }
-    setTimeout(poll, 5000);
-    pollerInterval = setInterval(poll, intervalMs);
+    // processChanges ultimately calls the Drive/Docs REST API
+    // (adapters/google-docs.ts), none of whose fetch()s carry a request
+    // timeout — startIntervalJob's own cadence-scaled timeout backstops a hung
+    // call, same convention as SyncTransport's poll abort.
+    if (pollerStartTimer)
+        clearTimeout(pollerStartTimer);
+    pollerStartTimer = setTimeout(() => {
+        pollerStartTimer = null;
+        pollerJob = startIntervalJob(poll, { intervalMs });
+    }, 5000);
     const email = getServiceAccountEmail();
     if (process.env.DEBUG) {
         console.log(`[google-docs] Poll loop started (interval: ${intervalMs / 1000}s, service account: ${email ?? "not configured"})`);
@@ -501,9 +516,13 @@ function startPollLoop(options, intervalMs) {
  * Stop the Google Docs integration.
  */
 export async function stopGoogleDocsPoller() {
-    if (pollerInterval) {
-        clearInterval(pollerInterval);
-        pollerInterval = null;
+    if (pollerStartTimer) {
+        clearTimeout(pollerStartTimer);
+        pollerStartTimer = null;
+    }
+    if (pollerJob) {
+        pollerJob.stop();
+        pollerJob = null;
     }
     if (watchRenewalTimer) {
         clearTimeout(watchRenewalTimer);

package/dist/integrations/pending-tasks-retry-job.js

@@ -1,4 +1,5 @@
 import { getDbExec } from "../db/client.js";
+import { startIntervalJob, } from "../server/interval-job.js";
 import { hasActiveIntegrationCampaign } from "./integration-campaigns-store.js";
 import { configuredIntegrationDurableDispatchScopes, dispatchPendingIntegrationTask, isIntegrationDurableDispatchEnabledForTask, } from "./integration-durable-dispatch.js";
 import { ensurePendingTasksTable, MAX_PENDING_TASK_ATTEMPTS, } from "./pending-tasks-store.js";
@@ -39,8 +40,8 @@ const SERVERLESS_PROCESSING_STUCK_AFTER_MS = 75_000;
 const DURABLE_BACKGROUND_PROCESSING_STUCK_AFTER_MS = 16 * 60 * 1000;
 /** After this many attempts we give up and mark the task failed */
 const DEFAULT_SWEEP_LIMIT = 100;
-let retryInterval = null;
-let initialTimer = null;
+let job = null;
+let startupTimer = null;
 let activeWebhookBaseUrl;
 /**
  * Whether the table exists. Cached after first probe so we don't log every
@@ -268,38 +269,31 @@ function getProcessingStuckAfterMs() {
  * is a no-op.
  */
 export function startPendingTasksRetryJob(options) {
-    if (retryInterval)
+    if (job || startupTimer)
         return;
     activeWebhookBaseUrl = options?.webhookBaseUrl;
     // Stagger the first run a bit so we don't hammer the DB immediately on boot.
-    initialTimer = setTimeout(() => {
-        void retryStuckPendingTasks().catch((err) => {
-            console.error("[integrations] Pending-tasks retry job error:", err);
+    startupTimer = setTimeout(() => {
+        startupTimer = null;
+        job = startIntervalJob(async () => void (await retryStuckPendingTasks()), {
+            intervalMs: RETRY_INTERVAL_MS,
+            onError: (err) => {
+                console.error("[integrations] Pending-tasks retry job error:", err);
+            },
         });
     }, 10_000);
-    unrefTimer(initialTimer);
-    retryInterval = setInterval(() => {
-        void retryStuckPendingTasks().catch((err) => {
-            console.error("[integrations] Pending-tasks retry job error:", err);
-        });
-    }, RETRY_INTERVAL_MS);
-    unrefTimer(retryInterval);
+    startupTimer.unref?.();
     if (process.env.DEBUG) {
         console.log(`[integrations] Pending-tasks retry job started (every ${RETRY_INTERVAL_MS / 1000}s)`);
     }
 }
 /** Stop the retry loop. */
 export function stopPendingTasksRetryJob() {
-    if (initialTimer) {
-        clearTimeout(initialTimer);
-        initialTimer = null;
-    }
-    if (retryInterval) {
-        clearInterval(retryInterval);
-        retryInterval = null;
+    if (startupTimer) {
+        clearTimeout(startupTimer);
+        startupTimer = null;
     }
+    job?.stop();
+    job = null;
     activeWebhookBaseUrl = undefined;
 }
-function unrefTimer(timer) {
-    timer.unref?.();
-}

package/dist/integrations/plugin.js

@@ -13,6 +13,7 @@ import { resolveSecret } from "../server/credential-provider.js";
 import { getH3App, markDefaultPluginProvided, } from "../server/framework-request-handler.js";
 import { decodeOAuthState, encodeOAuthState, oauthCallbackResponse, oauthErrorPage, resolveOAuthRedirectUri, } from "../server/google-oauth.js";
 import { readBody } from "../server/h3-helpers.js";
+import { startIntervalJob, } from "../server/interval-job.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import { processA2AContinuationById, processDueA2AContinuations, reconcileTerminalA2AParentIfDisabled, recoverA2AContinuationAfterProcessorFailure, recoverDueA2AContinuations, } from "./a2a-continuation-processor.js";
 import { getA2AContinuationTaskOutcome } from "./a2a-continuations-store.js";
@@ -50,7 +51,12 @@ import { assertSlackInstallAccess, buildSlackAuthorizeUrl, exchangeSlackOAuthCod
 import { getTaskQueueStats } from "./task-queue-stats.js";
 import { listIntegrationUsageBudgets, saveIntegrationUsageBudget, } from "./usage-budget-store.js";
 import { handleWebhook, processIntegrationTask, recordIntegrationResponseDelivery, } from "./webhook-handler.js";
-let a2aContinuationRetryInterval = null;
+// Timer-driven sweep only — the atomic DB claim inside
+// processDueA2AContinuations already makes concurrent calls (this timer, the
+// opportunistic post-dispatch sweep, etc.) safe.
+let a2aContinuationJob = null;
+let a2aContinuationStartupTimer = null;
+const A2A_CONTINUATION_SWEEP_INTERVAL_MS = 60_000;
 const INTEGRATION_DELIVERY_LEASE_MS = 2 * 60_000;
 async function checkpointIntegrationDeliveryRetry(task, payload, errorMessage, event, campaignLease) {
     let terminalStatus;
@@ -156,23 +162,18 @@ async function containFailedDeliveryTransition(task, errorMessage, event) {
     });
 }
 function startA2AContinuationRetryJob(adapters) {
-    if (a2aContinuationRetryInterval)
+    if (a2aContinuationJob || a2aContinuationStartupTimer)
         return;
-    const initialTimer = setTimeout(() => {
-        processDueA2AContinuations({ adapters }).catch((err) => {
-            console.error("[integrations] A2A continuation retry job failed:", err);
+    a2aContinuationStartupTimer = setTimeout(() => {
+        a2aContinuationStartupTimer = null;
+        a2aContinuationJob = startIntervalJob(() => processDueA2AContinuations({ adapters }), {
+            intervalMs: A2A_CONTINUATION_SWEEP_INTERVAL_MS,
+            onError: (err) => {
+                console.error("[integrations] A2A continuation retry job failed:", err);
+            },
         });
     }, 10_000);
-    unrefTimer(initialTimer);
-    a2aContinuationRetryInterval = setInterval(() => {
-        processDueA2AContinuations({ adapters }).catch((err) => {
-            console.error("[integrations] A2A continuation retry job failed:", err);
-        });
-    }, 60_000);
-    unrefTimer(a2aContinuationRetryInterval);
-}
-function unrefTimer(timer) {
-    timer.unref?.();
+    a2aContinuationStartupTimer.unref?.();
 }
 // ─── Google Pub/Sub OIDC verifier (for Drive changes.watch push) ────────────
 // Cache Google's public keys for OIDC verification. jose handles TTL +

package/dist/integrations/remote-push-delivery-job.js

@@ -1,12 +1,9 @@
+import { startIntervalJob, } from "../server/interval-job.js";
 import { deliverPendingRemotePushNotifications } from "./remote-push-delivery.js";
 const DELIVERY_INTERVAL_MS = 60_000;
-let retryInterval = null;
-let initialTimer = null;
-let running = false;
+let job = null;
+let startupTimer = null;
 export async function runRemotePushDelivery() {
-    if (running)
-        return;
-    running = true;
     try {
         await deliverPendingRemotePushNotifications();
     }
@@ -15,29 +12,23 @@ export async function runRemotePushDelivery() {
             error: error instanceof Error ? error.name : "UnknownError",
         });
     }
-    finally {
-        running = false;
-    }
 }
 export function startRemotePushDeliveryJob() {
-    if (retryInterval)
+    if (job || startupTimer)
         return;
-    initialTimer = setTimeout(() => void runRemotePushDelivery(), 10_000);
-    unrefTimer(initialTimer);
-    retryInterval = setInterval(() => void runRemotePushDelivery(), DELIVERY_INTERVAL_MS);
-    unrefTimer(retryInterval);
+    startupTimer = setTimeout(() => {
+        startupTimer = null;
+        job = startIntervalJob(runRemotePushDelivery, {
+            intervalMs: DELIVERY_INTERVAL_MS,
+        });
+    }, 10_000);
+    startupTimer.unref?.();
 }
 export function stopRemotePushDeliveryJob() {
-    if (initialTimer) {
-        clearTimeout(initialTimer);
-        initialTimer = null;
+    if (startupTimer) {
+        clearTimeout(startupTimer);
+        startupTimer = null;
     }
-    if (retryInterval) {
-        clearInterval(retryInterval);
-        retryInterval = null;
-    }
-    running = false;
-}
-function unrefTimer(timer) {
-    timer.unref?.();
+    job?.stop();
+    job = null;
 }

package/dist/integrations/remote-retry-job.js

@@ -1,7 +1,8 @@
+import { startIntervalJob, } from "../server/interval-job.js";
 import { retryStaleRemoteCommands } from "./remote-commands-store.js";
 const RETRY_INTERVAL_MS = 60_000;
-let retryInterval = null;
-let initialTimer = null;
+let job = null;
+let startupTimer = null;
 export async function retryRemoteCommands() {
     try {
         return await retryStaleRemoteCommands();
@@ -14,31 +15,26 @@ export async function retryRemoteCommands() {
     }
 }
 export function startRemoteCommandsRetryJob() {
-    if (retryInterval)
+    if (job || startupTimer)
         return;
-    initialTimer = setTimeout(() => {
-        void retryRemoteCommands().catch((err) => {
-            console.error("[integrations] Remote command retry job error:", err);
+    startupTimer = setTimeout(() => {
+        startupTimer = null;
+        job = startIntervalJob(async () => {
+            await retryRemoteCommands();
+        }, {
+            intervalMs: RETRY_INTERVAL_MS,
+            onError: (err) => {
+                console.error("[integrations] Remote command retry job error:", err);
+            },
         });
     }, 10_000);
-    unrefTimer(initialTimer);
-    retryInterval = setInterval(() => {
-        void retryRemoteCommands().catch((err) => {
-            console.error("[integrations] Remote command retry job error:", err);
-        });
-    }, RETRY_INTERVAL_MS);
-    unrefTimer(retryInterval);
+    startupTimer.unref?.();
 }
 export function stopRemoteCommandsRetryJob() {
-    if (initialTimer) {
-        clearTimeout(initialTimer);
-        initialTimer = null;
-    }
-    if (retryInterval) {
-        clearInterval(retryInterval);
-        retryInterval = null;
+    if (startupTimer) {
+        clearTimeout(startupTimer);
+        startupTimer = null;
     }
-}
-function unrefTimer(timer) {
-    timer.unref?.();
+    job?.stop();
+    job = null;
 }

package/dist/notifications/routes.d.ts

@@ -27,7 +27,7 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     count?: undefined;
 } | {
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
     count?: undefined;
 }>>;

package/dist/oauth-tokens/google-refresh.js

@@ -11,8 +11,11 @@
  * server plugin (see `templates/mail/server/plugins/oauth-refresh.ts`).
  */
 import { resolveGoogleProviderCredentialCandidates } from "../server/google-oauth-credentials.js";
+import { startIntervalJob } from "../server/interval-job.js";
 import { listOAuthAccounts, saveOAuthTokens } from "./store.js";
 const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+/** Bounds each per-account refresh call — this loop runs sequentially over every expiring account. */
+const REFRESH_REQUEST_TIMEOUT_MS = 15_000;
 async function refreshOne(refreshToken) {
     const credentialCandidates = resolveGoogleProviderCredentialCandidates();
     if (!credentialCandidates.length) {
@@ -30,6 +33,7 @@ async function refreshOne(refreshToken) {
                 client_secret: credentials.clientSecret,
                 grant_type: "refresh_token",
             }),
+            signal: AbortSignal.timeout(REFRESH_REQUEST_TIMEOUT_MS),
         });
         lastStatusText = res.statusText;
         data = (await res.json());
@@ -91,7 +95,6 @@ export async function refreshExpiringGoogleTokens(opts = {}) {
     }
 }
 let _started = false;
-let _timer;
 /**
  * Start the refresh loop. Idempotent — calling more than once is a no-op,
  * so multiple plugins/templates loading this in the same process are safe.
@@ -108,25 +111,15 @@ export function startGoogleTokenRefreshLoop(opts = {}) {
     }
     const intervalMs = opts.intervalMs ?? 20 * 60 * 1000;
     const bufferMs = opts.bufferMs ?? 15 * 60 * 1000;
-    // Kick off an initial pass shortly after startup (not immediately — the DB
+    // Kick off the first pass shortly after startup (not immediately — the DB
     // may still be initializing).
-    const initialTimer = setTimeout(() => {
-        refreshExpiringGoogleTokens({ bufferMs }).catch((err) => {
-            console.error("[google-refresh] initial pass failed:", err);
+    const startupTimer = setTimeout(() => {
+        startIntervalJob(() => refreshExpiringGoogleTokens({ bufferMs }), {
+            intervalMs,
+            onError: (err) => {
+                console.error("[google-refresh] refresh pass failed:", err);
+            },
         });
     }, 30_000);
-    _timer = setInterval(() => {
-        refreshExpiringGoogleTokens({ bufferMs }).catch((err) => {
-            console.error("[google-refresh] interval pass failed:", err);
-        });
-    }, intervalMs);
-    // Don't let either timer keep the process alive on its own.
-    if (typeof initialTimer === "object" &&
-        initialTimer &&
-        "unref" in initialTimer) {
-        initialTimer.unref();
-    }
-    if (typeof _timer === "object" && _timer && "unref" in _timer) {
-        _timer.unref();
-    }
+    startupTimer.unref?.();
 }

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

@@ -75,8 +75,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    deleted?: undefined;
     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;
 } | {
-    deleted?: undefined;
-    count?: undefined;
     id?: undefined;
+    deleted?: 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/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/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;