The Open Framework for Building Agents
fix(eve): service crons - publish embedded agent schedules (#1188)
Andrew Barba1c0347f52297
diff --git a/.changeset/friendly-bees-schedule.md b/.changeset/friendly-bees-schedule.mdnew file mode 100644index 000000000..b575c656a--- /dev/null+++ b/.changeset/friendly-bees-schedule.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Expose schedules from generated `withEve` services to Vercel's project-level Cron Jobs. Single and named agents now register routable jobs without requiring duplicate `vercel.json` entries.diff --git a/docs/guides/frontend/nextjs.mdx b/docs/guides/frontend/nextjs.mdxindex 128b98399..bf9fe5fb0 100644--- a/docs/guides/frontend/nextjs.mdx+++ b/docs/guides/frontend/nextjs.mdx@@ -102,7 +102,7 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti## Dev vs deploy topology- **Local dev.** `npm run dev` boots the eve dev server next to `next dev` and rewrites the eve routes over to it. The browser only ever talks to the Next.js origin.-- **Vercel.** The web app and the eve runtime deploy as a single project. `withEve()` writes Build Output `services` for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Next.js app itself remains the default app. By default, generated services run the installed eve binary from the agent root, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:+- **Vercel.** The web app and the eve runtime deploy as a single project. `withEve()` writes Build Output `services` for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Next.js app itself remains the default app. Vercel assembles authored [schedules](../../schedules) into the project config as Vercel Cron Jobs, including correctly prefixed jobs for named agents, while cron entries owned by the Next.js app are preserved. By default, generated services run the installed eve binary from the agent root, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:```tsexport default withEve(nextConfig, {diff --git a/docs/schedules.mdx b/docs/schedules.mdxindex 7b9bc0f9f..10ca6cfe0 100644--- a/docs/schedules.mdx+++ b/docs/schedules.mdx@@ -100,7 +100,11 @@ The route is dev-only. Production builds never mount it, and it needs no auth si## On Vercel-Hosted Vercel builds turn every `defineSchedule(...)` into a Vercel Cron Job, with each `cron` written as an entry in `.vercel/output/config.json`. Vercel evaluates these expressions in UTC. Confirm discovery under **Settings → Cron Jobs** and watch execution history under **Observability → Cron Jobs**. Per-run logs land under **Observability → Logs**.+Hosted Vercel builds turn every `defineSchedule(...)` into a Vercel Cron Job, with each `cron` written as an entry in `.vercel/output/config.json`. This also applies when [`withEve`](./guides/frontend/nextjs) embeds one or more agents in a Next.js deployment: Vercel assembles each generated eve service's schedules into the project Build Output config while preserving existing project cron entries. Named agents use their public `/eve/agents/<name>` route prefix automatically.++When running `vercel build` locally, use Vercel CLI 56.4.0 or later so generated-service cron entries are included in the project output.++Vercel evaluates cron expressions in UTC. Confirm discovery under **Settings → Cron Jobs** and watch execution history under **Observability → Cron Jobs**. Per-run logs land under **Observability → Logs**.## Self-deployed hostsdiff --git a/packages/eve/src/internal/nitro/host/build-application.ts b/packages/eve/src/internal/nitro/host/build-application.tsindex acfe42cf1..eb1ba8036 100644--- a/packages/eve/src/internal/nitro/host/build-application.ts+++ b/packages/eve/src/internal/nitro/host/build-application.ts@@ -33,6 +33,7 @@ import { createProductionApplicationNitro } from "#internal/nitro/host/create-apimport { emitVercelAgentSummary } from "#internal/nitro/host/build-vercel-agent-summary.js";import { tryReadExtensionBuildConfig } from "#internal/nitro/host/build-extension.js";import { copyHostMiddlewareFunctions } from "#internal/nitro/host/copy-host-middleware.js";+import { normalizeVercelServiceCrons } from "#internal/nitro/host/normalize-vercel-service-crons.js";import { prepareProductionApplicationHost } from "#internal/nitro/host/prepare-application-host.js";import { runVercelBuildPrewarm } from "#internal/nitro/host/vercel-build-prewarm.js";import type { ApplicationBuildOptions } from "#internal/nitro/host/types.js";@@ -437,6 +438,12 @@ async function buildApplicationInWorkspace(}const vercelServiceOutput = options.vercelServiceOutput;if (vercelServiceOutput !== undefined) {+ await measureBuildPhase(profiler, "vercel.service-crons.normalize", () =>+ normalizeVercelServiceCrons({+ publicRoutePrefix: options.publicRoutePrefix,+ serviceOutputDirectory: workspace.publication.output.stagedDir,+ }),+ );await measureBuildPhase(profiler, "vercel.host-middleware.copy", () =>copyHostMiddlewareFunctions({hostOutputDirectory: vercelServiceOutput.hostOutputDirectory,diff --git a/packages/eve/src/internal/nitro/host/normalize-vercel-service-crons.integration.test.ts b/packages/eve/src/internal/nitro/host/normalize-vercel-service-crons.integration.test.tsnew file mode 100644index 000000000..ee4f84669--- /dev/null+++ b/packages/eve/src/internal/nitro/host/normalize-vercel-service-crons.integration.test.ts@@ -0,0 +1,118 @@+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { afterEach, describe, expect, it } from "vitest";++import { normalizeVercelServiceCrons } from "#internal/nitro/host/normalize-vercel-service-crons.js";++const temporaryRoots: string[] = [];++async function createOutputDirectory(name: string): Promise<string> {+ const directory = await mkdtemp(join(tmpdir(), `eve-service-crons-${name}-`));+ temporaryRoots.push(directory);+ return directory;+}++async function writeOutputConfig(+ outputDirectory: string,+ config: Record<string, unknown>,+): Promise<void> {+ await mkdir(outputDirectory, { recursive: true });+ await writeFile(join(outputDirectory, "config.json"), `${JSON.stringify(config, null, 2)}\n`);+}++async function readOutputConfig(+ outputDirectory: string,+): Promise<Record<string, unknown> & { crons?: unknown[] }> {+ return JSON.parse(await readFile(join(outputDirectory, "config.json"), "utf8")) as Record<+ string,+ unknown+ > & { crons?: unknown[] };+}++afterEach(async () => {+ await Promise.all(+ temporaryRoots.splice(0).map((root) => rm(root, { force: true, recursive: true })),+ );+});++describe("normalizeVercelServiceCrons", () => {+ it("prefixes only eve cron paths and preserves the rest of the service config", async () => {+ const outputDirectory = await createOutputDirectory("named");+ await writeOutputConfig(outputDirectory, {+ crons: [+ { path: "/api/service-cleanup", schedule: "0 0 * * *" },+ { path: "/eve/v1/cron/current", schedule: "*/15 * * * *" },+ { path: "/eve/v1/cron/current", schedule: "*/15 * * * *" },+ {+ path: "/eve/agents/support/eve/v1/cron/keep",+ schedule: "*/5 * * * *",+ },+ ],+ routes: [{ handle: "filesystem" }],+ version: 3,+ });++ await normalizeVercelServiceCrons({+ publicRoutePrefix: "/eve/agents/billing/",+ serviceOutputDirectory: outputDirectory,+ });+ await normalizeVercelServiceCrons({+ publicRoutePrefix: "/eve/agents/billing/",+ serviceOutputDirectory: outputDirectory,+ });++ await expect(readOutputConfig(outputDirectory)).resolves.toEqual({+ crons: [+ { path: "/api/service-cleanup", schedule: "0 0 * * *" },+ {+ path: "/eve/agents/billing/eve/v1/cron/current",+ schedule: "*/15 * * * *",+ },+ {+ path: "/eve/agents/support/eve/v1/cron/keep",+ schedule: "*/5 * * * *",+ },+ ],+ routes: [{ handle: "filesystem" }],+ version: 3,+ });+ });++ it("deduplicates default-agent crons without changing their paths", async () => {+ const outputDirectory = await createOutputDirectory("default");+ await writeOutputConfig(outputDirectory, {+ crons: [+ { path: "/eve/v1/cron/current", schedule: "*/15 * * * *" },+ { path: "/eve/v1/cron/current", schedule: "*/15 * * * *" },+ ],+ version: 3,+ });++ await normalizeVercelServiceCrons({+ serviceOutputDirectory: outputDirectory,+ });++ expect((await readOutputConfig(outputDirectory)).crons).toEqual([+ { path: "/eve/v1/cron/current", schedule: "*/15 * * * *" },+ ]);+ });++ it("leaves service output without schedules unchanged", async () => {+ const outputDirectory = await createOutputDirectory("empty");+ await writeOutputConfig(outputDirectory, {+ routes: [{ handle: "filesystem" }],+ version: 3,+ });+ const configPath = join(outputDirectory, "config.json");+ const before = await readFile(configPath, "utf8");++ await normalizeVercelServiceCrons({+ publicRoutePrefix: "/eve/agents/billing",+ serviceOutputDirectory: outputDirectory,+ });++ await expect(readFile(configPath, "utf8")).resolves.toBe(before);+ });+});diff --git a/packages/eve/src/internal/nitro/host/normalize-vercel-service-crons.ts b/packages/eve/src/internal/nitro/host/normalize-vercel-service-crons.tsnew file mode 100644index 000000000..78e94bb94--- /dev/null+++ b/packages/eve/src/internal/nitro/host/normalize-vercel-service-crons.ts@@ -0,0 +1,112 @@+import { readFile } from "node:fs/promises";+import { join } from "node:path";++import { EVE_ROUTE_PREFIX } from "#protocol/routes.js";+import { atomicWriteFile } from "#shared/atomic-write-file.js";+import { normalizePublicRoutePrefix } from "#shared/public-route-prefix.js";++const VERCEL_OUTPUT_CONFIG_FILE_NAME = "config.json";+const EVE_CRON_ROUTE_PREFIX = `${EVE_ROUTE_PREFIX}/cron/`;++interface VercelCronConfig extends Record<string, unknown> {+ readonly path: string;+ readonly schedule: string;+}++interface VercelOutputConfig extends Record<string, unknown> {+ readonly crons?: readonly VercelCronConfig[];+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return value !== null && typeof value === "object" && !Array.isArray(value);+}++function parseOutputConfig(source: string, configPath: string): VercelOutputConfig {+ const value = JSON.parse(source) as unknown;+ if (!isRecord(value)) {+ throw new Error(`Vercel Build Output config at "${configPath}" must contain a JSON object.`);+ }+ return value;+}++function readCronConfigs(+ config: VercelOutputConfig,+ configPath: string,+): readonly VercelCronConfig[] | undefined {+ if (config.crons === undefined) {+ return undefined;+ }+ if (!Array.isArray(config.crons)) {+ throw new Error(`Vercel Build Output config at "${configPath}" must contain a crons array.`);+ }++ return config.crons.map((cron, index) => {+ if (+ !isRecord(cron) ||+ typeof cron.path !== "string" ||+ !cron.path.startsWith("/") ||+ typeof cron.schedule !== "string" ||+ cron.schedule.trim().length === 0+ ) {+ throw new Error(+ `Vercel Build Output config at "${configPath}" contains an invalid cron at index ${index}.`,+ );+ }+ return cron as VercelCronConfig;+ });+}++function normalizeCronPath(+ cron: VercelCronConfig,+ publicRoutePrefix: string | undefined,+): VercelCronConfig {+ if (publicRoutePrefix === undefined || !cron.path.startsWith(EVE_CRON_ROUTE_PREFIX)) {+ return cron;+ }++ return {+ ...cron,+ path: `${publicRoutePrefix}${cron.path}`,+ };+}++function deduplicateCronConfigs(crons: readonly VercelCronConfig[]): readonly VercelCronConfig[] {+ const keys = new Set<string>();+ return crons.filter((cron) => {+ const key = `${cron.path}\0${cron.schedule}`;+ if (keys.has(key)) {+ return false;+ }+ keys.add(key);+ return true;+ });+}++/**+ * Makes an eve service's cron paths addressable through its public Vercel+ * mount before the service Build Output is returned to Vercel for assembly.+ */+export async function normalizeVercelServiceCrons(input: {+ readonly publicRoutePrefix?: string;+ readonly serviceOutputDirectory: string;+}): Promise<void> {+ const configPath = join(input.serviceOutputDirectory, VERCEL_OUTPUT_CONFIG_FILE_NAME);+ const config = parseOutputConfig(await readFile(configPath, "utf8"), configPath);+ const crons = readCronConfigs(config, configPath);+ if (crons === undefined) {+ return;+ }++ const publicRoutePrefix = normalizePublicRoutePrefix(input.publicRoutePrefix);+ const normalizedCrons = deduplicateCronConfigs(+ crons.map((cron) => normalizeCronPath(cron, publicRoutePrefix)),+ );+ const nextConfig: VercelOutputConfig = {+ ...config,+ crons: normalizedCrons,+ };++ if (JSON.stringify(config) !== JSON.stringify(nextConfig)) {+ await atomicWriteFile(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`);+ }+}diff --git a/packages/eve/test/scenarios/framework-next-build.scenario.test.ts b/packages/eve/test/scenarios/framework-next-build.scenario.test.tsindex b1c0cbcdb..3a65d1dae 100644--- a/packages/eve/test/scenarios/framework-next-build.scenario.test.ts+++ b/packages/eve/test/scenarios/framework-next-build.scenario.test.ts@@ -10,7 +10,7 @@ import { useScenarioApp } from "../../src/internal/testing/scenario-app.js";import { runPnpmCommand } from "../../src/internal/testing/run-pnpm-command.js";const REPO_ROOT = fileURLToPath(new URL("../../../..", import.meta.url));-const VERCEL_GENERATED_SERVICES_VERSION = "55.0.0";+const VERCEL_GENERATED_SERVICES_VERSION = "56.4.0";const VERCEL_PNPM_10_PROJECT_CREATED_AT = Date.UTC(2026, 6, 13);const scenarioApp = useScenarioApp();@@ -42,19 +42,88 @@ const NEXT_EVE_MIDDLEWARE_DESCRIPTOR = {},name: "next-eve-middleware",} satisfies ScenarioAppDescriptor;+const NEXT_EVE_NAMED_SCHEDULES_DESCRIPTOR = {+ ...NEXT_EVE_PROXY_DESCRIPTOR,+ files: {+ ...NEXT_EVE_PROXY_DESCRIPTOR.files,+ ".vercel/project.json": `${JSON.stringify(+ {+ orgId: "team_eve_scenario",+ projectId: "prj_eve_named_schedules_scenario",+ projectName: "next-eve-named-schedules",+ settings: {+ buildCommand: "pnpm exec next build",+ createdAt: VERCEL_PNPM_10_PROJECT_CREATED_AT,+ framework: "nextjs",+ nodeVersion: "24.x",+ outputDirectory: null,+ rootDirectory: null,+ },+ },+ null,+ 2,+ )}\n`,+ "agents/billing/agent.mjs": `import { defineAgent } from "eve";-async function readVercelOutputRoutes(outputRoot: string): Promise<readonly unknown[]> {+export default defineAgent({ model: "openai/gpt-5.4" });+`,+ "agents/billing/instructions.md": "You are the billing test agent.\n",+ "agents/billing/schedules/sweep.md": `---+cron: "*/10 * * * *"+---++Sweep overdue invoices.+`,+ "agents/support/agent.mjs": `import { defineAgent } from "eve";++export default defineAgent({ model: "openai/gpt-5.4" });+`,+ "agents/support/instructions.md": "You are the support test agent.\n",+ "agents/support/schedules/triage.md": `---+cron: "*/5 * * * *"+---++Triage the support queue.+`,+ "next.config.mjs": `import { withEve } from "eve/next";++export default withEve({}, {+ agents: {+ billing: "./agents/billing",+ support: "./agents/support",+ },+});+`,+ "src/app/api/user-cleanup/route.js": `export function GET() {+ return Response.json({ ok: true });+}+`,+ "vercel.json": `${JSON.stringify(+ {+ crons: [{ path: "/api/user-cleanup", schedule: "0 0 * * *" }],+ },+ null,+ 2,+ )}\n`,+ },+ name: "next-eve-named-schedules",+} satisfies ScenarioAppDescriptor;++async function readVercelOutputConfig(outputRoot: string): Promise<Record<string, unknown>> {const config: unknown = JSON.parse(await readFile(join(outputRoot, "config.json"), "utf8"));- if (- typeof config !== "object" ||- config === null ||- !("routes" in config) ||- !Array.isArray(config.routes)- ) {- throw new Error("Expected Vercel Build Output config.json to contain a routes array.");+ if (typeof config !== "object" || config === null || Array.isArray(config)) {+ throw new Error("Expected Vercel Build Output config.json to contain an object.");}+ return config as Record<string, unknown>;+}++async function readVercelOutputRoutes(outputRoot: string): Promise<readonly unknown[]> {+ const config = await readVercelOutputConfig(outputRoot);+ if (!Array.isArray(config.routes)) {+ throw new Error("Expected Vercel Build Output config.json to contain a routes array.");+ }return config.routes;}@@ -98,4 +167,30 @@ describe("framework-next build", () => {),).resolves.toBeUndefined();}, 240_000);++ it("publishes named eve schedules into the assembled host output", async () => {+ const app = await scenarioApp(NEXT_EVE_NAMED_SCHEDULES_DESCRIPTOR);++ await runPnpmCommand({+ args: ["exec", "vercel", "build", "--yes"],+ cwd: app.appRoot,+ });++ const outputRoot = join(app.appRoot, ".vercel", "output");+ const config = await readVercelOutputConfig(outputRoot);+ expect(config.crons).toHaveLength(3);+ expect(config.crons).toEqual(+ expect.arrayContaining([+ { path: "/api/user-cleanup", schedule: "0 0 * * *" },+ {+ path: expect.stringMatching(/^\/eve\/agents\/billing\/eve\/v1\/cron\/[A-Za-z0-9_-]+$/),+ schedule: "*/10 * * * *",+ },+ {+ path: expect.stringMatching(/^\/eve\/agents\/support\/eve\/v1\/cron\/[A-Za-z0-9_-]+$/),+ schedule: "*/5 * * * *",+ },+ ]),+ );+ }, 240_000);});