Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.ts
index 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.ts
index 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.ts
index 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[]): HarnessTo
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,
approval: buildReplayedApproval(m),
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index 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.ts
index 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): Harness
return {
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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
};
/**