Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): resolve agent workspace topology (#1925)

OwenKephart56a36303aa27
diff --git a/packages/eve/src/cli/acp/command.ts b/packages/eve/src/cli/acp/command.ts
index e31e673c1..532853f78 100644
--- a/packages/eve/src/cli/acp/command.ts
+++ b/packages/eve/src/cli/acp/command.ts
@@ -58,7 +58,7 @@ export function registerAcpCommand(options: RegisterAcpCommandOptions): void {
)
.action(async (positionalUrl: string | undefined, commandOptions: AcpCliOptions) => {
const target = resolveDevelopmentUrlTarget(commandOptions, positionalUrl);
- loadDevelopmentEnvironmentFiles(options.applicationContext.root);
+ await loadDevelopmentEnvironmentFiles(options.applicationContext.root);
const lifecycle = installShutdownSignal({ exitAfterMs: FORCED_EXIT_BACKSTOP_MS });
if (target !== undefined) {
diff --git a/packages/eve/src/cli/application-root.test.ts b/packages/eve/src/cli/application-root.test.ts
index a6e751861..0eb0407db 100644
--- a/packages/eve/src/cli/application-root.test.ts
+++ b/packages/eve/src/cli/application-root.test.ts
@@ -52,6 +52,18 @@ describe("resolveCliApplicationRoot", () => {
await expect(resolveCliApplicationRoot("/repo/agent/tools", deps)).resolves.toBe("/repo");
});
+ it("finds a named agent workspace member", async () => {
+ const deps = dependencies(async () => ({
+ agentRoot: "/repo/agents/billing/agent",
+ appRoot: "/repo/agents/billing",
+ layout: "nested",
+ }));
+
+ await expect(findCliApplicationRoot("/repo/agents/billing/tools", deps)).resolves.toBe(
+ "/repo/agents/billing",
+ );
+ });
+
it("finds flat application roots", async () => {
const deps = dependencies(async () => ({
agentRoot: "/repo/agents/billing",
diff --git a/packages/eve/src/cli/commands/build.ts b/packages/eve/src/cli/commands/build.ts
index 37fe325fa..ead5dff85 100644
--- a/packages/eve/src/cli/commands/build.ts
+++ b/packages/eve/src/cli/commands/build.ts
@@ -40,7 +40,7 @@ export function registerBuildCommand(input: {
.action(async (options: BuildCliOptions) => {
const { loadDevelopmentEnvironmentFiles } = await import("#cli/dev/environment.js");
- loadDevelopmentEnvironmentFiles(input.applicationContext.root);
+ await loadDevelopmentEnvironmentFiles(input.applicationContext.root);
const buildHost =
input.buildHost ?? (await import("#internal/nitro/host.js")).buildApplication;
diff --git a/packages/eve/src/cli/dev/environment.ts b/packages/eve/src/cli/dev/environment.ts
index c8cc07838..6c93cca85 100644
--- a/packages/eve/src/cli/dev/environment.ts
+++ b/packages/eve/src/cli/dev/environment.ts
@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
import { join, resolve } from "node:path";
import { parseEnv } from "node:util";
+import { resolveEveProjectContext } from "#internal/project-context.js";
import { isObject } from "#shared/guards.js";
import { readProviderSelectionSync } from "#setup/provider-settings.js";
@@ -22,6 +23,7 @@ function isMissingEnvironmentFileError(error: unknown): error is NodeJS.ErrnoExc
}
interface DevelopmentEnvironmentLoader {
+ readonly environmentRoot: string;
reload(): void;
stageReload(): DevelopmentEnvironmentReload;
}
@@ -38,9 +40,9 @@ const developmentEnvironmentLoaders = new Map<string, DevelopmentEnvironmentLoad
* application root, ordered from highest to lowest precedence.
*/
export function getDevelopmentEnvironmentFilePaths(appRoot: string): string[] {
- const resolvedAppRoot = resolve(appRoot);
-
- return DEVELOPMENT_ENV_FILE_NAMES.map((fileName) => join(resolvedAppRoot, fileName));
+ return DEVELOPMENT_ENV_FILE_NAMES.map((fileName) =>
+ join(getDevelopmentEnvironmentLoader(appRoot).environmentRoot, fileName),
+ );
}
/**
@@ -51,8 +53,10 @@ export function getDevelopmentEnvironmentFilePaths(appRoot: string): string[] {
* precedence. Variables supplied by env files are refreshed on subsequent
* reloads so dev-mode file watching can pick up changed values.
*/
-export function loadDevelopmentEnvironmentFiles(appRoot: string): void {
- getDevelopmentEnvironmentLoader(appRoot).reload();
+export async function loadDevelopmentEnvironmentFiles(appRoot: string): Promise<void> {
+ const resolvedAppRoot = resolve(appRoot);
+ const context = await resolveEveProjectContext(resolvedAppRoot);
+ getDevelopmentEnvironmentLoader(resolvedAppRoot, context.environmentRoot).reload();
}
export function stageDevelopmentEnvironmentFiles(appRoot: string): DevelopmentEnvironmentReload {
@@ -63,7 +67,9 @@ export function readDevelopmentEnvironmentHostValues(
appRoot: string,
): Readonly<Record<string, string | null>> {
const values: Record<string, string | null> = {};
- const fileValues = readDevelopmentEnvironmentValues(resolve(appRoot));
+ const fileValues = readDevelopmentEnvironmentValues(
+ getDevelopmentEnvironmentLoader(appRoot).environmentRoot,
+ );
const hostKeys = new Set(fileValues.keys());
// Project selection can suppress a shell-only key. Keep that transition in
// the host fingerprint so the worker that inherited the key is replaced.
@@ -76,27 +82,33 @@ export function readDevelopmentEnvironmentHostValues(
return values;
}
-function getDevelopmentEnvironmentLoader(appRoot: string): DevelopmentEnvironmentLoader {
+function getDevelopmentEnvironmentLoader(
+ appRoot: string,
+ environmentRoot?: string,
+): DevelopmentEnvironmentLoader {
const resolvedAppRoot = resolve(appRoot);
const existingLoader = developmentEnvironmentLoaders.get(resolvedAppRoot);
+ if (existingLoader !== undefined && environmentRoot === undefined) return existingLoader;
- if (existingLoader !== undefined) {
- return existingLoader;
- }
+ const resolvedEnvironmentRoot = resolve(environmentRoot ?? resolvedAppRoot);
+ if (existingLoader?.environmentRoot === resolvedEnvironmentRoot) return existingLoader;
- const loader = createDevelopmentEnvironmentLoader(resolvedAppRoot);
+ const loader = createDevelopmentEnvironmentLoader(resolvedAppRoot, resolvedEnvironmentRoot);
developmentEnvironmentLoaders.set(resolvedAppRoot, loader);
return loader;
}
-function createDevelopmentEnvironmentLoader(appRoot: string): DevelopmentEnvironmentLoader {
+function createDevelopmentEnvironmentLoader(
+ appRoot: string,
+ environmentRoot: string,
+): DevelopmentEnvironmentLoader {
const protectedValues = new Map(Object.entries(process.env));
const protectedKeys = new Set(protectedValues.keys());
const managedValues = new Map<string, string>();
const stageReload = (): DevelopmentEnvironmentReload => {
const previousManagedValues = new Map(managedValues);
- const nextValues = readDevelopmentEnvironmentValues(appRoot);
+ const nextValues = readDevelopmentEnvironmentValues(environmentRoot);
const preferProjectOidc = applyProviderSelection(appRoot, nextValues);
const affectedKeys = new Set([...managedValues.keys(), ...nextValues.keys()]);
if (preferProjectOidc) {
@@ -143,6 +155,7 @@ function createDevelopmentEnvironmentLoader(appRoot: string): DevelopmentEnviron
};
return {
+ environmentRoot,
reload() {
stageReload().commit();
},
@@ -183,24 +196,18 @@ function applyDevelopmentEnvironmentValues(input: {
}
}
-function readDevelopmentEnvironmentValues(appRoot: string): Map<string, string> {
+function readDevelopmentEnvironmentValues(environmentRoot: string): Map<string, string> {
const values = new Map<string, string>();
for (const fileName of [...DEVELOPMENT_ENV_FILE_NAMES].reverse()) {
try {
- const parsedValues = parseEnv(readFileSync(join(appRoot, fileName), "utf8"));
+ const parsedValues = parseEnv(readFileSync(join(environmentRoot, fileName), "utf8"));
for (const [key, value] of Object.entries(parsedValues)) {
- if (value === undefined) {
- continue;
- }
-
- values.set(key, value);
+ if (value !== undefined) values.set(key, value);
}
} catch (error) {
- if (!isMissingEnvironmentFileError(error)) {
- throw error;
- }
+ if (!isMissingEnvironmentFileError(error)) throw error;
}
}
diff --git a/packages/eve/src/cli/dev/local-server-process.test.ts b/packages/eve/src/cli/dev/local-server-process.test.ts
index 4b50075e4..3ec368781 100644
--- a/packages/eve/src/cli/dev/local-server-process.test.ts
+++ b/packages/eve/src/cli/dev/local-server-process.test.ts
@@ -32,6 +32,7 @@ describe("createDevelopmentServer", () => {
beforeEach(() => {
child = new FakeChild();
mocks.fork.mockReturnValue(child);
+ mocks.loadEnv.mockResolvedValue(undefined);
});
it("finishes the close escalation inside the CLI forced-exit backstop", () => {
@@ -41,6 +42,7 @@ describe("createDevelopmentServer", () => {
it("starts and hands cleanup to the child", async () => {
const server = createDevelopmentServer("/tmp/app", { port: 2000 });
const started = server.start();
+ await vi.waitFor(() => expect(mocks.fork).toHaveBeenCalled());
child.emit("message", {
type: "started",
handle: { kind: "started", appRoot: "/tmp/app", url: "http://127.0.0.1:2000" },
@@ -61,6 +63,7 @@ describe("createDevelopmentServer", () => {
try {
const server = createDevelopmentServer("/tmp/app", { output: "stderr" });
const started = server.start();
+ await vi.waitFor(() => expect(mocks.fork).toHaveBeenCalled());
child.stdout.write("server output");
child.emit("message", {
type: "started",
@@ -85,6 +88,7 @@ describe("createDevelopmentServer", () => {
try {
const server = createDevelopmentServer("/tmp/app");
const started = server.start();
+ await vi.advanceTimersByTimeAsync(0);
child.emit("message", {
type: "started",
handle: { kind: "started", appRoot: "/tmp/app", url: "http://127.0.0.1:2000" },
@@ -118,6 +122,7 @@ describe("createDevelopmentServer", () => {
try {
const server = createDevelopmentServer("/tmp/app");
const started = server.start();
+ await vi.advanceTimersByTimeAsync(0);
child.emit("message", {
type: "started",
handle: { kind: "started", appRoot: "/tmp/app", url: "http://127.0.0.1:2000" },
diff --git a/packages/eve/src/cli/dev/local-server-process.ts b/packages/eve/src/cli/dev/local-server-process.ts
index 1fcca8483..dbf4d2b4b 100644
--- a/packages/eve/src/cli/dev/local-server-process.ts
+++ b/packages/eve/src/cli/dev/local-server-process.ts
@@ -83,10 +83,10 @@ export function createDevelopmentServer(
active.unref();
};
- const start = (): Promise<DevelopmentServerHandle> => {
+ const start = async (): Promise<DevelopmentServerHandle> => {
if (child !== undefined) throw new Error("DevelopmentServer.start() was already called.");
const shellEnvironment = { ...process.env };
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
process.env[EVE_DEV_ENV_FLAG] ??= "1";
const spawned = fork(
childPath,
diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.ts
index 65bdf4953..945d40fb6 100644
--- a/packages/eve/src/cli/dev/tui/runner.ts
+++ b/packages/eve/src/cli/dev/tui/runner.ts
@@ -1922,7 +1922,7 @@ export class EveTUIRunner {
const appRoot = this.#appRoot;
if (appRoot === undefined) return;
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
await this.#runtimeArtifacts?.refreshAfterSourceChange({});
const refreshedInfo = this.#replaceAgentInfo(await this.#readAgentInfo());
void this.#refreshSetupAttention(refreshedInfo);
diff --git a/packages/eve/src/cli/invoke/command.ts b/packages/eve/src/cli/invoke/command.ts
index d0c788893..df1377240 100644
--- a/packages/eve/src/cli/invoke/command.ts
+++ b/packages/eve/src/cli/invoke/command.ts
@@ -47,7 +47,7 @@ export function registerRuntimeInvokeCommand(input: {
...input,
deps: {
loadEnvironment: async (root) =>
- (await import("#cli/dev/environment.js")).loadDevelopmentEnvironmentFiles(root),
+ await (await import("#cli/dev/environment.js")).loadDevelopmentEnvironmentFiles(root),
runInvoke: async (invokeInput) =>
await (input.runtime.runInvoke ?? (await import("./invoke.js")).runInvoke)(invokeInput),
startHost: async (root) =>
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index 4ebf27537..a92063de9 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -218,7 +218,7 @@ function createCliProgram(
.description("Build the current package as an eve extension.")
.action(async () => {
const { loadDevelopmentEnvironmentFiles } = await import("#cli/dev/environment.js");
- loadDevelopmentEnvironmentFiles(applicationContext.root);
+ await loadDevelopmentEnvironmentFiles(applicationContext.root);
const { runExtensionBuildCommand } = await import("#cli/commands/extension-build.js");
await runExtensionBuildCommand(logger, applicationContext.root);
@@ -291,7 +291,7 @@ function createCliProgram(
.action(async (options: ProductionCliOptions) => {
const { loadDevelopmentEnvironmentFiles } = await import("#cli/dev/environment.js");
- loadDevelopmentEnvironmentFiles(applicationContext.root);
+ await loadDevelopmentEnvironmentFiles(applicationContext.root);
const startProductionHost = runtime.startProductionHost ?? (await loadStartProductionHost());
const server = await startProductionHost(applicationContext.root, {
@@ -401,7 +401,7 @@ function createCliProgram(
}
if (remoteServerUrl) {
const { loadDevelopmentEnvironmentFiles } = await import("#cli/dev/environment.js");
- loadDevelopmentEnvironmentFiles(applicationContext.root);
+ await loadDevelopmentEnvironmentFiles(applicationContext.root);
logger.log(
`↗ ${existingLocalDevelopmentServer ? "local" : "remote"} mode targeting ${theme.info(new URL(remoteServerUrl).host)}`,
);
diff --git a/packages/eve/src/discover/project.ts b/packages/eve/src/discover/project.ts
index 162fb1bcd..324a509aa 100644
--- a/packages/eve/src/discover/project.ts
+++ b/packages/eve/src/discover/project.ts
@@ -12,6 +12,7 @@ import {
isProjectMarkerEntry,
} from "#discover/filesystem.js";
import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
+import { resolveNamedAgentProjectContext } from "#internal/project-context.js";
/**
* Supported project layouts for filesystem-based agents.
@@ -55,6 +56,7 @@ export async function resolveDiscoveryProject(
): Promise<ResolvedDiscoveryProject> {
const source = options.source ?? createDiskProjectSource();
const startDirectory = await resolveSearchDirectory(source, startPath);
+
let currentDirectory = startDirectory;
while (true) {
@@ -123,7 +125,7 @@ async function tryResolveNestedProjectFromAgentDirectory(
const parentDirectory = dirname(directoryPath);
- if (!(await hasProjectMarkers(source, parentDirectory))) {
+ if (!(await isNestedProjectRoot(source, parentDirectory))) {
return null;
}
@@ -138,7 +140,7 @@ async function tryResolveNestedProjectFromAppRoot(
source: ProjectSource,
directoryPath: string,
): Promise<ResolvedDiscoveryProject | null> {
- if (!(await hasProjectMarkers(source, directoryPath))) {
+ if (!(await isNestedProjectRoot(source, directoryPath))) {
return null;
}
@@ -155,6 +157,11 @@ async function tryResolveNestedProjectFromAppRoot(
};
}
+async function isNestedProjectRoot(source: ProjectSource, directoryPath: string): Promise<boolean> {
+ if (await hasProjectMarkers(source, directoryPath)) return true;
+ return (await resolveNamedAgentProjectContext(directoryPath, { source })) !== undefined;
+}
+
async function isFlatAgentRoot(source: ProjectSource, directoryPath: string): Promise<boolean> {
const entries = await readDirectoryEntryTypes(source, directoryPath);
diff --git a/packages/eve/src/evals/cli/eval.ts b/packages/eve/src/evals/cli/eval.ts
index 6dd54ed0b..7bc12f919 100644
--- a/packages/eve/src/evals/cli/eval.ts
+++ b/packages/eve/src/evals/cli/eval.ts
@@ -55,7 +55,7 @@ export async function runEvalCommand(
logger: EvalCliLogger,
appRoot: string = process.cwd(),
): Promise<void> {
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
const requestedEvalIds = evalIds.length > 0 ? evalIds : undefined;
const discovered = await discoverAndImportEvals(appRoot, requestedEvalIds);
diff --git a/packages/eve/src/internal/agent-workspace.integration.test.ts b/packages/eve/src/internal/agent-workspace.integration.test.ts
new file mode 100644
index 000000000..bc15d818f
--- /dev/null
+++ b/packages/eve/src/internal/agent-workspace.integration.test.ts
@@ -0,0 +1,106 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { createMemoryProjectSource } from "#discover/project-source.js";
+import { resolveDiscoveryProject } from "#discover/project.js";
+import { resolveAgentWorkspace } from "#internal/agent-workspace.js";
+import { resolveEveProjectContext } from "#internal/project-context.js";
+
+async function createWorkspace(): Promise<string> {
+ const root = await mkdtemp(join(tmpdir(), "eve-workspace-"));
+ await Promise.all([
+ mkdir(join(root, "agents", "support", "agent"), { recursive: true }),
+ mkdir(join(root, "agents", "research", "agent"), { recursive: true }),
+ ]);
+ return root;
+}
+
+describe("resolveAgentWorkspace", () => {
+ it("discovers direct agents/ children in deterministic order", async () => {
+ const root = await createWorkspace();
+ await expect(resolveAgentWorkspace(root)).resolves.toEqual({
+ members: [
+ { name: "research", appRoot: join(root, "agents", "research") },
+ { name: "support", appRoot: join(root, "agents", "support") },
+ ],
+ root,
+ });
+ });
+
+ it("does not read package.json metadata to discover a workspace", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-workspace-metadata-"));
+ await writeFile(
+ join(root, "package.json"),
+ JSON.stringify({ eve: { agents: ["products/*"] }, private: true }),
+ );
+ await mkdir(join(root, "products", "support", "agent"), { recursive: true });
+ await expect(resolveAgentWorkspace(root)).resolves.toBeUndefined();
+ });
+
+ it("rejects agent/ and agents/ at the same root", async () => {
+ const root = await createWorkspace();
+ await mkdir(join(root, "agent"));
+ await expect(resolveAgentWorkspace(root)).rejects.toThrow(/both agent\/ and agents\//);
+ });
+
+ it("rejects empty workspaces", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-workspace-empty-"));
+ await mkdir(join(root, "agents"));
+ await expect(resolveAgentWorkspace(root)).rejects.toThrow(/at least one directory/);
+ });
+
+ it("rejects children without a nested agent directory", async () => {
+ const root = await createWorkspace();
+ await mkdir(join(root, "agents", "not-an-agent"));
+ await expect(resolveAgentWorkspace(root)).rejects.toThrow(
+ /expected agents\/not-an-agent\/agent/,
+ );
+ });
+
+ it("rejects flat members with a migration hint", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-workspace-flat-"));
+ await mkdir(join(root, "agents", "support"), { recursive: true });
+ await writeFile(join(root, "agents", "support", "agent.ts"), "export default {};\n");
+ await expect(resolveAgentWorkspace(root)).rejects.toThrow(/Move flat authored files/);
+ });
+
+ it("keeps conventional members discoverable without project metadata", async () => {
+ const root = await createWorkspace();
+ const supportRoot = join(root, "agents", "support");
+ await expect(resolveDiscoveryProject(supportRoot)).resolves.toEqual({
+ agentRoot: join(supportRoot, "agent"),
+ appRoot: supportRoot,
+ layout: "nested",
+ });
+ });
+
+ it("supports conventional discovery through an in-memory project source", async () => {
+ const root = join(process.cwd(), "memory", "project");
+ const supportRoot = join(root, "agents", "support");
+ const source = createMemoryProjectSource({
+ files: {
+ [join(supportRoot, "agent", "instructions.md")]: "Support users.",
+ },
+ });
+
+ await expect(resolveDiscoveryProject(supportRoot, { source })).resolves.toEqual({
+ agentRoot: join(supportRoot, "agent"),
+ appRoot: supportRoot,
+ layout: "nested",
+ });
+ });
+
+ it("resolves a workspace member from its application root", async () => {
+ const root = await createWorkspace();
+ const supportRoot = join(root, "agents", "support");
+ await expect(resolveEveProjectContext(supportRoot)).resolves.toMatchObject({
+ workspace: { root },
+ environmentRoot: root,
+ kind: "workspace-member",
+ member: { appRoot: supportRoot, name: "support" },
+ });
+ });
+});
diff --git a/packages/eve/src/internal/agent-workspace.ts b/packages/eve/src/internal/agent-workspace.ts
new file mode 100644
index 000000000..aa4b1caed
--- /dev/null
+++ b/packages/eve/src/internal/agent-workspace.ts
@@ -0,0 +1,67 @@
+import { basename, join, relative, resolve } from "node:path";
+
+import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
+import { assertValidPublicAgentName } from "#internal/agent-name.js";
+
+export interface AgentWorkspaceMember {
+ readonly appRoot: string;
+ readonly name: string;
+}
+
+export interface AgentWorkspace {
+ readonly members: readonly AgentWorkspaceMember[];
+ readonly root: string;
+}
+
+/** Discover the direct children of a conventional `agents/` workspace. */
+export async function resolveAgentWorkspace(
+ root: string,
+ options: { readonly source?: ProjectSource } = {},
+): Promise<AgentWorkspace | undefined> {
+ const source = options.source ?? createDiskProjectSource();
+ const workspaceRoot = resolve(root);
+ const agentsRoot = join(workspaceRoot, "agents");
+ if ((await source.stat(agentsRoot)) !== "directory") return undefined;
+
+ if ((await source.stat(join(workspaceRoot, "agent"))) === "directory") {
+ throw new Error(
+ "An eve project cannot contain both agent/ and agents/. Keep a standalone agent or move it into the workspace.",
+ );
+ }
+
+ const members: AgentWorkspaceMember[] = [];
+ const entries = (await source.readDirectory(agentsRoot))
+ .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+ .sort((left, right) => left.name.localeCompare(right.name));
+
+ for (const entry of entries) {
+ const appRoot = join(agentsRoot, entry.name);
+ const name = basename(appRoot);
+ assertValidPublicAgentName(name, "Agent workspace member");
+ if ((await source.stat(join(appRoot, "agent"))) !== "directory") {
+ const relativeAppRoot = relative(workspaceRoot, appRoot).replaceAll("\\", "/");
+ const flatHint =
+ (await source.stat(join(appRoot, "agent.ts"))) === "file"
+ ? " Move flat authored files under an agent/ directory."
+ : "";
+ throw new Error(
+ `${relativeAppRoot} is not a workspace agent: expected ${relativeAppRoot}/agent/.${flatHint}`,
+ );
+ }
+ members.push({ appRoot, name });
+ }
+
+ if (members.length === 0) {
+ throw new Error("An eve agent workspace requires at least one directory under agents/.");
+ }
+
+ return { members, root: workspaceRoot };
+}
+
+/** Load a workspace that the caller has already identified as workspace-shaped. */
+export async function loadAgentWorkspace(root: string): Promise<AgentWorkspace> {
+ const workspace = await resolveAgentWorkspace(root);
+ if (workspace === undefined)
+ throw new Error("An eve agent workspace requires an agents/ directory.");
+ return workspace;
+}
diff --git a/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts b/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts
index 3960e281e..a352d3081 100644
--- a/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts
+++ b/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts
@@ -4,6 +4,7 @@ import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import {
+ getDevelopmentEnvironmentFilePaths,
loadDevelopmentEnvironmentFiles,
readDevelopmentEnvironmentHostValues,
stageDevelopmentEnvironmentFiles,
@@ -12,6 +13,7 @@ import {
const ENV_KEYS = [
"EVE_WATCH_ENV_FILE_ONLY",
"EVE_WATCH_ENV_NEW",
+ "EVE_WATCH_ENV_ROOT_ONLY",
"EVE_WATCH_ENV_SHARED",
"EVE_WATCH_ENV_SHELL",
"AI_GATEWAY_API_KEY",
@@ -34,7 +36,7 @@ describe("development environment reload transactions", () => {
const appRoot = await createEnvironmentApp();
process.env.EVE_WATCH_ENV_SHELL = "from-parent";
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
expect(process.env.EVE_WATCH_ENV_FILE_ONLY).toBe("from-env");
expect(process.env.EVE_WATCH_ENV_SHARED).toBe("from-local");
@@ -47,11 +49,11 @@ describe("development environment reload transactions", () => {
await mkdir(join(appRoot, ".eve"));
await writeFile(join(appRoot, ".eve", "provider.json"), '{"selected":"ai-gateway-project"}\n');
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
expect(process.env.AI_GATEWAY_API_KEY).toBeUndefined();
await writeFile(join(appRoot, ".eve", "provider.json"), '{"selected":"ai-gateway-key"}\n');
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
expect(process.env.AI_GATEWAY_API_KEY).toBe("from-file");
});
@@ -59,21 +61,48 @@ describe("development environment reload transactions", () => {
const appRoot = await createEnvironmentApp();
process.env.AI_GATEWAY_API_KEY = "from-parent";
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
expect(readDevelopmentEnvironmentHostValues(appRoot).AI_GATEWAY_API_KEY).toBe("from-parent");
await mkdir(join(appRoot, ".eve"));
await writeFile(join(appRoot, ".eve", "provider.json"), '{"selected":"ai-gateway-project"}\n');
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
expect(process.env.AI_GATEWAY_API_KEY).toBeUndefined();
expect(readDevelopmentEnvironmentHostValues(appRoot).AI_GATEWAY_API_KEY).toBeNull();
});
+ it("loads, watches, fingerprints, and reloads workspace-root env", async () => {
+ const workspaceRoot = await mkdtemp(join(tmpdir(), "eve-dev-env-workspace-"));
+ temporaryDirectories.push(workspaceRoot);
+ const appRoot = join(workspaceRoot, "agents", "support");
+ await mkdir(join(appRoot, "agent"), { recursive: true });
+ await writeFile(
+ join(workspaceRoot, ".env.local"),
+ "EVE_WATCH_ENV_ROOT_ONLY=from-root\nEVE_WATCH_ENV_SHARED=from-root\n",
+ );
+ await writeFile(join(appRoot, ".env.local"), "EVE_WATCH_ENV_SHARED=from-child\n");
+
+ await loadDevelopmentEnvironmentFiles(appRoot);
+
+ expect(process.env.EVE_WATCH_ENV_ROOT_ONLY).toBe("from-root");
+ expect(process.env.EVE_WATCH_ENV_SHARED).toBe("from-root");
+ expect(getDevelopmentEnvironmentFilePaths(appRoot)).toEqual(environmentPaths(workspaceRoot));
+ expect(readDevelopmentEnvironmentHostValues(appRoot)).toMatchObject({
+ EVE_WATCH_ENV_ROOT_ONLY: "from-root",
+ EVE_WATCH_ENV_SHARED: "from-root",
+ });
+
+ await writeFile(join(workspaceRoot, ".env.local"), "EVE_WATCH_ENV_ROOT_ONLY=updated\n");
+ stageDevelopmentEnvironmentFiles(appRoot).commit();
+ expect(process.env.EVE_WATCH_ENV_ROOT_ONLY).toBe("updated");
+ expect(process.env.EVE_WATCH_ENV_SHARED).toBeUndefined();
+ });
+
it("restores the complete prior environment when a candidate is rejected", async () => {
const appRoot = await createEnvironmentApp();
const envLocalPath = join(appRoot, ".env.local");
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
await writeFile(
envLocalPath,
"EVE_WATCH_ENV_NEW=from-candidate\nEVE_WATCH_ENV_SHARED=from-candidate\n",
@@ -93,7 +122,7 @@ describe("development environment reload transactions", () => {
it("retains the candidate environment after commit", async () => {
const appRoot = await createEnvironmentApp();
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
await writeFile(join(appRoot, ".env.local"), "EVE_WATCH_ENV_SHARED=committed\n");
const reload = stageDevelopmentEnvironmentFiles(appRoot);
@@ -105,7 +134,7 @@ describe("development environment reload transactions", () => {
it("reapplies a rolled-back environment edit when a later rebuild stages again", async () => {
const appRoot = await createEnvironmentApp();
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
await writeFile(join(appRoot, ".env.local"), "EVE_WATCH_ENV_SHARED=after-fix\n");
stageDevelopmentEnvironmentFiles(appRoot).rollback();
@@ -120,6 +149,12 @@ describe("development environment reload transactions", () => {
});
});
+function environmentPaths(root: string): string[] {
+ return [".env.development.local", ".env.local", ".env.development", ".env"].map((name) =>
+ join(root, name),
+ );
+}
+
async function createEnvironmentApp(): Promise<string> {
const appRoot = await mkdtemp(join(tmpdir(), "eve-dev-env-transaction-"));
temporaryDirectories.push(appRoot);
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 21fd3c34a..5086a15ea 100644
--- a/packages/eve/src/internal/nitro/host/start-development-server.ts
+++ b/packages/eve/src/internal/nitro/host/start-development-server.ts
@@ -385,7 +385,7 @@ async function startNitroDevelopmentServer(
process.env[EVE_DEV_ENV_FLAG] ??= "1";
const project = await resolveDiscoveryProject(rootDir);
- loadDevelopmentEnvironmentFiles(project.appRoot);
+ await loadDevelopmentEnvironmentFiles(project.appRoot);
const environmentPort = readEnvironmentPort();
const requestedPort = options.port ?? environmentPort;
diff --git a/packages/eve/src/internal/nitro/host/start-production-server.ts b/packages/eve/src/internal/nitro/host/start-production-server.ts
index 5618f1960..768bdc479 100644
--- a/packages/eve/src/internal/nitro/host/start-production-server.ts
+++ b/packages/eve/src/internal/nitro/host/start-production-server.ts
@@ -19,10 +19,6 @@ const LOCAL_SERVER_URL_PATTERN = /https?:\/\/(?:\[[^\]\s]+\]|[^\s/:[\]]+)(?::\d+
const TERMINATE_GRACE_MS = 20_000;
const WILDCARD_LISTEN_HOSTNAMES: ReadonlySet<string> = new Set(["[::]", "::", "0.0.0.0"]);
-function isRecord(value: unknown): value is Record<string, unknown> {
- return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
function resolveOutputServerEntry(appRoot: string): string {
return join(resolve(appRoot), ".output", "server", "index.mjs");
}
@@ -208,7 +204,7 @@ export async function startProductionServer(
);
}
- loadDevelopmentEnvironmentFiles(appRoot);
+ await loadDevelopmentEnvironmentFiles(appRoot);
await prewarmBuiltAppSandboxes({
appRoot,
log: (message) => console.log(message),
@@ -293,7 +289,7 @@ export async function startProductionServer(
closing = true;
await terminate(child);
- if (isRecord(error) && error.name === "AbortError") {
+ if (error instanceof Error && error.name === "AbortError") {
throw new Error("Timed out waiting for built eve server to respond.", { cause: error });
}
diff --git a/packages/eve/src/internal/project-context.ts b/packages/eve/src/internal/project-context.ts
new file mode 100644
index 000000000..ce8dba3db
--- /dev/null
+++ b/packages/eve/src/internal/project-context.ts
@@ -0,0 +1,79 @@
+import { join, resolve } from "node:path";
+
+import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
+import {
+ resolveAgentWorkspace,
+ type AgentWorkspace,
+ type AgentWorkspaceMember,
+} from "#internal/agent-workspace.js";
+
+export type EveProjectContext =
+ | {
+ readonly workspace: AgentWorkspace;
+ readonly environmentRoot: string;
+ readonly kind: "workspace";
+ }
+ | {
+ readonly workspace: AgentWorkspace;
+ readonly environmentRoot: string;
+ readonly kind: "workspace-member";
+ readonly member: AgentWorkspaceMember;
+ }
+ | {
+ readonly appRoot: string;
+ readonly environmentRoot: string;
+ readonly kind: "standalone";
+ };
+
+function standalone(appRoot: string): Extract<EveProjectContext, { kind: "standalone" }> {
+ return { appRoot, environmentRoot: appRoot, kind: "standalone" };
+}
+
+/** Classify an app root included by the nearest declared agent workspace. */
+export async function resolveNamedAgentProjectContext(
+ appRoot: string,
+ options: { readonly source?: ProjectSource } = {},
+): Promise<Extract<EveProjectContext, { kind: "workspace-member" | "standalone" }> | undefined> {
+ const resolvedAppRoot = resolve(appRoot);
+ const source = options.source ?? createDiskProjectSource();
+ let workspaceRoot = resolvedAppRoot;
+
+ while (true) {
+ if (
+ workspaceRoot !== resolvedAppRoot &&
+ (await source.stat(join(workspaceRoot, "agent"))) === "directory"
+ ) {
+ return undefined;
+ }
+ const workspace = await resolveAgentWorkspace(workspaceRoot, { source });
+ const member = workspace?.members.find((candidate) => candidate.appRoot === resolvedAppRoot);
+ if (workspace !== undefined && member !== undefined) {
+ return {
+ workspace,
+ environmentRoot: workspace.root,
+ kind: "workspace-member",
+ member,
+ };
+ }
+
+ const parent = resolve(workspaceRoot, "..");
+ if (parent === workspaceRoot) return undefined;
+ workspaceRoot = parent;
+ }
+}
+
+/** Classify the current filesystem scope before command-specific policy runs. */
+export async function resolveEveProjectContext(
+ appRoot: string,
+ options: { readonly source?: ProjectSource } = {},
+): Promise<EveProjectContext> {
+ const resolvedAppRoot = resolve(appRoot);
+ const source = options.source ?? createDiskProjectSource();
+ const namedAgent = await resolveNamedAgentProjectContext(resolvedAppRoot, { source });
+ if (namedAgent !== undefined) return namedAgent;
+
+ const workspace = await resolveAgentWorkspace(resolvedAppRoot, { source });
+ return workspace === undefined
+ ? standalone(resolvedAppRoot)
+ : { workspace, environmentRoot: workspace.root, kind: "workspace" };
+}
diff --git a/packages/eve/src/setup/scaffold/update/channels.ts b/packages/eve/src/setup/scaffold/update/channels.ts
index 63e437494..be459127d 100644
--- a/packages/eve/src/setup/scaffold/update/channels.ts
+++ b/packages/eve/src/setup/scaffold/update/channels.ts
@@ -164,23 +164,9 @@ async function hasPackageDependency(
return parsed !== undefined && packageJsonHasDependency(parsed, dependencyName);
}
-/**
- * Whether the project already carries a Next.js app: `package.json` declares a
- * `next` dependency in the same dependency fields Vercel framework detection
- * checks. This is the exact predicate the
- * web scaffold skips on (`skipReason: "nextjs-project"`), so pickers can mark
- * Web Chat as already present precisely when scaffolding would be a no-op.
- * A missing `package.json` reads as "no app".
- */
-export async function isNextJsProject(projectRoot: string): Promise<boolean> {
- return hasPackageDependency(join(projectRoot, "package.json"), NEXT_PACKAGE_NAME);
-}
-
/**
* Host-framework dependency → the Vercel Framework Preset slug it must deploy
* under (so the framework owns the top-level build and eve runs as a sibling).
- * Single source of truth for which dependencies mark a host framework;
- * {@link hasVercelHostFramework} derives from it.
*/
const VERCEL_HOST_FRAMEWORK_PRESETS: Readonly<Record<string, string>> = {
"@sveltejs/kit": "sveltekit",
@@ -191,10 +177,7 @@ const VERCEL_HOST_FRAMEWORK_PRESETS: Readonly<Record<string, string>> = {
"nuxt-nightly": "nuxtjs",
};
-/**
- * The Vercel Framework Preset slug for the host framework a project declares, or
- * `undefined` when it declares none (a missing `package.json` reads as none).
- */
+/** The Vercel Framework Preset slug for the host framework a project declares. */
export async function resolveVercelHostFrameworkPreset(
projectRoot: string,
): Promise<string | undefined> {
@@ -207,16 +190,23 @@ export async function resolveVercelHostFrameworkPreset(
return undefined;
}
-/**
- * Whether the root app declares a Vercel framework that should own the
- * top-level deployment while eve runs as a sibling service. These match Eve's
- * current framework integrations: Next.js, Nuxt, and SvelteKit. Derived from
- * {@link resolveVercelHostFrameworkPreset} so the two share one dependency list.
- */
+/** Whether the root app declares a Vercel framework that owns its top-level deployment. */
export async function hasVercelHostFramework(projectRoot: string): Promise<boolean> {
return (await resolveVercelHostFrameworkPreset(projectRoot)) !== undefined;
}
+/**
+ * Whether the project already carries a Next.js app: `package.json` declares a
+ * `next` dependency in the same dependency fields Vercel framework detection
+ * checks. This is the exact predicate the
+ * web scaffold skips on (`skipReason: "nextjs-project"`), so pickers can mark
+ * Web Chat as already present precisely when scaffolding would be a no-op.
+ * A missing `package.json` reads as "no app".
+ */
+export async function isNextJsProject(projectRoot: string): Promise<boolean> {
+ return hasPackageDependency(join(projectRoot, "package.json"), NEXT_PACKAGE_NAME);
+}
+
async function ensurePackageDependency(
packageJsonPath: string,
dependencyName: string,
diff --git a/packages/eve/test/scenarios/dev-environment.scenario.test.ts b/packages/eve/test/scenarios/dev-environment.scenario.test.ts
index 4703627ad..4fbb6d212 100644
--- a/packages/eve/test/scenarios/dev-environment.scenario.test.ts
+++ b/packages/eve/test/scenarios/dev-environment.scenario.test.ts
@@ -60,7 +60,7 @@ describe("loadDevelopmentEnvironmentFiles", () => {
process.env.EVE_DEV_SHELL_ONLY = "from-shell";
- loadDevelopmentEnvironmentFiles(fixtureRoot);
+ await loadDevelopmentEnvironmentFiles(fixtureRoot);
expect(process.env.EVE_DEV_DEVELOPMENT_LOCAL_ONLY).toBe("from-development-local");
expect(process.env.EVE_DEV_LOCAL_ONLY).toBe("from-local");