eve 0.52.3 → 0.52.5

package/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.
 

package/docs/sandbox.mdx

@@ -289,6 +289,8 @@ Custom backend handles implement the same boundary in `delete()`: remove the ses
 
 Session sandboxes are keyed per durable session, not per deployment, so redeploying your app does not by itself discard them. A definition change to the authored sandbox source, workspace seed content, or `revalidationKey` replaces the sandbox on the next turn and runs `onSession` again.
 
+For sandboxes with `bootstrap`, unrelated agent changes preserve the template and session sandbox keys even when there are no skill or workspace seed files. You do not need to add a seed file or `revalidationKey` solely to preserve reuse across those changes.
+
 Reattachment still depends on the backend retaining its physical sandbox state. If a persisted Vercel sandbox is no longer available, eve creates a replacement, using the current template when one is configured. Files and other changes made after the original sandbox was created are not restored automatically. Because the durable session still has the same sandbox key, `onSession` does not run again for this replacement. Persist important artifacts outside the sandbox, and do not rely on `onSession` as the only place that applies security-critical configuration.
 
 When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters implement `stop()` for authored runtime calls and `shutdown()` for server teardown. Both stop the underlying compute while keeping the session reattachable from persisted state where the backend supports it; authored `stop()` failures reject, while process-wide shutdown collects and logs failures without blocking teardown.

package/docs/subagents/index.mdx

@@ -5,6 +5,16 @@ description: "Delegate work to root-agent copies or declared specialists with th
 
 eve supports two ways to delegate work: the root-only built-in `agent` tool, which starts or continues a copy of the root agent, and declared subagents, which are specialists with their own directories. Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.
 
+## Completion batching
+
+eve automatically combines adjacent successful completions already queued from
+tasks launched in the same parent turn. Every result is retained, and the parent
+responds to the batch in one turn. No configuration is required.
+
+There is no debounce timer or waiting for unfinished tasks. Failures, input
+requests, explicit updates, user messages, and different task cohorts remain
+separate delivery boundaries.
+
 ## The built-in `agent` tool
 
 The root session receives `agent` by default. The model calls it to delegate a task to a new copy of the root agent or continue an existing copy:

package/docs/tools/overview.mdx

@@ -138,9 +138,11 @@ After the initiating turn accepts background tasks, eve supplies runtime-authore
 cohort and instructs the model to acknowledge that the work started without waiting for results.
 [Schedule](/docs/schedules)-initiated turns are the exception: no user prompted them, so their
 launches keep conditional delivery and send no acknowledgement.
-Later task-triggered parent turns receive fresh state for the same cohort. The model is instructed
-to keep related intermediate results silent while any task remains pending. Once every related
+Later task-triggered parent turns receive fresh state for the same cohort. Once every related
 task is terminal, the state includes their outputs so the model can combine the useful results.
