eve 0.62.0 → 0.64.0

package/docs/README.md

@@ -12,32 +12,28 @@ Important naming note:
 
 ## Find the page for your task
 
-| To do this                                               | Read this                                                                                                                    |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Organize agents, subagents, and browser application code | [Project Structure](./concepts/project-structure.mdx)                                                                        |
-| Create a project and run your first agent                | [Getting Started](./getting-started.mdx)                                                                                     |
-| Look up agent files and discovery rules                  | [Agent Files](./reference/agent-files.md)                                                                                    |
-| Set the model, reasoning, or other agent-wide config     | [Agents](./agent-config.md)                                                                                                  |
-| Choose an agent model automatically for each request     | [Automatic Model Selection](./guides/evaluate.md)                                                                            |
-| Change what the agent does and how it behaves            | [Instructions](./instructions.mdx)                                                                                           |
-| Give the agent a typed capability it can call            | [Tools](./tools/overview.mdx)                                                                                                |
-| Require approval, or ask the user something mid-turn     | [Human in the Loop](./tools/human-in-the-loop.md)                                                                            |
-| Call an external HTTP API or MCP server                  | [Connections](./connections/overview.mdx)                                                                                    |
-| Add a messaging surface (Slack, Discord, iMessage, …)    | [Channels](./channels/overview.mdx)                                                                                          |
-| Expose your own HTTP route as a conversation surface     | [Custom Channels](./channels/custom.mdx)                                                                                     |
-| Package a procedure the agent loads only when it applies | [Skills](./skills.mdx)                                                                                                       |
-| Carry state across turns, or shape what the model sees   | [State](./concepts/state.md), [Context Control](./concepts/context-control.md)                                               |
-| Run commands or untrusted code in isolation              | [Sandboxes](./sandbox.mdx)                                                                                                   |
-| Delegate work to a specialist child agent                | [Subagents](./subagents/index.mdx)                                                                                           |
-| Run work on a recurring schedule                         | [Schedules](./schedules.mdx)                                                                                                 |
-| Install an existing integration instead of writing one   | [Add Integrations](./install-integrations.mdx)                                                                               |
-| Link a Vercel project and deploy to production           | [Deploy to Vercel](./guides/deployment/vercel.mdx)                                                                           |
-| Self-host, or compare hosting strategies                 | [Deployment](./guides/deployment/overview.md)                                                                                |
-| Authorize routes, sessions, and per-user access          | [Authentication](./guides/auth-and-route-protection.md)                                                                      |
-| Add a browser application                                | [Next.js](./guides/frontend/nextjs.mdx), [Nuxt](./guides/frontend/nuxt.mdx), or [SvelteKit](./guides/frontend/sveltekit.mdx) |
-| Build a custom web UI, or stream a session to a client   | [Client SDK](./guides/client/overview.mdx), [Frontend](./guides/frontend/overview.mdx)                                       |
-| Test the agent's behavior                                | [Evals](./evals/overview.mdx)                                                                                                |
-| Look up a CLI command or an exported type                | [CLI](./reference/cli.md), [TypeScript API](./reference/typescript-api.md)                                                   |
+| To do this                                               | Read this                                                                              |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Create a project, or understand the file layout          | [Getting Started](./getting-started.mdx)                                               |
+| Set the model, reasoning, or other agent-wide config     | [Agents](./agent-config.md)                                                            |
+| Change what the agent does and how it behaves            | [Instructions](./instructions.mdx)                                                     |
+| Give the agent a typed capability it can call            | [Tools](./tools/overview.mdx)                                                          |
+| Require approval, or ask the user something mid-turn     | [Human in the Loop](./tools/human-in-the-loop.md)                                      |
+| Call an external HTTP API or MCP server                  | [Connections](./connections/overview.mdx)                                              |
+| Add a messaging surface (Slack, Discord, iMessage, …)    | [Channels](./channels/overview.mdx)                                                    |
+| Expose your own HTTP route as a conversation surface     | [Custom Channels](./channels/custom.mdx)                                               |
+| Package a procedure the agent loads only when it applies | [Skills](./skills.mdx)                                                                 |
+| Carry state across turns, or shape what the model sees   | [State](./concepts/state.md), [Context Control](./concepts/context-control.md)         |
+| Run commands or untrusted code in isolation              | [Sandboxes](./sandbox/index.mdx)                                                       |
+| Delegate work to a specialist child agent                | [Subagents](./subagents/index.mdx)                                                     |
+| Run work on a recurring schedule                         | [Schedules](./schedules.mdx)                                                           |
+| Install an existing integration instead of writing one   | [Add Integrations](./install-integrations.mdx)                                         |
+| Link a Vercel project and deploy to production           | [Deploy to Vercel](./guides/deployment/vercel.mdx)                                     |
+| Self-host, or compare hosting strategies                 | [Deployment](./guides/deployment/overview.md)                                          |
+| Authorize routes, sessions, and per-user access          | [Authentication](./guides/auth-and-route-protection.md)                                |
+| Build a web UI, or stream a session to a client          | [Client SDK](./guides/client/overview.mdx), [Frontend](./guides/frontend/overview.mdx) |
+| Test the agent's behavior                                | [Evals](./evals/overview.mdx)                                                          |
+| Look up a CLI command or an exported type                | [CLI](./reference/cli.md), [TypeScript API](./reference/typescript-api.md)             |
 
 ## Legal and safeguards
 
