Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add the Vercel subscription schedule provider (#4011)

Colton Padden8751775fbbd7
diff --git a/.changeset/tidy-schedules-runtime.md b/.changeset/tidy-schedules-runtime.md
new file mode 100644
index 000000000..4ca0c28dd
--- /dev/null
+++ b/.changeset/tidy-schedules-runtime.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+The experimental Vercel schedule provider includes Schedules SDK alpha.11 in the published package without adding a runtime dependency. Provider requests receive the operation's abort signal, and failed disable calls after inactive creation report that the schedule may remain active.
diff --git a/.changeset/vercel-schedule-provider.md b/.changeset/vercel-schedule-provider.md
new file mode 100644
index 000000000..8c012a94e
--- /dev/null
+++ b/.changeset/vercel-schedule-provider.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Schedule subscriptions default to Vercel Schedules in production and process-local storage under `eve dev`, so an explicit `provider` is no longer required. Pass a provider to override the backend, or use `vercelScheduleProvider` from `eve/experimental/schedules/vercel` to customize the Vercel endpoint.
diff --git a/packages/eve/package.json b/packages/eve/package.json
index d6835807b..6d0ac8eed 100644
--- a/packages/eve/package.json
+++ b/packages/eve/package.json
@@ -436,6 +436,12 @@
"import": "./dist/src/public/experimental/schedules/index.js",
"default": "./dist/src/public/experimental/schedules/index.js"
},
+ "./experimental/schedules/vercel": {
+ "eve-source": "./src/public/experimental/schedules/vercel.ts",
+ "types": "./dist/src/public/experimental/schedules/vercel.d.ts",
+ "import": "./dist/src/public/experimental/schedules/vercel.js",
+ "default": "./dist/src/public/experimental/schedules/vercel.js"
+ },
"./channels": {
"types": "./dist/src/public/channels/index.d.ts",
"import": "./dist/src/public/channels/index.js",
@@ -591,7 +597,9 @@
"@vercel/detect-agent": "1.2.3",
"@vercel/oidc": "3.8.0",
"@vercel/otel": "catalog:",
+ "@vercel/queue": "0.5.1",
"@vercel/sandbox": "catalog:",
+ "@vercel/schedules": "0.0.0-alpha.11",
"@vercel/sdk": "1.28.8",
"@workflow/core": "5.1.0",
"@workflow/errors": "5.0.2",
diff --git a/packages/eve/scripts/vendor-compiled/@vercel/schedules.mjs b/packages/eve/scripts/vendor-compiled/@vercel/schedules.mjs
new file mode 100644
index 000000000..a086c663c
--- /dev/null
+++ b/packages/eve/scripts/vendor-compiled/@vercel/schedules.mjs
@@ -0,0 +1,14 @@
+import { createDeclarationCopier } from "../_shared.mjs";
+
+export default {
+ packageName: "@vercel/schedules",
+ compiledPath: "@vercel/schedules",
+ bundling: "standalone",
+ 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 d0a22a7b4..4ca94ec13 100644
--- a/packages/eve/scripts/vendor-compiled/index.mjs
+++ b/packages/eve/scripts/vendor-compiled/index.mjs
@@ -32,6 +32,7 @@ import vercelOidc from "./@vercel/oidc.mjs";
import vercelOtel from "./@vercel/otel.mjs";
import vercelSandbox from "./@vercel/sandbox.mjs";
import vercelSdk from "./@vercel/sdk.mjs";
+import vercelSchedules from "./@vercel/schedules.mjs";
import workflowCore from "./@workflow/core.mjs";
import workflowErrors from "./@workflow/errors.mjs";
import workflowSerde from "./@workflow/serde.mjs";
@@ -102,6 +103,7 @@ export const MODULES = [
vercelOtel,
vercelSandbox,
vercelSdk,
+ vercelSchedules,
workflowCore,
workflowErrors,
workflowSerde,
diff --git a/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts b/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts
index 831c46f83..18f9faa34 100644
--- a/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts
+++ b/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts
@@ -29,6 +29,10 @@ import {
} from "#internal/nitro/host/application-route-registry.js";
import { registerChannelVirtualHandlers } from "#internal/nitro/host/channel-routes.js";
import type { PreparedApplicationHost } from "#internal/nitro/host/types.js";
+import {
+ EVE_SCHEDULE_COLLECTION_CONSUMER_ROUTE_PATH,
+ hasVercelScheduleCollections,
+} from "#internal/schedules/consumer-route.js";
function resolveNitroWorkflowBuildDirectory(nitro: Nitro): string {
return join(nitro.options.buildDir, "workflow");
@@ -415,11 +419,22 @@ export async function configureProductionNitroRoutes(
await registerWorkflowArtifactBuildHook(nitro, syncWorkflowArtifacts);
const routeRegistry = createApplicationRouteRegistry(preparedHost);
- registerApplicationRoutes(
- nitro,
- createProductionNitroArtifactsConfig(preparedHost.appRoot),
- routeRegistry,
- );
+ const artifactsConfig = createProductionNitroArtifactsConfig(preparedHost.appRoot);
+ registerApplicationRoutes(nitro, artifactsConfig, routeRegistry);
+ if (
+ isVercelBuildEnvironment() &&
+ hasVercelScheduleCollections(preparedHost.compileResult.manifest)
+ ) {
+ addHostVirtualHandler(nitro, {
+ args: JSON.stringify(artifactsConfig),
+ handlerExport: "handleScheduleCollectionConsumer",
+ method: "POST",
+ modulePath: resolvePackageSourceFilePath(
+ "src/internal/nitro/routes/schedule-collection-consumer.ts",
+ ),
+ route: EVE_SCHEDULE_COLLECTION_CONSUMER_ROUTE_PATH,
+ });
+ }
const workflowBundlePath = join(preparedHost.workflowBuildDir, "workflows.mjs");
const hasConfiguredWorkflowWorld =
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 df6532239..4bfe20812 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
@@ -5,6 +5,7 @@ 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 { configureInstrumentationEntry } from "#internal/nitro/host/instrumentation-entry.js";
import { EVE_PACKAGE_NAME } from "#internal/package-name.js";
import {
@@ -839,6 +840,9 @@ export async function createProductionApplicationNitro(
vercel: createEveVercelOptions({
agentName: preparedHost.compileResult.manifest.config.name,
enabled: preset === "vercel",
+ hasVercelScheduleCollections: hasVercelScheduleCollections(
+ preparedHost.compileResult.manifest,
+ ),
publicRoutePrefix: options.publicRoutePrefix,
workspaceMember: options.workspaceMember,
}),
diff --git a/packages/eve/src/internal/nitro/host/vercel-build-output-config.test.ts b/packages/eve/src/internal/nitro/host/vercel-build-output-config.test.ts
index 769a1fb34..d78ea57a1 100644
--- a/packages/eve/src/internal/nitro/host/vercel-build-output-config.test.ts
+++ b/packages/eve/src/internal/nitro/host/vercel-build-output-config.test.ts
@@ -52,7 +52,7 @@ describe("createEveVercelOptions", () => {
enabled: true,
publicRoutePrefix,
});
- expect(options?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH].environment).not.toHaveProperty(
+ expect(options?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH]!.environment).not.toHaveProperty(
"EVE_PUBLIC_ROUTE_PREFIX",
);
}
@@ -65,7 +65,7 @@ describe("createEveVercelOptions", () => {
publicRoutePrefix: "eve/support/",
});
- expect(options?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH].environment).toEqual({
+ expect(options?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH]!.environment).toEqual({
WORKFLOW_PRECONDITION_GUARD: "1",
EVE_PUBLIC_ROUTE_PREFIX: "/eve/support",
});
@@ -84,11 +84,13 @@ describe("createEveVercelOptions", () => {
workspaceMember: true,
});
- expect(standalone?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH].environment).not.toHaveProperty(
+ expect(standalone?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH]!.environment).not.toHaveProperty(
"EVE_INTERNAL_AGENT_WORKSPACE_MEMBER",
);
- expect(workspaceMember?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH].environment).toMatchObject({
- EVE_INTERNAL_AGENT_WORKSPACE_MEMBER: "1",
- });
+ expect(workspaceMember?.functionRules[EVE_WORKFLOW_FLOW_ROUTE_PATH]!.environment).toMatchObject(
+ {
+ EVE_INTERNAL_AGENT_WORKSPACE_MEMBER: "1",
+ },
+ );
});
});
diff --git a/packages/eve/src/internal/nitro/host/vercel-build-output-config.ts b/packages/eve/src/internal/nitro/host/vercel-build-output-config.ts
index 9879c7072..6255f1673 100644
--- a/packages/eve/src/internal/nitro/host/vercel-build-output-config.ts
+++ b/packages/eve/src/internal/nitro/host/vercel-build-output-config.ts
@@ -2,6 +2,10 @@ import { EVE_INTERNAL_AGENT_WORKSPACE_MEMBER_ENV } from "#internal/application/b
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
import { EVE_PACKAGE_NAME } from "#internal/package-name.js";
import { createEveWorkflowQueueTrigger } from "#internal/workflow/queue-namespace.js";
+import {
+ createEveScheduleQueueTrigger,
+ EVE_SCHEDULE_COLLECTION_CONSUMER_ROUTE_PATH,
+} from "#internal/schedules/consumer-route.js";
import { EVE_WORKFLOW_FLOW_ROUTE_PATH } from "#internal/workflow-bundle/eve-service-route-output.js";
import {
EVE_PUBLIC_ROUTE_PREFIX_ENV,
@@ -22,6 +26,7 @@ export { EVE_WORKFLOW_FLOW_ROUTE_PATH };
export function createEveVercelOptions(input: {
agentName: string;
enabled: boolean;
+ hasVercelScheduleCollections?: boolean;
publicRoutePrefix?: string;
workspaceMember?: boolean;
}) {
@@ -60,6 +65,14 @@ export function createEveVercelOptions(input: {
experimentalTriggers: [createEveWorkflowQueueTrigger(input.agentName)],
environment,
},
+ // The consumer only exists when a collection stores its schedules in Vercel Schedules.
+ ...(input.hasVercelScheduleCollections === true && {
+ [EVE_SCHEDULE_COLLECTION_CONSUMER_ROUTE_PATH]: {
+ maxDuration: "max" as const,
+ experimentalTriggers: [createEveScheduleQueueTrigger(input.agentName)],
+ environment,
+ },
+ }),
},
};
}
diff --git a/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts b/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts
new file mode 100644
index 000000000..fbf202c6d
--- /dev/null
+++ b/packages/eve/src/internal/nitro/routes/schedule-collection-consumer.ts
@@ -0,0 +1,137 @@
+import { handleCallback } from "@vercel/queue";
+import { SchedulesApiError, SchedulesClient } from "#compiled/@vercel/schedules/index.js";
+
+import type { NitroArtifactsConfig } from "#internal/nitro/routes/runtime-artifacts.js";
+import { resolveNitroCompiledArtifactsSource } from "#internal/nitro/routes/runtime-artifacts.js";
+import { EVE_SCHEDULE_CONSUMER_MAX_DELIVERIES } from "#internal/schedules/consumer-route.js";
+import {
+ expectScheduleQueueMessage,
+ PermanentScheduleMessageError,
+ verifyScheduleDelivery,
+ type VerifiedScheduleMessage,
+} from "#internal/schedules/verify-delivery.js";
+import type {
+ DynamicSchedulesDefinition,
+ ScheduleOccurrenceIdentity,
+} from "#public/schedules/subscription.js";
+import { readVercelScheduleClientOptions } from "#public/schedules/providers/vercel.js";
+import { loadCompiledManifest } from "#runtime/loaders/manifest.js";
+import { dispatchScheduledOccurrence } from "#runtime/schedules/dispatch-occurrence.js";
+import {
+ loadScheduleCollectionDefinition,
+ ScheduleCollectionNotDeployedError,
+} from "#runtime/schedules/load-collection.js";
+import { parseSchedulePayload } from "#runtime/schedules/payload.js";
+import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
+import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
+
+/** Receives verified Vercel Schedules occurrences and dispatches at-least-once callbacks. */
+export async function handleScheduleCollectionConsumer(
+ config: NitroArtifactsConfig,
+ request: Request,
+): Promise<Response> {
+ const handler = handleCallback<unknown>(
+ async (message, metadata) => {
+ const queue = expectScheduleQueueMessage(message);
+ const application = queue.payload.eve.application;
+ const collection = queue.payload.eve.collection;
+ const source = resolveNitroCompiledArtifactsSource(config);
+ const [bundle, manifest] = await Promise.all([
+ getCompiledRuntimeAgentBundle({ compiledArtifactsSource: source }),
+ loadCompiledManifest({ compiledArtifactsSource: source }),
+ ]);
+ if (manifest.config.name !== application)
+ throw new PermanentScheduleMessageError("Schedule application does not match this agent.");
+ if (
+ !queue.namespace.startsWith("eve-") ||
+ metadata.topicName !== deriveEveScheduleQueueTopic(application)
+ )
+ throw new PermanentScheduleMessageError("Schedule delivery does not match this agent.");
+ let definition: DynamicSchedulesDefinition<unknown>;
+ try {
+ definition = await loadScheduleCollectionDefinition(bundle, collection, {
+ manifest,
+ providerKind: "vercel",
+ });
+ } catch (error) {
+ if (error instanceof ScheduleCollectionNotDeployedError)
+ throw new PermanentScheduleMessageError(error.message);
+ throw error;
+ }
+ const occurrence: ScheduleOccurrenceIdentity = {
+ collection,
+ executionId: queue.executionId ?? metadata.messageId,
+ name: queue.name,
+ scheduleId: queue.scheduleId,
+ scheduledAt: queue.scheduledAt ?? queue.firedAt ?? metadata.createdAt.toISOString(),
+ };
+ try {
+ let payload;
+ try {
+ payload = parseSchedulePayload<unknown>(queue.payload.payload, {
+ application,
+ collection,
+ });
+ } catch {
+ throw new PermanentScheduleMessageError("Scheduled collection request is invalid.");
+ }
+ await dispatchScheduledOccurrence({
+ bundle,
+ collection,
+ definition,
+ occurrence,
+ payload,
+ verifyDelivery: async () =>
+ verifyScheduleDelivery(
+ queue,
+ await getSchedule(definition, queue),
+ application,
+ metadata.topicName,
+ ),
+ });
+ } catch (error) {
+ // Report failure only when the provider stops retrying this callback.
+ const final =
+ error instanceof PermanentScheduleMessageError ||
+ metadata.deliveryCount >= EVE_SCHEDULE_CONSUMER_MAX_DELIVERIES;
+ if (final) {
+ await definition.events?.["occurrence.failed"]?.({
+ collection,
+ executionId: occurrence.executionId,
+ name: occurrence.name,
+ occurrence,
+ reason: error instanceof Error ? error.message : "Scheduled occurrence failed.",
+ scheduledAt: occurrence.scheduledAt,
+ scheduleId: occurrence.scheduleId,
+ type: "occurrence.failed",
+ });
+ }
+ throw error;
+ }
+ },
+ {
+ 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. */
+async function getSchedule(
+ definition: DynamicSchedulesDefinition<unknown>,
+ queue: VerifiedScheduleMessage,
+) {
+ try {
+ return await new SchedulesClient(
+ readVercelScheduleClientOptions(definition.provider) ?? {},
+ ).get({ name: queue.name, namespace: queue.namespace });
+ } catch (error) {
+ if (error instanceof SchedulesApiError && error.status === 404)
+ throw new PermanentScheduleMessageError("Schedule delivery does not match this agent.");
+ throw error;
+ }
+}
diff --git a/packages/eve/src/internal/schedules/consumer-route.ts b/packages/eve/src/internal/schedules/consumer-route.ts
new file mode 100644
index 000000000..b8283e78d
--- /dev/null
+++ b/packages/eve/src/internal/schedules/consumer-route.ts
@@ -0,0 +1,27 @@
+import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
+
+export const EVE_SCHEDULE_COLLECTION_CONSUMER_ROUTE_PATH = "/.well-known/eve/v1/schedules/consumer";
+
+/** Deliveries the queue attempts before giving up on an occurrence. */
+export const EVE_SCHEDULE_CONSUMER_MAX_DELIVERIES = 10;
+
+/** The queue trigger that delivers an agent's scheduled occurrences to its consumer. */
+export function createEveScheduleQueueTrigger(agentName: string) {
+ return {
+ type: "queue/v2beta" as const,
+ topic: deriveEveScheduleQueueTopic(agentName),
+ retryAfterSeconds: 5,
+ initialDelaySeconds: 0,
+ maxDeliveries: EVE_SCHEDULE_CONSUMER_MAX_DELIVERIES,
+ };
+}
+
+/** Whether a build needs the Vercel schedule consumer: its route and its queue trigger. */
+export function hasVercelScheduleCollections(manifest: {
+ readonly scheduleCollections?: readonly { readonly providerKind: string }[];
+}): boolean {
+ return (
+ manifest.scheduleCollections?.some((collection) => collection.providerKind === "vercel") ??
+ false
+ );
+}
diff --git a/packages/eve/src/internal/schedules/verify-delivery.ts b/packages/eve/src/internal/schedules/verify-delivery.ts
new file mode 100644
index 000000000..ceda3a90a
--- /dev/null
+++ b/packages/eve/src/internal/schedules/verify-delivery.ts
@@ -0,0 +1,66 @@
+import type { Schedule as VercelSchedule } from "#compiled/@vercel/schedules/index.js";
+import { z } from "#compiled/zod/index.js";
+
+import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
+
+const referenceSchema = z.string().min(1);
+const queueMessageSchema = z.looseObject({
+ executionId: referenceSchema.optional(),
+ firedAt: z.string().optional(),
+ name: referenceSchema,
+ namespace: referenceSchema,
+ payload: z.looseObject({
+ eve: z.looseObject({
+ application: referenceSchema,
+ collection: referenceSchema,
+ version: z.literal(1),
+ }),
+ // The common occurrence dispatcher owns validation of the inner eve envelope.
+ payload: z.unknown(),
+ }),
+ scheduleId: referenceSchema,
+ scheduledAt: z.string().optional(),
+ source: z.literal("dynamic"),
+});
+
+export type VerifiedScheduleMessage = z.infer<typeof queueMessageSchema>;
+
+export class PermanentScheduleMessageError extends Error {}
+
+export function expectScheduleQueueMessage(value: unknown): VerifiedScheduleMessage {
+ let json: string | undefined;
+ try {
+ json = JSON.stringify(value);
+ } catch {
+ throw new PermanentScheduleMessageError("Invalid eve schedule queue message.");
+ }
+ if (json === undefined)
+ throw new PermanentScheduleMessageError("Invalid eve schedule queue message.");
+ if (Buffer.byteLength(json) > 256 * 1024)
+ throw new PermanentScheduleMessageError("Schedule queue message exceeds the payload limit.");
+ const parsed = queueMessageSchema.safeParse(JSON.parse(json));
+ if (!parsed.success)
+ throw new PermanentScheduleMessageError("Invalid eve schedule queue message.");
+ return parsed.data;
+}
+
+export function verifyScheduleDelivery(
+ message: VerifiedScheduleMessage,
+ schedule: VercelSchedule | null,
+ application: string,
+ topic: string,
+): void {
+ if (
+ message.payload.eve.application !== application ||
+ topic !== deriveEveScheduleQueueTopic(application) ||
+ schedule === null ||
+ schedule.scheduleId !== message.scheduleId ||
+ schedule.name !== message.name ||
+ schedule.namespace !== message.namespace ||
+ schedule.source !== "dynamic" ||
+ schedule.target.type !== "queue" ||
+ schedule.target.topic !== topic
+ ) {
+ throw new PermanentScheduleMessageError("Schedule delivery does not match this agent.");
+ }
+}
diff --git a/packages/eve/src/public/experimental/schedules/vercel.ts b/packages/eve/src/public/experimental/schedules/vercel.ts
new file mode 100644
index 000000000..df05d9ae4
--- /dev/null
+++ b/packages/eve/src/public/experimental/schedules/vercel.ts
@@ -0,0 +1,5 @@
+/** Experimental Vercel-backed dynamic schedule collections. */
+export {
+ vercelScheduleProvider,
+ type VercelScheduleProviderOptions,
+} from "#public/schedules/providers/vercel.js";
diff --git a/packages/eve/src/public/schedules/providers/vercel.test.ts b/packages/eve/src/public/schedules/providers/vercel.test.ts
new file mode 100644
index 000000000..5c6136944
--- /dev/null
+++ b/packages/eve/src/public/schedules/providers/vercel.test.ts
@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { vercelScheduleProvider } from "#public/schedules/providers/vercel.js";
+import type { ScheduleProviderContext } from "#runtime/schedules/provider-types.js";
+
+const oidcToken = `eyJhbGciOiJSUzI1NiJ9.${Buffer.from(
+ JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600 }),
+).toString("base64url")}.signature`;
+
+const context: ScheduleProviderContext = {
+ abortSignal: new AbortController().signal,
+ collection: "collection",
+ namespace: "eve-namespace",
+ operationId: "operation_1",
+ target: { key: "dynamic-schedules" },
+};
+
+function schedule(overrides: Record<string, unknown> = {}) {
+ return {
+ createdAt: 1,
+ expression: { type: "cron", cron: "0 12 * * *" },
+ name: "review-prs-daily",
+ scheduleId: "sch_1",
+ state: "active",
+ timezone: "America/New_York",
+ updatedAt: 2,
+ ...overrides,
+ };
+}
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+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 },
+ 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}`);
+ });
+
+ it("reports when creating an inactive schedule leaves it active after disable fails", async () => {
+ vi.stubEnv("VERCEL", "1");
+ vi.stubEnv("VERCEL_ENV", "production");
+ vi.stubEnv("VERCEL_OIDC_TOKEN", oidcToken);
+ const fetchImpl = vi
+ .fn<typeof fetch>()
+ .mockResolvedValueOnce(Response.json(schedule()))
+ .mockResolvedValueOnce(new Response("disable failed", { status: 500 }));
+ const provider = vercelScheduleProvider({ fetch: fetchImpl });
+
+ await expect(
+ provider.create(context, {
+ expression: { type: "cron", cron: "0 12 * * *", timezone: "UTC" },
+ payload: "Review PRs",
+ name: "review-prs-daily",
+ state: "inactive",
+ }),
+ ).rejects.toThrow("was created active, but disabling it failed; it may remain active");
+ expect(fetchImpl).toHaveBeenCalledTimes(2);
+ });
+
+ it("omits a blank first-page cursor", 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({ data: [], cursor: null }));
+ const provider = vercelScheduleProvider({ fetch: fetchImpl });
+
+ await provider.list(context, { cursor: "", limit: 20 });
+
+ expect(String(fetchImpl.mock.calls[0]![0])).toBe(
+ "https://vercel-schedules.com/v1/schedules?namespace=eve-namespace&limit=20",
+ );
+ });
+
+ it("rejects preview deployments before calling the API", async () => {
+ vi.stubEnv("VERCEL", "1");
+ vi.stubEnv("VERCEL_ENV", "preview");
+ const fetchImpl = vi.fn<typeof fetch>();
+ const provider = vercelScheduleProvider({ fetch: fetchImpl });
+
+ await expect(provider.list(context, {})).rejects.toThrow("production deployments only");
+ expect(fetchImpl).not.toHaveBeenCalled();
+ });
+
+ it("uses the shared in-memory provider under eve dev", async () => {
+ vi.stubEnv("EVE_DEV", "1");
+ const provider = vercelScheduleProvider();
+ expect(provider.kind).toBe("in-memory");
+
+ await provider.create(context, {
+ expression: { type: "single", at: "2026-10-01T12:00:00", timezone: "UTC" },
+ payload: "Review PRs",
+ name: "review-prs",
+ });
+ await expect(
+ provider.get({ ...context, operationId: "get" }, "review-prs"),
+ ).resolves.toMatchObject({ name: "review-prs" });
+ });
+});
diff --git a/packages/eve/src/public/schedules/providers/vercel.ts b/packages/eve/src/public/schedules/providers/vercel.ts
new file mode 100644
index 000000000..0da5e5ead
--- /dev/null
+++ b/packages/eve/src/public/schedules/providers/vercel.ts
@@ -0,0 +1,196 @@
+import type {
+ Schedule as VercelSchedule,
+ SchedulesClient,
+} from "#compiled/@vercel/schedules/index.js";
+
+import { isEveDevEnvironment } from "#internal/application/dev-environment.js";
+import type {
+ ScheduleExpression,
+ SchedulePage,
+ ScheduleProvider,
+ ScheduleRecord,
+} from "#public/schedules/subscription.js";
+import type { ScheduleProviderContext } from "#runtime/schedules/provider-types.js";
+import { inMemoryScheduleProvider } from "#public/schedules/providers/in-memory.js";
+import { deriveEveScheduleQueueTopic } from "#runtime/schedules/queue-namespace.js";
+
+const DEVELOPMENT_PROVIDER = inMemoryScheduleProvider();
+const CLIENT_OPTIONS = new WeakMap<ScheduleProvider, VercelScheduleProviderOptions>();
+
+/** Client options of a Vercel provider, so delivery verification talks to the same endpoint. */
+export function readVercelScheduleClientOptions(
+ provider: ScheduleProvider,
+): VercelScheduleProviderOptions | undefined {
+ return CLIENT_OPTIONS.get(provider);
+}
+
+export interface VercelScheduleProviderOptions {
+ /** Overrides the public Vercel Schedules endpoint. */
+ readonly baseUrl?: string;
+ readonly fetch?: typeof fetch;
+}
+
+/** Uses ambient OIDC on Vercel and process-local storage under `eve dev`. */
+export function vercelScheduleProvider(
+ options: VercelScheduleProviderOptions = {},
+): ScheduleProvider {
+ if (isEveDevEnvironment()) return DEVELOPMENT_PROVIDER;
+
+ const client = (signal: AbortSignal) => createClient(options, signal);
+
+ const provider: ScheduleProvider = {
+ kind: "vercel",
+ async create(context, input) {
+ const schedules = await client(context.abortSignal);
+ let schedule: VercelSchedule = await schedules.create({
+ expression: toVercelExpression(input.expression),
+ jitter: input.expression.type === "cron" ? input.expression.jitter : undefined,
+ name: input.name,
+ namespace: context.namespace,
+ payload: createDispatchPayload(context, input.payload),
+ target: { topic: deriveEveScheduleQueueTopic(context.target.key) },
+ timezone: input.expression.timezone,
+ });
+ if (input.state === "inactive") {
+ try {
+ schedule = await schedules.disable({ name: input.name, namespace: context.namespace });
+ } catch (error) {
+ throw new Error(
+ `Schedule ${JSON.stringify(input.name)} was created active, but disabling it failed; it may remain active.`,
+ { cause: error },
+ );
+ }
+ }
+ return fromVercelSchedule(schedule);
+ },
+ async list(context, input): Promise<SchedulePage> {
+ const cursor = input.cursor?.trim() || undefined;
+ const params: { namespace: string; cursor?: string; limit?: number } = {
+ namespace: context.namespace,
+ };
+ if (cursor !== undefined) params.cursor = cursor;
+ if (input.limit !== undefined) params.limit = input.limit;
+ const page = await (await client(context.abortSignal)).list(params);
+ return { cursor: page.cursor, data: page.data.map(fromVercelSchedule) };
+ },
+ async get(context, name) {
+ const response = await getScheduleOrNull(
+ await client(context.abortSignal),
+ name,
+ context.namespace,
+ );
+ return response === null ? null : fromVercelSchedule(response);
+ },
+ async enable(context, name) {
+ return fromVercelSchedule(
+ await (await client(context.abortSignal)).enable({ name, namespace: context.namespace }),
+ );
+ },
+ async disable(context, name) {
+ return fromVercelSchedule(
+ await (await client(context.abortSignal)).disable({ name, namespace: context.namespace }),
+ );
+ },
+ async invoke(context, name) {
+ await (await client(context.abortSignal)).invoke({ name, namespace: context.namespace });
+ },
+ async delete(context, name) {
+ try {
+ await (await client(context.abortSignal)).delete({ name, namespace: context.namespace });
+ return true;
+ } catch (error) {
+ if (isNotFoundError(error)) return false;
+ throw error;
+ }
+ },
+ };
+ CLIENT_OPTIONS.set(provider, options);
+ return provider;
+}
+
+async function createClient(
+ options: VercelScheduleProviderOptions,
+ signal: AbortSignal,
+): Promise<SchedulesClient> {
+ assertSupportedVercelEnvironment();
+ const { SchedulesClient } = await import("#compiled/@vercel/schedules/index.js");
+ signal.throwIfAborted();
+ const fetchImpl = options.fetch ?? fetch;
+ return new SchedulesClient({
+ ...options,
+ fetch: (input, init) => fetchImpl(input, { ...init, signal }),
+ });
+}
+
+function createDispatchPayload(context: ScheduleProviderContext, payload: unknown) {
+ return {
+ eve: {
+ application: context.target.key,
+ collection: context.collection,
+ version: 1,
+ },
+ payload,
+ };
+}
+
+function toVercelExpression(expression: ScheduleExpression) {
+ return expression.type === "cron"
+ ? { type: "cron" as const, cron: expression.cron }
+ : { type: "single" as const, at: expression.at };
+}
+
+function fromVercelSchedule(schedule: VercelSchedule): ScheduleRecord {
+ let expression: ScheduleExpression;
+ if (schedule.expression.type === "cron") {
+ const cron: { type: "cron"; cron: string; timezone: string; jitter?: number } = {
+ type: "cron",
+ cron: schedule.expression.cron,
+ timezone: schedule.timezone,
+ };
+ if (schedule.jitter !== undefined) cron.jitter = schedule.jitter;
+ expression = cron;
+ } else {
+ expression = { type: "single", at: schedule.expression.at, timezone: schedule.timezone };
+ }
+ return {
+ createdAt: schedule.createdAt,
+ expression,
+ name: schedule.name,
+ scheduleId: schedule.scheduleId,
+ state: schedule.state,
+ updatedAt: schedule.updatedAt,
+ };
+}
+
+async function getScheduleOrNull(
+ client: SchedulesClient,
+ name: string,
+ namespace: string,
+): Promise<VercelSchedule | null> {
+ try {
+ return await client.get({ name, namespace });
+ } catch (error) {
+ if (isNotFoundError(error)) return null;
+ throw error;
+ }
+}
+
+function isNotFoundError(error: unknown): boolean {
+ return (
+ typeof error === "object" &&
+ error !== null &&
+ Reflect.get(error, "name") === "SchedulesApiError" &&
+ Reflect.get(error, "status") === 404
+ );
+}
+
+function assertSupportedVercelEnvironment(): void {
+ if (!process.env.VERCEL?.trim()) {
+ throw new Error("vercelScheduleProvider() requires a Vercel production deployment or eve dev.");
+ }
+ if (process.env.VERCEL_ENV !== "production") {
+ throw new Error(
+ "Vercel Schedules currently supports production deployments only. Deploy with `vercel --prod`.",
+ );
+ }
+}
diff --git a/packages/eve/src/public/schedules/subscription.ts b/packages/eve/src/public/schedules/subscription.ts
index f6ab22766..64292be61 100644
--- a/packages/eve/src/public/schedules/subscription.ts
+++ b/packages/eve/src/public/schedules/subscription.ts
@@ -17,6 +17,7 @@ import type { InferReceiveTarget } from "#channel/receive-target.js";
import type { Session } from "#channel/session.js";
import { SCHEDULE_COLLECTION_DEFINITION_BRAND } from "#shared/schedule-collection-definition.js";
import type { ScheduleProviderContext } from "#runtime/schedules/provider-types.js";
+import { vercelScheduleProvider } from "#public/schedules/providers/vercel.js";
/** A provider namespace scope, represented by one key or a hierarchical key path. */
export type ScheduleScopeValue = string | readonly string[];
@@ -217,7 +218,7 @@ export interface DynamicSchedulesDefinition<
readonly description?: string;
/** Model-facing payload schema. Destination intent may be resolved by `run`. */
readonly inputSchema: TSchema;
- /** Backend used to store schedules and deliver occurrences. */
+ /** Resolved backend. defineDynamicSchedules defaults omitted providers to Vercel Schedules. */
readonly provider: ScheduleProvider;
/**
* Validates application policy and enriches a creation payload before the provider write.
@@ -285,8 +286,8 @@ type DynamicSchedulesOptions<
DynamicSchedulesDefinition<TInput, TSchema, TPrepared>,
"provider" | "tool" | "approval"
> & {
- /** Backend used by this definition. */
- readonly provider: ScheduleProvider;
+ /** Defaults to vercelScheduleProvider(): hosted production scheduling, process-local storage in eve dev. */
+ readonly provider?: ScheduleProvider;
} & (
| { readonly tool: false; readonly approval?: never }
| { readonly tool?: true; readonly approval?: ScheduleApprovals<NoInfer<TPrepared>> }
@@ -297,6 +298,8 @@ type DynamicSchedulesOptions<
* identity comes from the module path. inputSchema validates caller input,
* while eve captures creator identity separately and re-resolves it on every attempt.
* `run` chooses destinations and starts work; no creation conversation is implicitly captured.
+ * Provider defaults to vercelScheduleProvider(); pass provider explicitly to select another backend.
+ * The default supports Vercel production and eve dev, not preview or self-hosted scheduling.
*/
export function defineDynamicSchedules<TInput, TPrepared>(
definition: Omit<
@@ -317,11 +320,11 @@ export function defineDynamicSchedules<TSchema extends StandardSchemaV1<unknown,
): DefinedDynamicSchedules<StandardSchemaV1.InferOutput<TSchema>, TSchema>;
export function defineDynamicSchedules(
definition: Omit<DynamicSchedulesDefinition<any, any, any>, "provider"> & {
- readonly provider: ScheduleProvider;
+ readonly provider?: ScheduleProvider;
},
): DefinedDynamicSchedules<any, any, any> {
Object.assign(definition, {
- provider: definition.provider,
+ provider: definition.provider ?? vercelScheduleProvider(),
tool: definition.tool ?? true,
[SCHEDULE_COLLECTION_DEFINITION_BRAND]: true,
});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7224acb9a..3e45a017b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1742,9 +1742,15 @@ importers:
'@vercel/otel':
specifier: 'catalog:'
version: 2.1.3(@opentelemetry/[email protected])(@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected])([email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))
+ '@vercel/queue':
+ specifier: 0.5.1
+ version: 0.5.1(@opentelemetry/[email protected])
'@vercel/sandbox':
specifier: 'catalog:'
version: 3.3.0
+ '@vercel/schedules':
+ specifier: 0.0.0-alpha.11
+ version: 0.0.0-alpha.11
'@vercel/sdk':
specifier: 1.28.8
version: 1.28.8
@@ -7634,6 +7640,10 @@ packages:
'@vercel/[email protected]':
resolution: {integrity: sha512-TclqRD2joExyECTrrHsioi3Onw20X2YfpOYEzs3JpJUtAjOKYw2bMeXldKrUg+TB/TT7tPdDu8uKNxj9NE7QUg==}
+ '@vercel/[email protected]':
+ resolution: {integrity: sha512-wu2YwHwO+GMW/0ou8l+5749zvV1eNdJNQrD+juTcsaIqcuksAnaXDSlmG/qAJZhLcIy+cSgURhdGqpLpSXrV5g==}
+ engines: {node: '>=20.0.0'}
+
'@vercel/[email protected]':
resolution: {integrity: sha512-uAl+pEZZnFYRFzE/43ihP3aYTJ+4v0+coiMYobYMqtaERWknYKuRZWEj9Dk9r87yWXfxclsQugXkN42kaOcySw==}
@@ -21355,6 +21365,10 @@ snapshots:
- bare-abort-controller
- react-native-b4a
+ '@vercel/[email protected]':
+ dependencies:
+ '@vercel/oidc': 3.8.0
+
'@vercel/[email protected]':
dependencies:
zod: 4.5.4