The Open Framework for Building Agents
feat(eve): extensions - support subagents (#2134)
Andrew Barbad23467dd4a55
diff --git a/.changeset/bright-owls-delegate.md b/.changeset/bright-owls-delegate.mdnew file mode 100644index 000000000..44f0123c6--- /dev/null+++ b/.changeset/bright-owls-delegate.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Allow extensions to contribute namespaced subagents, including their tools, configuration access, nested subagents, and directory-mount overrides.diff --git a/docs/extensions.md b/docs/extensions.mdindex 8bc47708a..2c2e3d919 100644--- a/docs/extensions.md+++ b/docs/extensions.md@@ -3,7 +3,7 @@ title: "Extensions"description: "Package reusable eve capabilities and mount them from npm or a monorepo workspace."----Extensions package eve tools, channels, connections, skills, schedules, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.+Extensions package eve tools, channels, connections, skills, schedules, subagents, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.Ready-made extensions can also be distributed through an eve integration registry. See [Add Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.@@ -33,6 +33,7 @@ An extension uses the same file conventions as an agent for its contributions:connections/api.tsskills/triage/SKILL.mdschedules/sync.ts+ subagents/reviewer/agent.tsinstructions.mdhooks/audit.tslib/http.ts@@ -40,9 +41,9 @@ An extension uses the same file conventions as an agent for its contributions:Each listed slot accepts the same authored forms as its agent counterpart. Static and dynamic tools, skills, and instructions all work in an extension: `extension/instructions.ts` is as valid as `extension/instructions.md`, and `extension/tools/` can contain `defineDynamic(...)`.-Names 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 and schedule IDs, while channel route paths and schedule cron expressions stay unchanged. Keep shared code in `extension/lib/`.+Names 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/`.-Keep agent configuration, sandboxes, and nested extensions in the consumer's agent.+The extension root cannot declare agent configuration, a sandbox, or nested extensions. A subagent contributed under `extension/subagents/` owns its own agent configuration and sandbox like any other [declared subagent](./subagents).### Add configuration and contributions@@ -82,6 +83,12 @@ If no configuration is needed, export `defineExtension()` and let consumers re-e`defineState` is automatically scoped to the extension package, so the same state name does not collide with the consumer or another extension.+### Add a subagent++Author a subagent under `extension/subagents/<id>/` using the same files as a subagent declared by an agent. Mounting the extension as `crm` exposes `extension/subagents/reviewer/` to the consuming agent node as `crm__reviewer`. The subagent's own tools, connections, skills, hooks, instructions, sandbox, and nested subagents remain isolated inside its node and keep their path-derived names.++Modules inside the contributed subagent can import the extension handle. For example, a tool under `extension/subagents/reviewer/tools/` can read the configuration bound by the consumer's `agent/extensions/crm.ts` mount.+### Build and optionally publishThe scaffold's `package.json` declares separate source and distribution roots:@@ -170,7 +177,7 @@ export default crm({ apiKey: process.env.CRM_API_KEY! });Set `CRM_API_KEY` in the consumer's environment, such as `.env.local` for local development.-The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, `channels/webhook.ts` becomes `crm__webhook`, `schedules/sync.ts` becomes `crm__sync`, and `connections/api.ts` becomes `crm__api`. Channels keep their declared route paths, and schedules keep their cron expressions.+The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, `channels/webhook.ts` becomes `crm__webhook`, `schedules/sync.ts` becomes `crm__sync`, `connections/api.ts` becomes `crm__api`, and `subagents/reviewer/` becomes `crm__reviewer`. Channels keep their declared route paths, and schedules keep their cron expressions.For an extension with no configuration, mount its default export directly:@@ -276,7 +283,7 @@ import crm from "@acme/crm";export default crm({ apiKey: process.env.CRM_API_KEY! });```-A same-named consumer channel, tool, connection, skill, or schedule wins. To adjust an extension tool, import it from the package's `./tools` export and define it again:+A same-named consumer channel, tool, connection, skill, schedule, or subagent wins. To adjust an extension tool, import it from the package's `./tools` export and define it again:```ts title="agent/extensions/crm/tools/search.ts"import { search } from "@acme/crm/tools";@@ -296,7 +303,7 @@ export default disableTool();Hooks and instruction fragments are additive, so they cannot be replaced. To replace a dynamic tool, use a dynamic definition in the same slot; dynamic tools win over same-named static tools at runtime. `disableTool()` removes either kind.-The `crm__` prefix is reserved for this directory mount. A consumer cannot override the extension from `agent/tools/`, `agent/connections/`, or another agent-root slot.+The `crm__` prefix is reserved for this directory mount. A consumer cannot override the extension from `agent/tools/`, `agent/connections/`, `agent/subagents/`, or another agent-root slot.### Use an extension tool result in a hook@@ -333,4 +340,5 @@ At build time, eve checks the extension's generated capability metadata. If the- [Connections](/docs/connections): integrate external services- [Channels](/docs/channels/overview): receive messages and expose routes- [Schedules](/docs/schedules): run the agent on a cron cadence+- [Subagents](/docs/subagents): delegate to declared specialists- [Hooks](/docs/guides/hooks): observe agent eventsdiff --git a/docs/subagents/index.mdx b/docs/subagents/index.mdxindex c8609f95f..9077ff046 100644--- a/docs/subagents/index.mdx+++ b/docs/subagents/index.mdx@@ -50,6 +50,8 @@ export default defineAgent({`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out.+A mounted extension can also contribute declared subagents from `extension/subagents/`. The mount namespace prefixes the subagent visible to the consuming agent node: mounting an extension as `crm` exposes its `reviewer` subagent as `crm__reviewer`. The contributed subagent keeps its own isolated tools, connections, skills, hooks, instructions, sandbox, and nested subagents, and its modules can read configuration from the extension handle. See [Extensions](./extensions#add-a-subagent) for the authoring and override behavior.+### Conditional availabilityTo expose a declared subagent only for certain sessions or turns, export@@ -153,7 +155,7 @@ Declared subagents can call nested subagents defined under their own directories`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Workflow Tool](./subagents/workflow-tool).-A declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. Unlike connection tools (`<connection>__<tool>`), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:+A directly declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. A subagent supplied by a mounted extension includes the mount namespace, such as `crm__reviewer`. The model, approvals, logs, and evals reference the resulting name. Its input schema is:```ts{diff --git a/packages/eve/extension-contracts/entrypoints/subagent.ts b/packages/eve/extension-contracts/entrypoints/subagent.tsnew file mode 100644index 000000000..91cd73327--- /dev/null+++ b/packages/eve/extension-contracts/entrypoints/subagent.ts@@ -0,0 +1,14 @@+export {+ type AgentCompactionDefinition,+ type AgentDefinition,+ type AgentModelDefinition,+ type AgentStaticModelDefinition,+ type DefinedAgent,+ type DynamicLocalSubagentDefinition,+ type DynamicSubagentDefinition,+ type RemoteAgentDefinition,+ type RemoteAgentDefinitionInput,+ defineAgent,+ defineDynamic,+ defineRemoteAgent,+} from "../../src/public/index.ts";diff --git a/packages/eve/extension-contracts/reports/subagent/v1.json b/packages/eve/extension-contracts/reports/subagent/v1.jsonnew file mode 100644index 000000000..67a75920b--- /dev/null+++ b/packages/eve/extension-contracts/reports/subagent/v1.json@@ -0,0 +1,20 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "subagent",+ "epoch": 1,+ "sha256": "bee02112ba6f4e68f8309516df224559acc1e54d165c5f9bbf499d9fa1f7fceb",+ "exports": [+ "AgentCompactionDefinition",+ "AgentDefinition",+ "AgentModelDefinition",+ "AgentStaticModelDefinition",+ "DefinedAgent",+ "DynamicLocalSubagentDefinition",+ "DynamicSubagentDefinition",+ "RemoteAgentDefinition",+ "RemoteAgentDefinitionInput",+ "defineAgent",+ "defineDynamic",+ "defineRemoteAgent"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 5b9e4e112..ceb685c78 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -29,6 +29,7 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},channel: { current: 1, supported: [1], dropped: {} },schedule: { current: 1, supported: [1], dropped: {} },+ subagent: { current: 1, supported: [1], dropped: {} },connection: { current: 5, supported: [1, 2, 3, 4, 5], dropped: {} },hook: {current: 13,diff --git a/packages/eve/src/compiler/normalize-extension.test.ts b/packages/eve/src/compiler/normalize-extension.test.tsindex 136d74f11..7b504024e 100644--- a/packages/eve/src/compiler/normalize-extension.test.ts+++ b/packages/eve/src/compiler/normalize-extension.test.ts@@ -2,9 +2,15 @@ import { describe, expect, it } from "vitest";import {applyOverrideDisables,+ composeExtensionSubagentSources,type CompiledExtensionContributions,mergeContributions,} from "#compiler/normalize-extension.js";+import {+ createAgentSourceManifest,+ createLocalSubagentSourceRef,+ createModuleSourceRef,+} from "#discover/manifest.js";// mergeContributions only reads each named contribution's identifier for dedup,// so minimal partial fixtures suffice.@@ -97,6 +103,63 @@ describe("mergeContributions", () => {});});+describe("composeExtensionSubagentSources", () => {+ it("namespaces extension subagents and lets a directory override win", () => {+ const extensionRoot = "/packages/crm/dist/extension";+ const overrideRoot = "/app/agent/extensions/crm";+ const createSubagent = (root: string, subagentId: string) => {+ const agentRoot = `${root}/subagents/${subagentId}`;+ return createLocalSubagentSourceRef({+ entryPath: agentRoot,+ logicalPath: `subagents/${subagentId}`,+ manifest: createAgentSourceManifest({+ agentId: subagentId,+ agentRoot,+ appRoot: "/app",+ configModule: createModuleSourceRef({ logicalPath: "agent.ts" }),+ tools: [createModuleSourceRef({ logicalPath: "tools/search.ts" })],+ }),+ rootPath: agentRoot,+ subagentId,+ });+ };+ const extensionManifest = createAgentSourceManifest({+ agentRoot: extensionRoot,+ appRoot: "/packages/crm",+ subagents: [+ createSubagent(extensionRoot, "reviewer"),+ createSubagent(extensionRoot, "analyst"),+ ],+ });+ const overrideManifest = createAgentSourceManifest({+ agentRoot: overrideRoot,+ appRoot: "/app",+ subagents: [createSubagent(overrideRoot, "reviewer")],+ });++ const result = composeExtensionSubagentSources({+ consumerAgentRoot: "/app/agent",+ mount: {+ namespace: "crm",+ specifier: "@acme/crm",+ packageName: "@acme/crm",+ packageRoot: "/packages/crm",+ sourceRoot: extensionRoot,+ manifest: extensionManifest,+ overrides: overrideManifest,+ },+ });++ expect(result.map((source) => [source.subagentId, source.sourceId])).toEqual([+ ["crm__reviewer", "ext-override:crm:subagents/reviewer"],+ ["crm__analyst", "ext:crm:subagents/analyst"],+ ]);+ expect(result[1]?.manifest.tools[0]?.sourceId).toBe(+ "ext:crm:subagents/analyst/tools/search.ts",+ );+ });+});+describe("applyOverrideDisables", () => {it("removes the disabled static extension tool while keeping the rest", () => {const merged = contributions({diff --git a/packages/eve/src/compiler/normalize-extension.ts b/packages/eve/src/compiler/normalize-extension.tsindex 5da02ca27..a4cca1b87 100644--- a/packages/eve/src/compiler/normalize-extension.ts+++ b/packages/eve/src/compiler/normalize-extension.ts@@ -1,6 +1,11 @@import { join as joinPath, relative as relativePath } from "node:path";-import type { AgentSourceManifest, ResolvedExtensionMount } from "#discover/manifest.js";+import {+ createPathDerivedSourceId,+ type AgentSourceManifest,+ type LocalSubagentSourceRef,+ type ResolvedExtensionMount,+} from "#discover/manifest.js";import type {CompiledChannelEntry,CompiledConnectionDefinition,@@ -99,6 +104,127 @@ export async function compileExtensionContributions(input: {});}+/** Composes one mount's root-visible subagents under its namespace. */+export function composeExtensionSubagentSources(input: {+ readonly consumerAgentRoot: string;+ readonly mount: ResolvedExtensionMount;+}): LocalSubagentSourceRef[] {+ const base = scopeExtensionSubagents({+ consumerAgentRoot: input.consumerAgentRoot,+ manifest: input.mount.manifest,+ namespace: input.mount.namespace,+ sourceIdScope: `ext:${input.mount.namespace}`,+ sourceRoot: input.mount.sourceRoot,+ });+ if (input.mount.overrides === undefined) {+ return base;+ }++ const overrides = scopeExtensionSubagents({+ consumerAgentRoot: input.consumerAgentRoot,+ manifest: input.mount.overrides,+ namespace: input.mount.namespace,+ sourceIdScope: `ext-override:${input.mount.namespace}`,+ sourceRoot: input.mount.overrides.agentRoot,+ });+ return mergeExtensionSubagentSources(overrides, base);+}++/** Returns authored and mounted-extension subagents visible from one agent node. */+export function composeAgentSubagentSources(+ manifest: AgentSourceManifest,+): LocalSubagentSourceRef[] {+ return [+ ...manifest.subagents,+ ...[...manifest.resolvedExtensions]+ .sort((left, right) => left.namespace.localeCompare(right.namespace))+ .flatMap((mount) =>+ composeExtensionSubagentSources({ consumerAgentRoot: manifest.agentRoot, mount }),+ ),+ ];+}++/** Earlier entries win, matching directory-override precedence for other slots. */+export function mergeExtensionSubagentSources(+ primary: readonly LocalSubagentSourceRef[],+ secondary: readonly LocalSubagentSourceRef[],+): LocalSubagentSourceRef[] {+ return dedupeBy([...primary, ...secondary], (source) => source.subagentId);+}++function scopeExtensionSubagents(input: {+ readonly consumerAgentRoot: string;+ readonly manifest: AgentSourceManifest;+ readonly namespace: string;+ readonly sourceIdScope: string;+ readonly sourceRoot: string;+}): LocalSubagentSourceRef[] {+ return input.manifest.subagents.map((source) => ({+ ...scopeExtensionSubagentSource(source, input.sourceRoot, input.sourceIdScope),+ logicalPath: relativePath(input.consumerAgentRoot, source.entryPath).replaceAll("\\", "/"),+ subagentId: `${input.namespace}__${source.subagentId}`,+ }));+}++function scopeExtensionSubagentSource(+ source: LocalSubagentSourceRef,+ sourceRoot: string,+ sourceIdScope: string,+): LocalSubagentSourceRef {+ return {+ ...source,+ manifest: scopeExtensionSubagentManifest(source.manifest, sourceRoot, sourceIdScope),+ sourceId: scopeExtensionSourceId(sourceRoot, source.entryPath, sourceIdScope),+ };+}++function scopeExtensionSubagentManifest(+ manifest: AgentSourceManifest,+ sourceRoot: string,+ sourceIdScope: string,+): AgentSourceManifest {+ const scopeRef = <T extends { readonly logicalPath: string; readonly sourceId: string }>(+ source: T,+ ): T => ({+ ...source,+ sourceId: scopeExtensionSourceId(+ sourceRoot,+ joinPath(manifest.agentRoot, source.logicalPath),+ sourceIdScope,+ ),+ });++ return {+ ...manifest,+ channels: manifest.channels.map(scopeRef),+ connections: manifest.connections.map(scopeRef),+ ...(manifest.configModule === undefined+ ? {}+ : { configModule: scopeRef(manifest.configModule) }),+ extensions: manifest.extensions.map(scopeRef),+ hooks: manifest.hooks.map(scopeRef),+ instructions: manifest.instructions.map(scopeRef),+ lib: manifest.lib.map(scopeRef),+ sandbox: manifest.sandbox === null ? null : scopeRef(manifest.sandbox),+ sandboxWorkspaces: manifest.sandboxWorkspaces.map(scopeRef),+ schedules: manifest.schedules.map(scopeRef),+ skills: manifest.skills.map(scopeRef),+ subagents: manifest.subagents.map((source) =>+ scopeExtensionSubagentSource(source, sourceRoot, sourceIdScope),+ ),+ tools: manifest.tools.map(scopeRef),+ };+}++function scopeExtensionSourceId(+ sourceRoot: string,+ sourcePath: string,+ sourceIdScope: string,+): string {+ const logicalPath = relativePath(sourceRoot, sourcePath).replaceAll("\\", "/");+ return `${sourceIdScope}:${createPathDerivedSourceId(logicalPath)}`;+}+export interface DisabledToolTarget {/** Namespaced target, e.g. `crm__search`. */readonly name: string;diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.tsindex 6c31f3e9f..b73572242 100644--- a/packages/eve/src/compiler/normalize-manifest.ts+++ b/packages/eve/src/compiler/normalize-manifest.ts@@ -22,7 +22,10 @@ import { createCompiledRuntimeModelCatalogLoader } from "#compiler/model-catalogimport { compileAgentConfig } from "#compiler/normalize-agent-config.js";import { compileChannelDefinition } from "#compiler/normalize-channel.js";import { compileConnectionDefinition } from "#compiler/normalize-connection.js";-import { compileExtensionContributions } from "#compiler/normalize-extension.js";+import {+ composeAgentSubagentSources,+ compileExtensionContributions,+} from "#compiler/normalize-extension.js";import type { ManifestCompileContext } from "#compiler/normalize-helpers.js";import { compileHookEntry } from "#compiler/normalize-hook.js";import { compileSandboxDefinition } from "#compiler/normalize-sandbox.js";@@ -48,8 +51,9 @@ export async function compileAgentManifest(compileAgentResources,context,externalDependencies: compiledNode.config.build?.externalDependencies ?? [],+ parentAgentRoot: manifest.agentRoot,parentNodeId: ROOT_COMPILED_AGENT_NODE_ID,- subagents: manifest.subagents,+ subagents: composeAgentSubagentSources(manifest),});return createCompiledAgentManifest({diff --git a/packages/eve/src/compiler/normalize-subagent.ts b/packages/eve/src/compiler/normalize-subagent.tsindex 182291061..503deee73 100644--- a/packages/eve/src/compiler/normalize-subagent.ts+++ b/packages/eve/src/compiler/normalize-subagent.ts@@ -1,3 +1,5 @@+import { join, relative } from "node:path";+import {type AgentSourceManifest,createPathDerivedSourceId,@@ -11,6 +13,7 @@ import {type CompiledSubagentNode,createCompiledSubagentNodeId,} from "#compiler/manifest.js";+import { composeAgentSubagentSources } from "#compiler/normalize-extension.js";import type { CompiledDynamicSubagentDefinition } from "#compiler/remote-agent-node.js";import {loadModuleBackedDefinition,@@ -69,6 +72,7 @@ export async function compileSubagentGraph(input: {readonly compileAgentResources: CompileAgentResourcesFn;readonly context: ManifestCompileContext;readonly externalDependencies?: readonly string[];+ readonly parentAgentRoot: string;readonly parentNodeId: string;readonly subagents: readonly LocalSubagentSourceRef[];}): Promise<{@@ -87,6 +91,7 @@ export async function compileSubagentGraph(input: {compileAgentResources: input.compileAgentResources,context: input.context,externalDependencies: input.externalDependencies,+ parentAgentRoot: input.parentAgentRoot,parentNodeId: input.parentNodeId,source: subagentSource,});@@ -119,6 +124,7 @@ async function compileSubagentDefinition(input: {readonly compileAgentResources: CompileAgentResourcesFn;readonly context: ManifestCompileContext;readonly externalDependencies?: readonly string[];+ readonly parentAgentRoot: string;readonly parentNodeId: string;readonly source: LocalSubagentSourceRef;}): Promise<@@ -142,7 +148,11 @@ async function compileSubagentDefinition(input: {throw new Error(`Subagent "${input.source.logicalPath}" is missing an agent config module.`);}- const configModuleSource = createSubagentConfigModuleSourceRef(input.source, configModule);+ const configModuleSource = createSubagentConfigModuleSourceRef(+ input.source,+ configModule,+ input.parentAgentRoot,+ );const definition = await loadModuleBackedDefinition({agentRoot: input.source.manifest.agentRoot,displayPath: configModuleSource.logicalPath,@@ -158,6 +168,7 @@ async function compileSubagentDefinition(input: {return {kind: "remote",node: compileRemoteAgent({+ parentAgentRoot: input.parentAgentRoot,source: input.source,value: definition,}),@@ -185,6 +196,7 @@ async function compileSubagent(input: {readonly agentConfigDefinition?: unknown;readonly configResolver?: CompiledDynamicSubagentDefinition;readonly externalDependencies?: readonly string[];+ readonly parentAgentRoot: string;readonly parentNodeId: string;readonly source: LocalSubagentSourceRef;}): Promise<{@@ -235,8 +247,9 @@ async function compileSubagent(input: {compileAgentResources: input.compileAgentResources,externalDependencies:agent.config.build?.externalDependencies ?? inheritedExternalDependencies,+ parentAgentRoot: input.source.manifest.agentRoot,parentNodeId: nodeId,- subagents: input.source.manifest.subagents,+ subagents: composeAgentSubagentSources(input.source.manifest),});return {descendants,@@ -257,8 +270,9 @@ async function compileSubagent(input: {context: input.context,compileAgentResources: input.compileAgentResources,externalDependencies: inheritedExternalDependencies,+ parentAgentRoot: input.source.manifest.agentRoot,parentNodeId: nodeId,- subagents: input.source.manifest.subagents,+ subagents: composeAgentSubagentSources(input.source.manifest),});return {descendants,@@ -273,6 +287,7 @@ async function compileSubagent(input: {const compileLocalSubagent = compileSubagent;function compileRemoteAgent(input: {+ readonly parentAgentRoot: string;readonly source: LocalSubagentSourceRef;readonly value: unknown;}): CompiledRemoteAgentNode {@@ -284,7 +299,11 @@ function compileRemoteAgent(input: {assertRemoteAgentDefinitionHasNoLocalPackageEntries(input.source);- const moduleSource = createSubagentConfigModuleSourceRef(input.source, configModule);+ const moduleSource = createSubagentConfigModuleSourceRef(+ input.source,+ configModule,+ input.parentAgentRoot,+ );const definition = normalizeRemoteAgentDefinition(input.value,`Expected the remote agent config export "${configModule.exportName ?? "default"}" from "${moduleSource.logicalPath}" to match the public eve shape.`,@@ -369,16 +388,21 @@ function mergeExternalDependencies(function createSubagentConfigModuleSourceRef(source: LocalSubagentSourceRef,configModule: NonNullable<LocalSubagentSourceRef["manifest"]["configModule"]>,+ parentAgentRoot: string,): {readonly exportName?: string;readonly logicalPath: string;readonly sourceId: string;readonly sourceKind: "module";} {- const logicalPath =- source.logicalPath === configModule.logicalPath- ? configModule.logicalPath- : `${source.logicalPath}/${configModule.logicalPath}`;+ const logicalPath = relative(+ parentAgentRoot,+ join(source.manifest.agentRoot, configModule.logicalPath),+ ).replaceAll("\\", "/");+ const sourceId =+ configModule.sourceId.startsWith("ext:") || configModule.sourceId.startsWith("ext-override:")+ ? configModule.sourceId+ : createPathDerivedSourceId(logicalPath);const moduleSource: {exportName?: string;logicalPath: string;@@ -386,7 +410,7 @@ function createSubagentConfigModuleSourceRef(sourceKind: "module";} = {logicalPath,- sourceId: createPathDerivedSourceId(logicalPath),+ sourceId,sourceKind: "module",};diff --git a/packages/eve/src/discover/agent.integration.test.ts b/packages/eve/src/discover/agent.integration.test.tsindex 203eaf11c..b333a3488 100644--- a/packages/eve/src/discover/agent.integration.test.ts+++ b/packages/eve/src/discover/agent.integration.test.ts@@ -976,7 +976,7 @@ describe("discoverAgent (memory)", () => {expect(result.manifest.resolvedExtensions).toEqual([]);});- it("rejects an agent-root tool that overrides a mounted extension's namespace", async () => {+ it("rejects agent-root contributions that override a mounted extension's namespace", async () => {const project = buildMemoryAgentProject({appFiles: {"node_modules/@acme/crm/package.json": JSON.stringify({@@ -991,6 +991,7 @@ describe("discoverAgent (memory)", () => {// A root tool using the mounted `crm__` prefix would shadow the// extension from outside its mount directory."tools/crm__search.ts": "export default {};\n",+ "subagents/crm__reviewer.ts": "export default {};\n","instructions.md": "You are a precise assistant.",},});@@ -1001,11 +1002,11 @@ describe("discoverAgent (memory)", () => {source: project.source,});- const collision = result.diagnostics.find(+ const collisions = result.diagnostics.filter((diagnostic) => diagnostic.code === DISCOVER_EXTENSION_OVERRIDE_OUTSIDE_MOUNT,);- expect(collision).toBeDefined();- expect(collision?.message).toContain("extensions/crm/");+ expect(collisions).toHaveLength(2);+ expect(collisions[0]?.message).toContain("extensions/crm/");});it("rejects a mounted extension that requires an unsupported capability version", async () => {diff --git a/packages/eve/src/discover/discover-agent.ts b/packages/eve/src/discover/discover-agent.tsindex c6d9e157b..dbca1c707 100644--- a/packages/eve/src/discover/discover-agent.ts+++ b/packages/eve/src/discover/discover-agent.ts@@ -252,6 +252,7 @@ export async function discoverAgent(input: DiscoverAgentInput): Promise<Discover...connectionsResult.connections,...skillsResult.skills,...schedulesResult.schedules,+ ...subagentsResult.subagents,],}),);diff --git a/packages/eve/src/discover/discover-subagent.ts b/packages/eve/src/discover/discover-subagent.tsindex 6cf3bedfd..c6def21d0 100644--- a/packages/eve/src/discover/discover-subagent.ts+++ b/packages/eve/src/discover/discover-subagent.ts@@ -294,7 +294,12 @@ async function discoverLocalSubagentPackage(input: {...detectRootNamespaceCollisions({agentRoot: input.subagentRoot,namespaces: extensionsResult.mounts.map((mount) => mount.namespace),- sources: [...toolsResult.sources, ...connectionsResult.connections, ...skillsResult.skills],+ sources: [+ ...toolsResult.sources,+ ...connectionsResult.connections,+ ...skillsResult.skills,+ ...subagentsResult.subagents,+ ],}),);diff --git a/packages/eve/src/internal/authored-module-map-loader.ts b/packages/eve/src/internal/authored-module-map-loader.tsindex d2f8a4f0a..7e32c88ce 100644--- a/packages/eve/src/internal/authored-module-map-loader.ts+++ b/packages/eve/src/internal/authored-module-map-loader.ts@@ -92,15 +92,29 @@ async function hydrateCompiledModuleMapFromManifest(nodeId: subagent.nodeId,})),];+ const nodeManifestById = new Map(nodeManifests.map((entry) => [entry.nodeId, entry.manifest]));+ const parentNodeIdByChild = new Map(+ manifest.subagentEdges.map((edge) => [edge.childNodeId, edge.parentNodeId]),+ );+ const extensionNamespacesByNodeId = new Map<string, ReadonlyMap<string, string>>();+ const extensionNamespacesForNode = (nodeId: string): ReadonlyMap<string, string> => {+ const cached = extensionNamespacesByNodeId.get(nodeId);+ if (cached !== undefined) return cached;++ const parentNodeId = parentNodeIdByChild.get(nodeId);+ const namespaces = new Map(+ parentNodeId === undefined ? [] : extensionNamespacesForNode(parentNodeId),+ );+ for (const mount of nodeManifestById.get(nodeId)?.extensionMounts ?? []) {+ namespaces.set(mount.namespace, mount.packageNamespace);+ }+ extensionNamespacesByNodeId.set(nodeId, namespaces);+ return namespaces;+ };for (const nodeManifest of nodeManifests) {const scopeIndex: ExtensionScopeIndex = {- byMountNamespace: new Map(- nodeManifest.manifest.extensionMounts.map((mount) => [- mount.namespace,- mount.packageNamespace,- ]),- ),+ byMountNamespace: extensionNamespacesForNode(nodeManifest.nodeId),byMountSourceId: new Map(nodeManifest.manifest.extensionMounts.map((mount) => [mount.mountSourceId,diff --git a/packages/eve/src/internal/nitro/host/extension-capability-requirements.ts b/packages/eve/src/internal/nitro/host/extension-capability-requirements.tsindex 038540da5..80c192260 100644--- a/packages/eve/src/internal/nitro/host/extension-capability-requirements.ts+++ b/packages/eve/src/internal/nitro/host/extension-capability-requirements.ts@@ -22,18 +22,25 @@ export async function deriveExtensionCapabilityRequirements(input: {}): Promise<ExtensionCapabilityRequirements> {const required = new Set<ExtensionCapability>(["extension"]);const loadOptions = { externalDependencies: input.runtimeDependencies };+ const manifests = collectSubagentManifests(input.manifest);const [tools, skills, instructions, declaration, usesState] = await Promise.all([Promise.all(- input.manifest.tools.map((source) => compileToolEntry(input.sourceRoot, source, loadOptions)),+ manifests.flatMap((manifest) =>+ manifest.tools.map((source) => compileToolEntry(manifest.agentRoot, source, loadOptions)),+ ),),Promise.all(- input.manifest.skills.map((source) =>- compileSkillSource(input.sourceRoot, source, loadOptions),+ manifests.flatMap((manifest) =>+ manifest.skills.map((source) =>+ compileSkillSource(manifest.agentRoot, source, loadOptions),+ ),),),Promise.all(- input.manifest.instructions.map((source) =>- compileInstructionsEntry(input.sourceRoot, source, loadOptions),+ manifests.flatMap((manifest) =>+ manifest.instructions.map((source) =>+ compileInstructionsEntry(manifest.agentRoot, source, loadOptions),+ ),),),loadAuthoredModuleNamespace(join(input.sourceRoot, input.declarationModule.logicalPath), {@@ -44,10 +51,11 @@ export async function deriveExtensionCapabilityRequirements(input: {if (tools.length > 0) required.add("tool");if (tools.some((entry) => entry.kind === "dynamic-tool")) required.add("dynamicTool");- if (input.manifest.channels.length > 0) required.add("channel");- if (input.manifest.connections.length > 0) required.add("connection");- if (input.manifest.hooks.length > 0) required.add("hook");- if (input.manifest.schedules.length > 0) required.add("schedule");+ if (manifests.some((manifest) => manifest.channels.length > 0)) required.add("channel");+ if (manifests.some((manifest) => manifest.connections.length > 0)) required.add("connection");+ if (manifests.some((manifest) => manifest.hooks.length > 0)) required.add("hook");+ if (manifests.some((manifest) => manifest.schedules.length > 0)) required.add("schedule");+ if (manifests.some((manifest) => manifest.subagents.length > 0)) required.add("subagent");if (skills.length > 0) required.add("skill");if (skills.some((entry) => entry.kind === "dynamic-skill")) required.add("dynamicSkill");if (instructions.length > 0) required.add("instructions");@@ -71,3 +79,10 @@ export async function deriveExtensionCapabilityRequirements(input: {.map((capability) => [capability, EXTENSION_CAPABILITY_VERSIONS[capability]]),);}++function collectSubagentManifests(manifest: AgentSourceManifest): AgentSourceManifest[] {+ return [+ manifest,+ ...manifest.subagents.flatMap((subagent) => collectSubagentManifests(subagent.manifest)),+ ];+}diff --git a/packages/eve/src/setup/scaffold/create/extension.ts b/packages/eve/src/setup/scaffold/create/extension.tsindex fe0f2713c..c74e5bb7e 100644--- a/packages/eve/src/setup/scaffold/create/extension.ts+++ b/packages/eve/src/setup/scaffold/create/extension.ts@@ -132,7 +132,7 @@ distconst AGENTS_MD_TEMPLATE = `# eve Extension PackageThis package is an eve extension — a reusable package of tools, channels,-connections, skills, schedules, hooks, and instruction fragments that a consuming agent+connections, skills, schedules, subagents, hooks, and instruction fragments that a consuming agentmounts under \`agent/extensions/\`.Before writing code, read the Extensions guide from the installed eve package@@ -145,13 +145,14 @@ unavailable, use https://eve.dev/docs/extensions as a fallback.- Declare the extension in \`extension/extension.ts\` with \`defineExtension\` from\`eve/extension\`. Config is optional; read bound values via the handle's- \`.config\` in tools, channels, schedules, and hooks.+ \`.config\` in tools, channels, schedules, hooks, and tools inside contributed subagents.- Add contributions under \`extension/\` the same way as in an agent:- \`tools/\`, \`channels/\`, \`connections/\`, \`skills/\`, \`schedules/\`, \`hooks/\`, and+ \`tools/\`, \`channels/\`, \`connections/\`, \`skills/\`, \`schedules/\`, \`subagents/\`, \`hooks/\`, andoptional instruction fragments. Names come from file paths; the mount supplies the namespace, soname tools for what they do (\`search\`, not \`crm_search\`).-- An extension cannot declare \`agent.ts\`, \`sandbox\`, or nested- \`extensions/\` — those belong to the consuming agent.+- The extension root cannot declare \`agent.ts\`, \`sandbox\`, or nested+ \`extensions/\`. A subagent under \`extension/subagents/\` owns its own agent+ configuration and sandbox.## Build and publishdiff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.tsindex be962b95a..7681ca569 100644--- a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts+++ b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts@@ -98,6 +98,34 @@ const EXT_TREE: Readonly<Record<string, string>> = {"});","",].join("\n"),+ "extension/subagents/reviewer/agent.ts": [+ 'import { defineAgent } from "eve";',+ "export default defineAgent({",+ ' model: "openai/gpt-5.4",',+ ' description: "Review CRM records.",',+ "});",+ "",+ ].join("\n"),+ "extension/subagents/reviewer/tools/key.ts": [+ 'import { defineTool } from "eve/tools";',+ 'import extension from "../../../extension.js";',+ "export default defineTool({",+ ' description: "Read the configured API key.",',+ ' inputSchema: { type: "object", properties: {}, additionalProperties: false },',+ " async execute() {",+ " return { apiKey: extension.config.apiKey };",+ " },",+ "});",+ "",+ ].join("\n"),+ "extension/subagents/weather.ts": [+ 'import { defineRemoteAgent } from "eve";',+ "export default defineRemoteAgent({",+ ' description: "Answer weather questions.",',+ ' url: "https://weather.example.com",',+ "});",+ "",+ ].join("\n"),"extension/skills/notes.ts": ['import { defineSkill } from "eve/skills";',"export default defineSkill({",@@ -221,13 +249,25 @@ describe("mounted extension installed under node_modules", () => {);expect(JSON.parse(extensionFiles[`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`]!),- ).toMatchObject({ requires: { channel: 1, schedule: 1 } });+ ).toMatchObject({ requires: { channel: 1, schedule: 1, subagent: 1 } });const app = await scenarioApp({name: "mounted-extension-installed",installDependencies: true,files: {"agent/agent.mjs": 'export default { model: "openai/gpt-5.4" };\n',"agent/instructions.md": "You are a precise assistant.\n",+ "agent/subagents/manager/agent.mjs": [+ "export default {",+ ' model: "openai/gpt-5.4",',+ ' description: "Manage CRM reviews.",',+ "};",+ "",+ ].join("\n"),+ "agent/subagents/manager/extensions/nested.mjs": [+ `import crm from "${PACKAGE_NAME}";`,+ 'export default crm({ apiKey: "sk-installed" });',+ "",+ ].join("\n"),"agent/extensions/crm.mjs": [`import crm from "${PACKAGE_NAME}";`,'export default crm({ apiKey: "sk-installed" });',@@ -294,6 +334,33 @@ describe("mounted extension installed under node_modules", () => {});await expect(scheduledTask).resolves.toBe("sk-installed");+ const reviewer = graph.root.subagentRegistry.subagentsByName.get("crm__reviewer");+ expect(reviewer?.definition).toMatchObject({+ name: "crm__reviewer",+ sourceId: "ext:crm:subagents/reviewer",+ });+ const reviewerNode = graph.nodesByNodeId.get(reviewer!.definition.nodeId);+ const key = reviewerNode?.agent.tools.find((entry) => entry.name === "key");+ await expect(key?.execute?.({}, { messages: [], toolCallId: "call_3" })).resolves.toEqual({+ apiKey: "sk-installed",+ });+ expect(+ graph.root.subagentRegistry.subagentsByName.get("crm__weather")?.definition,+ ).toMatchObject({+ kind: "remote",+ sourceId: "ext:crm:subagents/weather.mjs",+ url: "https://weather.example.com",+ });++ const manager = graph.root.subagentRegistry.subagentsByName.get("manager");+ const managerNode = graph.nodesByNodeId.get(manager!.definition.nodeId);+ const nestedReviewer = managerNode?.subagentRegistry.subagentsByName.get("nested__reviewer");+ const nestedReviewerNode = graph.nodesByNodeId.get(nestedReviewer!.definition.nodeId);+ const nestedKey = nestedReviewerNode?.agent.tools.find((entry) => entry.name === "key");+ await expect(nestedKey?.execute?.({}, { messages: [], toolCallId: "call_4" })).resolves.toEqual(+ { apiKey: "sk-installed" },+ );+expect(graph.root.agent.skills.map((skill) => skill.name)).toEqual(expect.arrayContaining(["crm__notes", "crm__research", "crm__guide"]),);diff --git a/scripts/extension-contracts/configuration.mjs b/scripts/extension-contracts/configuration.mjsindex 746554fc0..00dd0890f 100644--- a/scripts/extension-contracts/configuration.mjs+++ b/scripts/extension-contracts/configuration.mjs@@ -20,6 +20,7 @@ export const PUBLIC_SURFACES = [{ path: "src/public/extension/index.ts", capabilities: ["extension", "config"] },{ path: "src/public/channels/index.ts", capabilities: ["channel"] },{ path: "src/public/schedules/index.ts", capabilities: ["schedule"] },+ { path: "src/public/index.ts", capabilities: ["subagent"] },{ path: "src/public/tools/index.ts", capabilities: ["tool", "dynamicTool"] },{ path: "src/public/connections/index.ts", capabilities: ["connection"] },{ path: "src/public/hooks/index.ts", capabilities: ["hook"] },