Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat: support local Vercel Schedules under `vc dev` (#4557)

Colton Padden73adcdf316ed
diff --git a/.changeset/local-vercel-dynamic-schedules.md b/.changeset/local-vercel-dynamic-schedules.md
new file mode 100644
index 000000000..849574869
--- /dev/null
+++ b/.changeset/local-vercel-dynamic-schedules.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Dynamic schedules now use Vercel's local scheduler and queue delivery under `vc dev`, so cron and one-time occurrences fire automatically. The local consumer loads only for Vercel-backed dynamic collections; standalone `eve dev` keeps its in-memory scheduling backend.
diff --git a/packages/eve/scripts/vendor-compiled/@vercel/queue.mjs b/packages/eve/scripts/vendor-compiled/@vercel/queue.mjs
new file mode 100644
index 000000000..0ea56d58c
--- /dev/null
+++ b/packages/eve/scripts/vendor-compiled/@vercel/queue.mjs
@@ -0,0 +1,15 @@
+import { createDeclarationCopier } from "../_shared.mjs";
+
+export default {
+ packageName: "@vercel/queue",
+ compiledPath: "@vercel/queue",
+ bundling: "standalone",
+ entry: "dist/index.mjs",
+ copyDeclarations: createDeclarationCopier({
+ files: ({ distEntries }) =>
+ distEntries
+ .filter((file) => file.endsWith(".d.ts"))
+ .sort()
+ .map((file) => ({ source: file, output: file })),
+ }),
+};
diff --git a/packages/eve/scripts/vendor-compiled/index.mjs b/packages/eve/scripts/vendor-compiled/index.mjs
index 4ca94ec13..a3c376cbb 100644
--- a/packages/eve/scripts/vendor-compiled/index.mjs
+++ b/packages/eve/scripts/vendor-compiled/index.mjs
@@ -30,6 +30,7 @@ import vercelConnect from "./@vercel/connect.mjs";
import vercelDetectAgent from "./@vercel/detect-agent.mjs";
import vercelOidc from "./@vercel/oidc.mjs";
import vercelOtel from "./@vercel/otel.mjs";
+import vercelQueue from "./@vercel/queue.mjs";
import vercelSandbox from "./@vercel/sandbox.mjs";
import vercelSdk from "./@vercel/sdk.mjs";
import vercelSchedules from "./@vercel/schedules.mjs";
@@ -101,6 +102,7 @@ export const MODULES = [
vercelDetectAgent,
vercelOidc,
vercelOtel,
+ vercelQueue,
vercelSandbox,
vercelSdk,
vercelSchedules,
diff --git a/packages/eve/src/internal/nitro/host/create-application-nitro.ts b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
index 4bfe20812..33be65846 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
@@ -5,7 +5,10 @@ import { fileURLToPath } from "node:url";
import { resolveAuthoredTsConfigPath } from "#internal/authored-module-loader.js";
import { createNitro } from "nitro/builder";
import type { Nitro } from "nitro/types";
-import { hasVercelScheduleCollections } from "#internal/schedules/consumer-route.js";
+import {
+ hasVercelScheduleCollections,
+ usesLocalVercelSchedules,
+} from "#internal/schedules/consumer-route.js";
import { configureInstrumentationEntry } from "#internal/nitro/host/instrumentation-entry.js";
import { EVE_PACKAGE_NAME } from "#internal/package-name.js";
import {
@@ -722,6 +725,11 @@ export async function createDevelopmentApplicationNitro(
preset: undefined,
});
const plugins = createApplicationNitroPlugins(preparedHost);
+ if (usesLocalVercelSchedules(preparedHost.compileResult.manifest)) {
+ plugins.push(
+ resolvePackageSourceFilePath("src/internal/nitro/host/local-schedules-runtime-plugin.ts"),
+ );
+ }
if (preparedHost.compiledArtifacts.instrumentationPluginPath === undefined) {
plugins.unshift(
resolvePackageSourceFilePath("src/internal/nitro/host/local-tracing-runtime-plugin.ts"),
diff --git a/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts b/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts
index 1b5243124..bada66291 100644
--- a/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts
+++ b/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts
@@ -4,6 +4,7 @@ import { readFile } from "node:fs/promises";
import { readDevelopmentEnvironmentHostValues } from "#cli/dev/environment.js";
import { computeChannelRouteRegistrations } from "#internal/nitro/host/channel-routes.js";
import type { PreparedDevelopmentApplicationHost } from "#internal/nitro/host/types.js";
+import { usesLocalVercelSchedules } from "#internal/schedules/consumer-route.js";
export async function computeDevelopmentHostFingerprint(
host: PreparedDevelopmentApplicationHost,
@@ -41,6 +42,7 @@ export async function computeDevelopmentHostFingerprint(
channels: computeChannelRouteRegistrations(host),
environment: readDevelopmentEnvironmentHostValues(host.appRoot),
instrumentation: await readInstrumentationSource(host),
+ localScheduleConsumer: usesLocalVercelSchedules(manifest),
workflow: {
// Authored workflow bodies and step registrations are bundled into the
// host, so their sources are structural, not runtime, state.
diff --git a/packages/eve/src/internal/nitro/host/local-schedules-runtime-plugin.test.ts b/packages/eve/src/internal/nitro/host/local-schedules-runtime-plugin.test.ts
new file mode 100644
index 000000000..d1b1db17e
--- /dev/null
+++ b/packages/eve/src/internal/nitro/host/local-schedules-runtime-plugin.test.ts
@@ -0,0 +1,83 @@
+import { afterEach, expect, it, onTestFinished, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ pointer: vi.fn<() => string | undefined>(),
+ manifest: vi.fn(async (_input: { compiledArtifactsSource: unknown }) => ({
+ config: { name: "fixture" },
+ scheduleCollections: [{ providerKind: "vercel" }],
+ })),
+ receive: vi.fn(async () => ({ ok: false, reason: "empty" })),
+}));
+
+vi.mock("#compiled/@vercel/queue/index.js", () => ({
+ PollingQueueClient: class {
+ receive = mocks.receive;
+ },
+}));
+vi.mock("#internal/nitro/dev-runtime-artifacts.js", () => ({
+ resolveDevelopmentRuntimeArtifactsPointerPath: () => "pointer.json",
+ readDevelopmentRuntimeArtifactsSnapshotRoot: mocks.pointer,
+}));
+vi.mock("#runtime/loaders/manifest.js", () => ({ loadCompiledManifest: mocks.manifest }));
+vi.mock("#internal/nitro/routes/schedule-collection-consumer.js", () => ({
+ createScheduleCollectionConsumer: () => ({ handler: async () => {}, retry: () => undefined }),
+}));
+
+import installLocalSchedulesRuntimePlugin from "./local-schedules-runtime-plugin.js";
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+});
+
+it("waits for a snapshot, refreshes only on generation changes, and bounds failed polling", async () => {
+ vi.useFakeTimers();
+ vi.stubEnv("EVE_DEV_WORKER_APP_ROOT", "/fixture");
+ vi.stubEnv("VERCEL_QUEUE_BASE_URL", "http://127.0.0.1:4782");
+ vi.stubEnv("VERCEL_QUEUE_TOKEN", "queue-secret");
+ vi.stubEnv("VERCEL_SCHEDULE_TOKEN", "schedule-secret");
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ let close: (() => void) | undefined;
+ onTestFinished(() => close?.());
+ installLocalSchedulesRuntimePlugin({
+ hooks: {
+ hook: (_name, handler) => {
+ close = handler;
+ },
+ },
+ });
+
+ expect(mocks.manifest).not.toHaveBeenCalled();
+ expect(mocks.receive).not.toHaveBeenCalled();
+ expect(warn).not.toHaveBeenCalled();
+
+ mocks.pointer.mockReturnValue("/generation-one");
+ await vi.advanceTimersByTimeAsync(3_000);
+ expect(mocks.manifest).toHaveBeenCalledTimes(1);
+ expect(mocks.manifest.mock.calls[0]?.[0]).toMatchObject({
+ compiledArtifactsSource: { appRoot: "/generation-one" },
+ });
+ expect(mocks.receive).toHaveBeenCalledTimes(3);
+
+ mocks.pointer.mockReturnValue("/generation-two");
+ await vi.advanceTimersByTimeAsync(1_000);
+ expect(mocks.manifest).toHaveBeenCalledTimes(2);
+ expect(mocks.manifest.mock.calls[1]?.[0]).toMatchObject({
+ compiledArtifactsSource: { appRoot: "/generation-two" },
+ });
+
+ mocks.receive.mockRejectedValue(new Error("Authentication failed: queue-secret schedule-secret"));
+ const attempts = mocks.receive.mock.calls.length;
+ await vi.advanceTimersByTimeAsync(20_000);
+ expect(warn).toHaveBeenCalledOnce();
+ expect(warn.mock.calls[0]?.[0]).toContain("Authentication failed: [redacted] [redacted]");
+ expect(warn.mock.calls[0]?.[0]).not.toContain("queue-secret");
+ expect(warn.mock.calls[0]?.[0]).not.toContain("schedule-secret");
+ expect(mocks.receive.mock.calls.length - attempts).toBeLessThan(10);
+
+ close!();
+ const stopped = mocks.receive.mock.calls.length;
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(mocks.receive).toHaveBeenCalledTimes(stopped);
+});
diff --git a/packages/eve/src/internal/nitro/host/local-schedules-runtime-plugin.ts b/packages/eve/src/internal/nitro/host/local-schedules-runtime-plugin.ts
new file mode 100644
index 000000000..14d9c52f7
--- /dev/null
+++ b/packages/eve/src/internal/nitro/host/local-schedules-runtime-plugin.ts
@@ -0,0 +1,123 @@
+import { PollingQueueClient } from "#compiled/@vercel/queue/index.js";
+
+import { readDevelopmentRuntimeArtifactsSnapshotRoot } from "#internal/nitro/dev-runtime-artifacts.js";
+import {
+ createDevelopmentGenerationArtifactsSource,
+ createDevelopmentNitroArtifactsConfig,
+} from "#internal/nitro/host/artifacts-config.js";
+import { createScheduleCollectionConsumer } from "#internal/nitro/routes/schedule-collection-consumer.js";
+import {
+ createEveScheduleQueueTrigger,
+ hasVercelScheduleCollections,
+} from "#internal/schedules/consumer-route.js";
+import { DEVELOPMENT_WORKER_APP_ROOT_ENV } from "#internal/workflow/development-world-protocol.js";
+import { loadCompiledManifest } from "#runtime/loaders/manifest.js";
+
+export default function installLocalSchedulesRuntimePlugin(nitroApp: {
+ readonly hooks: { hook(name: "close", handler: () => void): unknown };
+}): void {
+ const appRoot = process.env[DEVELOPMENT_WORKER_APP_ROOT_ENV];
+ const baseUrl = process.env.VERCEL_QUEUE_BASE_URL;
+ const token = process.env.VERCEL_QUEUE_TOKEN;
+ if (!appRoot || !baseUrl || !token) {
+ throw new Error(
+ "Local Vercel Schedules requires eve's dev worker and the local Queues API. Start eve through `vc dev` with a CLI that supports local Schedules and Queues.",
+ );
+ }
+ const endpoint = new URL(baseUrl);
+ const queue = new PollingQueueClient({
+ deploymentId: null,
+ region: "dev1",
+ resolveBaseUrl: () => endpoint,
+ token,
+ });
+ const config = createDevelopmentNitroArtifactsConfig({ appRoot });
+ let snapshot:
+ | {
+ readonly root: string;
+ readonly consumer: ReturnType<typeof createScheduleCollectionConsumer>;
+ readonly trigger: ReturnType<typeof createEveScheduleQueueTrigger> | undefined;
+ }
+ | undefined;
+ let closed = false;
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ let lastFailure: string | undefined;
+
+ // Service-hosted queue functions are not discovered by vc dev yet.
+ const poll = async () => {
+ let delay = 1_000;
+ try {
+ const root = readDevelopmentRuntimeArtifactsSnapshotRoot(
+ config.devRuntimeArtifactsPointerPath,
+ );
+ if (root === undefined) return;
+ if (snapshot?.root !== root) {
+ const manifest = await loadCompiledManifest({
+ compiledArtifactsSource: createDevelopmentGenerationArtifactsSource({
+ appRoot,
+ runtimeAppRoot: root,
+ }),
+ });
+ snapshot = {
+ root,
+ consumer: createScheduleCollectionConsumer(
+ createDevelopmentNitroArtifactsConfig({
+ appRoot,
+ configuredWorld: manifest.config.experimental?.workflow?.world,
+ }),
+ ),
+ trigger: hasVercelScheduleCollections(manifest)
+ ? createEveScheduleQueueTrigger(manifest.config.name)
+ : undefined,
+ };
+ }
+ if (!closed && snapshot.trigger !== undefined) {
+ const {
+ consumer,
+ trigger: { topic, maxDeliveries, retryAfterSeconds },
+ } = snapshot;
+ await queue.receive(
+ topic,
+ topic,
+ async (message, metadata) => {
+ if (closed) throw new Error("Local schedule consumer is closing.");
+ await consumer.handler(message, metadata);
+ },
+ {
+ retry: (error, metadata) =>
+ consumer.retry(error, metadata) ??
+ (metadata.deliveryCount >= maxDeliveries
+ ? { acknowledge: true }
+ : { afterSeconds: retryAfterSeconds }),
+ },
+ );
+ }
+ lastFailure = undefined;
+ } catch (error) {
+ if (closed) return;
+ let reason = error instanceof Error ? error.message : "Unknown local schedule error";
+ for (const secret of [token, process.env.VERCEL_SCHEDULE_TOKEN]) {
+ if (secret) reason = reason.replaceAll(secret, "[redacted]");
+ }
+ reason = reason.slice(0, 1_000);
+ if (reason !== lastFailure) {
+ console.warn(
+ `[eve] Local schedule delivery failed: ${reason}. Check vc dev's local Queues and Schedules APIs; retrying in 5s.`,
+ );
+ lastFailure = reason;
+ }
+ delay = 5_000;
+ } finally {
+ if (!closed) {
+ timer = setTimeout(() => void poll(), delay);
+ timer.unref();
+ }
+ }
+ };
+
+ nitroApp.hooks.hook("close", () => {
+ closed = true;
+ clearTimeout(timer);
+ });
+ void poll();
+}
diff --git a/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.test.ts b/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.test.ts
index 1c4df1961..fa511f1d0 100644
--- a/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.test.ts
+++ b/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.test.ts
@@ -4,20 +4,9 @@ import type { ScheduleOccurrenceEvent } from "#public/schedules/subscription.js"
import { createScheduleCollectionPayload } from "#runtime/schedules/payload.js";
import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
-type Callback = (message: unknown, metadata: Record<string, unknown>) => Promise<void>;
-type RetryHandler = (error: unknown) => unknown;
-
const mocks = vi.hoisted(() => ({
admit: vi.fn(),
failed: vi.fn(),
- queue: {} as { callback?: Callback; retry?: RetryHandler },
-}));
-vi.mock("@vercel/queue", () => ({
- handleCallback: (callback: Callback, options: { retry: RetryHandler }) => {
- mocks.queue.callback = callback;
- mocks.queue.retry = options.retry;
- return async () => new Response(null);
- },
}));
vi.mock("#internal/nitro/routes/runtime-artifacts.js", () => ({
resolveNitroCompiledArtifactsSource: () => ({}),
@@ -39,7 +28,7 @@ vi.mock("#runtime/schedules/load-collection.js", () => ({
}),
}));
-const { handleScheduleCollectionConsumer } =
+const { createScheduleCollectionConsumer } =
await import("#internal/nitro/routes/schedule-collection-consumer.js");
const { EVE_SCHEDULE_CONSUMER_MAX_DELIVERIES } =
await import("#internal/schedules/consumer-route.js");
@@ -57,7 +46,10 @@ const payload = createScheduleCollectionPayload({
});
async function deliver(deliveryCount: number) {
- await handleScheduleCollectionConsumer({} as never, new Request("https://agent.test"));
+ const consumer = createScheduleCollectionConsumer({
+ kind: "production",
+ sandboxScope: "fixture",
+ });
const message = {
source: "dynamic",
scheduleId: "sch-1",
@@ -69,14 +61,18 @@ async function deliver(deliveryCount: number) {
};
const metadata = {
createdAt: new Date(),
+ expiresAt: new Date("2026-10-09T19:00:00Z"),
deliveryCount,
messageId: "msg-1",
topicName: deriveEveScheduleQueueTopic("fixture"),
+ consumerGroup: "fixture",
+ region: "dev1",
};
- return await mocks.queue.callback!(message, metadata).then(
+ const thrown = await Promise.resolve(consumer.handler(message, metadata)).then(
() => undefined,
(error: unknown) => error,
);
+ return { thrown, directive: consumer.retry(thrown, metadata) };
}
describe("schedule collection consumer", () => {
@@ -108,10 +104,10 @@ describe("schedule collection consumer", () => {
mocks.failed.mockClear();
mocks.admit.mockRejectedValueOnce(error);
- const thrown = await deliver(count);
+ const result = await deliver(count);
- expect(thrown).toBe(error);
- expect(mocks.queue.retry!(thrown)).toEqual(directive);
+ expect(result.thrown).toBe(error);
+ expect(result.directive).toEqual(directive);
expect(mocks.failed).toHaveBeenCalledTimes(reported ? 1 : 0);
if (reported)
expect(mocks.failed.mock.calls[0]![0] as ScheduleOccurrenceEvent).toMatchObject({
diff --git a/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts b/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts
index fbf202c6d..bf6337b7a 100644
--- a/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts
+++ b/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts
@@ -1,4 +1,8 @@
-import { handleCallback } from "@vercel/queue";
+import {
+ handleCallback,
+ type MessageHandler,
+ type RetryHandler,
+} from "#compiled/@vercel/queue/index.js";
import { SchedulesApiError, SchedulesClient } from "#compiled/@vercel/schedules/index.js";
import type { NitroArtifactsConfig } from "#internal/nitro/routes/runtime-artifacts.js";
@@ -30,8 +34,17 @@ export async function handleScheduleCollectionConsumer(
config: NitroArtifactsConfig,
request: Request,
): Promise<Response> {
- const handler = handleCallback<unknown>(
- async (message, metadata) => {
+ const { handler, retry } = createScheduleCollectionConsumer(config);
+ return await handleCallback(handler, { retry })(request);
+}
+
+/** Shares occurrence verification and dispatch between hosted callbacks and local queue polling. */
+export function createScheduleCollectionConsumer(config: NitroArtifactsConfig): {
+ readonly handler: MessageHandler<unknown>;
+ readonly retry: RetryHandler;
+} {
+ return {
+ handler: async (message, metadata) => {
const queue = expectScheduleQueueMessage(message);
const application = queue.payload.eve.application;
const collection = queue.payload.eve.collection;
@@ -109,15 +122,12 @@ export async function handleScheduleCollectionConsumer(
throw error;
}
},
- {
- retry(error) {
- return error instanceof PermanentScheduleMessageError
- ? { acknowledge: true as const }
- : undefined;
- },
+ retry(error) {
+ return error instanceof PermanentScheduleMessageError
+ ? { acknowledge: true as const }
+ : undefined;
},
- );
- return await handler(request);
+ };
}
/** Reads the delivered schedule with the collection provider's own client options. */
diff --git a/packages/eve/src/internal/schedules/consumer-route.ts b/packages/eve/src/internal/schedules/consumer-route.ts
index b8283e78d..b7c9f139b 100644
--- a/packages/eve/src/internal/schedules/consumer-route.ts
+++ b/packages/eve/src/internal/schedules/consumer-route.ts
@@ -1,3 +1,5 @@
+import type { CompiledAgentManifest } from "#compiler/manifest.js";
+import { isVercelSchedulesDevEnvironment } from "#internal/schedules/dev-environment.js";
import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
export const EVE_SCHEDULE_COLLECTION_CONSUMER_ROUTE_PATH = "/.well-known/eve/v1/schedules/consumer";
@@ -16,6 +18,12 @@ export function createEveScheduleQueueTrigger(agentName: string) {
};
}
+export function usesLocalVercelSchedules(
+ manifest: Pick<CompiledAgentManifest, "scheduleCollections">,
+): boolean {
+ return isVercelSchedulesDevEnvironment() && hasVercelScheduleCollections(manifest);
+}
+
/** Whether a build needs the Vercel schedule consumer: its route and its queue trigger. */
export function hasVercelScheduleCollections(manifest: {
readonly scheduleCollections?: readonly { readonly providerKind: string }[];
diff --git a/packages/eve/src/internal/schedules/dev-environment.ts b/packages/eve/src/internal/schedules/dev-environment.ts
new file mode 100644
index 000000000..dcb788473
--- /dev/null
+++ b/packages/eve/src/internal/schedules/dev-environment.ts
@@ -0,0 +1,8 @@
+/** Matches the Schedules SDK's CLI-hosted local environment selection. */
+export function isVercelSchedulesDevEnvironment(): boolean {
+ return (
+ process.env.NODE_ENV === "development" &&
+ process.env.VERCEL_DEPLOYMENT_ID === undefined &&
+ process.env.VERCEL_SCHEDULE_DEV_API_VERSION !== undefined
+ );
+}
diff --git a/packages/eve/src/public/schedules/providers/vercel.test.ts b/packages/eve/src/public/schedules/providers/vercel.test.ts
index fb0ed155f..2802eba8a 100644
--- a/packages/eve/src/public/schedules/providers/vercel.test.ts
+++ b/packages/eve/src/public/schedules/providers/vercel.test.ts
@@ -33,44 +33,55 @@ afterEach(() => {
});
describe("vercelScheduleProvider", () => {
- it("creates a queue-target schedule with an eve dispatch envelope using ambient OIDC", async () => {
- vi.stubEnv("VERCEL", "1");
- vi.stubEnv("VERCEL_ENV", "production");
- vi.stubEnv("VERCEL_OIDC_TOKEN", oidcToken);
- const fetchImpl = vi.fn<typeof fetch>(async () => Response.json(schedule()));
- const provider = vercelScheduleProvider({
- fetch: fetchImpl,
- baseUrl: "https://vercel-schedules.com",
- });
-
- const record = await provider.create(context, {
- expression: {
- type: "cron",
- cron: "0 12 * * *",
- timezone: "America/New_York",
- jitter: 5,
- },
- payload: "Review PRs",
- name: "review-prs-daily",
- });
-
- expect(provider.kind).toBe("vercel");
- expect(record).toMatchObject({ name: "review-prs-daily", scheduleId: "sch_1" });
- const [url, init] = fetchImpl.mock.calls[0]!;
- expect(String(url)).toBe("https://vercel-schedules.com/v1/schedules");
- expect(JSON.parse(String(init?.body))).toMatchObject({
- name: "review-prs-daily",
- namespace: "eve-namespace",
- payload: {
- eve: { application: "dynamic-schedules", collection: "collection", version: 1 },
+ it.each(["production", "local"] as const)(
+ "creates a queue-target schedule with an eve dispatch envelope in %s",
+ async (environment) => {
+ const local = environment === "local";
+ vi.stubEnv("VERCEL", local ? undefined : "1");
+ vi.stubEnv("VERCEL_ENV", local ? "development" : "production");
+ vi.stubEnv("EVE_DEV", local ? "1" : undefined);
+ vi.stubEnv("NODE_ENV", local ? "development" : "test");
+ vi.stubEnv("VERCEL_DEPLOYMENT_ID", undefined);
+ vi.stubEnv("VERCEL_OIDC_TOKEN", oidcToken);
+ vi.stubEnv("VERCEL_SCHEDULE_DEV_API_VERSION", local ? "1" : undefined);
+ vi.stubEnv("VERCEL_SCHEDULE_BASE_URL", local ? "http://127.0.0.1:4784" : undefined);
+ vi.stubEnv("VERCEL_SCHEDULE_TOKEN", local ? "local-token" : undefined);
+ const fetchImpl = vi.fn<typeof fetch>(async () => Response.json(schedule()));
+ const provider = vercelScheduleProvider({ fetch: fetchImpl });
+
+ const record = await provider.create(context, {
+ expression: {
+ type: "cron",
+ cron: "0 12 * * *",
+ timezone: "America/New_York",
+ jitter: 5,
+ },
payload: "Review PRs",
- },
- target: { type: "queue", topic: expect.stringMatching(/^__eve_schedule_/u) },
- });
- expect(init?.headers).toBeInstanceOf(Headers);
- expect(init?.signal).toBe(context.abortSignal);
- expect(new Headers(init?.headers).get("Authorization")).toBe(`Bearer ${oidcToken}`);
- });
+ name: "review-prs-daily",
+ });
+
+ expect(provider.kind).toBe("vercel");
+ expect(record).toMatchObject({ name: "review-prs-daily", scheduleId: "sch_1" });
+ const [url, init] = fetchImpl.mock.calls[0]!;
+ expect(String(url)).toBe(
+ `${local ? "http://127.0.0.1:4784" : "https://vercel-schedules.com"}/v1/schedules`,
+ );
+ expect(JSON.parse(String(init?.body))).toMatchObject({
+ name: "review-prs-daily",
+ namespace: "eve-namespace",
+ payload: {
+ eve: { application: "dynamic-schedules", collection: "collection", version: 1 },
+ payload: "Review PRs",
+ },
+ target: { type: "queue", topic: expect.stringMatching(/^__eve_schedule_/u) },
+ });
+ expect(init?.headers).toBeInstanceOf(Headers);
+ expect(init?.signal).toBe(context.abortSignal);
+ expect(new Headers(init?.headers).get("Authorization")).toBe(
+ `Bearer ${local ? "local-token" : oidcToken}`,
+ );
+ },
+ );
it("patches only supplied configuration, wraps replacement payloads, and clears omitted timing options", async () => {
vi.stubEnv("VERCEL", "1");
@@ -117,6 +128,9 @@ describe("vercelScheduleProvider", () => {
it("rejects preview deployments before calling the API", async () => {
vi.stubEnv("VERCEL", "1");
vi.stubEnv("VERCEL_ENV", "preview");
+ vi.stubEnv("NODE_ENV", "development");
+ vi.stubEnv("VERCEL_DEPLOYMENT_ID", "dpl_preview");
+ vi.stubEnv("VERCEL_SCHEDULE_DEV_API_VERSION", "1");
const fetchImpl = vi.fn<typeof fetch>();
const provider = vercelScheduleProvider({ fetch: fetchImpl });
@@ -124,8 +138,24 @@ describe("vercelScheduleProvider", () => {
expect(fetchImpl).not.toHaveBeenCalled();
});
- it("uses the shared in-memory provider under eve dev", async () => {
+ it("rejects missing local authentication without falling back", async () => {
+ vi.stubEnv("EVE_DEV", "1");
+ vi.stubEnv("NODE_ENV", "development");
+ vi.stubEnv("VERCEL_DEPLOYMENT_ID", undefined);
+ vi.stubEnv("VERCEL_SCHEDULE_DEV_API_VERSION", "1");
+ vi.stubEnv("VERCEL_SCHEDULE_BASE_URL", "http://127.0.0.1:4784");
+ vi.stubEnv("VERCEL_SCHEDULE_TOKEN", undefined);
+ const fetchImpl = vi.fn<typeof fetch>();
+ const provider = vercelScheduleProvider({ fetch: fetchImpl });
+
+ await expect(provider.list(context, {})).rejects.toThrow("VERCEL_SCHEDULE_TOKEN");
+ expect(fetchImpl).not.toHaveBeenCalled();
+ });
+
+ it("uses the shared in-memory provider under standalone eve dev", async () => {
vi.stubEnv("EVE_DEV", "1");
+ vi.stubEnv("NODE_ENV", "development");
+ vi.stubEnv("VERCEL_SCHEDULE_DEV_API_VERSION", undefined);
const provider = vercelScheduleProvider();
expect(provider.kind).toBe("in-memory");
diff --git a/packages/eve/src/public/schedules/providers/vercel.ts b/packages/eve/src/public/schedules/providers/vercel.ts
index d2bfe2f2f..0610dd6d4 100644
--- a/packages/eve/src/public/schedules/providers/vercel.ts
+++ b/packages/eve/src/public/schedules/providers/vercel.ts
@@ -5,6 +5,7 @@ import type {
} from "#compiled/@vercel/schedules/index.js";
import { isEveDevEnvironment } from "#internal/application/dev-environment.js";
+import { isVercelSchedulesDevEnvironment } from "#internal/schedules/dev-environment.js";
import type {
ScheduleExpression,
SchedulePage,
@@ -35,7 +36,7 @@ export interface VercelScheduleProviderOptions {
export function vercelScheduleProvider(
options: VercelScheduleProviderOptions = {},
): ScheduleProvider {
- if (isEveDevEnvironment()) return DEVELOPMENT_PROVIDER;
+ if (isEveDevEnvironment() && !isVercelSchedulesDevEnvironment()) return DEVELOPMENT_PROVIDER;
const client = (signal: AbortSignal) => createClient(options, signal);
@@ -189,6 +190,7 @@ function isNotFoundError(error: unknown): boolean {
}
function assertSupportedVercelEnvironment(): void {
+ if (isVercelSchedulesDevEnvironment()) return;
if (!process.env.VERCEL?.trim()) {
throw new Error("vercelScheduleProvider() requires a Vercel production deployment or eve dev.");
}
diff --git a/packages/eve/test/scenarios/local-schedules.scenario.test.ts b/packages/eve/test/scenarios/local-schedules.scenario.test.ts
new file mode 100644
index 000000000..fec956b88
--- /dev/null
+++ b/packages/eve/test/scenarios/local-schedules.scenario.test.ts
@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { useScenarioApp } from "#internal/testing/scenario-app.js";
+import { createScheduleCollectionPayload } from "#runtime/schedules/payload.js";
+import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
+import {
+ fetchAgentInfo,
+ startEveDev,
+ waitForCondition,
+ type RunningEveDev,
+} from "./dev-server-harness.js";
+import { DEV_SERVER_SCENARIO_TIMEOUT_MS } from "./dev-server-descriptors.js";
+
+const scenarioApp = useScenarioApp();
+const appDescriptor = {
+ name: "local-schedules",
+ dependencies: { zod: "4.5.4" },
+ installDependencies: true,
+ files: {
+ "agent/instructions.md": "Help Alice review her daily reports.\n",
+ "agent/agent.ts": 'export default { model: "openai/gpt-5.4-mini" };\n',
+ "agent/schedules/heartbeat.ts": 'export default { cron: "* * * * *", run() {} };\n',
+ },
+};
+const localEnv = {
+ NODE_ENV: "development",
+ VERCEL_DEPLOYMENT_ID: undefined,
+ VERCEL_SCHEDULE_DEV_API_VERSION: "1",
+};
+const collectionSource = `import { appendFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { defineDynamicSchedules } from "eve/experimental/schedules";
+export default defineDynamicSchedules({
+ inputSchema: z.object({ task: z.string() }),
+ tool: false,
+ auth: ({ principal }) => ({ attributes: {}, authenticator: principal.authenticator,
+ principalId: principal.principalId, principalType: principal.type }),
+ async run({ payload, auth }) {
+ await appendFile(join(process.env.EVE_DEV_WORKER_APP_ROOT!, "occurrences.jsonl"),
+ JSON.stringify({ task: payload.task, creator: auth.principalId }) + "\\n");
+ },
+});
+`;
+
+describe("local Vercel schedule delivery", () => {
+ it(
+ "boots a static-only agent without local queue configuration",
+ async () => {
+ const app = await scenarioApp(appDescriptor);
+ const server = await startEveDev(app.appRoot, {
+ env: { ...localEnv, VERCEL_QUEUE_BASE_URL: undefined, VERCEL_QUEUE_TOKEN: undefined },
+ });
+ try {
+ expect((await fetchAgentInfo(server.url)).agent.name).toBe(appDescriptor.name);
+ } finally {
+ await server.stop();
+ }
+ },
+ DEV_SERVER_SCENARIO_TIMEOUT_MS,
+ );
+
+ it(
+ "consumes and acknowledges an occurrence after hot-adding the first dynamic collection",
+ async () => {
+ const app = await scenarioApp(appDescriptor);
+ const topic = deriveEveScheduleQueueTopic(appDescriptor.name);
+ const identity = {
+ scheduleId: "sch_local",
+ name: "alice-reminder",
+ namespace: "eve-local-schedules",
+ source: "dynamic",
+ };
+ const message = {
+ ...identity,
+ executionId: "schx_local",
+ scheduledAt: "2026-10-08T12:00:00.000Z",
+ payload: {
+ eve: { application: appDescriptor.name, collection: "requests", version: 1 },
+ payload: createScheduleCollectionPayload({
+ application: appDescriptor.name,
+ collection: "requests",
+ envelope: {
+ version: 3,
+ scope: "alice",
+ principal: { type: "user", authenticator: "fixture", principalId: "alice" },
+ payload: { task: "Review the daily report" },
+ },
+ }),
+ },
+ };
+ let pending = true;
+ let acknowledged = false;
+ const broker = createServer((request, response) => {
+ if (request.headers.authorization !== "Bearer local-token") {
+ response.writeHead(401).end();
+ } else if (request.url?.startsWith("/v1/schedules/alice-reminder?")) {
+ response.setHeader("content-type", "application/json");
+ response.end(JSON.stringify({ ...identity, target: { type: "queue", topic } }));
+ } else if (!request.url?.startsWith(`/api/v3/topic/${topic}/consumer/`)) {
+ response.writeHead(404).end();
+ } else if (request.method === "DELETE") {
+ acknowledged = true;
+ response.writeHead(204).end();
+ } else if (pending) {
+ pending = false;
+ response.setHeader("content-type", "multipart/mixed; boundary=local-message");
+ response.end(
+ [
+ "--local-message",
+ "Content-Type: application/json",
+ "Vqs-Message-Id: local-occurrence",
+ "Vqs-Receipt-Handle: local-receipt",
+ "Vqs-Delivery-Count: 1",
+ "Vqs-Timestamp: 2026-10-08T12:00:00.000Z",
+ "",
+ JSON.stringify(message),
+ "--local-message--",
+ "",
+ ].join("\r\n"),
+ );
+ } else {
+ response.writeHead(204).end();
+ }
+ });
+ await new Promise<void>((resolve) => broker.listen(0, "127.0.0.1", resolve));
+ const address = broker.address();
+ if (!address || typeof address === "string") throw new Error("Missing broker address.");
+ const endpoint = `http://127.0.0.1:${address.port}`;
+ let server: RunningEveDev | undefined;
+ try {
+ server = await startEveDev(app.appRoot, {
+ env: {
+ ...localEnv,
+ VERCEL_SCHEDULE_BASE_URL: endpoint,
+ VERCEL_SCHEDULE_TOKEN: "local-token",
+ VERCEL_QUEUE_BASE_URL: endpoint,
+ VERCEL_QUEUE_TOKEN: "local-token",
+ },
+ });
+ await writeFile(join(app.appRoot, "agent/schedules/requests.ts"), collectionSource);
+ const occurrencesPath = join(app.appRoot, "occurrences.jsonl");
+ await waitForCondition(
+ () => existsSync(occurrencesPath) && acknowledged,
+ () => `Local occurrence was not dispatched and acknowledged.\n${server?.stderr()}`,
+ );
+ expect(JSON.parse((await readFile(occurrencesPath, "utf8")).trim())).toEqual({
+ task: "Review the daily report",
+ creator: "alice",
+ });
+ } finally {
+ await server?.stop();
+ broker.closeAllConnections();
+ await new Promise<void>((resolve, reject) =>
+ broker.close((error) => (error ? reject(error) : resolve())),
+ );
+ }
+ },
+ DEV_SERVER_SCENARIO_TIMEOUT_MS,
+ );
+});