@agent-native/core 0.144.2 → 0.145.0

package/dist/client/use-run-stuck-detection.js

@@ -1,4 +1,5 @@
 import { useEffect, useState, useCallback } from "react";
+import { createPollEngine } from "../shared/poll-engine.js";
 import { agentNativePath } from "./api-path.js";
 const DEFAULT_STUCK_THRESHOLD_MS = 90_000;
 export const DEFAULT_BACKGROUND_STUCK_THRESHOLD_MS = 180_000;
@@ -7,6 +8,12 @@ const DEFAULT_POLL_INTERVAL_MS = 5_000;
 const IDLE_BACKOFF_INTERVAL_MS = 15_000;
 const MAX_POLL_ERROR_BACKOFF_MS = 30_000;
 const FRESH_BACKGROUND_HEARTBEAT_MS = 30_000;
+// Bounds each poll fetch so a hung request can't stall the self-rescheduling
+// setTimeout loop forever (the reschedule only fires once the fetch settles).
+const POLL_ABORT_MIN_MS = 10_000;
+function getPollAbortMs(interval) {
+    return Math.max(POLL_ABORT_MIN_MS, interval * 4);
+}
 const EMPTY_STATE = {
     isStuck: false,
     runId: null,
@@ -28,10 +35,15 @@ export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdM
             return;
         const base = apiUrl ?? agentNativePath("/_agent-native/agent-chat");
         let cancelled = false;
-        let timer = null;
         let snapshotTransitionTimer = null;
         let snapshotVersion = 0;
         let consecutivePollFailures = 0;
+        // The engine's own cadence varies per tick (idle backoff, error backoff),
+        // which is why intervalMs below reads from this ref instead of a fixed
+        // number. Stagger the very first poll so a freshly-started run isn't
+        // immediately classified as stuck before the server has had a chance to
+        // record any progress events.
+        const nextDelayRef = { current: 2_000 };
         const pollFailureDelay = () => {
             consecutivePollFailures += 1;
             return Math.min(Math.max(pollIntervalMs, 1) * 2 ** consecutivePollFailures, MAX_POLL_ERROR_BACKOFF_MS);
@@ -124,12 +136,10 @@ export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdM
                 scheduleSnapshotTransition(snapshot, observedAtMs, version);
             }, delayMs);
         };
