eve 0.61.1 → 0.63.0

package/docs/guides/instrumentation/migration.md

@@ -0,0 +1,97 @@
+---
+title: "Migrate Instrumentation"
+description: "Move a single instrumentation.ts configuration into lifecycle instrumentation and OpenTelemetry destinations."
+url: "/observability/instrumentation-migration"
+---
+
+Replace `agent/instrumentation.ts` with path-named files under
+`agent/instrumentation/`. Remove
+`experimental.instrumentationProviders` from `agent.ts`; instrumentation
+discovery is now always enabled.
+
+## Preserve metadata-only capture
+
+In the removed API, omitted `recordInputs` and `recordOutputs` settings both
+defaulted to `false`. Once an OpenTelemetry destination is present, the new
+default includes content during development and for public conversations.
+
+Add `agent/instrumentation/otel.ts` with an explicit metadata-only policy
+before moving exporters:
+
+```ts title="agent/instrumentation/otel.ts"
+import { otel } from "eve/instrumentation/otel";
+
+export default otel({
+  functionId: "support-agent",
+  traceChannelRequests: true,
+  tracePolicy: () => ({
+    emit: true,
+    recordInputs: false,
+    recordOutputs: false,
+  }),
+});
+```
+
+After verifying each destination's retention and access controls, widen
+`recordInputs` or `recordOutputs` deliberately if needed.
+
+## Move an OpenTelemetry exporter
+
+Move each exporter into its own destination file and replace startup
+`registerOTel(...)` calls with `otelIntegration(...)`. Install `@vercel/otel`
+if the exporter comes from that package:
+
+```bash
+pnpm add @vercel/otel
+```
+
+```ts title="agent/instrumentation/honeycomb.ts"
+import { OTLPHttpProtoTraceExporter } from "@vercel/otel";
+import { otelIntegration } from "eve/instrumentation/otel";
+
+export default otelIntegration({
+  exportPolicy: {
+    span: () => ({ redact: true, inputs: true, outputs: true }),
+  },
+  traceExporter: new OTLPHttpProtoTraceExporter({
+    url: "https://api.honeycomb.io/v1/traces",
+    headers: {
+      "x-honeycomb-team": process.env.HONEYCOMB_API_KEY!,
+    },
+  }),
+});
+```
+
+The destination policy preserves metadata-only export even if the shared
+OpenTelemetry policy is widened later. Add another file for each additional
+destination; eve combines them into one pipeline.
+
+## Move runtime context and lifecycle events
+
+Use this mapping when splitting the old definition:
+
+| `agent/instrumentation.ts` field | New location                                 |
+| -------------------------------- | -------------------------------------------- |
+| `setup` with `registerOTel`      | One `otelIntegration()` file per destination |
+| `functionId`                     | `otel({ functionId })`                       |
+| `recordInputs`, `recordOutputs`  | `otel({ tracePolicy })`                      |
+| `traceChannelRequests`           | `otel({ traceChannelRequests })`             |
+| `events["step.started"]`         | `otelIntegration({ runtimeContext })`        |
+
+Move `events["step.started"]` to the destination that needs those attributes;
+see [Add runtime context](/docs/observability/otel#add-runtime-context). For
+eve lifecycle events, create a separate file with `defineInstrumentation(...)`;
+see
+[Instrumentation](/docs/observability/instrumentation).
+
+## Verify the migration
+
+Run `eve build`. A remaining `agent/instrumentation.ts` fails the build with a
+message directing you to the instrumentation directory.
+
+Before verifying a Vercel deployment, configure trace sampling. A deployed eve
+project needs at least one sampling rule with a rate above 0%; we recommend
+setting the rate to 100%. See
+[Enable tracing on Vercel](/docs/observability/otel#enable-tracing-on-vercel).
+
+Then run the agent and verify each destination independently.

package/docs/guides/instrumentation/otel.mdx

@@ -1,25 +1,22 @@
 ---
 title: "OpenTelemetry"
-description: "Configure OpenTelemetry destinations, content capture, and managed exports with Instrumentation Providers."
+description: "Configure OpenTelemetry destinations, content capture, and managed exports."
 url: "/observability/otel"
 ---
 
-<Callout type="warning" title="Experimental">
-  This API is experimental and may change without a deprecation period.
-</Callout>
-
-Use the built-in APIs from `eve/instrumentation/otel` to configure eve's
-OpenTelemetry pipeline. This page requires the experimental
-[Instrumentation Providers](./instrumentation-providers) layout.
+eve configures its built-in OpenTelemetry destinations automatically.
+`eve dev` records local traces, and preview and production deployments export
+to Vercel Agent Runs by default. You do not need `otel()` or
+`otelIntegration()` to use these defaults.
 
 ## Configure OpenTelemetry
 
-OpenTelemetry configuration has two parts:
+`otel()` and `otelIntegration()` are optional:
 
-- `otel()` declares process-wide settings such as the resource, sampler,
-  propagators, and trace capture policy. Declare it at most once.
-- `otelIntegration()` adds one destination. Declare one file per exporter or
-  processor chain.
+- Use `otel()` only when you need process-wide settings such as the resource,
+  sampler, propagators, or trace capture policy. Declare it at most once.
+- Use `otelIntegration()` only when adding a third-party OpenTelemetry
+  destination. Declare one file per exporter or processor chain.
 
 Add `agent/instrumentation/otel.ts` when you need process-wide settings or
 want to control the content eve writes to OpenTelemetry spans:
@@ -39,26 +36,67 @@ export default otel({
 
 The OpenTelemetry `tracePolicy` is a capture ceiling shared by every OTel
 destination. A destination cannot restore content excluded by this policy. It
-does not affect lifecycle-event providers created with `defineInstrumentation()`.
+does not affect lifecycle instrumentation created with `defineInstrumentation()`.
 See [Audience](../channels/overview#audience) for how channels classify the
 conversation passed to this policy.
 
 ## Add an OpenTelemetry destination
 
-Most agents only need a destination:
+Use this section when sending traces to a third-party destination. Install
+`@vercel/otel` before using its exporters:
+
+```bash
+pnpm add @vercel/otel
+```
 
-```ts title="agent/instrumentation/braintrust.ts"
-import { BraintrustExporter } from "@braintrust/otel";
+```ts title="agent/instrumentation/honeycomb.ts"
+import { OTLPHttpProtoTraceExporter } from "@vercel/otel";
 import { otelIntegration } from "eve/instrumentation/otel";
 
 export default otelIntegration({
-  traceExporter: new BraintrustExporter({ filterAISpans: true }),
+  exportPolicy: {
+    span: () => ({ redact: true, inputs: true, outputs: true }),
+  },
+  traceExporter: new OTLPHttpProtoTraceExporter({
+    url: "https://api.honeycomb.io/v1/traces",
+    headers: {
+      "x-honeycomb-team": process.env.HONEYCOMB_API_KEY!,
+    },
+  }),
 });
 ```
 
 Pass `spanProcessors` to `otelIntegration()` when a custom destination needs
-filtering or transformation. `exportPolicy` is for the built-in
-`localTraces()` and `agentRuns()` destinations below.
+filtering or transformation. The example's `exportPolicy` preserves span
+metadata while removing inputs and outputs from this destination.
+
+## Add runtime context
+
+Use `runtimeContext` to add JSON values to AI SDK spans for each model attempt.
+For typed channel metadata, import the channel definition and narrow with
+`isChannel`:
+
+```ts title="agent/instrumentation/support.ts"
+import { isChannel } from "eve/instrumentation";
+import { otelIntegration } from "eve/instrumentation/otel";
+
+import supportChannel from "../channels/support";
+
+export default otelIntegration({
+  runtimeContext(input) {
+    if (!isChannel(input.channel, supportChannel)) return undefined;
+
+    return {
+      "support.channel_id": input.channel.metadata.channelId ?? "",
+      "support.user_id": input.channel.metadata.triggeringUserId ?? "",
+    };
+  },
+});
+```
+
+The resolver receives the channel, session, final model input, step, and turn.
+Keys beginning with `eve.` are reserved. Content excluded by
+`otel({ tracePolicy })` is not available to the resolver.
 
 ## Trace topology
 
@@ -82,15 +120,13 @@ destination's span-search surface.
 
 ## Manage built-in destinations
 
-The provider layout has two environment-specific defaults:
+Instrumentation has two environment-specific defaults.
 
-- `local` records local traces during `eve dev`.
-- `agent-runs` exports to Vercel Agent Runs in preview and production
-  deployments.
+### Local traces
 
-Omitting these files preserves the defaults. Reconfigure a destination by
-exporting `localTraces()` or `agentRuns()` from the matching file. Disable one
-explicitly:
+`eve dev` records local traces by default. Omitting
+`agent/instrumentation/local.ts` preserves that default. Export
+`localTraces(...)` from that file to reconfigure it, or disable it explicitly:
 
 ```ts title="agent/instrumentation/local.ts"
 import { disableInstrumentation } from "eve/instrumentation";
@@ -98,11 +134,37 @@ import { disableInstrumentation } from "eve/instrumentation";
 export default disableInstrumentation();
 ```
 
-## Filter a managed destination
+### Vercel Agent Runs
+
+Preview and production deployments export to Vercel Agent Runs by default.
+Omitting `agent/instrumentation/agent-runs.ts` preserves that default. Export
+`agentRuns(...)` from that file to reconfigure it, or export
+`disableInstrumentation()` to disable it.
+
+## Enable tracing on Vercel
+
+A deployed eve project needs at least one
+[sampling rule with a rate above 0%](https://vercel.com/docs/tracing/always-on-tracing#enable-always-on-tracing)
+before Vercel collects traces. We recommend setting the rate to **100%** for
+eve projects so every matching request is traced.
+
+Select your team and project, then open
+[**Settings → Tracing**](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Ftracing&title=Go+to+Tracing+settings):
+
+1. Select **Add Sampling Rule**.
+2. Choose **All Environments**, **Production**, or **Preview**.
+3. Set **Rate** to `100%`.
+4. Select **Save**.
+
+Tracing starts as soon as you save the rule. You can also manage sampling
+rules with [`vercel traces config`](https://vercel.com/docs/cli/traces#manage-trace-sampling-rules).
+The CLI accepts rates from 1 to 100%; add a 0% rule from the dashboard.
+
+## Filter a destination
 
-`localTraces()` and `agentRuns()` accept one `exportPolicy` object or an array
-applied in order. Each policy filters spans and attributes before that
-destination's processors receive them:
+`otelIntegration()`, `localTraces()`, and `agentRuns()` accept one
+`exportPolicy` object or an array applied in order. Each policy filters spans
+and attributes before that destination's processors receive them:
 
 ```ts title="agent/instrumentation/agent-runs.ts"
 import { agentRuns } from "eve/instrumentation/otel";
@@ -153,6 +215,6 @@ before it.
 
 ## What to read next
 
-- [Instrumentation Providers](./instrumentation-providers): add lifecycle-event providers.
-- [Instrumentation](../observability/instrumentation): configure the current single-file API.
+- [Instrumentation](/docs/observability/instrumentation): handle eve lifecycle events.
+- [Migrate instrumentation](/docs/observability/instrumentation-migration): replace `agent/instrumentation.ts`.
 - [Local development](../guides/dev-tui): inspect local traces in the TUI.

package/docs/install-integrations.mdx

@@ -23,7 +23,7 @@ Web Chat installs a project-level Next.js application. It cannot be added to an
 
 If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search <query>`.
 
-Extensions may create a mount under `agent/extensions/`. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation providers write `agent/instrumentation.ts`; because an agent has one instrumentation file, compose multiple exporters there by hand. Configure generated files and required environment variables before running your agent.
+Extensions may create a mount under `agent/extensions/`. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can install and configure multiple exporters independently. Configure generated files and required environment variables before running your agent.
 
 When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the item's declared flows from the beginning.
 

package/docs/reference/agent-files.md

@@ -13,7 +13,7 @@ In a single-agent project, the agent directory is `agent/`. In an eve agent work
 agent/
 ├── agent.ts
 ├── instructions.md
-├── instrumentation.ts
+├── instrumentation/
 ├── channels/
 ├── connections/
 ├── extensions/
@@ -50,7 +50,7 @@ Paths below are relative to the agent directory. Root agents can use every path;
 | ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `agent.ts`                                              | Runtime config                            | Yes                    | Model, model options, compaction, build, and experimental settings. See [Agents](/docs/agent-config).                                   |
 | `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Yes                    | A flat file or directory of `.md` and `.ts` files. Required on the root, optional on subagents. See [Instructions](/docs/instructions). |
-| `instrumentation.ts`                                    | Telemetry config                          | No                     | Auto-discovered and run before agent code. See [Instrumentation](/docs/observability/instrumentation).                                  |
+| `instrumentation/`                                      | Telemetry providers and destinations      | No                     | One path-named provider per file. See [Instrumentation](/docs/observability/instrumentation).                                           |
 | `channels/`                                             | HTTP and messaging entry points           | No                     | See [Channels](/docs/channels/overview).                                                                                                |
 | `connections/`                                          | External MCP and OpenAPI services         | Yes                    | Static files define path-named connections; dynamic sources can resolve caller-specific connections.                                    |
 | `extensions/`                                           | Mounted reusable capabilities             | Yes                    | File or directory mounts. See [Extensions](/docs/extensions).                                                                           |

package/docs/reference/cli.md

@@ -272,7 +272,7 @@ Local dev records the last ready URL per resolved app root in `.eve/dev-server-s
 
 Local dev keeps immutable runtime generations under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. Each generation contains the compiled authored module graph and runtime resources rather than a recursive copy of the app or workspace. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; `/new` terminally retires that session before clearing the transcript, and the next prompt starts a fresh session with a new session-scoped sandbox on first sandbox use. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned.
 
-When no authored `agent/instrumentation.ts` exists, local dev also records traces under `.eve/traces/`, and bounds that store by age, size, and a keep-newest floor. Configure it with `EVE_TRACES*` in `.env.local`; see [`eve traces`](#retention) for the rules and defaults.
+Local development records traces under `.eve/traces/` by default and bounds that store by age, size, and a keep-newest floor. Configure it with `EVE_TRACES*` in `.env.local`, or disable the destination with `agent/instrumentation/local.ts`; see [`eve traces`](#retention) for the rules and defaults.
 
 ## `eve logs`
 

package/docs/reference/typescript-api.md

@@ -49,7 +49,8 @@ export default defineTool({
 | `defineSchedule`                                      | `eve/schedules`                                                         | `agent/schedules/<name>.ts`                                                            | [Schedules](../schedules)                              |
 | `defineState`                                         | `eve/context`                                                           | tools, hooks, lifecycle                                                                | [Session context](../guides/session-context)           |
 | `defineSandbox`                                       | `eve/sandbox`                                                           | `agent/sandbox.ts`                                                                     | [Sandbox](../sandbox)                                  |
-| `defineInstrumentation`                               | `eve/instrumentation`                                                   | `agent/instrumentation.ts`                                                             | [Instrumentation](../observability/instrumentation)    |
+| `defineInstrumentation`                               | `eve/instrumentation`                                                   | `agent/instrumentation/<name>.ts`                                                      | [Instrumentation](../observability/instrumentation)    |
+| `otel`, `otelIntegration`                             | `eve/instrumentation/otel`                                              | `agent/instrumentation/<destination>.ts`                                               | [OpenTelemetry](../observability/otel)                 |
 | `defineRemoteAgent`                                   | `eve`                                                                   | `agent/subagents/<id>/agent.ts`                                                        | [Remote agents](../guides/remote-agents)               |
 | `defineEval`                                          | `eve/evals`                                                             | `evals/*.eval.ts`                                                                      | [Evals](../evals/overview)                             |
 | `defineEvalConfig`                                    | `eve/evals`                                                             | `evals/evals.config.ts`                                                                | [Evals](../evals/overview)                             |
@@ -136,7 +137,8 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `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/instrumentation`                                                       | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
+| `eve/instrumentation/otel`                                                  | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
 | `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
 | [`eve/models`](../guides/evaluate)                                          | Automatic model selection with `auto`                                                                                          |
 | `eve/models/openai`                                                         | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |

package/docs/subagents/index.mdx

@@ -9,15 +9,16 @@ eve supports two ways to delegate work: the root-only built-in `agent` tool, whi
 
 Overlapping background work owned by a session forms a cohort. Tasks launched in
 later user turns join the open cohort while earlier work is still pending or its
-successful results await delivery. eve holds successful completion notifications
-until every task in that cohort has completed, failed, or been cancelled, then
-delivers the successful results together in one parent turn. Partial completions
-do not invoke the parent model. Work started after the cohort settles forms a new
-cohort. No configuration or debounce timer is required.
-
-User messages, input requests, authorization events, failures, and cancellation
-are handled without waiting for the cohort. Child lifecycle events are processed
-before completion delivery so usage accounting and handle cleanup stay ordered.
+terminal results await delivery. eve holds completion, failure, and cancellation
+notifications until every task in that cohort is terminal, then delivers all outcomes
+together in one parent turn. This includes cohorts where every task failed or was
+cancelled. Partial settlements do not invoke the parent model. Work started after the
+cohort settles forms a new cohort. No configuration or debounce timer is required.
+
+User messages, input requests, and authorization events are handled without waiting
+for the cohort. Failure and cancellation update task lifecycle state immediately;
+their automatic conversational report waits for the cohort. Child lifecycle events
+are processed before terminal delivery so usage accounting and handle cleanup stay ordered.
 To follow work in progress, subscribe to the child session streams.
 
 ## The built-in `agent` tool
@@ -234,6 +235,8 @@ Do not rely on subagent delegation by itself as an approval boundary. Put sensit
 
 Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events `subagent.called` and `subagent.completed`, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
 
+Both blocking and background invocations emit `subagent.called` after dispatch and `subagent.completed` after the parent records successful completion. Completion carries the actual output and identifies the same invocation by `callId`; the child session can remain available for reuse. A background working receipt is returned as an `action.result` tool output and does not emit completion. Background completion events do not wait for the cohort report. Failure and cancellation are not successful completion; task notifications retain those outcomes.
+
 Channels with activity reporting attribute the backing agent's tool activity to its background task. Local and remote subagents share the task's progress item rather than adding a separate agent item. Continuing or steering a child with `agentId` attaches its new activity to the new task; the previous task keeps its completed or cancelled status. This applies to the built-in `agent` and declared subagent tools, not to child invocations inside custom workflow tools. Activity reporting is best-effort and does not change task execution or result delivery.
 
 A background task that was already admitted survives cancellation of the turn that started it; background work that has not yet been admitted is rejected with the cancelled step. Use `task_cancel` to stop an admitted task. Cancellation delivers the task's final notification to an active parent even if the task must be stopped forcibly. Parent-session finalization cancels remaining live tasks.

package/docs/tools/overview.mdx

@@ -121,33 +121,25 @@ receive only the projected text.
 
 ### Background execution
 
-Background execution controls how a tool delivers its result to the parent agent. Durable
-suspension controls whether the executor can pause at a workflow wait and release compute.
-These are independent choices: `execution: "background"` selects the task lifecycle;
-`defineWorkflowTool` with a leading `"use workflow"` directive enables durable suspension.
-
-| Definition                                       | Durable waits inside `execute`                                  | Result delivered to the model                                          |
-| ------------------------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `defineTool`                                     | No; the executor runs inside the initiating step.               | Executor output after it finishes.                                     |
-| `defineTool` + `execution: "background"`         | No; the initiating step still waits for the executor to finish. | Task receipt, followed by task notifications.                          |
-| `defineWorkflowTool`                             | Yes; the tool call waits while the workflow can suspend.        | Workflow output after it finishes.                                     |
-| `defineWorkflowTool` + `execution: "background"` | Yes; the workflow body can outlive the initiating step.         | Task receipt before the body finishes, followed by task notifications. |
-
-A background tool receives a third `task` argument. Its tool result is the receipt
-`{ status: "working", taskId }`; its eventual output belongs to the task. Use a background
-workflow tool when the conversation should continue while the body waits for a person,
-webhook, or timer. Setting `execution: "background"` on an ordinary tool does not move its
-executor into a separate workflow or make an ordinary Promise a durable wait.
+Background execution controls how a workflow tool delivers its result to the parent agent.
+Set `execution: "background"` on `defineWorkflowTool`; ordinary `defineTool` calls always finish
+inside the initiating step.
+
+| Definition                                       | Durable waits inside `execute`                           | Result delivered to the model                                                                          |
+| ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `defineTool`                                     | No; the executor runs inside the initiating step.        | Executor output after it finishes.                                                                     |
+| `defineWorkflowTool`                             | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes.                                                                     |
+| `defineWorkflowTool` + `execution: "background"` | Yes; the workflow body can outlive the initiating step.  | Task receipt before the body finishes; one combined report after all tasks in its cohort are terminal. |
+
+A background workflow tool's result is the receipt `{ status: "working", taskId }`; its eventual
+output belongs to the task. Use this mode when the conversation should continue while the body
+waits for a person, webhook, or timer.
 
 For background tools, `outputSchema` and `toModelOutput` describe the fixed receipt. The body's
 return value is available through the completed task's output.
 
-`task.delegated()` has been removed. Move external work into a `defineWorkflowTool` executor and
-return its result when it finishes. Rebuild extensions using the removed API after migrating.
-
-`yield task.postMessage(message)` is the only yield that requests a parent-agent turn. Calling
-`task.postMessage` only constructs the message descriptor; you must yield it to send it.
-In a workflow body, keep values needed after a wait in local variables; workflow replay
+The `TaskExec` argument and `task.postMessage` have been removed. Return the terminal result;
+background yields are consumed without publishing progress or retaining a task-progress stream. In a workflow body, keep values needed after a wait in local variables; workflow replay
 reconstructs them across durable waits.
 Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an answer from the human.
 Background tools are a normal execution mode and need no root-agent flag. Built-in, declared local,
@@ -158,10 +150,11 @@ cohort and instructs the model to acknowledge that the work started without wait
 [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. Once every related
-task is terminal, the state includes their outputs so the model can combine the useful results.
+task is terminal, one automatic parent turn receives the cohort's completed, failed, and cancelled
+outcomes 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.
+combines terminal results already queued for the parent.
 
 ### Yield and return
 
@@ -169,19 +162,18 @@ combines successful results already queued for the parent.
 It does not by itself create a durable wait for a person, timer, or external event. The value's
 meaning depends on the tool's execution mode:
 
-| Executor                                         | Ordinary `yield value`                                                                  | Final output                                                                                                      |
-| ------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `defineTool`, default execution                  | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                        |
-| `defineWorkflowTool`, default execution          | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`.       |
-| Either definition with `execution: "background"` | Stream-only task progress; does not request a parent-agent turn.                        | Explicit return value becomes the task output; no return completes with `null`. The last yield is not a fallback. |
+| Executor                                            | Ordinary `yield value`                                                                  | Final output                                                                                                      |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `defineTool`, default execution                     | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                        |
+| `defineWorkflowTool`, default execution             | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`.       |
+| `defineWorkflowTool` with `execution: "background"` | Consumed without publishing progress or requesting a parent-agent turn.                 | Explicit return value becomes the task output; no return completes with `null`. The last yield is not a fallback. |
 
-For either kind of background tool, `yield task.postMessage(message)` sends a message to the
-parent agent while the task remains open. Return completes the task; throw fails it. These
-notifications are separate from the original tool call's receipt.
+For a background workflow tool, return completes the task and throw fails it. The automatic
+cohort report is separate from the original tool call's receipt.
 
 Progress snapshots do not enter model history as intermediate tool results. For a default
 executor, the final output selected by the rules above becomes the tool result. For a background
-executor, task messages and completion notifications provide input to later parent-agent turns.
+executor, the terminal cohort report provides input to a later parent-agent turn.
 
 ### Workflows as tools
 

package/docs/tools/workflows.mdx

@@ -178,8 +178,7 @@ agent should receive a tool result:
 
 Use default execution when the model needs the answer to continue. Use background execution when
 the conversation should continue while the task is pending. Background tools need no root-agent
-flag. Ordinary `defineTool` also accepts `execution: "background"`, but its executor still runs
-inside the initiating step and cannot suspend at workflow waits. See the
+flag. `defineTool` does not accept background execution. See the
 [tool execution comparison](/docs/tools#background-execution).
 
 ### How suspension works
@@ -429,23 +428,23 @@ This pattern controls specialist selection, not whether the parent model delegat
 
 ## Report progress: `yield`
 
-A workflow body may be an async generator. Ordinary yields report progress in both execution
-modes. After processing a yield, eve advances the generator; use an awaited workflow operation
+A workflow body may be an async generator. In default execution, yields report progress.
+Background execution consumes yielded values without publishing them or retaining a task-progress
+stream. After processing a yield, eve advances the generator; use an awaited workflow operation
 when the body needs to suspend.
 
-| Operation                         | Default execution                                                 | `execution: "background"`                                              |
-| --------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `yield value`                     | Emits an `action.partial` snapshot for the pending tool call.     | Emits stream-only task progress; does not request a parent-agent turn. |
-| `yield task.postMessage(message)` | Unavailable; there is no `task` argument.                         | Sends a message requesting a parent-agent turn; the task stays open.   |
-| `return value`                    | Settles the tool call with its output.                            | Completes the task and delivers its output in a later notification.    |
-| No return value                   | Uses the last yield as output, or `null` if there were no yields. | Completes with `null`; yielded progress is not the task output.        |
+| Operation       | Default execution                                                 | `execution: "background"`                                                         |
+| --------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `yield value`   | Emits an `action.partial` snapshot for the pending tool call.     | Consumes the value without publishing progress or requesting a parent-agent turn. |
+| `return value`  | Settles the tool call with its output.                            | Completes the task and contributes to its cohort's terminal report.               |
+| No return value | Uses the last yield as output, or `null` if there were no yields. | Completes with `null`; yielded progress is not the task output.                   |
 
 For default execution, an explicit `return null` also falls back to the last yield. Prefer an
 explicit object return when progress snapshots and the final result have different shapes.
 Progress snapshots are last-write-wins by tool call id and do not enter model history as
 intermediate tool results. A snapshot used as the final output does enter history as the tool result.
 
-This background workflow reports progress, sends the parent one message, and then suspends:
+This background workflow consumes an intermediate yield, then suspends until its timer expires:
 
 ```ts title="agent/tools/remind_with_progress.ts"
 import { defineWorkflowTool } from "eve/tools";
@@ -453,25 +452,22 @@ import { sleep } from "workflow";
 import { z } from "zod";
 
 export default defineWorkflowTool({
-  description: "Schedule a reminder and report progress before waiting.",
+  description: "Schedule a reminder.",
   inputSchema: z.object({ note: z.string(), delay: z.string() }),
   execution: "background",
-  async *execute({ note, delay }, ctx, task) {
+  async *execute({ note, delay }) {
     "use workflow";
-    yield { status: "preparing reminder" }; // Stream-only progress.
-    yield task.postMessage(`Reminder scheduled for ${delay}.`); // Parent-agent message.
+    yield { status: "preparing reminder" }; // Consumed without publishing progress in background mode.
     await sleep(delay); // Durable suspension while the timer is pending.
     return { reminder: note }; // Task completion notification.
   },
 });
 ```
 
-Calling `task.postMessage` constructs a descriptor; yielding it sends the message. It does not
-wait for a reply. Use [`ctx.ask`](#ask-a-human-ctxask) when the workflow needs a human answer.
-Removing `execution: "background"` requires removing the `task` argument and message yield; the
-ordinary progress yield and `await sleep(delay)` still work, but the model waits for the final
-reminder as the tool result. See [yield and return](/docs/tools#yield-and-return) for the different
-final-output rules of ordinary `defineTool` generators.
+Use [`ctx.ask`](#ask-a-human-ctxask) when the workflow needs a human answer. Removing
+`execution: "background"` makes the yield visible as progress and keeps the durable sleep; the model
+waits for the final reminder as the tool result. See [yield and return](/docs/tools#yield-and-return) for the
+final-output rules.
 
 ## Cancel and clean up: `ctx.abortSignal`
 
@@ -497,6 +493,11 @@ as cancelled whether or not it did. A body parked on a hook or a `sleep` does no
 it is abandoned when the grace period ends. Steps that received the signal are how you clean up
 first.
 
+The caller waits up to 35 seconds for a cooperatively cancelled run to settle before forcing it
+to stop. This includes time for the run to publish its outcome after body cleanup. A background
+task records its cancelled status before cleanup finishes, so that status alone does not mean
+its work has stopped.
+
 ## Workflow tool examples
 
 ### Approve with a deadline and an escalation
@@ -607,8 +608,10 @@ it.
 ## Semantics
 
 One call, one result. A waiting tool's call resolves once, with the return value, the error, or a
-cancellation. A background tool's call resolves once, with the receipt; everything after arrives as
-separate session input.
+cancellation. A background tool's call resolves once, with the receipt. Its terminal outcome arrives
+in one automatic report after every task in its cohort is terminal. A cohort includes overlapping
+background work in the same session, including tasks launched in later user turns while earlier
+work remains open.
 
 While a waiting tool runs, the turn is parked. A `queue` message waits for it. A `steer` message
 cancels the turn, which cancels the run, which withdraws its requests. Input responses never steer.
@@ -616,8 +619,12 @@ cancels the turn, which cancels the run, which withdraws its requests. Input res
 Background runs belong to the session. They survive turn completion and cancellation, appear in the
 session's task index, can be cancelled with `task_cancel`, and are cancelled when the session ends.
 
+The parent session records each background task's outcome when it processes the child's notification.
+The first terminal outcome it records is final: a late child result cannot replace a recorded
+cancellation. Task completion does not require the wrapper workflow to have exited.
+
 Errors follow the SDK. A thrown error in a step retries per the step's policy; `FatalError` does
-not. An error that escapes the body fails the run.
+not. An error that escapes the body fails the tool invocation.
 
 Starting a waiting workflow tool can also be retried. If dispatch is interrupted after starting a
 run, its retry starts another run, and both may execute. The parent tracks the run returned by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.61.1",
+  "version": "0.63.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -505,7 +505,6 @@
     "@workflow/world-local": "5.0.0-beta.45",
     "@workflow/world-vercel": "5.0.0-beta.48",
     "ai": "^7.0.105",
-    "autoevals": "0.0.132",
     "chat": "4.34.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",