Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Improve duplicate eve dev process hint (#52)

JJ Kasper432503d4e5b0
diff --git a/.changeset/dev-process-connect-hint.md b/.changeset/dev-process-connect-hint.md
new file mode 100644
index 000000000..43b5bd785
--- /dev/null
+++ b/.changeset/dev-process-connect-hint.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Clarify the duplicate `eve dev` process error with a copyable package-manager command for connecting to the existing local server instead of stopping it.
diff --git a/packages/eve/src/internal/nitro/host/start-development-server.test.ts b/packages/eve/src/internal/nitro/host/start-development-server.test.ts
index 9e8cfa9cf..409a8a7f7 100644
--- a/packages/eve/src/internal/nitro/host/start-development-server.test.ts
+++ b/packages/eve/src/internal/nitro/host/start-development-server.test.ts
@@ -58,6 +58,11 @@ const mocks = vi.hoisted(() => {
rm: vi.fn(async (path: string) => {
files.delete(path);
}),
+ stat: vi.fn(async (path: string) => {
+ if (!files.has(path)) {
+ throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+ }
+ }),
startDevelopmentSandboxPrewarmInBackground: vi.fn(() => undefined),
pruneLocalSandboxTemplatesInBackground: vi.fn(() => undefined),
stopDevelopmentSandboxResources: vi.fn(async () => undefined),
@@ -78,6 +83,7 @@ vi.mock("node:fs/promises", () => ({
mkdir: mocks.mkdir,
readFile: mocks.readFile,
rm: mocks.rm,
+ stat: mocks.stat,
writeFile: mocks.writeFile,
}));
@@ -153,6 +159,7 @@ function createSocket(): Socket {
}
const developmentProcessIdPath = join("/tmp/eve-test", ".eve", "dev-process.pid");
+const developmentServerMetadataPath = join("/tmp/eve-test", ".eve", "dev-server.json");
async function startServer(): Promise<{
close(): Promise<void>;
@@ -327,10 +334,15 @@ describe("startDevelopmentServer", () => {
const server = await startDevelopmentServer("/tmp/eve-test");
expect(mocks.files.get(developmentProcessIdPath)).toBe(`${process.pid}\n`);
+ expect(JSON.parse(mocks.files.get(developmentServerMetadataPath) ?? "{}")).toMatchObject({
+ pid: process.pid,
+ url: "http://localhost:2000/",
+ });
await server.close();
expect(mocks.files.has(developmentProcessIdPath)).toBe(false);
+ expect(mocks.files.has(developmentServerMetadataPath)).toBe(false);
});
it("refuses to start when the agent already has a running dev process", async () => {
@@ -340,6 +352,35 @@ describe("startDevelopmentServer", () => {
await expect(startDevelopmentServer("/tmp/eve-test")).rejects.toThrow(
[
`A dev server is already running for this eve agent (pid ${process.pid}).`,
+ "To connect to the existing instance, run: pnpm exec eve dev http://localhost:PORT",
+ `To stop it, run: ${
+ process.platform === "win32" ? "taskkill /PID" : "kill"
+ } ${process.pid}`,
+ ].join("\n"),
+ );
+ expect(mocks.createApplicationNitro).not.toHaveBeenCalled();
+ });
+
+ it("prints a copyable connect command with the detected package manager and server URL", async () => {
+ const { startDevelopmentServer } = await import("./start-development-server.js");
+ mocks.files.set(
+ join("/tmp/eve-test", "package.json"),
+ JSON.stringify({ packageManager: "[email protected]" }),
+ );
+ mocks.files.set(developmentProcessIdPath, `${process.pid}\n`);
+ mocks.files.set(
+ developmentServerMetadataPath,
+ JSON.stringify({
+ pid: process.pid,
+ updatedAt: "2026-06-17T00:00:00.000Z",
+ url: "http://127.0.0.1:4321/",
+ }),
+ );
+
+ await expect(startDevelopmentServer("/tmp/eve-test")).rejects.toThrow(
+ [
+ `A dev server is already running for this eve agent (pid ${process.pid}).`,
+ "To connect to the existing instance, run: npm exec -- eve dev http://127.0.0.1:4321/",
`To stop it, run: ${
process.platform === "win32" ? "taskkill /PID" : "kill"
} ${process.pid}`,
diff --git a/packages/eve/src/internal/nitro/host/start-development-server.ts b/packages/eve/src/internal/nitro/host/start-development-server.ts
index e44d99c58..5db5a10ef 100644
--- a/packages/eve/src/internal/nitro/host/start-development-server.ts
+++ b/packages/eve/src/internal/nitro/host/start-development-server.ts
@@ -31,13 +31,27 @@ import {
DEFAULT_DEVELOPMENT_SERVER_PORT,
MAX_DEVELOPMENT_SERVER_PORT_ATTEMPTS,
} from "#internal/nitro/host/ports.js";
+import { detectPackageManager, type PackageManagerKind } from "#setup/package-manager.js";
+import { eveDevArguments } from "#setup/primitives/index.js";
const MAX_ALLOWED_DEVELOPMENT_SERVER_PORT = 65_535;
const WORKFLOW_LOCAL_BASE_URL_ENV = "WORKFLOW_LOCAL_BASE_URL";
const PORT_ENV = "PORT";
const DEVELOPMENT_PROCESS_ID_FILE = "dev-process.pid";
+const DEVELOPMENT_SERVER_METADATA_FILE = "dev-server.json";
const DEFAULT_DEVELOPMENT_SERVER_HOST = "127.0.0.1";
const IPV6_LOOPBACK_HOSTNAME = "[::1]";
+const DEVELOPMENT_SERVER_URL_PLACEHOLDER = "http://localhost:PORT";
+
+interface DevelopmentServerMetadata {
+ readonly processId: number;
+ readonly url: string;
+}
+
+interface ActiveDevelopmentProcess {
+ readonly processId: number;
+ readonly url?: string;
+}
/**
* Hostnames Nitro/srvx surface when listening on an IPv6 wildcard interface.
@@ -111,6 +125,10 @@ function resolveDevelopmentProcessIdPath(appRoot: string): string {
return join(appRoot, ".eve", DEVELOPMENT_PROCESS_ID_FILE);
}
+function resolveDevelopmentServerMetadataPath(appRoot: string): string {
+ return join(appRoot, ".eve", DEVELOPMENT_SERVER_METADATA_FILE);
+}
+
function parseProcessId(value: string): number | undefined {
const trimmed = value.trim();
@@ -141,7 +159,60 @@ function formatKillCommand(processId: number): string {
return `kill ${processId}`;
}
-async function readActiveDevelopmentProcessId(appRoot: string): Promise<number | undefined> {
+function parseDevelopmentServerMetadata(value: string): DevelopmentServerMetadata | undefined {
+ let parsed: unknown;
+
+ try {
+ parsed = JSON.parse(value);
+ } catch {
+ return undefined;
+ }
+
+ if (
+ typeof parsed !== "object" ||
+ parsed === null ||
+ !("pid" in parsed) ||
+ typeof parsed.pid !== "number" ||
+ !Number.isSafeInteger(parsed.pid) ||
+ parsed.pid <= 0 ||
+ !("url" in parsed) ||
+ typeof parsed.url !== "string"
+ ) {
+ return undefined;
+ }
+
+ const url = normalizeDevelopmentServerClientUrl(parsed.url);
+
+ try {
+ const parsedUrl = new URL(url);
+ if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+ return undefined;
+ }
+ } catch {
+ return undefined;
+ }
+
+ return {
+ processId: parsed.pid,
+ url,
+ };
+}
+
+async function readDevelopmentServerMetadata(
+ appRoot: string,
+): Promise<DevelopmentServerMetadata | undefined> {
+ try {
+ return parseDevelopmentServerMetadata(
+ await readFile(resolveDevelopmentServerMetadataPath(appRoot), "utf8"),
+ );
+ } catch {
+ return undefined;
+ }
+}
+
+async function readActiveDevelopmentProcess(
+ appRoot: string,
+): Promise<ActiveDevelopmentProcess | undefined> {
let processId: number | undefined;
try {
@@ -154,18 +225,61 @@ async function readActiveDevelopmentProcessId(appRoot: string): Promise<number |
return undefined;
}
- return processId;
+ const metadata = await readDevelopmentServerMetadata(appRoot);
+
+ return {
+ processId,
+ url: metadata?.processId === processId ? metadata.url : undefined,
+ };
+}
+
+async function detectDevelopmentCommandPackageManager(
+ appRoot: string,
+): Promise<PackageManagerKind> {
+ try {
+ return (await detectPackageManager(appRoot)).kind;
+ } catch {
+ return "pnpm";
+ }
+}
+
+async function formatDevelopmentServerConnectCommand(
+ appRoot: string,
+ serverUrl: string,
+): Promise<string> {
+ const packageManager = await detectDevelopmentCommandPackageManager(appRoot);
+ return [packageManager, ...eveDevArguments(packageManager), serverUrl].join(" ");
+}
+
+async function writeDevelopmentServerMetadata(appRoot: string, serverUrl: string): Promise<void> {
+ await writeFile(
+ resolveDevelopmentServerMetadataPath(appRoot),
+ `${JSON.stringify(
+ {
+ pid: process.pid,
+ updatedAt: new Date().toISOString(),
+ url: normalizeDevelopmentServerClientUrl(serverUrl),
+ },
+ null,
+ 2,
+ )}\n`,
+ "utf8",
+ );
}
async function writeDevelopmentProcessId(appRoot: string): Promise<() => Promise<void>> {
const processIdPath = resolveDevelopmentProcessIdPath(appRoot);
- const activeProcessId = await readActiveDevelopmentProcessId(appRoot);
+ const metadataPath = resolveDevelopmentServerMetadataPath(appRoot);
+ const activeProcess = await readActiveDevelopmentProcess(appRoot);
- if (activeProcessId !== undefined) {
+ if (activeProcess !== undefined) {
+ const connectUrl = activeProcess.url ?? DEVELOPMENT_SERVER_URL_PLACEHOLDER;
+ const connectCommand = await formatDevelopmentServerConnectCommand(appRoot, connectUrl);
throw new Error(
[
- `A dev server is already running for this eve agent (pid ${activeProcessId}).`,
- `To stop it, run: ${formatKillCommand(activeProcessId)}`,
+ `A dev server is already running for this eve agent (pid ${activeProcess.processId}).`,
+ `To connect to the existing instance, run: ${connectCommand}`,
+ `To stop it, run: ${formatKillCommand(activeProcess.processId)}`,
].join("\n"),
);
}
@@ -184,6 +298,13 @@ async function writeDevelopmentProcessId(appRoot: string): Promise<() => Promise
if (currentProcessId === process.pid) {
await rm(processIdPath, { force: true });
+ await rm(metadataPath, { force: true });
+ return;
+ }
+
+ const metadata = await readDevelopmentServerMetadata(appRoot);
+ if (metadata?.processId === process.pid) {
+ await rm(metadataPath, { force: true });
}
};
}
@@ -395,7 +516,9 @@ export async function startDevelopmentServer(
throw new Error("Nitro dev server did not expose a URL.");
}
- restoreWorkflowLocalQueueEnvironment = installWorkflowLocalQueueEnvironment(server.url);
+ const serverUrl = normalizeDevelopmentServerClientUrl(server.url);
+ await writeDevelopmentServerMetadata(preparedHost.appRoot, serverUrl);
+ restoreWorkflowLocalQueueEnvironment = installWorkflowLocalQueueEnvironment(serverUrl);
await prepare(nitro);
await buildNitro(nitro);
@@ -431,7 +554,7 @@ export async function startDevelopmentServer(
restoreDevelopmentSandboxRunId(previousDevelopmentSandboxRunId);
}
},
- url: normalizeDevelopmentServerClientUrl(server.url),
+ url: serverUrl,
};
} catch (error) {
await authoredSourceWatcher?.close().catch(() => {});