+eve does not instruct the model to stay silent while sibling tasks are pending; a new user
+question can receive an answer while background work continues. [Completion batching](/docs/subagents#completion-batching)
+combines successful results already queued for the parent.
 
 ### Yield and return
 

package/docs/tools/workflows.mdx

@@ -79,8 +79,8 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
   `start`, `getRun`, and `resumeHook` from `workflow/api` belong in steps. Your app does not install
   the SDK; for types, new projects list `eve/workflow-modules` in the tsconfig `types`.
 - In the body, `ctx` has `session`, `callId`, `toolName`, `abortSignal`, `agent`, and `ask`.
-  `getSandbox`, `getSkill`, `getToken`, and `requireAuth` are not part of `WorkflowToolContext`.
-  Read credentials from `process.env` in a step; session-scoped workflow authorization is not yet available.
+  `getToken` and `requireAuth` work inside a `"use step"` helper that receives `ctx` as a direct argument;
+  they throw in the workflow body. `getSandbox` and `getSkill` remain unavailable.
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
   not tools returned from `defineDynamic` resolvers.
 
@@ -154,6 +154,65 @@ Answering resumes the body in either mode.
 Promise or Node.js timer inside a step also does not create a durable workflow suspension; use
 the workflow operations for waits that must survive a restart.
 
+## Authorize inside a step
+
+Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there. User-scoped providers
+resolve as whoever launched this workflow tool, even if another person speaks in the session while it waits.
+The provider declaration and the API request both stay inside the step:
+
+```ts
+import { connect } from "@vercel/connect/eve";
+import type { WorkflowToolContext } from "eve/tools";
+
+async function readRepository(ctx: WorkflowToolContext, repository: string) {
+  "use step";
+  const provider = connect("github/my-agent");
+  const { token } = await ctx.getToken(provider);
+  const response = await fetch(`https://api.github.com/repos/${repository}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (response.status === 401) ctx.requireAuth(provider);
+  if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
+  return response.json();
+}
+```
+
+Connections discovered through `connection_search`, ordinary tools, and workflow steps use the same
+authorization machinery for requester identity, token caching, callback completion, and rejection
+after sign-in. The execution runtime owns the wait: an agent returns to its model after authorization,
+while a workflow retries the interrupted step and continues the authored body.
+
+The workflow body calls `await readRepository(ctx, repository)`.
+
+<Callout type="warning" title="Keep tokens out of step results">
+  Step results enter the workflow's durable history, so do not return the token from the helper.
+  eve's token cache stays inside the step. The step input is recorded too and, after sign-in,
+  carries the provider's callback parameters, such as a one-time authorization code. This matches
+  how agent turns record callbacks. Bearer tokens are never written.
+</Callout>
+
+When sign-in is required, the step attempt ends and the workflow waits on its own callback hook,
+without holding compute. The channel renders the sign-in challenge. After the callback, eve retries
+**the whole interrupted step**, resolves the token, and continues. Previously completed steps are
+not rerun. Resolve auth before other side effects in that step, and make operations before
+`requireAuth` safe to retry. A token rejected immediately after sign-in fails instead of prompting
+again. Provider declarations can be shared imports, but context must be passed directly, not nested
+inside another argument or captured in a closure.
+
+After a successful callback exchange, eve records a completion marker before returning to authored
+code. If that code later fails and the step retries, eve reads the token from the provider instead
+of exchanging the same callback again. The provider must persist the grant or token; the marker
+itself contains no credentials.
+
+A background task becomes `input_required` during sign-in. The callback resumes that task; it does
+not rely on the launching agent turn still being active. Cancelling an authorization wait withdraws
+its callback. Cancellation uses the existing turn or task cancellation path rather than a separate
+authorization completion event.
+
+Background workflow authorization requires a new session after upgrading. In older sessions,
+`ctx.getToken` and `ctx.requireAuth` fail immediately with an instruction to start a new session.
+Blocking workflows and background workflows without auth are unaffected.
+
 ## Ask a human: `ctx.ask`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.52.3",
+  "version": "0.52.5",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -290,6 +290,11 @@
       "import": "./dist/src/public/context/index.js",
       "default": "./dist/src/public/context/index.js"
     },
+    "./internal/workflow-step-execution": {
+      "types": "./dist/src/execution/tools/workflow/step-execution.d.ts",
+      "import": "./dist/src/execution/tools/workflow/step-execution.js",
+      "default": "./dist/src/execution/tools/workflow/step-execution.js"
+    },
     "./internal/programmatic-source-loader": {
       "types": "./dist/src/internal/programmatic-source-loader.d.ts",
       "import": "./dist/src/internal/programmatic-source-loader.js",
@@ -420,6 +425,12 @@
       "types": "./dist/src/setup/index.d.ts",
       "import": "./dist/src/setup/index.js",
       "default": "./dist/src/setup/index.js"
+    },
+    "./self-modification/config": {
+      "eve-source": "./src/self-modification/config.ts",
+      "types": "./dist/src/self-modification/config.d.ts",
+      "import": "./dist/src/self-modification/config.js",
+      "default": "./dist/src/self-modification/config.js"
     }
   },
   "publishConfig": {
@@ -478,6 +489,7 @@
     "chat": "4.34.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
+    "dd-trace": "6.13.0",
     "emulate": "0.6.0",
     "env-runner": "0.1.16",
     "eventsource-parser": "3.1.0",
@@ -507,6 +519,7 @@
     "@opentelemetry/api": "^1.0.0",
     "ai": "^7.0.82",
     "braintrust": "^3.0.0",
+    "dd-trace": "^6.13.0",
     "just-bash": "^3.1.0",
     "microsandbox": "^0.5.0"
   },
@@ -517,6 +530,9 @@
     "braintrust": {
       "optional": true
     },
+    "dd-trace": {
+      "optional": true
+    },
     "just-bash": {
       "optional": true
     },

package/dist/src/self-modification/extension/source-lock.d.ts

@@ -1,2 +0,0 @@
-/** Runs `task` after every previously queued authored-source mutation settles. */
-export declare function withAuthoredSourceLock<T>(task: () => Promise<T>): Promise<T>;

package/dist/src/self-modification/extension/source-lock.js

@@ -1 +0,0 @@
-let queue=Promise.resolve();async function withAuthoredSourceLock(e){let t=queue.then(e,e);return queue=t.catch(()=>void 0),await t}export{withAuthoredSourceLock};