The Open Framework for Building Agents
feat(eve): expose tool name in execution context (#750)
Sharce5c06d73a7e
diff --git a/.changeset/expose-tool-context-name.md b/.changeset/expose-tool-context-name.mdnew file mode 100644index 000000000..ba693dfe7--- /dev/null+++ b/.changeset/expose-tool-context-name.md@@ -0,0 +1,5 @@+---+"eve": patch+---++`ToolContext` now exposes `toolName`, the final runtime tool name, so executors can share routing, authorization, and observability logic without duplicating path-derived or qualified names.diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdxindex 82c1b72c1..b0fa3fbea 100644--- a/docs/tools/overview.mdx+++ b/docs/tools/overview.mdx@@ -38,6 +38,7 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or- `ctx.session`: session metadata, turn, auth, parent lineage.- `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.+- `ctx.toolName`: the final runtime name the model called, including any namespace qualification.- `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.- `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.- `ctx.getSkill(id)`: read a packaged [skill](/docs/skills)'s metadata and files.diff --git a/packages/eve/src/context/build-base-tool-context.integration.test.ts b/packages/eve/src/context/build-base-tool-context.integration.test.tsindex e745a41ab..4363c7507 100644--- a/packages/eve/src/context/build-base-tool-context.integration.test.ts+++ b/packages/eve/src/context/build-base-tool-context.integration.test.ts@@ -17,7 +17,11 @@ describe("buildBaseToolContext – getSandbox abort binding", () => {const controller = new AbortController();await runtime.runAsSession({ sandbox }, async () => {- const ctx = buildBaseToolContext({ abortSignal: controller.signal, toolCallId: "call_1" });+ const ctx = buildBaseToolContext({+ options: { abortSignal: controller.signal, toolCallId: "call_1" },+ toolName: "shell",+ });+ expect(ctx.toolName).toBe("shell");const live = await ctx.getSandbox();await live.run({ command: "echo ready" });});@@ -36,7 +40,10 @@ describe("buildBaseToolContext – getSandbox abort binding", () => {const runtime = createTestRuntime();await runtime.runAsSession({ sandbox }, async () => {- const ctx = buildBaseToolContext({ toolCallId: "call_1" });+ const ctx = buildBaseToolContext({+ options: { toolCallId: "call_1" },+ toolName: "shell",+ });const live = await ctx.getSandbox();await live.run({ command: "echo ready" });});diff --git a/packages/eve/src/context/build-base-tool-context.ts b/packages/eve/src/context/build-base-tool-context.tsindex 139cf23d5..14528a12b 100644--- a/packages/eve/src/context/build-base-tool-context.ts+++ b/packages/eve/src/context/build-base-tool-context.ts@@ -7,19 +7,22 @@ import type { ToolExecuteOptions } from "#shared/tool-definition.js";export type BaseToolContext = SessionContext & {readonly abortSignal: AbortSignal;readonly callId: string;+ readonly toolName: string;};/** Builds the base context for one tool execution. */-export function buildBaseToolContext(- options: Pick<ToolExecuteOptions, "abortSignal" | "toolCallId">,-): BaseToolContext {+export function buildBaseToolContext(input: {+ readonly options: Pick<ToolExecuteOptions, "abortSignal" | "toolCallId">;+ readonly toolName: string;+}): BaseToolContext {const callbackContext = buildCallbackContext();- const signal = options.abortSignal ?? new AbortController().signal;+ const signal = input.options.abortSignal ?? new AbortController().signal;return {...callbackContext,abortSignal: signal,- callId: options.toolCallId,+ callId: input.options.toolCallId,getSandbox: async () => bindSandboxAbortSignal(await callbackContext.getSandbox(), signal),+ toolName: input.toolName,};}diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.tsindex 25be17b58..c424ef814 100644--- a/packages/eve/src/context/build-dynamic-tools.ts+++ b/packages/eve/src/context/build-dynamic-tools.ts@@ -51,7 +51,7 @@ function replayTools(metadata: readonly DurableDynamicToolMetadata[]): HarnessTotools.push({description: m.description,execute: (input: unknown, options) =>- stepFn(m.closureVars, input, buildBaseToolContext(options)),+ stepFn(m.closureVars, input, buildBaseToolContext({ options, toolName: m.name })),inputSchema: jsonSchema(m.inputSchema),name: m.name,approval: buildReplayedApproval(m),diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.tsindex ffa66cbc1..b389f04c1 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts@@ -535,6 +535,33 @@ describe("dispatchDynamicToolEvent", () => {expect(buildDynamicTools(ctx)).toHaveLength(0);});+ it("passes the final qualified name to a step-scoped tool", async () => {+ const ctx = createCtx();+ const resolver = {+ ...createResolver("search", ["step.started"], () => ({+ query: defineTool({+ description: "search records",+ inputSchema: { type: "object" },+ execute: async (_input, toolCtx) => ({ toolName: toolCtx.toolName }),+ }),+ })),+ extensionNamespace: "warehouse",+ };++ await dispatchDynamicToolEvent({+ ctx,+ resolvers: [resolver],+ messages: [],+ event: makeEvent("step.started"),+ });++ const tool = buildDynamicTools(ctx)[0]!;+ expect(tool.name).toBe("warehouse__query");+ await expect(tool.execute!({}, executeOptions)).resolves.toEqual({+ toolName: "warehouse__query",+ });+ });+it("replaces tools from the same resolver slug (last write wins)", async () => {const ctx = createCtx();let callCount = 0;@@ -654,7 +681,10 @@ describe("dispatchDynamicToolEvent", () => {// Register a step function so replayDynamicSessionTools can// reconstruct the tool on the second step.const stepId = "eve:dynamic-tool//__eve_dispatch_rehydrate_test";- const stepFn = vi.fn((_vars: unknown, input: unknown) => ({ input }));+ const stepFn = vi.fn((_vars: unknown, input: unknown, toolCtx: unknown) => ({+ input,+ toolName: (toolCtx as { toolName: string }).toolName,+ }));const registrySym = Symbol.for("@workflow/core//registeredSteps");const registry = getOrCreateStepRegistry(registrySym);registry.set(stepId, stepFn);@@ -693,6 +723,10 @@ describe("dispatchDynamicToolEvent", () => {const tools = buildDynamicTools(ctx);expect(tools).toHaveLength(1);expect(tools[0]!.name).toBe("query");+ expect(tools[0]!.execute!({}, executeOptions)).toEqual({+ input: {},+ toolName: "query",+ });} finally {registry.delete(stepId);}diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.tsindex f597028f6..c2166d787 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts@@ -33,7 +33,10 @@ function toHarnessToolDefinition(name: string, entry: DynamicToolEntry): Harnessreturn {description: entry.description,execute: (input: unknown, options) =>- entry.execute(input as Record<string, unknown>, buildBaseToolContext(options)),+ entry.execute(+ input as Record<string, unknown>,+ buildBaseToolContext({ options, toolName: name }),+ ),inputSchema: convertInputSchema(entry.inputSchema),name,approval: entry.approval,@@ -124,7 +127,7 @@ export function replayDynamicSessionTools(tools.push({description: m.description,execute: (input: unknown, options) =>- stepFn(m.closureVars, input, buildBaseToolContext(options)),+ stepFn(m.closureVars, input, buildBaseToolContext({ options, toolName: m.name })),inputSchema: jsonSchema(m.inputSchema),name: m.name,outputSchema: m.outputSchema === undefined ? undefined : jsonSchema(m.outputSchema),diff --git a/packages/eve/src/execution/tool-auth.integration.test.ts b/packages/eve/src/execution/tool-auth.integration.test.tsindex 53b931859..f83f7d17b 100644--- a/packages/eve/src/execution/tool-auth.integration.test.ts+++ b/packages/eve/src/execution/tool-auth.integration.test.ts@@ -98,11 +98,11 @@ describe("tool-hosted authorization", () => {expect(calls).toBe(1);});- it("exposes the tool call id on the authored context", async () => {+ it("exposes the tool call metadata on the authored context", async () => {const tool = authoredTool({- name: "observe_call_id",+ name: "observe_call_metadata",execute(_input, ctx) {- return { callId: ctx.callId };+ return { callId: ctx.callId, toolName: ctx.toolName };},});const runtime = createTestRuntime({ tools: [tool] });@@ -110,7 +110,7 @@ describe("tool-hosted authorization", () => {const result = await runtime.runAsSession(undefined, async () => runtime.executeTool(tool, {}));// The test harness dispatches every executeTool call as "call_test".- expect(result).toEqual({ callId: "call_test" });+ expect(result).toEqual({ callId: "call_test", toolName: "observe_call_metadata" });});it("resolves and caches an inline provider on a plain tool", async () => {diff --git a/packages/eve/src/execution/tool-auth.ts b/packages/eve/src/execution/tool-auth.tsindex e0d6e2864..d040ff465 100644--- a/packages/eve/src/execution/tool-auth.ts+++ b/packages/eve/src/execution/tool-auth.ts@@ -87,7 +87,7 @@ function buildToolContext(input: {readonly inlineAuthState: InlineAuthState;}): ToolContext {const { scope, justAuthorizedScopes, inlineAuthState } = input;- const base = buildBaseToolContext(input.options);+ const base = buildBaseToolContext({ options: input.options, toolName: scope });return {...base,async getToken(provider?: ToolAuthProvider, options?: ToolAuthOptions): Promise<TokenResult> {diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.tsindex 9349a479d..5be6d58b7 100644--- a/packages/eve/src/public/definitions/tool.ts+++ b/packages/eve/src/public/definitions/tool.ts@@ -87,6 +87,12 @@ export type ToolContext = SessionContext & {* stream events and its {@link ApprovalContext}.*/readonly callId: string;+ /**+ * Final runtime name of the current tool, including any namespace+ * qualification. This is the same `toolName` carried by stream events and+ * the tool's {@link ApprovalContext}.+ */+ readonly toolName: string;/*** Resolves the bearer token for an inline provider. This accepts the same* auth shapes as a connection's `auth` field, including `connect("...")`diff --git a/packages/eve/src/shared/dynamic-tool-definition.ts b/packages/eve/src/shared/dynamic-tool-definition.tsindex 207617256..32fb55bb6 100644--- a/packages/eve/src/shared/dynamic-tool-definition.ts+++ b/packages/eve/src/shared/dynamic-tool-definition.ts@@ -13,6 +13,8 @@ import type { HandleMessageStreamEvent } from "#protocol/message.js";type ToolContext = SessionContext & {/** Aborts when the active turn is cancelled. */readonly abortSignal: AbortSignal;+ /** Final runtime name of the current tool. */+ readonly toolName: string;};/**