Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): support extension external dependencies (#2278)

Casey Gowrie6e87b130fef2
diff --git a/.changeset/curvy-dingos-trace.md b/.changeset/curvy-dingos-trace.md
new file mode 100644
index 000000000..055141c01
--- /dev/null
+++ b/.changeset/curvy-dingos-trace.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Allow extension packages to declare runtime dependencies that eve must keep external and preserve with their complete package files. Consumers receive these packaging requirements automatically without editing their agent config.
diff --git a/docs/extensions.md b/docs/extensions.md
index 2c2e3d919..7d1343abe 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -102,6 +102,7 @@ The scaffold's `package.json` declares separate source and distribution roots:
"extension": {
"source": "./extension",
"dist": "./dist/extension",
+ "externalDependencies": ["@acme/runtime-sdk"],
},
},
"files": ["dist"],
@@ -121,6 +122,7 @@ The scaffold's `package.json` declares separate source and distribution roots:
"typecheck": "tsc",
},
"dependencies": {
+ "@acme/runtime-sdk": "^x",
"zod": "^x",
},
"devDependencies": {
@@ -149,7 +151,9 @@ eve extension build
The exact `eve` development pin controls the extension authoring API and build tooling. The wildcard peer lets the consumer provide the runtime copy of eve. At consumption time, eve checks generated metadata, not the npm peer range. Do not add eve to regular `dependencies`.
-Put runtime packages such as `zod` or an SDK in `dependencies`. If a dependency cannot be bundled, such as a native addon, tell consumers to add it to `build.externalDependencies` in `agent.ts`.
+Put runtime packages such as `zod` or an SDK in `dependencies`. Most dependencies are bundled into the consuming agent automatically.
+
+When a package must keep normal Node.js package layout at runtime, add it to `eve.extension.externalDependencies`. Common cases include native addons and SDKs that load package-relative assets. `eve extension build` requires each listed package to also appear in `dependencies`, `optionalDependencies`, or `peerDependencies`, and records the requirement in the generated compatibility manifest. The consuming eve keeps the package external and preserves its complete package tree; consumers do not need to edit `agent.ts` or install the transitive package directly.
Consumers can now add the built package to an agent. A workspace-only extension uses the same package contract but does not need to be published; see [Use an extension in a workspace](#use-an-extension-in-a-workspace).
diff --git a/e2e/fixtures/dist-extensions/agent/agent.ts b/e2e/fixtures/dist-extensions/agent/agent.ts
index 384bb0e2a..ec9538588 100644
--- a/e2e/fixtures/dist-extensions/agent/agent.ts
+++ b/e2e/fixtures/dist-extensions/agent/agent.ts
@@ -1,7 +1,8 @@
import { e2eAgentConfig } from "@eve-e2e/config";
import { defineAgent } from "eve";
+import { respond } from "./mock-responder.js";
export default defineAgent({
- ...e2eAgentConfig(),
+ ...e2eAgentConfig({ mock: respond }),
reasoning: "high",
});
diff --git a/e2e/fixtures/dist-extensions/agent/mock-responder.ts b/e2e/fixtures/dist-extensions/agent/mock-responder.ts
new file mode 100644
index 000000000..e32a44b77
--- /dev/null
+++ b/e2e/fixtures/dist-extensions/agent/mock-responder.ts
@@ -0,0 +1,17 @@
+import type { MockModelRequest, MockModelResponse } from "eve/evals";
+
+const LAYOUT_TOOL = "gizmo__gizmo_layout";
+
+export function respond(request: MockModelRequest): MockModelResponse | string {
+ const message = request.lastUserMessage ?? "";
+ if (!message.includes(`Call \`${LAYOUT_TOOL}\``)) {
+ return `Mock reply: ${message}`;
+ }
+
+ const result = [...request.toolResults].reverse().find((entry) => entry.name === LAYOUT_TOOL);
+ if (result === undefined) {
+ return { toolCalls: [{ name: LAYOUT_TOOL }] };
+ }
+
+ return JSON.stringify(result.output);
+}
diff --git a/e2e/fixtures/dist-extensions/evals/external-dependency-assets.eval.ts b/e2e/fixtures/dist-extensions/evals/external-dependency-assets.eval.ts
new file mode 100644
index 000000000..d01f18a4d
--- /dev/null
+++ b/e2e/fixtures/dist-extensions/evals/external-dependency-assets.eval.ts
@@ -0,0 +1,14 @@
+import { defineEval } from "eve/evals";
+
+export default defineEval({
+ description:
+ "A store-installed extension preserves assets from an extension-owned external dependency.",
+ async test(t) {
+ await t.send("Call `gizmo__gizmo_layout` and report its payload.");
+
+ t.succeeded();
+ t.calledTool("gizmo__gizmo_layout", {
+ output: { payload: "[email protected]" },
+ });
+ },
+});
diff --git a/e2e/fixtures/extensions/agent/agent.ts b/e2e/fixtures/extensions/agent/agent.ts
index 384bb0e2a..ec9538588 100644
--- a/e2e/fixtures/extensions/agent/agent.ts
+++ b/e2e/fixtures/extensions/agent/agent.ts
@@ -1,7 +1,8 @@
import { e2eAgentConfig } from "@eve-e2e/config";
import { defineAgent } from "eve";
+import { respond } from "./mock-responder.js";
export default defineAgent({
- ...e2eAgentConfig(),
+ ...e2eAgentConfig({ mock: respond }),
reasoning: "high",
});
diff --git a/e2e/fixtures/extensions/agent/mock-responder.ts b/e2e/fixtures/extensions/agent/mock-responder.ts
new file mode 100644
index 000000000..e32a44b77
--- /dev/null
+++ b/e2e/fixtures/extensions/agent/mock-responder.ts
@@ -0,0 +1,17 @@
+import type { MockModelRequest, MockModelResponse } from "eve/evals";
+
+const LAYOUT_TOOL = "gizmo__gizmo_layout";
+
+export function respond(request: MockModelRequest): MockModelResponse | string {
+ const message = request.lastUserMessage ?? "";
+ if (!message.includes(`Call \`${LAYOUT_TOOL}\``)) {
+ return `Mock reply: ${message}`;
+ }
+
+ const result = [...request.toolResults].reverse().find((entry) => entry.name === LAYOUT_TOOL);
+ if (result === undefined) {
+ return { toolCalls: [{ name: LAYOUT_TOOL }] };
+ }
+
+ return JSON.stringify(result.output);
+}
diff --git a/e2e/fixtures/extensions/evals/external-dependency-assets.eval.ts b/e2e/fixtures/extensions/evals/external-dependency-assets.eval.ts
new file mode 100644
index 000000000..fcc2f1d7a
--- /dev/null
+++ b/e2e/fixtures/extensions/evals/external-dependency-assets.eval.ts
@@ -0,0 +1,13 @@
+import { defineEval } from "eve/evals";
+
+export default defineEval({
+ description: "An extension-owned external dependency retains package-relative runtime assets.",
+ async test(t) {
+ await t.send("Call `gizmo__gizmo_layout` and report its payload.");
+
+ t.succeeded();
+ t.calledTool("gizmo__gizmo_layout", {
+ output: { payload: "[email protected]" },
+ });
+ },
+});
diff --git a/e2e/fixtures/gizmo-extension/extension/tools/gizmo_layout.ts b/e2e/fixtures/gizmo-extension/extension/tools/gizmo_layout.ts
new file mode 100644
index 000000000..6bd184e14
--- /dev/null
+++ b/e2e/fixtures/gizmo-extension/extension/tools/gizmo_layout.ts
@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+const require = createRequire(import.meta.url);
+
+export default defineTool({
+ description: "Read deterministic metadata from an external package's sibling asset.",
+ inputSchema: z.object({}),
+ async execute() {
+ const entryPath = require.resolve("zod");
+ const packageJson = JSON.parse(
+ await readFile(join(dirname(entryPath), "package.json"), "utf8"),
+ ) as { name: string; version: string };
+
+ return { payload: `${packageJson.name}@${packageJson.version}` };
+ },
+});
diff --git a/e2e/fixtures/gizmo-extension/package.json b/e2e/fixtures/gizmo-extension/package.json
index 3010312cb..8c0b2e9dd 100644
--- a/e2e/fixtures/gizmo-extension/package.json
+++ b/e2e/fixtures/gizmo-extension/package.json
@@ -33,7 +33,10 @@
"eve": {
"extension": {
"source": "./extension",
- "dist": "./dist/extension"
+ "dist": "./dist/extension",
+ "externalDependencies": [
+ "zod"
+ ]
}
}
}
diff --git a/packages/eve/src/compiler/extension-compatibility.test.ts b/packages/eve/src/compiler/extension-compatibility.test.ts
index 894a97d6e..ccec98d5f 100644
--- a/packages/eve/src/compiler/extension-compatibility.test.ts
+++ b/packages/eve/src/compiler/extension-compatibility.test.ts
@@ -17,6 +17,7 @@ describe("extension compatibility manifest", () => {
kind: EXTENSION_COMPATIBILITY_MANIFEST_KIND,
formatVersion: EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION,
builtWithEve: "0.24.6",
+ build: { externalDependencies: ["@acme/runtime-sdk"] },
requires: { extension: 1, tool: 1 },
} as const;
@@ -28,6 +29,25 @@ describe("extension compatibility manifest", () => {
).toEqual(manifest);
});
+ it("continues to parse format v1 manifests", () => {
+ expect(
+ parseExtensionCompatibilityManifest(
+ JSON.stringify({
+ kind: EXTENSION_COMPATIBILITY_MANIFEST_KIND,
+ formatVersion: 1,
+ builtWithEve: "0.39.0",
+ requires: { extension: 1 },
+ }),
+ "/pkg/dist/extension/_manifest.json",
+ ),
+ ).toEqual({
+ kind: EXTENSION_COMPATIBILITY_MANIFEST_KIND,
+ formatVersion: 1,
+ builtWithEve: "0.39.0",
+ requires: { extension: 1 },
+ });
+ });
+
it("rejects executable or contribution fields", () => {
expect(() =>
parseExtensionCompatibilityManifest(
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 8cea6d598..b5af79650 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -8,7 +8,7 @@ import { formatValidationError } from "#runtime/validation.js";
export const EXTENSION_COMPATIBILITY_MANIFEST_KIND = "eve-extension";
/** Current compatibility-manifest JSON format. */
-export const EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION = 1;
+export const EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION = 2;
/** Filename emitted at the root of an extension's agent-shaped dist tree. */
export const EXTENSION_COMPATIBILITY_MANIFEST_FILENAME = "_manifest.json";
@@ -95,10 +95,13 @@ export type ExtensionCapabilitySupport = Readonly<Record<string, readonly number
/** Compatibility-only metadata emitted by `eve extension build`. */
export interface ExtensionCompatibilityManifest {
readonly kind: typeof EXTENSION_COMPATIBILITY_MANIFEST_KIND;
- readonly formatVersion: typeof EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION;
+ readonly formatVersion: 1 | typeof EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION;
/** Diagnostic producer version; capability requirements decide compatibility. */
readonly builtWithEve: string;
readonly requires: Readonly<Record<string, number>>;
+ readonly build?: {
+ readonly externalDependencies: readonly string[];
+ };
}
/** One requirement the consuming eve cannot satisfy. */
@@ -108,14 +111,27 @@ export interface UnsupportedExtensionCapability {
readonly supportedVersions: readonly number[];
}
-const extensionCompatibilityManifestSchema: z.ZodType<ExtensionCompatibilityManifest> = z
+const extensionCompatibilityManifestV1Schema = z
.object({
kind: z.literal(EXTENSION_COMPATIBILITY_MANIFEST_KIND),
- formatVersion: z.literal(EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION),
+ formatVersion: z.literal(1),
builtWithEve: z.string().min(1),
requires: z.record(z.string(), z.number().int().positive()),
})
.strict();
+const extensionCompatibilityManifestV2Schema = extensionCompatibilityManifestV1Schema.extend({
+ formatVersion: z.literal(EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION),
+ build: z
+ .object({
+ externalDependencies: z.array(z.string().min(1)).readonly(),
+ })
+ .strict()
+ .optional(),
+});
+const extensionCompatibilityManifestSchema: z.ZodType<ExtensionCompatibilityManifest> = z.union([
+ extensionCompatibilityManifestV1Schema,
+ extensionCompatibilityManifestV2Schema,
+]);
/** Serializes a compatibility manifest deterministically. */
export function serializeExtensionCompatibilityManifest(
diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.ts
index aaf7dea66..6dd820114 100644
--- a/packages/eve/src/compiler/manifest.ts
+++ b/packages/eve/src/compiler/manifest.ts
@@ -672,6 +672,7 @@ const compiledHookDefinitionSchema: z.ZodType<CompiledHookDefinition> = z
const compiledExtensionMountSchema: z.ZodType<CompiledExtensionMount> = z
.object({
+ externalDependencies: z.array(z.string()).readonly(),
namespace: z.string(),
packageName: z.string(),
packageNamespace: z.string(),
@@ -767,6 +768,8 @@ const compiledSubagentEdgeSchema: z.ZodType<CompiledSubagentEdge> = z
* call binds the extension's config before any tool runs.
*/
export interface CompiledExtensionMount {
+ /** Runtime packages this extension requires the consuming application to externalize. */
+ readonly externalDependencies: readonly string[];
/** Mount-derived namespace that prefixes the extension's tool/skill names. */
readonly namespace: string;
readonly packageName: string;
diff --git a/packages/eve/src/compiler/normalize-extension.test.ts b/packages/eve/src/compiler/normalize-extension.test.ts
index 7b504024e..9d5749949 100644
--- a/packages/eve/src/compiler/normalize-extension.test.ts
+++ b/packages/eve/src/compiler/normalize-extension.test.ts
@@ -146,6 +146,7 @@ describe("composeExtensionSubagentSources", () => {
packageRoot: "/packages/crm",
sourceRoot: extensionRoot,
manifest: extensionManifest,
+ externalDependencies: [],
overrides: overrideManifest,
},
});
diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.ts
index 8ddbdee61..5783c7538 100644
--- a/packages/eve/src/compiler/normalize-manifest.test.ts
+++ b/packages/eve/src/compiler/normalize-manifest.test.ts
@@ -83,6 +83,51 @@ describe("compileAgentManifest", () => {
);
});
+ it("merges agent-owned and extension-owned external dependencies", async () => {
+ const extensionManifest = createAgentSourceManifest({
+ agentId: "research-extension",
+ agentRoot: "/packages/research/dist/extension",
+ appRoot: "/packages/research",
+ });
+ const manifest = createAgentSourceManifest({
+ agentId: "root",
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ extensions: [createModuleSourceRef({ logicalPath: "extensions/research.ts" })],
+ resolvedExtensions: [
+ {
+ namespace: "research",
+ specifier: "@acme/research",
+ packageName: "@acme/research",
+ packageRoot: "/packages/research",
+ sourceRoot: "/packages/research/dist/extension",
+ manifest: extensionManifest,
+ externalDependencies: ["extension-only", "shared"],
+ },
+ ],
+ });
+ mocks.compileAgentConfig.mockResolvedValue(
+ createConfig({
+ name: "root",
+ build: { externalDependencies: ["agent-only", "shared"] },
+ }),
+ );
+
+ const compiled = await compileAgentManifest(manifest);
+
+ expect(compiled.config.build?.externalDependencies).toEqual([
+ "agent-only",
+ "shared",
+ "extension-only",
+ ]);
+ expect(compiled.extensionMounts).toEqual([
+ expect.objectContaining({
+ namespace: "research",
+ externalDependencies: ["extension-only", "shared"],
+ }),
+ ]);
+ });
+
it("retains extension mounts on the subagent that owns them", async () => {
const extensionManifest = createAgentSourceManifest({
agentId: "research-extension",
@@ -104,6 +149,7 @@ describe("compileAgentManifest", () => {
packageRoot: "/packages/research",
sourceRoot: "/packages/research/dist/extension",
manifest: extensionManifest,
+ externalDependencies: [],
},
],
});
@@ -430,7 +476,7 @@ function createManifestWithSubagent(): AgentSourceManifest {
function createConfig(
input: Pick<CompiledAgentDefinition, "name"> &
- Partial<Pick<CompiledAgentDefinition, "description" | "experimental">>,
+ Partial<Pick<CompiledAgentDefinition, "build" | "description" | "experimental">>,
): CompiledAgentDefinition {
const config: CompiledAgentDefinition = {
model: {
@@ -443,6 +489,9 @@ function createConfig(
if (input.description !== undefined) {
config.description = input.description;
}
+ if (input.build !== undefined) {
+ config.build = input.build;
+ }
if (input.experimental !== undefined) {
config.experimental = input.experimental;
}
diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.ts
index b73572242..8bed87ce0 100644
--- a/packages/eve/src/compiler/normalize-manifest.ts
+++ b/packages/eve/src/compiler/normalize-manifest.ts
@@ -92,6 +92,7 @@ async function compileAgentNodeManifest(
const externalDependencies = mergeExternalDependencies(
options.externalDependencies,
rawConfig.build?.externalDependencies,
+ manifest.resolvedExtensions.flatMap((mount) => mount.externalDependencies),
);
const config =
externalDependencies.length === 0
@@ -282,6 +283,7 @@ function compileExtensionMounts(manifest: AgentSourceManifest): CompiledExtensio
(entry) => mountRefNamespace(entry.logicalPath) === mount.namespace,
);
return {
+ externalDependencies: [...mount.externalDependencies],
namespace: mount.namespace,
packageName: mount.packageName,
packageNamespace: packageStateNamespace(mount.packageName),
diff --git a/packages/eve/src/discover/discover-agent.ts b/packages/eve/src/discover/discover-agent.ts
index dbca1c707..e401f2c7b 100644
--- a/packages/eve/src/discover/discover-agent.ts
+++ b/packages/eve/src/discover/discover-agent.ts
@@ -371,6 +371,7 @@ export async function resolveExtensionMounts(input: {
packageRoot: located.location.packageRoot,
sourceRoot: located.location.sourceRoot,
manifest: extensionResult.manifest,
+ externalDependencies: located.location.externalDependencies,
overrides,
});
}
diff --git a/packages/eve/src/discover/extensions.ts b/packages/eve/src/discover/extensions.ts
index 970f5c05d..1abce481c 100644
--- a/packages/eve/src/discover/extensions.ts
+++ b/packages/eve/src/discover/extensions.ts
@@ -91,6 +91,8 @@ export interface ExtensionMountLocation {
readonly packageRoot: string;
/** Absolute path to the extension's agent-shaped distribution root. */
readonly sourceRoot: string;
+ /** Runtime packages this extension requires the consuming application to externalize. */
+ readonly externalDependencies: readonly string[];
}
/**
@@ -217,6 +219,7 @@ export async function locateExtensionMount(input: {
packageName: location.packageName,
packageRoot: location.packageRoot,
sourceRoot: location.distRoot,
+ externalDependencies: compatibility.build?.externalDependencies ?? [],
},
diagnostics: [],
};
diff --git a/packages/eve/src/discover/manifest.ts b/packages/eve/src/discover/manifest.ts
index 7ee97ce7a..95f102ef6 100644
--- a/packages/eve/src/discover/manifest.ts
+++ b/packages/eve/src/discover/manifest.ts
@@ -155,6 +155,8 @@ export interface ResolvedExtensionMount {
readonly sourceRoot: string;
/** Discovered agent-shaped source manifest for the extension. */
readonly manifest: AgentSourceManifest;
+ /** Runtime packages this extension requires the consuming application to externalize. */
+ readonly externalDependencies: readonly string[];
/**
* Consumer-authored overrides discovered in the mount directory form
* (`extensions/<ns>/{tools,connections,…}/`). Composed under the same
diff --git a/packages/eve/src/internal/nitro/dev-runtime-artifacts.ts b/packages/eve/src/internal/nitro/dev-runtime-artifacts.ts
index 96b932cd6..d458923c0 100644
--- a/packages/eve/src/internal/nitro/dev-runtime-artifacts.ts
+++ b/packages/eve/src/internal/nitro/dev-runtime-artifacts.ts
@@ -1,5 +1,5 @@
import { randomUUID } from "node:crypto";
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
import { existsSync, readFileSync } from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";
@@ -7,6 +7,7 @@ import type { CompileAgentResult } from "#compiler/compile-agent.js";
import type { CompiledAgentManifest } from "#compiler/manifest.js";
import { readMaterializedAuthoredModuleIndex } from "#internal/materialized-authored-modules.js";
import { copyDevelopmentSourceSnapshot } from "#internal/nitro/dev-runtime-source-snapshot-copy.js";
+import { resolveExtensionExternalDependencyPaths } from "#internal/nitro/host/extension-external-dependency-plugin.js";
import {
createDevelopmentSourceSnapshotPlan,
toDevelopmentSourceSnapshotPath,
@@ -94,6 +95,10 @@ export async function stageDevelopmentRuntimeArtifactsSnapshot(
try {
await copyDevelopmentSourceSnapshot(sourceSnapshotPlan);
+ await mountExtensionExternalDependencies({
+ manifest: compileResult.manifest,
+ runtimeAppRoot: sourceSnapshotPlan.runtimeAppRoot,
+ });
await cp(
compileResult.paths.compileDirectoryPath,
join(sourceSnapshotPlan.runtimeAppRoot, ".eve", "compile"),
@@ -139,6 +144,56 @@ export async function stageDevelopmentRuntimeArtifactsSnapshot(
};
}
+async function mountExtensionExternalDependencies(input: {
+ readonly manifest?: CompiledAgentManifest;
+ readonly runtimeAppRoot: string;
+}): Promise<void> {
+ if (input.manifest === undefined) {
+ return;
+ }
+
+ const mounts = [
+ input.manifest,
+ ...(input.manifest.subagents ?? []).map((subagent) => subagent.agent),
+ ]
+ .flatMap((node) => node.extensionMounts ?? [])
+ .filter((mount) => (mount.externalDependencies ?? []).length > 0);
+
+ for (const [dependency, entryPath] of Object.entries(
+ resolveExtensionExternalDependencyPaths(mounts),
+ )) {
+ const packageRoot = findPackageRoot(entryPath, dependency);
+ const mountPath = join(input.runtimeAppRoot, "node_modules", ...dependency.split("/"));
+ await mkdir(dirname(mountPath), { recursive: true });
+ await rm(mountPath, { force: true, recursive: true });
+ await symlink(packageRoot, mountPath, "junction");
+ }
+}
+
+function findPackageRoot(entryPath: string, packageName: string): string {
+ let directory = dirname(entryPath);
+
+ while (true) {
+ const packageJsonPath = join(directory, "package.json");
+ if (existsSync(packageJsonPath)) {
+ try {
+ const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { name?: unknown };
+ if (pkg.name === packageName) {
+ return directory;
+ }
+ } catch {}
+ }
+
+ const parent = dirname(directory);
+ if (parent === directory) {
+ throw new Error(
+ `Cannot locate package root for extension external dependency "${packageName}".`,
+ );
+ }
+ directory = parent;
+ }
+}
+
/**
* Moves the dev runtime pointer so future sessions use a staged snapshot.
*/
diff --git a/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts b/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts
index 847df3a66..1bcec6fad 100644
--- a/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts
+++ b/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts
@@ -81,6 +81,45 @@ describe("extension build output", () => {
);
});
+ it("stamps extension-owned external dependencies into compatibility metadata", async () => {
+ const root = await createExtensionPackage({
+ dependencies: { "layout-sensitive-runtime": "1.0.0" },
+ eve: {
+ extension: {
+ source: "extension",
+ dist: "dist/extension",
+ externalDependencies: ["layout-sensitive-runtime"],
+ },
+ },
+ });
+ const config = await tryReadExtensionBuildConfig(root);
+ const outDir = await buildExtensionPackage(root, config!);
+ const manifestPath = join(outDir, "extension", "_manifest.json");
+
+ expect(
+ parseExtensionCompatibilityManifest(await readFile(manifestPath, "utf8"), manifestPath),
+ ).toMatchObject({
+ formatVersion: 2,
+ build: { externalDependencies: ["layout-sensitive-runtime"] },
+ });
+ });
+
+ it("rejects external dependencies without a runtime package declaration", async () => {
+ const root = await createExtensionPackage({
+ eve: {
+ extension: {
+ source: "extension",
+ dist: "dist/extension",
+ externalDependencies: ["layout-sensitive-runtime"],
+ },
+ },
+ });
+
+ await expect(tryReadExtensionBuildConfig(root)).rejects.toThrow(
+ /Missing runtime declarations: layout-sensitive-runtime/,
+ );
+ });
+
it("preserves shared module identity across transformed contribution entries", async () => {
const root = await createExtensionPackage();
await mkdir(join(root, "extension", "lib"), { recursive: true });
diff --git a/packages/eve/src/internal/nitro/host/build-extension.ts b/packages/eve/src/internal/nitro/host/build-extension.ts
index 3a2155dc6..3147b3508 100644
--- a/packages/eve/src/internal/nitro/host/build-extension.ts
+++ b/packages/eve/src/internal/nitro/host/build-extension.ts
@@ -84,6 +84,9 @@ export async function buildExtensionPackage(
kind: EXTENSION_COMPATIBILITY_MANIFEST_KIND,
formatVersion: EXTENSION_COMPATIBILITY_MANIFEST_FORMAT_VERSION,
builtWithEve: resolveInstalledPackageInfo().version,
+ ...(config.externalDependencies.length === 0
+ ? {}
+ : { build: { externalDependencies: config.externalDependencies } }),
requires: await deriveExtensionCapabilityRequirements({
declarationModule,
manifest,
diff --git a/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts b/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts
index 808b1da10..16b417508 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts
@@ -570,6 +570,47 @@ describe("application Nitro creation", () => {
expect(traceDeps).not.toContain("eve");
});
+ it("fully traces dependencies requested by mounted extensions", async () => {
+ const nitroStub = createNitroStub();
+ createNitroMock.mockResolvedValueOnce(nitroStub.nitro);
+
+ const { createProductionApplicationNitro } =
+ await import("#internal/nitro/host/create-application-nitro.js");
+ const preparedHost = createPreparedHost();
+ preparedHost.compileResult.manifest.extensionMounts = [
+ {
+ externalDependencies: ["zod", "sharp"],
+ mountLogicalPath: "extensions/layout.ts",
+ mountSourceId: "extensions/layout.ts",
+ namespace: "layout",
+ packageName: "layout-extension",
+ packageNamespace: "layout-extension",
+ sourceRoot: process.cwd(),
+ },
+ ];
+ preparedHost.compileResult.manifest.config = {
+ ...preparedHost.compileResult.manifest.config,
+ build: { externalDependencies: ["sharp"] },
+ } as typeof preparedHost.compileResult.manifest.config;
+
+ await createProductionApplicationNitro(preparedHost, createProductionOptions(preparedHost));
+
+ const traceDeps = createNitroMock.mock.calls[0]?.[0].traceDeps;
+ expect(traceDeps).toEqual(expect.arrayContaining(["zod*", "sharp", "sharp*"]));
+ const plugins = createNitroMock.mock.calls[0]?.[0].rolldownConfig.plugins;
+ const externalPlugin = plugins.find(
+ (plugin: { name?: string }) => plugin.name === "eve-extension-external-dependency",
+ );
+ expect(externalPlugin.resolveId("zod")).toEqual({
+ external: true,
+ id: "zod",
+ });
+ expect(createNitroMock.mock.calls[0]?.[0].traceOpts.nft.paths).toEqual({
+ zod: expect.stringMatching(/zod[/\\].*index\.(?:c?js|mjs)$/),
+ sharp: expect.stringMatching(/sharp[/\\]lib[/\\]index\.js$/),
+ });
+ });
+
it("traces configured hosted dependencies from subagent configs", async () => {
const nitroStub = createNitroStub();
createNitroMock.mockResolvedValueOnce(nitroStub.nitro);
diff --git a/packages/eve/src/internal/nitro/host/create-application-nitro.ts b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
index a34a0b577..ba3ad09b1 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
@@ -18,6 +18,10 @@ import {
import { createProductionNitroArtifactsConfig } from "#internal/nitro/host/artifacts-config.js";
import { createCompiledSandboxBackendPrunePlugin } from "#internal/nitro/host/compiled-sandbox-backend-prune-plugin.js";
import { createExtensionScopePlugin } from "#internal/bundler/extension-scope-plugin.js";
+import {
+ createExtensionExternalDependencyPlugin,
+ resolveExtensionExternalDependencyPaths,
+} from "#internal/nitro/host/extension-external-dependency-plugin.js";
import {
configureDevelopmentNitroRoutes,
configureProductionNitroRoutes,
@@ -100,6 +104,9 @@ function collectHostedTraceDependencies(
preparedHost: PreparedApplicationHost,
configuredOptionalEnginePackages: readonly string[],
): string[] {
+ const extensionExternalDependencies = new Set(
+ collectExtensionExternalDependencies(preparedHost.compileResult.manifest),
+ );
const configuredExternalDependencies = [
...(preparedHost.compileResult.manifest.config.build?.externalDependencies ?? []),
...preparedHost.compileResult.manifest.subagents.flatMap((subagent) =>
@@ -121,8 +128,18 @@ function collectHostedTraceDependencies(
// output.
...configuredOptionalEnginePackages,
...configuredExternalDependencies,
+ ...[...extensionExternalDependencies].map((dependencyName) => `${dependencyName}*`),
]);
- return [...merged].filter((dependencyName) => dependencyName !== EVE_PACKAGE_NAME);
+ return [...merged].filter(
+ (dependencyName) =>
+ dependencyName !== EVE_PACKAGE_NAME && dependencyName !== `${EVE_PACKAGE_NAME}*`,
+ );
+}
+
+function collectExtensionExternalDependencies(manifest: CompiledAgentManifest): string[] {
+ return [manifest, ...manifest.subagents.map((subagent) => subagent.agent)].flatMap((node) =>
+ node.extensionMounts.flatMap((mount) => mount.externalDependencies),
+ );
}
/**
@@ -634,9 +651,14 @@ function createApplicationNitroBundlerConfiguration(
})),
),
);
+ const extensionMounts = [
+ preparedHost.compileResult.manifest,
+ ...preparedHost.compileResult.manifest.subagents.map((subagent) => subagent.agent),
+ ].flatMap((node) => node.extensionMounts);
const nitroBundlerPlugins = [
compiledSandboxBackendPrunePlugin,
createOptionalEngineDependencyPlugin(unconfiguredOptionalEnginePackages),
+ createExtensionExternalDependencyPlugin(extensionMounts),
extensionScopePlugin,
].filter((plugin) => plugin !== null);
const nitroRolldownConfig = createNitroBundlerConfig(nitroBundlerPlugins);
@@ -645,11 +667,13 @@ function createApplicationNitroBundlerConfiguration(
preparedHost,
configuredOptionalEnginePackages,
);
+ const tracedAppDependencyPaths = resolveExtensionExternalDependencyPaths(extensionMounts);
return {
nitroRolldownConfig,
nitroRollupConfig,
tracedAppDependencies,
+ tracedAppDependencyPaths,
};
}
@@ -756,6 +780,7 @@ export async function createDevelopmentApplicationNitro(
rootDir: preparedHost.appRoot,
serverDir: false,
traceDeps: bundler.tracedAppDependencies,
+ traceOpts: { nft: { paths: bundler.tracedAppDependencyPaths } },
vercel: createEveVercelOptions({
agentName: preparedHost.compileResult.manifest.config.name,
enabled: false,
@@ -827,6 +852,7 @@ export async function createProductionApplicationNitro(
rootDir: preparedHost.appRoot,
serverDir: false,
traceDeps: bundler.tracedAppDependencies,
+ traceOpts: { nft: { paths: bundler.tracedAppDependencyPaths } },
vercel: createEveVercelOptions({
agentName: preparedHost.compileResult.manifest.config.name,
enabled: preset === "vercel",
diff --git a/packages/eve/src/internal/nitro/host/dev-authored-rebuild-coordinator.test.ts b/packages/eve/src/internal/nitro/host/dev-authored-rebuild-coordinator.test.ts
index 488d2e888..7e18d9e05 100644
--- a/packages/eve/src/internal/nitro/host/dev-authored-rebuild-coordinator.test.ts
+++ b/packages/eve/src/internal/nitro/host/dev-authored-rebuild-coordinator.test.ts
@@ -157,6 +157,7 @@ describe("transactional authored rebuild coordinator", () => {
outDir: "/tmp/eve-test/packages/crm/dist",
packageName: "@acme/crm",
runtimeDependencies: ["eve"],
+ externalDependencies: [],
shortName: "crm",
},
} as const;
diff --git a/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts b/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts
index bac8fa316..68f9f4bc0 100644
--- a/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts
+++ b/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts
@@ -296,6 +296,7 @@ describe("startAuthoredSourceWatcher", () => {
outDir,
packageName: "@acme/crm",
runtimeDependencies: ["eve"],
+ externalDependencies: [],
shortName: "crm",
},
},
diff --git a/packages/eve/src/internal/nitro/host/extension-build-config.ts b/packages/eve/src/internal/nitro/host/extension-build-config.ts
index a557116c3..09f3691c0 100644
--- a/packages/eve/src/internal/nitro/host/extension-build-config.ts
+++ b/packages/eve/src/internal/nitro/host/extension-build-config.ts
@@ -16,6 +16,8 @@ export interface ExtensionBuildConfig {
readonly shortName: string;
/** Packages allowed to remain as imports in the published distribution. */
readonly runtimeDependencies: readonly string[];
+ /** Runtime packages the consuming application must preserve outside generated bundles. */
+ readonly externalDependencies: readonly string[];
}
/** Reads and validates the extension producer contract from `package.json`. */
@@ -65,19 +67,30 @@ export async function tryReadExtensionBuildConfig(
const packageName = typeof pkg.name === "string" && pkg.name.length > 0 ? pkg.name : "extension";
const bareName = packageName.slice(packageName.lastIndexOf("/") + 1);
+ const runtimeDependencies = [
+ ...new Set([
+ ...Object.keys(pkg.dependencies ?? {}),
+ ...Object.keys(pkg.optionalDependencies ?? {}),
+ ...Object.keys(pkg.peerDependencies ?? {}),
+ ]),
+ ].sort();
+ const externalDependencies = [...(extension.externalDependencies ?? [])].sort();
+ const undeclaredExternalDependencies = externalDependencies.filter(
+ (dependency) => !runtimeDependencies.includes(dependency),
+ );
+ if (undeclaredExternalDependencies.length > 0) {
+ throw new Error(
+ `\`eve.extension.externalDependencies\` must name packages declared in dependencies, optionalDependencies, or peerDependencies. Missing runtime declarations: ${undeclaredExternalDependencies.join(", ")}.`,
+ );
+ }
return {
sourceRoot,
distRoot,
outDir,
packageName,
shortName: safeJsIdentifier(bareName),
- runtimeDependencies: [
- ...new Set([
- ...Object.keys(pkg.dependencies ?? {}),
- ...Object.keys(pkg.optionalDependencies ?? {}),
- ...Object.keys(pkg.peerDependencies ?? {}),
- ]),
- ].sort(),
+ runtimeDependencies,
+ externalDependencies,
};
}
diff --git a/packages/eve/src/internal/nitro/host/extension-external-dependency-plugin.test.ts b/packages/eve/src/internal/nitro/host/extension-external-dependency-plugin.test.ts
new file mode 100644
index 000000000..821b7a4db
--- /dev/null
+++ b/packages/eve/src/internal/nitro/host/extension-external-dependency-plugin.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ createExtensionExternalDependencyPlugin,
+ resolveExtensionExternalDependencyPaths,
+} from "#internal/nitro/host/extension-external-dependency-plugin.js";
+
+describe("extension external dependency plugin", () => {
+ it("resolves configured packages from the mounted extension", () => {
+ const plugin = createExtensionExternalDependencyPlugin([
+ {
+ externalDependencies: ["zod"],
+ sourceRoot: process.cwd(),
+ },
+ ]);
+
+ expect(plugin?.resolveId("zod")).toEqual({ external: true, id: "zod" });
+ expect(plugin?.resolveId("layout-sensitive-runtime-extra")).toBeNull();
+ expect(plugin?.resolveId("unconfigured-runtime")).toBeNull();
+ });
+
+ it("omits the plugin without extension requirements", () => {
+ expect(createExtensionExternalDependencyPlugin([])).toBeNull();
+ });
+
+ it("resolves tracer paths from mounted extension packages", () => {
+ expect(
+ resolveExtensionExternalDependencyPaths([
+ { externalDependencies: ["zod"], sourceRoot: process.cwd() },
+ ]),
+ ).toEqual({ zod: expect.stringMatching(/zod[/\\].*index\.(?:c?js|mjs)$/) });
+ });
+});
diff --git a/packages/eve/src/internal/nitro/host/extension-external-dependency-plugin.ts b/packages/eve/src/internal/nitro/host/extension-external-dependency-plugin.ts
new file mode 100644
index 000000000..55a82c19e
--- /dev/null
+++ b/packages/eve/src/internal/nitro/host/extension-external-dependency-plugin.ts
@@ -0,0 +1,71 @@
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+interface BundlerPluginShape {
+ readonly name: string;
+ resolveId(source: string): { external: true; id: string } | null;
+}
+
+interface ExtensionExternalDependencyMount {
+ readonly externalDependencies: readonly string[];
+ readonly sourceRoot: string;
+}
+
+/** Keeps extension-owned runtime packages external so Nitro can preserve their full package trees. */
+export function createExtensionExternalDependencyPlugin(
+ mounts: readonly ExtensionExternalDependencyMount[],
+): BundlerPluginShape | null {
+ const dependencyAnchors = collectDependencyAnchors(mounts);
+ if (dependencyAnchors.size === 0) {
+ return null;
+ }
+
+ return {
+ name: "eve-extension-external-dependency",
+ resolveId(source) {
+ const dependency = [...dependencyAnchors.keys()].find(
+ (packageName) => source === packageName || source.startsWith(`${packageName}/`),
+ );
+ if (dependency === undefined) {
+ return null;
+ }
+ return { external: true, id: source };
+ },
+ };
+}
+
+/** Resolves package entries for Nitro's nft tracer from the mounted extension package. */
+export function resolveExtensionExternalDependencyPaths(
+ mounts: readonly ExtensionExternalDependencyMount[],
+): Record<string, string> {
+ const resolvedPaths: Record<string, string> = {};
+ for (const [dependency, anchors] of collectDependencyAnchors(mounts)) {
+ for (const anchor of anchors) {
+ try {
+ resolvedPaths[dependency] = createRequire(anchor).resolve(dependency);
+ break;
+ } catch {}
+ }
+ if (resolvedPaths[dependency] === undefined) {
+ throw new Error(
+ `Cannot resolve extension external dependency "${dependency}" from its mounted extension package.`,
+ );
+ }
+ }
+ return resolvedPaths;
+}
+
+function collectDependencyAnchors(
+ mounts: readonly ExtensionExternalDependencyMount[],
+): Map<string, string[]> {
+ const dependencyAnchors = new Map<string, string[]>();
+ for (const mount of mounts) {
+ for (const dependency of mount.externalDependencies) {
+ const anchors = dependencyAnchors.get(dependency) ?? [];
+ anchors.push(join(realpathSync(mount.sourceRoot), "_manifest.json"));
+ dependencyAnchors.set(dependency, anchors);
+ }
+ }
+ return dependencyAnchors;
+}
diff --git a/packages/eve/src/shared/extension-package-contract.test.ts b/packages/eve/src/shared/extension-package-contract.test.ts
index fb597c425..a04e85893 100644
--- a/packages/eve/src/shared/extension-package-contract.test.ts
+++ b/packages/eve/src/shared/extension-package-contract.test.ts
@@ -4,9 +4,16 @@ import { parseExtensionPackageRoots } from "#shared/extension-package-contract.j
describe("parseExtensionPackageRoots", () => {
it("parses source and dist roots", () => {
- expect(parseExtensionPackageRoots({ source: "extension", dist: "dist/extension" })).toEqual({
+ expect(
+ parseExtensionPackageRoots({
+ source: "extension",
+ dist: "dist/extension",
+ externalDependencies: ["sharp", "sharp", "@acme/runtime"],
+ }),
+ ).toEqual({
source: "extension",
dist: "dist/extension",
+ externalDependencies: ["sharp", "@acme/runtime"],
});
});
@@ -26,6 +33,18 @@ describe("parseExtensionPackageRoots", () => {
expect(parseExtensionPackageRoots({ source: 7, dist: "dist/extension" })).toBeNull();
});
+ it("rejects invalid external dependency declarations", () => {
+ expect(
+ parseExtensionPackageRoots({ dist: "dist/extension", externalDependencies: "sharp" }),
+ ).toBeNull();
+ expect(
+ parseExtensionPackageRoots({ dist: "dist/extension", externalDependencies: [""] }),
+ ).toBeNull();
+ expect(
+ parseExtensionPackageRoots({ dist: "dist/extension", externalDependencies: [7] }),
+ ).toBeNull();
+ });
+
it("rejects non-object contracts", () => {
expect(parseExtensionPackageRoots("extension")).toBeNull();
expect(parseExtensionPackageRoots(["extension"])).toBeNull();
diff --git a/packages/eve/src/shared/extension-package-contract.ts b/packages/eve/src/shared/extension-package-contract.ts
index f5d897581..a26bcd07e 100644
--- a/packages/eve/src/shared/extension-package-contract.ts
+++ b/packages/eve/src/shared/extension-package-contract.ts
@@ -6,6 +6,8 @@ export interface ExtensionPackageRoots {
*/
readonly source?: string;
readonly dist: string;
+ /** Runtime packages the consuming application must preserve outside generated bundles. */
+ readonly externalDependencies?: readonly string[];
}
/** Parses the strict `package.json#eve.extension` object contract. */
@@ -13,8 +15,27 @@ export function parseExtensionPackageRoots(value: unknown): ExtensionPackageRoot
if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
const record = value as Record<string, unknown>;
if (typeof record.dist !== "string" || record.dist.length === 0) return null;
- if (record.source === undefined) return { dist: record.dist };
+ const externalDependencies = parseExternalDependencies(record.externalDependencies);
+ if (externalDependencies === null) return null;
+ const roots: { dist: string; externalDependencies?: readonly string[] } = {
+ dist: record.dist,
+ };
+ if (externalDependencies !== undefined) {
+ roots.externalDependencies = externalDependencies;
+ }
+ if (record.source === undefined) return roots;
return typeof record.source === "string" && record.source.length > 0
- ? { source: record.source, dist: record.dist }
+ ? { ...roots, source: record.source }
: null;
}
+
+function parseExternalDependencies(value: unknown): readonly string[] | undefined | null {
+ if (value === undefined) return undefined;
+ if (!Array.isArray(value)) return null;
+ const dependencies = new Set<string>();
+ for (const dependency of value) {
+ if (typeof dependency !== "string" || dependency.length === 0) return null;
+ dependencies.add(dependency);
+ }
+ return [...dependencies];
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0317d3e25..7b23ca279 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -421,7 +421,7 @@ importers:
version: 0.41.2
'@vercel/connect':
specifier: 'catalog:'
ai:
specifier: 'catalog:'
version: 7.0.58([email protected])
@@ -16400,21 +16400,6 @@ snapshots:
- utf-8-validate
- zod
- dependencies:
- transitivePeerDependencies:
- - ai
- - bufferutil
- - debug
- - supports-color
- - utf-8-validate
- - zod
- optional: true
-
dependencies:
@@ -21862,13 +21847,13 @@ snapshots:
ai: 6.0.191([email protected])
eve: link:packages/eve
dependencies:
'@vercel/oidc': 3.8.1
optionalDependencies:
'@ai-sdk/mcp': 2.0.29([email protected])
'@auth/core': 0.41.2
ai: 7.0.58([email protected])
eve: link:packages/eve
diff --git a/research/extension-distribution-compatibility.md b/research/extension-distribution-compatibility.md
deleted file mode 100644
index a443c5e0e..000000000
--- a/research/extension-distribution-compatibility.md
+++ /dev/null
@@ -1,318 +0,0 @@
----
-issue: TBD
-last_updated: "2026-07-17"
-status: proposed
----
-
-# Extension distribution and compatibility
-
-## Summary
-
-eve extensions should publish a built, agent-shaped distribution tree while the consuming
-application's eve remains responsible for discovery, validation, normalization, namespacing, and
-final bundling. The npm package need not contain the author's original TypeScript, but it does not
-ship eve-internal compiled definitions either. This is a **source-backed execution contract with a
-dist-only publication contract**.
-
-Compatibility is independent of eve's package version. `eve extension build` generates a small
-manifest containing only the extension capabilities the package uses and the contract version it
-requires for each one. A skills contract change therefore cannot invalidate a tools-only
-extension. npm provides the consumer's singleton eve through a required wildcard peer; eve itself
-performs compatibility validation from the generated manifest.
-
-Local workspace extensions use the same dist tree as published packages. `eve dev` watches their
-real source roots, rebuilds affected extension dist trees transactionally, then reuses the existing
-agent-generation reload path. Development therefore exercises the package that will be published
-without requiring a second source-resolution mode.
-
-## Package contract
-
-An extension has distinct authoring and distribution roots:
-
-```jsonc
-{
- "name": "@acme/crm",
- "type": "module",
- "files": ["dist"],
- "eve": {
- "extension": {
- "source": "./extension",
- "dist": "./dist/extension",
- },
- },
- "exports": {
- ".": {
- "types": "./dist/index.d.ts",
- "default": "./dist/index.mjs",
- },
- "./tools": {
- "types": "./dist/tools/index.d.ts",
- "default": "./dist/tools/index.mjs",
- },
- },
- "peerDependencies": {
- "eve": "*",
- },
- "devDependencies": {
- "eve": "^0.24.6",
- },
-}
-```
-
-`source` is build input and is not published by default. `dist` is the only tree a consuming app
-mounts. `eve extension build` owns the managed exports and emits:
-
-```text
-dist/
- extension/
- _manifest.json
- extension.mjs
- tools/search.mjs
- skills/triage/SKILL.md
- lib/client.mjs
- index.mjs
- index.d.ts
- tools/index.mjs
- tools/index.d.ts
-```
-
-The build transforms JavaScript and TypeScript modules individually while preserving their logical
-paths and relative module graph. Markdown, skill packages, scripts, references, and assets are
-copied without changing their semantics. Generated entrypoints re-export modules from the dist
-tree so the mount, consumer overrides, and compiled agent share the same module identities. Publish
-artifacts do not embed source maps containing the author's source text.
-
-The consuming eve walks `dist`, loads its public definitions through the consumer's `eve/*`
-exports, and produces the consuming agent's internal compiled manifest. Internal types such as
-`CompiledToolDefinition` are never a package-level extension ABI.
-
-## Dependency semantics
-
-`eve` is a required peer with the wildcard range. The peer exists to make package managers resolve
-extension imports against the application's singleton eve; it does not express extension
-compatibility. `peerDependenciesMeta.eve.optional` is deliberately absent because an extension
-cannot operate without eve. The application should declare eve directly, while the extension's
-concrete dev dependency provides authoring types and build tooling.
-
-Everything the distributed extension imports at execution time belongs in `dependencies`.
-Build-only and test-only packages belong in `devDependencies`. A package that must share the
-consumer's instance may be a peer, and an integration that is genuinely optional may use optional
-peer metadata. An extension must never carry its own runtime `eve` dependency.
-
-The wildcard peer keeps npm semver out of capability compatibility for stable eve releases. Strict
-install tests must also cover eve prereleases. If package managers cannot represent the supported
-prerelease policy without warnings, the fallback is to remove the peer and make the eve compiler
-alias extension `eve/*` imports explicitly; marking the peer optional does not solve a present-peer
-version mismatch.
-
-## Generated compatibility manifest
-
-`dist/extension/_manifest.json` is generated and validated as data:
-
-```json
-{
- "kind": "eve-extension",
- "formatVersion": 1,
- "builtWithEve": "0.24.6",
- "requires": {
- "extension": 1,
- "tool": 1,
- "config": 1
- }
-}
-```
-
-The fields have separate meanings:
-
-- `formatVersion` versions this JSON schema, not extension behavior.
-- `builtWithEve` is diagnostic information only.
-- `requires` contains only extension-facing contracts used by this package.
-
-The initial capability vocabulary is `extension`, `tool`, `dynamicTool`, `connection`, `hook`,
-`skill`, `dynamicSkill`, `instructions`, `dynamicInstructions`, `config`, and `state`.
-`extension` is the small universal mount, module-loading, and filesystem contract. Other
-capabilities remain independent unless their semantics truly share a contract.
-
-The build derives requirements rather than asking authors to maintain them:
-
-- Static and dynamic slot files require their matching capability.
-- Declaring a config schema requires `config`; a no-config declaration does not.
-- Importing and using `defineState` requires `state`; it is not stamped on every extension.
-- Capability dependencies are expanded, such as `dynamicTool` requiring `tool` and
- `dynamicSkill` requiring `skill`.
-- Every extension requires `extension`.
-
-The manifest may gain a file inventory later if it materially improves discovery, but the
-filesystem remains authoritative in the first version. It does not serialize schemas, normalized
-definitions, executable functions, or other compiler output.
-
-## Capability version semantics
-
-Each eve release declares all capability versions it can consume, not just one current value:
-
-```ts
-const EXTENSION_CAPABILITY_SUPPORT = {
- extension: [1],
- tool: [1, 2],
- skill: [2],
- config: [1],
- state: [1],
-} as const;
-```
-
-Consumer validation checks only keys present in the extension's `requires` map and succeeds when
-the required version appears in the consumer's supported set. Unknown capability names and unknown
-versions fail closed before any extension module executes.
-
-A capability version advances when a newly built extension can require behavior an older consumer
-cannot interpret. A newer eve should retain older versions through an adapter whenever practical.
-If an incompatible change cannot be adapted, the new eve drops the old version from its supported
-set; only extensions using that capability become incompatible. Changes outside extension-facing
-contracts do not alter any capability version.
-
-Examples:
-
-- A skills-only contract change advances `skill`; a tools-only extension remains valid.
-- A new tool feature advances `tool` to 2. A newer eve can support `[1, 2]`, keeping existing tool
- extensions valid while rejecting tool-v2 extensions on older consumers.
-- A state scoping change advances `state` without affecting extensions that do not call
- `defineState`.
-- A universal change to mounting or path interpretation advances `extension`; this should be rare.
-
-Compatibility errors name the extension package, capability, required version, supported versions,
-and an actionable upgrade or downgrade:
-
-```text
-Extension "@acme/crm" requires tool contract v2, but this eve supports tool contract v1.
-Upgrade eve or install an extension release that requires tool v1.
-```
-
-## Consumer lifecycle
-
-For an installed extension, agent compilation proceeds in this order:
-
-1. Resolve the mount package and its package root without executing the mount.
-2. Read `package.json#eve.extension.dist` and the generated manifest.
-3. Validate the manifest format and each required capability.
-4. Discover the agent-shaped dist tree and compose its contributions under the mount namespace.
-5. Evaluate the consumer's mount module to bind extension config.
-6. Normalize extension definitions with the consuming eve and include their modules in the final
- agent bundle.
-
-Missing, malformed, or incompatible manifests fail the build before extension code runs. There is
-no fallback to author source for an installed package and no fallback to a legacy compiled
-artifact. Local and registry packages therefore have the same consumer semantics.
-
-### Namespacing and overrides
-
-Distribution does not change composition. Modules in `dist/extension` retain their bare,
-path-derived names; the consumer's mount path still supplies the namespace (`crm` + `search` →
-`crm__search`). Directory overrides under `agent/extensions/crm/` compose into that same namespace
-and win on collision, while `disableTool()` removes the matching extension tool. The generated
-`@acme/crm/tools` barrel re-exports the exact dist modules discovery consumes so overrides and
-runtime helpers share module identity.
-
-Config and durable state remain scoped to the extension package name, separately from the mount
-namespace. Renaming a consumer mount therefore changes model-facing contribution names without
-orphaning package state. The compatibility manifest only gates contracts; it does not participate
-in naming, merge precedence, or disable behavior.
-
-## Workspace development and HMR
-
-Workspace development keeps the published dist contract and automates its producer step. A local
-extension is one whose resolved package root realpaths into the application's workspace source
-root; detection is based on the filesystem rather than `workspace:` syntax so linked and `file:`
-packages behave consistently.
-
-At `eve dev` startup:
-
-1. Resolve mounted packages far enough to read their source/dist roots.
-2. Identify local extensions and build them before the initial agent compile.
-3. Record each canonical source root and its build configuration.
-4. Add those source roots to the authored-source watcher.
-
-When a watched extension source changes:
-
-```text
-extension source change
- |
- v
-build affected dist tree in a temporary location
- |
- v
-atomically replace the managed dist tree
- |
- v
-prepare and compile the next agent generation
- |
- v
-activate it through the existing transactional reload
-```
-
-Only affected extensions rebuild. Added and removed contributions cleanly add or remove dist
-outputs; edits to skills and assets recopy their content. Generated `dist` paths remain ignored by
-the source watcher, preventing rebuild loops. A failed extension build leaves both its previous
-dist tree and the currently serving agent generation intact. Changes to an extension's local
-workspace dependencies still trigger an agent rebuild through the existing transitive workspace
-watch plan; the extension itself only needs rebuilding when its managed source tree changes.
-
-This is an eve development reload rather than browser-style component HMR: the server remains
-available while eve builds and atomically activates a new immutable agent generation. Directly
-resolving workspace TypeScript through a development-only export condition is intentionally
-avoided because it would give local extensions different entrypoints, barrels, and module identity
-from their published packages.
-
-## Build and runtime invariants
-
-- Published extensions contain the dist tree and generated manifest; original TypeScript is not
- required.
-- The consumer, not the extension author, owns normalization into eve's internal compiled model.
-- npm peer ranges never decide capability compatibility.
-- Only used capabilities can invalidate an extension.
-- Extension capability validation completes before authored extension code executes.
-- Extension entrypoints and tool barrels re-export the same dist modules discovery consumes.
-- Workspace HMR builds the same dist contract registry consumers install.
-- Failed development rebuilds never replace a valid dist tree or live generation.
-
-## Migration from the contribution artifact
-
-The producer-side contribution manifest on the current branch should become the compatibility
-manifest described here:
-
-- Retain versioned parsing, serialization, `builtWithEve`, and the capability vocabulary.
-- Add the universal `extension` capability.
-- Replace exact current-version comparison with supported-version membership.
-- Stop stamping `config` and `state` unconditionally.
-- Remove serialized compiled contributions and the compiler schemas they expose.
-- Keep source compilation and namespacing on the existing consumer path.
-- Change the scaffold to distinct source/dist roots, `files: ["dist"]`, and a required wildcard eve
- peer.
-- Replace discovery's `peerDependencies.eve` compatibility check with manifest capability
- validation.
-- Extend `eve dev` to prebuild and transactionally rebuild local mounted extensions.
-
-A genuinely pre-normalized extension may be designed later as a separate artifact kind with an
-explicit ABI. It is not a fallback or alternate interpretation of this manifest.
-
-## Verification
-
-Use the narrowest test tier for each contract:
-
-- Unit: manifest schema, unknown capability rejection, supported-version membership, capability
- dependency expansion, and config/state usage detection.
-- Integration: extension build emits a complete dist tree and manifest; entrypoints reference dist
- modules; consumer discovery ignores author source; unrelated capability changes remain valid.
-- Scenario: a mounted workspace extension hot-reloads edits, additions, removals, config, skills,
- and assets; failed builds preserve the prior generation; generated dist writes do not loop.
-- Package-manager fixtures: packed extensions install under npm `--strict-peer-deps`, strict pnpm,
- and Yarn with multiple stable and prerelease eve versions, without acquiring a private eve copy.
-- E2E: registry-installed extension fixtures publish dist only and continue to boot, accept a
- request, and execute namespaced tools in CI.
-
-The implementation changes the published `eve` package and requires a patch changeset. Public docs
-must describe the source/dist split, capability diagnostics, required wildcard peer, and automatic
-workspace development behavior.
-
-## Open issue
-
-File a tracking issue and replace the frontmatter placeholder before landing.