Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): report agent with framework tools (#831)

Rui376a82f9188e
diff --git a/.changeset/tidy-tools-report.md b/.changeset/tidy-tools-report.md
new file mode 100644
index 000000000..a3242eb79
--- /dev/null
+++ b/.changeset/tidy-tools-report.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Report the root-only `agent` action alongside other framework tools in agent info, including whether it is active, disabled, or replaced.
diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.md
index 96a1d557f..0f67c97c5 100644
--- a/docs/concepts/default-harness.md
+++ b/docs/concepts/default-harness.md
@@ -79,7 +79,7 @@ import { disableTool } from "eve/tools";
export default disableTool();
```
-Use `agent/tools/agent.ts` to remove the root-only `agent` delegation tool. The root session then receives no recursive delegation capability, and the model never sees the tool.
+Use `agent/tools/agent.ts` to remove the root-only `agent` delegation tool. The root session then receives no tool for delegating to a fresh copy of itself, and the model never sees that tool.
If the filename matches no known framework tool, resolution fails instead of silently doing nothing, so a typo surfaces at build time rather than removing the wrong tool.
diff --git a/docs/subagents.mdx b/docs/subagents.mdx
index b6908fd72..74481fc4e 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents.mdx
@@ -22,7 +22,7 @@ The copy uses the root's instructions, connections, auth, and sandbox. It receiv
The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
-To prevent the root session from delegating, disable `agent` the same way as any other built-in tool:
+To prevent the root session from delegating to a fresh copy of itself, disable `agent` the same way as any other built-in tool:
```ts title="agent/tools/agent.ts"
import { disableTool } from "eve/tools";
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index e87c34105..71e99a3e2 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -225,7 +225,7 @@ function createNoopRuntime(): Runtime {
}
describe("createNodeHarnessTools", () => {
- it("guides the model to split large tasks across parallel recursive agent calls", () => {
+ it("guides the model to split large tasks across parallel agent calls", () => {
const agentTool = createNodeHarnessTools({ node: createTestNode() }).get("agent");
expect(agentTool?.description).toContain("split a large task into independent pieces");
@@ -234,10 +234,14 @@ describe("createNodeHarnessTools", () => {
expect(agentTool?.description).toContain("include essential context");
expect(agentTool?.description).toContain("non-overlapping scopes");
expect(agentTool?.description).not.toContain("eve");
- expect(agentTool?.runtimeAction?.recursive).toBe(true);
+ expect(agentTool?.runtimeAction).toEqual({
+ kind: "subagent-call",
+ nodeId: ROOT_RUNTIME_AGENT_NODE_ID,
+ subagentName: "agent",
+ });
});
- it("does not give declared subagent nodes the recursive agent tool", () => {
+ it("does not give declared subagent nodes the built-in agent tool", () => {
const tools = createNodeHarnessTools({
node: createTestNode(undefined, { nodeId: "subagents/researcher" }),
});
@@ -245,7 +249,7 @@ describe("createNodeHarnessTools", () => {
expect(tools.has("agent")).toBe(false);
});
- it("does not give the root node a recursive agent tool when it is disabled", () => {
+ it("does not give the root node the built-in agent tool when it is disabled", () => {
const node = createTestNode();
const tools = createNodeHarnessTools({
node: {
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index c5f8176cd..f5b7f265e 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -18,8 +18,8 @@ import { AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME } from "#runtime/framework-tool
import { ROOT_RUNTIME_AGENT_NODE_ID, type ResolvedRuntimeAgentNode } from "#runtime/graph.js";
import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";
-import { findRegisteredRuntimeTool } from "#runtime/tools/registry.js";
import { SUBAGENT_TOOL_INPUT_SCHEMA } from "#runtime/subagents/registry.js";
+import { findRegisteredRuntimeTool } from "#runtime/tools/registry.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
import { preserveFrameworkStateOnCompaction } from "#execution/compaction.js";
import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
@@ -187,7 +187,6 @@ export function createNodeHarnessTools(input: {
runtimeAction: {
kind: "subagent-call",
nodeId: input.node.nodeId,
- recursive: true,
subagentName: AGENT_TOOL_NAME,
},
});
diff --git a/packages/eve/src/harness/advertised-tools.test.ts b/packages/eve/src/harness/advertised-tools.test.ts
index 8160144f8..f5b3eacce 100644
--- a/packages/eve/src/harness/advertised-tools.test.ts
+++ b/packages/eve/src/harness/advertised-tools.test.ts
@@ -5,13 +5,14 @@ import { getAdvertisedTools } from "#harness/advertised-tools.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { HarnessSession, HarnessToolMap } from "#harness/types.js";
import { buildToolSet } from "#harness/tools.js";
+import { ROOT_RUNTIME_AGENT_NODE_ID } from "#runtime/graph.js";
import { WORKFLOW_TOOL_NAME } from "#shared/workflow-sandbox.js";
describe("getAdvertisedTools", () => {
- it("keeps the recursive agent tool in the root session", () => {
+ it("keeps the built-in agent tool in the root session", () => {
const tools = new Map([
["add", createTool("add")],
- ["agent", createRecursiveAgentTool()],
+ ["agent", createBuiltInAgentTool()],
]) satisfies HarnessToolMap;
const advertisedTools = getAdvertisedTools({ session: {}, tools });
@@ -33,10 +34,10 @@ describe("getAdvertisedTools", () => {
expect([...advertisedTools.keys()]).toEqual(["add", "delegate"]);
});
- it("removes the recursive agent tool from delegated sessions", () => {
+ it("removes the built-in agent tool from delegated sessions", () => {
const tools = new Map([
["add", createTool("add")],
- ["agent", createRecursiveAgentTool()],
+ ["agent", createBuiltInAgentTool()],
]) satisfies HarnessToolMap;
const advertisedTools = getAdvertisedTools({
@@ -64,7 +65,7 @@ describe("getAdvertisedTools", () => {
it("removes the built-in agent tool when depth identifies a delegated session", () => {
const tools = new Map([
["add", createTool("add")],
- ["agent", createRecursiveAgentTool()],
+ ["agent", createBuiltInAgentTool()],
]) satisfies HarnessToolMap;
const advertisedTools = getAdvertisedTools({
@@ -125,10 +126,10 @@ describe("getAdvertisedTools", () => {
});
describe("getAdvertisedTools for definition arrays", () => {
- it("removes recursive agent tool definitions from delegated sessions", () => {
+ it("removes built-in agent tool definitions from delegated sessions", () => {
const advertisedTools = getAdvertisedTools({
session: { rootSessionId: "root-session", subagentDepth: 1 },
- tools: [createTool("add"), createSubagentTool("delegate"), createRecursiveAgentTool()],
+ tools: [createTool("add"), createSubagentTool("delegate"), createBuiltInAgentTool()],
});
expect(advertisedTools.map((tool) => tool.name)).toEqual(["add", "delegate"]);
@@ -154,13 +155,12 @@ function createSubagentTool(name: string): HarnessToolDefinition {
};
}
-function createRecursiveAgentTool(): HarnessToolDefinition {
+function createBuiltInAgentTool(): HarnessToolDefinition {
return {
...createSubagentTool("agent"),
runtimeAction: {
kind: "subagent-call",
- nodeId: "root",
- recursive: true,
+ nodeId: ROOT_RUNTIME_AGENT_NODE_ID,
subagentName: "agent",
},
};
diff --git a/packages/eve/src/harness/advertised-tools.ts b/packages/eve/src/harness/advertised-tools.ts
index 4e804a877..e1df9f000 100644
--- a/packages/eve/src/harness/advertised-tools.ts
+++ b/packages/eve/src/harness/advertised-tools.ts
@@ -1,6 +1,8 @@
import type { ToolSet } from "ai";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import { resolveSubagentDepth } from "#harness/subagent-depth.js";
+import { AGENT_TOOL_NAME } from "#runtime/framework-tools/agent.js";
+import { ROOT_RUNTIME_AGENT_NODE_ID } from "#runtime/graph.js";
import {
ensureWorkflowContinuationSecurity,
getWorkflowContinuationSecurity,
@@ -160,7 +162,11 @@ function shouldHideDelegationTool(
definition: HarnessToolDefinition,
session: AdvertisedToolSession,
): boolean {
- if (definition.runtimeAction?.recursive !== true) {
+ if (
+ definition.name !== AGENT_TOOL_NAME ||
+ definition.runtimeAction?.kind !== "subagent-call" ||
+ definition.runtimeAction.nodeId !== ROOT_RUNTIME_AGENT_NODE_ID
+ ) {
return false;
}
diff --git a/packages/eve/src/harness/execute-tool.ts b/packages/eve/src/harness/execute-tool.ts
index 11d45ead6..ad92b038e 100644
--- a/packages/eve/src/harness/execute-tool.ts
+++ b/packages/eve/src/harness/execute-tool.ts
@@ -12,7 +12,6 @@ import type { ToolExecuteOptions } from "#shared/tool-definition.js";
export type HarnessRuntimeActionDefinition = {
readonly kind: "remote-agent-call" | "subagent-call";
readonly nodeId: string;
- readonly recursive?: true;
readonly remoteAgentName?: string;
readonly subagentName: string;
};
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
index 749c1126b..c47451987 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
@@ -1,27 +1,24 @@
-import {
- getAllFrameworkToolNames,
- getFrameworkToolDefinitions,
-} from "#runtime/framework-tools/index.js";
+import { getAllFrameworkToolNames } from "#runtime/framework-tools/index.js";
import {
getAllFrameworkChannelNames,
getFrameworkChannelDefinitions,
} from "#runtime/framework-channels/index.js";
import { createConnectionSearchResolver } from "#runtime/framework-tools/connection-search-dynamic.js";
import type { AgentInfoManifestData } from "#internal/nitro/routes/agent-info/load-agent-info-data.js";
-import type { ResolvedChannelDefinition, ResolvedToolDefinition } from "#runtime/types.js";
+import type { ResolvedChannelDefinition } from "#runtime/types.js";
import { LOAD_SKILL_TOOL_NAME } from "#runtime/skills/fragment-context.js";
import { WORKFLOW_TOOL_NAME } from "#shared/workflow-sandbox.js";
import type {
AgentInfoFrameworkChannelEntry,
- AgentInfoFrameworkToolEntry,
AgentInfoResponse,
} from "#internal/nitro/routes/agent-info/build-agent-info-response.js";
import {
+ buildFrameworkToolInfo,
+ getRootDelegationToolNames,
renderChannel,
renderDynamicResolver,
renderSchedule,
renderSubagent,
- renderTool,
toSource,
} from "#internal/nitro/routes/agent-info/build-agent-info-response.js";
import {
@@ -45,13 +42,7 @@ export function buildAgentInfoResponseFromManifest(
const disabledFrameworkTools = new Set(manifest.disabledFrameworkTools);
const allFrameworkToolNames = getAllFrameworkToolNames();
const allFrameworkChannelNames = getAllFrameworkChannelNames();
- const frameworkToolDefinitions = getFrameworkToolDefinitions({
- hasConnections: manifest.connections.length > 0,
- });
const frameworkChannelDefinitions = getFrameworkChannelDefinitions();
- const activeFrameworkTools = frameworkToolDefinitions.filter(
- (tool) => !authoredToolNames.has(tool.name) && !disabledFrameworkTools.has(tool.name),
- );
const authoredTools = manifest.tools.map((tool) => ({
...toSource(tool),
description: tool.description,
@@ -73,6 +64,11 @@ export function buildAgentInfoResponseFromManifest(
(channel) =>
!authoredChannelNames.has(channel.name) && !disabledFrameworkChannelNames.has(channel.name),
);
+ const frameworkToolInfo = buildFrameworkToolInfo({
+ authoredToolNames,
+ delegationToolNames: getRootDelegationToolNames(manifest),
+ disabledFrameworkToolNames: disabledFrameworkTools,
+ });
const renderedAuthoredChannels = authoredChannels.map((channel) => ({
...toSource(channel),
adapterKind: channel.adapterKind,
@@ -201,15 +197,7 @@ export function buildAgentInfoResponseFromManifest(
total: manifest.subagents.length,
},
tools: {
- available: [
- ...activeFrameworkTools.map((tool) =>
- renderTool(tool as ResolvedToolDefinition, {
- origin: "framework",
- replacesFrameworkTool: false,
- }),
- ),
- ...authoredTools,
- ],
+ available: [...frameworkToolInfo.available, ...authoredTools],
authored: authoredTools,
disabledFramework: [...manifest.disabledFrameworkTools],
dynamic: [
@@ -220,25 +208,7 @@ export function buildAgentInfoResponseFromManifest(
renderDynamicResolver(resolver, { origin: "authored" }),
),
],
- framework: frameworkToolDefinitions.map((tool) => {
- const replacedByAuthoredTool = authoredToolNames.has(tool.name);
- const disabledByAuthor = disabledFrameworkTools.has(tool.name);
- const status: AgentInfoFrameworkToolEntry["status"] = disabledByAuthor
- ? "disabled"
- : replacedByAuthoredTool
- ? "replaced"
- : "active";
-
- return {
- ...renderTool(tool as ResolvedToolDefinition, {
- origin: "framework",
- replacesFrameworkTool: false,
- }),
- disabledByAuthor,
- replacedByAuthoredTool,
- status,
- };
- }),
+ framework: frameworkToolInfo.framework,
reserved: [WORKFLOW_TOOL_NAME, LOAD_SKILL_TOOL_NAME],
},
version: 1,
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts
new file mode 100644
index 000000000..5898486fe
--- /dev/null
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import { buildFrameworkToolInfo } from "#internal/nitro/routes/agent-info/build-agent-info-response.js";
+
+describe("buildFrameworkToolInfo", () => {
+ it("reports the built-in agent action as active and available by default", () => {
+ const info = buildFrameworkToolInfo({
+ authoredToolNames: new Set(),
+ delegationToolNames: new Set(),
+ disabledFrameworkToolNames: new Set(),
+ });
+
+ expect(info.available.map((tool) => tool.name)).toContain("agent");
+ expect(info.framework.find((tool) => tool.name === "agent")).toMatchObject({
+ status: "active",
+ });
+ });
+
+ it("reports the built-in agent action as disabled and unavailable", () => {
+ const info = buildFrameworkToolInfo({
+ authoredToolNames: new Set(),
+ delegationToolNames: new Set(),
+ disabledFrameworkToolNames: new Set(["agent"]),
+ });
+
+ expect(info.available.map((tool) => tool.name)).not.toContain("agent");
+ expect(info.framework.find((tool) => tool.name === "agent")).toMatchObject({
+ disabledByAuthor: true,
+ status: "disabled",
+ });
+ });
+
+ it("reports a declared agent delegation tool as replacing the recursive action", () => {
+ const info = buildFrameworkToolInfo({
+ authoredToolNames: new Set(),
+ delegationToolNames: new Set(["agent"]),
+ disabledFrameworkToolNames: new Set(),
+ });
+
+ expect(info.available.map((tool) => tool.name)).not.toContain("agent");
+ expect(info.framework.find((tool) => tool.name === "agent")).toMatchObject({
+ replacedByAuthoredTool: false,
+ status: "replaced",
+ });
+ });
+
+ it("reports an authored agent tool as replacing the recursive action", () => {
+ const info = buildFrameworkToolInfo({
+ authoredToolNames: new Set(["agent"]),
+ delegationToolNames: new Set(),
+ disabledFrameworkToolNames: new Set(),
+ });
+
+ expect(info.framework.find((tool) => tool.name === "agent")).toMatchObject({
+ replacedByAuthoredTool: true,
+ status: "replaced",
+ });
+ });
+});
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
index 1aaf75d09..5504bf7f4 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
@@ -1,6 +1,7 @@
+import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";
import {
+ getAllFrameworkToolDefinitions,
getAllFrameworkToolNames,
- getFrameworkToolDefinitions,
} from "#runtime/framework-tools/index.js";
import {
getAllFrameworkChannelNames,
@@ -9,6 +10,7 @@ import {
import { createConnectionSearchResolver } from "#runtime/framework-tools/connection-search-dynamic.js";
import type {
AgentInfoData,
+ CompiledAgentManifest,
CompiledSubagentNode,
ResolvedSandboxDefinition,
ResolvedScheduleDefinition,
@@ -215,7 +217,7 @@ export function buildAgentInfoResponse(
},
): AgentInfoResponse {
const agent = data.agent;
- const tools = buildToolInfo(agent);
+ const tools = buildToolInfo(agent, getRootDelegationToolNames(data.manifest));
return {
agent: {
@@ -343,54 +345,29 @@ function buildChannelInfo(agent: ResolvedAgent): AgentInfoChannels {
};
}
-function buildToolInfo(agent: ResolvedAgent): AgentInfoTools {
+function buildToolInfo(
+ agent: ResolvedAgent,
+ delegationToolNames: ReadonlySet<string>,
+): AgentInfoTools {
const authoredToolNames = new Set(agent.tools.map((tool) => tool.name));
const disabledFrameworkTools = new Set(agent.disabledFrameworkTools);
const allFrameworkToolNames = getAllFrameworkToolNames();
- const frameworkToolDefinitions = getFrameworkToolDefinitions({
- hasConnections: agent.connections.length > 0,
- });
const dynamicFrameworkResolvers =
agent.connections.length > 0 ? [createConnectionSearchResolver()] : [];
- const activeFrameworkTools = frameworkToolDefinitions.filter(
- (tool) => !authoredToolNames.has(tool.name) && !disabledFrameworkTools.has(tool.name),
- );
const authored = agent.tools.map((tool) =>
renderTool(tool, {
origin: "authored",
replacesFrameworkTool: allFrameworkToolNames.has(tool.name),
}),
);
- const framework = frameworkToolDefinitions.map((tool) => {
- const replacedByAuthoredTool = authoredToolNames.has(tool.name);
- const disabledByAuthor = disabledFrameworkTools.has(tool.name);
- const status: AgentInfoFrameworkToolEntry["status"] = disabledByAuthor
- ? "disabled"
- : replacedByAuthoredTool
- ? "replaced"
- : "active";
-
- return {
- ...renderTool(tool, {
- origin: "framework",
- replacesFrameworkTool: false,
- }),
- disabledByAuthor,
- replacedByAuthoredTool,
- status,
- };
+ const frameworkInfo = buildFrameworkToolInfo({
+ authoredToolNames,
+ delegationToolNames,
+ disabledFrameworkToolNames: disabledFrameworkTools,
});
return {
- available: [
- ...activeFrameworkTools.map((tool) =>
- renderTool(tool, {
- origin: "framework",
- replacesFrameworkTool: false,
- }),
- ),
- ...authored,
- ],
+ available: [...frameworkInfo.available, ...authored],
authored,
disabledFramework: [...agent.disabledFrameworkTools],
dynamic: [
@@ -401,11 +378,63 @@ function buildToolInfo(agent: ResolvedAgent): AgentInfoTools {
renderDynamicResolver(resolver, { origin: "authored" }),
),
],
- framework,
+ framework: frameworkInfo.framework,
reserved: [WORKFLOW_TOOL_NAME, LOAD_SKILL_TOOL_NAME],
};
}
+export function buildFrameworkToolInfo(input: {
+ readonly authoredToolNames: ReadonlySet<string>;
+ readonly delegationToolNames: ReadonlySet<string>;
+ readonly disabledFrameworkToolNames: ReadonlySet<string>;
+}): Pick<AgentInfoTools, "available" | "framework"> {
+ const occupiedToolNames = new Set([...input.authoredToolNames, ...input.delegationToolNames]);
+ const available: AgentInfoToolEntry[] = [];
+ const framework: AgentInfoFrameworkToolEntry[] = [];
+
+ for (const definition of getAllFrameworkToolDefinitions()) {
+ const disabledByAuthor = input.disabledFrameworkToolNames.has(definition.name);
+ const replacedByAuthoredTool = input.authoredToolNames.has(definition.name);
+ const status: AgentInfoFrameworkToolEntry["status"] = disabledByAuthor
+ ? "disabled"
+ : occupiedToolNames.has(definition.name)
+ ? "replaced"
+ : "active";
+ const rendered = renderTool(definition, {
+ origin: "framework",
+ replacesFrameworkTool: false,
+ });
+
+ if (status === "active") {
+ available.push(rendered);
+ }
+
+ framework.push({
+ ...rendered,
+ disabledByAuthor,
+ replacedByAuthoredTool,
+ status,
+ });
+ }
+
+ return { available, framework };
+}
+
+export function getRootDelegationToolNames(manifest: CompiledAgentManifest): ReadonlySet<string> {
+ const rootChildNodeIds = new Set(
+ manifest.subagentEdges
+ .filter((edge) => edge.parentNodeId === ROOT_COMPILED_AGENT_NODE_ID)
+ .map((edge) => edge.childNodeId),
+ );
+
+ return new Set([
+ ...manifest.subagents
+ .filter((subagent) => rootChildNodeIds.has(subagent.nodeId))
+ .map((subagent) => subagent.name),
+ ...manifest.remoteAgents.map((remoteAgent) => remoteAgent.name),
+ ]);
+}
+
export function renderChannel(
channel: ResolvedChannelDefinition,
input: {
diff --git a/packages/eve/src/internal/testing/scenario-apps/tool-overrides.ts b/packages/eve/src/internal/testing/scenario-apps/tool-overrides.ts
index 789676221..bb24aeadd 100644
--- a/packages/eve/src/internal/testing/scenario-apps/tool-overrides.ts
+++ b/packages/eve/src/internal/testing/scenario-apps/tool-overrides.ts
@@ -2,7 +2,7 @@ import type { ScenarioAppDescriptor } from "#internal/testing/scenario-app.js";
/**
* Scenario-tier descriptor exercising every framework-tool override pattern:
- * wrap (`bash`), replace (`todo`), and disable (`web_fetch`, `web_search`).
+ * wrap (`bash`), replace (`todo`), and disable (`agent`, `web_fetch`, `web_search`).
* The compile pipeline must preserve the override semantics end-to-end.
*/
export const TOOL_OVERRIDES_DESCRIPTOR: ScenarioAppDescriptor = {
@@ -19,6 +19,11 @@ export default defineAgent({
});
`,
"agent/instructions.md": `A fixture agent that exercises every framework-tool override pattern: wrap, disable, and replace.
+`,
+ "agent/tools/agent.ts": `import { disableTool } from "eve/tools";
+
+// Removes the root-only recursive self-copy tool.
+export default disableTool();
`,
"agent/tools/bash.ts": `import { defineTool } from "eve/tools";
import { always } from "eve/tools/approval";
diff --git a/packages/eve/src/runtime/framework-tools/agent.ts b/packages/eve/src/runtime/framework-tools/agent.ts
index 6ea842e0d..f17993d54 100644
--- a/packages/eve/src/runtime/framework-tools/agent.ts
+++ b/packages/eve/src/runtime/framework-tools/agent.ts
@@ -1,10 +1,13 @@
+import { SUBAGENT_TOOL_INPUT_SCHEMA } from "#runtime/subagents/registry.js";
+import type { ResolvedToolDefinition } from "#runtime/types.js";
+
/**
- * Stable model-visible name for the root-only recursive agent tool.
+ * Stable model-visible name for the root-only agent delegation tool.
*/
export const AGENT_TOOL_NAME = "agent";
/**
- * Model-facing instructions for the root-only recursive agent tool.
+ * Model-facing instructions for the root-only agent delegation tool.
*/
export const AGENT_TOOL_DESCRIPTION = [
"Delegate a focused subtask to a fresh copy of yourself.",
@@ -12,3 +15,15 @@ export const AGENT_TOOL_DESCRIPTION = [
"Issue multiple `agent` calls in one response to run a small fixed set in parallel.",
"Each child has fresh history and state but shares your tools and sandbox, so include essential context in `message` and give parallel writers non-overlapping scopes.",
].join(" ");
+
+/**
+ * Shared metadata for the root-only agent delegation tool.
+ */
+export const AGENT_TOOL_DEFINITION: ResolvedToolDefinition = {
+ description: AGENT_TOOL_DESCRIPTION,
+ inputSchema: SUBAGENT_TOOL_INPUT_SCHEMA,
+ logicalPath: "eve:framework/agent",
+ name: AGENT_TOOL_NAME,
+ sourceId: "eve:agent-tool",
+ sourceKind: "module",
+};
diff --git a/packages/eve/src/runtime/framework-tools/index.test.ts b/packages/eve/src/runtime/framework-tools/index.test.ts
index 2f817cd16..c82c1cccd 100644
--- a/packages/eve/src/runtime/framework-tools/index.test.ts
+++ b/packages/eve/src/runtime/framework-tools/index.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import {
+ getAllFrameworkToolDefinitions,
getAllFrameworkToolNames,
getFrameworkToolDefinitions,
} from "#runtime/framework-tools/index.js";
@@ -23,18 +24,21 @@ describe("framework-tools/index", () => {
expect(names.has("connection_search")).toBe(false);
});
- it("never returns undefined entries", () => {
- for (const config of [{ hasConnections: true }, { hasConnections: false }] as const) {
- const tools = getFrameworkToolDefinitions(config);
- for (const tool of tools) {
- expect(tool, `framework tool entry is undefined`).toBeDefined();
- expect(tool.name).toBeTypeOf("string");
- expect(tool.name.length).toBeGreaterThan(0);
- }
+ it("contains every framework tool exactly once", () => {
+ const tools = getAllFrameworkToolDefinitions();
+ const names = tools.map((tool) => tool.name);
+
+ expect(new Set(names).size).toBe(names.length);
+ for (const tool of tools) {
+ expect(tool.name).toBeTypeOf("string");
+ expect(tool.name.length).toBeGreaterThan(0);
}
+
+ expect(names).toContain("agent");
+ expect(getFrameworkToolDefinitions().map((tool) => tool.name)).not.toContain("agent");
});
- it("declares an output schema for every statically shaped framework tool", () => {
+ it("declares an output schema for every statically shaped registered tool", () => {
const tools = getFrameworkToolDefinitions();
for (const tool of tools) {
if (tool.name === "web_search") {
@@ -46,9 +50,12 @@ describe("framework-tools/index", () => {
}
});
- it("returns the same tools regardless of hasConnections", () => {
+ it("returns the same registered tools regardless of hasConnections", () => {
const withConnections = getFrameworkToolDefinitions({ hasConnections: true });
const withoutConnections = getFrameworkToolDefinitions({ hasConnections: false });
- expect(withConnections.map((t) => t.name)).toEqual(withoutConnections.map((t) => t.name));
+
+ expect(withConnections.map((tool) => tool.name)).toEqual(
+ withoutConnections.map((tool) => tool.name),
+ );
});
});
diff --git a/packages/eve/src/runtime/framework-tools/index.ts b/packages/eve/src/runtime/framework-tools/index.ts
index 97cf2b876..40c585e70 100644
--- a/packages/eve/src/runtime/framework-tools/index.ts
+++ b/packages/eve/src/runtime/framework-tools/index.ts
@@ -1,4 +1,4 @@
-import { AGENT_TOOL_NAME } from "#runtime/framework-tools/agent.js";
+import { AGENT_TOOL_DEFINITION } from "#runtime/framework-tools/agent.js";
import { ASK_QUESTION_TOOL_DEFINITION } from "#runtime/framework-tools/ask-question.js";
import { BASH_TOOL_DEFINITION } from "#runtime/framework-tools/bash.js";
import { GLOB_TOOL_DEFINITION } from "#runtime/framework-tools/glob.js";
@@ -18,7 +18,7 @@ export { TodoStateKey } from "#runtime/framework-tools/todo.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
-const ALL_FRAMEWORK_TOOLS: readonly ResolvedToolDefinition[] = [
+const REGISTERED_FRAMEWORK_TOOLS: readonly ResolvedToolDefinition[] = [
ASK_QUESTION_TOOL_DEFINITION,
BASH_TOOL_DEFINITION,
GLOB_TOOL_DEFINITION,
@@ -31,16 +31,29 @@ const ALL_FRAMEWORK_TOOLS: readonly ResolvedToolDefinition[] = [
SKILL_TOOL_DEFINITION,
];
+const ALL_FRAMEWORK_TOOLS: readonly ResolvedToolDefinition[] = [
+ ...REGISTERED_FRAMEWORK_TOOLS,
+ AGENT_TOOL_DEFINITION,
+];
+
/**
* Returns framework-owned tool definitions registered in the tool registry
* alongside authored tools during graph resolution.
*
- * `connection_search` is no longer in this list — it is registered as a
- * framework dynamic tool resolver in the graph resolution path.
+ * `connection_search` is no longer in this list. The graph resolution path
+ * registers it as a framework dynamic tool resolver.
*/
export function getFrameworkToolDefinitions(_config?: {
readonly hasConnections?: boolean;
}): readonly ResolvedToolDefinition[] {
+ return REGISTERED_FRAMEWORK_TOOLS;
+}
+
+/**
+ * Returns every static framework-owned tool definition, including tools such
+ * as `agent` that the runtime does not register in the tool registry.
+ */
+export function getAllFrameworkToolDefinitions(): readonly ResolvedToolDefinition[] {
return ALL_FRAMEWORK_TOOLS;
}
@@ -54,5 +67,5 @@ export function getFrameworkToolDefinitions(_config?: {
* as an authoring error rather than silently dropping the request.
*/
export function getAllFrameworkToolNames(): ReadonlySet<string> {
- return new Set([...ALL_FRAMEWORK_TOOLS.map((def) => def.name), AGENT_TOOL_NAME]);
+ return new Set(ALL_FRAMEWORK_TOOLS.map((definition) => definition.name));
}
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index 10785bcf6..9b494a81e 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -146,7 +146,8 @@ export type ResolvedSandboxDefinition = ResolvedModuleSourceRef & {
};
/**
- * Runtime-owned authored tool definition resolved from a compiled module map.
+ * Runtime-owned tool definition resolved from a compiled module map or
+ * declared by the framework catalog.
* A tool without `execute` is surfaced to the client and never executed by eve.
*/
export type ResolvedToolDefinition = Readonly<
diff --git a/packages/eve/test/runtime-agent-framework-tools.test.ts b/packages/eve/test/runtime-agent-framework-tools.test.ts
new file mode 100644
index 000000000..d9ad5e544
--- /dev/null
+++ b/packages/eve/test/runtime-agent-framework-tools.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ createCompiledAgentManifest,
+ createCompiledAgentNodeManifest,
+ ROOT_COMPILED_AGENT_NODE_ID,
+} from "../src/compiler/manifest.js";
+import { createNodeHarnessTools } from "../src/execution/node-step.js";
+import { TEST_DEFAULT_MODEL_ID } from "../src/internal/testing/app-harness.js";
+import { resolveRuntimeAgentGraph } from "../src/runtime/resolve-agent-graph.js";
+
+describe("runtime agent framework tools", () => {
+ it("lets an authored agent tool replace the built-in agent action", async () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: {
+ id: TEST_DEFAULT_MODEL_ID,
+ routing: { kind: "gateway", target: "openai" },
+ },
+ name: "weather-agent",
+ },
+ tools: [
+ {
+ description: "Delegate through an authored implementation.",
+ inputSchema: null,
+ logicalPath: "tools/agent.mjs",
+ name: "agent",
+ sourceId: "tools/agent.mjs",
+ sourceKind: "module",
+ },
+ ],
+ });
+ const graph = await resolveRuntimeAgentGraph({
+ manifest,
+ moduleMap: {
+ nodes: {
+ [ROOT_COMPILED_AGENT_NODE_ID]: {
+ modules: {
+ "tools/agent.mjs": {
+ default: {
+ description: "Delegate through an authored implementation.",
+ execute: () => "authored-agent",
+ },
+ },
+ },
+ },
+ },
+ },
+ });
+
+ expect(graph.root.turnAgent.tools.filter((tool) => tool.name === "agent")).toMatchObject([
+ { kind: "authored-tool" },
+ ]);
+ expect(
+ createNodeHarnessTools({ node: graph.root }).get("agent")?.runtimeAction,
+ ).toBeUndefined();
+ });
+
+ it("lets a declared subagent named agent replace the built-in agent action", async () => {
+ const child = createCompiledAgentNodeManifest({
+ agentRoot: "/app/agent/subagents/agent",
+ appRoot: "/app",
+ config: {
+ model: {
+ id: TEST_DEFAULT_MODEL_ID,
+ routing: { kind: "gateway", target: "openai" },
+ },
+ name: "agent",
+ },
+ });
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: {
+ id: TEST_DEFAULT_MODEL_ID,
+ routing: { kind: "gateway", target: "openai" },
+ },
+ name: "root-agent",
+ },
+ subagentEdges: [
+ {
+ childNodeId: "subagents/agent",
+ parentNodeId: ROOT_COMPILED_AGENT_NODE_ID,
+ },
+ ],
+ subagents: [
+ {
+ agent: child,
+ description: "A declared specialist named agent.",
+ entryPath: "/app/agent/subagents/agent",
+ logicalPath: "subagents/agent",
+ name: "agent",
+ nodeId: "subagents/agent",
+ rootPath: "/app/agent/subagents/agent",
+ sourceId: "subagents/agent",
+ sourceKind: "module",
+ },
+ ],
+ });
+ const graph = await resolveRuntimeAgentGraph({
+ manifest,
+ moduleMap: {
+ nodes: {
+ [ROOT_COMPILED_AGENT_NODE_ID]: { modules: {} },
+ "subagents/agent": { modules: {} },
+ },
+ },
+ });
+
+ expect(graph.root.turnAgent.tools.filter((tool) => tool.name === "agent")).toMatchObject([
+ { kind: "subagent" },
+ ]);
+ const runtimeAction = createNodeHarnessTools({ node: graph.root }).get("agent")?.runtimeAction;
+ expect(runtimeAction?.subagentName).toBe("agent");
+ });
+});
diff --git a/packages/eve/test/runtime-agent-graph.test.ts b/packages/eve/test/runtime-agent-graph.test.ts
index 801a17f43..24913beaf 100644
--- a/packages/eve/test/runtime-agent-graph.test.ts
+++ b/packages/eve/test/runtime-agent-graph.test.ts
@@ -6,6 +6,7 @@ import {
} from "../src/compiler/manifest.js";
import type { CompiledModuleMap } from "../src/compiler/module-map.js";
import { defineAgent } from "../src/public/definitions/agent.js";
+import { createNodeHarnessTools } from "../src/execution/node-step.js";
import { TEST_DEFAULT_MODEL_ID } from "../src/internal/testing/app-harness.js";
import { ROOT_RUNTIME_AGENT_NODE_ID } from "../src/runtime/graph.js";
import { resolveRuntimeAgentGraph } from "../src/runtime/resolve-agent-graph.js";
@@ -770,6 +771,7 @@ describe("resolveRuntimeAgentGraph", () => {
});
expect(graph.root.agent.disabledFrameworkTools).toContain("agent");
+ expect(createNodeHarnessTools({ node: graph.root }).has("agent")).toBe(false);
});
it("combines replacement and disable in one agent", async () => {
diff --git a/packages/eve/test/scenarios/agent-info-route.scenario.test.ts b/packages/eve/test/scenarios/agent-info-route.scenario.test.ts
index c06a4f2bc..b5b5901a4 100644
--- a/packages/eve/test/scenarios/agent-info-route.scenario.test.ts
+++ b/packages/eve/test/scenarios/agent-info-route.scenario.test.ts
@@ -15,6 +15,7 @@ const createAppRoot = useTemporaryAppRoots();
const APP_ROOT_OPTIONS = { packageName: "agent-info-route-test-agent" } as const;
const EVE_CHANNEL_IMPORT_URL = new URL("../../dist/src/public/channels/eve.js", import.meta.url);
+const EVE_TOOLS_IMPORT_URL = new URL("../../dist/src/public/tools/index.js", import.meta.url);
const INFO_ROUTE_KEY = `GET ${EVE_INFO_ROUTE_PATH}`;
// Loopback request — `localDev()` authenticates this one. Models a
@@ -59,6 +60,19 @@ async function installEveChannelShim(appRoot: string): Promise<void> {
);
}
+async function installEveToolsShim(appRoot: string): Promise<void> {
+ const packageRoot = join(appRoot, "node_modules", "eve");
+ await mkdir(packageRoot, { recursive: true });
+ await writeFile(
+ join(packageRoot, "package.json"),
+ `${JSON.stringify({ name: "eve", type: "module", exports: { "./tools": "./tools.js" } })}\n`,
+ );
+ await writeFile(
+ join(packageRoot, "tools.js"),
+ `export { disableTool } from ${JSON.stringify(EVE_TOOLS_IMPORT_URL.href)};\n`,
+ );
+}
+
function createInfoEvent(request: Request): H3Event {
Object.assign(request, { ip: "127.0.0.1" });
const event: MinimalAgentInfoH3Event = {
@@ -84,6 +98,7 @@ describe("eve agent info route", () => {
await writeFile(join(agentRoot, "agent.mjs"), 'export default { model: "openai/gpt-5.4" };\n');
await writeFile(join(agentRoot, "instructions.md"), "You are a precise assistant.\n");
await mkdir(join(agentRoot, "tools"), { recursive: true });
+ await installEveToolsShim(appRoot);
await writeFile(
join(agentRoot, "tools", "get_weather.mjs"),
'export default { description: "Get the weather.", async execute() { return { temperature: 72 }; } };\n',
@@ -109,11 +124,16 @@ describe("eve agent info route", () => {
expect(payload.instructions.dynamic).toEqual([]);
expect(payload.tools.authored.map((tool) => tool.name)).toEqual(["get_weather"]);
expect(payload.tools.available.map((tool) => tool.name)).toContain("bash");
+ expect(payload.tools.available.map((tool) => tool.name)).toContain("agent");
expect(payload.tools.available.map((tool) => tool.name)).toContain("get_weather");
expect(payload.tools.framework.find((tool) => tool.name === "bash")).toMatchObject({
origin: "framework",
status: "active",
});
+ expect(payload.tools.framework.find((tool) => tool.name === "agent")).toMatchObject({
+ origin: "framework",
+ status: "active",
+ });
expect(payload.channels.available.map((channel) => channel.urlPath)).toContain(
EVE_CREATE_SESSION_ROUTE_PATH,
);
@@ -122,6 +142,22 @@ describe("eve agent info route", () => {
discoveryErrors: 0,
discoveryWarnings: 0,
});
+
+ await writeFile(
+ join(agentRoot, "tools", "agent.mjs"),
+ 'import { disableTool } from "eve/tools";\nexport default disableTool();\n',
+ );
+ await compileAgent({ startPath: appRoot });
+
+ const disabledPayload = (await (
+ await requestAgentInfo(appRoot, LOOPBACK_REQUEST)
+ ).json()) as AgentInfoResponse;
+
+ expect(disabledPayload.tools.available.map((tool) => tool.name)).not.toContain("agent");
+ expect(disabledPayload.tools.framework.find((tool) => tool.name === "agent")).toMatchObject({
+ disabledByAuthor: true,
+ status: "disabled",
+ });
});
it("returns 401 without a Vercel OIDC bearer token when the request is addressed to a public hostname", async () => {
diff --git a/packages/eve/test/scenarios/bundle-module-evaluation.scenario.test.ts b/packages/eve/test/scenarios/bundle-module-evaluation.scenario.test.ts
index 6dd0d2515..22929d5a8 100644
--- a/packages/eve/test/scenarios/bundle-module-evaluation.scenario.test.ts
+++ b/packages/eve/test/scenarios/bundle-module-evaluation.scenario.test.ts
@@ -115,7 +115,7 @@ describe("eve dist single-chunk module evaluation", () => {
});
const loaded = await import(pathToFileURL(outfile).href);
- const tools = loaded.default.getFrameworkToolDefinitions({ hasConnections: true });
+ const tools = loaded.default.getAllFrameworkToolDefinitions();
expect(tools.length).toBeGreaterThan(0);
for (const tool of tools) {
expect(tool, "framework tool entry must be defined").toBeDefined();
diff --git a/packages/eve/test/scenarios/compile-agent.scenario.test.ts b/packages/eve/test/scenarios/compile-agent.scenario.test.ts
index b9f76d88f..b4226e0ba 100644
--- a/packages/eve/test/scenarios/compile-agent.scenario.test.ts
+++ b/packages/eve/test/scenarios/compile-agent.scenario.test.ts
@@ -682,7 +682,11 @@ describe("compileAgent", () => {
// The disable sentinel reaches the compiled manifest as a name in the
// dedicated array, not as a tool entry.
- expect([...result.manifest.disabledFrameworkTools].sort()).toEqual(["web_fetch", "web_search"]);
+ expect([...result.manifest.disabledFrameworkTools].sort()).toEqual([
+ "agent",
+ "web_fetch",
+ "web_search",
+ ]);
// Both the wrapped bash and the replacement todo land in `tools` as
// ordinary CompiledToolDefinitions. The web_fetch override is intentionally