Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Fix optional microsandbox auto-install reload (#85)

JJ Kasper7b8df64427c5
diff --git a/.changeset/quiet-masks-cheer.md b/.changeset/quiet-masks-cheer.md
new file mode 100644
index 000000000..09d0a7f93
--- /dev/null
+++ b/.changeset/quiet-masks-cheer.md
@@ -0,0 +1,7 @@
+---
+"eve": patch
+---
+
+Serialize optional sandbox engine auto-installs and reload newly installed engines through their package entrypoint file instead of retrying the cached bare specifier. This prevents first-run `eve dev` sessions from racing microsandbox installation or surfacing Node's stale same-process module-not-found result after Bun installs `microsandbox`.
+
+`eve init` also supports `EVE_INIT_PACKAGE_SPEC` so local tarball/source validation can make the generated project install the same eve build under test instead of resolving the published semver range from the registry.
diff --git a/packages/eve/src/cli/commands/init.integration.test.ts b/packages/eve/src/cli/commands/init.integration.test.ts
index 7774fc80e..caaeef0e5 100644
--- a/packages/eve/src/cli/commands/init.integration.test.ts
+++ b/packages/eve/src/cli/commands/init.integration.test.ts
@@ -19,7 +19,12 @@ import {
import { pathExists } from "#setup/path-exists.js";
import type { GitInitResult } from "./init-git.js";
-import { runInitCommand, type InitCliLogger, type InitCommandDependencies } from "./init.js";
+import {
+ EVE_INIT_PACKAGE_SPEC_ENV,
+ runInitCommand,
+ type InitCliLogger,
+ type InitCommandDependencies,
+} from "./init.js";
const BASE_VERSIONS = {
aiPackageVersion: "7.0.0",
@@ -64,8 +69,13 @@ function dependencies(
tryInitializeGit: ReturnType<typeof vi.fn<InitCommandDependencies["tryInitializeGit"]>>;
} {
return {
- addAgentToProject: (options: AddAgentToProjectOptions) =>
- addAgentToProject({ ...BASE_VERSIONS, ...options }),
+ addAgentToProject: (options: AddAgentToProjectOptions) => {
+ const merged = { ...BASE_VERSIONS, ...options };
+ if (options.evePackage === undefined) {
+ merged.evePackage = BASE_VERSIONS.evePackage;
+ }
+ return addAgentToProject(merged);
+ },
// Stubbed to "no visible manager" so assertions do not depend on which
// manager launched the test runner itself.
detectInvokingPackageManager: vi.fn(() => undefined),
@@ -73,8 +83,13 @@ function dependencies(
// launched by a coding agent, and these tests assert the human path.
isCodingAgentLaunch: vi.fn(async () => false),
detectPackageManager,
- scaffoldBaseProject: (options: ScaffoldBaseProjectOptions) =>
- scaffoldBaseProject({ ...BASE_VERSIONS, ...options }),
+ scaffoldBaseProject: (options: ScaffoldBaseProjectOptions) => {
+ const merged = { ...BASE_VERSIONS, ...options };
+ if (options.evePackage === undefined) {
+ merged.evePackage = BASE_VERSIONS.evePackage;
+ }
+ return scaffoldBaseProject(merged);
+ },
ensureChannel: (options: EnsureChannelOptions) =>
ensureChannel({
...options,
@@ -104,6 +119,7 @@ async function createHostProject(
afterEach(() => {
vi.restoreAllMocks();
+ vi.unstubAllEnvs();
});
describe("runInitCommand", () => {
@@ -159,6 +175,35 @@ describe("runInitCommand", () => {
expect(output.messages[3]).toContain("$ eve dev --input /model");
});
+ it("uses an explicit init package spec for fresh project scaffolds", async () => {
+ const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-package-spec-"));
+ const output = logger();
+ const deps = dependencies();
+ vi.stubEnv(EVE_INIT_PACKAGE_SPEC_ENV, "file:/tmp/eve-0.11.5.tgz");
+
+ await runInitCommand(output, parentDirectory, "my-agent", {}, deps);
+
+ const packageJson = JSON.parse(
+ await readFile(join(parentDirectory, "my-agent", "package.json"), "utf8"),
+ ) as { dependencies: Record<string, string> };
+ expect(packageJson.dependencies.eve).toBe("file:/tmp/eve-0.11.5.tgz");
+ });
+
+ it("uses an explicit init package spec when adding to an existing project", async () => {
+ const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-existing-package-spec-"));
+ const projectRoot = await createHostProject(parentDirectory);
+ const output = logger();
+ const deps = dependencies();
+ vi.stubEnv(EVE_INIT_PACKAGE_SPEC_ENV, "file:/tmp/eve-0.11.5.tgz");
+
+ await runInitCommand(output, parentDirectory, "host-app", {}, deps);
+
+ const packageJson = JSON.parse(await readFile(join(projectRoot, "package.json"), "utf8")) as {
+ dependencies: Record<string, string>;
+ };
+ expect(packageJson.dependencies.eve).toBe("file:/tmp/eve-0.11.5.tgz");
+ });
+
it.each([undefined, ".", "./"] as const)(
"scaffolds the current empty directory when target is %j",
async (target) => {
diff --git a/packages/eve/src/cli/commands/init.ts b/packages/eve/src/cli/commands/init.ts
index cf1792d71..b2ea4f1cb 100644
--- a/packages/eve/src/cli/commands/init.ts
+++ b/packages/eve/src/cli/commands/init.ts
@@ -22,6 +22,10 @@ import {
} from "#setup/primitives/index.js";
import { addAgentToProject } from "#setup/scaffold/create/add-to-project.js";
import { ensureChannel, scaffoldBaseProject } from "#setup/scaffold/index.js";
+import {
+ DEFAULT_EVE_PACKAGE_CONTRACT,
+ type EvePackageContract,
+} from "#setup/scaffold/create/project.js";
import { initAgentDevHandoff } from "./agent-instructions.js";
import { tryInitializeGit } from "./init-git.js";
@@ -62,6 +66,7 @@ const defaultDependencies: InitCommandDependencies = {
const CURRENT_DIRECTORY_PROJECT_NAME = ".";
const ALLOWED_CREATE_IN_PLACE_ENTRIES = new Set([".DS_Store", ".git", ".gitkeep", ".hg"]);
+export const EVE_INIT_PACKAGE_SPEC_ENV = "EVE_INIT_PACKAGE_SPEC";
/** Resolves `target` to an existing directory, or undefined for name mode. */
async function resolveTargetDirectory(
@@ -105,6 +110,7 @@ async function addToExistingProject(
targetPath: string,
options: InitCommandOptions,
dependencies: InitCommandDependencies,
+ evePackage: EvePackageContract | undefined,
): Promise<{ packageManager: PackageManagerKind; nodeEngineOverride?: NodeEngineOverride }> {
if (options.channelWebNextjs === true) {
throw new Error(
@@ -118,6 +124,7 @@ async function addToExistingProject(
projectRoot: targetPath,
model: DEFAULT_AGENT_MODEL_ID,
packageManager: manager.kind,
+ evePackage,
});
return {
packageManager: manager.kind,
@@ -146,6 +153,7 @@ async function scaffoldProject(
packageManager: PackageManagerKind,
options: InitCommandOptions,
dependencies: InitCommandDependencies,
+ evePackage: EvePackageContract | undefined,
): Promise<string> {
const parentPath = resolve(parentDirectory);
const createInPlace = projectName === CURRENT_DIRECTORY_PROJECT_NAME;
@@ -159,12 +167,14 @@ async function scaffoldProject(
const stagingDirectory = await mkdtemp(join(parentPath, ".eve-init-"));
try {
const stagedProjectName = createInPlace ? basename(projectPath) : projectName;
- const stagedProjectPath = await dependencies.scaffoldBaseProject({
+ const scaffoldOptions = {
projectName: stagedProjectName,
model: DEFAULT_AGENT_MODEL_ID,
- packageManager,
+ evePackage,
targetDirectory: stagingDirectory,
- });
+ packageManager,
+ };
+ const stagedProjectPath = await dependencies.scaffoldBaseProject(scaffoldOptions);
if (options.channelWebNextjs === true) {
await dependencies.ensureChannel({
@@ -234,6 +244,7 @@ export async function runInitCommand(
): Promise<void> {
const agentLaunched = await dependencies.isCodingAgentLaunch();
const rawTarget = target ?? CURRENT_DIRECTORY_PROJECT_NAME;
+ const evePackage = resolveInitEvePackageOverride();
const currentDirectoryTarget = isCurrentDirectoryTarget(rawTarget);
const existingDirectory = currentDirectoryTarget
? (await pathExists(join(resolve(parentDirectory), "package.json")))
@@ -261,11 +272,17 @@ export async function runInitCommand(
packageManager,
options,
dependencies,
+ evePackage,
);
freshScaffold = true;
logger.log(`${pc.green("✓")} Created an ${EVE_WORDMARK} agent in ${pc.bold(projectPath)}`);
} else {
- const addition = await addToExistingProject(existingDirectory, options, dependencies);
+ const addition = await addToExistingProject(
+ existingDirectory,
+ options,
+ dependencies,
+ evePackage,
+ );
packageManager = addition.packageManager;
projectPath = existingDirectory;
freshScaffold = false;
@@ -329,3 +346,15 @@ export async function runInitCommand(
throw new Error(`Development server exited unsuccessfully in "${projectPath}".`);
}
}
+
+function resolveInitEvePackageOverride(): EvePackageContract | undefined {
+ const spec = process.env[EVE_INIT_PACKAGE_SPEC_ENV]?.trim();
+ if (spec === undefined || spec.length === 0) {
+ return undefined;
+ }
+
+ return {
+ nodeEngine: DEFAULT_EVE_PACKAGE_CONTRACT.nodeEngine,
+ version: spec,
+ };
+}
diff --git a/packages/eve/src/internal/application/optional-package-install.test.ts b/packages/eve/src/internal/application/optional-package-install.test.ts
index f03a52145..694694af0 100644
--- a/packages/eve/src/internal/application/optional-package-install.test.ts
+++ b/packages/eve/src/internal/application/optional-package-install.test.ts
@@ -3,7 +3,11 @@ import { existsSync } from "node:fs";
import { PassThrough } from "node:stream";
import { beforeEach, describe, expect, it, vi } from "vitest";
-import { installPackageIntoProject } from "#internal/application/optional-package-install.js";
+import {
+ EVE_DEV_ENV_FLAG,
+ installPackageIntoProject,
+ loadOptionalEnginePackage,
+} from "#internal/application/optional-package-install.js";
vi.mock("node:child_process", async (importOriginal) => ({
...(await importOriginal<typeof import("node:child_process")>()),
@@ -15,6 +19,16 @@ vi.mock("node:fs", async (importOriginal) => ({
existsSync: vi.fn(() => false),
}));
+vi.mock("node:fs/promises", () => ({
+ mkdir: vi.fn(async () => {}),
+ readFile: vi.fn(async () => "{}"),
+ rm: vi.fn(async () => {}),
+ stat: vi.fn(async () => {
+ throw Object.assign(new Error("not found"), { code: "ENOENT" });
+ }),
+ writeFile: vi.fn(async () => {}),
+}));
+
const mockedExistsSync = vi.mocked(existsSync);
const mockedSpawn = vi.mocked(spawn);
@@ -37,6 +51,7 @@ function mockProcessPlatform(platform: NodeJS.Platform): () => void {
beforeEach(() => {
vi.clearAllMocks();
+ vi.unstubAllEnvs();
mockedExistsSync.mockReturnValue(false);
mockedSpawn.mockImplementation(() => {
const child = createMockChildProcess();
@@ -45,6 +60,96 @@ beforeEach(() => {
});
});
+describe("loadOptionalEnginePackage", () => {
+ it("retries loading the package after auto-install finishes", async () => {
+ const appRoot = "/repo/retry-app";
+ vi.stubEnv(EVE_DEV_ENV_FLAG, "1");
+ let installed = false;
+ mockedSpawn.mockImplementationOnce(() => {
+ const child = createMockChildProcess();
+ queueMicrotask(() => {
+ installed = true;
+ child.emit("close", 0);
+ });
+ return child;
+ });
+ const loadedModule = { ok: true };
+ const importModule = vi.fn(async () => {
+ throw new Error("Cannot find module 'microsandbox'");
+ });
+ const importInstalledModule = vi.fn(async () => {
+ if (!installed) throw new Error("Cannot find module 'microsandbox'");
+ return loadedModule;
+ });
+
+ await expect(
+ loadOptionalEnginePackage({
+ appRoot,
+ autoInstall: true,
+ importInstalledModule,
+ importModule,
+ missingMessage: "missing microsandbox",
+ packageName: "microsandbox",
+ }),
+ ).resolves.toBe(loadedModule);
+
+ expect(mockedSpawn).toHaveBeenCalledTimes(1);
+ expect(importModule).toHaveBeenCalledTimes(1);
+ expect(importInstalledModule).toHaveBeenCalledTimes(2);
+ });
+
+ it("coalesces concurrent auto-installs for the same project package", async () => {
+ const appRoot = "/repo/concurrent-app";
+ vi.stubEnv(EVE_DEV_ENV_FLAG, "1");
+ let installed = false;
+ let installChild: ReturnType<typeof createMockChildProcess> | undefined;
+ mockedSpawn.mockImplementationOnce(() => {
+ installChild = createMockChildProcess();
+ return installChild;
+ });
+ const loadedModule = { ok: true };
+ const importModule = vi.fn(async () => {
+ throw new Error("Cannot find module 'microsandbox'");
+ });
+ const importInstalledModule = vi.fn(async () => {
+ if (!installed) throw new Error("Cannot find module 'microsandbox'");
+ return loadedModule;
+ });
+
+ const first = loadOptionalEnginePackage({
+ appRoot,
+ autoInstall: true,
+ importInstalledModule,
+ importModule,
+ missingMessage: "missing microsandbox",
+ packageName: "microsandbox",
+ });
+ await flushMicrotasks();
+ const second = loadOptionalEnginePackage({
+ appRoot,
+ autoInstall: true,
+ importInstalledModule,
+ importModule,
+ missingMessage: "missing microsandbox",
+ packageName: "microsandbox",
+ });
+ await flushMicrotasks();
+
+ expect(mockedSpawn).toHaveBeenCalledTimes(1);
+ installed = true;
+ installChild?.emit("close", 0);
+
+ await expect(Promise.all([first, second])).resolves.toEqual([loadedModule, loadedModule]);
+ expect(mockedSpawn).toHaveBeenCalledTimes(1);
+ });
+});
+
+async function flushMicrotasks(): Promise<void> {
+ for (let i = 0; i < 5; i += 1) {
+ await Promise.resolve();
+ }
+}
+
describe("installPackageIntoProject", () => {
it("uses the project's package manager", async () => {
mockedExistsSync.mockImplementation((path) => path === "/repo/pnpm-lock.yaml");
diff --git a/packages/eve/src/internal/application/optional-package-install.ts b/packages/eve/src/internal/application/optional-package-install.ts
index c3fceae0c..40204ceed 100644
--- a/packages/eve/src/internal/application/optional-package-install.ts
+++ b/packages/eve/src/internal/application/optional-package-install.ts
@@ -1,6 +1,8 @@
import { spawn } from "node:child_process";
import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
/**
* Environment flag set by `eve dev` so runtime code can distinguish the
@@ -56,6 +58,11 @@ const INSTALL_ARGUMENTS: Record<ProjectPackageManager, readonly string[]> = {
pnpm: ["add", "-D"],
yarn: ["add", "-D"],
};
+const OPTIONAL_PACKAGE_LOCK_POLL_MS = 250;
+const OPTIONAL_PACKAGE_LOCK_TIMEOUT_MS = 10 * 60 * 1000;
+const OPTIONAL_PACKAGE_STALE_LOCK_MS = 30 * 60 * 1000;
+
+const pendingOptionalPackageInstalls = new Map<string, Promise<void>>();
/**
* Installs one package into the application as a devDependency using
@@ -109,6 +116,7 @@ export async function installPackageIntoProject(input: {
export async function loadOptionalEnginePackage<T>(input: {
readonly appRoot: string;
readonly autoInstall: boolean;
+ readonly importInstalledModule?: () => Promise<T>;
readonly importModule: () => Promise<T>;
readonly missingMessage: string;
readonly packageName: string;
@@ -120,10 +128,25 @@ export async function loadOptionalEnginePackage<T>(input: {
throw new Error(input.missingMessage, { cause: importError });
}
+ const importInstalledModule =
+ input.importInstalledModule ??
+ (async () =>
+ await importInstalledEnginePackage<T>({
+ appRoot: input.appRoot,
+ packageName: input.packageName,
+ }));
+
try {
- await installPackageIntoProject({
- appRoot: input.appRoot,
- packageName: input.packageName,
+ await withOptionalPackageInstallLock(input, async () => {
+ try {
+ await importInstalledModule();
+ return;
+ } catch {}
+
+ await installPackageIntoProject({
+ appRoot: input.appRoot,
+ packageName: input.packageName,
+ });
});
} catch (installError) {
throw new Error(
@@ -132,8 +155,156 @@ export async function loadOptionalEnginePackage<T>(input: {
);
}
- return await input.importModule();
+ return await importInstalledModule();
+ }
+}
+
+async function importInstalledEnginePackage<T>(input: {
+ readonly appRoot: string;
+ readonly packageName: string;
+}): Promise<T> {
+ const packageRoot = join(input.appRoot, "node_modules", ...input.packageName.split("/"));
+ const packageJsonPath = join(packageRoot, "package.json");
+ const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8")) as {
+ readonly exports?: unknown;
+ readonly main?: unknown;
+ readonly module?: unknown;
+ };
+ const entry = resolvePackageEntryPoint(packageJson);
+ if (entry.startsWith("/")) {
+ throw new Error(`Invalid absolute entrypoint for optional package "${input.packageName}".`);
+ }
+ return (await import(pathToFileURL(join(packageRoot, entry)).href)) as T;
+}
+
+function resolvePackageEntryPoint(packageJson: {
+ readonly exports?: unknown;
+ readonly main?: unknown;
+ readonly module?: unknown;
+}): string {
+ const dotExport = readDotExport(packageJson.exports);
+ if (dotExport !== undefined) {
+ return dotExport;
+ }
+ if (typeof packageJson.module === "string" && packageJson.module.length > 0) {
+ return packageJson.module;
+ }
+ if (typeof packageJson.main === "string" && packageJson.main.length > 0) {
+ return packageJson.main;
+ }
+ return "index.js";
+}
+
+function readDotExport(exportsValue: unknown): string | undefined {
+ if (typeof exportsValue === "string" && exportsValue.length > 0) {
+ return exportsValue;
+ }
+ if (typeof exportsValue !== "object" || exportsValue === null) {
+ return undefined;
+ }
+
+ const dotExport =
+ "." in exportsValue ? (exportsValue as { readonly ".": unknown })["."] : exportsValue;
+ if (typeof dotExport === "string" && dotExport.length > 0) {
+ return dotExport;
+ }
+ if (typeof dotExport !== "object" || dotExport === null) {
+ return undefined;
+ }
+
+ const conditional = dotExport as { readonly import?: unknown; readonly default?: unknown };
+ if (typeof conditional.import === "string" && conditional.import.length > 0) {
+ return conditional.import;
+ }
+ if (typeof conditional.default === "string" && conditional.default.length > 0) {
+ return conditional.default;
+ }
+ return undefined;
+}
+
+async function withOptionalPackageInstallLock(
+ input: { readonly appRoot: string; readonly packageName: string },
+ callback: () => Promise<void>,
+): Promise<void> {
+ const lockKey = `${input.appRoot}:${input.packageName}`;
+ const pending = pendingOptionalPackageInstalls.get(lockKey);
+ if (pending !== undefined) {
+ await pending;
+ return;
+ }
+
+ const promise = withOptionalPackageInstallFileLock(input, callback).finally(() => {
+ pendingOptionalPackageInstalls.delete(lockKey);
+ });
+ pendingOptionalPackageInstalls.set(lockKey, promise);
+ await promise;
+}
+
+async function withOptionalPackageInstallFileLock(
+ input: { readonly appRoot: string; readonly packageName: string },
+ callback: () => Promise<void>,
+): Promise<void> {
+ const lockPath = join(
+ input.appRoot,
+ ".eve",
+ "optional-package-locks",
+ `${sanitizeLockName(input.packageName)}.lock`,
+ );
+ await acquireLock(lockPath);
+ try {
+ await callback();
+ } finally {
+ await rm(lockPath, { force: true, recursive: true }).catch(() => {});
+ }
+}
+
+async function acquireLock(lockPath: string): Promise<void> {
+ const startedAt = Date.now();
+ for (;;) {
+ await mkdir(dirname(lockPath), { recursive: true });
+ try {
+ await mkdir(lockPath);
+ await writeFile(
+ join(lockPath, "owner.json"),
+ `${JSON.stringify({ createdAt: new Date().toISOString(), pid: process.pid })}\n`,
+ );
+ return;
+ } catch (error) {
+ if (!isFileExistsError(error)) {
+ throw error;
+ }
+ await waitForExistingLock(lockPath, startedAt);
+ }
+ }
+}
+
+async function waitForExistingLock(lockPath: string, startedAt: number): Promise<void> {
+ const lockStat = await stat(lockPath).catch((error: unknown) => {
+ if (isNotFoundError(error)) {
+ return null;
+ }
+ throw error;
+ });
+ if (lockStat === null) {
+ return;
+ }
+
+ if (Date.now() - lockStat.mtimeMs > OPTIONAL_PACKAGE_STALE_LOCK_MS) {
+ await rm(lockPath, { force: true, recursive: true }).catch(() => {});
+ return;
+ }
+
+ if (Date.now() - startedAt > OPTIONAL_PACKAGE_LOCK_TIMEOUT_MS) {
+ throw new Error(
+ `Timed out waiting for optional package install lock "${lockPath}" after ${OPTIONAL_PACKAGE_LOCK_TIMEOUT_MS}ms.`,
+ );
}
+
+ await new Promise((resolve) => setTimeout(resolve, OPTIONAL_PACKAGE_LOCK_POLL_MS));
+}
+
+function sanitizeLockName(value: string): string {
+ return value.replaceAll(/[^a-zA-Z0-9._-]+/g, "-");
}
/**
@@ -144,6 +315,14 @@ function shouldSpawnPackageManagerWithShell(platform: NodeJS.Platform = process.
return platform === "win32";
}
+function isFileExistsError(error: unknown): boolean {
+ return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+
+function isNotFoundError(error: unknown): boolean {
+ return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
function toMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}