-        const poll = async () => {
-            if (cancelled)
-                return;
+        const attempt = async (signal) => {
             let nextDelay = pollIntervalMs;
             try {
-                const res = await fetch(`${base}/runs/active?threadId=${encodeURIComponent(threadId)}`, { credentials: "same-origin" });
+                const res = await fetch(`${base}/runs/active?threadId=${encodeURIComponent(threadId)}`, { credentials: "same-origin", signal });
                 if (cancelled)
                     return;
                 if (res.ok) {
@@ -203,21 +213,39 @@ export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdM
                 // while the server or database recovers.
                 nextDelay = pollFailureDelay();
             }
-            if (!cancelled) {
-                timer = setTimeout(poll, nextDelay);
+            finally {
+                nextDelayRef.current = nextDelay;
+            }
+        };
+        // The per-tick backoff above needs a variable cadence, which is why this
+        // uses createPollEngine directly instead of usePollLoop (whose public
+        // intervalMs is a fixed number) — see poll-engine.ts for the
+        // never-overlaps/never-stalls guarantees this still gets for free.
+        const engine = createPollEngine(attempt, {
+            intervalMs: () => nextDelayRef.current,
+            timeoutMs: getPollAbortMs(pollIntervalMs),
+            leading: false,
+        });
+        engine.start();
+        const onVisibilityChange = () => {
+            if (document.hidden) {
+                engine.stop();
+            }
+            else {
+                // Resume immediately rather than waiting out whatever delay was
+                // pending before the tab was hidden (which may be a long backoff).
+                engine.start();
+                engine.pollNow();
             }
         };
-        // Stagger the first poll so a freshly-started run isn't immediately
-        // classified as stuck before the server has had a chance to record
-        // any progress events.
-        timer = setTimeout(poll, 2_000);
+        document.addEventListener("visibilitychange", onVisibilityChange);
         return () => {
             cancelled = true;
             snapshotVersion += 1;
-            if (timer)
-                clearTimeout(timer);
+            engine.stop();
             if (snapshotTransitionTimer)
                 clearTimeout(snapshotTransitionTimer);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
         };
     }, [
         threadId,

package/dist/file-upload/actions/upload-image.d.ts

@@ -17,11 +17,11 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
+    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
-    error?: undefined;
 }>;
 export default _default;

package/dist/framework-tools.d.ts

@@ -0,0 +1,126 @@
+import { type DatabaseToolsOption } from "./scripts/db/tool-mode.js";
+/**
+ * Optional framework tool groups an app can turn off through `frameworkTools`.
+ *
+ * Each name is also stamped onto the group's actions as
+ * `ActionEntry.frameworkGroup`. That tag is what lets a single filter subtract a
+ * group from every agent tool surface at once: `agent-chat-plugin.ts` spreads
+ * these registries at thirteen separate composition sites (interactive chat,
+ * dev, MCP-full, A2A, background jobs, triggers), and a per-site condition would
+ * be the same omission waiting to happen thirteen times.
+ *
+ * The tag has a second job: framework-tagged actions are excluded from the
+ * DEFAULT first-request tool list, so an app pays for the ~40 kit schemas only
+ * when it names them in `initialToolNames`. They stay in the searchable registry
+ * either way.
+ */
+export declare const FRAMEWORK_TOOL_GROUPS: readonly ["sharing", "review", "history", "featureFlags", "localization", "audit", "contextXray", "userProfile", "automation", "docs", "resources", "web", "workspaceApps", "chat", "email"];
+export type FrameworkToolGroup = (typeof FRAMEWORK_TOOL_GROUPS)[number];
+/**
+ * Per-group switches for the framework's own agent tools. Every group defaults
+ * to today's behavior, so omitting this option leaves the tool surface
+ * byte-identical.
+ *
+ * Turning a group off removes it from the agent surfaces only — interactive
+ * chat, MCP, A2A, and background runs. The matching HTTP action routes stay
+ * mounted (see `httpActions` in `agent-chat-plugin.ts`) because the UI reaches
+ * them through client hooks; a flag meant to trim the model's tool list must not
+ * 404 the share dialog.
+ *
+ * Note the parity cost before disabling one: the framework's contract is that
+ * anything the UI can do, the agent can do. `sharing: false` on an app that
+ * still renders `ShareButton` breaks that on purpose, and only makes sense when
+ * the app has no such surface at all.
+ */
+export interface FrameworkToolsOption {
+    /** Raw SQL tools. `"read"` (default) exposes `db-schema`/`db-query`;
+     *  `"write"` adds `db-exec`/`db-patch`; `"off"` exposes neither. */
+    database?: DatabaseToolsOption;
+    /** Extension management (`create-extension`, `update-extension`, …).
+     *  Defaults to false — only apps that intentionally let the agent build
+     *  sandboxed mini-apps should enable it. */
+    extensions?: boolean;
+    /** `share-resource`, `unshare-resource`, `list-resource-shares`,
+     *  `set-resource-visibility`, `create-agent-resource-link`. */
+    sharing?: boolean;
+    /** The inline review/comment kit (`list-review-comments`,
+     *  `create-review-comment`, `resolve-review-thread`, …). */
+    review?: boolean;
+    /** Version snapshots and restore (`create-resource-version`,
+     *  `list-resource-versions`, `restore-resource-version`, …). */
+    history?: boolean;
+    /** `get-feature-flags`, `list-feature-flags`, `set-feature-flag`. */
+    featureFlags?: boolean;
+    /** `get-localization-preference`, `set-localization-preference`. */
+    localization?: boolean;
+    /** `list-audit-events`, `get-audit-event`, `export-audit-events`. */
+    audit?: boolean;
+    /** Context X-Ray (`context-manifest-get`, `context-pin`, `context-evict`, …). */
+    contextXray?: boolean;
+    /** `get-user-profile`, `update-user-profile`, `change-appearance`. */
+    userProfile?: boolean;
+    /** Recurring jobs, automations, notifications, and progress runs. */
+    automation?: boolean;
+    /** `docs-search` over the bundled framework documentation. */
+    docs?: boolean;
+    /** The `resources` tool — workspace notes, memory, and context files. */
+    resources?: boolean;
+    /** `web-request` and `web-search`. */
+    web?: boolean;
+    /** `describe-workspace-apps` and `call-agent` for cross-app delegation. */
+    workspaceApps?: boolean;
+    /** `chat-history`, `manage-agent-engine`, `manage-agent-loop-settings`. */
+    chat?: boolean;
+    /** `core-send-email`. */
+    email?: boolean;
+    /** `"minimal"` turns every group above off, for voice-first and
+     *  single-purpose apps that want the template's own actions and nothing else.
+     *  Any explicit group key wins over the preset, so
+     *  `{ preset: "minimal", resources: true }` keeps exactly one group. */
+    preset?: "minimal";
+}
+export type FrameworkToolsConfig = FrameworkToolsOption | "minimal";
+export interface FrameworkToolsInput {
+    frameworkTools?: FrameworkToolsConfig;
+    /** @deprecated Use `frameworkTools.database`. */
+    databaseTools?: DatabaseToolsOption;
+    /** @deprecated Use `frameworkTools.extensions`. */
+    extensionTools?: boolean;
+}
+export interface ResolvedFrameworkTools {
+    /** Pass-through for `normalizeDatabaseToolsMode`; `undefined` means default. */
+    database: DatabaseToolsOption | undefined;
+    extensions: boolean;
+    disabledGroups: ReadonlySet<FrameworkToolGroup>;
+    isEnabled(group: FrameworkToolGroup): boolean;
+}
+/**
+ * Resolve the public option surface into one shape the plugin threads inward.
+ *
+ * Legacy `databaseTools` / `extensionTools` remain accepted for one minor. When
+ * both forms are present and disagree we throw at plugin init rather than
+ * picking a winner: an app that boots with a tool surface nobody chose is how a
+ * "why can't the agent see db-query" report ends up unexplainable.
+ */
+export declare function resolveFrameworkTools(input: FrameworkToolsInput | undefined): ResolvedFrameworkTools;
+/** Structural view of the one field these helpers read, so tagging utilities
+ *  stay free of an import cycle with `ActionEntry`. */
+interface FrameworkGrouped {
+    frameworkGroup?: FrameworkToolGroup;
+}
+/**
+ * Drop every action belonging to a disabled group. Returns the input untouched
+ * when nothing is disabled so the default path allocates nothing.
+ */
+export declare function filterFrameworkToolGroups<T extends FrameworkGrouped>(actions: Record<string, T>, disabledGroups: ReadonlySet<FrameworkToolGroup>): Record<string, T>;
+/** True for actions the framework contributes rather than the app's own. */
+export declare function isFrameworkGroupedAction(entry: FrameworkGrouped): boolean;
+/**
+ * Whether a group is live, for prompt builders that only receive the disabled
+ * set. Prompt text and tool schemas must agree: a prompt that names a tool the
+ * request does not carry makes the model try it, fail, and often report the
+ * capability as nonexistent — so every block naming a group's tool by name has
+ * to be gated on the same set that gates the registry.
+ */
+export declare function frameworkGroupEnabled(disabledGroups: ReadonlySet<FrameworkToolGroup> | undefined, group: FrameworkToolGroup): boolean;
+export {};

package/dist/framework-tools.js

@@ -0,0 +1,114 @@
+import { normalizeDatabaseToolsMode, } from "./scripts/db/tool-mode.js";
+/**
+ * Optional framework tool groups an app can turn off through `frameworkTools`.
+ *
+ * Each name is also stamped onto the group's actions as
+ * `ActionEntry.frameworkGroup`. That tag is what lets a single filter subtract a
+ * group from every agent tool surface at once: `agent-chat-plugin.ts` spreads
+ * these registries at thirteen separate composition sites (interactive chat,
+ * dev, MCP-full, A2A, background jobs, triggers), and a per-site condition would
+ * be the same omission waiting to happen thirteen times.
+ *
+ * The tag has a second job: framework-tagged actions are excluded from the
+ * DEFAULT first-request tool list, so an app pays for the ~40 kit schemas only
+ * when it names them in `initialToolNames`. They stay in the searchable registry
+ * either way.
+ */
+export const FRAMEWORK_TOOL_GROUPS = [
+    "sharing",
+    "review",
+    "history",
+    "featureFlags",
+    "localization",
+    "audit",
+    "contextXray",
+    "userProfile",
+    "automation",
+    "docs",
+    "resources",
+    "web",
+    "workspaceApps",
+    "chat",
+    "email",
+];
+function normalizeFrameworkToolsConfig(config) {
+    if (config === "minimal")
+        return { option: {}, minimal: true };
+    if (!config || typeof config !== "object") {
+        return { option: {}, minimal: false };
+    }
+    const { preset, ...option } = config;
+    return { option, minimal: preset === "minimal" };
+}
+function conflict(key, legacyKey, legacyValue, nestedValue) {
+    throw new Error(`[agent-native] Conflicting agent-chat options: \`${legacyKey}: ${JSON.stringify(legacyValue)}\` ` +
+        `and \`frameworkTools.${key}: ${JSON.stringify(nestedValue)}\` disagree. ` +
+        `Remove the deprecated \`${legacyKey}\` and keep \`frameworkTools.${key}\`.`);
+}
+/**
+ * Resolve the public option surface into one shape the plugin threads inward.
+ *
+ * Legacy `databaseTools` / `extensionTools` remain accepted for one minor. When
+ * both forms are present and disagree we throw at plugin init rather than
+ * picking a winner: an app that boots with a tool surface nobody chose is how a
+ * "why can't the agent see db-query" report ends up unexplainable.
+ */
+export function resolveFrameworkTools(input) {
+    const { option, minimal } = normalizeFrameworkToolsConfig(input?.frameworkTools);
+    const legacyDatabase = input?.databaseTools;
+    if (legacyDatabase !== undefined) {
+        if (option.database !== undefined &&
+            normalizeDatabaseToolsMode(legacyDatabase) !==
+                normalizeDatabaseToolsMode(option.database)) {
+            conflict("database", "databaseTools", legacyDatabase, option.database);
+        }
+        console.warn("[agent-native] `databaseTools` is deprecated — use `frameworkTools: { database: … }`.");
+    }
+    const legacyExtensions = input?.extensionTools;
+    if (legacyExtensions !== undefined) {
+        if (option.extensions !== undefined &&
+            (legacyExtensions === true) !== (option.extensions === true)) {
+            conflict("extensions", "extensionTools", legacyExtensions, option.extensions);
+        }
+        console.warn("[agent-native] `extensionTools` is deprecated — use `frameworkTools: { extensions: … }`.");
+    }
+    const database = option.database ?? legacyDatabase ?? (minimal ? "off" : undefined);
+    const extensions = option.extensions ?? legacyExtensions ?? false;
+    const disabledGroups = new Set();
+    for (const group of FRAMEWORK_TOOL_GROUPS) {
+        const explicit = option[group];
+        if (explicit === false || (explicit === undefined && minimal)) {
+            disabledGroups.add(group);
+        }
+    }
+    return {
+        database,
+        extensions,
+        disabledGroups,
+        isEnabled: (group) => !disabledGroups.has(group),
+    };
+}
+/**
+ * Drop every action belonging to a disabled group. Returns the input untouched
+ * when nothing is disabled so the default path allocates nothing.
+ */
+export function filterFrameworkToolGroups(actions, disabledGroups) {
+    if (disabledGroups.size === 0)
+        return actions;
+    return Object.fromEntries(Object.entries(actions).filter(([, entry]) => entry.frameworkGroup === undefined ||
+        !disabledGroups.has(entry.frameworkGroup)));
+}
+/** True for actions the framework contributes rather than the app's own. */
+export function isFrameworkGroupedAction(entry) {
+    return entry.frameworkGroup !== undefined;
+}
+/**
+ * Whether a group is live, for prompt builders that only receive the disabled
+ * set. Prompt text and tool schemas must agree: a prompt that names a tool the
+ * request does not carry makes the model try it, fail, and often report the
+ * capability as nonexistent — so every block naming a group's tool by name has
+ * to be gated on the same set that gates the registry.
+ */
+export function frameworkGroupEnabled(disabledGroups, group) {
+    return !disabledGroups?.has(group);
+}

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;
 }