fix(eve): stabilize dev host artifact paths

Signed-off-by: Casey Gowrie <ctgowrie@gmail.com>

Author: ctgowrie

.changeset/stable-dev-host-artifacts.md

@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+`eve dev` now keeps Nitro build inputs outside prunable runtime snapshots. Long-running development servers no longer fail structural rebuilds with stale import errors after snapshot cleanup.

packages/eve/src/internal/application/compiled-artifacts.ts

@@ -37,6 +37,12 @@ export interface GeneratedCompiledArtifactsFiles {
   instrumentationSourcePath?: string;
 }
 
+export const GENERATED_COMPILED_ARTIFACT_FILE_NAMES = [
+  "compiled-artifacts-bootstrap.mjs",
+  "compiled-artifacts-instrumentation.mjs",
+  "compiled-artifacts-workflow-world.mjs",
+] as const;
+
 /**
  * Writes the generated compiled-artifacts bootstrap module.
  *
@@ -97,10 +103,6 @@ export async function writeCompiledArtifactsFiles(input: {
 
 const INSTRUMENTATION_EXTENSIONS = [".ts", ".mts", ".js", ".mjs"];
 
-/**
- * Resolves the optional `agent/instrumentation` module from the agent root
- * directory. Returns the absolute path if found, `undefined` otherwise.
- */
 function resolveInstrumentationModule(agentRoot: string): string | undefined {
   for (const ext of INSTRUMENTATION_EXTENSIONS) {
     const candidate = join(agentRoot, `instrumentation${ext}`);

packages/eve/src/internal/application/paths.ts

@@ -54,6 +54,10 @@ export function resolveNitroBuildDirectory(
   return join(rootDirectory, surface);
 }
 
+export function resolveApplicationHostArtifactsDirectory(appRoot: string): string {
+  return join(appRoot, ".eve", "host");
+}
+
 /**
  * Resolves the staged Nitro output directory for one isolated build surface.
  */

packages/eve/src/internal/nitro/dev-runtime-artifacts.integration.test.ts

@@ -155,6 +155,46 @@ describe("development runtime artifact snapshots", () => {
     });
   });
 
