The Open Framework for Building Agents
fix(eve): dynamic tools - replay schema factories with captured state (#3095)
Andrew Barba7973fa2d7d10
diff --git a/.changeset/preserve-dynamic-schema-validation.md b/.changeset/preserve-dynamic-schema-validation.mdnew file mode 100644index 000000000..4ff6f4ad8--- /dev/null+++ b/.changeset/preserve-dynamic-schema-validation.md@@ -0,0 +1,5 @@+---+"eve": minor+---++Preserve dynamic tool validation through durable schema factories that replay the original captured values, including Zod refinements and transformations. Rebuild extensions with the current eve compiler; provider packages must wrap live dynamic schemas with `defineDurableSchema`, and resolver-local schema objects must be constructed inline or moved to module scope.diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.mdindex 4cfbe1a44..b6125ad94 100644--- a/docs/guides/dynamic-capabilities.md+++ b/docs/guides/dynamic-capabilities.md@@ -265,6 +265,12 @@ 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.+Dynamic tools preserve authored input and output validation, including Zod refinements and transformations. JSON Schema describes the tool to the model; the authored validator checks its input and output. eve transforms inline `inputSchema` and `outputSchema` expressions into schema factories and snapshots the JSON-serializable values they capture, just as it does for callbacks.++Write schemas inline in `defineTool()`, or reference a stable module-level schema. A schema stored in a resolver-local variable is a non-serializable capture; inline its construction instead. Schema factories must be synchronous and deterministic for their captured values. Keep external reads in the resolver and capture the resulting JSON data. Imported functions and module-level values remain live code, so they must not hide per-session state.++Schema factories use the same session, scope, resolver entry, and recovery rules as the tool's callbacks. A recovered factory receives its original captures, even if re-running the resolver produces different values. If a required factory is missing, validation fails explicitly; eve does not substitute its JSON Schema description.+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@@ -298,6 +304,22 @@ export function createSearchTool(baseUrl: string) {Wrap every callback property with the helper. This includes labels, approval policies, `approvalKey`, `execute`, and `toModelOutput`.+For live schemas created in a provider package, use `defineDurableSchema` from `eve/tools`. Put the schema's per-tool values in `closure` and construct the schema in `schema`. Plain JSON Schema objects need no helper.++```ts+import { defineDurableSchema } from "eve/tools";+import { z } from "zod";++export function amountSchema(limit: number) {+ return defineDurableSchema({+ closure: { limit },+ schema: ({ limit }) => z.object({ amount: z.number().refine((amount) => amount <= limit) }),+ });+}+```++Pass the result as `inputSchema` or `outputSchema` in `defineTool()`. Rebuild existing extensions with the current `eve extension build` to generate schema factories. A live dynamic schema without a durable factory is rejected at resolution with instructions to inline its construction or use `defineDurableSchema`.+`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.diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.mdindex deb344b1f..7695f4827 100644--- a/docs/reference/typescript-api.md+++ b/docs/reference/typescript-api.md@@ -35,6 +35,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) |+| `defineDurableSchema` | `eve/tools` | provider-package dynamic input and output schemas | [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) |@@ -55,7 +56,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`, `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`, `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`, `defineDurableSchema`, `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`, `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`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.@@ -109,42 +110,42 @@ import template from "../../prompts/template.txt?raw";## Imports at a glance-| 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` | Runtime-generated `workflow` tool factory |-| `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` | `openai`, `chatgpt`, deprecated `experimental_chatgpt` |-| `eve/models/anthropic` | `anthropic` |-| [`eve/experimental/evaluate`](../guides/evaluate) | Experimental `autoModel` and standalone `evaluate` |-| `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`, `defineDurableSchema`, `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` | Runtime-generated `workflow` tool factory |+| `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` | `openai`, `chatgpt`, deprecated `experimental_chatgpt` |+| `eve/models/anthropic` | `anthropic` |+| [`eve/experimental/evaluate`](../guides/evaluate) | Experimental `autoModel` and standalone `evaluate` |+| `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/e2e/fixtures/agent-tools/agent/agent.ts b/e2e/fixtures/agent-tools/agent/agent.tsindex 6db5aea44..1f571c46c 100644--- a/e2e/fixtures/agent-tools/agent/agent.ts+++ b/e2e/fixtures/agent-tools/agent/agent.ts@@ -10,6 +10,26 @@ const base = e2eAgentConfig({}return "Callback identity checked.";}+ if (request.lastUserMessage?.includes("`schema_validate`")) {+ const roles = request.messages.map((message) => message.role);+ if (roles.lastIndexOf("tool") <= roles.lastIndexOf("user")) {+ return {+ toolCalls: [+ {+ name: "schema_validate",+ input: {+ value: request.lastUserMessage?.includes("blank form") ? " " : " normalized ",+ },+ },+ ],+ };+ }+ const result = request.toolResults.at(-1);+ if (result?.name === "schema_validate" && result.isError) {+ return "Blank value rejected.";+ }+ return "Schema validation checked.";+ }return `Mock reply: ${request.lastUserMessage ?? ""}`;},});diff --git a/e2e/fixtures/agent-tools/agent/tools/dynamic-schema-validation.ts b/e2e/fixtures/agent-tools/agent/tools/dynamic-schema-validation.tsnew file mode 100644index 000000000..01146a837--- /dev/null+++ b/e2e/fixtures/agent-tools/agent/tools/dynamic-schema-validation.ts@@ -0,0 +1,15 @@+import { defineDynamic, defineTool } from "eve/tools";+import { z } from "zod";++export default defineDynamic({+ events: {+ "session.started": () => ({+ schema_validate: defineTool({+ description:+ "Returns the validated value. Call only when explicitly asked for schema_validate.",+ inputSchema: z.object({ value: z.string().trim().min(1) }),+ execute: (input) => ({ value: input.value }),+ }),+ }),+ },+});diff --git a/e2e/fixtures/agent-tools/evals/dynamic-tools/schema-validation.eval.ts b/e2e/fixtures/agent-tools/evals/dynamic-tools/schema-validation.eval.tsnew file mode 100644index 000000000..22ede0103--- /dev/null+++ b/e2e/fixtures/agent-tools/evals/dynamic-tools/schema-validation.eval.ts@@ -0,0 +1,21 @@+import { defineEval } from "eve/evals";++export default defineEval({+ description: "Dynamic tool replay preserves input transformations and validation across turns.",+ async test(t) {+ for (let turn = 0; turn < 2; turn++) {+ const result = await t.send(+ 'Call `schema_validate` with value " normalized ", including the surrounding spaces, and report its returned value.',+ );+ result.expectOk();+ result.calledTool("schema_validate", { output: { value: "normalized" } });+ }+ const invalid = await t.send(+ 'Alice is checking a blank form submission. Call `schema_validate` with value " " (one space). If the tool reports a validation error, include "Blank value rejected" in your explanation. Do not retry.',+ );+ invalid.expectOk();+ invalid.event("step.completed", { data: { finishReason: "tool-calls" } });+ invalid.notCalledTool("schema_validate");+ invalid.messageIncludes("Blank value rejected");+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v44.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v44.tsnew file mode 100644index 000000000..bdc51a74d--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v44.ts@@ -0,0 +1,16 @@+import { defineDurableCallback, defineDynamic, defineTool } from "#public/tools/index.js";++export default defineDynamic({+ events: {+ "session.started": (_event, context) => ({+ session_id: defineTool({+ description: "Return the captured session id.",+ inputSchema: { type: "object", properties: {} },+ execute: defineDurableCallback({+ closure: { sessionId: context.session.id },+ callback: ({ sessionId }) => sessionId,+ }),+ }),+ }),+ },+});diff --git a/packages/eve/extension-contracts/entrypoints/dynamicTool.ts b/packages/eve/extension-contracts/entrypoints/dynamicTool.tsindex 3e0cc233f..a8ba45e06 100644--- a/packages/eve/extension-contracts/entrypoints/dynamicTool.ts+++ b/packages/eve/extension-contracts/entrypoints/dynamicTool.ts@@ -4,6 +4,7 @@ export {type DynamicToolResult,type DynamicToolSet,defineDurableCallback,+ defineDurableSchema,defineDynamic,} from "../../src/public/tools/index.ts";export { autoModel } from "../../src/public/experimental/evaluate/index.ts";diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v45.json b/packages/eve/extension-contracts/reports/dynamicTool/v45.jsonnew file mode 100644index 000000000..a8fc218f9--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v45.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 45,+ "sha256": "f6032295d049859c4ceaf65b52dc804d57f4e26b6852c0d2c2c6c1f593e3f671",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "autoModel",+ "defineDurableCallback",+ "defineDurableSchema",+ "defineDynamic"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 2099dfbb3..8421ab7fc 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -53,10 +53,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 44,+ current: 45,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, 32,- 33, 41, 42, 43, 44,+ 33, 41, 42, 43, 44, 45,],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 a80d55db3..2ed26e2b5 100644--- a/packages/eve/src/context/build-dynamic-tools.ts+++ b/packages/eve/src/context/build-dynamic-tools.ts@@ -1,3 +1,4 @@+import type { StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";import type { HarnessToolDefinition } from "#harness/execute-tool.js";import type { HarnessToolMap } from "#harness/types.js";import type { ContextReader } from "#context/key.js";@@ -27,7 +28,13 @@ import {type DurableDynamicCallbackReference,type DynamicToolCallbackOwner,} from "#tools/durable-callbacks.js";-import { toInputSchema, toOutputSchema } from "#tools/schema.js";+import { hasSchemaValidator } from "#tools/durable-schema.js";+import {+ toInputSchema,+ toOutputSchema,+ type ToolSchema,+ type ToolSchemaSource,+} from "#tools/schema.js";const log = createLogger("dynamic-tools");@@ -166,7 +173,7 @@ export function replayDynamicTools();},}),- inputSchema: toInputSchema(entry.inputSchema),+ inputSchema: replayDynamicToolSchema(entry, owner, "inputSchema")!,name: entry.name,execution: entry.execution,approval: buildReplayedApproval(entry, owner),@@ -190,7 +197,7 @@ export function replayDynamicTools(return key;},}),- outputSchema: toOutputSchema(entry.outputSchema),+ outputSchema: replayDynamicToolSchema(entry, owner, "outputSchema"),};if (labelComplete !== undefined || labelDelta !== undefined || labelStart !== undefined) {replayed.label = {@@ -204,6 +211,48 @@ export function replayDynamicTools(});}+function replayDynamicToolSchema(+ entry: CurrentDynamicToolMetadata,+ owner: DynamicToolCallbackOwner,+ phase: "inputSchema" | "outputSchema",+): ToolSchema | undefined {+ const jsonSchema = entry[phase];+ if (jsonSchema === undefined) return undefined;+ const reference = entry.callbacks[phase];+ if (reference === undefined) {+ return phase === "inputSchema" ? toInputSchema(jsonSchema) : toOutputSchema(jsonSchema);+ }+ const factory = lookupDurableDynamicCallback(owner, phase);+ let validator: Promise<StandardSchemaV1> | undefined;+ return {+ "~standard": {+ version: 1,+ vendor: "eve",+ jsonSchema: {+ input: () => structuredClone(jsonSchema),+ output: () => structuredClone(jsonSchema),+ },+ validate: async (value) => {+ if (factory === undefined) throw missingCallbackError(entry, phase);+ validator ??= Promise.resolve(callDurableDynamicCallback(factory, reference.closure)).then(+ (source) => {+ if (hasSchemaValidator(source)) return source;+ if (typeof source !== "object" || source === null) {+ throw new Error(+ `Dynamic tool "${entry.name}" ${phase} factory did not return a schema.`,+ );+ }+ return phase === "inputSchema"+ ? toInputSchema(source as ToolSchemaSource)+ : toOutputSchema(source as ToolSchemaSource);+ },+ );+ return (await validator)["~standard"].validate(value);+ },+ },+ };+}+function bindDynamicCallback(entry: CurrentDynamicToolMetadata,owner: DynamicToolCallbackOwner,diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.tsindex 3e542d2e6..4a38a0425 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts@@ -1142,6 +1142,7 @@ describe("dispatchDynamicToolEvent", () => {},});stampDurableDynamicToolCallbacks(entry, {+ inputSchema: { callback: () => entry.inputSchema, closure: {} },execute: { callback: stepFn as never, closure: {} },});return { background_task: entry };diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.tsindex 6eaaa4426..c6b9521a6 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts@@ -42,6 +42,7 @@ import {} from "#tools/durable-callbacks.js";import { toErrorMessage } from "#shared/errors.js";import { parseJsonObject } from "#shared/json.js";+import { hasSchemaValidator } from "#tools/durable-schema.js";import { serializeInputSchema, serializeOutputSchema } from "#tools/schema.js";import type { ResolvedDynamicToolResolver } from "#runtime/types.js";@@ -133,11 +134,15 @@ function validateReference(input: {readonly stamped: StampedDurableDynamicCallback | undefined;readonly required: boolean;}): DurableDynamicCallbackReference | undefined {+ const schemaPhase = input.phase === "inputSchema" || input.phase === "outputSchema";+ const authoringHint = schemaPhase+ ? "Write the schema expression inline in defineTool() or use defineDurableSchema() for a provider package."+ : "Author the callback inline in transformed source or use an eve durable callback helper.";if (input.stamped === undefined) {if (input.required) {throw new Error(`Dynamic tool "${input.name}" callback "${input.phase}" does not have a durable descriptor. ` +- "Author the callback inline in transformed source or use an eve durable callback helper.",+ authoringHint,);}return undefined;@@ -159,7 +164,7 @@ function validateReference(input: {if (typeof input.stamped.callback !== "function") {throw new Error(`Dynamic tool "${input.name}" callback "${input.phase}" does not have a durable descriptor. ` +- "Author the callback inline in transformed source or use an eve durable callback helper.",+ authoringHint,);}let closure: DurableDynamicCallbackReference["closure"];@@ -167,7 +172,10 @@ function validateReference(input: {closure = parseJsonObject(input.stamped.closure);} catch (error) {throw new Error(- `Dynamic tool "${input.name}" callback "${input.phase}" has a non-serializable capture. ${toErrorMessage(error)}`,+ `Dynamic tool "${input.name}" callback "${input.phase}" has a non-serializable capture. ${toErrorMessage(error)}` ++ (schemaPhase+ ? " Inline the schema construction or reference a stable module-level schema; put only JSON data in its closure."+ : ""),);}registerDurableDynamicCallback({@@ -187,6 +195,8 @@ export function validateDurableDynamicToolCallbacks(const unknownPhases = Object.keys(raw).filter((key) =>key !== "execute" &&+ key !== "inputSchema" &&+ key !== "outputSchema" &&key !== "label" &&key !== "approvalKey" &&key !== "approvalRequest" &&@@ -261,8 +271,25 @@ export function validateDurableDynamicToolCallbacks(required: entry.toModelOutput !== undefined,});+ const inputSchema = validateReference({+ name,+ owner,+ phase: "inputSchema",+ stamped: raw.inputSchema,+ required: hasSchemaValidator(entry.inputSchema),+ });+ const outputSchema = validateReference({+ name,+ owner,+ phase: "outputSchema",+ stamped: raw.outputSchema,+ required: hasSchemaValidator(entry.outputSchema),+ });+const callbacks: {execute: DurableDynamicCallbackReference;+ inputSchema?: DurableDynamicCallbackReference;+ outputSchema?: DurableDynamicCallbackReference;label?: {complete?: DurableDynamicCallbackReference;delta?: DurableDynamicCallbackReference;@@ -273,6 +300,8 @@ export function validateDurableDynamicToolCallbacks(approvalResponse?: DurableDynamicCallbackReference;toModelOutput?: DurableDynamicCallbackReference;} = { execute };+ if (inputSchema !== undefined) callbacks.inputSchema = inputSchema;+ if (outputSchema !== undefined) callbacks.outputSchema = outputSchema;if (labelComplete !== undefined || labelDelta !== undefined || labelStart !== undefined) {callbacks.label = {complete: labelComplete,diff --git a/packages/eve/src/context/dynamic-tool-schema-replay.test.ts b/packages/eve/src/context/dynamic-tool-schema-replay.test.tsnew file mode 100644index 000000000..3dbedd109--- /dev/null+++ b/packages/eve/src/context/dynamic-tool-schema-replay.test.ts@@ -0,0 +1,260 @@+import { describe, expect, it, vi } from "vitest";+import { z as z3 } from "zod/v3";+import { z } from "#compiled/zod/index.js";+import { ContextContainer } from "#context/container.js";+import { buildDynamicTools } from "#context/build-dynamic-tools.js";+import {+ dispatchDynamicToolEvent,+ refreshDynamicSessionToolsForRuntimeRevision,+ rebindMissingCompiledDynamicToolCallbacks,+ validateDurableDynamicToolCallbacks,+} from "#context/dynamic-tool-lifecycle.js";+import { deserializeContext, serializeContext } from "#context/serialize.js";+import {+ SessionIdKey,+ SessionDynamicToolRuntimeRevisionKey,+ StaticModelReferenceKey,+} from "#context/keys.js";+import {+ defineTool,+ type PublicToolInputSchema,+ type PublicToolOutputSchema,+} from "#tools/definition.js";+import { defineDurableSchema } from "#tools/durable-schema.js";+import { clearDurableDynamicCallbacks, defineDurableCallback } from "#tools/durable-callbacks.js";+import { isToolSchema, serializeInputSchema, type ToolSchema } from "#tools/schema.js";+import { createStepStartedEvent, type UnstampedMessageStreamEvent } from "#protocol/message.js";+import type { DynamicToolEntry } from "#tools/dynamic.js";+import type { ResolvedDynamicToolResolver } from "#runtime/types.js";++vi.mock("#context/build-callback-context.js", () => ({ buildCallbackContext: () => ({}) }));++let sequence = 0;+const executeOptions = { messages: [], toolCallId: "call_1" };+const owner = {+ sessionId: "schemas",+ scope: "session" as const,+ resolverSlug: "schema",+ entryKey: "tool",+ name: "tool",+};++function event(scope: "session" | "turn" | "step"): UnstampedMessageStreamEvent {+ return scope === "step"+ ? createStepStartedEvent({ modelId: "test", sequence: 0, stepIndex: 0, turnId: "turn" })+ : ({ type: `${scope}.started`, data: {} } as UnstampedMessageStreamEvent);+}++function tool(inputSchema: PublicToolInputSchema, outputSchema?: PublicToolOutputSchema) {+ return defineTool({+ description: "Validated tool",+ inputSchema: defineDurableSchema({ closure: {}, schema: () => inputSchema }),+ ...(outputSchema === undefined+ ? {}+ : { outputSchema: defineDurableSchema({ closure: {}, schema: () => outputSchema }) }),+ execute: defineDurableCallback({ closure: {}, callback: () => "executed" }),+ });+}++async function resolve(createTool: () => unknown, scope: "session" | "turn" | "step" = "session") {+ const ctx = new ContextContainer();+ ctx.set(SessionIdKey, `schema-session-${++sequence}`);+ ctx.set(StaticModelReferenceKey, null);+ const resolver: ResolvedDynamicToolResolver = {+ slug: "schema",+ eventNames: [`${scope}.started`],+ events: { [`${scope}.started`]: () => ({ tool: createTool() }) },+ sourceId: "test:schema",+ sourceKind: "module",+ logicalPath: "agent/tools/schema.ts",+ };+ await dispatchDynamicToolEvent({ ctx, resolvers: [resolver], event: event(scope), messages: [] });+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "stable");+ return { ctx, resolver };+}++async function coldReplay(ctx: ContextContainer, resolver: ResolvedDynamicToolResolver) {+ const restored = await deserializeContext(serializeContext(ctx));+ clearDurableDynamicCallbacks(ctx.require(SessionIdKey));+ await refreshDynamicSessionToolsForRuntimeRevision({+ ctx: restored,+ resolvers: [resolver],+ event: { type: "session.started", data: {} },+ messages: [],+ runtimeRevision: "stable",+ });+ return buildDynamicTools(restored)[0]!;+}++function validate(schema: unknown, value: unknown) {+ if (!isToolSchema(schema)) throw new Error("Expected a live schema");+ return schema["~standard"].validate(value);+}++describe("durable dynamic tool schemas", () => {+ it.each(["session", "turn", "step"] as const)(+ "preserves %s input and output validation through context serialization",+ async (scope) => {+ const schema = z.object({ value: z.string().trim().min(1).optional() });+ const { ctx } = await resolve(() => tool(schema, schema), scope);+ const replayed = buildDynamicTools(await deserializeContext(serializeContext(ctx)))[0]!;+ for (const live of [replayed.inputSchema, replayed.outputSchema]) {+ expect(await validate(live, { value: " " })).toHaveProperty("issues");+ expect(await validate(live, { value: " normalized " })).toEqual({+ value: { value: "normalized" },+ });+ }+ expect(serializeInputSchema(replayed.inputSchema as ToolSchema)).toEqual(+ serializeInputSchema(schema),+ );+ },+ );++ it.each([+ z.object({ value: z.string().trim().min(1) }),+ z3.object({ value: z3.string().trim().min(1) }),+ ])("preserves Zod transforms after a cold start", async (schema) => {+ const { ctx, resolver } = await resolve(() => tool(schema));+ const replayed = await coldReplay(ctx, resolver);+ expect(await validate(replayed.inputSchema, { value: " " })).toHaveProperty("issues");+ expect(await validate(replayed.inputSchema, { value: " a " })).toEqual({+ value: { value: "a" },+ });+ });++ it("preserves cross-field refinements and asynchronous Standard Schema validation", async () => {+ const schema = z.object({ start: z.number(), end: z.number() }).superRefine((value, ctx) => {+ if (value.start >= value.end)+ ctx.addIssue({ code: "custom", message: "End must follow start" });+ });+ const asyncSchema: ToolSchema = {+ "~standard": {+ version: 1,+ vendor: "custom",+ validate: async (value) =>+ value === "allowed" ? { value: "normalized" } : { issues: [{ message: "Denied" }] },+ jsonSchema: { input: () => ({ type: "string" }), output: () => ({ type: "string" }) },+ },+ };+ const { ctx, resolver } = await resolve(() => tool(schema, asyncSchema));+ const replayed = await coldReplay(ctx, resolver);+ expect(await validate(replayed.inputSchema, { start: 2, end: 1 })).toHaveProperty("issues");+ expect(await validate(replayed.outputSchema, "denied")).toHaveProperty("issues");+ expect(await validate(replayed.outputSchema, "allowed")).toEqual({ value: "normalized" });+ });++ it("rebuilds validation and execution from the same original captures", async () => {+ let limit = 10;+ const { ctx, resolver } = await resolve(() =>+ defineTool({+ description: "Captured limit",+ inputSchema: defineDurableSchema({+ closure: { limit },+ schema: ({ limit }) => z.object({ amount: z.number().refine((value) => value <= limit) }),+ }),+ execute: defineDurableCallback({ closure: { limit }, callback: ({ limit }) => limit }),+ }),+ );+ limit = 100;+ const replayed = await coldReplay(ctx, resolver);+ expect(await validate(replayed.inputSchema, { amount: 50 })).toHaveProperty("issues");+ expect(await validate(replayed.inputSchema, { amount: 5 })).toEqual({ value: { amount: 5 } });+ await expect(replayed.execute!({}, executeOptions)).resolves.toBe(10);+ });++ it("isolates identical JSON shapes across sessions", async () => {+ const makeTool = (required: string) =>+ defineTool({+ description: "Session value",+ inputSchema: defineDurableSchema({+ closure: { required },+ schema: ({ required }) =>+ z.object({ value: z.string().refine((value) => value === required) }),+ }),+ execute: defineDurableCallback({ closure: {}, callback: () => "executed" }),+ });+ const first = await resolve(() => makeTool("first"));+ const second = await resolve(() => makeTool("second"));+ const replayed = await coldReplay(first.ctx, first.resolver);+ expect(await validate(replayed.inputSchema, { value: "second" })).toHaveProperty("issues");+ expect(+ await validate(buildDynamicTools(second.ctx)[0]!.inputSchema, { value: "first" }),+ ).toHaveProperty("issues");+ });++ it("does not evict an active turn schema after 2,048 other resolutions", async () => {+ const { ctx, resolver } = await resolve(() => tool(z.object({ value: z.string() })), "turn");+ // Resolve many entries in one other session: callback storage is bounded by sessions, not individual schemas.+ const other = new ContextContainer();+ other.set(SessionIdKey, `other-schema-session-${++sequence}`);+ other.set(StaticModelReferenceKey, null);+ const otherResolver = {+ ...resolver,+ events: {+ "turn.started": () =>+ Object.fromEntries(+ Array.from({ length: 2_049 }, (_, index) => [`tool_${index}`, tool(z.object({}))]),+ ),+ },+ };+ await dispatchDynamicToolEvent({+ ctx: other,+ resolvers: [otherResolver],+ event: event("turn"),+ messages: [],+ });+ await rebindMissingCompiledDynamicToolCallbacks({+ ctx,+ resolvers: [resolver],+ event: event("turn"),+ messages: [],+ });+ expect(await validate(buildDynamicTools(ctx)[0]!.inputSchema, { value: "ok" })).toEqual({+ value: { value: "ok" },+ });+ });++ it("fails validation closed if a schema factory is removed during recovery", async () => {+ const { ctx, resolver } = await resolve(() => tool(z.object({ value: z.string().min(1) })));+ const replacement = {+ ...resolver,+ events: {+ "session.started": () => ({+ tool: defineTool({+ description: "JSON-only replacement",+ inputSchema: { type: "object" },+ execute: defineDurableCallback({ closure: {}, callback: () => "executed" }),+ }),+ }),+ },+ };+ const replayed = await coldReplay(ctx, replacement);+ await expect(validate(replayed.inputSchema, { value: " " })).rejects.toThrow(+ "cannot replay its inputSchema callback",+ );+ });++ it("rejects an unstamped live schema instead of reducing it to JSON Schema", () => {+ const entry = defineTool({+ description: "Untransformed",+ inputSchema: z.object({ value: z.string().trim() }),+ execute: defineDurableCallback({ closure: {}, callback: () => null }),+ });+ expect(() =>+ validateDurableDynamicToolCallbacks("tool", entry as DynamicToolEntry, owner),+ ).toThrow("defineDurableSchema()");+ });++ it("rejects non-serializable schema captures at resolution", () => {+ const schema = z.object({ value: z.string() });+ const entry = defineTool({+ description: "Invalid capture",+ // Simulate an authored local schema reference captured by the compiler.+ inputSchema: defineDurableSchema({ closure: { schema } as never, schema: () => schema }),+ execute: defineDurableCallback({ closure: {}, callback: () => null }),+ });+ expect(() =>+ validateDurableDynamicToolCallbacks("tool", entry as DynamicToolEntry, owner),+ ).toThrow('"inputSchema" has a non-serializable capture');+ });+});diff --git a/packages/eve/src/context/memory-tools.test.ts b/packages/eve/src/context/memory-tools.test.tsindex 84457c1dc..dfe294f0f 100644--- a/packages/eve/src/context/memory-tools.test.ts+++ b/packages/eve/src/context/memory-tools.test.ts@@ -1,3 +1,5 @@+import { z } from "#compiled/zod/index.js";+import { isToolSchema } from "#tools/schema.js";import { describe, expect, it } from "vitest";import { buildDynamicTools } from "#context/build-dynamic-tools.js";@@ -63,7 +65,9 @@ function resolver(version: () => number): ResolvedDynamicToolResolver {approval: always(),description: "Save a field.",execute: async () => `${version()}:${String(context.memory.scope.value)}`,- inputSchema: {},+ inputSchema: z.object({+ scope: z.string().refine((value) => value === context.memory.scope.value),+ }),}),}),},@@ -134,6 +138,13 @@ describe("memory provider tools", () => {async () => await replayed.execute!({}, { messages: [], toolCallId: "call_1" }),);expect(output).toBe("2:user_1");+ if (!isToolSchema(replayed.inputSchema)) throw new Error("Expected live schema");+ expect(await replayed.inputSchema["~standard"].validate({ scope: "user_2" })).toHaveProperty(+ "issues",+ );+ expect(await replayed.inputSchema["~standard"].validate({ scope: "user_1" })).toEqual({+ value: { scope: "user_1" },+ });});it("omits tools when the provider has no tool factory", async () => {diff --git a/packages/eve/src/context/memory-tools.ts b/packages/eve/src/context/memory-tools.tsindex 52c3d5ed5..8650e687d 100644--- a/packages/eve/src/context/memory-tools.ts+++ b/packages/eve/src/context/memory-tools.ts@@ -88,6 +88,14 @@ function createProviderToolCallbacks(input: {closure,},};+ for (const phase of ["inputSchema", "outputSchema"] as const) {+ if (input.tool[phase] !== undefined) {+ callbacks[phase] = {+ callback: async (rawClosure) => (await loadTool(rawClosure))[phase],+ closure,+ };+ }+ }if (input.tool.approval !== undefined) {callbacks.approvalRequest = {callback: async (rawClosure, context) =>diff --git a/packages/eve/src/execution/tools/connection-search.test.ts b/packages/eve/src/execution/tools/connection-search.test.tsindex 7d8cf0482..62b37c329 100644--- a/packages/eve/src/execution/tools/connection-search.test.ts+++ b/packages/eve/src/execution/tools/connection-search.test.ts@@ -2,7 +2,11 @@ import { describe, expect, it, vi } from "vitest";import { ConnectionRegistryKey } from "#context/providers/connection-key.js";import { ContextContainer, contextStorage } from "#context/container.js";-import { AuthKey, SessionIdKey } from "#context/keys.js";+import { AuthKey, SessionIdKey, StaticModelReferenceKey } from "#context/keys.js";+import { buildDynamicTools } from "#context/build-dynamic-tools.js";+import { dispatchDynamicToolEvent } from "#context/dynamic-tool-lifecycle.js";+import { createStepStartedEvent } from "#protocol/message.js";+import { isToolSchema } from "#tools/schema.js";import {CallbackBaseUrlKey,isAuthorizationSignal,@@ -16,7 +20,7 @@ import type {} from "#shared/connection-types.js";import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";import connectionSearch from "#tools/framework/connection-search.js";-import type { ResolvedConnectionDefinition } from "#runtime/types.js";+import type { ResolvedConnectionDefinition, ResolvedDynamicToolResolver } from "#runtime/types.js";import { isBrandedToolEntry, type DynamicToolSet } from "#tools/dynamic.js";import type { DynamicResolveContext } from "#dynamic/definition.js";import { readDurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";@@ -80,6 +84,51 @@ function registry(input: {}describe("connection dynamic tools", () => {+ it("survives lifecycle resolution with both authored schema validators", async () => {+ const ctx = new ContextContainer();+ ctx.set(SessionIdKey, "connection-schema-replay");+ ctx.set(StaticModelReferenceKey, null);+ ctx.set(+ ConnectionRegistryKey,+ registry({+ connections: [connection("linear")],+ loadTools: { linear: async () => [] },+ }),+ );+ const resolver: ResolvedDynamicToolResolver = {+ slug: "connection-search",+ sourceId: "eve:connection-search",+ sourceKind: "module",+ logicalPath: "tools/connection-search.ts",+ eventNames: ["step.started"],+ events: getConnectionSearchResolver().events as ResolvedDynamicToolResolver["events"],+ };+ await contextStorage.run(ctx, () =>+ dispatchDynamicToolEvent({+ ctx,+ resolvers: [resolver],+ messages: [],+ event: createStepStartedEvent({+ modelId: "test",+ turnId: "turn",+ stepIndex: 0,+ sequence: 0,+ }),+ }),+ );+ const tools = buildDynamicTools(ctx);+ expect(tools.map((tool) => tool.name)).toEqual(["connection_search"]);+ const tool = tools[0]!;+ if (!isToolSchema(tool.inputSchema) || !isToolSchema(tool.outputSchema)) {+ throw new Error("Expected both connection search schemas");+ }+ expect(await tool.inputSchema["~standard"].validate({ keywords: 42 })).toHaveProperty("issues");+ expect(await tool.inputSchema["~standard"].validate({ keywords: "issues" })).toEqual({+ value: { keywords: "issues" },+ });+ expect(await tool.outputSchema["~standard"].validate("invalid")).toHaveProperty("issues");+ });+it("contributes no tools when no connections are available", async () => {const ctx = new ContextContainer();ctx.set(diff --git a/packages/eve/src/execution/tools/connection-search.ts b/packages/eve/src/execution/tools/connection-search.tsindex eca9a738f..a7353d61a 100644--- a/packages/eve/src/execution/tools/connection-search.ts+++ b/packages/eve/src/execution/tools/connection-search.ts@@ -407,6 +407,8 @@ export async function resolveConnectionSearchDynamicTools() {outputSchema: CONNECTION_SEARCH_OUTPUT_SCHEMA,});stampDurableDynamicToolCallbacks(connectionSearchTool, {+ inputSchema: { callback: () => CONNECTION_SEARCH_INPUT_SCHEMA, closure: {} },+ outputSchema: { callback: () => CONNECTION_SEARCH_OUTPUT_SCHEMA, closure: {} },execute: {callback: (_closure, input) => executeConnectionSearch(input as ConnectionSearchInput),closure: {},diff --git a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.tsindex ad2069b74..0e621711c 100644--- a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts+++ b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts@@ -1,3 +1,6 @@+import { z } from "#compiled/zod/index.js";+import { defineDurableSchema } from "#tools/durable-schema.js";+import { isToolSchema } from "#tools/schema.js";import { describe, expect, it, beforeEach } from "vitest";import { transformDynamicToolExecute } from "./dynamic-tool-transform.js";@@ -52,6 +55,8 @@ async function transformAndEval(stampDurableDynamicToolCallbacks(entry,collectDurableDynamicToolCallbacks({+ inputSchema: entry.inputSchema,+ outputSchema: entry.outputSchema,label: entry.label as { complete?: never; delta?: never; start?: never } | undefined,approval: entry.approval as never,approvalKey: entry.approvalKey as never,@@ -64,8 +69,14 @@ async function transformAndEval(// Evaluate in a function scope to provide our stubs. The transform// prepends its own __eveStepRegistry setup, so we don't need to add it.- const evalFn = new Function("defineDynamic", "defineTool", `${code}\nreturn __exported;`);- evalFn(defineDynamic, defineTool);+ const evalFn = new Function(+ "defineDynamic",+ "defineTool",+ "__eveDefineDurableSchema",+ "z",+ `${code}\nreturn __exported;`,+ );+ evalFn(defineDynamic, defineTool, defineDurableSchema, z);return {code,@@ -2485,3 +2496,51 @@ describe("approvalKey callbacks", () => {).toBe("repo:main");});});++describe("durable schema expression transform", () => {+ it("captures inline refinement values separately from the current resolver invocation", async () => {+ const { callHandler } = await transformAndEval(+ "schema.ts",+ `+ import { defineTool, defineDynamic } from "eve/tools";+ import { z } from "zod";+ const output = z.object({ value: z.string().trim() });+ export default defineDynamic({ events: { "session.started": (_event, ctx) => {+ const limit = ctx.limit;+ return { checked: defineTool({+ description: "Checked",+ inputSchema: z.object({ amount: z.number().refine(value => value <= limit) }),+ outputSchema: output,+ execute: () => limit,+ }) };+ } } });+ `,+ { ctx: { limit: 10 } },+ );+ const entry = (await callHandler()).checked;+ const callbacks = durableCallbacks(entry);+ expect(callbacks.inputSchema!.closure).toEqual({ limit: 10 });+ expect(callbacks.outputSchema!.closure).toEqual({});+ const schema = callbacks.inputSchema!.callback({ limit: 5 });+ if (!isToolSchema(schema)) throw new Error("Expected schema");+ expect(await schema["~standard"].validate({ amount: 6 })).toHaveProperty("issues");+ expect(await schema["~standard"].validate({ amount: 4 })).toEqual({ value: { amount: 4 } });+ const output = callbacks.outputSchema!.callback({});+ if (!isToolSchema(output)) throw new Error("Expected output schema");+ expect(await output["~standard"].validate({ value: " a " })).toEqual({ value: { value: "a" } });+ });++ it("does not wrap explicit durable schema factories again", async () => {+ const result = await transformDynamicToolExecute(+ "schema.ts",+ `+ import { defineTool, defineDurableSchema as durable } from "eve/tools";+ import { z } from "zod";+ export function tool(limit) {+ return defineTool({ inputSchema: durable({ closure: { limit }, schema: ({ limit }) => z.number().max(limit) }), execute: () => null });+ }+ `,+ );+ expect(result!.code).not.toContain("__eveDefineDurableSchema");+ });+});diff --git a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.tsindex 0aaad6f4e..2bda4a7a9 100644--- a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts+++ b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts@@ -21,7 +21,9 @@ type CallbackPhase =| "approvalRequest"| "approvalResponse"| "execute"- | "toModelOutput";+ | "toModelOutput"+ | "inputSchema"+ | "outputSchema";type CallbackPropertyName =| "approvalKey"| "label"@@ -32,7 +34,9 @@ type CallbackPropertyName =| "response"| "complete"| "delta"- | "toModelOutput";+ | "toModelOutput"+ | "inputSchema"+ | "outputSchema";interface CallbackInfo {readonly body: string;@@ -70,7 +74,11 @@ export async function transformDynamicToolExecute(if (defineToolAliases.size === 0) return null;const callbacks: CallbackInfo[] = [];- walkForCallbacks(source, ast, callbacks, [], { defineToolAliases, workflowFunctions });+ walkForCallbacks(source, ast, callbacks, [], {+ defineToolAliases,+ workflowFunctions,+ durableSchemaAliases: findDefineToolAliases(ast, ["defineDurableSchema"]),+ });return callbacks.length === 0 ? null : applyTransform(source, callbacks);}@@ -78,6 +86,7 @@ const NO_WORKFLOW_FUNCTIONS: ReadonlySet<string> = new Set();interface WalkContext {readonly defineToolAliases: ReadonlySet<string>;+ readonly durableSchemaAliases: ReadonlySet<string>;/*** Top-level `"use workflow"` functions the directive transform already* hoisted and stubbed. A tool whose `execute` is one never runs as a@@ -89,7 +98,10 @@ interface WalkContext {// Keep the old export name for backward compatibility with the plugin.export { transformDynamicToolExecute as transformDynamicToolAwait };-function findDefineToolAliases(ast: AstNode): ReadonlySet<string> {+function findDefineToolAliases(+ ast: AstNode,+ names: readonly string[] = ["defineTool", "defineWorkflowTool"],+): ReadonlySet<string> {const aliases = new Set<string>();walkNode(ast, (node) => {if (node.type !== "ImportDeclaration") return true;@@ -99,13 +111,11 @@ function findDefineToolAliases(ast: AstNode): ReadonlySet<string> {}for (const specifier of node.specifiers ?? []) {if (specifier.type === "ImportNamespaceSpecifier" && specifier.local?.name) {- aliases.add(`${specifier.local.name}.defineWorkflowTool`);+ for (const name of names) aliases.add(`${specifier.local.name}.${name}`);}if (specifier.type === "ImportSpecifier" &&- ["defineTool", "defineWorkflowTool"].includes(- String(specifier.imported?.name ?? specifier.imported?.value),- ) &&+ names.includes(String(specifier.imported?.name ?? specifier.imported?.value)) &&specifier.local?.name) {aliases.add(specifier.local.name);@@ -234,6 +244,39 @@ function collectToolCallbacks(nestedScopes,);+ for (const propertyName of ["inputSchema", "outputSchema"] as const) {+ const property = findProperty(tool, propertyName);+ const value = property?.value as AstNode | undefined;+ if (+ property?.start === undefined ||+ property.end === undefined ||+ value?.start === undefined ||+ value.end === undefined+ )+ continue;+ // JSON Schema literals are already durable data and need no factory.+ if (value.type === "ObjectExpression" && !findProperty(value, "~standard")) continue;+ if (+ value.type === "CallExpression" &&+ (value.callee?.name === "__eveDefineDurableSchema" ||+ context.durableSchemaAliases.has(readDefinerName(value.callee) ?? ""))+ )+ continue;+ results.push({+ body: `{ return ${source.slice(value.start, value.end)}; }`,+ bodyNode: value,+ isAsync: false,+ isGenerator: false,+ isReference: false,+ nestedScopes,+ params: "",+ phase: propertyName,+ propertyName,+ propEnd: property.end,+ propStart: property.start,+ });+ }+const approval = findProperty(tool, "approval");const approvalValue = approval?.value as AstNode | undefined;if (approvalValue?.type === "ObjectExpression") {@@ -342,7 +385,10 @@ function applyTransform(source: string, callbacks: readonly CallbackInfo[]): { c);const wrapper = createLiveWrapper(callback, hoistedName, closure);- const stamped = `__eveStampDynamicCallback(${wrapper}, ${hoistedName}, ${closure})`;+ const stamped =+ callback.phase === "inputSchema" || callback.phase === "outputSchema"+ ? `__eveDefineDurableSchema({ schema: ${hoistedName}, closure: ${closure} })`+ : `__eveStampDynamicCallback(${wrapper}, ${hoistedName}, ${closure})`;replacements.push({end: callback.propEnd,start: callback.propStart,@@ -356,6 +402,11 @@ function applyTransform(source: string, callbacks: readonly CallbackInfo[]): { c}const registrySetup = [+ ...(callbacks.some(+ (callback) => callback.phase === "inputSchema" || callback.phase === "outputSchema",+ )+ ? ['import { defineDurableSchema as __eveDefineDurableSchema } from "eve/tools";']+ : []),`var __eveDurableCallbackSym = Symbol.for("eve:durable-dynamic-callback");`,`function __eveStampDynamicCallback(callback, impl, closure) {`,` Object.defineProperty(callback, __eveDurableCallbackSym, { configurable: true, value: { callback: impl, closure } });`,diff --git a/packages/eve/src/public/tools/index.ts b/packages/eve/src/public/tools/index.tsindex e2ba3d179..41e739e2a 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 { defineDurableSchema } from "#tools/durable-schema.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";diff --git a/packages/eve/src/tools/definition.ts b/packages/eve/src/tools/definition.tsindex 73ac7e744..ca0ba1247 100644--- a/packages/eve/src/tools/definition.ts+++ b/packages/eve/src/tools/definition.ts@@ -390,6 +390,8 @@ export function defineTool<TInput = unknown, TOutput = unknown>(export function stampToolDefinition<T extends {readonly description: string;+ readonly inputSchema?: unknown;+ readonly outputSchema?: unknown;readonly execute: (...args: never[]) => unknown;readonly label?: ToolLabelDefinition;readonly approval?: Approval<never>;@@ -407,6 +409,8 @@ export function stampToolDefinition<stampDurableDynamicToolCallbacks(definition,collectDurableDynamicToolCallbacks({+ inputSchema: definition.inputSchema,+ outputSchema: definition.outputSchema,label: definition.label,approval: definition.approval,approvalKey: definition.approvalKey,diff --git a/packages/eve/src/tools/durable-callbacks.ts b/packages/eve/src/tools/durable-callbacks.tsindex 808384b75..37984a147 100644--- a/packages/eve/src/tools/durable-callbacks.ts+++ b/packages/eve/src/tools/durable-callbacks.ts@@ -1,3 +1,4 @@+import { readDurableSchema } from "#tools/durable-schema.js";import type { Approval } from "#approval/definition.js";import { resolveApprovalPolicy } from "#approval/definition.js";import type { JsonObject, JsonPrimitive } from "#shared/json.js";@@ -10,7 +11,9 @@ export type DurableDynamicCallbackPhase =| "approvalRequest"| "approvalResponse"| "execute"- | "toModelOutput";+ | "toModelOutput"+ | "inputSchema"+ | "outputSchema";export type DurableDynamicCallbackFn = (closure: JsonObject, ...args: never[]) => unknown;@@ -27,6 +30,8 @@ export interface DurableDynamicCallbackReference {export interface DurableDynamicToolCallbacks {readonly execute: DurableDynamicCallbackReference;+ readonly inputSchema?: DurableDynamicCallbackReference;+ readonly outputSchema?: DurableDynamicCallbackReference;readonly label?: {readonly complete?: DurableDynamicCallbackReference;readonly delta?: DurableDynamicCallbackReference;@@ -46,6 +51,8 @@ export interface StampedDurableDynamicCallback {export type LiveDurableDynamicToolCallbacks = Partial<{execute: StampedDurableDynamicCallback;+ inputSchema: StampedDurableDynamicCallback;+ outputSchema: StampedDurableDynamicCallback;label: {readonly complete?: StampedDurableDynamicCallback;readonly delta?: StampedDurableDynamicCallback;@@ -169,6 +176,8 @@ function durableCallbackPhases(DurableDynamicCallbackReference | undefined,])[] = [["execute", callbacks.execute],+ ["inputSchema", callbacks.inputSchema],+ ["outputSchema", callbacks.outputSchema],["labelComplete", callbacks.label?.complete],["labelDelta", callbacks.label?.delta],["labelStart", callbacks.label?.start],@@ -190,7 +199,7 @@ type DurableCallbackJsonValue<T> = T extends (...args: never[]) => unknown? DurableCallbackJsonObject<T>: never;-type DurableCallbackJsonObject<T extends object> =+export type DurableCallbackJsonObject<T extends object> =Extract<keyof T, symbol> extends never? {readonly [TKey in keyof T]:@@ -255,6 +264,8 @@ export function stampDurableDynamicToolCallbacks(}export function collectDurableDynamicToolCallbacks(input: {+ readonly inputSchema?: unknown;+ readonly outputSchema?: unknown;readonly label?: {readonly complete?: (...args: never[]) => unknown;readonly delta?: (...args: never[]) => unknown;@@ -281,6 +292,10 @@ export function collectDurableDynamicToolCallbacks(input: {const execute = readDurableDynamicCallback(input.execute);const toModelOutput = readDurableDynamicCallback(input.toModelOutput);const callbacks: LiveDurableDynamicToolCallbacks = {};+ const inputSchema = readDurableSchema(input.inputSchema);+ const outputSchema = readDurableSchema(input.outputSchema);+ if (inputSchema !== undefined) callbacks.inputSchema = inputSchema;+ if (outputSchema !== undefined) callbacks.outputSchema = outputSchema;if (execute !== undefined) callbacks.execute = execute;if (labelComplete !== undefined || labelDelta !== undefined || labelStart !== undefined) {callbacks.label = {diff --git a/packages/eve/src/tools/durable-schema.test.ts b/packages/eve/src/tools/durable-schema.test.tsnew file mode 100644index 000000000..3bd475c1c--- /dev/null+++ b/packages/eve/src/tools/durable-schema.test.ts@@ -0,0 +1,47 @@+import { describe, expect, expectTypeOf, it } from "vitest";+import { z } from "#compiled/zod/index.js";+import { defineDurableSchema, readDurableSchema } from "#tools/durable-schema.js";+import { defineTool } from "#tools/definition.js";+import { serializeInputSchema } from "#tools/schema.js";++describe("defineDurableSchema", () => {+ it("leaves JSON-only schemas unchanged without adding a runtime validation contract", () => {+ const source = { type: "string", minLength: 1 };+ const schema = defineDurableSchema({ closure: {}, schema: () => source });+ expect(schema).toBe(source);+ expect(readDurableSchema(schema)).toBeUndefined();+ expectTypeOf(schema).toEqualTypeOf<typeof source>();+ });+ it("leaves absent optional output schemas undefined", () => {+ const schema = defineDurableSchema({ closure: {}, schema: () => undefined });+ expectTypeOf(schema).toEqualTypeOf<undefined>();+ expect(schema).toBeUndefined();+ });+ it("preserves inferred transformed input types", () => {+ const schema = defineDurableSchema({+ closure: { prefix: "value:" },+ schema: ({ prefix }) => z.object({ value: z.string().transform((value) => prefix + value) }),+ });+ defineTool({+ description: "Typed schema",+ inputSchema: schema,+ execute(input) {+ expectTypeOf(input).toEqualTypeOf<{ value: string }>();+ return input.value;+ },+ });+ expect(schema["~standard"].validate({ value: "a" })).toEqual({ value: { value: "value:a" } });+ expect(serializeInputSchema(schema)).toMatchObject({+ properties: { value: { type: "string" } },+ });+ });++ it("does not mutate shared or frozen schema objects", () => {+ const source = Object.freeze({ "~standard": z.object({ value: z.string() })["~standard"] });+ const first = defineDurableSchema({ closure: { version: 1 }, schema: () => source });+ const second = defineDurableSchema({ closure: { version: 2 }, schema: () => source });+ expect(readDurableSchema(source)).toBeUndefined();+ expect(readDurableSchema(first)?.closure).toEqual({ version: 1 });+ expect(readDurableSchema(second)?.closure).toEqual({ version: 2 });+ });+});diff --git a/packages/eve/src/tools/durable-schema.ts b/packages/eve/src/tools/durable-schema.tsnew file mode 100644index 000000000..038151a6a--- /dev/null+++ b/packages/eve/src/tools/durable-schema.ts@@ -0,0 +1,68 @@+import type { StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";+import type {+ DurableCallbackJsonObject,+ StampedDurableDynamicCallback,+} from "#tools/durable-callbacks.js";+import {+ serializeInputSchema,+ serializeOutputSchema,+ type ToolSchema,+ type ToolSchemaSource,+} from "#tools/schema.js";+import type { JsonObject } from "#shared/json.js";++const DURABLE_SCHEMA = Symbol.for("eve:durable-dynamic-schema");++export function hasSchemaValidator(source: unknown): source is StandardSchemaV1 {+ if (typeof source !== "object" || source === null || !("~standard" in source)) return false;+ const standard = source["~standard"];+ return (+ typeof standard === "object" &&+ standard !== null &&+ "validate" in standard &&+ typeof standard.validate === "function"+ );+}++type DurableSchema<TSchema> = TSchema extends StandardSchemaV1+ ? ToolSchema<StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>+ : TSchema;++/**+ * Defines a replayable schema for dynamic tools returned by provider packages.+ * Put per-tool values in `closure`; `schema` rebuilds the validator from that+ * JSON snapshot. Authored inline schema expressions are transformed automatically.+ */+export function defineDurableSchema<+ TClosure extends object,+ TSchema extends ToolSchemaSource | undefined,+>(input: {+ readonly closure: TClosure & DurableCallbackJsonObject<TClosure>;+ readonly schema: (closure: TClosure) => TSchema;+}): DurableSchema<TSchema> {+ const source = input.schema(input.closure);+ if (!hasSchemaValidator(source)) return source as DurableSchema<TSchema>;+ const schema: ToolSchema = {+ "~standard": {+ version: 1,+ vendor: "eve",+ validate: (value) => source["~standard"].validate(value),+ jsonSchema: {+ input: () => serializeInputSchema(source),+ output: () => serializeOutputSchema(source),+ },+ },+ };+ Object.defineProperty(schema, DURABLE_SCHEMA, {+ value: {+ callback: (closure: JsonObject) => input.schema(closure as TClosure),+ closure: input.closure as JsonObject,+ } satisfies StampedDurableDynamicCallback,+ });+ return schema as DurableSchema<TSchema>;+}++export function readDurableSchema(source: unknown): StampedDurableDynamicCallback | undefined {+ if (typeof source !== "object" || source === null) return undefined;+ return Reflect.get(source, DURABLE_SCHEMA) as StampedDurableDynamicCallback | undefined;+}diff --git a/packages/eve/test/scenarios/dynamic-tool-cold-replay.scenario.test.ts b/packages/eve/test/scenarios/dynamic-tool-cold-replay.scenario.test.tsindex fd377c1c9..149ddf476 100644--- a/packages/eve/test/scenarios/dynamic-tool-cold-replay.scenario.test.ts+++ b/packages/eve/test/scenarios/dynamic-tool-cold-replay.scenario.test.ts@@ -36,11 +36,12 @@ function writeMarker(phase: string, key: string, extra: Record<string, unknown>}export function createDurableMarkerTool(key: string) {+ const suffix = process.env.EVE_SCHEMA_TEST_SUFFIX ?? "";services.set(key, { createdInPid: process.pid, key });return tool({description: "Durable marker tool " + key + ".",- inputSchema: z.object({ label: z.string().optional() }),+ inputSchema: z.object({ label: z.string().transform((value) => value.toUpperCase() + suffix).optional() }),approval: {request(context) {writeMarker("approval-request", key, { callId: context.callId });@@ -57,6 +58,7 @@ export function createDurableMarkerTool(key: string) {const output = {key,label: input.label ?? "unlabeled",+ suffix,pid: process.pid,rawSecret: "raw-secret-" + key,serviceCreatedInPid: service.createdInPid,@@ -115,6 +117,8 @@ interface Marker {readonly phase: string;readonly pid: number;readonly serviceCreatedInPid?: number;+ readonly label?: string;+ readonly suffix?: string;}async function readMarker(appRoot: string, phase: string, key: string): Promise<Marker> {@@ -131,7 +135,9 @@ describe("dynamic tool cold replay", () => {const pinnedEnv = {WORKFLOW_INLINE_OWNERSHIP_LEASE_SECONDS: "1",};- let server = await startEveDev(app.appRoot, { env: pinnedEnv });+ let server = await startEveDev(app.appRoot, {+ env: { ...pinnedEnv, EVE_SCHEMA_TEST_SUFFIX: ":original" },+ });try {const client = new Client({ host: server.url });@@ -168,7 +174,9 @@ describe("dynamic tool cold replay", () => {return error instanceof Error && "code" in error && error.code === "ENOENT";}}, "The crashed development server did not release its state record.");- server = await startEveDev(app.appRoot, { env: pinnedEnv });+ server = await startEveDev(app.appRoot, {+ env: { ...pinnedEnv, EVE_SCHEMA_TEST_SUFFIX: ":changed" },+ });const resumedSession = new Client({ host: server.url }).sessions.attach(sessionState.sessionId,@@ -192,6 +200,8 @@ describe("dynamic tool cold replay", () => {expect(response.pid).not.toBe(firstRequest.pid);expect(execute.pid).toBe(response.pid);expect(execute.serviceCreatedInPid).toBe(execute.pid);+ expect(execute.label).toBe("STRUCTURED-OUTPUT:original");+ expect(execute.suffix).toBe(":original");expect(projection.pid).toBe(execute.pid);}diff --git a/research/durable-dynamic-tool-schemas.md b/research/durable-dynamic-tool-schemas.mdnew file mode 100644index 000000000..16899f563--- /dev/null+++ b/research/durable-dynamic-tool-schemas.md@@ -0,0 +1,53 @@+---+issue: https://github.com/vercel/eve/issues/3019+status: implemented+last_updated: "2026-09-17"+---++# Durable dynamic tool schemas++Dynamic tools must run their authored validators. JSON Schema cannot retain+transforms or refinements, and an in-memory validator cache cannot preserve+captured state across recovery. Related: #1682.++## Authoring contract++Keep `inputSchema` and `outputSchema` expressions in `defineTool()`. The compiler+hoists each expression into a schema factory and snapshots its referenced local+JSON values using the existing durable callback mechanism. Stable module-level+schema references are supported; local schema objects, clients, and functions+are non-serializable captures and fail resolution with a diagnostic.++Packages outside the source transform use `defineDurableSchema({ closure,+schema })` from `eve/tools`. The synchronous `schema` function receives the JSON+closure snapshot and returns the authored schema. The helper preserves Standard+Schema validation and JSON Schema emission. Plain JSON schemas remain supported.++Factories must be deterministic for their captures. Read changing external data+in the resolver and capture its JSON result. Module-level values and imports are+live code under the same contract as existing durable callbacks.++## Replay++Store schema factories as input/output phases in the existing callback registry.+Persist their closure data alongside execute/approval closures and the model's+JSON Schema description. Materialize a validator from the persisted closure+when validation is first needed. Preserve async validation and Zod 3 input+validation. Missing factories fail closed at validation.++Session recovery re-runs the owning resolver to register its current code but+keeps the original factory and executor captures. Existing scope and redeploy+rules apply. There is no independent validator registry or per-schema eviction.++Memory provider tools rebuild schemas with the same persisted provider context+used to reconstruct their callbacks. Existing extensions must be rebuilt to+include the new schema descriptors. The runtime rejects unstamped live schemas+rather than silently reducing them to JSON validation.++## Verification++Unit coverage checks captures, cross-session isolation, all lifecycle scopes,+missing descriptors, async validation, and large tool sets. A process-restart+scenario changes resolver configuration while an approval is parked and checks+that a non-idempotent transform and executor both retain their original capture.+Fixture evals exercise transformed dynamic input across turns in CI.