The Open Framework for Building Agents
fix(eve): match every mounted name for a shared tool definition (#4346)
Andrew Barba073281ca5c48
diff --git a/.changeset/shared-tool-result-identity.md b/.changeset/shared-tool-result-identity.mdnew file mode 100644index 000000000..bb701ebb2--- /dev/null+++ b/.changeset/shared-tool-result-identity.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Fix a spurious `toolResultFrom` identity warning when one tool definition is mounted under more than one name, such as the code extension's `grep` tool in its worker subagent. `toolResultFrom` now matches results from every name that definition is mounted under.diff --git a/docs/extensions.md b/docs/extensions.mdindex a039bd1ac..ae80e84e5 100644--- a/docs/extensions.md+++ b/docs/extensions.md@@ -357,7 +357,7 @@ export default defineHook({});```-`toolResultFrom` recognizes the mounted `crm__search` result from the original definition, not the namespaced string. Publishers should keep tool descriptions distinct so eve can assign each definition an unambiguous identity.+`toolResultFrom` recognizes the mounted `crm__search` result from the original definition, not the namespaced string. Publishers should keep descriptions distinct across different tool definitions so eve can assign each definition an unambiguous identity. Re-exporting the same definition, such as from a subagent's `tools/` directory, does not conflict.### Bundled development extensionsdiff --git a/docs/guides/hooks.md b/docs/guides/hooks.mdindex 3b281021f..5400d802d 100644--- a/docs/guides/hooks.md+++ b/docs/guides/hooks.md@@ -135,6 +135,8 @@ import { search } from "@acme/crm/tools";const crmSearch = toolResultFrom(event.data.result, search); // typed; matches crm__search```+When one definition is mounted under more than one tool name, for example when a subagent re-exports an extension tool, `toolResultFrom` matches results from every mounted name.+### Persist events to your own databaseEvery event carries a `meta` envelope with `meta.id`, a unique, sortable identifier for that event. It makes a natural primary key for an events table:diff --git a/packages/eve/src/internal/authored-definition/source-identity.ts b/packages/eve/src/internal/authored-definition/source-identity.tsindex 54762062a..d6cbad5b4 100644--- a/packages/eve/src/internal/authored-definition/source-identity.ts+++ b/packages/eve/src/internal/authored-definition/source-identity.ts@@ -1,47 +1,113 @@-type DefinitionSourceEntry =- | { readonly kind: "connection"; readonly logicalPath?: string; readonly name: string }- | { readonly kind: "tool"; readonly logicalPath?: string; readonly name: string };+type DefinitionSourceKind = "connection" | "tool";-type AmbiguousDefinitionSourceEntry = { readonly kind: "ambiguous" };-type RegisteredDefinitionSource = DefinitionSourceEntry | AmbiguousDefinitionSourceEntry;+type DefinitionSourceEntry = {+ readonly kind: DefinitionSourceKind;+ readonly logicalPath?: string;+ readonly name: string;+};++type DefinitionSource = {+ readonly kind: DefinitionSourceKind;+ readonly names: Set<string>;+};++type FallbackDefinitionSource =+ | (DefinitionSource & {+ readonly definitions: WeakSet<object>;+ readonly firstEntry: DefinitionSourceEntry;+ })+ | { readonly kind: "ambiguous" };++export type RegisteredDefinitionSource =+ | { readonly kind: DefinitionSourceKind; readonly names: ReadonlySet<string> }+ | { readonly kind: "ambiguous" };const DEFINITION_KEY = Symbol.for("eve.definition-source-key");-const REGISTRY_SYMBOL = Symbol.for("eve.definition-source-registry");+const RESOLVED_REGISTRY_SYMBOL = Symbol.for("eve.resolved-definition-sources");+const FALLBACK_REGISTRY_SYMBOL = Symbol.for("eve.fallback-definition-sources");type RegistryGlobal = typeof globalThis & {- [REGISTRY_SYMBOL]?: Map<string, RegisteredDefinitionSource>;+ [RESOLVED_REGISTRY_SYMBOL]?: WeakMap<object, DefinitionSource>;+ [FALLBACK_REGISTRY_SYMBOL]?: Map<string, FallbackDefinitionSource>;};+// Registries live on globalThis so duplicate eve module instances share them.const registryContainer = globalThis as RegistryGlobal;-registryContainer[REGISTRY_SYMBOL] ??= new Map();-const definitionSourceRegistry = registryContainer[REGISTRY_SYMBOL];+registryContainer[RESOLVED_REGISTRY_SYMBOL] ??= new WeakMap();+registryContainer[FALLBACK_REGISTRY_SYMBOL] ??= new Map();+const resolvedSources = registryContainer[RESOLVED_REGISTRY_SYMBOL];+const fallbackSources = registryContainer[FALLBACK_REGISTRY_SYMBOL];+/** Stamps the authoring-time fallback key used for copies eve never loaded. */export function stampDefinitionKey(definition: object, key: string): void {Object.defineProperty(definition, DEFINITION_KEY, { configurable: true, value: key });}-export function registerDefinitionSource(key: string, entry: DefinitionSourceEntry): void {- const existing = definitionSourceRegistry.get(key);- if (existing !== undefined && !sameDefinitionSourceEntry(existing, entry)) {- if (existing.kind !== "ambiguous") {- console.warn(- [- `eve could not assign a unique toolResultFrom identity for ${JSON.stringify(key)}.`,- `Conflicting definitions: ${formatDefinitionSourceForWarning(existing)} and ${formatDefinitionSourceForWarning(entry)}.`,- "Multiple authored definitions share that fallback identity, so toolResultFrom will not match through it.",- "Use the original definition object loaded by eve so source-derived identity can be used instead.",- ].join(" "),- );- }- definitionSourceRegistry.set(key, { kind: "ambiguous" });- return;+/**+ * Records a definition object eve loaded under one mounted name. The same+ * object can be mounted more than once, for example when a subagent re-exports+ * an extension tool, so every mounted name matches it.+ *+ * `fallbackKey` also lets copies with the same stamped key match. That+ * fallback is marked ambiguous when different objects with different names+ * share it.+ */+export function registerDefinitionSource(+ definition: object,+ entry: DefinitionSourceEntry,+ fallbackKey?: string,+): void {+ const resolved = resolvedSources.get(definition);+ if (resolved === undefined || resolved.kind !== entry.kind) {+ resolvedSources.set(definition, { kind: entry.kind, names: new Set([entry.name]) });+ } else {+ resolved.names.add(entry.name);+ }+ if (fallbackKey !== undefined) {+ registerFallbackSource(fallbackKey, definition, entry);}- definitionSourceRegistry.set(key, entry);}export function readDefinitionSource(definition: object): RegisteredDefinitionSource | undefined {+ const resolved = resolvedSources.get(definition);+ if (resolved !== undefined) return resolved;const key = readDefinitionKey(definition);- return key === undefined ? undefined : definitionSourceRegistry.get(key);+ return key === undefined ? undefined : fallbackSources.get(key);+}++function registerFallbackSource(+ key: string,+ definition: object,+ entry: DefinitionSourceEntry,+): void {+ const existing = fallbackSources.get(key);+ if (existing === undefined) {+ fallbackSources.set(key, {+ definitions: new WeakSet([definition]),+ firstEntry: entry,+ kind: entry.kind,+ names: new Set([entry.name]),+ });+ return;+ }+ if (existing.kind === "ambiguous") return;+ if (+ existing.kind === entry.kind &&+ (existing.definitions.has(definition) || existing.names.has(entry.name))+ ) {+ existing.definitions.add(definition);+ existing.names.add(entry.name);+ return;+ }+ console.warn(+ [+ `eve could not assign a unique toolResultFrom identity for ${JSON.stringify(key)}.`,+ `Conflicting definitions: ${formatDefinitionSourceForWarning(existing.firstEntry)} and ${formatDefinitionSourceForWarning(entry)}.`,+ "Multiple authored definitions share that fallback identity, so toolResultFrom will not match through it.",+ "Use the original definition object loaded by eve so source-derived identity can be used instead.",+ ].join(" "),+ );+ fallbackSources.set(key, { kind: "ambiguous" });}function readDefinitionKey(definition: object): string | undefined {@@ -51,14 +117,6 @@ function readDefinitionKey(definition: object): string | undefined {return undefined;}-function sameDefinitionSourceEntry(- a: RegisteredDefinitionSource,- b: DefinitionSourceEntry,-): boolean {- if (a.kind !== b.kind) return false;- return a.name === b.name;-}-function formatDefinitionSourceForWarning(entry: DefinitionSourceEntry): string {if (entry.logicalPath === undefined) {return `${entry.kind} "${entry.name}"`;diff --git a/packages/eve/src/public/tools/result.test.ts b/packages/eve/src/public/tools/result.test.tsindex cc810cdc9..bb2ef0ac8 100644--- a/packages/eve/src/public/tools/result.test.ts+++ b/packages/eve/src/public/tools/result.test.ts@@ -4,10 +4,7 @@ import { z } from "#compiled/zod/index.js";import type { RuntimeActionResult } from "#shared/action-types.js";import { defineMcpClientConnection } from "#public/definitions/connections/mcp.js";import { defineTool } from "#tools/definition.js";-import {- registerDefinitionSource,- stampDefinitionKey,-} from "#internal/authored-definition/source-identity.js";+import { registerDefinitionSource } from "#internal/authored-definition/source-identity.js";import {toolResultFrom,type MatchedConnectionResult,@@ -58,14 +55,16 @@ describe("toolResultFrom", () => {description: "Linear",});- registerDefinitionSource("tool:Get the current weather for a city.", {- kind: "tool",- name: "get_weather",- });- registerDefinitionSource("connection:https://mcp.linear.app", {- kind: "connection",- name: "linear",- });+ registerDefinitionSource(+ weatherTool,+ { kind: "tool", name: "get_weather" },+ "tool:Get the current weather for a city.",+ );+ registerDefinitionSource(+ linearConnection,+ { kind: "connection", name: "linear" },+ "connection:https://mcp.linear.app",+ );it("matches an authored tool result and returns typed output", () => {const result = toolResultFrom(@@ -133,7 +132,7 @@ describe("toolResultFrom", () => {expect(result!.output).toEqual({ city: "NY", tempF: 65 });});- it("uses source-derived keys to distinguish tools with the same description", () => {+ it("uses loaded definitions to distinguish tools with the same description", () => {const warn = vi.spyOn(console, "warn").mockImplementation(() => {});const first = defineTool({description: "Run the shared action.",@@ -146,28 +145,16 @@ describe("toolResultFrom", () => {inputSchema: z.object({}),});- stampDefinitionKey(first, "tool-source:first-source");- stampDefinitionKey(second, "tool-source:second-source");- registerDefinitionSource("tool-source:first-source", {- kind: "tool",- logicalPath: "tools/first.ts",- name: "first_tool",- });- registerDefinitionSource("tool-source:second-source", {- kind: "tool",- logicalPath: "tools/second.ts",- name: "second_tool",- });- registerDefinitionSource("tool:Run the shared action.", {- kind: "tool",- logicalPath: "tools/first.ts",- name: "first_tool",- });- registerDefinitionSource("tool:Run the shared action.", {- kind: "tool",- logicalPath: "tools/second.ts",- name: "second_tool",- });+ registerDefinitionSource(+ first,+ { kind: "tool", logicalPath: "tools/first.ts", name: "first_tool" },+ "tool:Run the shared action.",+ );+ registerDefinitionSource(+ second,+ { kind: "tool", logicalPath: "tools/second.ts", name: "second_tool" },+ "tool:Run the shared action.",+ );expect(warn).toHaveBeenCalledOnce();expect(warn).toHaveBeenCalledWith(@@ -196,16 +183,16 @@ describe("toolResultFrom", () => {inputSchema: z.object({}),});- registerDefinitionSource("tool:Run the fallback action.", {- kind: "tool",- logicalPath: "tools/first.ts",- name: "first_tool",- });- registerDefinitionSource("tool:Run the fallback action.", {- kind: "tool",- logicalPath: "tools/second.ts",- name: "second_tool",- });+ registerDefinitionSource(+ {},+ { kind: "tool", logicalPath: "tools/first.ts", name: "first_tool" },+ "tool:Run the fallback action.",+ );+ registerDefinitionSource(+ {},+ { kind: "tool", logicalPath: "tools/second.ts", name: "second_tool" },+ "tool:Run the fallback action.",+ );expect(warn).toHaveBeenCalledOnce();expect(toolResultFrom(toolResult("first_tool", { source: "first" }), copy)).toBeUndefined();@@ -232,7 +219,7 @@ describe("toolResultFrom", () => {expect(result).toBeUndefined();});- it("uses source-derived keys to distinguish connections with the same URL", () => {+ it("uses loaded definitions to distinguish connections with the same URL", () => {const warn = vi.spyOn(console, "warn").mockImplementation(() => {});const first = defineMcpClientConnection({url: "https://mcp.example.test",@@ -243,28 +230,16 @@ describe("toolResultFrom", () => {description: "Second",});- stampDefinitionKey(first, "connection-source:first-source");- stampDefinitionKey(second, "connection-source:second-source");- registerDefinitionSource("connection-source:first-source", {- kind: "connection",- logicalPath: "connections/first.ts",- name: "first",- });- registerDefinitionSource("connection-source:second-source", {- kind: "connection",- logicalPath: "connections/second.ts",- name: "second",- });- registerDefinitionSource("connection:https://mcp.example.test", {- kind: "connection",- logicalPath: "connections/first.ts",- name: "first",- });- registerDefinitionSource("connection:https://mcp.example.test", {- kind: "connection",- logicalPath: "connections/second.ts",- name: "second",- });+ registerDefinitionSource(+ first,+ { kind: "connection", logicalPath: "connections/first.ts", name: "first" },+ "connection:https://mcp.example.test",+ );+ registerDefinitionSource(+ second,+ { kind: "connection", logicalPath: "connections/second.ts", name: "second" },+ "connection:https://mcp.example.test",+ );expect(warn).toHaveBeenCalledOnce();expect(warn).toHaveBeenCalledWith(diff --git a/packages/eve/src/public/tools/result.ts b/packages/eve/src/public/tools/result.tsindex 4ef28c6a3..f086f4c6a 100644--- a/packages/eve/src/public/tools/result.ts+++ b/packages/eve/src/public/tools/result.ts@@ -81,7 +81,7 @@ function toolResultFromImpl(if (entry.kind === "ambiguous") return undefined;if (entry.kind === "tool") {- if (result.toolName !== entry.name) return undefined;+ if (!entry.names.has(result.toolName)) return undefined;return {callId: result.callId,output: result.output,@@ -89,12 +89,15 @@ function toolResultFromImpl(};}- const prefix = entry.name + CONNECTION_TOOL_SEPARATOR;- if (!result.toolName.startsWith(prefix)) return undefined;- return {- callId: result.callId,- connectionToolName: result.toolName.slice(prefix.length),- output: result.output,- toolName: result.toolName,- };+ for (const name of entry.names) {+ const prefix = name + CONNECTION_TOOL_SEPARATOR;+ if (!result.toolName.startsWith(prefix)) continue;+ return {+ callId: result.callId,+ connectionToolName: result.toolName.slice(prefix.length),+ output: result.output,+ toolName: result.toolName,+ };+ }+ return undefined;}diff --git a/packages/eve/src/runtime/resolve-connection.ts b/packages/eve/src/runtime/resolve-connection.tsindex 5ed77eac6..e3ec6a937 100644--- a/packages/eve/src/runtime/resolve-connection.ts+++ b/packages/eve/src/runtime/resolve-connection.ts@@ -7,10 +7,7 @@ import {normalizeOpenApiConnectionDefinition,} from "#internal/authored-definition/connection.js";import { readStampedConnectionProtocol } from "#public/definitions/connections/protocol.js";-import {- registerDefinitionSource,- stampDefinitionKey,-} from "#internal/authored-definition/source-identity.js";+import { registerDefinitionSource } from "#internal/authored-definition/source-identity.js";import { toErrorMessage } from "#shared/errors.js";import type {ConnectionAuthResolver,@@ -51,20 +48,15 @@ export async function resolveConnectionDefinition(`Expected the connection export "${definition.exportName ?? "default"}" from "${definition.logicalPath}" to return an object.`,);- const sourceEntry = {- kind: "connection",- logicalPath: definition.logicalPath,- name: definition.connectionName,- } as const;-- const sourceKey = `connection-source:${definition.sourceId}`;- stampDefinitionKey(resolvedRecord, sourceKey);- registerDefinitionSource(sourceKey, sourceEntry);// Use the compiled `url` (the MCP endpoint or OpenAPI base URL) as- // the secondary key so it matches the authoring-time key stamped by+ // the fallback key so it matches the authoring-time key stamped by// the `define*` factory for both protocols. The live record only// carries `url` for MCP connections.- registerDefinitionSource(`connection:${definition.url}`, sourceEntry);+ registerDefinitionSource(+ resolvedRecord,+ { kind: "connection", logicalPath: definition.logicalPath, name: definition.connectionName },+ `connection:${definition.url}`,+ );const hasAuth = resolvedRecord.auth !== undefined;const hasHeaders = resolvedRecord.headers !== undefined;@@ -182,14 +174,11 @@ export function resolveDynamicConnectionValue(throw new Error(message);}- const sourceEntry = {+ registerDefinitionSource(value as object, {kind: "connection",logicalPath: source.logicalPath,name: source.connectionName,- } as const;- const sourceKey = `dynamic-connection-source:${source.sourceId}:${source.connectionName}`;- stampDefinitionKey(value as object, sourceKey);- registerDefinitionSource(sourceKey, sourceEntry);+ });if (protocol === "openapi") {const normalized = normalizeOpenApiConnectionDefinition(value, message);diff --git a/packages/eve/src/runtime/resolve-dynamic-tool.ts b/packages/eve/src/runtime/resolve-dynamic-tool.tsindex a4bb0c95b..a37ea5685 100644--- a/packages/eve/src/runtime/resolve-dynamic-tool.ts+++ b/packages/eve/src/runtime/resolve-dynamic-tool.ts@@ -1,10 +1,7 @@import type { CompiledDynamicToolDefinition } from "#compiler/manifest.js";import type { CompiledModuleMap } from "#compiler/module-map.js";import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";-import {- registerDefinitionSource,- stampDefinitionKey,-} from "#internal/authored-definition/source-identity.js";+import { registerDefinitionSource } from "#internal/authored-definition/source-identity.js";import { isDynamicSentinel, type DynamicSentinel } from "#dynamic/definition.js";import { toErrorMessage } from "#shared/errors.js";import type { ModuleSourceRef } from "#shared/source-ref.js";@@ -92,9 +89,7 @@ function createResolvedDynamicToolResolver();}- const sourceKey = `dynamic-tool-source:${source.sourceId}`;- stampDefinitionKey(value, sourceKey);- registerDefinitionSource(sourceKey, {+ registerDefinitionSource(value, {kind: "tool",logicalPath: source.logicalPath,name: source.slug,diff --git a/packages/eve/src/runtime/resolve-tool.test.ts b/packages/eve/src/runtime/resolve-tool.test.tsindex 5e9f8bbea..ed4b3f360 100644--- a/packages/eve/src/runtime/resolve-tool.test.ts+++ b/packages/eve/src/runtime/resolve-tool.test.ts@@ -1,10 +1,12 @@-import { describe, expect, it } from "vitest";+import { describe, expect, it, vi } from "vitest";import type { CompiledToolDefinition } from "#compiler/manifest.js";import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";import type { CompiledModuleMap } from "#compiler/module-map.js";import { normalizeToolDefinition } from "#internal/authored-definition/schema-backed.js";+import { toolResultFrom } from "#public/tools/result.js";import { resolveToolDefinition } from "#runtime/resolve-tool.js";+import type { RuntimeActionResult } from "#shared/action-types.js";import { defineTool } from "#tools/definition.js";const definition: CompiledToolDefinition = {@@ -90,3 +92,39 @@ describe("authored tool approval keys", () => {).toThrow();});});++describe("toolResultFrom identity for resolved tools", () => {+ it("matches every name one shared definition is mounted under without warning", async () => {+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ const shared = defineTool({+ description: "Search the workspace with a shared definition.",+ execute: () => null,+ inputSchema: { type: "object" },+ });+ const mounts = [+ { name: "code__search", sourceId: "tools/code__search.ts" },+ { name: "search", sourceId: "subagents/worker/tools/search.ts" },+ ];+ for (const mount of mounts) {+ await resolveToolDefinition(+ { ...definition, description: shared.description, logicalPath: mount.sourceId, ...mount },+ {+ nodes: { __root__: { modules: { [mount.sourceId]: { default: shared } } } },+ } as CompiledModuleMap,+ undefined,+ { kind: "application" },+ );+ }++ expect(warn).not.toHaveBeenCalled();+ for (const { name } of mounts) {+ expect(toolResultFrom(toolResult(name), shared)?.toolName).toBe(name);+ }+ expect(toolResultFrom(toolResult("other"), shared)).toBeUndefined();+ warn.mockRestore();+ });+});++function toolResult(toolName: string): RuntimeActionResult {+ return { callId: "call_1", kind: "tool-result", output: null, toolName };+}diff --git a/packages/eve/src/runtime/resolve-tool.ts b/packages/eve/src/runtime/resolve-tool.tsindex 5fdad276f..a3d20439b 100644--- a/packages/eve/src/runtime/resolve-tool.ts+++ b/packages/eve/src/runtime/resolve-tool.ts@@ -2,10 +2,7 @@ import type { CompiledToolDefinition } from "#compiler/manifest.js";import type { CompiledModuleMap } from "#compiler/module-map.js";import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";import { normalizeApproval } from "#internal/authored-definition/approval.js";-import {- registerDefinitionSource,- stampDefinitionKey,-} from "#internal/authored-definition/source-identity.js";+import { registerDefinitionSource } from "#internal/authored-definition/source-identity.js";import { isToolSchema, toInputSchema, toOutputSchema } from "#tools/schema.js";import { toErrorMessage } from "#shared/errors.js";import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";@@ -54,17 +51,11 @@ export async function resolveToolDefinition(describe(definition, "to return an object"),);- const sourceEntry = {- kind: "tool",- logicalPath: definition.logicalPath,- name: definition.name,- owner,- } as const;-- const sourceKey = `tool-source:${definition.sourceId}`;- stampDefinitionKey(resolvedRecord, sourceKey);- registerDefinitionSource(sourceKey, sourceEntry);- registerDefinitionSource(`tool:${resolvedRecord.description}`, sourceEntry);+ registerDefinitionSource(+ resolvedRecord,+ { kind: "tool", logicalPath: definition.logicalPath, name: definition.name },+ `tool:${resolvedRecord.description}`,+ );// A workflow tool's entry point runs from the workflow registry, never in process.const execute =