The Open Framework for Building Agents
fix(eve): scope flat extension instructions (#2592)
Casey Gowriefdba4e0a6542
diff --git a/.changeset/scope-extension-instructions.md b/.changeset/scope-extension-instructions.mdnew file mode 100644index 000000000..9e264b101--- /dev/null+++ b/.changeset/scope-extension-instructions.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Scope every extension contribution through one mount-namespace policy so multiple extensions can contribute flat `instructions.md` files without collisions. Extension-owned agent singleton slots such as instrumentation are now rejected during discovery.diff --git a/docs/extensions.md b/docs/extensions.mdindex 8db655074..dfef7c248 100644--- a/docs/extensions.md+++ b/docs/extensions.md@@ -43,9 +43,9 @@ Each listed slot accepts the same authored forms as its agent counterpart. StatiNames come from paths, so call the tool `search`, not `crm_search`; the consumer's mount adds the `crm__` prefix. The same prefix applies to channel, schedule, and parent-visible subagent IDs, while channel route paths and schedule cron expressions stay unchanged. Keep shared code in `extension/lib/`.-The extension root cannot declare agent configuration, [memory](./memory), a-sandbox, or nested extensions. Memory scope and lifecycle state belong to the-consuming application. A subagent contributed under+The extension root cannot declare agent configuration, instrumentation,+[memory](./memory), a sandbox, or nested extensions. Those agent-level concerns+belong to the consuming application. A subagent contributed under`extension/subagents/` owns its own agent configuration, memory, and sandboxlike any other [declared subagent](./subagents).diff --git a/e2e/fixtures/extensions/agent/mock-responder.ts b/e2e/fixtures/extensions/agent/mock-responder.tsindex e32a44b77..acc52f4b3 100644--- a/e2e/fixtures/extensions/agent/mock-responder.ts+++ b/e2e/fixtures/extensions/agent/mock-responder.ts@@ -1,9 +1,21 @@import type { MockModelRequest, MockModelResponse } from "eve/evals";+const GIZMO_INSTRUCTIONS_TOKEN = "gizmo-instructions-ok-7K2M";+const JAVASCRIPT_INSTRUCTIONS_TOKEN = "javascript-instructions-ok-9P4R";const LAYOUT_TOOL = "gizmo__gizmo_layout";export function respond(request: MockModelRequest): MockModelResponse | string {const message = request.lastUserMessage ?? "";+ if (message.includes("Report both extension instruction tokens")) {+ const instructions = request.messages+ .filter((entry) => entry.role === "system")+ .map((entry) => entry.text)+ .join("\n");+ return [GIZMO_INSTRUCTIONS_TOKEN, JAVASCRIPT_INSTRUCTIONS_TOKEN]+ .filter((token) => instructions.includes(token))+ .join(" ");+ }+if (!message.includes(`Call \`${LAYOUT_TOOL}\``)) {return `Mock reply: ${message}`;}diff --git a/e2e/fixtures/extensions/evals/extension-instructions.eval.ts b/e2e/fixtures/extensions/evals/extension-instructions.eval.tsnew file mode 100644index 000000000..1b04ae166--- /dev/null+++ b/e2e/fixtures/extensions/evals/extension-instructions.eval.ts@@ -0,0 +1,17 @@+import { defineEval } from "eve/evals";++const GIZMO_INSTRUCTIONS_TOKEN = "gizmo-instructions-ok-7K2M";+const JAVASCRIPT_INSTRUCTIONS_TOKEN = "javascript-instructions-ok-9P4R";++export default defineEval({+ description: "Flat instructions from multiple extensions coexist on one agent.",+ async test(t) {+ await t.send(+ "Report both extension instruction tokens exactly. Do not call tools or add other text.",+ );++ t.succeeded();+ t.messageIncludes(GIZMO_INSTRUCTIONS_TOKEN);+ t.messageIncludes(JAVASCRIPT_INSTRUCTIONS_TOKEN);+ },+});diff --git a/e2e/fixtures/gizmo-extension/extension/instructions.md b/e2e/fixtures/gizmo-extension/extension/instructions.mdnew file mode 100644index 000000000..f349c906e--- /dev/null+++ b/e2e/fixtures/gizmo-extension/extension/instructions.md@@ -0,0 +1 @@+The gizmo extension instruction token is `gizmo-instructions-ok-7K2M`.diff --git a/e2e/fixtures/js-only-extension/extension/instructions.md b/e2e/fixtures/js-only-extension/extension/instructions.mdnew file mode 100644index 000000000..0c64743e6--- /dev/null+++ b/e2e/fixtures/js-only-extension/extension/instructions.md@@ -0,0 +1 @@+The JavaScript extension instruction token is `javascript-instructions-ok-9P4R`.diff --git a/packages/eve/src/compiler/project-sources.test.ts b/packages/eve/src/compiler/project-sources.test.tsnew file mode 100644index 000000000..e40c937ea--- /dev/null+++ b/packages/eve/src/compiler/project-sources.test.ts@@ -0,0 +1,59 @@+import { describe, expect, it } from "vitest";++import {+ projectAgentSources,+ qualifyExtensionContributionLogicalPath,+} from "#compiler/project-sources.js";+import { createAgentSourceManifest, createModuleSourceRef } from "#discover/manifest.js";++describe("qualifyExtensionContributionLogicalPath", () => {+ it.each([+ ["channels/webhook.ts", "channels/crm__webhook.ts"],+ ["connections/api.ts", "connections/crm__api.ts"],+ ["hooks/audit.ts", "hooks/crm__audit.ts"],+ ["instructions.md", "instructions/crm.md"],+ ["instructions/policy.md", "instructions/crm__policy.md"],+ ["schedules/sync.ts", "schedules/crm__sync.ts"],+ ["skills/triage/SKILL.md", "skills/crm__triage/SKILL.md"],+ ["subagents/reviewer/agent.ts", "subagents/crm__reviewer/agent.ts"],+ ["tools/search.ts", "tools/crm__search.ts"],+ ])("scopes %s", (logicalPath, expected) => {+ expect(qualifyExtensionContributionLogicalPath(logicalPath, "crm")).toBe(expected);+ });++ it.each(["agent.ts", "instrumentation.ts", "memory.ts", "sandbox.ts", "lib/http.ts"])(+ "rejects unscopable slot %s",+ (logicalPath) => {+ expect(() => qualifyExtensionContributionLogicalPath(logicalPath, "crm")).toThrow(+ `Extension source slot "${logicalPath}" cannot be namespace-scoped.`,+ );+ },+ );++ it("applies the selected extension projector to canonical path overrides", () => {+ const extensionManifest = createAgentSourceManifest({+ agentRoot: "/extension",+ appRoot: "/package",+ configModule: createModuleSourceRef({ logicalPath: "custom-agent.ts" }),+ });+ const manifest = createAgentSourceManifest({+ agentRoot: "/app/agent",+ appRoot: "/app",+ resolvedExtensions: [+ {+ namespace: "crm",+ specifier: "@acme/crm",+ packageName: "@acme/crm",+ packageRoot: "/package",+ sourceRoot: "/extension",+ manifest: extensionManifest,+ externalDependencies: [],+ },+ ],+ });++ expect(() =>+ projectAgentSources({ externalDependencies: [], manifest, nodeId: "root" }),+ ).toThrow('Extension source slot "agent.ts" cannot be namespace-scoped.');+ });+});diff --git a/packages/eve/src/compiler/project-sources.ts b/packages/eve/src/compiler/project-sources.tsindex d140d9327..696253e3a 100644--- a/packages/eve/src/compiler/project-sources.ts+++ b/packages/eve/src/compiler/project-sources.ts@@ -107,7 +107,7 @@ export function projectAgentSources(input: {projectManifest({externalDependencies: input.externalDependencies,candidates,- extensionScope: input.extensionScope,+ projection: createApplicationManifestSourceProjection(input.extensionScope),layer: input.layer ?? "application",manifest: input.manifest,nodeId: input.nodeId,@@ -119,6 +119,7 @@ export function projectAgentSources(input: {for (const mount of [...input.manifest.resolvedExtensions].sort((left, right) =>left.namespace.localeCompare(right.namespace),)) {+ const projection = createExtensionManifestSourceProjection(mount);const extensionOwner: AgentSourceOwner = {kind: "extension",namespace: mount.namespace,@@ -130,7 +131,7 @@ export function projectAgentSources(input: {mount.externalDependencies,),candidates,- extension: mount,+ projection,layer: "extension-package",manifest: mount.manifest,nodeId: input.nodeId,@@ -143,7 +144,7 @@ export function projectAgentSources(input: {projectManifest({externalDependencies: input.externalDependencies,candidates,- extension: mount,+ projection,layer: "extension-override",manifest: mount.overrides,nodeId: input.nodeId,@@ -179,7 +180,6 @@ export function projectSelectedSources(input: {export function createFilesystemModuleCandidate(input: {readonly externalDependencies: readonly string[];- readonly extension?: ResolvedExtensionMount;readonly extensionScope?: { readonly namespace: string; readonly sourceRoot: string };readonly layer: AgentSourceLayer;readonly logicalPath: string;@@ -191,14 +191,8 @@ export function createFilesystemModuleCandidate(input: {}): AgentModuleCandidate {const backing = {externalDependencies: [...input.externalDependencies],- ...(input.owner.kind === "extension" &&- (input.extension !== undefined || input.extensionScope !== undefined)- ? {- extensionScope: {- namespace: input.extension?.namespace ?? input.extensionScope!.namespace,- sourceRoot: input.extension?.sourceRoot ?? input.extensionScope!.sourceRoot,- },- }+ ...(input.owner.kind === "extension" && input.extensionScope !== undefined+ ? { extensionScope: input.extensionScope }: {}),kind: "filesystem" as const,sourcePath: join(input.sourceRoot, input.source.logicalPath),@@ -215,11 +209,45 @@ export function createFilesystemModuleCandidate(input: {};}+interface ManifestSourceProjection {+ readonly extensionScope?: { readonly namespace: string; readonly sourceRoot: string };+ readonly logicalPath: (logicalPath: string) => string;+ readonly name: (name: string) => string;+}++function createApplicationManifestSourceProjection(extensionScope?: {+ readonly namespace: string;+ readonly sourceRoot: string;+}): ManifestSourceProjection {+ const projection: {+ extensionScope?: { readonly namespace: string; readonly sourceRoot: string };+ logicalPath: (logicalPath: string) => string;+ name: (name: string) => string;+ } = {+ logicalPath: (logicalPath) => logicalPath,+ name: (name) => name,+ };+ if (extensionScope !== undefined) {+ projection.extensionScope = extensionScope;+ }+ return projection;+}++function createExtensionManifestSourceProjection(+ extension: ResolvedExtensionMount,+): ManifestSourceProjection {+ const { namespace, sourceRoot } = extension;+ return {+ extensionScope: { namespace, sourceRoot },+ logicalPath: (logicalPath) => qualifyExtensionContributionLogicalPath(logicalPath, namespace),+ name: (name) => `${namespace}__${name}`,+ };+}+function projectManifest(input: {readonly candidates: AgentSourceCandidate[];readonly externalDependencies: readonly string[];- readonly extension?: ResolvedExtensionMount;- readonly extensionScope?: { readonly namespace: string; readonly sourceRoot: string };+ readonly projection: ManifestSourceProjection;readonly layer: AgentSourceLayer;readonly manifest: AgentSourceManifest;readonly nodeId: string;@@ -228,17 +256,15 @@ function projectManifest(input: {readonly sourceIdPrefix?: string;readonly subagents: ProjectedSubagentSource[];}): void {- const qualify = (logicalPath: string) =>- input.extension === undefined- ? logicalPath- : qualifyExtensionLogicalPath(logicalPath, input.extension.namespace);+ const { projection } = input;const sourceId = (id: string) => `${input.sourceIdPrefix ?? ""}${id}`;const pushModule = (source: ModuleSourceRef, logicalPathOverride?: string) => {- const logicalPath = logicalPathOverride ?? qualify(source.logicalPath);+ const logicalPath = projection.logicalPath(logicalPathOverride ?? source.logicalPath);const candidate = createFilesystemModuleCandidate({externalDependencies: input.externalDependencies,- extension: input.extension,- extensionScope: input.extensionScope,+ ...(projection.extensionScope === undefined+ ? {}+ : { extensionScope: projection.extensionScope }),layer: input.layer,logicalPath,nodeId: input.nodeId,@@ -253,15 +279,12 @@ function projectManifest(input: {kind: ProjectedResourceSource["kind"],source: InstructionsSourceRef | ScheduleSourceRef | SkillSourceRef,) => {- const logicalPath = qualify(source.logicalPath);+ const logicalPath = projection.logicalPath(source.logicalPath);const projected = {...source,...(source.sourceKind === "skill-package"? {- name:- input.extension === undefined- ? source.name- : `${input.extension.namespace}__${source.name}`,+ name: projection.name(source.name),}: {}),logicalPath,@@ -290,7 +313,7 @@ function projectManifest(input: {} as ProjectedResourceSource);};- if (input.extension === undefined && input.manifest.configModule !== undefined) {+ if (input.manifest.configModule !== undefined) {const logicalPath = input.manifest.configModule.logicalPath;pushModule(input.manifest.configModule,@@ -300,9 +323,7 @@ function projectManifest(input: {if (input.manifest.instrumentation !== undefined) {pushModule(input.manifest.instrumentation);}- if (input.extension === undefined) {- for (const source of input.manifest.extensions) pushModule(source);- }+ for (const source of input.manifest.extensions) pushModule(source);for (const source of input.manifest.channels) pushModule(source);for (const source of input.manifest.connections) pushModule(source);for (const source of input.manifest.hooks) pushModule(source);@@ -322,14 +343,8 @@ function projectManifest(input: {else pushResource("skill", source);}for (const source of input.manifest.subagents) {- const name =- input.extension === undefined- ? source.subagentId- : `${input.extension.namespace}__${source.subagentId}`;- const logicalPath =- input.extension === undefined- ? source.logicalPath- : qualifyExtensionLogicalPath(source.logicalPath, input.extension.namespace);+ const name = projection.name(source.subagentId);+ const logicalPath = projection.logicalPath(source.logicalPath);const projectedSource = {...source,logicalPath,@@ -348,14 +363,9 @@ function projectManifest(input: {input.candidates.push(candidate);input.subagents.push({candidate,- ...(input.extension === undefined && input.extensionScope === undefined+ ...(projection.extensionScope === undefined? {}- : {- extensionScope:- input.extension === undefined- ? input.extensionScope- : { namespace: input.extension.namespace, sourceRoot: input.extension.sourceRoot },- }),+ : { extensionScope: projection.extensionScope }),owner: input.owner,source: projectedSource,});@@ -388,11 +398,34 @@ function isModuleCandidate(candidate: AgentSourceCandidate): candidate is AgentMreturn candidate.backing.kind !== "resource";}-export function qualifyExtensionLogicalPath(logicalPath: string, namespace: string): string {+const EXTENSION_CONTRIBUTION_ROOTS = new Set([+ "channels",+ "connections",+ "hooks",+ "instructions",+ "schedules",+ "skills",+ "subagents",+ "tools",+]);++export function qualifyExtensionContributionLogicalPath(+ logicalPath: string,+ namespace: string,+): string {const parts = logicalPath.split("/");- if (parts.length < 2) return logicalPath;+ if (parts.length === 1) {+ const slot = stripLogicalPathExtension(logicalPath);+ if (slot === "instructions" || slot === "system") {+ return `instructions/${namespace}${logicalPath.slice(logicalPath.lastIndexOf("."))}`;+ }+ throw new Error(`Extension source slot "${logicalPath}" cannot be namespace-scoped.`);+ }+const root = parts[0]!;- if (root === "sandbox" || root === "extensions" || root === "lib") return logicalPath;+ if (!EXTENSION_CONTRIBUTION_ROOTS.has(root)) {+ throw new Error(`Extension source slot "${logicalPath}" cannot be namespace-scoped.`);+ }parts[1] = `${namespace}__${parts[1]}`;return parts.join("/");}diff --git a/packages/eve/src/discover/agent.integration.test.ts b/packages/eve/src/discover/agent.integration.test.tsindex 0325b696a..0c692a78c 100644--- a/packages/eve/src/discover/agent.integration.test.ts+++ b/packages/eve/src/discover/agent.integration.test.ts@@ -13,6 +13,7 @@ import { discoverAgent } from "#discover/discover-agent.js";import {DISCOVER_EXTENSION_CAPABILITY_INCOMPATIBLE,DISCOVER_EXTENSION_COMPATIBILITY_INVALID,+ DISCOVER_EXTENSION_INSTRUMENTATION_UNSUPPORTED,DISCOVER_EXTENSION_MEMORY_UNSUPPORTED,DISCOVER_EXTENSION_MOUNT_AMBIGUOUS,DISCOVER_EXTENSION_MOUNT_MISSING_DECLARATION,@@ -796,6 +797,58 @@ describe("discoverAgent (memory)", () => {]);});+ it("scopes flat instructions from multiple extensions by mount namespace", async () => {+ const project = buildMemoryAgentProject({+ appFiles: {+ "node_modules/@acme/crm/package.json": JSON.stringify({+ name: "@acme/crm",+ eve: { extension: { source: "source", dist: "extension" } },+ }),+ "node_modules/@acme/crm/extension/_manifest.json": EXTENSION_COMPATIBILITY_MANIFEST,+ "node_modules/@acme/crm/extension/instructions.md": "Use the CRM before guessing.",+ "node_modules/@acme/gizmo/package.json": JSON.stringify({+ name: "@acme/gizmo",+ eve: { extension: { source: "source", dist: "extension" } },+ }),+ "node_modules/@acme/gizmo/extension/_manifest.json": EXTENSION_COMPATIBILITY_MANIFEST,+ "node_modules/@acme/gizmo/extension/instructions.md": "Use gizmo data before guessing.",+ },+ agentFiles: {+ "extensions/crm.ts": 'export { default } from "@acme/crm";\n',+ "extensions/gizmo.ts": 'export { default } from "@acme/gizmo";\n',+ "instructions.md": "You are a precise assistant.",+ },+ });++ const result = await discoverAgent({+ agentRoot: project.agentRoot,+ appRoot: project.appRoot,+ source: project.source,+ });++ expect(result.diagnostics).toEqual([]);+ const projected = projectAgentSources({+ externalDependencies: [],+ manifest: result.manifest,+ nodeId: "root",+ });+ const composed = composeAgentModuleCandidates(projected.candidates);++ expect([...composed.selected.keys()].filter((slot) => slot.startsWith("instructions"))).toEqual(+ ["instructions", "instructions/crm", "instructions/gizmo"],+ );+ expect(composed.selected.get("instructions/crm")).toMatchObject({+ layer: "extension-package",+ logicalPath: "instructions/crm.md",+ owner: { kind: "extension", namespace: "crm", packageName: "@acme/crm" },+ });+ expect(composed.selected.get("instructions/gizmo")).toMatchObject({+ layer: "extension-package",+ logicalPath: "instructions/gizmo.md",+ owner: { kind: "extension", namespace: "gizmo", packageName: "@acme/gizmo" },+ });+ });+it("rejects extension mount filenames that violate the namespace charset", async () => {const project = buildMemoryAgentProject({agentFiles: {@@ -912,6 +965,34 @@ describe("discoverAgent (memory)", () => {);});+ it("rejects instrumentation declared by a mounted extension", async () => {+ const project = buildMemoryAgentProject({+ appFiles: {+ "node_modules/@acme/crm/package.json": JSON.stringify({+ name: "@acme/crm",+ eve: { extension: { source: "source", dist: "extension" } },+ }),+ "node_modules/@acme/crm/extension/_manifest.json": EXTENSION_COMPATIBILITY_MANIFEST,+ "node_modules/@acme/crm/extension/instrumentation.ts": "export default {};",+ },+ agentFiles: {+ "extensions/crm.ts": 'export { default } from "@acme/crm";\n',+ "instructions.md": "You are a precise assistant.",+ },+ });++ const result = await discoverAgent({+ agentRoot: project.agentRoot,+ appRoot: project.appRoot,+ source: project.source,+ });++ expect(result.diagnostics.map((diagnostic) => diagnostic.code)).toContain(+ DISCOVER_EXTENSION_INSTRUMENTATION_UNSUPPORTED,+ );+ expect(result.manifest.resolvedExtensions[0]?.manifest.instrumentation).toBeUndefined();+ });+it("rejects memory declared by a mounted extension", async () => {const project = buildMemoryAgentProject({appFiles: {@@ -1317,6 +1398,14 @@ describe("discoverAgent (memory)", () => {);expect(nested).toBeDefined();expect(nested?.message).toContain("extensions/inner");+ expect(result.manifest.resolvedExtensions[0]?.manifest.extensions).toEqual([]);+ expect(() =>+ projectAgentSources({+ externalDependencies: [],+ manifest: result.manifest,+ nodeId: "root",+ }),+ ).not.toThrow();});it("allows an agent-root tool whose name does not use a mounted namespace prefix", async () => {diff --git a/packages/eve/src/discover/discover-agent.ts b/packages/eve/src/discover/discover-agent.tsindex 4b49d6594..39c816fde 100644--- a/packages/eve/src/discover/discover-agent.ts+++ b/packages/eve/src/discover/discover-agent.ts@@ -7,6 +7,7 @@ import {DISCOVER_EXTENSION_AGENT_CONFIG_UNSUPPORTED,DISCOVER_EXTENSION_MOUNT_AMBIGUOUS,DISCOVER_EXTENSION_MOUNT_MISSING_DECLARATION,+ DISCOVER_EXTENSION_INSTRUMENTATION_UNSUPPORTED,DISCOVER_EXTENSION_MEMORY_UNSUPPORTED,DISCOVER_EXTENSION_NESTED_MOUNT_UNSUPPORTED,DISCOVER_EXTENSION_SANDBOX_UNSUPPORTED,@@ -183,6 +184,16 @@ export async function discoverAgent(input: DiscoverAgentInput): Promise<Discover}),);}+ if (instrumentationModuleResult.module !== undefined) {+ diagnostics.push(+ createDiscoverErrorDiagnostic({+ code: DISCOVER_EXTENSION_INSTRUMENTATION_UNSUPPORTED,+ message:+ "An extension may not declare instrumentation — it is a singleton owned by the consuming agent.",+ sourcePath: join(agentRoot, instrumentationModuleResult.module.logicalPath),+ }),+ );+ }const [firstMemory] = memoryResult.memories;if (firstMemory !== undefined) {diagnostics.push(@@ -294,25 +305,28 @@ export async function discoverAgent(input: DiscoverAgentInput): Promise<Discoverconnections: connectionsResult.connections,packageName,diagnostics,- extensions: mountCollection.mounts.map((descriptor) => descriptor.mountRef),+ extensions:+ role === "extension" ? [] : mountCollection.mounts.map((descriptor) => descriptor.mountRef),resolvedExtensions,hooks: hooksResult.sources,memories: role === "extension" ? [] : memoryResult.memories,lib: libResult.lib,instructions: instructionsResult.instructions,- sandbox: sandboxResult.sandbox,+ sandbox: role === "extension" ? null : sandboxResult.sandbox,sandboxWorkspaces:- sandboxResult.sandboxWorkspace === null ? [] : [sandboxResult.sandboxWorkspace],+ role === "extension" || sandboxResult.sandboxWorkspace === null+ ? []+ : [sandboxResult.sandboxWorkspace],schedules: schedulesResult.schedules,skills: skillsResult.skills,tools: toolsResult.sources,subagents: subagentsResult.subagents,};- if (configModuleResult.module !== undefined) {+ if (role !== "extension" && configModuleResult.module !== undefined) {manifestInput.configModule = configModuleResult.module;}- if (instrumentationModuleResult.module !== undefined) {+ if (role !== "extension" && instrumentationModuleResult.module !== undefined) {manifestInput.instrumentation = instrumentationModuleResult.module;}diff --git a/packages/eve/src/discover/extensions.ts b/packages/eve/src/discover/extensions.tsindex 4b2b13c60..912cfe711 100644--- a/packages/eve/src/discover/extensions.ts+++ b/packages/eve/src/discover/extensions.ts@@ -70,6 +70,13 @@ export const DISCOVER_EXTENSION_AGENT_CONFIG_UNSUPPORTED =export const DISCOVER_EXTENSION_SANDBOX_UNSUPPORTED = "discover/extension-sandbox-unsupported";export const DISCOVER_EXTENSION_MEMORY_UNSUPPORTED = "discover/extension-memory-unsupported";+/**+ * Emitted when an extension declares agent-level instrumentation. Instrumentation+ * is a singleton owned by the consuming agent and cannot be namespace-scoped.+ */+export const DISCOVER_EXTENSION_INSTRUMENTATION_UNSUPPORTED =+ "discover/extension-instrumentation-unsupported";+/*** Resolved on-disk location of one mounted extension package.*/