eve 0.82.0 → 0.83.1

package/docs/sandbox/troubleshooting.mdx

@@ -0,0 +1,215 @@
+---
+title: "Sandbox Troubleshooting"
+description: "Causes and fixes for common eve sandbox errors in the sandbox file, after a build, when a session resumes, and during eve dev."
+---
+
+Sections whose heading is in code format start with the beginning of an error message, so you can search this page for the text you see. Most sandbox errors come from one of three mismatches: the sandbox file does not match what eve expects, the build output does not match the runtime, or a session's recorded sandbox does not match the current agent.
+
+## Errors in the sandbox file
+
+### `must export an environment`
+
+```text
+Sandbox "sandbox.ts" must export an environment.
+```
+
+eve compiles the sandbox file during `eve build` and `eve dev`, and it needs the environment as a named `environment` export so it can prepare it before any session exists. Export the environment that the selector opens:
+
+```ts title="agent/sandbox.ts"
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+
+export const environment = DefaultSandbox.environment();
+export default defineSandbox(() => environment.open());
+```
+
+### `opened an environment other than the one it exports`
+
+```text
+Sandbox "sandbox.ts" opened an environment other than the one it exports as `environment`.
+```
+
+The selector called `open()` on a different environment object than the exported `environment`. This happens when the selector creates an environment inline, such as `DefaultSandbox.environment().open()`, or imports another sandbox file's environment. Create the environment once at module scope, export it, and call `environment.open()` on that export.
+
+### `can open only one sandbox`
+
+```text
+A sandbox definition can open only one sandbox.
+```
+
+The selector called `environment.open()` more than once. Call `environment.open()` once in the `defineSandbox()` selector and return that sandbox.
+
+### `can only open sandboxes inside defineSandbox()`
+
+```text
+Sandbox environments can only open sandboxes inside defineSandbox().
+```
+
+Code outside the `defineSandbox()` selector called `environment.open()`, for example a tool or a module's top level. Only the selector opens the sandbox. From tools and other runtime code, use `ctx.getSandbox()` to reach the session's sandbox, or `ctx.getSandbox(environment)` to keep the provider-specific session type.
+
+### `selects parent.sandbox but agent node ... has no parent`
+
+```text
+Sandbox "sandbox.ts" selects parent.sandbox but agent node "..." has no parent.
+```
+
+The sandbox file uses `defineParentSandbox()`, but the agent is not a declared subagent, so it has no parent sandbox to share. eve reports this when it loads the agent graph. Only a declared subagent can [share its parent's sandbox](/docs/sandbox#share-a-parent-sandbox). Give this agent its own sandbox file with `defineSandbox()` and an exported environment.
+
+## Errors after a build or deploy
+
+Production never prepares sandbox environments. `eve build` prepares them and records one artifact for each agent sandbox, such as a Docker image, a Vercel snapshot, or a just-bash template, and the runtime only uses those recorded artifacts.
+
+### `No prepared ... sandbox environment is recorded`
+
+```text
+No prepared "docker" sandbox environment is recorded for agent node "...".
+```
+
+The deployed build output has no prepared artifact for this agent. This usually means the output came from `eve build --skip-sandbox-prewarm`, which [the CLI reference](/docs/reference/cli) marks as not deployable. Run `eve build` without that flag and deploy its output together with the runtime.
+
+### `The prepared sandbox artifact ... was created with provider`
+
+```text
+The prepared sandbox artifact for agent node "..." was created with provider "vercel", but this process selects provider "docker".
+```
+
+The sandbox file selected one provider when eve prepared the sandbox and a different one in the process that uses it. This happens when the sandbox file chooses a provider by reading the host, for example with `process.env.VERCEL ? VercelSandbox.environment() : DockerSandbox.environment()`, and the build and runtime hosts differ. `DefaultSandbox.environment()` does not cause this, because it [records its choice when it prepares the sandbox](/docs/sandbox/default#the-build-records-the-choice). Select one provider explicitly, or use `DefaultSandbox.environment()`, then rebuild with `eve build`, or restart `eve dev` locally.
+
+### `DefaultSandbox has no sandbox provider for this build`
+
+```text
+DefaultSandbox has no sandbox provider for this build: it did not run on Vercel, no Docker daemon was reachable, and production builds do not fall back to just-bash.
+```
+
+The production `eve build` ran outside Vercel without a reachable Docker daemon, so `DefaultSandbox` recorded no provider, and the first session that opens the sandbox fails. A `RUN eve build` step in a Dockerfile usually has no Docker daemon, even when the running container later mounts `/var/run/docker.sock`. Start Docker and run `eve build` again, deploy to Vercel, or select a provider explicitly in the sandbox file, for example `DockerSandbox.environment()` from `eve/sandbox/docker`. See [How eve selects the provider](/docs/sandbox/default#how-eve-selects-the-provider).
+
+### `Sandbox template ... is not available to this runtime`
+
+```text
+Sandbox template "..." for provider "docker" is not available to this runtime.
+```
+
+The build recorded an artifact, but the provider can no longer use its template. When the provider knows the cause, the message includes it:
+
+| Provider  | Common cause                                                                                                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Docker    | The Docker daemon has no image with that name: it was removed, for example by `docker image prune -a`, or the build used another Docker daemon. |
+| Vercel    | The Vercel Sandbox snapshot expired or was deleted.                                                                                             |
+| just-bash | The template directory under `.eve/sandbox-cache/` was deleted, or the build ran on another machine.                                            |
+| Custom    | The image, snapshot, or template that the artifact names no longer exists, so the provider threw `SandboxTemplateNotProvisionedError`.          |
+
+The runtime never recreates a template. Run `eve build` again and deploy its output.
+
+### `Invalid prepared ... artifact`
+
+```text
+Invalid prepared Docker sandbox artifact.
+```
+
+The recorded artifact does not match the format that this eve version expects, usually because the build used a different eve version than the runtime. Run `eve build` with the same eve version that the runtime uses, then redeploy.
+
+## Errors when a session resumes
+
+A session records which provider created its sandbox, and later turns resume that sandbox directly without running the selector again.
+
+### `This session's sandbox was created by provider`
+
+```text
+This session's sandbox was created by provider "just-bash", but the agent now selects provider "docker".
+```
+
+eve logs this warning when a session resumes on a build whose sandbox file selects a different provider than the one that created the session's sandbox, for example after you change providers or `DefaultSandbox` records a different choice in a new build. eve cannot move a sandbox between providers, so the session continues in a fresh sandbox from the current provider, without the old sandbox's files. eve does not delete the old sandbox. Remove it with the old provider's tooling, for example `docker rm` for a Docker container. To keep the session's files instead, restore the previous provider before the session resumes.
+
+### `DefaultSandbox selected just-bash, which always allows network access`
+
+```text
+DefaultSandbox selected just-bash, which always allows network access and accepts only the "allow-all" network policy.
+```
+
+The sandbox passed a `networkPolicy` other than `"allow-all"` to `open()`, or called `setNetworkPolicy()`, while `DefaultSandbox` uses just-bash during `eve dev` or `eve eval` because Docker is not reachable. just-bash cannot restrict network access. Start Docker and restart `eve dev` so `DefaultSandbox` selects Docker, or select `VercelSandbox.environment()` or `DockerSandbox.environment()` explicitly.
+
+### `Invalid ... session state`
+
+```text
+Invalid Docker sandbox session state.
+```
+
+The session's recorded sandbox state does not match the format that this eve version expects, usually because the session started under a different eve version. Start a new session to get a fresh sandbox.
+
+## Errors during eve dev
+
+During `eve dev`, the first sandbox access prepares every sandbox environment in the current build. See [Prepare a reusable environment](/docs/sandbox#prepare-a-reusable-environment).
+
+### `Timed out after 10 minutes waiting for another request or eve dev worker`
+
+```text
+Timed out after 10 minutes waiting for another request or eve dev worker to prepare sandbox environments (this request needs provider "docker").
+```
+
+Another request or `eve dev` worker is still preparing environments. Check the `eve dev` output, or run `eve logs`, to find the slow step, such as an image pull, a Dockerfile build, or a `prepare` callback. Retry after preparation finishes, or restart `eve dev` to cancel it.
+
+## Custom provider errors
+
+These errors come from a provider defined with `defineSandboxProvider()`, or from a keyed tool call on a provider that cannot keep its sandbox. See [Custom sandbox providers](/docs/sandbox/custom-providers).
+
+### `cannot keep a sandbox between invokeTool calls`
+
+```text
+Sandbox provider "acme" cannot keep a sandbox between invokeTool calls, so a call with a key cannot open one.
+```
+
+A keyed `invokeTool` call, such as an MCP tool session, requested the sandbox, and the provider does not keep sandboxes between calls. Call the tool without a key, use Vercel Sandbox or just-bash, or set `toolSessions: true` on a custom provider that bounds how long it keeps those sandboxes. Docker does not support keyed calls. See [Keep sandboxes for keyed tool calls](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls).
+
+### `Sandbox connection extensions cannot replace the session members eve provides`
+
+```text
+Sandbox connection extensions cannot replace the session members eve provides: run. Rename them.
+```
+
+The connection's `extensions` define a member that eve already provides on every sandbox session, such as `run`, `readFile`, `stop`, or `delete`. Rename the extension member.
+
+### `ctx.templateKey() reserves`
+
+```text
+ctx.templateKey() reserves "sourceRevision": eve adds the workspace and skill files and the sandbox source revision itself.
+```
+
+The identity passed to `ctx.templateKey()` in `prepare()` sets `resources` or `sourceRevision`. eve adds both to every template key. Rename that identity field.
+
+### `returned non-serializable session state`
+
+```text
+Sandbox provider "acme" returned non-serializable session state.
+```
+
+`start()` returned state that is not JSON-compatible, such as a class instance, a function, or `undefined`. Return only strings, numbers, booleans, `null`, arrays, and plain objects, and keep live clients in the connection instead.
+
+## Provider setup errors
+
+### Docker is not installed or not running
+
+```text
+The Docker sandbox provider requires Docker, but the `docker` CLI was not found.
+The Docker sandbox provider requires a running Docker daemon, but it is not reachable.
+```
+
+Install and start Docker Desktop, OrbStack, Colima, or another runtime with a Docker-compatible `docker` CLI. To use another compatible CLI, such as Podman, set `EVE_DOCKER_PATH` to its path. If you do not need Docker specifically, use `DefaultSandbox.environment()`, which falls back to just-bash during `eve dev` and `eve eval`.
+
+### The just-bash package is missing
+
+```text
+The just-bash sandbox provider requires the `just-bash` package, which is not bundled with eve.
+```
+
+`eve dev` installs `just-bash` automatically unless the environment sets `autoInstall: false`. Other commands require you to install it. Add it to your application, for example with `pnpm add -D just-bash`, which matches what `eve dev` installs. See [just-bash Sandbox](/docs/sandbox/just-bash#automatic-installation).
+
+### `Cannot build deployable Vercel output because this app requires sandbox templates`
+
+```text
+Cannot build deployable Vercel output because this app requires sandbox templates and VERCEL_OIDC_TOKEN is missing.
+```
+
+eve raises this during a Vercel build, when `VERCEL` is set, if the app needs sandbox templates prepared and `VERCEL_OIDC_TOKEN` is missing. Do not deploy the `.vercel/output` from a build that failed this way. For a local `vercel build`, run `vercel link` and `vercel pull`, then retry. In a build on Vercel, Vercel sets `VERCEL_OIDC_TOKEN` automatically; see [Vercel OIDC federation](https://vercel.com/docs/oidc).
+
+### Vercel Sandbox authentication fails
+
+When `eve build` or the runtime cannot create a Vercel Sandbox because of missing or expired credentials, the Vercel Sandbox SDK reports an authentication or OIDC token error. Locally, run `eve link` to link a project and pull `VERCEL_OIDC_TOKEN` into `.env.local`. Outside Vercel without a linked project, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. See [Vercel Sandbox authentication](/docs/sandbox/vercel#authentication) for the full resolution order.

package/docs/sandbox/vercel.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Vercel Sandbox"
-description: "Create snapshot-backed persistent sandboxes on Vercel."
+description: "Create persistent sandboxes on Vercel, from a prepared snapshot when the environment has build-time setup."
 ---
 
-`VercelSandbox.environment()` prepares a reusable Vercel Sandbox snapshot and creates persistent session sandboxes from its recorded snapshot ID.
+`VercelSandbox.environment()` prepares a reusable Vercel Sandbox snapshot when the environment has build-time setup, and creates persistent session sandboxes from its recorded snapshot ID.
 
 ```ts
 import { defineSandbox } from "eve/sandbox";
@@ -27,12 +27,40 @@ export default defineSandbox(() =>
 );
 ```
 
+## Authentication
+
+eve needs a Vercel token, team ID, and project ID to create Vercel Sandboxes. `eve build` needs them to capture the snapshot, and the runtime needs them to create and resume session sandboxes. Deployments on Vercel provide them automatically.
+
+eve resolves each value from the first source that is set:
+
+| Value      | Sources, in order                                               |
+| ---------- | --------------------------------------------------------------- |
+| Token      | `token` environment option, `VERCEL_OIDC_TOKEN`, `VERCEL_TOKEN` |
+| Team ID    | `teamId` environment option, `VERCEL_TEAM_ID`, `VERCEL_ORG_ID`  |
+| Project ID | `projectId` environment option, `VERCEL_PROJECT_ID`             |
+
+When all three resolve, eve uses them. Otherwise, eve requests a Vercel OIDC token and reads the team and project from the token. On Vercel, the deployment provides that token. Elsewhere, eve reads `VERCEL_OIDC_TOKEN` and, when it is missing or expired, refreshes it with your Vercel CLI login and the project linked in `.vercel/project.json`. If that also fails, eve falls back to the Vercel Sandbox SDK's own credential lookup, which reports an authentication error if it finds none.
+
+For local development, link the app to a Vercel project and pull its environment into `.env.local`:
+
+```bash
+eve link
+```
+
+`vercel link` followed by `vercel env pull` produces the same `.env.local`. A running `eve dev` reloads env files automatically.
+
+Outside Vercel and without a linked project, such as in CI or on a self-hosted server, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`, or pass `token`, `teamId`, and `projectId` to `VercelSandbox.environment()`.
+
 ## Snapshot preparation
 
-eve creates a temporary persistent Vercel Sandbox during build, installs the base runtime, writes managed workspace and skill files, runs the authored `prepare` callback, and captures a snapshot. The build artifact records the snapshot ID.
+eve creates a temporary, non-persistent Vercel Sandbox during build, installs the base runtime, writes managed workspace and skill files, and runs the authored `prepare` callback. It then checks the base runtime again before capturing the snapshot, so a `prepare` callback that breaks it fails the build. The build artifact records the snapshot ID.
 
 When a live session sandbox does not exist, eve creates it directly from that snapshot ID. Runtime does not need to look up the temporary template Sandbox.
 
+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.
+
 ## Initialize after open
 
 Initialize session-specific state after `open()` and before returning the sandbox. This selector writes a configuration file into the persistent `/workspace` filesystem:
@@ -67,6 +95,8 @@ export default defineSandbox(async () => {
 });
 ```
 
+Relative paths, including a relative `workingDirectory` passed to `run()` or `spawn()`, resolve from `/workspace`.
+
 Use the environment's `prepare` callback for immutable setup that every new session should inherit. Use post-open initialization for state that belongs only to one durable session.
 
 ## Network policy
@@ -106,11 +136,16 @@ const sandboxName = sandbox.name;
 
 ## Mount a Drive
 
-A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. 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 it in `mounts` under an absolute path:
+
+```bash
+pnpm add @vercel/sandbox
+```
 
 ```ts
+import { Drive } from "@vercel/sandbox";
 import { defineSandbox } from "eve/sandbox";
-import { Drive, VercelSandbox } from "eve/sandbox/vercel";
+import { VercelSandbox } from "eve/sandbox/vercel";
 
 const REGION = "iad1";
 
@@ -130,6 +165,8 @@ export default defineSandbox(async () => {
 });
 ```
 
+`Drive.getOrCreate()` comes from your app's own `@vercel/sandbox`, so it resolves credentials through the SDK, not eve: it reads `token`, `teamId`, and `projectId` passed to it, or a Vercel OIDC token, which the SDK refreshes from your Vercel CLI login and linked project. It does not read `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, or the credentials passed to `VercelSandbox.environment()`, so outside Vercel without a linked project, pass them to `Drive.getOrCreate()` too.
+
 This example mounts the Drive read-write at `/data`. Files written there remain on the Drive after the sandbox stops. Keep Drive mounts separate from eve's managed `/workspace` directory.
 
 Set the same region on the environment and the Drive. The environment region places the prepared snapshot and each session sandbox together with the Drive.
@@ -148,13 +185,17 @@ return environment.open({
 
 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.
 
+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.
+
 Vercel allows up to four non-overlapping, absolute Drive mount paths per sandbox. See the Vercel documentation for [Drive lifecycle, limits, and pricing](https://vercel.com/docs/sandbox/concepts/drives).
 
 ## Live sandbox options
 
-`open()` also accepts Vercel compute resources, timeout, and Drive mounts. Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.
+`open()` also accepts Vercel compute resources, timeout, environment variables, and Drive mounts. These options apply only when creating the sandbox. Reopening the same key or resuming recorded state keeps the native sandbox's original environment variables, mounts, and network policy. Pass `env` to `run()` or `spawn()` for a per-command override, or call `setNetworkPolicy()` to change the live network policy.
+
+Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.
 
-Initialize the returned sandbox directly in `defineSandbox()`. If initialization fails, eve deletes the newly started sandbox and retries the selector on the next access. After initialization succeeds, the provider persists only immutable JSON-compatible state. If the named Vercel Sandbox later disappears, resume fails rather than recreating initialization side effects.
+Initialize the returned sandbox directly in `defineSandbox()`. If initialization fails, eve keeps the sandbox and runs the selector against it again on the next access, so make initialization safe to repeat; session end deletes the sandbox. After initialization succeeds, the provider persists only immutable JSON-compatible state. If the named Vercel Sandbox later disappears, resume does not recreate it; eve reruns the selector to start a fresh sandbox instead.
 
 eve owns the persistent sandbox identity and prepared snapshot source.
 

package/docs/skills.mdx

@@ -9,7 +9,7 @@ A skill is a model-loadable procedure that follows the `SKILL.md` convention. It
 
 eve scans the files under `agent/skills/` and lists each one's name and description in the system prompt. When a request matches a skill's description (or you name the skill outright), the model loads it with `eve__skill({ name })`, and the skill's markdown becomes the call's result in the active turn. An agent with skills always has the [`eve__skill` tool](./concepts/built-in-tools#eve__search-eve__tool-and-eve__skill). A load reports a `load-skill` action named for the skill, and `t.loadedSkill` asserts it in [evals](./evals/assertions).
 
-Listing skills and loading their instructions do not require a sandbox: loading returns static instructions from the compiled agent and dynamic instructions from session state. Only access to supporting package files requires a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `/workspace/skills/<skill>/` as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
+Listing skills and loading their instructions do not require a sandbox: loading returns static instructions from the compiled agent and dynamic instructions from session state. Only access to supporting package files requires a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `skills/<skill>/` under the workspace root as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
 
 The description is a routing hint, not a label. Write it as the task that should trigger activation:
 

package/docs/subagents/index.mdx

@@ -34,7 +34,7 @@ The copy uses the root's instructions, connections, auth, and sandbox. It receiv
 
 The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
 
-An authored workflow can open the same root-copy target through `ctx.agent("agent")`. To keep the copied configuration but use another model for that child session, pass a [model override to `ctx.agent`](./tools/workflows#delegate-work-ctxagent). The model-facing built-in tool does not accept a model choice.
+An authored workflow can open the same root-copy target through `ctx.agent("agent")`. To keep the copied configuration but use another model for that child session, pass a [model override to `ctx.agent`](./tools/workflows#delegate-work-ctxagent). The default model-facing tool does not accept a model choice; an authored [`agentWithModel` tool](./concepts/built-in-tools#agent) can expose that choice in its input.
 
 To prevent the root session from delegating to a fresh copy of itself, set `tool: false` on the root agent:
 
@@ -212,7 +212,7 @@ The root built-in `agent` tool is the exception. Its children reuse the root's s
 
 ## What the parent sees
 
-eve lowers every tool-enabled subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, taskId? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. To require structured output from a child, open a session with it from an authored workflow tool with [`ctx.agent(name)`](./tools/workflows#delegate-work-ctxagent) and pass `outputSchema` to `send()`; the schema applies to that turn, and the session accepts follow-up messages until the workflow run finishes.
+By default, eve lowers every tool-enabled subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, taskId? }` shape. The opt-in [`agentWithModel` root-copy tool](./concepts/built-in-tools#agent) instead uses `{ message, model, taskId? }`. The parent packs `message` with everything the child needs, since the child never sees the parent's history. To require structured output from a child, open a session with it from an authored workflow tool with [`ctx.agent(name)`](./tools/workflows#delegate-work-ctxagent) and pass `outputSchema` to `send()`; the schema applies to that turn, and the session accepts follow-up messages until the workflow run finishes.
 
 Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
 

package/docs/tools/overview.mdx

@@ -123,7 +123,7 @@ eve does not append the sentence for a function, because whether the call ends t
 
 The turn ends only when every tool call in the model's step can end the turn and succeeds, and every `endsTurn` function returns `true`. Otherwise the model receives the results and continues as usual. Text the model writes before the call is narration, so channels do not post it as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
 
-eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries accept `endsTurn: true` or `false`; eve rejects a function when the resolver returns the entry, because dynamic tool metadata is stored durably. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
+eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries accept `endsTurn` too, including a function. eve replays the function from a durable descriptor, as it does `execute`. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
 
 ### Label tool activity
 
@@ -339,6 +339,25 @@ eve writes each returned file to the session sandbox and keeps only a reference
 
 When compaction drops older tool results, each file becomes a text reference such as `Attached file /workspace/.eve/attachments/<hash>/chart.png (image/png)`. The built-in `read_file` tool shows PNG, JPEG, GIF, and WebP images up to 3 MiB and PDFs up to 20 MiB to the model as files, so the agent can open a compacted image or PDF again.
 
+#### Send a file by URL
+
+For large files that already live in object storage, such as PDFs behind a presigned S3 link, return the URL instead of the bytes with `toolOutputPart.fileUrl`:
+
+```ts
+toModelOutput(output) {
+  return toolOutput.content([
+    toolOutputPart.text(`Contract ${output.id}:`),
+    toolOutputPart.fileUrl(output.signedUrl, { mediaType: "application/pdf" }),
+  ]);
+},
+```
+
+eve keeps only the URL in session history and does not write the file to the sandbox. The model provider fetches the URL itself when it supports that for the file's type; otherwise the AI SDK downloads the file before the call. Only `https:` URLs are accepted.
+
+Every later model call sends the same URL again, so it must stay readable for the rest of the session. A presigned URL that expires mid-session makes later model calls fail. The provider still counts the file's input tokens on each call, the same as an inline file.
+
+Unlike a staged file, a URL part has no sandbox path to fall back on. When compaction drops the tool result, the file becomes `Attached file <filename> (<mediaType>)` and the URL is gone. If the agent may need the file again later, also return a text part with an id or path the tool can fetch it by.
+
 Do not return secrets, credentials, unnecessary personal data, or unbounded sensitive content from tools. Filter, minimize, and redact tool outputs before returning them.
 
 ## What to read next

package/docs/tools/workflows.mdx

@@ -90,9 +90,9 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
   `agent`, `agents`, `ask`, and `reply`; each call it receives carries its own `callId` and
   `abortSignal`.
   A `"use step"` helper that receives `ctx` directly gets a restricted `WorkflowStepToolContext` with
-  `session`, `callId`, `toolName`, `abortSignal`, `getToken`, and `requireAuth`. Read `ctx.agents`, call
+  `session`, `callId`, `toolName`, `abortSignal`, `getSandbox`, `getToken`, and `requireAuth`. Read `ctx.agents`, call
   `ctx.agent()`, and call `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
-  `getSandbox` remains unavailable.
+  Call `getSandbox`, `getToken`, and `requireAuth` in a step: the workflow body throws when it calls them.
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
   not tools returned from `defineDynamic` resolvers.
 
@@ -146,9 +146,21 @@ continue a child from an earlier call. Agent authorization, questions, approvals
 behave as they do for sessions an authored workflow tool opens with `ctx.agent`.
 
 The sandbox resumes after every pending call in the current batch settles. `Promise.all` supports
-fan-out followed by fan-in, but `Promise.race` does not resume after only the first child settles.
-A failed child turn throws at the corresponding `ctx.agent` call, so generated code can catch it.
-The program must return a JSON-serializable value.
+fan-out followed by fan-in. The program must await every `ctx.agent` call before it returns. A call
+that is still pending at that point, such as one that is never awaited or one that loses a
+`Promise.race` or `Promise.any`, fails the workflow.
+
+A failed child turn, an invalid call, or a call over the `maxSubagents` budget throws a
+`WorkflowProgramAgentError` at that `ctx.agent` call, which the program can catch; the message
+says which.
+
+The sandbox converts the program's return value and each `ctx.agent` input with `JSON.stringify`,
+so a `Date` becomes a string and functions and `undefined` members drop. A return value that
+converts to nothing, such as `undefined`, becomes `null`. Each converted value may be up to 1 MiB of
+JSON, each child reply up to 4 MiB of JSON, and the program source up to 256 KiB.
+
+Each start or resume may spend up to 30 seconds running JavaScript and up to 5 minutes in total.
+Time spent waiting for child agents does not count toward either limit.
 
 ### Migrate from `experimental_workflow`
 
@@ -438,6 +450,62 @@ itself contains no credentials.
 Cancelling an authorization wait withdraws its callback. Cancellation uses the existing turn
 cancellation path rather than a separate authorization completion event.
 
+## Use the session sandbox in a step
+
+Pass `ctx` directly to a step helper and call `ctx.getSandbox()` there. The step opens the
+[sandbox](/docs/sandbox) of the session that called the tool, the same sandbox that session's
+turns use. When the session shares its parent's sandbox, as a copy started by the built-in `agent`
+tool does, the step opens that shared sandbox. The step sees files the session wrote, and the
+session's later tool calls see files the step writes:
+
+```ts title="agent/tools/analyze.ts"
+import { defineWorkflowTool, type WorkflowStepToolContext } from "eve/tools";
+import { z } from "zod";
+
+export default defineWorkflowTool({
+  description: "Prepare the input file for an analysis run.",
+  inputSchema: z.object({ value: z.string() }),
+  async task(input, ctx) {
+    "use workflow";
+    await prepareInput(ctx, input);
+    return { path: "/workspace/input.json" };
+  },
+});
+
+async function prepareInput(ctx: WorkflowStepToolContext, input: { value: string }) {
+  "use step";
+  const sandbox = await ctx.getSandbox();
+  await sandbox.writeTextFile({ path: "/workspace/input.json", content: JSON.stringify(input) });
+}
+```
+
+- The workflow body cannot open the sandbox, because it replays. `ctx.getSandbox()` in the body
+  throws and tells you to pass `ctx` to a step helper.
+- The step opens the sandbox directly, with any sandbox provider. If the session recorded its
+  sandbox before it called the tool, the step resumes it. Otherwise, or if that sandbox is gone by
+  the time the step runs, the step opens it the way the session's first turn would: it runs your
+  `defineSandbox()` definition, and the provider finds or creates the sandbox by the session's id. The session's later turns open the same sandbox. Your
+  definition can run once for each caller that opens the sandbox before the session records it,
+  so make its initialization safe to repeat.
+- The step does not own the sandbox. When the step ends, even by throwing, eve lets go of the
+  step's handle and leaves the sandbox running for the session. eve never stops or deletes the
+  sandbox for a step, and `sandbox.stop()` and `sandbox.delete()` in a step fail without a retry,
+  because the session's turns may be using the sandbox.
+- The session removes the sandbox when the session ends, even when only a step opened it. A step
+  that is still running when the session ends can open the sandbox again after that cleanup, and
+  nothing removes the new one.
+- When the eve server shuts down, it stops the sandboxes its sessions opened, but not one that
+  only a step opened. With Docker, that container keeps running until the session ends or you
+  stop it.
+- A step can use the sandbox while the session's turns use it too, as subagents that share a
+  sandbox do. Give each one its own files to write.
+- Steps run at least once and retry after a failure, so make sandbox writes safe to repeat. Write
+  whole files instead of appending to them, or check for earlier output first.
+- When the session shares its parent's sandbox, the step opens it by the parent's session id with
+  the parent's sandbox definition, and the parent removes it when the parent ends.
+- A step runs wherever the workflow runs. A sandbox that lives on one machine, such as just-bash
+  on the local disk, is reachable from a step only on that machine, as in local development.
+
 ## Ask a human: `ctx.ask`
 
 ```ts

package/docs/tutorial/run-analysis.mdx

@@ -29,9 +29,9 @@ Top-level workspace entries get advertised to the model automatically, so it kno
 
 ## Install the chart dependencies
 
-Python needs a sandbox that runs real binaries. For local development, start a Docker-compatible daemon and run `docker info` to verify it is reachable before restarting `npm run dev`. eve also supports [microsandbox](../sandbox#microsandbox) on compatible hosts. The `just-bash` fallback cannot run Python or install packages; installing Python on your laptop does not add it to the sandbox. You can [continue to the next chapter](./remember-definitions) if you do not want to set up a local container or VM yet.
+Python needs a sandbox that runs real binaries. For local development, start a Docker-compatible daemon and run `docker info` to verify it is reachable before restarting `npm run dev`. The `just-bash` fallback cannot run Python or install packages; installing Python on your laptop does not add it to the sandbox. You can [continue to the next chapter](./remember-definitions) if you do not want to set up a local container yet.
 
-The default eve images for Docker, microsandbox, and Vercel Sandbox include Python, but not matplotlib. Add this definition alongside `workspace/` to install matplotlib in a virtual environment. It uses the same environment for installation and chart execution, without changing the system Python:
+The default eve images for Docker and Vercel Sandbox include Python, but not matplotlib. Add this definition alongside `workspace/` to install matplotlib in a virtual environment. It uses the same environment for installation and chart execution, without changing the system Python:
 
 ```ts title="agent/sandbox/sandbox.ts"
 import { DefaultSandbox, defineSandbox } from "eve/sandbox";