eve 0.52.2 → 0.52.4

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-1NAM6ftx.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-BR8EpIOX.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-1NAM6ftx.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-BR8EpIOX.js";
 
 export { useEveAgent };

package/docs/concepts/default-harness.md

@@ -18,6 +18,12 @@ export default defineAgent({
 });
 ```
 
+Before summarizing, eve tries to shorten oversized tool results in older history.
+It checks whether that reduction is sufficient using the last provider-reported
+input token count plus an estimate of new messages. A smaller character estimate
+alone cannot satisfy compaction triggered by a higher provider count. If trimming
+cannot free enough space, eve summarizes the older history.
+
 Compaction also preserves the framework's own tool state automatically. It resets read-before-write tracking (so a write afterward re-reads the file whose read evidence was summarized away) and re-injects the active todo list, so the model keeps its task list across the summary. There is no per-tool hook to configure.
 
 First-class [memory](../memory) participates in a separate lifecycle. eve asks

package/docs/concepts/sessions-runs-and-streaming.md

@@ -95,6 +95,8 @@ Note: consider the privacy, confidentiality, and user-experience implications fo
 
 `message.completed` can fire more than once in a turn: the agent often emits interim assistant text before a tool call. To tell tool-call narration from a terminal reply, check `message.completed.data.finishReason`. `step.completed.data.finishReason` mirrors the step outcome, and usage lives on `step.completed`.
 
+When a task explicitly requires conditional delivery and there is nothing new to report, the agent can finish with exactly `<eve-empty-delivery/>`. eve emits `message.completed` with `message: null` for that intentional silence. The marker must be the entire response, apart from surrounding whitespace; the HTML-escaped form `&lt;eve-empty-delivery/&gt;` is also accepted. A response that quotes the marker in prose or code is delivered normally.
+
 A delegated subagent publishes progress on its own child-session stream. The parent emits `subagent.called` with a `childSessionId`, which a client uses to attach. `subagent.completed` carries a working task receipt after admission; later updates and outcomes arrive as task-triggered `message.received` notifications.
 
 `step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, but discards incomplete assistant output and unfinished tool state. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`).
@@ -119,6 +121,10 @@ Alongside `type` and `data`, every event carries a `meta` envelope:
 
 - **`meta.id`** uniquely identifies the event. It is an `evt_`-prefixed [ULID](https://github.com/ulid/spec): a millisecond timestamp followed by random bits, so ids are broadly time-ordered.
 - **`meta.at`** is the ISO-8601 time the event was emitted.
+- **`meta.deliveryIds`**, when present, identifies the accepted messages that own
+  the turn. `POST /eve/v1/session/:sessionId` returns its `deliveryId`, allowing
+  clients to skip earlier turns when resuming from an old cursor. Coalesced
+  messages share the same turn events.
 
 `meta.id` is stable. eve mints it once, when the event is written to the durable stream, and stores it with the event. Reconnecting from a cursor, rewinding to `startIndex=0`, or replaying a finished session all return the same id for the same event.
 

package/docs/connections/overview.mdx

@@ -200,7 +200,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-`"linear/myagent"` is the UID you chose when registering the Connect client. `connect("linear/myagent")` is shorthand for a user-scoped interactive OAuth connection: eve resolves a token for the active user before each tool call, emits `authorization.required` when that user has not authorized yet, and resumes the parked turn after the callback completes.
+Use the connector UID returned by `vercel connect create`; the display name passed to `--name` is not the UID. `connect("linear/myagent")` is shorthand for a user-scoped interactive OAuth connection: eve resolves a token for the active user before each tool call, emits `authorization.required` when that user has not authorized yet, and resumes the parked turn after the callback completes.
 
 When a local subagent needs interactive authorization, eve surfaces the authorization lifecycle on the root session's channel, including through nested subagent chains. The challenge still points to the child session's callback, so completing it resumes the child directly while the parent continues waiting for its result.
 

package/docs/evals/reporters.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Reporters"
-description: "Ship eval results to Braintrust experiments or JUnit XML. eve runs and scores everything itself."
+description: "Ship eval results to Braintrust, Datadog, or JUnit XML. eve runs and scores everything itself."
 ---
 
 eve runs and grades everything itself; reporters ship the results out. The CLI prints a console summary by default (one line per eval, with failed assertions and their messages), and reporters from `eve/evals/reporters` add destinations on top.
@@ -44,6 +44,25 @@ A reporter instance observes the evals that reference it. Share one instance acr
 
 Braintrust needs its SDK installed in the app and credentials in the environment: install the `braintrust` package (`npm install braintrust`) and set `BRAINTRUST_API_KEY`. Pass `--skip-report` to run the eval without shipping results, which also suppresses config reporters and is useful locally when iterating.
 
+## Datadog
+
+`Datadog(...)` uploads eval assertion scores to a Datadog LLM Observability Experiment. Put one instance in the config so it covers the whole run:
+
+```ts title="evals/evals.config.ts"
+import { defineEvalConfig } from "eve/evals";
+import { Datadog } from "eve/evals/reporters";
+
+export default defineEvalConfig({
+  reporters: [Datadog({ projectName: "weather-agent" })],
+});
+```
+
+The reporter creates one Datadog Experiment, submits one synthetic experiment span per completed eve eval, associates that eval's assertion scores as experiment metrics, and prints the Datadog Experiment URL after the run completes. Without input recording, the external Experiment uses a placeholder dataset and spans are submitted as evals finish. With `recordInputs: true`, the reporter instead creates and pushes a versioned Datadog dataset after the evals finish, adds one record per eval, starts the Experiment against that dataset version, passes each dataset record id to its corresponding experiment span, and prints both Dataset and Experiment URLs. Buffering is necessary because an imperative eval's first `t.send(...)` input is only known after that eval executes. `dd-trace` generates dataset record, experiment trace, and experiment span identifiers; the reporter does not mutate or link the agent runtime's OpenTelemetry spans.
+
+Assertion metrics use descriptive assertion names by default: characters outside letters, numbers, underscores, and hyphens are normalized to underscores, gate labels receive a `gate_` prefix, and repeated or reserved labels receive numeric suffixes. For example, `succeeded` becomes `gate_succeeded` and `calledTool(get_stock_quote)` becomes `gate_calledTool_get_stock_quote`. Authors can use `.label("stable name")` on an assertion handle to choose a stable metric name. Because assertion names can contain authored expectations, review them before exporting sensitive evals. Pass `recordAssertionDetails: true` only when the destination is also approved for raw assertion-name tags and failed assertion messages in row metadata.
+
+Datadog needs `dd-trace` installed in the app and Datadog credentials in the environment. The reporter is tested against `dd-trace@6.13.0`; install it with `npm install dd-trace@6.13.0` and set `DD_API_KEY`, `DD_APP_KEY`, and `DD_SITE` as appropriate. By default, the reporter records assertion scores, eval metadata, and the target URL origin only. Pass `recordInputs: true`, `recordOutputs: true`, `recordExpectedOutputs: true`, or `recordErrors: true` if your destination is approved for eval prompts, outputs, authored expectations, or execution error messages. `recordInputs` stores the eval input in both the linked dataset record and experiment span. Input is read from the eval's first `t.send(...)` message, falling back to the eval description when no message event is available. When `recordExpectedOutputs` is enabled, expected output is read from eval `metadata.expectedOutput`, `metadata.expected`, or `metadata.expected_output` and stored in both the dataset record and experiment span; when no expected output is authored, the input-only dataset record is still valid. Those expected-output keys are excluded from the general metadata payload. Target URL credentials, paths, query parameters, and fragments are never reported.
+
 ## JUnit
 
 `JUnit({ filePath })` writes JUnit XML for CI annotations. The `--junit <path>` CLI flag does the same thing without touching the eval file, usually the better fit because CI owns the output path, not the eval:

package/docs/guides/client/continuations.mdx

@@ -52,6 +52,17 @@ console.log((await response.result()).message);
 `attach()` performs no request. Every later operation targets exactly
 `saved.sessionId`; it never follows or creates a replacement.
 
+`send()` correlates its response with the message accepted by the server. If the
+saved cursor is behind, it skips earlier turns and advances past them before
+collecting the new result, including when another turn is active or queued. You
+do not need to drain the stream before sending. Upgrade the server alongside the
+client: a server that omits the accepted delivery identity causes `send()` to
+throw instead of returning an ambiguous result.
+
+If a configured reconnect limit ends the stream before the accepted turn reaches
+a boundary, collecting its response throws. A partial stream is not a completed
+result.
+
 ## Waiting, completed, and reset sessions
 
 A session that emits `session.waiting` accepts another message through the same

package/docs/guides/dynamic-capabilities.md

@@ -257,11 +257,11 @@ Call expressions such as `execute: makeExecutor()` are not transformed. Put the
 
 ### Identity and redeploys
 
-A parked call binds to its callback by **tool name and phase** — the same identity a static tool uses — never by source position. This gives dynamic tools static-tool semantics across deploys:
+A parked call binds to its callback within its session, lifecycle scope, and resolver entry. Another session or scope can expose the same tool name without replacing that binding. Callback identity does not depend on source position:
 
-- Editing a callback body (or anything else that does not change tool names) is safe: replaying a parked call runs the latest deployed code with the closure values snapshotted when the call was made.
-- If a persisted callback has no registered implementation (fresh process after a crash, or after a redeploy), eve re-runs `session.started` resolvers once to rebind it, then replays.
-- If the tool no longer exists under that name, replay fails closed with an explicit error instead of invoking something else. Ordinary turn-scoped and step-scoped tools are not rebound; a parked call to a missing one errors. Framework-provided resolvers such as memory provider-tool wrappers opt into the same generic missing-callback rebind while preserving their locked scope.
+- Editing a callback body while keeping its resolver entry and tool names is safe: replaying a parked call runs the latest deployed code with the closure values snapshotted when the call was made.
+- If a persisted session-scoped callback has no registered implementation (a fresh process, a redeploy, or an expired in-process binding), eve re-runs `session.started` resolvers once to rebind it, then replays.
+- If the owning resolver no longer returns that tool, replay fails closed with an explicit error instead of invoking something else. Ordinary turn-scoped and step-scoped tools are not rebound; a parked call to a missing one errors. Framework-provided resolvers such as memory provider-tool wrappers opt into the same generic missing-callback rebind while preserving their locked scope.
 
 ### Naming
 

package/docs/guides/hooks.md

@@ -176,7 +176,7 @@ Hooks always run after the event is durably recorded, so if a hook throws, the s
 
 ## What happens when a hook throws
 
-A thrown handler propagates through the emit composer and surfaces as `turn.failed`. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. eve treats a thrown hook as a real failure.
+A thrown handler propagates through the emit composer and surfaces as `turn.failed`. In a conversation session, this includes handlers for `turn.started` and the first `step.started` of a model call: the failed turn ends with `session.waiting`, and the next message can start another turn. Task-mode boundary failures remain terminal. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. eve treats a thrown hook as a real failure.
 
 ## Subagent isolation
 

package/docs/guides/instrumentation.md

@@ -97,6 +97,45 @@ retry behavior. Best-effort activity delivery keeps its single
 `[eve:execution.activity-submit] activity sink request failed` warning and does
 not mark the active span as failed.
 
+## Exported span names and outcomes
+
+The built-in OpenTelemetry provider preserves each span's OTel name and adds
+`operation.name` and `resource.name` for Datadog's operation/resource mapping:
+
+| OTel span name                                                                                                     | `operation.name`  | `resource.name`        |
+| ------------------------------------------------------------------------------------------------------------------ | ----------------- | ---------------------- |
+| `invoke_agent weather`                                                                                             | `invoke_agent`    | `invoke_agent weather` |
+| `execute_tool search`                                                                                              | `execute_tool`    | `execute_tool search`  |
+| `chat <model>`                                                                                                     | `chat`            | `chat <model>`         |
+| `agent.session`, `agent.step`, `agent.action`, `agent.approval`, `agent.channel.delivery`, `agent.channel.request` | Same as span name | Same as span name      |
+
+These attributes apply to eve-owned spans in local tracing and the
+[instrumentation provider layout](./instrumentation-providers). They do not
+rename Workflow, AI SDK, or other third-party spans, or change trace IDs,
+parenting, sampling, or session grouping. Legacy `instrumentation.ts` setup
+still owns its exporter configuration and [authored trace
+hierarchy](#authored-trace-hierarchy).
+
+In Datadog APM, `operation_name:invoke_agent resource_name:"invoke_agent weather"`
+selects named agent invocations. Operation-based dashboards and monitors may
+need to replace inferred names such as `otel.span` with these explicit names.
+Keep session IDs, turn IDs, and message content in attributes, not operation or
+resource names.
+
+If an eve-owned span still appears as `otel.span`, inspect its exported OTel
+name, `operation.name`, and `resource.name` before and after any drain or
+Collector transforms. Datadog's [operation-name mapping
+guide](https://docs.datadoghq.com/opentelemetry/migrate/migrate_operation_names/)
+describes the explicit override. Exported fields must survive the ingestion
+path; a local export does not prove that a hosted backend retained them.
+
+Agent invocation spans carry `agent.turn.outcome=completed|failed|cancelled`
+when the turn has a terminal outcome. A failed invocation also has OTel error
+status; cancellation is not an error. The scalar outcome survives backends
+that discard span events, including Sentry's [direct OTLP
+intake](https://docs.sentry.io/concepts/otlp/direct/traces/). These attributes
+remain available when model and tool content is redacted.
+
 ## Runtime context
 
 _Runtime context_ is an [AI SDK concept](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text): a user-defined object that flows through a generation lifecycle. eve exposes it through `events["step.started"]`, a callback that runs once eve has assembled the model input for an attempt and returns `{ runtimeContext }`. Because eve registers the AI SDK's OpenTelemetry integration with runtime context enabled, those returned values ride onto the model-call span and its children. The field is named `runtimeContext`, not `metadata`, because AI SDK v7 carries per-call attributes on runtime context rather than a dedicated metadata field.
@@ -156,7 +195,7 @@ ai.eve.turn  {eve.session.id}
 
 eve creates the `ai.eve.turn` parent span per turn and passes enriched telemetry to the AI SDK so model calls and tool executions are traced automatically. The AI SDK's OpenTelemetry integration names these spans after the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/), so backends that understand `gen_ai.operation.name` can classify them without extra configuration. The `invoke_agent` span is named after the model; the agent name is on its `gen_ai.agent.name` attribute.
 
-This hierarchy applies when eve passes telemetry to the AI SDK. When the `otel()` provider layout is declared and eve owns the agent spans, eve names the span `invoke_agent <agent>` and emits no step spans. Session, turn, step, and channel context is injected as the framework half of the runtime context (`eve.version`, `eve.session.id`, `eve.environment`, `eve.turn.id`, `eve.turn.sequence`, `eve.step.index`, `eve.channel.kind`) and rides onto the spans alongside any values your `events["step.started"]` callback returns under `runtimeContext`.
+This hierarchy applies when eve passes telemetry to the AI SDK. When the `otel()` provider layout is declared and eve owns the agent spans, eve names its invocation span `invoke_agent <agent>` and its model-attempt spans `agent.step`. Session, turn, step, and channel context is injected as the framework half of the runtime context (`eve.version`, `eve.session.id`, `eve.environment`, `eve.turn.id`, `eve.turn.sequence`, `eve.step.index`, `eve.channel.kind`) and rides onto the spans alongside any values your `events["step.started"]` callback returns under `runtimeContext`.
 
 Set `traceChannelRequests: true` on `defineInstrumentation` to also wrap each inbound channel HTTP request in a single OpenTelemetry `SERVER` span named for the registered route, which parents the turn tree above (and any `hook.resume` and outgoing HTTP spans):
 

package/docs/guides/remote-agents.md

@@ -180,6 +180,8 @@ The parent stream carries the same `subagent.called`, `action.result`, and `suba
 
 An admitted task 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. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
 
