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.mdnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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)}`;}