@@ -58,25 +54,24 @@ Unless you configure stricter controls, eve agents may operate with permissive s
 For a full picture rather than a single task, read in this order:
 
 1. [Getting Started](./getting-started.mdx)
-2. [Project Structure](./concepts/project-structure.mdx)
-3. [Tutorial](./tutorial/first-agent.mdx)
-4. [Agents](./agent-config.md)
-5. [TypeScript API Reference](./reference/typescript-api.md)
-6. [Context Control](./concepts/context-control.md)
-7. [Skills](./skills.mdx)
-8. [Tools](./tools/overview.mdx)
-9. [Connections](./connections/overview.mdx)
-10. [Sandboxes](./sandbox.mdx)
-11. [Channels](./channels/overview.mdx)
-12. [Session Context](./guides/session-context.md)
-13. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md)
-14. [Client SDK](./guides/client/overview.mdx)
-15. [Subagents](./subagents/index.mdx)
-16. [Schedules](./schedules.mdx)
-17. [Evals](./evals/overview.mdx)
-18. [Authentication](./guides/auth-and-route-protection.md)
-19. [Deployment](./guides/deployment/overview.md)
-20. [CLI](./reference/cli.md)
+2. [Tutorial](./tutorial/first-agent.mdx)
+3. [Agents](./agent-config.md)
+4. [TypeScript API Reference](./reference/typescript-api.md)
+5. [Context Control](./concepts/context-control.md)
+6. [Skills](./skills.mdx)
+7. [Tools](./tools/overview.mdx)
+8. [Connections](./connections/overview.mdx)
+9. [Sandboxes](./sandbox/index.mdx)
+10. [Channels](./channels/overview.mdx)
+11. [Session Context](./guides/session-context.md)
+12. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md)
+13. [Client SDK](./guides/client/overview.mdx)
+14. [Subagents](./subagents/index.mdx)
+15. [Schedules](./schedules.mdx)
+16. [Evals](./evals/overview.mdx)
+17. [Authentication](./guides/auth-and-route-protection.md)
+18. [Deployment](./guides/deployment/overview.md)
+19. [CLI](./reference/cli.md)
 
 ## The public mental model
 

package/docs/agent-config.md

@@ -1,5 +1,5 @@
 ---
-title: "Agents"
+title: "Agent Configuration"
 description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
 ---
 
@@ -21,7 +21,7 @@ For a static AI Gateway model ID, you can make the same source change from the
 project root with `eve set --model anthropic/claude-opus-4.8` or from the local
 dev TUI with `/model anthropic/claude-opus-4.8`.
 
-The root `agent.ts` can be omitted when no runtime config is needed. eve then selects its default `agent.ts` source at the same slot, configured with `openai/gpt-5.6-luna-fast`; authoring the file replaces that source.
+The root `agent.ts` can be omitted when no runtime config is needed. eve then selects its default `agent.ts` source at the same slot, configured with `spacexai/grok-4.7`; authoring the file replaces that source.
 When `agent.ts` is present, `model` is required.
 
 A config that selects a static Gateway model is compile-only. A config that contains a dynamic model or a direct-provider `LanguageModel` remains a runtime entry because eve must resolve that authored value while the agent runs. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).

package/docs/channels/eve.mdx

@@ -34,7 +34,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
 
 The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
 
-`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 4. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
+`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
 
 ### Start and continue a session
 

package/docs/channels/overview.mdx

