Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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 === undefined
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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 = an
readonly 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