+  it("excludes generated host entrypoints from runtime snapshots", async () => {
+    const appRoot = await createScratchDirectory("eve-dev-runtime-host-entrypoints-");
+    const agentRoot = join(appRoot, "agent");
+    const compileDirectoryPath = join(appRoot, ".eve", "compile");
+
+    await mkdir(agentRoot, { recursive: true });
+    await mkdir(compileDirectoryPath, { recursive: true });
+    await writeFile(join(appRoot, "package.json"), '{"type":"module"}\n');
+    await writeFile(
+      join(compileDirectoryPath, "compiled-agent-manifest.json"),
+      `${JSON.stringify({ agentRoot, appRoot }, null, 2)}\n`,
+    );
+    await Promise.all(
+      [
+        "compiled-artifacts-bootstrap.mjs",
+        "compiled-artifacts-instrumentation.mjs",
+        "compiled-artifacts-workflow-world.mjs",
+      ].map((fileName) => writeFile(join(compileDirectoryPath, fileName), "stale\n")),
+    );
+
+    const snapshot = await stageDevelopmentRuntimeArtifactsSnapshot({
+      paths: { compileDirectoryPath },
+      project: { appRoot },
+    } as CompileAgentResult);
+    const snapshotCompileDirectory = join(snapshot.runtimeAppRoot, ".eve", "compile");
+
+    await expect(
+      readFile(join(snapshotCompileDirectory, "compiled-agent-manifest.json"), "utf8").then(
+        (source) => JSON.parse(source) as { appRoot: string },
+      ),
+    ).resolves.toMatchObject({ appRoot: snapshot.runtimeAppRoot });
+    for (const fileName of [
+      "compiled-artifacts-bootstrap.mjs",
+      "compiled-artifacts-instrumentation.mjs",
+      "compiled-artifacts-workflow-world.mjs",
+    ]) {
+      expect(existsSync(join(snapshotCompileDirectory, fileName))).toBe(false);
+    }
+  });
+
   it("stages package-less flat markdown agents with generated runtime package metadata", async () => {
     const appRoot = await createScratchDirectory("eve-dev-runtime-flat-package-less-");
     const compileDirectoryPath = join(appRoot, ".eve", "compile");

packages/eve/src/internal/nitro/dev-runtime-artifacts.ts

@@ -4,6 +4,7 @@ import { existsSync, readFileSync, type Dirent } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
 import type { CompileAgentResult } from "#compiler/compile-agent.js";
+import { GENERATED_COMPILED_ARTIFACT_FILE_NAMES } from "#internal/application/compiled-artifacts.js";
 import { copyDevelopmentSourceSnapshot } from "#internal/nitro/dev-runtime-source-snapshot-copy.js";
 import { createDevelopmentSourceSnapshotPlan } from "#internal/nitro/dev-runtime-source-snapshot.js";
 
@@ -78,13 +79,19 @@ export async function stageDevelopmentRuntimeArtifactsSnapshot(
     appRoot: compileResult.project.appRoot,
     snapshotRoot,
   });
+  const excludedCompileArtifactPaths = new Set(
+    GENERATED_COMPILED_ARTIFACT_FILE_NAMES.map((fileName) =>
+      join(compileResult.paths.compileDirectoryPath, fileName),
+    ),
+  );
 
   try {
     await copyDevelopmentSourceSnapshot(sourceSnapshotPlan);
     await cp(
       compileResult.paths.compileDirectoryPath,
       join(sourceSnapshotPlan.runtimeAppRoot, ".eve", "compile"),
       {
+        filter: (source) => !excludedCompileArtifactPaths.has(source),
         recursive: true,
       },
     );

packages/eve/src/internal/nitro/host/prepare-application-host.scenario.test.ts

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { normalizeEsmImportSpecifier } from "#internal/application/import-specifier.js";
+import {
+  pruneDevelopmentRuntimeArtifactsSnapshots,
+  resolveDevelopmentRuntimeArtifactsPointerPath,
+} from "#internal/nitro/dev-runtime-artifacts.js";
+import { useTemporaryAppRoots } from "#internal/testing/use-temporary-app-roots.js";
+import { prepareApplicationHost } from "#internal/nitro/host/prepare-application-host.js";
+
+const createAppRoot = useTemporaryAppRoots();
+
+interface DevelopmentRuntimePointer {
+  readonly runtimeAppRoot: string;
+  readonly snapshotRoot: string;
+}
+
+async function readDevelopmentRuntimePointer(appRoot: string): Promise<DevelopmentRuntimePointer> {
+  return JSON.parse(
+    await readFile(resolveDevelopmentRuntimeArtifactsPointerPath(appRoot), "utf8"),
+  ) as DevelopmentRuntimePointer;
+}
+
+describe("prepareApplicationHost", () => {
+  it("keeps Nitro host inputs stable when their runtime snapshot is pruned", async () => {
+    const { agentRoot, appRoot } = await createAppRoot("eve-stable-dev-host-artifacts-", {
+      files: {
+        "agent/instructions.md": "Use the configured model.",
+      },
+      packageName: "stable-dev-host-artifacts",
+    });
+    const agentModulePath = join(agentRoot, "agent.mjs");
+    await writeFile(agentModulePath, 'export default { model: "openai/gpt-5.4" };\n');
+
+    const firstHost = await prepareApplicationHost(appRoot, { dev: true });
+    const firstPointer = await readDevelopmentRuntimePointer(appRoot);
+    const stableHostDirectory = join(appRoot, ".eve", "host");
+    const stableBootstrapPath = join(stableHostDirectory, "compiled-artifacts-bootstrap.mjs");
+    const snapshotBootstrapPath = join(
+      firstPointer.runtimeAppRoot,
+      ".eve",
+      "compile",
+      "compiled-artifacts-bootstrap.mjs",
+    );
+
+    expect(firstHost.compiledArtifacts.bootstrapPath).toBe(stableBootstrapPath);
+    expect(firstHost.compiledArtifacts.workflowWorldPluginPath).toBe(
+      join(stableHostDirectory, "compiled-artifacts-workflow-world.mjs"),
+    );
+    expect(firstHost.compiledArtifacts.bootstrapPath).not.toContain("/.eve/dev-runtime/snapshots/");
+    expect(await readFile(stableBootstrapPath, "utf8")).toContain(
+      normalizeEsmImportSpecifier(agentModulePath),
+    );
+    expect(existsSync(snapshotBootstrapPath)).toBe(false);
+
+    await writeFile(
+      agentModulePath,
+      'export default { model: "openai/gpt-5.4" };\n// revision two\n',
+    );
+    const nextHost = await prepareApplicationHost(appRoot, { dev: true });
+    const nextPointer = await readDevelopmentRuntimePointer(appRoot);
+
+    expect(nextHost.compiledArtifacts.bootstrapPath).toBe(stableBootstrapPath);
+    expect(nextPointer.snapshotRoot).not.toBe(firstPointer.snapshotRoot);
+
+    await pruneDevelopmentRuntimeArtifactsSnapshots({
+      appRoot,
+      now: Date.now() + 1_000,
+      recentWindowMs: 0,
+      retainCount: 0,
+    });
+
+    expect(existsSync(firstPointer.snapshotRoot)).toBe(false);
+    expect(existsSync(stableBootstrapPath)).toBe(true);
+  });
+});

packages/eve/src/internal/nitro/host/prepare-application-host.ts

@@ -1,17 +1,16 @@
-import { readFile } from "node:fs/promises";
-
 import { compileAgent } from "#compiler/compile-agent.js";
-import type { CompiledAgentManifest } from "#compiler/manifest.js";
 import { createScheduleRegistrations } from "#runtime/schedules/register.js";
 import { loadResolvedCompiledSchedules } from "#runtime/schedules/resolve-schedule.js";
 import { writeCompiledArtifactsFiles } from "#internal/application/compiled-artifacts.js";
-import { resolveWorkflowBuildDirectory } from "#internal/application/paths.js";
+import {
+  resolveApplicationHostArtifactsDirectory,
+  resolveWorkflowBuildDirectory,
+} from "#internal/application/paths.js";
 import { createAuthoredSourceRuntimeCompiledArtifactsSource } from "#internal/application/runtime-compiled-artifacts-source.js";
 import {
   activateDevelopmentRuntimeArtifactsSnapshot,
   stageDevelopmentRuntimeArtifactsSnapshot,
 } from "#internal/nitro/dev-runtime-artifacts.js";
-import { resolveRuntimeCompilerArtifactPaths } from "#runtime/loaders/artifact-paths.js";
 import type { PreparedApplicationHost } from "#internal/nitro/host/types.js";
 
 /**
@@ -38,23 +37,9 @@ export async function prepareApplicationHost(
     options.dev === true
       ? await stageDevelopmentRuntimeArtifactsSnapshot(compileResult)
       : undefined;
-  const runtimeArtifactsRoot =
-    runtimeArtifactsSnapshot === undefined
-      ? compileResult.project.appRoot
-      : runtimeArtifactsSnapshot.runtimeAppRoot;
-  const runtimeArtifactPaths = resolveRuntimeCompilerArtifactPaths(runtimeArtifactsRoot);
-  const runtimeCompileResult =
-    options.dev === true
-      ? {
-          ...compileResult,
-          manifest: JSON.parse(
-            await readFile(runtimeArtifactPaths.compiledManifestPath, "utf8"),
-          ) as CompiledAgentManifest,
-        }
-      : compileResult;
   const compiledArtifacts = await writeCompiledArtifactsFiles({
-    compileResult: runtimeCompileResult,
-    outDir: runtimeArtifactPaths.compileDirectoryPath,
+    compileResult,
+    outDir: resolveApplicationHostArtifactsDirectory(compileResult.project.appRoot),
   });
   if (runtimeArtifactsSnapshot !== undefined) {
     await activateDevelopmentRuntimeArtifactsSnapshot({

packages/eve/test/scenarios/dev-server.scenario.test.ts

@@ -1,10 +1,18 @@
 import { spawn, type ChildProcessByStdio } from "node:child_process";
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { Readable } from "node:stream";
 
 import { describe, expect, it } from "vitest";
 
 import { EVE_HEALTH_ROUTE_PATH } from "../../src/protocol/routes.js";
+import {
+  pruneDevelopmentRuntimeArtifactsSnapshots,
+  readDevelopmentRuntimeArtifactsSnapshotRoot,
+  resolveDevelopmentRuntimeArtifactsPointerPath,
+} from "../../src/internal/nitro/dev-runtime-artifacts.js";
+import { STRUCTURAL_RELOAD_LOG_LINE } from "../../src/internal/nitro/host/dev-watcher-log.js";
 import { WEATHER_AGENT_DESCRIPTOR } from "../../src/internal/testing/scenario-apps/weather-agent.js";
 import {
   type ScenarioAppDescriptor,
@@ -59,6 +67,7 @@ function hasUnsupportedWindowsEsmImport(text: string): boolean {
 function hasKnownDevBundlingFailure(text: string): boolean {
   return (
     hasUnsupportedWindowsEsmImport(text) ||
+    text.includes("UNRESOLVED_IMPORT") ||
     (text.includes("ERR_MODULE_NOT_FOUND") && text.includes("authored-module-map-loader"))
   );
 }
@@ -75,6 +84,21 @@ async function wait(ms: number): Promise<void> {
   });
 }
 
+async function waitForCondition(
+  condition: () => boolean,
+  failureMessage: string,
+  timeoutMs: number = 60_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (!condition()) {
+    if (Date.now() >= deadline) {
+      throw new Error(failureMessage);
+    }
+    await wait(100);
+  }
+}
+
 async function waitForServerUrl(input: {
   readonly child: ChildProcessByStdio<null, Readable, Readable>;
   readonly getOutput: () => {
@@ -234,7 +258,7 @@ async function startEveDev(appRoot: string): Promise<RunningEveDev> {
 
 describe("eve dev server", () => {
   it(
-    "boots the packaged development server and completes a streamed turn",
+    "rebuilds after pruning its startup runtime snapshot and completes a streamed turn",
     async () => {
       const app = await scenarioApp(DEV_SERVER_AGENT_DESCRIPTOR);
       const server = await startEveDev(app.appRoot);
@@ -257,6 +281,45 @@ describe("eve dev server", () => {
           status: "ready",
         });
 
+        const pointerPath = resolveDevelopmentRuntimeArtifactsPointerPath(app.appRoot);
+        const startupRuntimeRoot = readDevelopmentRuntimeArtifactsSnapshotRoot(pointerPath);
+        if (startupRuntimeRoot === undefined) {
+          throw new Error("Expected eve dev to publish an initial runtime snapshot.");
+        }
+
+        await writeFile(
+          join(app.appRoot, "agent", "instructions.md"),
+          "Use the weather tool and answer with the current conditions.\n",
+        );
+        await waitForCondition(() => {
+          const currentRuntimeRoot = readDevelopmentRuntimeArtifactsSnapshotRoot(pointerPath);
+          return currentRuntimeRoot !== undefined && currentRuntimeRoot !== startupRuntimeRoot;
+        }, `Timed out waiting for authored HMR.\n\nstdout:\n${server.stdout()}\n\nstderr:\n${server.stderr()}`);
+
+        const authoredRuntimeRoot = readDevelopmentRuntimeArtifactsSnapshotRoot(pointerPath);
+        if (authoredRuntimeRoot === undefined) {
+          throw new Error("Expected authored HMR to publish a runtime snapshot.");
+        }
+
+        await pruneDevelopmentRuntimeArtifactsSnapshots({
+          appRoot: app.appRoot,
+          now: Date.now() + 1_000,
+          recentWindowMs: 0,
+          retainCount: 0,
+        });
+        expect(existsSync(startupRuntimeRoot)).toBe(false);
+
+        await writeFile(join(app.appRoot, ".env.local"), "EVE_SCENARIO_RELOAD=1\n");
+        await waitForCondition(
+          () => server.stdout().includes(STRUCTURAL_RELOAD_LOG_LINE),
+          `Timed out waiting for a structural Nitro reload.\n\nstdout:\n${server.stdout()}\n\nstderr:\n${server.stderr()}`,
+        );
+        await waitForCondition(() => {
+          const currentRuntimeRoot = readDevelopmentRuntimeArtifactsSnapshotRoot(pointerPath);
+          return currentRuntimeRoot !== undefined && currentRuntimeRoot !== authoredRuntimeRoot;
+        }, `Timed out waiting for the structural reload snapshot.\n\nstdout:\n${server.stdout()}\n\nstderr:\n${server.stderr()}`);
+        await wait(2_000);
+
         let messageResult: Awaited<ReturnType<typeof sendDevelopmentMessage>>;
         try {
           messageResult = await sendDevelopmentMessage({