@agent-native/core 0.204.0 → 0.204.1-nightly-20261008034100

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

@@ -9,10 +9,15 @@ 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;
+const SETTLED_CONFIRMATIONS = 2;
+const UNREADABLE_AFTER_FAILURES = 2;
 const POLL_ABORT_MIN_MS = 10_000;
 function getPollAbortMs(interval) {
     return Math.max(POLL_ABORT_MIN_MS, interval * 4);
 }
+function isActiveRunResponse(body) {
+    return typeof body?.active === "boolean";
+}
 const EMPTY_STATE = {
     isStuck: false,
     runId: null,
@@ -24,9 +29,27 @@ const EMPTY_STATE = {
     heartbeatSinceMs: null,
     dispatchMode: null,
     hasInFlightWork: null,
+    serverSettled: false,
+    statusUnreadable: false,
 };
-export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdMs = DEFAULT_STUCK_THRESHOLD_MS, backgroundStuckThresholdMs = DEFAULT_BACKGROUND_STUCK_THRESHOLD_MS, liveBackgroundStuckThresholdMs = DEFAULT_LIVE_BACKGROUND_STUCK_THRESHOLD_MS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, apiUrl, }) {
+export function useRunStuckDetection({ threadId, enabled = true, awaitingResponse, stuckThresholdMs = DEFAULT_STUCK_THRESHOLD_MS, backgroundStuckThresholdMs = DEFAULT_BACKGROUND_STUCK_THRESHOLD_MS, liveBackgroundStuckThresholdMs = DEFAULT_LIVE_BACKGROUND_STUCK_THRESHOLD_MS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, apiUrl, }) {
     const [state, setState] = useState(EMPTY_STATE);
+    // Reset in render, not in the effect: an effect-time reset still lets the
+    // consumer's own effects act once on the previous answer. The epoch also
+    // restarts polling, which drops any poll still in flight from before.
+    const awaiting = awaitingResponse === true;
+    const [scope, setScope] = useState({ threadId, awaiting, epoch: 0 });
+    if (scope.threadId !== threadId || scope.awaiting !== awaiting) {
+        const waitingStarted = awaiting && !scope.awaiting;
+        setScope({
+            threadId,
+            awaiting,
+            epoch: scope.epoch + (waitingStarted ? 1 : 0),
+        });
+        if (waitingStarted || scope.threadId !== threadId)
+            setState(EMPTY_STATE);
+    }
+    const awaitingEpoch = scope.epoch;
     useEffect(() => {
         setState(EMPTY_STATE);
         if (!threadId || !enabled)
@@ -38,18 +61,24 @@ export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdM
         let lastObservedLocalProgressAt = null;
         let lastObservedLocalProgressSeq = null;
         let consecutivePollFailures = 0;
+        let consecutiveIdlePolls = 0;
         const nextDelayRef = { current: 2_000 };
         const pollFailureDelay = () => {
             consecutivePollFailures += 1;
+            // A poll that got no answer breaks an idle streak still being confirmed:
+            // a run can start and be missed between two idle answers that surround
+            // it. A streak that already settled stands, or the verdict would flip
+            // off and on again across one outage.
+            if (consecutiveIdlePolls < SETTLED_CONFIRMATIONS) {
+                consecutiveIdlePolls = 0;
+            }
+            if (!cancelled && consecutivePollFailures >= UNREADABLE_AFTER_FAILURES) {
+                setState((current) => current.statusUnreadable
+                    ? current
+                    : { ...current, statusUnreadable: true });
+            }
             return Math.min(Math.max(pollIntervalMs, 1) * 2 ** consecutivePollFailures, MAX_POLL_ERROR_BACKOFF_MS);
         };
-        const clearObservedRun = () => {
-            snapshotVersion += 1;
-            if (snapshotTransitionTimer)
-                clearTimeout(snapshotTransitionTimer);
-            snapshotTransitionTimer = null;
-            setState(EMPTY_STATE);
-        };
         const effectiveThresholdFor = (dispatchMode, heartbeatSinceMs) => {
             const liveBackgroundWorker = dispatchMode === "background-processing" &&
                 heartbeatSinceMs != null &&
@@ -180,77 +209,87 @@ export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdM
                 const res = await fetch(`${base}/runs/active?threadId=${encodeURIComponent(threadId)}`, { credentials: "same-origin", signal });
                 if (cancelled)
                     return;
-                if (res.ok) {
-                    consecutivePollFailures = 0;
-                    const data = (await res.json());
-                    const lastProgressAt = data.lastProgressAt ?? null;
-                    const nowMs = data.serverNow ?? Date.now();
-                    const stuckSinceMs = lastProgressAt != null ? nowMs - lastProgressAt : null;
-                    const heartbeatAt = data.heartbeatAt ?? null;
-                    const heartbeatSinceMs = heartbeatAt != null ? nowMs - heartbeatAt : null;
-                    const dispatchMode = typeof data.dispatchMode === "string" ? data.dispatchMode : null;
-                    const runId = data.runId ?? null;
-                    const activeRun = getActiveRun();
-                    const localProgressObservedAt = activeRun?.threadId === threadId && activeRun.runId === runId
-                        ? (activeRun.lastProgressObservedAt ?? null)
-                        : null;
-                    const localProgressSinceMs = localProgressObservedAt == null
-                        ? null
-                        : Math.max(0, Date.now() - localProgressObservedAt);
-                    const effectiveThresholdMs = effectiveThresholdFor(dispatchMode, heartbeatSinceMs);
-                    const isStuck = Boolean(data.active &&
-                        data.status === "running" &&
-                        stuckSinceMs != null &&
-                        stuckSinceMs > effectiveThresholdMs &&
-                        (localProgressSinceMs == null ||
-                            localProgressSinceMs > effectiveThresholdMs));
-                    const observedAtMs = Date.now();
-                    const version = ++snapshotVersion;
-                    scheduleSnapshotTransition({
-                        active: data.active,
-                        runId,
-                        status: data.status ?? null,
-                        lastProgressAt,
-                        stuckSinceMs,
-                        localProgressObservedAt,
-                        lastProgressSeq: activeRun?.threadId === threadId && activeRun.runId === runId
-                            ? (activeRun.lastProgressSeq ?? null)
-                            : null,
-                        heartbeatAt,
-                        heartbeatSinceMs,
-                        dispatchMode,
-                    }, observedAtMs, version);
-                    setState({
-                        isStuck,
-                        runId,
-                        status: data.status ?? null,
-                        lastProgressAt,
-                        stuckSinceMs: localProgressSinceMs != null &&
-                            localProgressSinceMs <= effectiveThresholdMs
-                            ? null
-                            : stuckSinceMs,
-                        lastProgressSeq: activeRun?.threadId === threadId && activeRun.runId === runId
-                            ? (activeRun.lastProgressSeq ?? null)
-                            : null,
-                        heartbeatAt,
-                        heartbeatSinceMs,
-                        dispatchMode,
-                        hasInFlightWork: typeof data.hasInFlightWork === "boolean"
-                            ? data.hasInFlightWork
-                            : null,
-                    });
-                    if (!data.active || data.status !== "running") {
-                        nextDelay = IDLE_BACKOFF_INTERVAL_MS;
-                    }
+                // The endpoint answers "no run" with a 200 and a boolean `active`, so
+                // no other status or body is an idle answer: a 401/403/404 or a body
+                // without `active` leaves the run's state unknown, not gone.
+                if (!res.ok) {
+                    nextDelay = pollFailureDelay();
+                    return;
                 }
-                else if (res.status === 429 || res.status >= 500) {
+                const data = await res.json();
+                if (cancelled)
+                    return;
+                if (!isActiveRunResponse(data)) {
                     nextDelay = pollFailureDelay();
+                    return;
                 }
-                else {
-                    consecutivePollFailures = 0;
-                    clearObservedRun();
-                    nextDelay = MAX_POLL_ERROR_BACKOFF_MS;
+                consecutiveIdlePolls = data.active ? 0 : consecutiveIdlePolls + 1;
+                const serverSettled = consecutiveIdlePolls >= SETTLED_CONFIRMATIONS;
+                const lastProgressAt = data.lastProgressAt ?? null;
+                const nowMs = data.serverNow ?? Date.now();
+                const stuckSinceMs = lastProgressAt != null ? nowMs - lastProgressAt : null;
+                const heartbeatAt = data.heartbeatAt ?? null;
+                const heartbeatSinceMs = heartbeatAt != null ? nowMs - heartbeatAt : null;
+                const dispatchMode = typeof data.dispatchMode === "string" ? data.dispatchMode : null;
+                const runId = data.runId ?? null;
+                const activeRun = getActiveRun();
+                const localProgressObservedAt = activeRun?.threadId === threadId && activeRun.runId === runId
+                    ? (activeRun.lastProgressObservedAt ?? null)
+                    : null;
+                const localProgressSinceMs = localProgressObservedAt == null
+                    ? null
+                    : Math.max(0, Date.now() - localProgressObservedAt);
+                const effectiveThresholdMs = effectiveThresholdFor(dispatchMode, heartbeatSinceMs);
+                const isStuck = Boolean(data.active &&
+                    data.status === "running" &&
+                    stuckSinceMs != null &&
+                    stuckSinceMs > effectiveThresholdMs &&
+                    (localProgressSinceMs == null ||
+                        localProgressSinceMs > effectiveThresholdMs));
+                const observedAtMs = Date.now();
+                const version = ++snapshotVersion;
+                scheduleSnapshotTransition({
+                    active: data.active,
+                    runId,
+                    status: data.status ?? null,
+                    lastProgressAt,
+                    stuckSinceMs,
+                    localProgressObservedAt,
+                    lastProgressSeq: activeRun?.threadId === threadId && activeRun.runId === runId
+                        ? (activeRun.lastProgressSeq ?? null)
+                        : null,
+                    heartbeatAt,
+                    heartbeatSinceMs,
+                    dispatchMode,
+                }, observedAtMs, version);
+                setState({
+                    isStuck,
+                    runId,
+                    status: data.status ?? null,
+                    lastProgressAt,
+                    stuckSinceMs: localProgressSinceMs != null &&
+                        localProgressSinceMs <= effectiveThresholdMs
+                        ? null
+                        : stuckSinceMs,
+                    lastProgressSeq: activeRun?.threadId === threadId && activeRun.runId === runId
+                        ? (activeRun.lastProgressSeq ?? null)
+                        : null,
+                    heartbeatAt,
+                    heartbeatSinceMs,
+                    dispatchMode,
+                    hasInFlightWork: typeof data.hasInFlightWork === "boolean"
+                        ? data.hasInFlightWork
+                        : null,
+                    serverSettled,
+                    statusUnreadable: false,
+                });
+                // The first idle answer is confirmed at the normal cadence, so a
+                // run the server has not registered yet is not called settled.
+                const confirmingIdle = !data.active && !serverSettled;
+                if (!confirmingIdle && (!data.active || data.status !== "running")) {
+                    nextDelay = IDLE_BACKOFF_INTERVAL_MS;
                 }
+                consecutivePollFailures = 0;
             }
             catch {
                 nextDelay = pollFailureDelay();
@@ -292,6 +331,7 @@ export function useRunStuckDetection({ threadId, enabled = true, stuckThresholdM
         liveBackgroundStuckThresholdMs,
         pollIntervalMs,
         apiUrl,
+        awaitingEpoch,
     ]);
     return state;
 }

package/dist/db/request-telemetry.d.ts

@@ -20,7 +20,13 @@ export interface DatabaseRequestTelemetry {
 export declare function createDatabaseRequestTelemetry(): DatabaseRequestTelemetry;
 export declare function claimStartupDatabaseTelemetry(): DatabaseRequestTelemetry | undefined;
 export declare function runWithDatabaseRequestTelemetry<T>(telemetry: DatabaseRequestTelemetry, fn: () => T): T;
-export declare function enterDatabaseRequestTelemetry(telemetry: DatabaseRequestTelemetry): void;
+/**
+ * Returns false when the runtime cannot scope telemetry to the rest of the
+ * request. workerd's AsyncLocalStorage implements `run()` but throws from
+ * `enterWith()`, and a throw here escapes the Nitro request hook and skips
+ * every hook after it, including the framework route readiness gate.
+ */
+export declare function enterDatabaseRequestTelemetry(telemetry: DatabaseRequestTelemetry): boolean;
 export declare function beginDatabaseOperation(operation: DatabaseOperationKind): (outcome: "success" | "error" | "timeout") => void;
 export declare function recordDatabaseRetry(): void;
 export declare function recordDatabaseQueryResult(sql: string, rowsReturned: number): void;

package/dist/db/request-telemetry.js

@@ -62,8 +62,27 @@ export function claimStartupDatabaseTelemetry() {
 export function runWithDatabaseRequestTelemetry(telemetry, fn) {
     return getStorage().run(telemetry, fn);
 }
+const storagesWithoutEnterWith = new WeakSet();
+/**
+ * Returns false when the runtime cannot scope telemetry to the rest of the
+ * request. workerd's AsyncLocalStorage implements `run()` but throws from
+ * `enterWith()`, and a throw here escapes the Nitro request hook and skips
+ * every hook after it, including the framework route readiness gate.
+ */
 export function enterDatabaseRequestTelemetry(telemetry) {
-    getStorage().enterWith(telemetry);
+    const storage = getStorage();
+    if (storage === NOOP_STORAGE || storagesWithoutEnterWith.has(storage)) {
+        return false;
+    }
+    try {
+        storage.enterWith(telemetry);
+        return true;
+    }
+    catch (error) {
+        storagesWithoutEnterWith.add(storage);
+        console.warn("[db] Per-request database telemetry is unavailable: AsyncLocalStorage.enterWith() failed on this runtime.", error);
+        return false;
+    }
 }
 export function beginDatabaseOperation(operation) {
     const telemetry = currentDatabaseTelemetry();

package/dist/deploy/build.d.ts

@@ -15,7 +15,15 @@ export declare const CLOUDFLARE_MODULE_WORKER_ENTRY = "worker.mjs";
 export declare function configureAwsAmplifyRuntimeOutput(serverDir: string, appDir: string, env?: NodeJS.ProcessEnv): void;
 export declare function configureAwsLambdaRuntimeOutput(serverDir: string, appDir: string, env?: NodeJS.ProcessEnv): void;
 export declare function shimCloudflarePagesModuleTimers(code: string): string;
-export declare function generateCloudflareModuleWorkerEntry(): string;
+export declare const CLOUDFLARE_SWEEP_CRON = "* * * * *";
+/**
+ * The URL path a platform scheduler requests. Under a custom framework route
+ * prefix the request boundary 404s `/_agent-native/*` before any route runs,
+ * and the server is mounted under the app base path, so the internal sweep
+ * path alone never reaches the sweep.
+ */
+export declare function publicRecurringJobsSweepPath(env?: NodeJS.ProcessEnv): string;
+export declare function generateCloudflareModuleWorkerEntry(env?: NodeJS.ProcessEnv): string;
 export declare function patchCloudflareModuleNitroEntry(code: string): string;
 export declare function configureCloudflareModuleWorkerOutput(serverDir: string): void;
 export declare const NITRO_RUNTIME_IGNORE_PATTERNS: string[];
@@ -65,6 +73,22 @@ export declare function isRecurringJobsDeployEnabled(): boolean;
 export declare function isKeepWarmDeployEnabled(): boolean;
 export declare function isKeepWarmBackgroundDeployEnabled(): boolean;
 export declare function resolveKeepWarmSchedule(): string;
+export declare function resolveVercelSweepCronSchedule(env?: NodeJS.ProcessEnv): string;
+export declare function vercelSweepCrons(sweepPaths: readonly string[], env?: NodeJS.ProcessEnv): Array<{
+    path: string;
+    schedule: string;
+}>;
+export declare function addVercelSweepCron(outputDir: string, env?: NodeJS.ProcessEnv): void;
+/**
+ * Reads back the sweep cron `addVercelSweepCron` wrote for an app mounted at
+ * `basePath`. A workspace deploy must reuse it rather than recompute it: the
+ * app's build resolved its framework route prefix from config files the
+ * workspace build never reads.
+ */
+export declare function readVercelSweepCron(outputDir: string, basePath: string): {
+    path: string;
+    schedule: string;
+};
 export declare function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd: string): void;
 export declare function emitSingleTemplateNetlifyRecurringJobsFunction(projectCwd: string): void;
 /**

package/dist/deploy/build.js

@@ -19,7 +19,7 @@ import { frameworkSessionHintCookieName, resolveAuthCookieNamespace, } from "../
 import { resolveAgentNativeBuildId } from "../shared/build-id.js";
 import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, SSR_QUERY_CACHE_KEY_HEADER, } from "../shared/cache-control.js";
 import { EMBED_TARGET_QUERY_PARAM, EMBED_TOKEN_QUERY_PARAM, } from "../shared/embed-auth.js";
-import { normalizeFrameworkRoutePrefix } from "../shared/framework-route-prefix.js";
+import { FRAMEWORK_INTERNAL_ROUTE_PREFIX, normalizeFrameworkRoutePrefix, toPublicFrameworkPath, } from "../shared/framework-route-prefix.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
 import { isTruthyRuntimeValue } from "../shared/runtime-config.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, } from "../shared/social-meta.js";
@@ -294,7 +294,79 @@ export function shimCloudflarePagesModuleTimers(code) {
     }
     return code;
 }
-export function generateCloudflareModuleWorkerEntry() {
+export const CLOUDFLARE_SWEEP_CRON = "* * * * *";
+/**
+ * The URL path a platform scheduler requests. Under a custom framework route
+ * prefix the request boundary 404s `/_agent-native/*` before any route runs,
+ * and the server is mounted under the app base path, so the internal sweep
+ * path alone never reaches the sweep.
+ */
+export function publicRecurringJobsSweepPath(env = process.env) {
+    const basePath = normalizeAppBasePath(env.VITE_APP_BASE_PATH || env.APP_BASE_PATH);
+    const publicPath = toPublicFrameworkPath(RECURRING_JOBS_SWEEP_PATH, {
+        publicPrefix: resolveBuildFrameworkRoutePrefix(env),
+    });
+    return `${basePath}${publicPath}`;
+}
+// The token format must match verifyInternalToken in
+// integrations/internal-token.ts.
+function cloudflareSweepTriggerScript(sweepPath) {
+    return `const SWEEP_CRON = ${JSON.stringify(CLOUDFLARE_SWEEP_CRON)};
+const SWEEP_PATH = ${JSON.stringify(sweepPath)};
+const SWEEP_TOKEN_SUBJECT = ${JSON.stringify(RECURRING_JOBS_SWEEP_TOKEN_SUBJECT)};
+
+async function sweepToken(secret) {
+  const timestamp = Date.now();
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(SWEEP_TOKEN_SUBJECT + ":" + timestamp),
+  );
+  const hex = Array.from(new Uint8Array(signature), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+  return timestamp + "." + hex;
+}
+
+async function runSweep(h, env, ctx) {
+  const secret = env?.A2A_SECRET;
+  if (!secret) {
+    throw new Error("[recurring-jobs] A2A_SECRET is required for the scheduled sweep");
+  }
+  const request = new Request(
+    new URL(SWEEP_PATH, env.APP_URL || "https://scheduled-sweep.invalid"),
+    {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + (await sweepToken(secret)),
+        "Content-Type": "application/json",
+        "user-agent": "agent-native-cloudflare-cron",
+      },
+      body: "{}",
+    },
+  );
+  if (typeof ctx?.waitUntil === "function") {
+    request.waitUntil = ctx.waitUntil.bind(ctx);
+  }
+  const response = await h.fetch(request, env, ctx);
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      "[recurring-jobs] Scheduled sweep failed (" + response.status + "): " + body.slice(0, 500),
+    );
+  }
+  console.log("[recurring-jobs] Scheduled sweep finished", body.slice(0, 500));
+}`;
+}
+export function generateCloudflareModuleWorkerEntry(env = process.env) {
     return `let handler;
 
 async function loadHandler() {
@@ -306,6 +378,8 @@ ${cloudflareBindingsInitScript()}
 
 ${cloudflareModuleTimerRestoreScript()}
 
+${cloudflareSweepTriggerScript(publicRecurringJobsSweepPath(env))}
+
 export default {
   async fetch(request, env, ctx) {
     if (typeof ctx?.waitUntil === "function") {
@@ -320,7 +394,10 @@ export default {
     initializeBindings(env);
     const h = await loadHandler();
     __cfRestoreModuleTimers();
-    return h.scheduled?.(controller, env, ctx);
+    await Promise.all([
+      h.scheduled?.(controller, env, ctx),
+      controller?.cron === SWEEP_CRON ? runSweep(h, env, ctx) : undefined,
+    ]);
   },
   async email(message, env, ctx) {
     initializeBindings(env);
@@ -386,6 +463,13 @@ export function configureCloudflareModuleWorkerOutput(serverDir) {
     }
     const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
     config.main = CLOUDFLARE_MODULE_WORKER_ENTRY;
+    const crons = Array.isArray(config.triggers?.crons)
+        ? config.triggers.crons.filter((cron) => typeof cron === "string")
+        : [];
+    config.triggers = {
+        ...config.triggers,
+        crons: [...new Set([...crons, CLOUDFLARE_SWEEP_CRON])],
+    };
     const compatibilityFlags = Array.isArray(config.compatibility_flags)
         ? config.compatibility_flags.filter((flag) => typeof flag === "string")
         : [];
@@ -2696,6 +2780,92 @@ export function resolveKeepWarmSchedule() {
     }
     return raw;
 }
+const DEFAULT_VERCEL_SWEEP_CRON_SCHEDULE = "* * * * *";
+// Vercel accepts a narrower grammar than cron-parser, and a schedule outside
+// it fails the deployment rather than the build.
+function vercelCronScheduleProblem(raw) {
+    const fields = raw.split(/\s+/);
+    if (fields.length !== 5 || !isValidCron(raw)) {
+        return `must be a 5-field cron expression (minute hour day month weekday); got "${raw}" (${fields.length} field(s))`;
+    }
+    if (!fields.every((field) => /^[\d*,/-]+$/.test(field))) {
+        return `must use numbers, not names such as MON or JAN, on Vercel; got "${raw}"`;
+    }
+    const [, , dayOfMonth, , dayOfWeek] = fields;
+    if (dayOfMonth !== "*" && dayOfWeek !== "*") {
+        return `cannot set both a day of the month and a day of the week on Vercel, so one must be "*"; got "${raw}"`;
+    }
+    const weekdays = dayOfWeek
+        .split(",")
+        .flatMap((part) => part.split("/")[0].split("-"));
+    if (weekdays.some((day) => day !== "*" && Number(day) > 6)) {
+        return `must number weekdays 0-6 (Sunday to Saturday) on Vercel; got "${raw}"`;
+    }
+    return null;
+}
+// Vercel Hobby rejects a deployment whose cron runs more than once a day, and
+// the build cannot see the team's plan, so the schedule is the operator's call.
+export function resolveVercelSweepCronSchedule(env = process.env) {
+    const raw = env.AGENT_NATIVE_VERCEL_CRON_SCHEDULE?.trim();
+    if (!raw)
+        return DEFAULT_VERCEL_SWEEP_CRON_SCHEDULE;
+    const problem = vercelCronScheduleProblem(raw);
+    if (problem) {
+        throw new Error(`AGENT_NATIVE_VERCEL_CRON_SCHEDULE ${problem}. ` +
+            `Example: "0 9 * * *" for once a day on Vercel Hobby.`);
+    }
+    return raw;
+}
+export function vercelSweepCrons(sweepPaths, env = process.env) {
+    const schedule = resolveVercelSweepCronSchedule(env);
+    return sweepPaths.map((sweepPath) => ({ path: sweepPath, schedule }));
+}
+export function addVercelSweepCron(outputDir, env = process.env) {
+    const configPath = path.join(outputDir, "config.json");
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`[deploy] Nitro did not generate ${configPath} for vercel`);
+    }
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const [sweepCron] = vercelSweepCrons([publicRecurringJobsSweepPath(env)], env);
+    config.crons = [
+        ...(config.crons ?? []).filter((cron) => cron.path !== sweepCron.path),
+        sweepCron,
+    ];
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    console.log(`[build] Added Vercel cron "${sweepCron.schedule}" for ${sweepCron.path}. ` +
+        "Vercel sends CRON_SECRET as its bearer, so set CRON_SECRET in the project." +
+        (env.AGENT_NATIVE_VERCEL_CRON_SCHEDULE?.trim()
+            ? ""
+            : " Hobby only allows daily crons: set AGENT_NATIVE_VERCEL_CRON_SCHEDULE " +
+                'to a daily expression such as "0 9 * * *" there.'));
+}
+const SWEEP_PATH_AFTER_PREFIX = RECURRING_JOBS_SWEEP_PATH.slice(FRAMEWORK_INTERNAL_ROUTE_PREFIX.length);
+/**
+ * Reads back the sweep cron `addVercelSweepCron` wrote for an app mounted at
+ * `basePath`. A workspace deploy must reuse it rather than recompute it: the
+ * app's build resolved its framework route prefix from config files the
+ * workspace build never reads.
+ */
+export function readVercelSweepCron(outputDir, basePath) {
+    const configPath = path.join(outputDir, "config.json");
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`[deploy] Expected Vercel build config at ${configPath}`);
+    }
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const sweepCrons = (config.crons ?? []).filter((cron) => {
+        if (!cron.path.startsWith(`${basePath}/`) ||
+            !cron.path.endsWith(SWEEP_PATH_AFTER_PREFIX)) {
+            return false;
+        }
+        const prefix = cron.path.slice(basePath.length, -SWEEP_PATH_AFTER_PREFIX.length);
+        return /^\/[^/]+$/.test(prefix);
+    });
+    if (sweepCrons.length !== 1) {
+        throw new Error(`[deploy] Expected one recurring-jobs sweep cron under ${basePath} in ${configPath}, found ${sweepCrons.length}. ` +
+            "Build the app with this version of @agent-native/core so its scheduled work runs on Vercel.");
+    }
+    return sweepCrons[0];
+}
 export function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd) {
     if (!isKeepWarmDeployEnabled()) {
         const reason = isDisabledByEnv("AGENT_NATIVE_DISABLE_KEEP_WARM")
@@ -4147,6 +4317,9 @@ export default bundle;
     if (isCloudflareModulePreset(preset)) {
         configureCloudflareModuleWorkerOutput(nitro.options.output.serverDir);
     }
+    if (preset === "vercel") {
+        addVercelSweepCron(nitro.options.output.dir);
+    }
     if (preset === "netlify" ||
         preset === "vercel" ||
         isAwsLambdaPreset(preset) ||

package/dist/deploy/workspace-deploy.js

@@ -12,7 +12,7 @@ import { DEFAULT_WORKSPACE_APP_AUDIENCE, normalizeWorkspaceAppHomePath, normaliz
 import { DISPATCH_WORKSPACE_ROOT_REDIRECTS, isValidWorkspaceAppIdFormat, } from "../shared/workspace-app-id.js";
 import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
 import { inferWorkspaceAppRootHomePath, readConfiguredWorkspaceAppHomePath, } from "../workspace-app-config.js";
-import { assertEmittedBackgroundFunctionOnDisk, isRecurringJobsDeployEnabled, } from "./build.js";
+import { assertEmittedBackgroundFunctionOnDisk, isRecurringJobsDeployEnabled, readVercelSweepCron, } from "./build.js";
 import { cloneServerBundleForFunction, pruneSsrIslandFromRewritingClone, } from "./function-bundle.js";
 import { collectImmutableAssetPaths, IMMUTABLE_ASSET_CACHE_HEADERS, } from "./immutable-assets.js";
 function workspaceFrameworkRoutePrefixEnv() {
@@ -211,9 +211,13 @@ export async function runWorkspaceDeploy(opts = {}) {
     }
     console.log(`[workspace-deploy] Building ${apps.length} app(s) for preset=${preset}`);
     const execFile = opts.execFile ?? execFileSync;
+    const sweepCrons = [];
     for (const app of apps) {
         buildOneApp(workspaceRoot, appsDir, app, preset, execFile, workspaceApps, workspaceAuthMode);
         moveAppBuildIntoWorkspaceOutput(workspaceRoot, appsDir, app, preset, distDir, vercelOutputDir, workspaceApps, workspaceAuthMode);
+        if (preset === "vercel") {
+            sweepCrons.push(readVercelSweepCron(path.join(appsDir, app, VERCEL_OUTPUT_DIR), `/${app}`));
+        }
     }
     writeWorkspaceAppManifests(workspaceRoot, apps, workspaceApps, preset);
     if (workspaceRootPage === "directory") {
@@ -224,7 +228,7 @@ export async function runWorkspaceDeploy(opts = {}) {
         writeNetlifyHeaders(distDir, apps);
     }
     else {
-        writeVercelBuildConfig(vercelOutputDir, apps, workspaceApps, workspaceRootPage);
+        writeVercelBuildConfig(vercelOutputDir, apps, workspaceApps, workspaceRootPage, sweepCrons);
     }
     if (buildOnly) {
         const outputDir = preset === "vercel" ? vercelOutputDir : distDir;
@@ -442,7 +446,7 @@ function netlifyHeaderBlock(pathname) {
         ...Object.entries(IMMUTABLE_ASSET_CACHE_HEADERS).map(([name, value]) => `  ${name}: ${value}`),
     ].join("\n");
 }
-function writeVercelBuildConfig(outputDir, apps, workspaceApps, rootPage) {
+function writeVercelBuildConfig(outputDir, apps, workspaceApps, rootPage, sweepCrons) {
     const routes = [
         ...vercelImmutableAssetHeaderRoutes(outputDir, apps),
         { handle: "filesystem" },
@@ -496,6 +500,7 @@ function writeVercelBuildConfig(outputDir, apps, workspaceApps, rootPage) {
     const config = {
         version: 3,
         routes,
+        crons: sweepCrons,
     };
     fs.writeFileSync(path.join(outputDir, "config.json"), JSON.stringify(config, null, 2) + "\n");
 }