+You can also steer a running remote background child by calling its subagent tool with the same `agentId` and an updated `message`. eve cancels the old task and requests cancellation of the remote turn before continuing the same remote session under a new task ID. The remote must support the standard eve cancellation and session-message routes. See [Agent messaging](../subagents#agent-messaging) for the shared steering contract.
+
 When the parent session ends, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for each remote child. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
 
 A failed _start_ rejects admission before a task receipt is returned. After a remote starts, a terminal failure callback fails the task and notifies the parent with the remote's error (or `REMOTE_AGENT_FAILED` when none is supplied). Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.

package/docs/instructions.mdx

@@ -86,7 +86,7 @@ See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failu
 
 [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-reset) treats user-role instructions like ordinary conversation history, so a summary may replace their original text. Clear removes them with the rest of model-message history and does not rerun static or dynamic instructions. System-role instructions remain because they are outside history.
 
-Keep system-role content stable and place it before frequently changing context when practical. That gives providers the best opportunity to reuse a prompt prefix, but cache behavior and billing remain provider-specific. User-role instructions preserve the normal append-only message prefix; eve does not promise a cache hit.
+Keep system-role content stable and place it before frequently changing context when practical. That gives providers the best opportunity to reuse a prompt prefix, but cache behavior and billing remain provider-specific. User-role instructions preserve the normal append-only message prefix. Framework context such as dynamic skill announcements also keeps its position before the current request across tool steps, including when a durable step resumes. eve does not promise a cache hit.
 
 ## Disclaimer
 

package/docs/memory/overview.mdx

@@ -70,12 +70,23 @@ Every slot needs a provider. The provider decides how memory is stored, how
 relevant context is retrieved, and whether the agent captures conversation
 automatically or only through explicit tool calls.
 
-| Provider                              | Ships as                | Recall                                                 | Capture                                              |
-| ------------------------------------- | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
-| [Supermemory](#supermemory)           | `@supermemory/eve`      | Semantic search over stored memories                   | Automatic after each turn, plus tools                |
-| [Upstash AgentKit](#upstash-agentkit) | `@upstash/agentkit-eve` | Ranked Redis Search recall or a Redis document backend | Automatic user-message capture or model-driven tools |
-| [File memory](#file-memory)           | Built into eve          | One bounded document per scope                         | Model-driven `save_memory` / `remove_memory`         |
-| [Your own provider](#build-your-own)  | Your code               | Whatever your store returns                            | Whatever rules you implement                         |
+| Provider                                | Ships as                | Recall                                                 | Capture                                              |
+| --------------------------------------- | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
+| [File memory](#file-memory)             | Built into eve          | One bounded document per scope                         | Model-driven `save_memory` / `remove_memory`         |
+| [Supermemory](#supermemory)             | `@supermemory/eve`      | Semantic search over stored memories                   | Automatic after each turn, plus tools                |
+| [Upstash AgentKit](#upstash-agentkit)   | `@upstash/agentkit-eve` | Ranked Redis Search recall or a Redis document backend | Automatic user-message capture or model-driven tools |
+| [Kybernesis Arcana](#kybernesis-arcana) | `@kybernesis/arcana`    | Semantic search and brain notes                        | Model-driven tools or optional automatic capture     |
+| [Your own provider](#build-your-own)    | Your code               | Whatever your store returns                            | Whatever rules you implement                         |
+
+### File memory
+
+`fileMemory()` from `eve/memory/file` keeps one bounded document per scope and
+gives the model `save_memory` and `remove_memory` tools. It does not extract
+facts automatically; the model decides what to save. It needs no external
+service in `eve dev` and stores to Vercel Blob when deployed to Vercel, which
+makes it the shortest path to a working slot.
+
+Read [File memory](/docs/memory/file) for size limits, storage backends, and options.
 
 ### Supermemory
 
@@ -137,15 +148,36 @@ export default defineMemory({
 See the [Upstash AgentKit integration page](/integrations/upstash-agentkit) for
 options.
 
-### File memory
+### Kybernesis Arcana
 
-`fileMemory()` from `eve/memory/file` keeps one bounded document per scope and
-gives the model `save_memory` and `remove_memory` tools. It does not extract
-facts automatically; the model decides what to save. It needs no external
-service in `eve dev` and stores to Vercel Blob when deployed to Vercel, which
-makes it the shortest path to a working slot.
+[Kybernesis Arcana](https://github.com/KybernesisAI/platform/tree/master/packages/arcana#readme)
+backs a memory slot with semantic search and brain notes. It gives the model
+tools to remember, recall, and search memory; capture is disabled by default.
 
-Read [File memory](/docs/memory/file) for size limits, storage backends, and options.
+```bash
+eve add memory/arcana
+```
+
+The command installs `@kybernesis/arcana` and writes an `arcana` slot:
+
+```ts title="agent/memory/arcana.ts"
+import { arcanaMemory } from "@kybernesis/arcana/memory";
+import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+
+export default defineMemory({
+  description: "Recall and manage durable context for the current user.",
+  provider: arcanaMemory({
+    apiKey: process.env.ARCANA_API_KEY!,
+    workspace: process.env.ARCANA_WORKSPACE!,
+  }),
+  scope: byPrincipal,
+});
+```
+
+Set `capture: { enabled: true }` when you want Arcana to capture completed
+turns automatically. See the [Arcana package documentation](https://github.com/KybernesisAI/platform/tree/master/packages/arcana#readme)
+for provider options.
 
 ### Build your own
 

package/docs/reference/cli.md

@@ -161,6 +161,10 @@ eve build [--profile <path>] [--skip-sandbox-prewarm]
 
 Compiles and bundles in an invocation-owned directory under `.eve/builds/`, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure.
 
+Authored bundles preserve custom Node.js resolution conditions supplied through `--conditions`,
+`-C`, or `NODE_OPTIONS`. For example, `NODE_OPTIONS="--conditions=react-server" eve build`
+keeps a channel's `server-only` imports on the same export used during compilation.
+
 | Flag                     | Type   | Default | Description                                                                                   |
 | ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------- |
 | `--profile <path>`       | string | off     | Best-effort versioned JSON report with build-phase timings and final output-size measurements |
@@ -199,6 +203,8 @@ eve start [--host <host>] [--port <port>]
 
 Serves the previously built output. Prints the listening URL.
 
+For self-hosted deployments, copy the app source, `.output/`, and installed dependencies together. The deployment directory can differ from the build directory. Preserve the relative layout of any workspace packages used by the app; startup resolves sandbox prewarm modules from the deployed source.
+
 ## `eve dev`
 
 ```bash

package/docs/reference/telemetry.md

@@ -12,9 +12,9 @@ eve collects usage data from its CLI to help improve its commands and developmen
 eve sends the following information to Vercel:
 
 - The eve version, operating system, CPU architecture, and whether stdin is a terminal.
-- The command you ran and whether it succeeded, had a usage error, or failed.
+- The command you ran, its outcome, and setup or onboarding steps when applicable.
 - For `eve dev`, whether you connected to a local or remote agent and whether the UI was interactive or headless.
-- Random identifiers for the CLI session, your eve installation, and the project.
+- Random identifiers for the CLI session, installation, and project, plus whether the installation and project identifiers are ephemeral or persistent.
 
 The project identifier lets eve group usage from the same project without sending its name or location. eve derives it from the Git remote when available, otherwise `REPOSITORY_URL` or the working directory, and transforms that value before sending it.
 

package/docs/reference/typescript-api.md

@@ -54,7 +54,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 such as `defineTool`, `defineWorkflowTool`, `defineDynamic`, and `disableTool` 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`, `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`.
 
@@ -170,7 +170,7 @@ Run source mutations inside `withSuspendedSource()`. It acquires a unique watche
 
 ## ChatGPT subscription models
 
-`chatgpt()` from `eve/models/openai` serves an OpenAI model through the local Codex login and bills the ChatGPT subscription. With no argument, it selects `gpt-5.6-sol`:
+`chatgpt()` from `eve/models/openai` serves an OpenAI model through your local ChatGPT login and bills the ChatGPT subscription. With no argument, it selects `gpt-5.6-sol`:
 
 ```ts title="agent/agent.ts"
 import { defineAgent } from "eve";
@@ -185,20 +185,24 @@ Pass another bare OpenAI model slug to override the default. `experimental_chatg
 
 `chatgpt()` uses stateless requests (`store: false`). eve retains reasoning summaries and encrypted reasoning in session history and replays them after tool calls and on later turns. You do not need to configure `reasoning.encrypted_content` explicitly.
 
-Authentication is delegated entirely to the Codex CLI:
+Sign in directly from eve; the Codex CLI is not required:
 
-1. Install or upgrade `codex` and run `codex login`.
-2. `eve dev` asks `codex app-server` for a usable access token. Codex owns refresh and credential persistence; eve does not read or write Codex login files.
-3. Normal token expiry is refreshed automatically. If the login is revoked, the status line shows `codex login`; completing login inside or outside eve repairs the running dev session without restarting it.
+1. Run `eve dev`, open `/model`, and select **Provider** → **ChatGPT subscription**.
+2. Complete sign-in in the browser. If the browser does not open, use the URL printed in the terminal.
+3. Return to eve after the terminal confirms that your subscription is connected. Normal token expiry is refreshed automatically.
+
+eve stores this session in `~/.eve/auth/chatgpt.json` with owner-only file permissions on Unix. It is separate from any Codex login and is never written to your project. Keep this file private. To remove the local eve login, stop your eve processes and delete the file. Existing Codex users must sign in once through eve after upgrading.
+
+Over SSH, or if localhost port 1455 is occupied, eve shows a device code instead. Open the displayed link in a browser and enter the code. Device sign-in requires enabling device code authorization in **ChatGPT Settings → Security**, or having a workspace admin enable it in workspace permissions. Sign-in times out after five minutes; press **Ctrl+C** to cancel sooner.
 
 ChatGPT subscription credentials are local user credentials. `eve deploy` blocks agents whose active model is `chatgpt()` because those credentials are not uploaded to a deployment. Use an environment branch with a deployable model, or switch to an AI Gateway model before deploying.
 
 Troubleshooting:
 
-- **`chatgpt-sub login`**: run `codex login`.
-- **`chatgpt-sub unavailable`**: ensure `codex` is installed, current, and available on `PATH`; then restart the command.
+- **`chatgpt-sub login`**: open `/model` and select **Provider** → **ChatGPT subscription** to sign in again. The running dev session picks up the new login.
+- **`chatgpt-sub unavailable`**: check your network connection and retry from `/model`. If eve reports an invalid credential file, remove `~/.eve/auth/chatgpt.json` and sign in again.
 - **Model rejected by the backend**: model availability depends on the signed-in ChatGPT account. Pick another supported OpenAI model.
-- **SSH/headless login**: run `codex login --device-auth` in another terminal, then return to the still-running `eve dev` session.
+- **Device sign-in unavailable**: enable device code authorization in ChatGPT security settings, or sign in from a local terminal with port 1455 available.
 
 ## What to read next
 

package/docs/sandbox.mdx

@@ -31,6 +31,11 @@ export default defineTool({
     const sandbox = await ctx.getSandbox();
     await sandbox.writeTextFile({ path: "analysis/run.py", content: script });
     const result = await sandbox.run({ command: "python analysis/run.py" });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Analysis failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+      );
+    }
     return { stdout: result.stdout };
   },
 });
@@ -38,13 +43,15 @@ export default defineTool({
 
 `ctx.getSandbox()` takes no arguments, is async, and only works inside authored runtime execution.
 
+`sandbox.run()` resolves with `{ exitCode, stdout, stderr }` when the process exits, including a nonzero exit. Check `exitCode` before reporting success or using generated files. Throw from a tool to report a failed operation to the model, and throw from `bootstrap` to prevent eve from caching an incomplete setup. The built-in `bash` tool returns all three fields so the model can interpret command results itself.
+
 `/workspace` is one namespace across every backend, so `/workspace/foo` points at the same file whether the backend is local or Vercel. When you need to interpolate a path into a generated command, `sandbox.resolvePath("repo/build.py")` anchors a relative path to its absolute `/workspace/repo/build.py` form.
 
 The handle does more than `run` and `writeTextFile`. In every method, relative paths resolve from `/workspace` and absolute paths pass through untouched:
 
 | Method                                   | Does                                                                                            |
 | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `run({ command })`                       | run one command, block until it exits, return `{ stdout, stderr, ... }`                         |
+| `run({ command })`                       | run one command, block until it exits, return `{ exitCode, stdout, stderr }`                    |
 | `spawn(options)`                         | launch a long-running process (server, watcher) and return a `SandboxProcess` handle            |
 | `readTextFile` / `writeTextFile`         | read/write a UTF-8 (or specified encoding) file; `readTextFile` supports 1-based line ranges    |
 | `readBinaryFile` / `writeBinaryFile`     | read/write raw bytes (images, archives, anything non-text)                                      |
@@ -106,7 +113,12 @@ export default defineSandbox({
   revalidationKey: () => "repo-bootstrap-v1",
   async bootstrap({ use }) {
     const sandbox = await use();
-    await sandbox.run({ command: "sudo apt-get install -y jq" });
+    const result = await sandbox.run({ command: "sudo apt-get install -y jq" });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Sandbox setup failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+      );
+    }
   },
   async onSession({ use }) {
     await use({ networkPolicy: "deny-all" });
@@ -277,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:
@@ -12,7 +22,7 @@ The root session receives `agent` by default. The model calls it to delegate a t
 ```ts
 {
   message: string;       // everything the child needs; it does not see the parent's history
-  agentId?: string;      // continue an existing child
+  agentId?: string;      // continue or steer an existing child
   outputSchema?: object; // require structured output for this turn
 }
 ```
@@ -160,7 +170,7 @@ A directly declared subagent's tool name is the bare path-derived name, with no
 ```ts
 {
   message: string;       // all context the child needs; it never sees the parent's history
-  agentId?: string;      // continue an existing child
+  agentId?: string;      // continue or steer an existing child
   outputSchema?: object; // require structured output for this turn
 }
 ```
@@ -171,13 +181,17 @@ 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`.
 
-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. Parent-session finalization cancels remaining live tasks.
+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.
 
 Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call so completed earlier steps, tool results, and sandbox work remain available to the child. Other recoverable task errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed task result instead of stacking both retry budgets; terminal errors fail immediately.
 
 ## Agent messaging
 
-A child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`, and messaging a child that is still starting or working on its previous request fails with `AGENT_BUSY` — wait for its result before continuing it.
+A child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`.
+
+To steer a running background child, call the same subagent tool with its `agentId` and the updated `message`. eve cancels the previous task before starting a new task in the same child session. The child retains its conversation history, and the receipt contains the same `agentId` with a new `taskId`. The cancelled task cannot publish a later successful result. Steering does not undo tool side effects that have already occurred.
+
+A child that is still starting, or is owned by a blocking workflow invocation rather than an admitted background task, continues to return `AGENT_BUSY`. Cancellation or delivery failures are reported to the caller; eve does not start a replacement child session to hide them.
 
 Whenever the set of parked (resumable) children changes, eve appends a framework-injected note to the conversation — labeled `[Agents]` and carrying an `<agents>` block — listing each child's `agentId`, name, and latest status. The static system prompt tells the model the note is injected by eve, not written by the user. The note is appended only when the listing changes (an append-only design that preserves the provider prompt cache), the most recent note is authoritative, and children that are starting or running do not appear until they park again.
 

package/docs/tools/overview.mdx

@@ -32,6 +32,30 @@ A tool definition needs:
 
 When a tool returns structured data, add an optional `outputSchema`. With Zod or Standard Schema it also types the `execute` return.
 
+### Label tool activity
+
+Use `label.start(input)` to describe a call in user-facing activity. The callback receives the validated tool input, so it can select the useful fields without exposing the full argument object:
+
+```ts title="agent/tools/deploy.ts"
+export default defineTool({
+  description: "Deploy a project to an environment.",
+  inputSchema: z.object({
+    project: z.string(),
+    environment: z.enum(["preview", "production"]),
+  }),
+  label: {
+    start: ({ project, environment }) => `Deploy ${project} to ${environment}`,
+  },
+  async execute(input) {
+    return deploy(input);
+  },
+});
+```
+
+The label is presentation only. It does not replace the path-derived tool name, enter model input, or change execution. eve records the bounded label on the corresponding public action event so activity renderers and other authorized stream consumers can use it without interpreting raw tool data. Built-in channel activity can show `Deploy storefront to production` instead of `deploy`; if the callback throws or returns an empty label, activity falls back to the tool name.
+
+Provided tools define labels for `bash`, `glob`, `grep`, `load_skill`, `read_file`, `web_fetch`, `web_search`, and `write_file`.
+
 ### Stream preliminary tool results
 
 For a `defineTool` executor with the default execution mode, an async generator streams complete
@@ -42,10 +66,15 @@ yield is the normal tool result the model receives:
 export default defineTool({
   description: "Build a project report.",
   inputSchema: z.object({ project: z.string() }),
+  label: {
+    start: ({ project }) => `Build report for ${project}`,
+    delta: (_input, partial) => partial.phase,
+    complete: (_input, output) => `Report ready with ${output.report.sections.length} sections`,
+  },
   async *execute({ project }) {
-    yield { phase: "collecting", report: null };
+    yield { phase: "Collecting sources", report: null };
     const report = await buildReport(project);
-    yield { phase: "complete", report };
+    yield { phase: "Complete", report };
   },
 });
 ```
@@ -58,6 +87,19 @@ can retry a step and replay overlapping snapshots. A generator `return` value is
 the result in this mode; yield the final output. Workflow and background generators have
 different result rules, described under [yield and return](#yield-and-return).
 
+Use `label.delta(input, partial)` to project preliminary snapshots into
+user-facing activity, and `label.complete(input, output)` to describe successful
+settlement differently. Both callbacks receive the validated input first and the typed value yielded by
+`execute` second. Each non-empty update replaces the previous activity label; the
+result projection replaces the latest update immediately before eve marks the
+action complete.
+
+eve normalizes and bounds projected text before rendering it. If either
+callback throws or returns an empty string, eve keeps the existing activity
+label. `label.complete` does not run for failed or rejected tool calls. The
+full values remain available in `action.partial` and `action.result`; renderers
+receive only the projected text.
+
 ### Background execution
 
 Background execution controls how a tool delivers its result to the parent agent. Durable