eve 0.83.2 → 0.84.0

package/docs/patterns/multi-tenant-approvals.md

@@ -3,7 +3,7 @@ title: "Multi-Tenant Approvals"
 description: "Resolve tenant policy asynchronously for authored tools, OpenAPI operations, and MCP tools."
 ---
 
-eve's `approval` field is an async policy hook. It receives the active session, qualified tool name, tool input, and previously approved tools. That is enough to ask your application whether this tenant should allow, deny, or require human confirmation for any authored or connection tool.
+eve's `approval` field is an async policy hook. It receives the active session, qualified tool name, and tool input. That is enough to ask your application whether this tenant should allow, deny, or require human confirmation for any authored or connection tool.
 
 Use this with [multi-tenant outbound auth](./multi-tenant-auth) when your own
 API key, JWT, or app session establishes the tenant and the connection
@@ -68,7 +68,7 @@ export async function decideTenantApproval(
 
 For authored tools, `ctx.toolName` is the path-derived name such as `transfer_funds`. For connection tools, it is qualified, such as `billing__updateSubscription` or `support__add_internal_note`. Your policy service can match exact names, connection-wide patterns, roles, amounts, environments, or any other tenant-owned rule.
 
-The callback deliberately does not treat `approvedTools` as a session-wide grant. Every call is evaluated. If your policy supports approve-once behavior, consult `ctx.approvedTools` explicitly after pinning the session tenant.
+The callback evaluates every call. Return `"user-approval"` when each tenant-specific action needs a separate decision. [`once()`](/docs/human-in-the-loop#remember-approval-for-a-tool) remembers approval for the tool across all inputs in the session; it does not create tenant-specific grants.
 
 ## Apply it to an authored tool
 
@@ -187,7 +187,7 @@ Policy lookup failures should throw or deny, never silently allow. Recheck autho
 
 An approval durably pauses the session and a later request resumes it. Your HTTP boundary must ensure a caller cannot continue or stream a session owned by another tenant. Persist session ownership in your application and check it before proxying:
 
-- `POST /eve/v1/session/:sessionId`, including `inputResponses`;
+- `POST /eve/v1/session/:sessionId`, including `answers`;
 - `GET /eve/v1/session/:sessionId/stream`.
 
 Built-in approval confirms that a human with access to the session approved the call. To restrict who may respond, add an [approval response policy](/docs/human-in-the-loop#authorizing-approval-responses): it receives who responded as `response.principal` and who asked for the call as `request.principal`, and runs for both Approve and Cancel. For a four-eyes workflow, where a different person or role must approve, branch on `response.decision`: allow `cancel` so the requester can still withdraw the call, and for `approve` reject a `response.principal` that matches `request.principal` and check the responder's role.

package/docs/patterns/multi-tenant-auth.md

@@ -91,7 +91,7 @@ eve to require the authenticated user from route auth, key the step-local token
 cache by that user, and pass the projected principal into `getToken`:
 
 ```ts title="agent/lib/tenant-connection-auth.ts"
-import type { ConnectionAuthProvider, ConnectionPrincipal } from "eve/connections";
+import type { AuthorizationDefinition, ConnectionPrincipal } from "eve/connections";
 import { tenantCredentials, type TenantService } from "./tenant-credentials";
 
 function requireTenantPrincipal(principal: ConnectionPrincipal): {
@@ -107,9 +107,9 @@ function requireTenantPrincipal(principal: ConnectionPrincipal): {
   return { tenantId, userId: principal.id };
 }
 
-export function tenantBearerAuth(service: TenantService): ConnectionAuthProvider {
+export function tenantBearerAuth(service: TenantService): AuthorizationDefinition {
   return {
-    credentialOwner: "user",
+    principalType: "user",
     async getToken({ principal }) {
       const { tenantId, userId } = requireTenantPrincipal(principal);
       const credential = await tenantCredentials.getBearer(tenantId, service, { userId });

package/docs/patterns/multi-tenant-memory.md

@@ -36,7 +36,6 @@ export default defineMemory({
 
     return [tenantId, principal];
   },
-  visibility: "scope",
 });
 ```
 
@@ -66,13 +65,13 @@ query itself, not as a filter after a global search. For custom capture, use
 the provider's stable `operationId` as an idempotency key. See
 [Build a memory provider](../memory/custom-provider) for the full contract.
 
-## Choose recall visibility
+## When the caller changes
 
-The default `visibility: "scope"` hides recalled records from an earlier scope
-when the authenticated caller changes within one session. Keep that default for
-tenant-and-caller memory, as the definition above does. Set
-`visibility: "session"` only when all callers who can share the session form
-one trusted audience. Namespace remains an isolation boundary in either mode.
+eve recalls again when the authenticated caller changes within one session.
+With the scope above, a new caller is a new scope, and the slot starts over:
+what eve recalled for the earlier caller leaves model context. It can't remove
+what an earlier assistant response already said; give participants who must not
+see each other's memory separate sessions.
 
 ## Set the trust policy
 

package/docs/patterns/voice-notes.md

@@ -32,7 +32,7 @@ export default defineTool({
     }
 
     const sandbox = await ctx.getSandbox();
-    const audio = await sandbox.readBinaryFile({ path: file, abortSignal: ctx.abortSignal });
+    const audio = await sandbox.readBinaryFile({ path: file, signal: ctx.abortSignal });
     if (!audio) {
       throw new Error(`Attachment not found: ${file}. Ask the user to send the voice note again.`);
     }

package/docs/reference/cli.md

@@ -11,8 +11,7 @@ Relevant `eve` commands can run from the application root or any directory benea
 | ---------------------------------------------- | ------------------------------------------------------ |
 | `eve init [target]`                            | Create a new agent, or add one to an existing project  |
 | `eve dev`                                      | Start the local development server and terminal UI     |
-| `eve remote connect --url <url>`               | Open the terminal UI for an existing agent             |
-| `eve remote invoke --url <url> [prompt]`       | Invoke an existing agent without a terminal UI         |
+| `eve remote connect --url <url>`               | Open the terminal UI or print one remote response      |
 | `eve remote info --url <url>`                  | Inspect an existing agent                              |
 | `eve acp [url]`                                | Serve a local or existing agent through ACP over stdio |
 | `eve info`                                     | Inspect the local application                          |
@@ -199,7 +198,7 @@ Run this first when something behaves unexpectedly. It confirms a file was disco
 }
 ```
 
-`toolInputSchemas` covers only tools compiled from tool files. It does not include provider-managed tools such as `web_search`, dynamic tools, connection tools, the tools eve generates at runtime for each subagent and remote agent, or the `eve__task_wait` and `eve__task_cancel` tools. Model providers can also transform a schema before the model reads it; those changes are not reflected here. To compute the same form for an input schema in your own code, such as in a test, call `serializeModelInputSchema(schema)` from `eve/tools`; it returns JSON Schema data and does not add `taskId`.
+`toolInputSchemas` covers only tools compiled from tool files. It does not include provider-managed tools such as `web_search`, dynamic tools, connection tools, the tools eve generates at runtime for each subagent and remote agent, or the `eve__task_wait` and `eve__task_cancel` tools. Model providers can also transform a schema before the model reads it; those changes are not reflected here.
 
 ## `eve build`
 
@@ -273,7 +272,7 @@ Starts a local development server and terminal UI. To connect the UI to an exist
 
 | Flag                                | Type   | Default            | Description                                                     |
 | ----------------------------------- | ------ | ------------------ | --------------------------------------------------------------- |
-| `--host <host>`                     | string | all interfaces     | Host interface to bind                                          |
+| `--host <host>`                     | string | `127.0.0.1`        | Host interface to bind                                          |
 | `--port <port>`                     | number | `$PORT`, then 2000 | Port to listen on                                               |
 | `--no-ui`                           | flag   | UI on              | Start the server without an interactive UI                      |
 | `--resume`                          | flag   | off                | Attempt recovery of retained runs from previous dev invocations |
@@ -288,6 +287,8 @@ Starts a local development server and terminal UI. To connect the UI to an exist
 | `--context-size <tokens>`           | number | none               | Model context window size                                       |
 | `--logs <mode>`                     | enum   | `error`            | Display `none`, `error`, `warn`, `debug`, or `all` logs         |
 
+`localDev()` refuses callers whose connection comes from another machine. When `--host` binds another interface, such as `0.0.0.0`, those callers need another authenticator in the channel's `auth` list. A tunnel or reverse proxy on the same machine, such as ngrok, cloudflared, or a local nginx, connects from this machine, so every caller it forwards still gets `local-dev`. Put an authenticator in front of any dev server you expose that way.
+
 Local development mounts bundled development extensions without adding files to your project. Pass `--no-default-extensions` to disable them. See [Self-Modification](../guides/self-modification) for details.
 
 A fresh `eve init` opens the TUI and reuses an available model connection or opens `/login`. No Vercel project, channels, integrations, or review step is required before chat. Use `/model` to change models and settings, and `/add` to install an addition. Other `--input` text stays editable in the prompt. See [Terminal UI](../guides/dev-tui) for credential precedence and login options.
@@ -326,7 +327,7 @@ Use `eve remote` only with an explicit existing agent URL:
 
 ```bash
 eve remote connect --url https://agent.example.com
-eve remote invoke --url https://agent.example.com "Summarize station telemetry"
+eve remote connect --url https://agent.example.com --print "Summarize station telemetry"
 eve remote info --url https://agent.example.com
 ```
 
@@ -335,28 +336,13 @@ eve remote info --url https://agent.example.com
 ### `eve remote connect`
 
 ```bash
-eve remote connect --url <url> [-H "Name: value"]
+eve remote connect --url <url> [--input <text>] [-H "Name: value"]
+eve remote connect --url <url> --print <prompt> [-H "Name: value"]
 ```
 
-Use `-H, --header <header>` for a bearer token or another custom request header; repeat it for multiple headers. For HTTP Basic authentication, put credentials in the URL. eve sends them as a Basic `Authorization` header and removes them from the target URL.
-
-### `eve remote invoke`
+Without `--print`, `connect` requires a terminal and opens the interactive UI. Pass `--print` and a prompt to send one message without a terminal UI. eve writes only the final assistant text to stdout, then exits. It writes errors to stderr and exits nonzero if the turn fails, is cancelled, needs input or authorization, or the stream ends before the turn settles. The error includes the session ID when the server has accepted the message. `--print` starts a new conversation each time and does not answer pending requests; to answer that session's pending request or script multi-turn sessions, use the `eve/client` API. `--input` only pre-fills the interactive UI and cannot be used with `--print`.
 
-```bash
-eve remote invoke --url <url> [prompt] [--resume] [-H "Name: value"] [--scope <team>]
-```
-
-Invokes an existing agent without opening the terminal UI. It emits JSON after the invocation completes or reaches a blocking input or authorization event.
-
-| Option                  | Type   | Default  | Description                                     |
-| ----------------------- | ------ | -------- | ----------------------------------------------- |
-| `<url>`                 | string | required | Existing eve agent URL                          |
-| `[prompt]`              | string | none     | Prompt, follow-up, or answer to a pending input |
-| `-H, --header <header>` | string | none     | Request header for the URL target; repeatable   |
-| `--resume`              | flag   | off      | Read a previous resumable result from stdin     |
-| `--scope <team>`        | string | current  | Vercel team that owns the URL target            |
-
-`--resume` reads a complete previous result from stdin. Supply text for a `ready` follow-up or pending input. An `authorization-required` result lists every unresolved challenge; complete them, then resume without text. Pass headers and scope again when resuming. Paused invocations exit `3`; failures exit `1`. If a waiting invocation receives `SIGINT` or `SIGTERM` after acceptance, it emits a final resumable `running` result before exiting.
+Use `-H, --header <header>` for a bearer token or another custom request header; repeat it for multiple headers. For HTTP Basic authentication, put credentials in the URL. eve sends them as a Basic `Authorization` header and removes them from the target URL.
 
 ### `eve remote info`
 
@@ -382,7 +368,7 @@ A log id is the file name without `.log` (for example `dev-2026-07-15T12-00-00.0
 
 `eve logs` prints nothing but records — no path banner on either stream — so `eve logs 2>&1 | jq -c .` always parses. Discover ids and file paths with `eve logs list`; `eve logs list --json` emits a machine-readable array with `id`, `path`, `startedAt`, and `sizeBytes`.
 
-`eve logs --events` resolves session events (`session.started`, `turn.failed`, message deltas, …) from the local workflow store (`.eve/.workflow-data`) at query time and interleaves them into the output by timestamp as `source: "event"` records — the log file itself never stores them, so nothing is duplicated at capture time. Selection is by the log's time window (its start through the next log's start), so events from concurrently running `eve dev` processes may appear.
+`eve logs --events` resolves session events (`session.started`, `turn.settled`, content deltas, …) from the local workflow store (`.eve/.workflow-data`) at query time and interleaves them into the output by timestamp as `source: "event"` records — the log file itself never stores them, so nothing is duplicated at capture time. Selection is by the log's time window (its start through the next log's start), so events from concurrently running `eve dev` processes may appear.
 
 Each log has a same-named `.dump` sibling holding environment diagnostics and session stats as one JSON document. `eve logs --dump` (with or without a log id) prepends that document to the JSONL log body; the combined output is a valid JSON value stream (`eve logs --dump | jq -c .`), one self-contained report to attach to an issue. When a log has no dump, the flag is silently a no-op.
 

package/docs/reference/typescript-api.md

@@ -28,14 +28,37 @@ export default defineTool({
 });
 ```
 
+## Integration dependencies
+
+Install the framework packages for the integration you import. These are optional peers of eve;
+using another entry does not require them.
+
+| Entry                                      | Required integration packages                         |
+| ------------------------------------------ | ----------------------------------------------------- |
+| `eve/react`                                | `react` 19 (and its React typings in TypeScript apps) |
+| `eve/vue`                                  | `vue` 3.5 or later in v3                              |
+| `eve/svelte`                               | `svelte` 5                                            |
+| `eve/next`                                 | `next` 16 and `react` 19                              |
+| `eve/sveltekit`, `eve/tanstack`            | `vite` 8.3.1 or later in v8                           |
+| `eve/nuxt`                                 | `@nuxt/kit` 4 and `@nuxt/schema` 4                    |
+| Chat SDK, Linq, and Photon channels        | `chat` 4.42 or later in v4                            |
+| `eve/channels/linq`                        | Also `@linqapp/sdk` 0.47.1 or later in v0.47          |
+| `eve/sandbox/just-bash`                    | `just-bash` 3.6 or later in v3                        |
+| `@vercel/connect/eve` with eve connections | `@vercel/connect` 2.5.2 or later in v2                |
+
+Connections with `experimental.events` require a static Connect auth provider with its events bridge.
+SDK-backed handles use the SDK classes installed in your app, not copies bundled with eve.
+
+The AI SDK is a required peer and has its own Zod peer requirement. To type the results of
+`client.info()` and `client.health()`, import `AgentInfoResult`, its entry types (such as
+`AgentInfoToolEntry`), and `HealthResult` from `eve/client`.
+
 ## The define\* helpers
 
 | Helper                                                | Import from                                                             | Authored at                                                                            | Guide                                                  |
 | ----------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
 | `defineAgent`                                         | `eve`                                                                   | `agent/agent.ts`                                                                       | [agent.ts](../agent-config)                            |
 | `defineTool`                                          | `eve/tools`                                                             | `agent/tools/<name>.ts`                                                                | [Tools](../tools)                                      |
-| `defineDurableCallback`                               | `eve/tools`                                                             | provider-package dynamic tool factories                                                | [Dynamic capabilities](../guides/dynamic-capabilities) |
-| `defineDurableSchema`                                 | `eve/tools`                                                             | provider-package dynamic input and output schemas                                      | [Dynamic capabilities](../guides/dynamic-capabilities) |
 | `defineWorkflowTool`                                  | `eve/tools`                                                             | `agent/tools/<name>.ts`                                                                | [Workflow tools](../tools/workflows)                   |
 | `defineDynamic`                                       | `eve`, `eve/tools`, `eve/skills`, `eve/instructions`, `eve/connections` | dynamic model or subagent `agent.ts`; `agent/{tools,skills,instructions,connections}/` | [Dynamic capabilities](../guides/dynamic-capabilities) |
 | `defineMcpClientConnection`                           | `eve/connections`                                                       | `agent/connections/<name>.ts`                                                          | [MCP connections](../connections/mcp)                  |
@@ -59,22 +82,15 @@ 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 and types such as `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDurableSchema`, `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`, `agentRouter` comes from `eve/tools/agent-router`, `sleep` comes from `eve/tools/sleep`, `noReply` comes from `eve/tools/no_reply`, 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`, `agentRouter` comes from `eve/tools/agent_router`, `sleep` comes from `eve/tools/sleep`, `noReply` comes from `eve/tools/no_reply`, 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`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
 `webSearch({ provider })` selects `"exa"`, `"parallel"`, `"browserbase"`, or `"native"` for AI Gateway search using the Gateway model's credentials. `"native"` uses the model vendor's own search for OpenAI, Anthropic, and Gemini 3 and later models; set `fallback` to `"exa"`, `"parallel"`, or `"browserbase"` to give other Gateway models search, which they otherwise don't get. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.
 
-`defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.
+`defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Dynamic instructions use `defineDynamic(ctx => defineInstructions(...))` or return `null`. The retired `{ markdown: string }` definition is rejected.
 
-The `eve/connections` version of `defineDynamic` accepts `session.started` and
-`turn.started` handlers returning one MCP or OpenAPI connection definition, a
-map of connection definitions, or `null`. Its resolver context exposes
-authenticated session identity and `channel.kind`, but not conversation history,
-delivery payloads, tool inputs, model outputs, or free-form channel metadata. An
-authenticated returned definition must set `instanceKey` to a stable,
-non-secret account or tenant identifier so durable authorization resumes cannot
-cross resolved instances.
+Dynamic connections use `defineDynamic(ctx => value)`, returning one MCP or OpenAPI connection definition, a map, or `null`. Functions read committed session context and can load conversation history with `ctx.messages()`. Set `instanceKey` to a stable, non-secret account or tenant identifier so authorization resumes cannot cross resolved instances. See [Dynamic capabilities](../guides/dynamic-capabilities).
 
 ## Authored module lifecycle
 
@@ -99,7 +115,9 @@ import icon from "../../assets/icon.png";
 import template from "../../prompts/template.txt?raw";
 ```
 
-`?raw` embeds the file as UTF-8 text. Other non-code asset imports produce a data URL with an inferred media type. Compilation, local development, and production builds use the same resolution behavior. Imports that escape the project package are rejected; package those files with the application instead.
+`?raw` embeds any file as UTF-8 text, including code files such as `.json` and files without an extension, such as a `Dockerfile`. Other non-code asset imports produce a data URL with an inferred media type. Compilation, local development, and production builds use the same resolution behavior.
+
+A workspace package bundled from TypeScript source can import its own assets the same way. Each import may reach files inside the project package or inside the package that contains the importing module. Imports that escape both are rejected; package those files with the application or the workspace package instead.
 
 ## Runtime context (`ctx`)
 
@@ -117,53 +135,62 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 
 ## Imports at a glance
 
-| Import                                                                            | Holds                                                                                                                          |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `eve`                                                                             | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                                                        |
-| `eve/tools`                                                                       | `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDurableSchema`, `defineDynamic`, `disableTool`, tool types |
-| `eve/tools/{bash,read_file,write_file,web_fetch,glob,grep}`                       | Individual reusable tool definitions                                                                                           |
-| `eve/tools/approval`                                                              | Approval types and `auto`, `always`, `once`, `never`                                                                           |
-| `eve/tools/ask_question`                                                          | Opt-in `askQuestion` tool factory                                                                                              |
-| `eve/tools/web_search`                                                            | Provider-managed `webSearch` configuration                                                                                     |
-| `eve/tools/workflow`                                                              | Runtime-generated `workflow` tool factory                                                                                      |
-| `eve/tools/sleep`                                                                 | Opt-in durable `sleep` tool                                                                                                    |
-| `eve/tools/no_reply`                                                              | Opt-in `noReply` tool factory                                                                                                  |
-| `eve/connections`                                                                 | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`                                                        |
-| `eve/channels`                                                                    | `defineChannel`, `disableRoute`, route verbs                                                                                   |
-| `eve/channels/eve`                                                                | `eveChannel`                                                                                                                   |
-| `eve/channels/auth`                                                               | `localDev`, `vercelOidc`, `placeholderAuth`                                                                                    |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}`                       | platform channel factories                                                                                                     |
-| `eve/hooks`                                                                       | `defineHook`                                                                                                                   |
-| `eve/schedules`                                                                   | `defineSchedule`                                                                                                               |
-| `eve/skills`                                                                      | `defineSkill`, `defineDynamic`                                                                                                 |
-| `eve/instructions`                                                                | `defineInstructions`, `defineDynamic`                                                                                          |
-| `eve/memory`                                                                      | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types                                                           |
-| `eve/memory/scope`                                                                | `byPrincipal` and memory scope helpers                                                                                         |
-| `eve/memory/file`                                                                 | `fileMemory`, `inMemory`, and the conditional document backend contract                                                        |
-| `eve/memory/file/vercel`                                                          | `vercelBlob` and Vercel Blob backend options                                                                                   |
-| `eve/context`                                                                     | `defineState`, session and state types                                                                                         |
-| `eve/sandbox`                                                                     | `defineSandbox`, `defineParentSandbox`, `DefaultSandbox`, and sandbox session and network policy types                         |
-| [`eve/sandbox/provider`](../sandbox/custom-providers)                             | `defineSandboxProvider`, provider errors, `SANDBOX_AGENT_ENV`, and connection and lifecycle types                              |
-| [`eve/sandbox/docker`](../sandbox/docker)                                         | `DockerSandbox` and Docker environment and session types                                                                       |
-| [`eve/sandbox/vercel`](../sandbox/vercel)                                         | `VercelSandbox` and Vercel environment, session, and mount types                                                               |
-| [`eve/sandbox/just-bash`](../sandbox/just-bash)                                   | `JustBashSandbox` and just-bash environment types                                                                              |
-| `eve/instrumentation`                                                             | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
-| `eve/instrumentation/otel`                                                        | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
-| `eve/local-dev`                                                                   | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
-| [`eve/models`](../guides/decide)                                                  | Automatic model selection with `auto`                                                                                          |
-| `eve/models/openai`                                                               | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |
-| `eve/models/anthropic`                                                            | `anthropic`                                                                                                                    |
-| [`eve/ai`](../guides/decide#decide-inside-a-tool)                                 | Standalone `decide`                                                                                                            |
-| `eve/evals`                                                                       | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                                                                      |
-| `eve/evals/expect`                                                                | `includes`, `equals`, `matches`, `similarity`                                                                                  |
-| `eve/evals/reporters`                                                             | `Braintrust`, `JUnit`, `EvalReporter`                                                                                          |
-| `eve/evals/loaders`                                                               | `loadJson`, `loadYaml`                                                                                                         |
-| `eve/react`, `eve/vue`, `eve/svelte`                                              | `useEveAgent`                                                                                                                  |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`, `eve/tanstack`                           | framework bundler plugins                                                                                                      |
-| [`eve/client`](../guides/client/overview)                                         | `Client`, `ClientSession`, health and agent-info schemas, response errors                                                      |
-| [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process                                                                             |
-
-Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
+| Import                                                                            | Holds                                                                                                             |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `eve`                                                                             | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                                           |
+| `eve/tools`                                                                       | `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, tool types                                    |
+| `eve/tools/{bash,read_file,write_file,web_fetch,glob,grep}`                       | Individual reusable tool definitions                                                                              |
+| `eve/tools/approval`                                                              | Approval types and `auto`, `always`, `once`, `never`                                                              |
+| `eve/tools/ask_question`                                                          | Opt-in `askQuestion` tool definition                                                                              |
+| `eve/tools/web_search`                                                            | Provider-managed `webSearch` configuration                                                                        |
+| `eve/tools/workflow`                                                              | Runtime-generated `workflow` tool factory                                                                         |
+| `eve/tools/sleep`                                                                 | Opt-in durable `sleep` tool                                                                                       |
+| `eve/tools/no_reply`                                                              | Opt-in `noReply` tool definition                                                                                  |
+| `eve/connections`                                                                 | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`                                           |
+| `eve/channels`                                                                    | `defineChannel`, `disableRoute`, route verbs, `isChannel`, channel metadata types                                 |
+| `eve/channels/eve`                                                                | `eveChannel`                                                                                                      |
+| `eve/channels/auth`                                                               | `localDev`, `vercelOidc`, `placeholderAuth`                                                                       |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}`                       | platform channel factories                                                                                        |
+| `eve/hooks`                                                                       | `defineHook`                                                                                                      |
+| `eve/schedules`                                                                   | `defineSchedule`                                                                                                  |
+| `eve/skills`                                                                      | `defineSkill`, `defineDynamic`                                                                                    |
+| `eve/instructions`                                                                | `defineInstructions`, `defineDynamic`                                                                             |
+| `eve/memory`                                                                      | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types                                              |
+| `eve/memory/scope`                                                                | `byPrincipal` and memory scope helpers                                                                            |
+| `eve/memory/file`                                                                 | `fileMemory`, `inMemory`, and the conditional document backend contract                                           |
+| `eve/memory/file/vercel`                                                          | `vercelBlob` and Vercel Blob backend options                                                                      |
+| `eve/context`                                                                     | `defineState`, session and state types                                                                            |
+| `eve/sandbox`                                                                     | `defineSandbox`, `defineParentSandbox`, `DefaultSandbox`, and sandbox session and network policy types            |
+| [`eve/sandbox/provider`](../sandbox/custom-providers)                             | `defineSandboxProvider`, provider errors, `SANDBOX_AGENT_ENV`, and connection and lifecycle types                 |
+| [`eve/sandbox/docker`](../sandbox/docker)                                         | `DockerSandbox` and Docker environment and session types                                                          |
+| [`eve/sandbox/vercel`](../sandbox/vercel)                                         | `VercelSandbox` and Vercel environment, session, and mount types                                                  |
+| [`eve/sandbox/just-bash`](../sandbox/just-bash)                                   | `JustBashSandbox` and just-bash environment types                                                                 |
+| `eve/instrumentation`                                                             | `defineInstrumentation`, `disableInstrumentation`, `InstrumentationEvent<K>`, lifecycle provider types            |
+| `eve/instrumentation/otel`                                                        | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                 |
+| `eve/local-dev`                                                                   | `getLocalDevCapability`, `LocalDevCapability`                                                                     |
+| [`eve/models`](../guides/decide)                                                  | Automatic model selection with `auto`                                                                             |
+| `eve/models/openai`                                                               | `openai`, `chatgpt`                                                                                               |
+| `eve/models/anthropic`                                                            | `anthropic`                                                                                                       |
+| [`eve/ai`](../guides/decide#decide-inside-a-tool)                                 | Standalone `decide`                                                                                               |
+| `eve/evals`                                                                       | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                                                         |
+| `eve/evals/expect`                                                                | `includes`, `equals`, `matches`, `similarity`                                                                     |
+| `eve/evals/reporters`                                                             | `braintrustReporter`, `junitReporter`, `EvalReporter`                                                             |
+| `eve/evals/loaders`                                                               | `loadJson`, `loadYaml`                                                                                            |
+| `eve/react`, `eve/vue`, `eve/svelte`                                              | `useEveAgent`                                                                                                     |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`, `eve/tanstack`                           | framework bundler plugins                                                                                         |
+| [`eve/client`](../guides/client/overview)                                         | `Client`, `ClientSession`, health and agent-info schemas, response errors                                         |
+| [`eve/sessions`](../guides/client/messages#reusable-delivery-reads)               | `Delivery`, `DeliveryResult`, read options, `SessionReader`, authenticated `Session`, and `SessionNotActiveError` |
+| [`eve/events`](../concepts/sessions-runs-and-streaming#query-session-state)       | Facts, opaque `SessionView`, immutable observations, and query/fold functions                                     |
+| [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process                                                                |
+
+Exported types ship from the entry point that owns them (for example `ToolDefinition` and `ToolContext` from `eve/tools`). Import fact and view types from `eve/events`, `SessionContext` and `HistoryMessage` from `eve/context`, and assertion types and `ToolStub` from `eve/evals`. Frontend hook entries also export the types their hooks return. Shared delivery/session contracts
+have one home, `eve/sessions`; client factories and transport-specific types stay in `eve/client`.
+`SessionInfo` from `eve/context` is callback metadata, not a reader or an operable session.
+`ChannelContext` from `eve/channels` separates session information from continuation aliasing.
+
+`HistoryMessage` and the sandbox session, process, result, and method-option types are eve-owned. Their declarations do not change with your app's AI SDK peer version. Named judge, mock-model, approval, and disabled-marker types remain public for reusable helpers and declaration emission.
+
+The `exports` field in `packages/eve/package.json` lists every package entry point. `eve/experimental/*` and `eve/internal/*` have no compatibility promise. The CLI setup wizard is not a public authoring API; Agent Builder's scaffold integration lives at `eve/internal/scaffold`.
 
 ## Direct provider models
 
@@ -184,7 +211,7 @@ export default defineAgent({
 });
 ```
 
-Pass another bare OpenAI model slug to override the default. `experimental_chatgpt()` remains as a deprecated alias.
+Pass another bare OpenAI model slug to override the default. The retired `experimental_chatgpt` alias is not exported.
 
 `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.
 

package/docs/sandbox/custom-providers.mdx

@@ -60,9 +60,9 @@ export const AcmeSandbox = defineSandboxProvider({
           throw new SandboxSessionGoneError(`Acme machine "${state.name}" is gone.`);
         return connect(machine);
       },
-      async onSessionEnd(ctx, state, { abortSignal }) {
+      async onSessionEnd(ctx, state, { signal }) {
         await acme.machines.destroyIfExists(state?.name ?? nameFor(ctx.session.id), {
-          signal: abortSignal,
+          signal,
         });
       },
     };
@@ -71,19 +71,18 @@ export const AcmeSandbox = defineSandboxProvider({
 
 function connect(machine: AcmeMachine): SandboxConnection {
   return {
-    spawn: ({ abortSignal, command, env, workingDirectory }) =>
+    spawn: ({ signal, command, env, workingDirectory }) =>
       machine.exec({
         argv: ["bash", "-lc", command],
         cwd: workingDirectory,
         env,
-        signal: abortSignal,
+        signal,
       }),
     // Acme returns `null` for a missing path and rejects for a directory.
-    readFile: ({ abortSignal, path }) => machine.files.read(path, { signal: abortSignal }),
-    writeFiles: ({ abortSignal, files }) =>
-      machine.files.write(files, { mkdirs: true, signal: abortSignal }),
-    removePath: ({ abortSignal, force, path, recursive }) =>
-      machine.files.remove(path, { force, recursive, signal: abortSignal }),
+    readFile: ({ signal, path }) => machine.files.read(path, { signal }),
+    writeFiles: ({ signal, files }) => machine.files.write(files, { mkdirs: true, signal }),
+    removePath: ({ signal, force, path, recursive }) =>
+      machine.files.remove(path, { force, recursive, signal }),
     stop: () => machine.suspend(),
   };
 }
@@ -111,10 +110,10 @@ export default defineSandbox(() => environment.open({ egress: "deny-all" }));
 
 A `SandboxConnection` is the byte-level link to one sandbox. Each method has a fixed contract:
 
-- `spawn({ command, workingDirectory, env, abortSignal })` runs `command` as a Bash login-shell script (`bash -lc`) in `workingDirectory`, with the sandbox's environment plus `env`. `env` holds only the per-call variables. Aborting kills the process tree. It resolves to a process with `stdout` and `stderr` byte streams, `wait()`, and `kill()`.
-- `readFile({ path, abortSignal })` resolves to the file's bytes or a byte stream, or to `null` only when the path does not exist. A directory or an unreadable path rejects.
-- `writeFiles({ files, abortSignal })` writes every file, creating missing parent directories and overwriting existing files. It is the only write primitive.
-- `removePath({ path, force, recursive, abortSignal })` removes a file or directory. `force` ignores a missing path, and `recursive` removes a non-empty directory.
+- `spawn({ command, workingDirectory, env, signal })` runs `command` as a Bash login-shell script (`bash -lc`) in `workingDirectory`, with the sandbox's environment plus `env`. `env` holds only the per-call variables. Aborting kills the process tree. It resolves to a process with `stdout` and `stderr` byte streams, `wait()`, and `kill()`.
+- `readFile({ path, signal })` resolves to the file's bytes or a byte stream, or to `null` only when the path does not exist. A directory or an unreadable path rejects.
+- `writeFiles({ files, signal })` writes every file, creating missing parent directories and overwriting existing files. It is the only write primitive.
+- `removePath({ path, force, recursive, signal })` removes a file or directory. `force` ignores a missing path, and `recursive` removes a non-empty directory.
 - `stop()` releases compute and keeps the sandbox's files.
 - `close()` is optional. It releases what this process holds for the connection, such as a local interpreter or child processes, without touching the sandbox. eve calls it whenever it lets go of a connection: when the step that opened it ends, after `stop()`, and before deletion. A connection lasts at most one step, so the next step resumes the sandbox through a new connection.
 - `extensions` is optional. It is a plain object whose own properties eve merges onto the session, such as `setNetworkPolicy()`. Use closures rather than class methods, because eve does not copy inherited members.
@@ -175,7 +174,7 @@ Validate the shape of your own state in `resume()`. When you change it incompati
 
 `onSessionEnd()` deletes whatever exists for `ctx.session.id`. `state` is `null` when the session never recorded it, for example when only a subagent that shares the sandbox opened it, or when a step failed before its checkpoint, so find the sandbox from the session id. The method must succeed when nothing exists and must be idempotent, because eve retries the cleanup step. eve logs an exhausted failure without replacing the session's outcome.
 
-`sandbox.delete()` uses the same method with `reason: "deleted"` and the caller's `abortSignal`, so a provider has one deletion path. A subagent that shares its parent's sandbox never calls it, because cleanup belongs to the parent. An `invokeTool` call without a key calls it when the call ends if the tool requested the sandbox.
+`sandbox.delete()` uses the same method with `reason: "deleted"` and the caller's `signal`, so a provider has one deletion path. A subagent that shares its parent's sandbox never calls it, because cleanup belongs to the parent. An `invokeTool` call without a key calls it when the call ends if the tool requested the sandbox.
 
 ## Bake files into templates
 

package/docs/sandbox/default.mdx

@@ -62,7 +62,7 @@ export default defineSandbox(() => environment.open());
 | `prepare`  | Any provider          | Setup captured in the prepared environment. Replaces a `prepare` set inside the provider options.                                   |
 | `docker`   | Docker is selected    | The options of [`DockerSandbox.environment()`](/docs/sandbox/docker#environment-options), such as `image`, `env`, and `pullPolicy`. |
 | `vercel`   | Vercel is selected    | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials.               |
-| `justBash` | just-bash is selected | The options of [`JustBashSandbox.environment()`](/docs/sandbox/just-bash), such as `autoInstall` and `customCommands`.              |
+| `justBash` | just-bash is selected | `autoInstall` and `prepare`. Use [`JustBashSandbox.environment()`](/docs/sandbox/just-bash) for `customCommands` or `filesystem`.   |
 
 Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects. just-bash runs no native binaries, so commands such as `apt-get` fail there during `eve dev`.
 

package/docs/sandbox/docker.mdx

@@ -28,6 +28,16 @@ When `agent/sandbox/Dockerfile` exists, eve builds it during preparation and use
 
 `DockerSandbox.dockerfile()` does not accept an `image` option, which makes the Dockerfile convention explicit in your sandbox file.
 
+## eve's default image
+
+eve's default image runs Ubuntu with Node.js 24, npm, Python 3, git, ripgrep, jq, and curl. Commands run as the `vercel-sandbox` user in `/workspace`, with passwordless `sudo`. Docker pulls it from `ghcr.io/vercel/eve`, and [Vercel Sandbox](/docs/sandbox/vercel) uses the same image from `vcr.vercel.com/vercel/eve/base`.
+
+The default image does not include pnpm or pip, so install them in `prepare` when your agent needs them. `npm install -g pnpm` installs pnpm for the `vercel-sandbox` user. Ubuntu's system Python refuses `pip install`, so install `python3-venv` with `sudo apt-get install -y python3-venv`, then use the pip inside a virtual environment. The [analysis tutorial](/docs/tutorial/run-analysis#install-the-chart-dependencies) shows the Python setup. Preparation runs when eve builds the template, so it needs network access to the package registries.
+
+Each eve release pins one tag of the default image. The tag comes from the image definition, not the eve version. Prepared templates include the image reference, so an eve upgrade that keeps the same image reuses them. A release that changes the image rebuilds them once.
+
+To run a different published tag, set `EVE_SANDBOX_IMAGE_TAG` in both the build and runtime environments. eve applies the tag to both registries.
+
 ## Environment options
 
 Image, pull policy, environment variables, and `prepare` belong to the reusable environment. During preparation, eve starts a temporary container, seeds workspace and skill files, runs your `prepare`, and commits the result as the recorded template image.

package/docs/sandbox/index.mdx

@@ -168,6 +168,10 @@ To run sandboxes on a backend eve does not ship, define a provider with `defineS
 | [Docker](/docs/sandbox/docker)       | Local containers from the default image, an existing OCI image, or a Dockerfile.            |
 | [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation.            |
 
+For SDK-specific just-bash commands or filesystem factories, use `JustBashSandbox.environment()`
+from `eve/sandbox/just-bash`. `DefaultSandbox` keeps only `autoInstall` and `prepare` for its
+just-bash fallback.
+
 ## Lifecycle
 
 Session-owned sandboxes persist across turns and deployments while their provider state remains available. `sandbox.stop()` stops compute without deleting persisted state; a later access resumes that state directly. `sandbox.delete()` deletes the sandbox and clears provider state, so the next `ctx.getSandbox()` reruns the selector, and the provider starts a fresh sandbox under the same session key from the current environment. If the native sandbox is gone when a session resumes, for example after a local daemon restart, a removed container, or a deleted just-bash session directory, eve does the same: the session continues in a fresh sandbox, without the lost sandbox's files. eve also starts a fresh sandbox when the recorded state belongs to another provider or state protocol than the current environment, for example after you change providers; the old sandbox is not deleted. When the durable session reaches a terminal outcome, eve calls the provider's `onSessionEnd()` hook to delete what remains under the session's key.

package/docs/sandbox/vercel.mdx

@@ -11,7 +11,7 @@ import { VercelSandbox } from "eve/sandbox/vercel";
 
 export const environment = VercelSandbox.environment({
   prepare: async (sandbox) => {
-    await sandbox.run({ command: "pnpm install --frozen-lockfile" });
+    await sandbox.run({ command: "npm ci" });
   },
 });
 
@@ -59,7 +59,7 @@ When a live session sandbox does not exist, eve creates it directly from that sn
 
 When the environment has no `prepare` callback, no managed workspace or skill files, and no `source`, a snapshot would contain only the base runtime. eve skips it: the build records no snapshot ID, and each new session sandbox starts from the image and installs the base runtime itself. A `source` always produces a snapshot, so sessions start from what the build captured instead of fetching the source again.
 
-A new session sandbox created from a prepared snapshot of the standard eve image, without Drive mounts, inherits the base runtime the build checked and runs no setup command. Existing or resumed sandboxes, custom images or snapshot sources, sandboxes with Drive mounts, and sandboxes created without a prepared snapshot still run base-runtime setup when eve attaches them.
+A new session sandbox created from a prepared snapshot of [eve's default image](/docs/sandbox/docker#eves-default-image), without Drive mounts, inherits the base runtime the build checked and runs no setup command. Existing or resumed sandboxes, custom images or snapshot sources, sandboxes with Drive mounts, and sandboxes created without a prepared snapshot still run base-runtime setup when eve attaches them.
 
 ## Initialize after open
 
@@ -136,7 +136,7 @@ const sandboxName = sandbox.name;
 
 ## Mount a Drive
 
-A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. Install `@vercel/sandbox` in your app, create or retrieve the Drive before calling `open()`, then pass it in `mounts` under an absolute path:
+A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. Install `@vercel/sandbox` in your app, create or retrieve the Drive before calling `open()`, then pass its name and mount mode in `mounts` under an absolute path:
 
 ```bash
 pnpm add @vercel/sandbox
@@ -159,7 +159,7 @@ export default defineSandbox(async () => {
 
   return environment.open({
     mounts: {
-      "/data": drive,
+      "/data": { drive: drive.name, mode: "read-write" },
     },
   });
 });
@@ -178,12 +178,12 @@ To share a point-in-time view across concurrent sandboxes, mount a read-only sna
 ```ts
 return environment.open({
   mounts: {
-    "/data": drive.snapshot(),
+    "/data": { drive: drive.name, mode: "snapshot" },
   },
 });
 ```
 
-Before mounting `drive.snapshot()`, seed a new Drive by mounting it read-write and writing at least one file. An uninitialized Drive cannot be mounted as a snapshot.
+Before mounting a Drive snapshot, seed a new Drive by mounting it read-write and writing at least one file. An uninitialized Drive cannot be mounted as a snapshot.
 
 Each `mounts` entry is a `Drive`, which mounts read-write, or a `{ drive, mode }` reference to an existing Drive by name, where `mode` is `"read-write"` or `"snapshot"`. `drive.snapshot()` returns such a reference.