Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.ts
skills/triage/SKILL.md
schedules/sync.ts
+ subagents/reviewer/agent.ts
instructions.md
hooks/audit.ts
lib/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 publish
The 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 events
diff --git a/docs/subagents/index.mdx b/docs/subagents/index.mdx
index 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 availability
To 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-catalog
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 @@ dist
const AGENTS_MD_TEMPLATE = `# eve Extension Package
This 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 agent
mounts 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/\`, and
optional instruction fragments. Names come from file paths; the mount supplies the namespace, so
name 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 publish
diff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
index 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.mjs
index 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"] },