Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 extensions
diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
index 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 database
Every 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 =