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.mdnew file mode 100644index 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.mdindex 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.mdxindex 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 receivThe 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.tsindex 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.tsindex 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-toolimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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