@@ -76,6 +76,54 @@ When eve doesn't ship a channel for your surface, build one with `defineChannel`
 
 A cross-channel `send(...)` supplies input to the agent and invokes the model on the destination channel. eve does not currently provide a direct cross-channel provider-message queue. To post without starting a turn, use the provider API. See [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications) when delivery also needs application-managed retries and deduplication.
 
+## Background task results
+
+Pass `taskDeliveryPolicy` to `send(...)` to choose how the session reports background results:
+
+- `"auto"` (default for new channel sessions): ready results can invoke the parent while other tasks continue. The parent reports results that are useful independently and stays silent when a useful answer needs unfinished work.
+- `"cohort"`: wait for overlapping tasks to settle, then deliver their terminal outcomes together.
+
+```ts title="agent/channels/reports.ts"
+import { defineChannel, POST } from "eve/channels";
+import { localDev, routeAuth } from "eve/channels/auth";
+
+export default defineChannel({
+  routes: [
+    POST("/reports", async (request, { from }) => {
+      const auth = await routeAuth(request, localDev());
+      if (auth instanceof Response) return auth;
+      const session = await from("daily-report").send("Prepare the daily reports.", {
+        auth,
+        taskDeliveryPolicy: "cohort",
+      });
+      return Response.json({ sessionId: session.id });
+    }),
+  ],
+});
+```
+
+The option is available on channel-local `from(...).send(...)`, cross-channel
+`to(...).send(...)`, fixed-session `send(...)`, Chat SDK `bridge.send(...)`, and client
+sends. An explicit value
+updates the session's policy, including pending background tasks; later sends that
+omit it preserve that policy. A cross-channel send carries its setting through the
+receiver's `from(...).send(...)` unless that call supplies an explicit value.
+
+[Schedules](../schedules#background-task-results) default new sessions to `"cohort"`.
+A schedule handler can pass `taskDeliveryPolicy: "auto"` to `send(...)` to override
+that default. Child sessions use their own policy.
+
+With `"auto"`, a model call may finish without a user-visible message. Results
+already queued from the same cohort may share a turn. Each reporting turn receives
+the whole cohort, including pending tasks and available outputs, so previously
+withheld results remain available for a later combined report.
+
+Input requests and explicit task messages remain eligible for delivery under
+either policy. Failure and cancellation update task state immediately; their
+automatic reports follow the selected policy. User messages follow `turnPolicy`.
+See [Completion batching](../subagents#completion-batching) for cohort membership
+and result ordering.
+
 ## Relationship to the Chat SDK
 
 eve uses the [Chat SDK's card-builder components](https://chat-sdk.dev/docs/api/cards) (Cards, Buttons, Actions, etc.) for composing rich Slack messages. When you build a card with the [Slack channel](./slack), the underlying primitives come from the Chat SDK and get converted to Slack Block Kit at post time.

package/docs/concepts/execution-model-and-durability.mdx

@@ -56,7 +56,7 @@ that has not reached its next turn dispatch has not migrated yet.
 Transparent rollback to the former execution model is unsupported. Retire and
 restart affected sessions before rolling back.
 
-Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or `defaultBackend()`.
+Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or the default sandbox environment.
 
 For advanced self-hosted deployments, the root `agent.ts` can select the installed Workflow world package to use with `experimental.workflow.world`:
 
@@ -118,12 +118,11 @@ Some work has to wait, including a human approving a [tool](../tools) or an inte
 Background execution is a separate choice about result delivery. A background workflow tool
 returns a task receipt so the parent turn can continue; the tool's workflow may then run or
 suspend independently. A default workflow tool can suspend too, with its original tool call
-still pending. Ordinary background tools run their executor inside the initiating step and do
-not gain durable waits by setting `execution: "background"`.
+still pending. Declare background work with `defineWorkflowTool`; `defineTool` always executes
+inside its initiating step.
 
-A generator's `yield` reports progress; an awaited workflow operation provides the durable wait.
-For background tools, ordinary yields are stream-only, while `yield task.postMessage(...)`
-requests a parent-agent turn. See [background execution](../tools#background-execution) and
+An awaited workflow operation provides the durable wait. A generator's `yield` reports progress
+in default execution; background workflow tools consume yields without publishing progress. See [background execution](../tools#background-execution) and
 [workflow suspension](../tools/workflows#how-suspension-works) for the execution and result rules.
 
 ## Message delivery and steering

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

@@ -80,7 +80,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | `input.requested`         | The run paused for human input ([HITL](/docs/human-in-the-loop) approval or `ask_question`); carries `requests`.                                   |
 | `input.resolved`          | The server accepted terminal human-input outcomes; carries `resolutions` with responses when provided.                                             |
 | `subagent.called`         | A subagent was delegated; carries `childSessionId` to attach to.                                                                                   |
-| `subagent.completed`      | A background subagent was admitted and returned its task receipt.                                                                                  |
+| `subagent.completed`      | The parent recorded a successful subagent invocation result; carries the actual output.                                                            |
 | `reasoning.appended`      | A reasoning text delta.                                                                                                                            |
 | `reasoning.completed`     | The finalized reasoning block.                                                                                                                     |
 | `message.appended`        | An assistant text delta.                                                                                                                           |
@@ -119,7 +119,7 @@ Note: consider the privacy, confidentiality, and user-experience implications fo
 
 When a task explicitly requires conditional delivery and there is nothing new to report, the agent can finish with exactly `<eve-empty-delivery/>`. eve emits `message.completed` with `message: null` for that intentional silence. The marker must be the entire response, apart from surrounding whitespace; the HTML-escaped form `&lt;eve-empty-delivery/&gt;` is also accepted. A response that quotes the marker in prose or code is delivered normally.
 
-A delegated subagent publishes progress on its own child-session stream. The parent emits `subagent.called` with a `childSessionId`, which a client uses to attach. `subagent.completed` carries a working task receipt after admission; terminal outcomes arrive as task-triggered `message.received` notifications with `data.kind: "execution.background_task"`. The default frontend reducer retains these events in `events` but does not project their runtime-authored text as participant messages.
+A delegated subagent publishes progress on its own child-session stream. The parent emits `subagent.called` with a `childSessionId`, which a client uses to attach. Both blocking and background calls emit `subagent.completed` with the actual output after the parent records a successful outcome. A background working receipt is an `action.result` tool output; it does not emit completion. Older streams can contain receipt-bearing completion events marked by `data.backgroundTask`; those are admission only. Completion does not mean that the reusable child session has ended. Background task terminal outcomes also arrive as task-triggered `message.received` notifications with `data.kind: "execution.background_task"`. The default frontend reducer retains these events in `events` but does not project their runtime-authored text as participant messages.
 
 `step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, but discards incomplete assistant output and unfinished tool state. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`).
 
@@ -214,7 +214,7 @@ With one question-only batch, an exact option match or permitted freeform respon
 
 A structured response matches any currently pending request by ID, not only the newest batch. It becomes stale only after that request was answered, cleared, or cancelled. eve delivers a stale response to the model as a new user message, and the model decides whether the old selection still matters. A stale approval never authorizes the earlier tool call; the model must request the action and approval again if they are still needed.
 
-One delivery can answer requests from several batches. eve resumes approval-bearing batches in durable order and carries later answers forward until each batch can resume.
+One delivery can answer requests from several batches. eve resumes approval-bearing batches in durable order and carries later answers forward until each batch can resume. If you answer only some approvals in a batch, eve saves those responses until the remaining approvals are answered. Meanwhile, unrelated messages can run tools and receive a completed reply. The saved partial responses neither block that reply nor trigger another model call after it.
 
 Multiple steering messages retain their durable arrival order and may be folded into one input at the next boundary. A message accepted after turn settlement starts the next turn. See [message delivery and steering](./execution-model-and-durability#message-delivery-and-steering).
 
@@ -301,7 +301,7 @@ Start with the [Client SDK](../guides/client/overview) guide. It covers basic us
 
 ## Inspect the agent over HTTP
 
-`GET /eve/v1/info` returns agent-info version 4, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, memory slots, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Memory tool wrappers include their selected memory-source dependency. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`.
+`GET /eve/v1/info` returns agent-info version 6, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, memory slots, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Memory tool wrappers include their selected memory-source dependency. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`. Sandbox inspection exposes the opaque `revisionHash` that identifies its compiler-discovered environment inputs.
 
 The info route belongs to the selected `channels/eve.ts` source and uses its resolved auth policy. Without an authored replacement, eve selects the default channel source with Vercel OIDC, local development access, and the production placeholder. Replacing or disabling that source replaces or removes the info route too; no native fallback serves it.
 
@@ -309,7 +309,7 @@ The info route belongs to the selected `channels/eve.ts` source and uses its res
 curl http://127.0.0.1:2000/eve/v1/info
 ```
 
-With the default auth chain (`[vercelOidc(), localDev(), placeholderAuth()]`), a Vercel OIDC bearer takes precedence, an `eve dev` or `vercel dev` server authenticates local requests, and everything else is rejected. A deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
+With the default auth chain (`[vercelOidc(), localDev(), placeholderAuth()]`), a Vercel OIDC bearer takes precedence, `localDev()` accepts requests to an `eve dev` or `vercel dev` server, and everything else is rejected. A deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
 
 ## Dispatch order
 

package/docs/dynamic-configuration/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Dynamic Capabilities",
+  "defaultOpen": false,
+  "pages": ["../guides/dynamic-capabilities", "../guides/evaluate"]
+}

package/docs/evals/assertions.mdx

@@ -83,7 +83,11 @@ Pick the cheapest builder that captures what "correct" means. When exact match i
 
 ## The matcher mini-language
 
-`t.calledTool` and `t.calledSubagent` take matcher objects. Tools accept `{ input, output, status, count }`; subagents accept `{ callId, childSessionId, remoteUrl, output, status, count }`. Calls match `status: "completed"` by default; use `"pending"`, `"failed"`, or `"rejected"` explicitly for lifecycle checks. A numeric `count` requires an exact number of calls matching every supplied constraint. Use a predicate for ranges or other custom count requirements; it receives the observed number of matching calls.
+`t.calledTool` and `t.calledSubagent` take matcher objects. Tools accept `{ input, output, status, count }`; subagents accept `{ callId, childSessionId, remoteUrl, output, status, count }`. Calls match `status: "completed"` by default. Tool lifecycle checks also accept `"pending"`, `"failed"`, and `"rejected"`. Subagent checks use the shared task status values: `"working"`, `"input_required"`, `"completed"`, `"failed"`, and `"cancelled"`. A numeric `count` requires an exact number of calls matching every supplied constraint. Use a predicate for ranges or other custom count requirements; it receives the observed number of matching calls.
+
+A background subagent that has only returned a working task receipt remains `working`; use `t.calledSubagent(name, { status: "working" })` to assert that delegation. Both blocking and background calls become `completed` when their actual successful result is observed through `subagent.completed`, even when the child session stays available for another call. A rejected dispatch is `failed`; an explicit cancelled child outcome is `cancelled`.
+
+The runner derives these values from captured events. It does not read stored task state, and the current stream does not expose every task transition. A proxied input request alone does not update the subagent call to `input_required`; assert that request with `requireInputRequest`. Check task notifications for background failure and cancellation when no child outcome event is present.
 
 Matcher values accept a literal (objects partial-deep-match), a RegExp, or a predicate function that returns a boolean:
 

package/docs/evals/overview.mdx

@@ -58,6 +58,49 @@ export default defineEvalConfig({
 
 Everything is optional. `judge` sets the default model for [LLM-as-judge](./judge) assertions (`t.judge(...)`); omit it to use the default evaluator, `typesafe-ai/jev`. Deterministic evals make no judge requests. `reporters`, `maxConcurrency`, and `timeoutMs` round out the defaults. Config `reporters` observe every eval in the run, so set one `Braintrust()` here instead of adding it to each eval. CLI flags (`--max-concurrency`, `--timeout`) and per-eval values take precedence over the config defaults.
 
+### Run setup and teardown
+
+Use `setup` to start shared resources or run migrations before eve starts the local agent server. Return shared context directly from `setup`, then release resources in `teardown`:
+
+```ts title="evals/evals.config.ts"
+import { defineEvalConfig } from "eve/evals";
+import { startTestDatabase } from "./database.js";
+
+export default defineEvalConfig({
+  async setup() {
+    const database = await startTestDatabase();
+    return { database };
+  },
+  async teardown(context) {
+    await context?.database.close();
+  },
+});
+```
+
+`context` is inferred from the setup return value. To use that type in an eval file, pass the config's type to `defineEval`:
+
+```ts title="evals/database.eval.ts"
+import { defineEval } from "eve/evals";
+import { equals } from "eve/evals/expect";
+import type config from "./evals.config.js";
+
+export default defineEval<typeof config>({
+  async test(t) {
+    const result = await t.context.database.query("SELECT 1 AS value");
+    await t.require(result.rows[0]?.value, equals(1));
+  },
+});
+```
+
+Setup, eval bodies, and teardown share the same context object in the runner process. Class instances and functions keep their identity; context is neither serialized nor sent to the agent server. Concurrent evals share these resources, so isolate any database records they modify.
+
+`setup` can also return nothing.
+
+- Setup runs once per `eve eval` invocation, after discovery and config loading, before target startup.
+- Teardown runs after the local server and its sandbox handles shut down, including after setup, startup, or eval failures. Cleanup failures fail the command.
+
+`teardown` receives `undefined` when setup returns no context or throws before returning. In that case, setup must clean up resources that only it can access. Teardown can also be used without setup. The per-eval `timeoutMs` does not apply to setup or teardown.
+
 ## Deterministic fixture models
 
 Use `mockModel` when an eval fixture needs to exercise eve's runtime without calling a model provider. A static fixture can be one line:

package/docs/getting-started.mdx

@@ -50,7 +50,7 @@ npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
 
 ## Run the agent
 
-The terminal UI opens after interactive initialization. To return later, enter the project and run:
+The [terminal UI](/docs/guides/dev-tui) opens after interactive initialization. To return later, enter the project and run:
 
 ```bash
 cd my-agent

package/docs/guides/client/overview.mdx

@@ -34,7 +34,7 @@ The client requires the successful response to match `{ ok: true, status: "ready
 
 ## Inspect an agent
 
-Use `info()` to inspect an agent. The client requires the complete agent-info version 4 response before returning it:
+Use `info()` to inspect an agent. The client requires the complete agent-info version 6 response before returning it:
 
 ```ts
 const info = await client.info();

package/docs/guides/deployment/overview.md

@@ -3,7 +3,7 @@ title: "Overview"
 description: "Choose a deployment strategy and prepare an eve agent for production."
 ---
 
-Deploy eve to Vercel or run it as a Node service on your own infrastructure. Your deployment strategy determines the build output, workflow storage, sandbox backend, and routing. The agent’s filesystem-based configuration remains portable across these strategies.
+Deploy eve to Vercel or run it as a Node service on your own infrastructure. Your deployment strategy determines the build output, workflow storage, sandbox provider, and routing. The agent’s filesystem-based configuration remains portable across these strategies.
 
 ## Choose a deployment strategy
 

package/docs/guides/deployment/self-hosting.md

@@ -1,6 +1,6 @@
 ---
 title: "Self-Host eve"
-description: "Run an eve agent as a Node service with your own workflow storage, sandbox backend, and routing."
+description: "Run an eve agent as a Node service with your own workflow storage, sandbox provider, and routing."
 ---
 
 Self-host eve when you operate a Node service, container platform, or reverse proxy. You run eve’s Nitro server and choose the infrastructure that stores workflows and executes sandbox sessions.
@@ -46,11 +46,11 @@ The package must export a default factory or `createWorld()` function. Read cred
 
 See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
 
-## Select a sandbox backend
+## Select a sandbox provider
 
-`defaultBackend()` selects a local sandbox backend in availability order. You can instead select Docker, microsandbox, or a custom `SandboxBackend` adapter for your container, virtual machine, or isolation service.
+The default sandbox environment selects Docker, microsandbox, or just-bash according to local availability. You can select one explicitly or implement a custom provider with `defineSandboxProvider()` for your container, virtual machine, or isolation service.
 
-Don’t select `vercel()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for backend configuration and selection order.
+Don’t select `VercelSandbox.environment()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for provider configuration and selection order.
 
 ## Configure proxy routes
 
@@ -125,4 +125,4 @@ Use these guides to secure and observe the deployed agent:
 
 - [Authentication](../auth-and-route-protection): configure the host’s route policy
 - [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
-- [Sandbox](../../sandbox): select and secure a sandbox backend
+- [Sandbox](../../sandbox): select and secure a sandbox provider

package/docs/guides/deployment/vercel.mdx

@@ -27,26 +27,24 @@ A string model ID routes requests through the [Vercel AI Gateway](https://vercel
 
 Add credentials for direct model providers, tools, and connections to the Vercel project environment. Add any signing keys or passwords required by your [route authentication policy](../auth-and-route-protection). Replace `placeholderAuth()` before a browser sends a production request.
 
-## Select the sandbox backend
+## Select the sandbox environment
 
-Leave the sandbox `backend` unset to use `defaultBackend()`. On Vercel, it selects Vercel Sandbox. You can also select the backend explicitly:
+The default environment selects Vercel Sandbox on Vercel. To select it explicitly:
 
 ```typescript
 import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
+import { VercelSandbox } from "eve/sandbox/vercel";
 
-export default defineSandbox({
-  backend: vercel(),
-});
+export const environment = VercelSandbox.environment();
+export default defineSandbox(() => environment.open());
 ```
 
-See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle hooks.
+See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and lifecycle.
 
 <Callout type="info" title="Sandbox prewarming">
-  During a Vercel build, eve automatically creates or reuses a sandbox template when your sandbox
-  has `bootstrap()` or seed files. The build needs permission to create Vercel Sandbox templates,
-  and a prewarm failure stops the deployment. See the [sandbox lifecycle](../../sandbox#lifecycle)
-  for template and session setup.
+  During a Vercel build, eve creates or reuses a snapshot-backed template when an environment uses
+  `VercelSandbox.environment({prepare})` or has seed files. A prewarm failure stops the deployment.
+  See the [sandbox lifecycle](../../sandbox#lifecycle).
 </Callout>
 
 ## Deploy the agent
@@ -137,7 +135,7 @@ Vercel uses the generated output to configure these services:
 - **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
 - **Vercel Workflow**: persists and resumes durable runs, with optimistic replay preconditions enabled so stale event-log snapshots reload before they can commit
 - **Vercel Cron**: invokes authored schedules
-- **Vercel Sandbox**: runs sandbox sessions selected by `defaultBackend()`
+- **Vercel Sandbox**: runs sandbox sessions selected by the default sandbox environment
 
 ## Verify the deployment
 

package/docs/guides/dev-tui.md

@@ -17,19 +17,19 @@ The transcript remains in your terminal scrollback after you exit. Run `/help` i
 
 | Command     | Description                                                                                                                                                  |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/model`    | Choose the model, speed, and reasoning. Pass a model ID to set it directly: `/model provider/model-id`.                                                      |
+| `/reset`    | Start a fresh session.                                                                                                                                       |
+| `/clear`    | Clear the session's model-message history. `/new` is an alias.                                                                                               |
+| `/compact`  | Compact the current session's context.                                                                                                                       |
+| `/cancel`   | Cancel the current turn without discarding settled context.                                                                                                  |
 | `/login`    | Connect a ChatGPT subscription, Vercel account, or provider API key.                                                                                         |
-| `/model`    | Choose the model and its settings. Pass a model ID to set it directly: `/model provider/model-id`.                                                           |
 | `/add`      | Select and install channels, MCP connections, extensions, and observability integrations. Pass an item address to install it directly: `/add channel/slack`. |
 | `/deploy`   | Deploy the agent to Vercel production. Installs the Vercel CLI, signs in, and links the directory if needed.                                                 |
-| `/info`     | Show the resolved application, compiled artifacts, discovery diagnostics, and messaging routes.                                                              |
-| `/loglevel` | Choose which server and agent logs appear in the transcript.                                                                                                 |
 | `/traces`   | Open the local trace viewer. Pass a trace ID prefix to open a specific trace.                                                                                |
-| `/reset`    | Start a fresh session.                                                                                                                                       |
-| `/cancel`   | Cancel the current turn without discarding settled context.                                                                                                  |
-| `/clear`    | Clear the session's model-message history. `/new` is an alias.                                                                                               |
-| `/compact`  | Compact the current session's context.                                                                                                                       |
-| `/exit`     | Quit the UI.                                                                                                                                                 |
+| `/loglevel` | Choose which server and agent logs appear in the transcript.                                                                                                 |
+| `/info`     | Show the resolved application, compiled artifacts, discovery diagnostics, and messaging routes.                                                              |
 | `/help`     | List available commands.                                                                                                                                     |
+| `/exit`     | Quit the UI.                                                                                                                                                 |
 
 `/login`, `/model`, `/add`, `/deploy`, `/info`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.
 
@@ -59,9 +59,19 @@ Local discovery runs only in development. Deployments need explicitly provisione
 
 ### Models and settings
 
-`/model` opens the model picker and settings. Each completed selection applies immediately and returns to chat; there is no final Done step. A successful login or model change takes effect on the next prompt.
+`/model` walks through model, speed, and reasoning in order:
+
+1. Choose a model. Type to filter the list.
+2. Choose **Standard** or **Fast** speed, when supported.
+3. Choose a reasoning level, when the model supports reasoning settings. **Provider default** leaves the reasoning level to the provider.
 
-OpenAI, ChatGPT, and Gateway connections default to `gpt-5.6-luna-fast`; Anthropic defaults to `claude-sonnet-5`. An explicitly authored compatible model stays selected. If a new default is unavailable, eve offers the connection's available models. Dynamic or custom model expressions must be edited in `agent.ts`.
+The picker highlights your current settings when they are compatible with the selected model and skips settings that cannot be changed. Use `↑` and `↓` to move, then `Enter` to advance or apply the final choice. `Esc` or `←` returns to the previous step; at the model list, either key cancels. `Ctrl+C` cancels from any step.
+
+Changes apply together after the final choice, then the picker returns to chat. Cancelling leaves your model and settings unchanged.
+
+A successful login or model change takes effect on the next prompt.
+
+Gateway connections default to `spacexai/grok-4.7`; OpenAI and ChatGPT default to `gpt-5.6-luna-fast`; Anthropic defaults to `claude-sonnet-5`. An explicitly authored compatible model stays selected. If a new default is unavailable, eve offers the connection's available models. Dynamic or custom model expressions must be edited in `agent.ts`.
 
 ## Add an integration
 
@@ -82,6 +92,8 @@ Required authorization or deployment setup still runs for the selected item. Pre
 
 Type a message and press `Enter` to send it. When the agent asks a question or requests tool approval, respond in the prompt shown by the UI. Connection authorization can open a browser; keep local `eve dev` running until the browser returns to it.
 
+The activity line shows **Thinking** while the model reasons or waits to respond, **Generating** while it writes a response or tool input, and **Running** while tools execute. A blinking dot and elapsed time indicate progress, with token counts shown when available. The activity line disappears when the turn finishes or needs your input.
+
 While a turn is running, `Enter` sends your message immediately as steering. Before assistant output begins, the runtime interrupts pending model generation and continues the same turn with your correction. Executing tools finish safely. After output begins, steering applies at the next workflow boundary and preserves streamed text.
 
 Slash commands wait until the turn ends, except `/cancel`, which cancels directly. If the session does not support steering, messages queue for the next turn. Press `Esc` or `Ctrl+C` to cancel a turn with no queued messages. With queued messages, these keys select the oldest message for steering, or for the next turn if steering is unavailable. If a direct cancellation requested with `/cancel` or `Ctrl+C` does not settle, press `Ctrl+C` to stop waiting. The UI then returns to the prompt and asks you to press `Ctrl+C` again to exit. At an idle prompt, press `Ctrl+C` twice to exit.

package/docs/guides/frontend/overview.mdx

@@ -172,7 +172,7 @@ supplied `session` remains externally owned and is never replaced by prewarming
 
 `data.messages` are eve-owned `EveMessage[]`. Common text, reasoning, file, and dynamic-tool parts follow the [AI SDK `UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) rendering convention, but the types are not interchangeable. eve also exposes authorization and HITL metadata, and a file part's URL can be absent. Adapt those parts before passing messages to an API typed as `UIMessage[]`.
 
-When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` after admission with a working task receipt. Later task notifications wake the parent with completion, failure, or cancellation. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. Use the lower-level [TypeScript client](../client/overview#sessions) to attach to that ID when your UI needs live subagent activity. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
+When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` when the parent records a successful result, for both blocking and background invocations. A background working receipt appears in `action.result`, without a completion event. The child session can remain available for reuse. Task notifications wake the parent with completion, failure, or cancellation. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. Use the lower-level [TypeScript client](../client/overview#sessions) to attach to that ID when your UI needs live subagent activity. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
 
 ## Sending and streaming
 

package/docs/guides/hooks.md

@@ -86,6 +86,10 @@ handle can also automatically resume on later I/O. A hook failure, including a
 failed stop, follows the normal
 [hook failure behavior](#what-happens-when-a-hook-throws).
 
+For `subagent.called` and `subagent.completed`, `ctx.session.id` identifies the
+parent session. Typed handlers and `*` handlers receive this context even when
+the subagent event arrives between parent turns.
+
 ### Narrowing tool results
 
 `toolResultFrom` narrows an `action.result` event to a specific authored tool or MCP connection and returns typed output. Import it from `eve/tools`:

package/docs/memory/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Memory",
   "defaultOpen": false,
-  "pages": ["overview", "file", "custom-provider"]
+  "pages": ["overview", "file", "../patterns/multi-tenant-memory", "custom-provider"]
 }

package/docs/memory/overview.mdx

@@ -28,6 +28,10 @@ caller using the built-in file provider. Swap `provider` for
 [Supermemory](#supermemory), [Upstash AgentKit](#upstash-agentkit), or your own
 implementation and the rest of the definition stays the same.
 
+For an application with multiple tenants, follow the
+[Multi-tenant memory](/docs/patterns/multi-tenant-memory) guide to scope memory
+by authenticated tenant and caller.
+
 ## How a memory slot works
 
 A memory slot is the unit eve manages. Each slot binds one provider to an