The Open Framework for Building Agents
fix(eve): export durable callback helper (#2981)
vercel-gh-bot-4[bot]a24b68c5774b
diff --git a/.changeset/public-durable-dynamic-callbacks.md b/.changeset/public-durable-dynamic-callbacks.mdnew file mode 100644index 000000000..2abaa1626--- /dev/null+++ b/.changeset/public-durable-dynamic-callbacks.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Export `defineDurableCallback` so provider packages can create replayable dynamic tools outside eve's authored-source transform.diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.mdindex 757ce8f3c..38e3646cd 100644--- a/docs/guides/dynamic-capabilities.md+++ b/docs/guides/dynamic-capabilities.md@@ -253,7 +253,42 @@ Write callback properties as inline function expressions, arrows, method shorthaClosure values must be JSON-serializable. Plain objects, arrays, strings, finite numbers, booleans, and `null` are supported; `undefined` object properties are omitted. Functions, class instances, `Date`, `Map`, symbols, non-finite numbers, and cyclic values fail resolution with the tool name and callback phase instead of being serialized lossily.-Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve-provided factories, including [memory provider tools](../memory), may also supply pre-registered callbacks. eve rejects a dynamic tool if any present callback lacks durable metadata.+Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve rejects a dynamic tool if a callback lacks durable metadata.++### Create dynamic tools in a package++Prefer an [extension](../extensions) for reusable eve integrations. Extensions contribute a namespaced set of capabilities that consumers can override. Author the final `defineTool()` calls in the extension source. Then build the package with `eve extension build` so eve transforms its callbacks.++Use `defineDurableCallback` when a provider package must return dynamic `defineTool()` values directly. eve cannot transform callback code inside an installed dependency. Put every per-tool value in the helper's `closure`. The callback receives that snapshot as its first argument. The closure follows the same JSON-serializability rules as transformed captures.++```ts title="provider-package/search.ts"+import { defineDurableCallback, defineTool } from "eve/tools";+import { z } from "zod";++interface SearchInput {+ query: string;+}++export function createSearchTool(baseUrl: string) {+ return defineTool({+ description: "Search the provider catalog.",+ inputSchema: z.object({ query: z.string() }),+ execute: defineDurableCallback({+ closure: { baseUrl },+ callback: async ({ baseUrl }, { query }: SearchInput) => {+ const response = await fetch(`${baseUrl}/search?q=${encodeURIComponent(query)}`);+ return response.json();+ },+ }),+ });+}+```++Wrap every callback property with the helper. This includes labels, approval policies, `approvalKey`, `execute`, and `toModelOutput`.++`closure` is the callback's only durable snapshot. Store the identifiers and configuration needed to reproduce the call there. Reconstruct clients or look up live runtime state when the callback runs. The callback may call stable imported functions, but it must not capture runtime objects outside `closure`. Those values disappear on a cold start.++eve-provided factories, including [memory provider tools](../memory), use the same durable callback mechanism.### Identity and redeploysdiff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.mdindex 7a56c9d8d..67345c775 100644--- a/docs/reference/typescript-api.md+++ b/docs/reference/typescript-api.md@@ -34,6 +34,7 @@ export default defineTool({| ----------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------ || `defineAgent` | `eve` | `agent/agent.ts` | [agent.ts](../agent-config) || `defineTool` | `eve/tools` | `agent/tools/<name>.ts` | [Tools](../tools) |+| `defineDurableCallback` | `eve/tools` | provider-package dynamic tool factories | [Dynamic capabilities](../guides/dynamic-capabilities) || `defineWorkflowTool` | `eve/tools` | `agent/tools/<name>.ts` | [Workflow tools](../tools/workflows) || `defineDynamic` | `eve`, `eve/tools`, `eve/skills`, `eve/instructions`, `eve/connections` | dynamic model or subagent `agent.ts`; `agent/{tools,skills,instructions,connections}/` | [Dynamic capabilities](../guides/dynamic-capabilities) || `defineMcpClientConnection` | `eve/connections` | `agent/connections/<name>.ts` | [MCP connections](../connections/mcp) |@@ -54,7 +55,7 @@ export default defineTool({| `mockModel` | `eve/evals` | Deterministic fixture agent models | [Evals](../evals/overview) || `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) |-Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.+Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.@@ -108,40 +109,40 @@ import template from "../../prompts/template.txt?raw";## Imports at a glance-| Import | Holds |-| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |-| `eve` | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types |-| `eve/tools` | `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, generic tool types |-| `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions |-| `eve/tools/approval` | Approval types and `always`, `once`, `never` |-| `eve/tools/web_search` | Provider-managed `webSearch` configuration |-| `eve/tools/workflow` | Experimental `Workflow` tool definition |-| `eve/tools/sleep` | Opt-in durable `sleep` tool |-| `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic` |-| `eve/channels` | `defineChannel`, `disableRoute`, route verbs |-| `eve/channels/eve` | `eveChannel` |-| `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` |-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories |-| `eve/hooks` | `defineHook` |-| `eve/schedules` | `defineSchedule` |-| `eve/skills` | `defineSkill`, `defineDynamic` |-| `eve/instructions` | `defineInstructions`, `defineDynamic` |-| `eve/memory` | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types |-| `eve/memory/scope` | `byPrincipal` and memory scope helpers |-| `eve/memory/file` | `fileMemory`, `inMemory`, and the conditional document backend contract |-| `eve/memory/file/vercel` | `vercelBlob` and Vercel Blob backend options |-| `eve/context` | `defineState`, session and state types |-| `eve/sandbox` | `defineSandbox`, backends |-| `eve/instrumentation` | `defineInstrumentation`, `isChannel` |-| `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |-| `eve/models/openai` | `chatgpt`, deprecated `experimental_chatgpt` |-| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |-| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |-| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |-| `eve/evals/loaders` | `loadJson`, `loadYaml` |-| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |-| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |-| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, response errors |+| Import | Holds |+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |+| `eve` | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types |+| `eve/tools` | `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDynamic`, `disableTool`, tool types |+| `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions |+| `eve/tools/approval` | Approval types and `always`, `once`, `never` |+| `eve/tools/web_search` | Provider-managed `webSearch` configuration |+| `eve/tools/workflow` | Experimental `Workflow` tool definition |+| `eve/tools/sleep` | Opt-in durable `sleep` tool |+| `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic` |+| `eve/channels` | `defineChannel`, `disableRoute`, route verbs |+| `eve/channels/eve` | `eveChannel` |+| `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` |+| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories |+| `eve/hooks` | `defineHook` |+| `eve/schedules` | `defineSchedule` |+| `eve/skills` | `defineSkill`, `defineDynamic` |+| `eve/instructions` | `defineInstructions`, `defineDynamic` |+| `eve/memory` | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types |+| `eve/memory/scope` | `byPrincipal` and memory scope helpers |+| `eve/memory/file` | `fileMemory`, `inMemory`, and the conditional document backend contract |+| `eve/memory/file/vercel` | `vercelBlob` and Vercel Blob backend options |+| `eve/context` | `defineState`, session and state types |+| `eve/sandbox` | `defineSandbox`, backends |+| `eve/instrumentation` | `defineInstrumentation`, `isChannel` |+| `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |+| `eve/models/openai` | `chatgpt`, deprecated `experimental_chatgpt` |+| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |+| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |+| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |+| `eve/evals/loaders` | `loadJson`, `loadYaml` |+| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |+| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |+| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, response errors |Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v31.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v31.tsnew file mode 100644index 000000000..850588b14--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v31.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: "Report deployment progress.",+ inputSchema: z.object({ service: z.string() }),+ outputSchema: z.object({ url: z.string() }),+ label: {+ start: ({ service }) => `Deploy ${service}`,+ delta: ({ service }) => `Deploying ${service}`,+ complete: ({ service }, { url }) => `Deployed ${service} to ${url}`,+ },+ execute: async ({ service }) => ({ url: `https://${service}.example.com` }),+ }),+ },+});diff --git a/packages/eve/extension-contracts/entrypoints/dynamicTool.ts b/packages/eve/extension-contracts/entrypoints/dynamicTool.tsindex 50ddb82b1..c410a9bbb 100644--- a/packages/eve/extension-contracts/entrypoints/dynamicTool.ts+++ b/packages/eve/extension-contracts/entrypoints/dynamicTool.ts@@ -3,5 +3,6 @@ export {type DynamicToolEvents,type DynamicToolResult,type DynamicToolSet,+ defineDurableCallback,defineDynamic,} from "../../src/public/tools/index.ts";diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v32.json b/packages/eve/extension-contracts/reports/dynamicTool/v32.jsonnew file mode 100644index 000000000..4fe68c594--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v32.json@@ -0,0 +1,14 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 32,+ "sha256": "d8c2e04a1fc4dd2f1453aab52ee5740b7bef161a05ba11ddc653d6805378899b",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "defineDurableCallback",+ "defineDynamic"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 4f6da39e7..d80b2c093 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -42,9 +42,9 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 31,+ current: 32,supported: [- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 28, 29, 30, 31,+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 28, 29, 30, 31, 32,],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.tsindex d481f2cac..adabda248 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts@@ -10,7 +10,12 @@ import {type OldSourceOffsetDynamicToolMetadata,type OldStepFunctionDynamicToolMetadata,} from "#context/dynamic-tool-metadata.js";-import { resolveApprovalPolicy, type ApprovalContext } from "#approval/definition.js";+import {+ resolveApprovalPolicy,+ type ApprovalContext,+ type ApprovalResponseContext,+} from "#approval/definition.js";+import { defineDurableCallback } from "#public/tools/index.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";@@ -1574,6 +1579,117 @@ describe("programmatic dynamic tools (no bundler transform)", () => {expect(approvalFn).toHaveBeenCalledExactlyOnceWith(approvalCtx);});+ it("rebinds every defineDurableCallback phase after a cold start", async () => {+ const ctx = createCtx();+ let provider = "original-provider";+ const handler = vi.fn(() => ({+ provider_tool: defineTool({+ approval: {+ request: defineDurableCallback({+ callback: ({ status }: { status: "user-approval" }) => status,+ closure: { status: "user-approval" },+ }),+ response: defineDurableCallback({+ callback: ({ provider: snapshotted }: { provider: string }) => ({+ reason: snapshotted,+ status: "rejected" as const,+ }),+ closure: { provider },+ }),+ },+ approvalKey: defineDurableCallback({+ callback: (+ { provider: snapshotted }: { provider: string },+ input: Readonly<Record<string, unknown>>,+ ) => `${snapshotted}:${String(input.operation)}`,+ closure: { provider },+ }),+ description: "dependency-created provider tool",+ execute: defineDurableCallback({+ callback: (+ { provider: snapshotted }: { provider: string },+ input: Record<string, unknown>,+ ) => ({ input, provider: snapshotted }),+ closure: { provider },+ }),+ inputSchema: { type: "object" },+ label: {+ complete: defineDurableCallback({+ callback: ({ provider: snapshotted }: { provider: string }) =>+ `Completed ${snapshotted}`,+ closure: { provider },+ }),+ delta: defineDurableCallback({+ callback: ({ provider: snapshotted }: { provider: string }) => `Running ${snapshotted}`,+ closure: { provider },+ }),+ start: defineDurableCallback({+ callback: ({ provider: snapshotted }: { provider: string }) =>+ `Starting ${snapshotted}`,+ closure: { provider },+ }),+ },+ toModelOutput: defineDurableCallback({+ callback: ({ provider: snapshotted }: { provider: string }, output: unknown) => ({+ type: "json" as const,+ value: { output, provider: snapshotted },+ }),+ closure: { provider },+ }),+ }),+ }));+ const resolver = createResolver("session_provider", ["session.started"], handler);++ await dispatchDynamicToolEvent({+ ctx,+ event: makeEvent("session.started"),+ messages: [],+ resolvers: [resolver],+ });+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "deployment:dpl_current");+ provider = "provider-after-rebind";+ simulateColdStart(ctx);++ await refreshDynamicSessionToolsForRuntimeRevision({+ ctx,+ event: createSessionStartedEvent(),+ messages: [],+ resolvers: [resolver],+ runtimeRevision: "deployment:dpl_current",+ });++ expect(handler).toHaveBeenCalledTimes(2);+ const [tool] = buildDynamicTools(ctx);+ const approval = tool!.approval;+ expect(approval).not.toBeTypeOf("function");+ if (approval === undefined || typeof approval === "function") {+ throw new Error("Expected approval request and response policies.");+ }+ expect(tool!.label?.start?.({ operation: "ping" })).toBe("Starting original-provider");+ expect(tool!.label?.delta?.({ operation: "ping" }, { step: 1 })).toBe(+ "Running original-provider",+ );+ expect(tool!.label?.complete?.({ operation: "ping" }, { ok: true })).toBe(+ "Completed original-provider",+ );+ expect(tool!.approvalKey?.({ operation: "ping" })).toBe("original-provider:ping");+ await expect(+ approval.request(createApprovalContext({ toolName: "provider_tool" })),+ ).resolves.toBe("user-approval");+ await expect(approval.response!({} as ApprovalResponseContext)).resolves.toEqual({+ reason: "original-provider",+ status: "rejected",+ });+ await expect(tool!.execute!({ operation: "ping" }, executeOptions)).resolves.toEqual({+ input: { operation: "ping" },+ provider: "original-provider",+ });+ expect(tool!.toModelOutput!({ result: "found" })).toEqual({+ type: "json",+ value: { output: { result: "found" }, provider: "original-provider" },+ });+ });+it("replays label callbacks", () => {const ctx = createCtx();const owner = {diff --git a/packages/eve/src/public/tools/index.ts b/packages/eve/src/public/tools/index.tsindex 5527d7025..e2ba3d179 100644--- a/packages/eve/src/public/tools/index.ts+++ b/packages/eve/src/public/tools/index.ts@@ -19,6 +19,7 @@ export {type ToolModelOutputPart,} from "#tools/definition.js";export { defineDynamic } from "#dynamic/definition.js";+export { defineDurableCallback } from "#tools/durable-callbacks.js";export { toolOutput, toolOutputPart } from "#tools/model-output.js";export type { DynamicEvents, DynamicResolveContext, DynamicSentinel } from "#dynamic/definition.js";export type {diff --git a/packages/eve/src/tools/durable-callbacks.ts b/packages/eve/src/tools/durable-callbacks.tsindex 371c3d47f..808384b75 100644--- a/packages/eve/src/tools/durable-callbacks.ts+++ b/packages/eve/src/tools/durable-callbacks.ts@@ -1,6 +1,6 @@import type { Approval } from "#approval/definition.js";import { resolveApprovalPolicy } from "#approval/definition.js";-import type { JsonObject } from "#shared/json.js";+import type { JsonObject, JsonPrimitive } from "#shared/json.js";export type DurableDynamicCallbackPhase =| "labelComplete"@@ -180,6 +180,50 @@ function durableCallbackPhases(return entries.flatMap(([phase, reference]) => (reference === undefined ? [] : [phase]));}+type DurableCallbackJsonValue<T> = T extends (...args: never[]) => unknown+ ? never+ : T extends JsonPrimitive+ ? T+ : T extends readonly (infer TItem)[]+ ? readonly DurableCallbackJsonValue<TItem>[]+ : T extends object+ ? DurableCallbackJsonObject<T>+ : never;++type DurableCallbackJsonObject<T extends object> =+ Extract<keyof T, symbol> extends never+ ? {+ readonly [TKey in keyof T]:+ | DurableCallbackJsonValue<Exclude<T[TKey], undefined>>+ | Extract<T[TKey], undefined>;+ }+ : never;++/**+ * Defines a replayable callback for tools created outside eve's authored-source+ * transform, such as tools returned by a provider package.+ *+ * Put every per-tool value in `closure`. eve snapshots that JSON-serializable+ * object when the dynamic tool resolves and passes it as the first argument to+ * the current callback implementation during both live execution and replay.+ */+export function defineDurableCallback<+ TClosure extends object,+ TArgs extends unknown[],+ TResult,+>(input: {+ readonly callback: (closure: TClosure, ...args: TArgs) => TResult;+ readonly closure: TClosure & DurableCallbackJsonObject<TClosure>;+}): (...args: TArgs) => TResult {+ const callback = (...args: TArgs): TResult => input.callback(input.closure, ...args);+ const durableCallback = (closure: JsonObject, ...args: never[]): TResult =>+ Reflect.apply(input.callback, undefined, [closure, ...args]) as TResult;+ return stampDurableDynamicCallback(callback, {+ callback: durableCallback,+ closure: input.closure as JsonObject,+ });+}+/** Marks a live callback with the descriptor needed to register it at resolve time. */export function stampDurableDynamicCallback<TCallback extends (...args: never[]) => unknown>(callback: TCallback,