eve 0.52.1 → 0.52.3

package/docs/guides/dynamic-capabilities.md

@@ -219,7 +219,7 @@ the handler.
 
 ## Dynamic tools
 
-Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. eve records durable descriptors for `execute`, approval request and response policies, and `toModelOutput`, so a parked call can reconstruct the same callbacks in a fresh process.
+Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. eve records durable descriptors for `execute`, approval request and response policies, input-scoped `approvalKey` callbacks, and `toModelOutput`, so a parked call can reconstruct the same callbacks in a fresh process.
 
 Dynamic tool executors receive the same `ToolContext` as static authored tools, including inline provider auth through `ctx.getToken(provider)` and `ctx.requireAuth(provider)`.
 
@@ -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/frontend/overview.mdx

@@ -306,7 +306,7 @@ then save a final snapshot in `onFinish`.
 
 For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, and `resume` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
 
-Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. While `status` is `"resuming"`, render hydrated `data` but disable message and HITL submission; do not present cancellation or active-turn progress controls. If catch-up finds an in-flight turn, `status` changes to `"streaming"` before the binding follows it to a boundary. A settled tail changes directly to `"ready"`, and a terminal session failure changes to `"error"`.
+Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. While `status` is `"resuming"`, render hydrated `data` but disable message and HITL submission; do not present cancellation or active-turn progress controls. If catch-up finds an in-flight turn, `status` changes to `"streaming"` before the binding follows it to a boundary. A settled tail changes directly to `"ready"` after a bounded catch-up check, without waiting for the live stream idle timeout. If that check finds a newly started turn or pending authorization, eve keeps following it. A terminal session failure changes to `"error"`.
 
 ```tsx
 const agent = useEveAgent({

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/custom-provider.md

@@ -173,7 +173,10 @@ turn recalls the same data again.
 ## Failure behavior
 
 - A throwing or invalid `recall["turn.started"]` fails the turn before the
-  model call. No slot's recall results are committed.
+  model call. No slot's recall results are committed. If the turn's
+  `abortSignal` is already aborted, eve treats the error as cancellation and
+  continues with any queued steering replacement. An `AbortError` with an active
+  signal still fails the turn.
 - A throwing `capture["compaction.requested"]` leaves history unchanged.
 - A throwing `recall["compaction.completed"]` fails an automatic turn. For
   standalone compaction, eve logs the error and returns the session to waiting,

package/docs/memory/file.md

@@ -18,9 +18,10 @@ eve add memory/file
 
 After you choose **Install and set up**, eve creates or reuses one private
 Vercel Blob store for the linked project, connects it to production, preview,
-and development with `EVE_MEMORY_`-prefixed variables, and pulls the updated
-environment. It uses the project's first configured function region, falling
-back to `iad1`. Blob usage may incur charges.
+and development using OIDC, and pulls the updated environment. The connection
+sets `EVE_MEMORY_BLOB_STORE_ID` and `EVE_MEMORY_BLOB_WEBHOOK_PUBLIC_KEY`
+without adding a read-write token. It uses the project's first configured
+function region, falling back to `iad1`. Blob usage may incur charges.
 
 The registry writes:
 
@@ -96,13 +97,21 @@ provider: fileMemory({ backend: inMemory() });
 ### Vercel Blob
 
 Provisioned bindings use the `EVE_MEMORY_BLOB_*` namespace so file memory does
-not take over an application's own Blob store. `fileMemory()` checks Vercel
-credentials in this order:
+not take over an application's own Blob store. Vercel supplies the OIDC token;
+the Blob SDK resolves the current token for each operation and handles refresh.
+File-memory reads and writes need the store ID. The webhook public key is for upload callbacks
+and is not used by file memory.
 
-1. `EVE_MEMORY_BLOB_READ_WRITE_TOKEN`
-2. `EVE_MEMORY_BLOB_STORE_ID` with Vercel OIDC from the environment or request context
-3. `BLOB_READ_WRITE_TOKEN`
-4. `BLOB_STORE_ID` with Vercel OIDC from the environment or request context
+`fileMemory()` checks Vercel configuration in this order:
+
+1. `EVE_MEMORY_BLOB_STORE_ID` with Vercel OIDC from the environment or request context
+2. `EVE_MEMORY_BLOB_READ_WRITE_TOKEN`
+3. `BLOB_STORE_ID` with Vercel OIDC from the environment or request context
+4. `BLOB_READ_WRITE_TOKEN`
+
+Prefer OIDC on Vercel. You do not need to set a read-write token or copy
+`VERCEL_OIDC_TOKEN` into your configuration. Redeploy after connecting the
+store: changes to project environment variables apply to new deployments.
 
 Generic `BLOB_*` variables remain supported for a store you attach manually.
 Run setup again without reinstalling the memory definition when a previous
@@ -113,8 +122,11 @@ eve integration setup file-memory
 ```
 
 Setup repairs the deterministic unconnected private store left by a partial
-run and reuses a complete `EVE_MEMORY_` connection. It does not adopt an
-arbitrary application store, change a `BLOB_*` connection, or replace a public
+run and reuses a complete `EVE_MEMORY_BLOB` connection. If an earlier setup
+created an `EVE_MEMORY_` connection, reconnect that same store with the
+`EVE_MEMORY_BLOB` prefix and OIDC in Vercel, then redeploy. Keep the existing
+store to preserve its memory documents. Setup does not adopt an arbitrary
+application store, change a `BLOB_*` connection, or replace a public
 or incompatible store. If the linked project later moves to another primary
 region, setup preserves the existing memory store and warns about the drift
 instead of risking data loss.
@@ -134,7 +146,8 @@ provider: fileMemory({
 `vercelBlob()` accepts `token`, `oidcToken`, `storeId`, and `prefix`. The
 default prefix is `eve/memory/file`; documents are stored privately under
 `<prefix>/<scope key>/MEMORY.md`. Passing these options continues to override
-the generic environment defaults directly.
+the generic environment defaults directly. Leave `oidcToken` unset on Vercel
+so the Blob SDK can manage token refresh.
 
 ### Custom backend
 

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" });

package/docs/subagents/index.mdx

@@ -12,7 +12,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 +160,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 +171,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

package/docs/tools/workflows.mdx

@@ -93,6 +93,12 @@ tool object, a channel handler, or a schedule handler fails the build. To start
 channel or schedule, use the [channel operations](/docs/channels/custom#channel-operations-and-session-handles)
 or [schedule handler](/docs/schedules#handler-form-run) APIs.
 
+Workflow imports resolve `paths` aliases from your application's `tsconfig.json` or
+`jsconfig.json`, including when the application is a workspace package. eve includes only
+workflow and step modules reachable from the agent's runtime modules. Unrelated workflows
+in the host application stay outside the agent bundle. An unresolved workflow import fails
+the build with the missing import in the error.
+
 ### Migrate an existing workflow tool
 
 Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workflow"` directive,
@@ -317,7 +323,9 @@ export default defineWorkflowTool({
 ```
 
 `createWebhook` mints a URL under `/.well-known/workflow/v1/webhook/` that eve serves. The external
-system posts to it when it is done. Nothing runs in between.
+system posts to it when it is done. Nothing runs in between. Webhook tokens are generated for
+you; use `createHook` with `resumeHook` if you need a deterministic token. To customize the HTTP
+response, pass `respondWith: new Response(...)` to `createWebhook`.
 
 ### Ask now, act when answered