The Open Framework for Building Agents
Add eve start --no-schedules for self-hosted replicas (#5056)
prha743b4989a82e
diff --git a/.changeset/quiet-schedule-replicas.md b/.changeset/quiet-schedule-replicas.mdnew file mode 100644index 000000000..44342913f--- /dev/null+++ b/.changeset/quiet-schedule-replicas.md@@ -0,0 +1,5 @@+---+"eve": patch+---++`eve start --no-schedules` and `EVE_SCHEDULES_DISABLED=1` start a server that does not fire authored cron schedules, so only one process runs them when you scale out.diff --git a/docs/guides/deployment/self-hosting.md b/docs/guides/deployment/self-hosting.mdindex 8a9a91c88..dc727e026 100644--- a/docs/guides/deployment/self-hosting.md+++ b/docs/guides/deployment/self-hosting.md@@ -105,6 +105,8 @@ You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if yThe standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.+Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).+## Verify the serviceCheck the health route after your proxy and authentication configuration are active:diff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex bb71a0db3..c1ae041a0 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -241,15 +241,20 @@ Useful stable artifacts written by inspection and development flows under `.eve/## `eve start````bash-eve start [--host <host>] [--port <port>]+eve start [--host <host>] [--port <port>] [--no-schedules]```-| Flag | Type | Default | Description |-| --------------- | ------ | ------------------ | ---------------------- |-| `--host <host>` | string | all interfaces | Host interface to bind |-| `--port <port>` | number | `$PORT`, then 3000 | Port to listen on |+| Flag | Type | Default | Description |+| ---------------- | ------ | ------------------ | --------------------------------------------- |+| `--host <host>` | string | all interfaces | Host interface to bind |+| `--port <port>` | number | `$PORT`, then 3000 | Port to listen on |+| `--no-schedules` | flag | schedules on | Start without running authored cron schedules |-Serves the previously built output. Prints the listening URL.+Serves the previously built output. Prints the listening URL, and a `schedules disabled` line when `--no-schedules` or `EVE_SCHEDULES_DISABLED` turns schedules off. HTTP requests and workflow jobs continue to run.++Set `EVE_SCHEDULES_DISABLED=1` or `true` (case-insensitive) to disable authored cron schedules at runtime, including when you run `node .output/server/index.mjs` directly. Unset, empty, and other values leave schedules enabled. `--no-schedules` sets the variable to `1` only for the spawned server; omitting the flag preserves any value you already set. The same build can run with schedules enabled or disabled.++Use this setting when [scaling self-hosted replicas](../guides/deployment/self-hosting#run-schedules). It also disables authored cron dispatch on Vercel if set there, but does not affect explicit schedule dispatch in `eve dev`.For self-hosted deployments, copy the app source, `.output/`, and installed dependencies together. The deployment directory can differ from the build directory. Preserve the relative layout of any workspace packages used by the app; startup resolves sandbox prewarm modules from the deployed source.diff --git a/packages/eve/src/cli/dev/command-options.ts b/packages/eve/src/cli/dev/command-options.tsindex 50430df05..060ae055d 100644--- a/packages/eve/src/cli/dev/command-options.ts+++ b/packages/eve/src/cli/dev/command-options.ts@@ -30,4 +30,5 @@ export interface DevelopmentCliOptions {export interface ProductionCliOptions {host?: string;port?: number;+ schedules?: boolean;}diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.tsindex 63721e9ea..ce4a3bd26 100644--- a/packages/eve/src/cli/run.test.ts+++ b/packages/eve/src/cli/run.test.ts@@ -1,6 +1,6 @@import { resolve } from "node:path";-import { describe, expect, it, vi } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import { createCliProgram, resolveDevUiMode, resolveTuiDisplayOptions, runCli } from "#cli/run.js";import { cliTelemetryCommandPaths, internalCliCommandPaths } from "#cli/telemetry/index.js";@@ -664,6 +664,41 @@ describe("eve dev --input", () => {});});+describe("eve start schedules", () => {+ afterEach(() => vi.unstubAllEnvs());++ it.each([+ { argv: ["start", "--no-schedules"], inherited: undefined, schedules: false, reported: true },+ { argv: ["start"], inherited: "1", schedules: true, reported: true },+ { argv: ["start"], inherited: undefined, schedules: true, reported: false },+ ])(+ "passes schedules=$schedules and reports disabled=$reported for $argv with $inherited",+ async ({ argv, inherited, schedules, reported }) => {+ vi.stubEnv("EVE_SCHEDULES_DISABLED", inherited);+ const lines: string[] = [];+ const startProductionHost = vi.fn(async () => ({+ close: async () => {},+ url: "http://127.0.0.1:4321/",+ wait: async () => {},+ }));++ await runCli(+ argv,+ { error: () => {}, log: (line) => lines.push(line) },+ {+ startProductionHost,+ },+ );++ expect(startProductionHost).toHaveBeenCalledWith(+ expect.any(String),+ expect.objectContaining({ schedules }),+ );+ expect(lines.some((line) => line.includes("schedules disabled"))).toBe(reported);+ },+ );+});+describe("eve remote invoke", () => {it("runs a fresh remote task without starting the TUI", async () => {const runInvoke = vi.fn(async () => ({diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.tsindex 852934a33..3b020c46e 100644--- a/packages/eve/src/cli/run.ts+++ b/packages/eve/src/cli/run.ts@@ -1,6 +1,7 @@import { Command, CommanderError } from "#compiled/commander/index.js";import { registerBuildCommand, type BuildHost } from "#cli/commands/build.js";import { resolveApplicationRoot } from "#internal/application/paths.js";+import { areSchedulesDisabled } from "#internal/schedules/disabled.js";import { resolveInstalledPackageInfo } from "#internal/application/package.js";import { isCodingAgentLaunch } from "#cli/agent-detection.js";import type { CliApplicationContext } from "#cli/application-command.js";@@ -79,6 +80,7 @@ interface CliRuntimeDependencies {options?: {host?: string;port?: number;+ schedules?: boolean;},): Promise<ProductionServerHandle>;}@@ -253,6 +255,7 @@ export function createCliProgram(agentCommand(program.command("start"), applicationContext).description("Start a built eve application.")+ .option("--no-schedules", "Start without running authored cron schedules").option("--host <host>", "Host interface to bind").option("--port <port>", "Port to listen on (defaults to $PORT, then 3000)", parsePortOption).action(async (options: ProductionCliOptions) => {@@ -264,6 +267,7 @@ export function createCliProgram(const server = await startProductionHost(applicationContext.root, {host: options.host,port: options.port,+ schedules: options.schedules,});logger.log(@@ -274,6 +278,17 @@ export function createCliProgram(}),);+ // The server inherits this process environment, including loaded env files.+ if (options.schedules === false || areSchedulesDisabled()) {+ logger.log(+ renderCliTaggedLine(theme, {+ message: "schedules disabled",+ tag: "start",+ tone: "info",+ }),+ );+ }+await waitForShutdownSignal({ close: () => server.close(), wait: () => server.wait() });});diff --git a/packages/eve/src/internal/nitro/host/start-production-server.test.ts b/packages/eve/src/internal/nitro/host/start-production-server.test.tsindex 88acbf991..df13d8aad 100644--- a/packages/eve/src/internal/nitro/host/start-production-server.test.ts+++ b/packages/eve/src/internal/nitro/host/start-production-server.test.ts@@ -68,6 +68,7 @@ describe("startProductionServer", () => {afterEach(() => {vi.restoreAllMocks();+ vi.unstubAllEnvs();globalThis.fetch = originalFetch;if (originalPort === undefined) {delete process.env.PORT;@@ -120,6 +121,28 @@ describe("startProductionServer", () => {expect(child.kill).toHaveBeenCalledWith("SIGTERM");});+ it.each([+ { schedules: undefined, inherited: undefined, expected: undefined },+ { schedules: false, inherited: undefined, expected: "1" },+ { schedules: undefined, inherited: "true", expected: "true" },+ { schedules: false, inherited: "false", expected: "1" },+ ])(+ "passes EVE_SCHEDULES_DISABLED=$expected for schedules=$schedules over $inherited",+ async ({ schedules, inherited, expected }) => {+ vi.stubEnv("EVE_SCHEDULES_DISABLED", inherited);+ const { startProductionServer } = await import("./start-production-server.js");+ const child = createChildProcess();+ (child.stdout as PassThrough).write("Listening on http://127.0.0.1:4321/\n");+ mocks.spawn.mockReturnValueOnce(child);++ const server = await startProductionServer("/tmp/app", { schedules });+ const spawnOptions = mocks.spawn.mock.calls[0]?.[2] as { env: NodeJS.ProcessEnv };+ expect(spawnOptions.env.EVE_SCHEDULES_DISABLED).toBe(expected);+ expect(process.env.EVE_SCHEDULES_DISABLED).toBe(inherited);+ await server.close();+ },+ );+it("uses PORT when no explicit port is provided", async () => {const { startProductionServer } = await import("./start-production-server.js");const child = createChildProcess();diff --git a/packages/eve/src/internal/nitro/host/start-production-server.ts b/packages/eve/src/internal/nitro/host/start-production-server.tsindex 7dd61736e..7fa30c289 100644--- a/packages/eve/src/internal/nitro/host/start-production-server.ts+++ b/packages/eve/src/internal/nitro/host/start-production-server.ts@@ -6,6 +6,7 @@ import { setTimeout as sleep } from "node:timers/promises";import { loadDevelopmentEnvironmentFiles } from "#cli/dev/environment.js";import type { ProductionServerHandle } from "#internal/nitro/host/types.js";+import { EVE_SCHEDULES_DISABLED_ENV } from "#internal/schedules/disabled.js";const DEFAULT_PRODUCTION_SERVER_HOST = "0.0.0.0";const DEFAULT_PRODUCTION_SERVER_PORT = 3000;@@ -192,6 +193,7 @@ export async function startProductionServer(options: {host?: string;port?: number;+ schedules?: boolean;} = {},): Promise<ProductionServerHandle> {const appRoot = resolve(rootDir);@@ -221,15 +223,20 @@ export async function startProductionServer(let closing = false;let startError: unknown;+ const env: NodeJS.ProcessEnv = {+ ...process.env,+ HOST: host,+ NITRO_HOST: host,+ NITRO_PORT: String(port),+ PORT: String(port),+ };+ if (options.schedules === false) {+ env[EVE_SCHEDULES_DISABLED_ENV] = "1";+ }+const child = spawn(process.execPath, [serverEntry], {cwd: appRoot,- env: {- ...process.env,- HOST: host,- NITRO_HOST: host,- NITRO_PORT: String(port),- PORT: String(port),- },+ env,stdio: ["ignore", "pipe", "pipe"],});diff --git a/packages/eve/src/internal/nitro/routes/schedule-task.test.ts b/packages/eve/src/internal/nitro/routes/schedule-task.test.tsnew file mode 100644index 000000000..dc72538fc--- /dev/null+++ b/packages/eve/src/internal/nitro/routes/schedule-task.test.ts@@ -0,0 +1,43 @@+import { afterEach, expect, it, vi } from "vitest";++const mocks = vi.hoisted(() => ({+ info: vi.fn(),+ loadResolvedCompiledScheduleByTaskName: vi.fn(),+ resolveNitroCompiledArtifactsSource: vi.fn(),+}));++vi.mock("#internal/logging.js", () => ({+ createLogger: () => ({ info: mocks.info }),+}));+vi.mock("#runtime/schedules/resolve-schedule.js", () => ({+ loadResolvedCompiledScheduleByTaskName: mocks.loadResolvedCompiledScheduleByTaskName,+}));+vi.mock("#internal/nitro/routes/runtime-artifacts.js", () => ({+ resolveNitroCompiledArtifactsSource: mocks.resolveNitroCompiledArtifactsSource,+}));++import { dispatchScheduleTask } from "./schedule-task.js";++afterEach(() => {+ vi.unstubAllEnvs();+});++it("skips disabled schedules before resolving artifacts and logs only the first skipped tick", async () => {+ vi.stubEnv("EVE_SCHEDULES_DISABLED", "1");+ const config = { kind: "production", sandboxScope: "test" } as const;++ await expect(dispatchScheduleTask("heartbeat", config)).resolves.toEqual({+ skipped: "schedules-disabled",+ taskName: "heartbeat",+ });+ await expect(dispatchScheduleTask("digest", config)).resolves.toEqual({+ skipped: "schedules-disabled",+ taskName: "digest",+ });++ expect(mocks.resolveNitroCompiledArtifactsSource).not.toHaveBeenCalled();+ expect(mocks.loadResolvedCompiledScheduleByTaskName).not.toHaveBeenCalled();+ expect(mocks.info).toHaveBeenCalledExactlyOnceWith(+ 'Schedules are disabled in this process (EVE_SCHEDULES_DISABLED); skipping "heartbeat"',+ );+});diff --git a/packages/eve/src/internal/nitro/routes/schedule-task.ts b/packages/eve/src/internal/nitro/routes/schedule-task.tsindex 77bf5287c..c020d7b5e 100644--- a/packages/eve/src/internal/nitro/routes/schedule-task.ts+++ b/packages/eve/src/internal/nitro/routes/schedule-task.ts@@ -6,6 +6,11 @@ import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-import type { NitroArtifactsConfig } from "#internal/nitro/routes/runtime-artifacts.js";import { resolveNitroCompiledArtifactsSource } from "#internal/nitro/routes/runtime-artifacts.js";import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";+import { createLogger } from "#internal/logging.js";+import { areSchedulesDisabled, EVE_SCHEDULES_DISABLED_ENV } from "#internal/schedules/disabled.js";++const log = createLogger("schedule.dispatch");+let loggedSchedulesDisabled = false;/*** Dispatches one eve authored schedule via the execution engine.@@ -17,7 +22,20 @@ import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifactsexport async function dispatchScheduleTask(taskName: string,config: NitroArtifactsConfig,-): Promise<{ scheduleId: string; sessionIds: readonly string[] }> {+): Promise<+ | { scheduleId: string; sessionIds: readonly string[] }+ | { skipped: "schedules-disabled"; taskName: string }+> {+ if (areSchedulesDisabled()) {+ if (!loggedSchedulesDisabled) {+ loggedSchedulesDisabled = true;+ log.info(+ `Schedules are disabled in this process (${EVE_SCHEDULES_DISABLED_ENV}); skipping "${taskName}"`,+ );+ }+ return { skipped: "schedules-disabled", taskName };+ }+return await dispatchScheduleTaskFromArtifacts(taskName,resolveNitroCompiledArtifactsSource(config),diff --git a/packages/eve/src/internal/schedules/disabled.test.ts b/packages/eve/src/internal/schedules/disabled.test.tsnew file mode 100644index 000000000..36fb15f79--- /dev/null+++ b/packages/eve/src/internal/schedules/disabled.test.ts@@ -0,0 +1,16 @@+import { expect, it } from "vitest";++import { areSchedulesDisabled } from "./disabled.js";++it.each([+ [undefined, false],+ ["", false],+ ["0", false],+ ["false", false],+ ["yes", false],+ ["1", true],+ ["true", true],+ ["TrUe", true],+] as const)("interprets EVE_SCHEDULES_DISABLED=%s as disabled=%s", (value, disabled) => {+ expect(areSchedulesDisabled({ EVE_SCHEDULES_DISABLED: value })).toBe(disabled);+});diff --git a/packages/eve/src/internal/schedules/disabled.ts b/packages/eve/src/internal/schedules/disabled.tsnew file mode 100644index 000000000..dc856d1f1--- /dev/null+++ b/packages/eve/src/internal/schedules/disabled.ts@@ -0,0 +1,8 @@+export const EVE_SCHEDULES_DISABLED_ENV = "EVE_SCHEDULES_DISABLED";++export function areSchedulesDisabled(+ env: Readonly<Record<string, string | undefined>> = process.env,+): boolean {+ const value = env[EVE_SCHEDULES_DISABLED_ENV]?.toLowerCase();+ return value === "1" || value === "true";+}diff --git a/packages/eve/test/scenarios/cli.scenario.test.ts b/packages/eve/test/scenarios/cli.scenario.test.tsindex 6b56142e3..5a1fa53f2 100644--- a/packages/eve/test/scenarios/cli.scenario.test.ts+++ b/packages/eve/test/scenarios/cli.scenario.test.ts@@ -325,6 +325,7 @@ describe("runCli", () => {expect(startProductionHost).toHaveBeenCalledWith(resolvedWorkspaceRoot, {host: "127.0.0.1",port: 0,+ schedules: true,});});