eve 0.52.2 → 0.52.3

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

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,

package/docs/tutorial/connect-a-warehouse.mdx

@@ -1,58 +1,81 @@
 ---
-title: "Connect a Warehouse"
-description: "Part 4 of the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
+title: "Connect a Warehouse (Optional)"
+description: "Optional follow-up to the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
 ---
 
-The sample dataset got the analytics assistant running, but it's a stand-in. Now point the agent at a real warehouse and let each user connect their own by signing in through their browser. That's what a connection is for. It's an MCP server the model reaches through tools, with auth that eve drives for you.
+Complete [the tutorial with sample data](./first-agent) first. When you have a warehouse with an MCP server, you can connect it to the analytics assistant and let each user sign in through their browser. That's what a connection is for. It's an MCP server the model reaches through tools, with auth that eve drives for you.
 
-This step depends on Vercel Connect, which is in private beta. No Connect access? Keep the Step 3 sample dataset and read this step for the connection model. Steps 5 through 9 work against the sample dataset, so you can complete the tutorial without a warehouse.
+[Vercel Connect is generally available](https://vercel.com/changelog/vercel-connect-secure-access-to-external-services-for-your-agents). You can complete the tutorial with the [sample dataset](./query-sample-data); Connect is only needed for the OAuth integration shown on this page.
 
-The filename sets the runtime name. Put the file at `agent/connections/warehouse.ts` and it registers as `"warehouse"`, with its tools surfaced as `warehouse__<tool>`.
+## Before you start
+
+This integration needs:
+
+- A warehouse account and a working MCP server for that warehouse, with its full endpoint URL. Connect manages credentials; it does not create a warehouse or turn a SQL database into an MCP server.
+- Permission to authorize that server, with read-only access to the data you want the agent to query.
+- A Vercel account and a linked project for Connect.
+- An authenticated user on the eve session. Complete the route-auth setup in [Ship it](./ship-it#replace-placeholderauth) before trying per-user OAuth from a web app.
+
+If you are working through the tutorial for the first time, keep `run_sql` and [continue to Run analysis](./run-analysis). You can add this integration later.
+
+## Register the connector
+
+Run these commands from `analytics-assistant/`. Replace the example URL with your MCP server's actual endpoint, including its path:
+
+```bash
+npm install @vercel/connect
+npx vercel@latest link
+npx vercel@latest connect create "https://your-warehouse.example/mcp" --name warehouse
+```
+
+Follow the provider-specific registration prompts. Copy the **connector UID returned by the CLI**. The display name `warehouse` is not the connector UID. Attach the returned connector to this project, then pull the local environment:
+
+```bash
+npx vercel@latest connect attach "<returned-connector-uid>" --yes
+npx vercel@latest env pull
+```
+
+`vercel env pull` provides `VERCEL_OIDC_TOKEN` for local requests to Connect. That token identifies your Vercel project; it does not sign an end user into the app. The steps below use the authenticated deployment from [Ship it](./ship-it#replace-placeholderauth). The [Connect reference](https://vercel.com/docs/connect) covers service-specific setup and project attachments.
 
 ## Declare the connection
 
-The warehouse exposes a generic SQL MCP behind OAuth. Pass `connect()` from `@vercel/connect/eve` as the auth, and Vercel Connect handles the OAuth flow, stores the tokens, and refreshes them for you:
+Create `agent/connections/warehouse.ts`. Replace both the endpoint URL and connector UID below with the values you just configured:
 
 ```ts title="agent/connections/warehouse.ts"
 import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.your-warehouse.example/sse",
+  url: "https://your-warehouse.example/mcp",
   description: "The team's data warehouse: run read-only SQL and list tables and columns.",
-  auth: connect("warehouse"),
+  auth: connect("<returned-connector-uid>"),
 });
 ```
 
-`"warehouse"` is the UID you chose when registering the Connect client. By default this OAuth is user-scoped. Each end-user authorizes in their own browser, and eve resolves that user's token before every tool call.
+The filename registers the eve connection as `"warehouse"`, with tools named `warehouse__<tool>`. This eve name is independent of the Connect connector UID. The remote server determines which tools exist; check its tool inventory and read-only permissions before using it.
 
-Before testing the warehouse from a web app, make sure the eve channel route auth maps your signed-in app user to `principalType: "user"`. A Connect-backed connection can only start per-user OAuth when the active session already has an authenticated user principal. If route auth still only accepts `localDev()`, a runtime token, or a placeholder guard, the first warehouse tool call fails with `reason: "principal_required"` instead of showing the sign-in challenge.
+`connect("...")` is user-scoped by default. Each end-user authorizes in their own browser, and eve resolves that user's token before a tool call. The eve channel's route auth must map the signed-in app user to `principalType: "user"`. `localDev()`, a runtime token, or a placeholder guard cannot supply that identity; those sessions fail with `reason: "principal_required"` before OAuth starts. For a shared app credential, see [app vs. user auth](../connections#choose-app-vs-user-auth).
 
-Once Connect is enabled on your account, wire it up:
+## Deploy and try it
 
-1. Install the package: `npm install @vercel/connect`.
-2. Create the Connect client: `vercel connect create <type> --name warehouse`.
-3. Link the client to your project.
-4. Run `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally.
+Deploy the updated app so the authenticated web app includes the new connection:
 
-For the full reference, see [MCP connections](../connections/mcp).
-
-## What the user sees
+```bash
+npx vercel@latest deploy
+```
 
-Ask a question that needs the warehouse:
+Open the new HTTPS preview URL, sign in with the credentials configured in [Ship it](./ship-it#replace-placeholderauth), and create a new session. The tutorial's development server bypasses the browser login and uses `localDev()`; restarting `npm run dev` alone does not provide the user identity this connection requires.
 
-```text
-How many enterprise customers signed up last month?
-```
+From your authenticated web app, ask the agent to inspect the warehouse's available tables and then query a table you have access to. Use the server's schema rather than assuming it has the tutorial's `orders` and `customers` tables.
 
-The first time, the model picks a warehouse tool but there's no token yet, so the turn parks and the channel shows a "Sign in" affordance. You authorize in the browser, and once the OAuth callback completes, the turn resumes from exactly that step (the durable parking from [Step 2](./how-it-runs)) and the query runs. Later calls in the session reuse the cached per-user token, so there's no prompt.
+If the user has not authorized the connector, the turn parks and the channel shows a sign-in link. Complete authorization in the browser; after the callback succeeds, the turn resumes and retries the tool call. Later calls use the existing grant while it remains valid. See [MCP connection troubleshooting](../connections/mcp#troubleshooting) if registration succeeds but the tool cannot connect.
 
 ## The token never reaches the model
 
-Right before each request to the MCP server, eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model only ever sees tool names, descriptions, and results. The credential stays out of its reach.
+Right before each request to the MCP server, eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model sees tool names, descriptions, and results. The credential stays in the app runtime.
 
-If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [MCP connections](../connections/mcp).
+Gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`) when needed. See [MCP connections](../connections/mcp).
 
-→ Next: [Run analysis](./run-analysis)
+→ Return to the tutorial: [Run analysis](./run-analysis)
 
 Learn more: [MCP connections](../connections/mcp) · [Authentication](../guides/auth-and-route-protection)