Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(compiler): prune stale authored-module cache bundles (#5258)

Andrew Barba84daf59a16ae
diff --git a/.changeset/prune-authored-module-cache.md b/.changeset/prune-authored-module-cache.md
new file mode 100644
index 000000000..0ffb71b8a
--- /dev/null
+++ b/.changeset/prune-authored-module-cache.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Compiles now prune `node_modules/.cache/eve/authored-modules` in the background, deleting cached bundles that no running eve process can still import, so the directory no longer grows without bound locally or in persisted Vercel build caches. Thanks @ryantbrown for reporting this in #847 and @kevludwig for reporting the Vercel build-cache impact.
diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.ts
index e15be2cfa..b54034286 100644
--- a/packages/eve/src/compiler/normalize-manifest.ts
+++ b/packages/eve/src/compiler/normalize-manifest.ts
@@ -7,6 +7,7 @@ import {
type AuthoredModuleGraph,
} from "#internal/authored-module-graph.js";
import { bindingMountId } from "#compiler/extension-mount-bindings.js";
+import { pruneAuthoredModuleCache } from "#internal/authored-module-cache.js";
import type { AgentSourceManifest } from "#discover/manifest.js";
import {
@@ -160,11 +161,14 @@ export async function compileAgentManifest(
const diagnosticsSummary = summarizeCompilerDiagnostics(diagnostics);
const subagents = withDiagnosticsSummary(root.descendants, diagnosticsSummary);
- return createCompiledAgentManifest({
+ const compiled = createCompiledAgentManifest({
...root.manifest,
diagnosticsSummary,
subagents,
});
+ // In the background, so pruning never delays a compile.
+ void pruneAuthoredModuleCache();
+ return compiled;
}
class AgentGraphCompiler {
diff --git a/packages/eve/src/internal/authored-module-cache.integration.test.ts b/packages/eve/src/internal/authored-module-cache.integration.test.ts
new file mode 100644
index 000000000..0a9eb6591
--- /dev/null
+++ b/packages/eve/src/internal/authored-module-cache.integration.test.ts
@@ -0,0 +1,79 @@
+import { readdir, realpath, utimes, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { compileAgentManifest } from "#compiler/normalize-manifest.js";
+import { discoverAgent } from "#discover/discover-agent.js";
+import { pruneAuthoredModuleCache } from "#internal/authored-module-cache.js";
+import { AUTHORED_MODULE_BUNDLE_DIRECTORY_PATH } from "#internal/authored-module-loader.js";
+import { useTemporaryAppRoots } from "#internal/testing/use-temporary-app-roots.js";
+
+const tool = (marker: string) =>
+ `export default { description: "Return ${marker}.", inputSchema: { type: "object" }, execute: () => "${marker}" };\n`;
+
+const HOUR_MS = 60 * 60 * 1000;
+
+describe("authored-module cache", () => {
+ const createAppRoot = useTemporaryAppRoots();
+
+ async function createCachedApp() {
+ const app = await createAppRoot("eve-authored-module-cache-", {
+ files: {
+ "agent/agent.ts": 'export default { model: "openai/gpt-5.4" };\n',
+ "agent/tools/edited.ts": tool("first"),
+ "agent/tools/unchanged.ts": tool("unchanged"),
+ },
+ });
+ const cacheDirectory = join(await realpath(app.appRoot), AUTHORED_MODULE_BUNDLE_DIRECTORY_PATH);
+ const listBundles = async () =>
+ new Set((await readdir(cacheDirectory)).filter((name) => name.endsWith(".mjs")));
+ const compile = async () => {
+ await compileAgentManifest(
+ (await discoverAgent({ agentRoot: app.agentRoot, appRoot: app.appRoot })).manifest,
+ );
+ // Compiles start pruning without waiting for it.
+ await pruneAuthoredModuleCache();
+ };
+
+ await compile();
+ const firstBundles = await listBundles();
+ // Last used an hour ago: by a process that has since finished, unless a lease says otherwise.
+ const hourAgo = new Date(Date.now() - HOUR_MS);
+ for (const name of firstBundles) await utimes(join(cacheDirectory, name), hourAgo, hourAgo);
+ await writeFile(join(app.agentRoot, "tools", "edited.ts"), tool("second"));
+ return { cacheDirectory, compile, firstBundles, listBundles };
+ }
+
+ it("removes bundles no running process can import and keeps the ones a compile reused", async () => {
+ const { compile, firstBundles, listBundles } = await createCachedApp();
+
+ await compile();
+
+ const secondBundles = await listBundles();
+ const reused = [...firstBundles].filter((name) => secondBundles.has(name));
+ expect(reused.length).toBeGreaterThan(0);
+ expect(reused.length).toBeLessThan(firstBundles.size);
+ expect(secondBundles.size).toBeGreaterThan(reused.length);
+ });
+
+ it("keeps bundles while an earlier process that may import them is still running", async () => {
+ const { cacheDirectory, compile, firstBundles, listBundles } = await createCachedApp();
+ const leasePath = join(cacheDirectory, ".leases", "earlier-process.json");
+ const lease = { host: hostname(), pid: process.pid, since: Date.now() - 2 * HOUR_MS };
+ await writeFile(leasePath, JSON.stringify(lease));
+
+ await compile();
+ const whileRunning = await listBundles();
+ expect([...firstBundles].every((name) => whileRunning.has(name))).toBe(true);
+
+ // A lease nobody refreshed for longer than the heartbeat expiry belongs to a process that
+ // is gone, even though this pid and host still look alive.
+ const staleRefresh = new Date(Date.now() - HOUR_MS);
+ await utimes(leasePath, staleRefresh, staleRefresh);
+ await pruneAuthoredModuleCache();
+ const afterwards = await listBundles();
+ expect([...firstBundles].some((name) => !afterwards.has(name))).toBe(true);
+ });
+});
diff --git a/packages/eve/src/internal/authored-module-cache.ts b/packages/eve/src/internal/authored-module-cache.ts
new file mode 100644
index 000000000..021b06c33
--- /dev/null
+++ b/packages/eve/src/internal/authored-module-cache.ts
@@ -0,0 +1,213 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+
+// Cache file names derive from bundle output, so no process imports a file another process
+// wrote: each one bundles, writes or touches the file, then imports it, possibly lazily much
+// later. A file is therefore in use only while a process that touched it is still running.
+// Each process registers a lease before its first touch, so every file it uses is newer than
+// its lease, and a file older than every live lease cannot be in use.
+const LEASE_DIRECTORY_NAME = ".leases";
+// Some file systems store mtimes at 1–2 s precision, which can round a touch below its lease.
+const MTIME_PRECISION_MARGIN_MS = 60_000;
+// Live processes refresh their leases, so a lease nobody refreshed belongs to a process that
+// is gone, even when its pid was reused or it ran on another host or in another container.
+const LEASE_HEARTBEAT_MS = 60_000;
+const LEASE_EXPIRY_MS = 10 * 60_000;
+
+interface CacheLease {
+ readonly host: string;
+ readonly pid: number;
+ readonly since: number;
+}
+
+const leases = new Map<string, { readonly path: string; readonly lease: CacheLease }>();
+let heartbeat: NodeJS.Timeout | undefined;
+let pruning: Promise<void> | undefined;
+
+/**
+ * Writes a content-addressed bundle into the authored-module cache, or marks an
+ * existing one as used by this process so {@link pruneAuthoredModuleCache} keeps it.
+ */
+export function writeAuthoredModuleCacheFile(
+ directoryPath: string,
+ fileName: string,
+ code: string,
+): string {
+ registerLease(directoryPath);
+ const filePath = join(directoryPath, fileName);
+ // Touch first and write only when missing, so a file this process reuses is never older
+ // than its lease, even if another process removes it in between.
+ try {
+ const now = new Date();
+ utimesSync(filePath, now, now);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+ // Not ours to touch: replace it with a fresh copy so it stays protected.
+ replaceFile(filePath, code);
+ return filePath;
+ }
+ try {
+ writeFileSync(filePath, code);
+ } catch (writeError) {
+ if ((writeError as NodeJS.ErrnoException).code !== "ENOENT") throw writeError;
+ // The cache directory was removed while this process ran.
+ leases.delete(directoryPath);
+ registerLease(directoryPath);
+ writeFileSync(filePath, code);
+ }
+ }
+ return filePath;
+}
+
+/**
+ * Removes cached bundles that no running process can still import. Runs in the
+ * background: callers should not await it, and it never rejects.
+ */
+export function pruneAuthoredModuleCache(): Promise<void> {
+ pruning ??= pruneLeasedDirectories().finally(() => {
+ pruning = undefined;
+ });
+ return pruning;
+}
+
+function registerLease(directoryPath: string): void {
+ if (leases.has(directoryPath)) return;
+ const lease: CacheLease = { host: hostname(), pid: process.pid, since: Date.now() };
+ const path = join(directoryPath, LEASE_DIRECTORY_NAME, `${process.pid}-${randomUUID()}.json`);
+ leases.set(directoryPath, { path, lease });
+ try {
+ writeLease(path, lease);
+ } catch {
+ // An unwritable cache still serves existing bundles, and nobody can prune it either.
+ }
+ if (heartbeat === undefined) {
+ heartbeat = setInterval(refreshLeases, LEASE_HEARTBEAT_MS).unref();
+ process.once("exit", releaseLeases);
+ }
+}
+
+function writeLease(path: string, lease: CacheLease): void {
+ mkdirSync(join(path, ".."), { recursive: true });
+ writeFileSync(path, JSON.stringify(lease));
+}
+
+function refreshLeases(): void {
+ const now = new Date();
+ for (const { path, lease } of leases.values()) {
+ try {
+ utimesSync(path, now, now);
+ } catch {
+ try {
+ writeLease(path, lease);
+ } catch {}
+ }
+ }
+}
+
+function releaseLeases(): void {
+ for (const { path } of leases.values()) {
+ try {
+ unlinkSync(path);
+ } catch {}
+ }
+}
+
+function replaceFile(filePath: string, code: string): void {
+ const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+ try {
+ writeFileSync(temporaryPath, code);
+ renameSync(temporaryPath, filePath);
+ } catch {
+ try {
+ unlinkSync(temporaryPath);
+ } catch {}
+ }
+}
+
+async function pruneLeasedDirectories(): Promise<void> {
+ for (const [directoryPath, { path, lease }] of leases) {
+ try {
+ await pruneDirectory(directoryPath, path, lease.since);
+ } catch {}
+ }
+}
+
+async function pruneDirectory(
+ directoryPath: string,
+ ownLeasePath: string,
+ ownLeaseSince: number,
+): Promise<void> {
+ const oldestLease = await findOldestLiveLease(
+ join(directoryPath, LEASE_DIRECTORY_NAME),
+ ownLeasePath,
+ ownLeaseSince,
+ );
+ const cutoff = oldestLease - MTIME_PRECISION_MARGIN_MS;
+ for (const fileName of await readdir(directoryPath)) {
+ if (!fileName.endsWith(".mjs") && !fileName.endsWith(".tmp")) continue;
+ const filePath = join(directoryPath, fileName);
+ // Checked and removed back to back, so a concurrent touch by another process has only
+ // microseconds to land in between.
+ try {
+ if (statSync(filePath).mtimeMs < cutoff) unlinkSync(filePath);
+ } catch {}
+ await yieldToEventLoop();
+ }
+}
+
+async function findOldestLiveLease(
+ leaseDirectory: string,
+ ownLeasePath: string,
+ ownLeaseSince: number,
+): Promise<number> {
+ let oldest = ownLeaseSince;
+ for (const fileName of await readdir(leaseDirectory).catch(() => [])) {
+ const leasePath = join(leaseDirectory, fileName);
+ if (leasePath === ownLeasePath) continue;
+ const since = await readLiveLeaseSince(leasePath);
+ if (since === undefined) {
+ await unlink(leasePath).catch(() => undefined);
+ } else {
+ oldest = Math.min(oldest, since);
+ }
+ }
+ return oldest;
+}
+
+/** The lease's start time while its process may still run, or `undefined` once it is gone. */
+async function readLiveLeaseSince(leasePath: string): Promise<number | undefined> {
+ const refreshedAt = (await stat(leasePath).catch(() => undefined))?.mtimeMs;
+ if (refreshedAt === undefined || Date.now() - refreshedAt > LEASE_EXPIRY_MS) return undefined;
+ const lease = parseLease(await readFile(leasePath, "utf8").catch(() => undefined));
+ // Still being written: its process registered just now.
+ if (lease === undefined) return refreshedAt;
+ if (lease.host === hostname() && !isRunning(lease.pid)) return undefined;
+ return Math.min(lease.since, refreshedAt);
+}
+
+function parseLease(text: string | undefined): CacheLease | undefined {
+ if (text === undefined) return undefined;
+ try {
+ const value = JSON.parse(text) as Partial<CacheLease>;
+ return typeof value.host === "string" &&
+ typeof value.pid === "number" &&
+ typeof value.since === "number"
+ ? (value as CacheLease)
+ : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+function isRunning(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code === "EPERM";
+ }
+}
diff --git a/packages/eve/src/internal/authored-module-graph.ts b/packages/eve/src/internal/authored-module-graph.ts
index e4eafc17f..544340a5d 100644
--- a/packages/eve/src/internal/authored-module-graph.ts
+++ b/packages/eve/src/internal/authored-module-graph.ts
@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { join, resolve } from "node:path";
+import { writeAuthoredModuleCacheFile } from "#internal/authored-module-cache.js";
import {
createAuthoredModuleBuildOptions,
evaluatedBundleSourcemap,
@@ -95,12 +95,10 @@ async function writeAuthoredModuleGraph(
},
});
const directoryPath = join(packageRoot, AUTHORED_MODULE_BUNDLE_DIRECTORY_PATH);
- mkdirSync(directoryPath, { recursive: true });
for (const item of result.output) {
if (item.type !== "chunk") continue;
// File names carry a content hash, so an existing file already has this content.
- const filePath = join(directoryPath, item.fileName);
- if (!existsSync(filePath)) writeFileSync(filePath, item.code);
+ const filePath = writeAuthoredModuleCacheFile(directoryPath, item.fileName, item.code);
const modulePath = item.isEntry ? inputs.get(item.name) : undefined;
if (modulePath !== undefined) entryPaths.set(modulePath, filePath);
}
diff --git a/packages/eve/src/internal/authored-module-loader.ts b/packages/eve/src/internal/authored-module-loader.ts
index 61d1f9c1b..ae39dccc3 100644
--- a/packages/eve/src/internal/authored-module-loader.ts
+++ b/packages/eve/src/internal/authored-module-loader.ts
@@ -1,5 +1,5 @@
import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";
import { extensionOverridePaths } from "#compiler/extension-mount-bindings.js";
@@ -11,6 +11,7 @@ import {
evaluatedBundleSourcemap,
resolveAuthoredTsConfigPath,
} from "#internal/authored-module-build-options.js";
+import { writeAuthoredModuleCacheFile } from "#internal/authored-module-cache.js";
import type { AuthoredModuleGraph } from "#internal/authored-module-graph.js";
import {
createExtensionMountPlugin,
@@ -654,13 +655,7 @@ async function writeAuthoredModuleBundle(
resolveAuthoredPackageRoot(modulePath),
AUTHORED_MODULE_BUNDLE_DIRECTORY_PATH,
);
- const bundlePath = join(bundleDirectoryPath, `${bundleHash}.mjs`);
-
- if (!existsSync(bundlePath)) {
- mkdirSync(bundleDirectoryPath, { recursive: true });
- writeFileSync(bundlePath, code);
- }
-
+ const bundlePath = writeAuthoredModuleCacheFile(bundleDirectoryPath, `${bundleHash}.mjs`, code);
const instance = options.extension?.evaluationId ?? "";
return `${createFileImportSpecifier(bundlePath)}?v=${bundleHash}&instance=${encodeURIComponent(instance)}`;
}