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