The Open Framework for Building Agents
[1/3] fix(eve): replay background dynamic tools (#2796)
Ben Pankowb03290a104c3
diff --git a/.changeset/curvy-tools-delegate.md b/.changeset/curvy-tools-delegate.mdnew file mode 100644index 000000000..c788ceb2c--- /dev/null+++ b/.changeset/curvy-tools-delegate.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Preserve background execution for durable dynamic tools so replayed callbacks receive their task runtime.diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v21.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v21.tsnew file mode 100644index 000000000..b70853803--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v21.ts@@ -0,0 +1,19 @@+import { z } from "zod";++import { defineDynamic, defineTool } from "#public/tools/index.js";++export default defineDynamic({+ events: {+ "session.started": (_event, ctx) =>+ defineTool({+ description: "Return the active tool identity.",+ inputSchema: z.object({ note: z.string() }),+ execute: ({ note }, toolCtx) => ({+ callId: toolCtx.callId,+ note,+ sessionId: ctx.session.id,+ toolName: toolCtx.toolName,+ }),+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v23.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v23.tsnew file mode 100644index 000000000..1e9382581--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v23.ts@@ -0,0 +1,20 @@+import { z } from "zod";++import { defineDynamic, defineTool } from "#public/tools/index.js";++export default defineDynamic({+ events: {+ "session.started": () =>+ defineTool({+ description: "Delegate a background report.",+ execution: "background",+ inputSchema: z.object({ reportId: z.string() }),+ execute({ reportId }, _ctx, task) {+ return task.delegated({+ executor: { data: { reportId }, kind: "report" },+ receipt: { reportId },+ });+ },+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v24.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v24.tsnew file mode 100644index 000000000..1e9382581--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v24.ts@@ -0,0 +1,20 @@+import { z } from "zod";++import { defineDynamic, defineTool } from "#public/tools/index.js";++export default defineDynamic({+ events: {+ "session.started": () =>+ defineTool({+ description: "Delegate a background report.",+ execution: "background",+ inputSchema: z.object({ reportId: z.string() }),+ execute({ reportId }, _ctx, task) {+ return task.delegated({+ executor: { data: { reportId }, kind: "report" },+ receipt: { reportId },+ });+ },+ }),+ },+});diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v24.json b/packages/eve/extension-contracts/reports/dynamicTool/v24.jsonnew file mode 100644index 000000000..a24c77722--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v24.json@@ -0,0 +1,13 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 24,+ "sha256": "241319046be4153d20afd0ef8cecb6fcd09aa1f242ba16fafa5570065c4a917a",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "defineDynamic"+ ]+}diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v25.json b/packages/eve/extension-contracts/reports/dynamicTool/v25.jsonnew file mode 100644index 000000000..2476f5437--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v25.json@@ -0,0 +1,13 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 25,+ "sha256": "685842bc19f8158d708c406478311a74e82f8dc2fe2a660d2c007f539b3a5fa0",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "defineDynamic"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 11a92dc78..329f20b79 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -29,8 +29,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {dropped: { 15: "TaskExec replaces stageEffect with send" },},dynamicTool: {- current: 23,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23],+ current: 25,+ supported: [+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25,+ ],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",},diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.tsindex e77dc6e03..4b40626bf 100644--- a/packages/eve/src/context/build-dynamic-tools.ts+++ b/packages/eve/src/context/build-dynamic-tools.ts@@ -99,17 +99,41 @@ export function replayDynamicTools(return {description: entry.description,- execute: createToolExecuteWithAuth({- scope: entry.name,- execute: (input, context) => {- if (execute === undefined) {- throw missingCallbackError(entry, "execute");- }- return callDurableDynamicCallback(execute, executeReference.closure, input, context);- },- }),+ execute:+ entry.execution === "background"+ ? createToolExecuteWithAuth({+ execution: "background",+ scope: entry.name,+ execute: (input, context, task) => {+ if (execute === undefined) {+ throw missingCallbackError(entry, "execute");+ }+ return callDurableDynamicCallback(+ execute,+ executeReference.closure,+ input,+ context,+ task,+ );+ },+ })+ : createToolExecuteWithAuth({+ scope: entry.name,+ execute: (input, context) => {+ if (execute === undefined) {+ throw missingCallbackError(entry, "execute");+ }+ return callDurableDynamicCallback(+ execute,+ executeReference.closure,+ input,+ context,+ );+ },+ }),inputSchema: toInputSchema(entry.inputSchema),name: entry.name,+ execution: entry.execution,approval: buildReplayedApproval(entry),outputSchema: toOutputSchema(entry.outputSchema),...(toModelOutputReference === undefineddiff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.tsindex 392e0cd18..51904e8ff 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts@@ -1,6 +1,7 @@import { asSchema } from "ai";import { describe, expect, it, vi } from "vitest";+import { z } from "#compiled/zod/index.js";import type { DynamicToolEntry } from "#tools/dynamic.js";import {isCurrentDynamicToolMetadata,@@ -9,7 +10,7 @@ import {type OldStepFunctionDynamicToolMetadata,} from "#context/dynamic-tool-metadata.js";import { resolveApprovalPolicy, type ApprovalContext } from "#approval/definition.js";-import { defineTool, type ToolContext } from "#tools/definition.js";+import { defineTool, type TaskExec, type ToolContext } from "#tools/definition.js";import type { JsonObject } from "#shared/json.js";import { serializeOutputSchema, type ToolSchema } from "#tools/schema.js";@@ -1056,6 +1057,60 @@ describe("dispatchDynamicToolEvent", () => {expect(buildDynamicTools(ctx)).toHaveLength(2);});+ it("persists background execution and forwards TaskExec when replaying", async () => {+ const ctx = createCtx();+ const stepFn = vi.fn((_closure: unknown, _input: unknown, _toolCtx: unknown, task: TaskExec) =>+ task.delegated({+ executor: { data: {}, kind: "test" },+ receipt: {},+ }),+ );+ const resolver = createResolver("background", ["session.started"], () => {+ const entry = defineTool({+ description: "delegate background work",+ execution: "background",+ inputSchema: z.strictObject({}),+ execute: (_input, _toolCtx, task) =>+ task.delegated({ executor: { data: {}, kind: "test" }, receipt: {} }),+ });+ stampDurableDynamicToolCallbacks(entry, {+ execute: { callback: stepFn as never, closure: {} },+ });+ return { background_task: entry };+ });++ await dispatchDynamicToolEvent({+ ctx,+ resolvers: [resolver],+ messages: [],+ event: makeEvent("session.started"),+ });+ const restored = await deserializeContext(serializeContext(ctx));+ const [metadata] = restored.get(SessionDynamicToolMetadataKey) ?? [];+ expect(metadata?.execution).toBe("background");++ const [tool] = buildDynamicTools(restored);+ expect(tool?.execution).toBe("background");+ const binding = { taskId: "task-1", token: "token-1" };+ const task: TaskExec = {+ batch: [],+ binding,+ delegated: ({ executor, receipt }) => ({+ executor,+ kind: "eve:task-delegated",+ receipt: { ...receipt, status: "working", taskId: binding.taskId },+ }),+ send: vi.fn(),+ session: {} as TaskExec["session"],+ task: {} as TaskExec["task"],+ };+ await expect(tool!.execute!({}, executeOptions, task)).resolves.toMatchObject({+ kind: "eve:task-delegated",+ receipt: { status: "working", taskId: "task-1" },+ });+ expect(stepFn).toHaveBeenCalledWith({}, {}, expect.anything(), task);+ });+it("replays session tools from durable metadata on a fresh step", async () => {const ctx = createCtx();diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.tsindex 5800baf8e..0a80a9a0b 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts@@ -230,6 +230,7 @@ function createMetadata(input: {return {callbacks: validateDurableDynamicToolCallbacks(input.name, input.entry),description: input.entry.description,+ execution: input.entry.execution === "background" ? "background" : undefined,entryKey: input.entryKey,inputSchema: serializeInputSchema(input.entry.inputSchema),name: input.name,diff --git a/packages/eve/src/context/dynamic-tool-metadata.ts b/packages/eve/src/context/dynamic-tool-metadata.tsindex d7ed25a1f..a619d77f3 100644--- a/packages/eve/src/context/dynamic-tool-metadata.ts+++ b/packages/eve/src/context/dynamic-tool-metadata.ts@@ -4,6 +4,7 @@ import type { DurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";interface DynamicToolMetadataBase {readonly name: string;readonly description: string;+ readonly execution?: "background";readonly inputSchema: JsonObject;readonly outputSchema?: JsonObject;readonly resolverSlug: string;diff --git a/packages/eve/src/tools/dynamic.ts b/packages/eve/src/tools/dynamic.tsindex 4b10bcbce..6762757a3 100644--- a/packages/eve/src/tools/dynamic.ts+++ b/packages/eve/src/tools/dynamic.ts@@ -5,6 +5,7 @@ import type {PublicToolOutputSchema,ToolContext,} from "#tools/definition.js";+import type { TaskDelegated, TaskExec } from "#tools/task.js";import type { ToolModelOutput } from "#tools/model-output.js";/**@@ -24,7 +25,12 @@ export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = anreadonly description: string;readonly inputSchema: PublicToolInputSchema<TInput>;readonly outputSchema?: PublicToolOutputSchema<TOutput>;- execute(input: TInput, ctx: ToolContext): TOutput | Promise<TOutput>;+ readonly execution?: "background";+ execute(+ input: TInput,+ ctx: ToolContext,+ task?: TaskExec,+ ): TOutput | TaskDelegated | Promise<TOutput | TaskDelegated>;readonly toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;/*** Optional per-call approval gate, mirroring the authored-tool