eve 0.82.0 → 0.83.1

package/docs/guides/frontend/overview.mdx

@@ -78,7 +78,7 @@ export function Chat() {
 | `error`        | The latest session creation, stream, resume, or turn failure.                             |
 | `events`       | Raw eve stream events for this session.                                                   |
 | `session`      | Serializable fixed session cursor (`sessionId`, `streamIndex`).                           |
-| `prewarm`      | Create the durable session without starting a turn.                                       |
+| `prewarm`      | Create a session or prepare its idle owner without starting a turn.                       |
 | `send`         | Send text or a multi-part message, with per-turn options.                                 |
 | `respond`      | Answer pending HITL input requests, with per-turn options.                                |
 | `resume`       | Replay an attached session and follow its in-flight turn.                                 |
@@ -131,25 +131,49 @@ An initial `true` value or a later `false` to `true` change prepares the current
 Changing `prewarm` back to `false` does not abort creation or discard an existing session. If
 a reset and state update happen in the same event, React applies both before deciding whether
 to prepare the next session. Vue and Svelte read `prewarm` when their binding is created; call
-their returned `prewarm()` method for interaction-driven creation.
+their returned `prewarm()` method when typing starts.
 
 Prewarming defaults to `false`: the first send creates the session. Set it to `true` only after
 your application's auth, headers, and any chat-record binding are ready. Applications that
 prepare those in the submit handler should keep the default until then.
 
-Prewarming starts the workflow and establishes its inbox, then parks before session hooks,
-dynamic definitions, or sandbox setup run. The first message passes through the channel's
-`onMessage` hook and supplies the identity and context for initialization and `turn_0`.
-
-The explicit `prewarm()` method resolves on `202 Accepted`, as does `client.sessions.create()`.
-It does not wait for an initialization event; concurrent calls share the same create request.
+Prewarming starts the workflow and establishes its inbox, then parks before session hooks or
+dynamic definitions run. Meanwhile, it starts the agent's [sandbox](/docs/sandbox) in the
+background. The first message passes through the channel's `onMessage` hook and supplies the
+identity and context for initialization and `turn_0`. That turn does not wait for the sandbox;
+only a tool or hook that uses the sandbox waits for the rest of its start. If the sandbox fails
+to start during prewarming, the first turn that uses it starts it instead. eve deletes the
+sandbox when the session ends, including when an unused prewarmed session times out.
+
+For an existing session, `prewarm()` checks the owner against the exact deployment accepting
+that request. On Vercel, an idle owner on another deployment can transfer in the background
+before Send. The session ID, history, stream, and expiry stay the same; no model call runs.
+An owner already serving that deployment needs no workflow wake-up. Active turns are never
+interrupted; an active turn can finish before preparation, and a queued real message takes priority.
+An owner with pending tasks or input requests can skip the hint.
+Older owners without preparation support and Worlds without deployment affinity are left alone.
+
+Call `agent.prewarm()` once when a new typing burst begins, with an application-level cooldown
+if you also retry during long drafts. eve shares concurrent calls; it does not listen to inputs
+or poll deployments. `prewarm: true` also prepares a restored session when the binding mounts.
+A production alias targets its current deployment; a preview alias targets that preview.
+Requests pinned to an immutable deployment (including deployment-skew routing) cannot discover
+a newer deployment. Local development retains session-creation behavior.
+
+`client.sessions.attach(sessionId).prewarm({ signal })` returns `ready`, `accepted`,
+`unsupported`, or `no_active_session`. `accepted` means the hint was persisted, not that handoff
+has finished. It never replaces an expired session. Send retains its existing retry and
+handoff behavior if preparation is unavailable, fails, or has not finished.
+
+The explicit `prewarm()` method resolves after ingress acceptance, as does `client.sessions.create()`.
+It does not wait for an initialization event; concurrent calls share the same preparation request.
 The composer stays `"ready"`, meaning it can accept input, and prewarming does not run
-`prepareSend`. A concurrent `send()` waits only for acceptance, then posts the message.
+`prepareSend`. A concurrent `send()` waits for initial creation acceptance when needed, but never waits for existing-session preparation.
 If the inbox is still starting, the client retries `409 session_not_ready` with bounded
 exponential backoff for up to 20 seconds. The caller's abort signal cancels the wait. Stream
 events are not a prerequisite for sending.
 
-A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
+An existing-session preparation failure rejects the explicit call without setting the composer's error or blocking Send. A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
 fall back to creating a session with its message. After creation succeeds, initialization
 failures arrive on the stream during the first turn. The configured session timeout starts
 at creation, so an unused prewarmed session can expire before its first message. React does not

package/docs/guides/instrumentation/agent-runs.mdx

@@ -40,6 +40,22 @@ Tracing starts as soon as you save the rule. You can also manage sampling
 rules with [`vercel traces config`](https://vercel.com/docs/cli/traces#manage-trace-sampling-rules).
 The CLI accepts rates from 1 to 100%; add a 0% rule from the dashboard.
 
+## Trace selected paths
+
+If you prefer path-scoped sampling, replace the all-path rule with 100% rules
+for each required **Request Path Prefix**. For a single agent at the default
+mount, start with:
+
+- `/eve/v1`: eve's HTTP API and default channel endpoints.
+- `/.well-known/workflow`: workflow execution and webhooks.
+
+For named agents, use their deployed prefixes, such as `/eve/support/v1`,
+instead of `/eve/v1`. Include custom channel routes and, for Vercel-backed
+schedule collections,
+`/.well-known/eve/v1/schedules/consumer`. Missing paths can leave traces
+incomplete. The workflow prefix also includes non-eve workflows in the same
+project.
+
 ## Configure Agent Runs
 
 Preview and production deployments export to Vercel Agent Runs by default.

package/docs/guides/instrumentation/otel.mdx

@@ -7,6 +7,29 @@ url: "/observability/otel"
 `eve dev` records local traces by default. Use `otel()` for process-wide
 settings and `otelIntegration()` for third-party destinations.
 
+## Session handover events
+
+Existing Workflow step spans include these events when tracing is active:
+
+- `eve.session.handover.forwarding_started`: the previous owner starts submitting its buffered messages, including an empty buffer.
+- `eve.session.handover.part_submitted`: a buffered part was durably submitted.
+- `eve.session.handover.final_submitted`: the final marker was durably submitted. This does not confirm that the successor has processed it.
+- `eve.session.handover.inbox_unblocked`: an existing turn step observes that the inbox applied every buffered part and the final marker.
+
+Join both owners with `eve.session.id` and `eve.handoff.attempt_key`.
+`workflow.run.id` identifies the emitting owner; submission events also include
+`eve.handoff.destination_run_id`. Counts and part indexes describe the transfer
+without recording message content. Step IDs and `eve.handoff.step_attempt`
+distinguish retries; these events are not exactly-once counters.
+
+The receiver records `eve.handoff.applied_at_ms` using Workflow's replay-stable
+clock, identified by `eve.handoff.applied_at_clock: workflow`. This is logical
+event time, not the host time when replay applied the marker. The event's own
+timestamp is when the next turn step exports the observation. No receiver
+observation is exported if no subsequent turn step runs. An abandoned handover
+does not emit a successful receipt. No additional Workflow steps or writes are
+created for tracing.
+
 ## Configure OpenTelemetry
 
 `otel()` and `otelIntegration()` are optional:

package/docs/guides/self-modification.md

@@ -74,7 +74,7 @@ export default selfModification({
 | `credentials`           | Required. An object with a `resolve({ capability, repository })` function that returns a GitHub token, or `{ pat: true }` to read `EVE_SELF_MODIFICATION_GITHUB_TOKEN` from the deployment environment. |
 | `model`, `reasoning`    | Optional model and reasoning level for the deployed subagent. It defaults to the parent agent's model.                                                                                                  |
 
-The deployed subagent is never offered during `eve dev`. In a deployment, it needs a sandbox provider that supports runtime credential transforms: Vercel Sandbox on Vercel, or microsandbox on a supported self-hosted system. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
+The deployed subagent is never offered during `eve dev`. It requires deploying on Vercel, where Vercel Sandbox provides the runtime credential transforms that keep the GitHub token out of the sandbox. Builds succeed on any host, but in a deployment outside Vercel the deployed subagent fails with an error that names this requirement when it opens its sandbox. Don't mount `eve/self-modification/remote` in self-hosted deployments. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
 
 ## Run without self-modification
 

package/docs/guides/session-context.md

@@ -46,7 +46,7 @@ Public fields include:
 - `auth.current`: the caller for the active inbound turn.
 - `auth.initiator`: the caller that started the session.
 - `parent`: the parent call, session, root session, and turn for a child subagent session.
-- `predecessor`: present when eve started this session in place of a [stranded session](../concepts/execution-model-and-durability#stranded-sessions). Its `sessionId` names the session this one replaced. Read the earlier conversation with `sessions.attach(predecessor.sessionId)` from `eve/server`. See [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives).
+- `predecessor`: present only when this session replaced a stranded one; `sessionId` names that earlier session. See [Recover a stranded session](./deployment/self-hosting#recover-a-stranded-session) to read its earlier conversation.
 
 Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Top-level schedule sessions use the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
 

package/docs/instructions.mdx

@@ -80,7 +80,7 @@ A dynamic system result applies at its lifecycle scope. A dynamic user result is
 
 The `messages` snapshot passed to a `session.started` resolver includes static user instructions. A `turn.started` resolver additionally sees user instructions produced at `session.started`. Other dynamic capability resolvers keep their existing snapshots.
 
-See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. To give a session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) the earlier conversation, read its stream with `sessions.attach()` and `transcriptReducer()` in a `session.started` user-role instruction.
+See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. For a `session.started` instruction that reads the earlier conversation into a replacement session, see [Recover a stranded session](./guides/deployment/self-hosting#recover-a-stranded-session).
 
 ## History controls and prompt caching
 

package/docs/meta.json

@@ -2,6 +2,7 @@
   "pages": [
     "---Introduction---",
     "getting-started",
+    "use-cases",
     "tutorial",
     "concepts",
     "---Build---",

package/docs/reference/agent-files.md

@@ -56,10 +56,10 @@ Paths below are relative to the agent directory. Root agents can use every path;
 | `extensions/`                                           | Mounted reusable capabilities             | Yes                    | File or directory mounts. See [Extensions](/docs/extensions).                                                                           |
 | `hooks/`                                                | Lifecycle and stream-event subscribers    | Yes                    | Module-backed only; recursive directories are supported.                                                                                |
 | `skills/`                                               | On-demand procedures and capability packs | Yes                    | Flat Markdown, module-backed skills, or packaged skills.                                                                                |
-| `lib/`                                                  | Shared authored helper code               | Yes                    | Import-only; not copied into the sandbox.                                                                                               |
+| `lib/`                                                  | Shared authored helper code               | Yes                    | Import-only; not copied into the sandbox. Helpers can import data files such as JSON from here.                                         |
 | `memory.ts` or `memory/<name>.ts`                       | Cross-session memory                      | Yes                    | Provider-backed slots. See [Memory](/docs/memory).                                                                                      |
-| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's sandbox                       | Yes                    | The framework default applies when neither is authored.                                                                                 |
-| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes                    | Mirrored into `/workspace/` when a session starts.                                                                                      |
+| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's sandbox                       | Yes                    | The framework default applies when neither is authored. When `sandbox/` exists, only `sandbox/sandbox.ts` is read.                      |
+| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes                    | Copied into the prepared environment; each new session sandbox starts with them in the workspace root.                                  |
 | `tools/`                                                | Typed executable integrations             | Yes                    | Module-backed only.                                                                                                                     |
 | `schedules/`                                            | Recurring jobs                            | No                     | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported.                                   |
 | `subagents/`                                            | Specialist child agents                   | Yes                    | Local directories or remote-agent definitions; nested subagents are supported.                                                          |
@@ -82,7 +82,7 @@ Explicit imports, sandbox workspace files, and packaged skill resources are unaf
 
 ## Files available in the sandbox
 
-Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's `/workspace/` under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).
+Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's workspace root (`/workspace/` on built-in providers) under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `skills/` under the workspace root as the fallback when the sandbox has no usable `$HOME`. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).
 
 ## Local subagents
 

package/docs/reference/cli.md

@@ -210,8 +210,13 @@ eve build [--profile <path>] [--skip-sandbox-prewarm]
 Compiles and bundles in an invocation-owned directory under `.eve/builds/`, prepares sandbox artifacts, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure. Pass `--skip-sandbox-prewarm` when you only need compiled output, such as before a separate typecheck. Skipping preparation can produce output that cannot start its configured sandbox, so do not deploy that output.
 
 Authored bundles preserve custom Node.js resolution conditions supplied through `--conditions`,
-`-C`, or `NODE_OPTIONS`. For example, `NODE_OPTIONS="--conditions=react-server" eve build`
-keeps a channel's `server-only` imports on the same export used during compilation.
+`-C`, or `NODE_OPTIONS`, so compilation and the bundle resolve each package to the same export.
+For example, `NODE_OPTIONS="--conditions=react-server" eve build` selects the `react-server`
+export of packages that publish one.
+
+eve loads `server-only` and `client-only` imports as empty modules in every bundle it builds. Code
+shared with a Next.js app can keep these imports without a resolution condition, and your app does
+not need to depend on either package.
 
 | Flag                     | Type   | Default | Description                                                                                   |
 | ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------- |
@@ -454,21 +459,23 @@ eve eval [evalId...] [--url <url>] [options]
 
 Runs all discovered evals when no eval ids are given; ids match exactly or by directory prefix (`eve eval weather` runs everything under `evals/weather/`). Exits `0` when every eval passed its checks, `1` when any eval failed (a failed check, an execution error, or a `--strict` threshold miss), `2` on configuration errors.
 
-Without `--url`, `eve eval` starts its own local server on a free port with state under `.eve/eval-servers/<run id>/`, removed when the run ends. It runs beside an `eve dev` session for the same agent without attaching to it or changing it.
-
-| Flag                     | Type   | Default | Description                                                   |
-| ------------------------ | ------ | ------- | ------------------------------------------------------------- |
-| `--url <url>`            | string | none    | Remote agent URL (skip local host startup)                    |
-| `--tag <tag...>`         | string | none    | Run only evals carrying a tag                                 |
-| `--exclude-tag <tag...>` | string | none    | Skip evals carrying a tag                                     |
-| `--strict`               | flag   | off     | Below-threshold scores also fail the exit code                |
-| `--list`                 | flag   | off     | Print evals selected by the tag filters, without running them |
-| `--timeout <ms>`         | number | none    | Per-eval timeout in milliseconds                              |
-| `--max-concurrency <n>`  | number | 8       | Max concurrent eval executions                                |
-| `--json`                 | flag   | off     | Output results as JSON                                        |
-| `--junit <path>`         | string | none    | Write JUnit XML results to a file                             |
-| `--skip-report`          | flag   | off     | Skip eval-defined reporters (e.g. Braintrust)                 |
-| `--verbose`              | flag   | off     | Stream per-eval logs and workflow run IDs to stdout           |
+Without `--url`, `eve eval` starts its own local server on a free port with state under `.eve/eval-servers/<run id>/`, removed when the run ends unless you pass `--keep-state`. A kept directory, including the server's Workflow data in `.workflow-data/`, stays until a later `eve eval` in the same app cleans it up. The local server runs beside an `eve dev` session for the same agent without attaching to it or changing it.
+
+| Flag                     | Type   | Default | Description                                                    |
+| ------------------------ | ------ | ------- | -------------------------------------------------------------- |
+| `--url <url>`            | string | none    | Remote agent URL (skip local host startup)                     |
+| `--tag <tag...>`         | string | none    | Run only evals carrying a tag                                  |
+| `--exclude-tag <tag...>` | string | none    | Skip evals carrying a tag                                      |
+| `--strict`               | flag   | off     | Below-threshold scores also fail the exit code                 |
+| `--list`                 | flag   | off     | Print evals selected by the tag filters, without running them  |
+| `--timeout <ms>`         | number | none    | Per-eval timeout in milliseconds                               |
+| `--max-concurrency <n>`  | number | 8       | Max concurrent eval executions                                 |
+| `--repeat <n>`           | number | 1       | Run every eval n times to measure repeatability                |
+| `--json`                 | flag   | off     | Output results as JSON                                         |
+| `--junit <path>`         | string | none    | Write JUnit XML results to a file                              |
+| `--skip-report`          | flag   | off     | Skip eval-defined reporters (e.g. Braintrust)                  |
+| `--keep-state`           | flag   | off     | Keep the local eval server's state after the run (not `--url`) |
+| `--verbose`              | flag   | off     | Stream per-eval logs and workflow run IDs to stdout            |
 
 See [Evals](../evals/overview) for authoring evals.
 

package/docs/reference/typescript-api.md

@@ -48,7 +48,9 @@ export default defineTool({
 | `defineHook`                                          | `eve/hooks`                                                             | `agent/hooks/<slug>.ts`                                                                | [Hooks](../guides/hooks)                               |
 | `defineSchedule`                                      | `eve/schedules`                                                         | `agent/schedules/<name>.ts`                                                            | [Schedules](../schedules)                              |
 | `defineState`                                         | `eve/context`                                                           | tools, hooks, lifecycle                                                                | [Session context](../guides/session-context)           |
-| `defineSandbox`                                       | `eve/sandbox`                                                           | `agent/sandbox.ts`                                                                     | [Sandbox](../sandbox)                                  |
+| `defineSandbox`                                       | `eve/sandbox`                                                           | `agent/sandbox.ts` or `agent/sandbox/sandbox.ts`                                       | [Sandbox](../sandbox)                                  |
+| `defineParentSandbox`                                 | `eve/sandbox`                                                           | `agent/subagents/<name>/sandbox.ts`                                                    | [Sandbox](../sandbox#share-a-parent-sandbox)           |
+| `defineSandboxProvider`                               | `eve/sandbox/provider`                                                  | custom sandbox provider modules                                                        | [Custom providers](../sandbox/custom-providers)        |
 | `defineInstrumentation`                               | `eve/instrumentation`                                                   | `agent/instrumentation/<name>.ts`                                                      | [Instrumentation](../observability/instrumentation)    |
 | `otel`, `otelIntegration`                             | `eve/instrumentation/otel`                                              | `agent/instrumentation/<destination>.ts`                                               | [OpenTelemetry](../observability/otel)                 |
 | `defineRemoteAgent`                                   | `eve`                                                                   | `agent/subagents/<id>/agent.ts`                                                        | [Remote agents](../guides/remote-agents)               |
@@ -111,7 +113,7 @@ import template from "../../prompts/template.txt?raw";
 | `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401`                                                                                                                                                                           |
 | `ctx.approval`              | Present only while a call runs after a person approved it: `responder` is who approved it and `responder.getToken(provider)` resolves their token. The call still runs as `ctx.session.auth.current`; see [Human-in-the-loop](/docs/human-in-the-loop) |
 
-Tool definitions accept `availableInSubagents: false` to restrict the tool to top-level root sessions, and `deferred: true` to keep the tool out of the model's tool list so the model finds it with `eve__search` and calls it with `eve__tool`; see [Tools](../tools#keep-a-tool-out-of-the-tool-list). `defineTool` definitions accept `endsTurn: true`, or a function that receives the `execute` output, to end the turn without a reply after a successful call; see [Tools](../tools#end-the-turn-after-a-tool-call). Authored workflow bodies also receive `ctx.agents`, a replay-stable map of callable-agent metadata, and `ctx.agent(name)`, which returns an `AgentSession` whose `send(message, options?)` resolves to a response with `result()`. A `"use step"` helper that receives the context directly should type it as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`. The root-copy `agent` entry has an empty description when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
+Tool definitions accept `availableInSubagents: false` to restrict the tool to top-level root sessions, and `deferred: true` to keep the tool out of the model's tool list so the model finds it with `eve__search` and calls it with `eve__tool`; see [Tools](../tools#keep-a-tool-out-of-the-tool-list). `defineTool` definitions accept `endsTurn: true`, or a function that receives the `execute` output, to end the turn without a reply after a successful call; see [Tools](../tools#end-the-turn-after-a-tool-call). Authored workflow bodies also receive `ctx.agents`, a replay-stable map of callable-agent metadata, and `ctx.agent(name)`, which returns an `AgentSession` whose `send(message, options?)` resolves to a response with `result()`. A `"use step"` helper that receives the context directly should type it as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`; its `getSandbox()` opens the sandbox of the session that called the tool (see [Use the session sandbox in a step](../tools/workflows#use-the-session-sandbox-in-a-step)). The root-copy `agent` entry has an empty description when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
 
 ## Imports at a glance
 
@@ -140,7 +142,11 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `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`, provider environments, and sandbox session 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`                                                                                  |

package/docs/sandbox/custom-providers.mdx

@@ -0,0 +1,254 @@
+---
+title: "Custom Sandbox Providers"
+description: "Connect eve to your own sandbox backend with defineSandboxProvider()."
+---
+
+A custom sandbox provider connects eve to a backend that eve does not ship, such as your own container service or virtual machine pool. You implement a byte-level connection to one sandbox and four lifecycle methods. eve derives the full sandbox session from the connection, seeds workspace and skill files into templates, hashes template keys, and maps `sandbox.stop()`, `sandbox.delete()`, and server shutdown onto the lifecycle.
+
+## Define a provider
+
+`defineSandboxProvider()` from `eve/sandbox/provider` takes a name and an `environment()` function that returns the lifecycle. This example targets `@acme/sdk`, a hypothetical client for a snapshot-capable machine service:
+
+```ts title="agent/lib/acme-sandbox.ts"
+import { createHash } from "node:crypto";
+import {
+  defineSandboxProvider,
+  SANDBOX_AGENT_ENV,
+  SandboxSessionGoneError,
+  type SandboxConnection,
+} from "eve/sandbox/provider";
+import { AcmeClient, type AcmeMachine } from "@acme/sdk";
+
+export const AcmeSandbox = defineSandboxProvider({
+  name: "acme",
+  environment(options: { readonly project: string }) {
+    const acme = new AcmeClient({ project: options.project });
+    // Session ids can be long, so hash them into a bounded machine name.
+    const nameFor = (sessionId: string) =>
+      `eve-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`;
+    return {
+      async prepare(ctx) {
+        const template = `eve-tpl-${ctx.templateKey({ project: options.project, version: 1 }).slice(0, 32)}`;
+        const cached = await acme.snapshots.find(template);
+        if (cached !== null) return { snapshotId: cached.id };
+        const machine = await acme.machines.create({
+          env: SANDBOX_AGENT_ENV,
+          image: "ubuntu:24.04",
+        });
+        try {
+          await ctx.populate(connect(machine));
+          return { snapshotId: (await machine.snapshot({ name: template })).id };
+        } finally {
+          await machine.destroy();
+        }
+      },
+      async start(ctx, open: { readonly egress?: "allow-all" | "deny-all" } | undefined, artifact) {
+        const name = nameFor(ctx.session.id);
+        // Atomic create-if-absent: an existing machine is returned unchanged,
+        // so `egress` and the snapshot apply only on creation.
+        const machine = await acme.machines.createIfAbsent({
+          egress: open?.egress ?? "allow-all",
+          env: SANDBOX_AGENT_ENV,
+          name,
+          snapshotId: artifact.snapshotId,
+        });
+        return { connection: connect(machine), state: { name, version: 1 } };
+      },
+      async resume(_ctx, _artifact, state) {
+        const machine = await acme.machines.get(state.name);
+        if (machine === null)
+          throw new SandboxSessionGoneError(`Acme machine "${state.name}" is gone.`);
+        return connect(machine);
+      },
+      async onSessionEnd(ctx, state, { abortSignal }) {
+        await acme.machines.destroyIfExists(state?.name ?? nameFor(ctx.session.id), {
+          signal: abortSignal,
+        });
+      },
+    };
+  },
+});
+
+function connect(machine: AcmeMachine): SandboxConnection {
+  return {
+    spawn: ({ abortSignal, command, env, workingDirectory }) =>
+      machine.exec({
+        argv: ["bash", "-lc", command],
+        cwd: workingDirectory,
+        env,
+        signal: abortSignal,
+      }),
+    // 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 }),
+    stop: () => machine.suspend(),
+  };
+}
+```
+
+Use the provider from a sandbox file like any built-in environment. Every provider accepts the standard `prepare` option:
+
+```ts title="agent/sandbox.ts"
+import { defineSandbox } from "eve/sandbox";
+import { AcmeSandbox } from "./lib/acme-sandbox";
+
+export const environment = AcmeSandbox.environment({
+  project: "agents",
+  prepare: async (sandbox) => {
+    await sandbox.run({ command: "apt-get install -y ripgrep" });
+  },
+});
+
+export default defineSandbox(() => environment.open({ egress: "deny-all" }));
+```
+
+`environment(options)` always receives an object, without `prepare`: `{}` when the sandbox file passes no options, so make every field optional or require the caller to pass it. TypeScript infers the environment options, open options, artifact, state, and connection extensions from the implementation, so you do not pass type arguments. Write `start()` before `resume()` so the state type comes from `start()`'s return value, or annotate `resume()`'s `state` parameter.
+
+## Implement the connection
+
+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.
+- `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.
+- `workspaceRoot` is optional. It is the session's workspace root: the absolute sandbox directory where commands start by default. It defaults to `/workspace`, which every built-in provider uses. Set it when your sandbox keeps its working files somewhere else, such as `/home/user/project`. The directory must exist before eve runs a command in it.
+
+Every path a connection receives is absolute, and `workingDirectory` is always set. eve resolves relative paths and a missing or relative working directory from the workspace root before it calls the connection, and `session.resolvePath(".")` returns the root. The built-in file tools, attachment staging, and GitHub checkouts use the same root. eve throws when it opens a connection whose `workspaceRoot` is not absolute:
+
+```text
+Sandbox connection workspaceRoot must be an absolute path, but received "project".
+```
+
+eve builds the rest of the session from these methods: `run()` over `spawn()`, the binary and text read and write variants, encodings and line ranges, `writeFiles()`, `resolvePath()`, and abort-signal binding. An extension member named like a session method, or `stop` or `delete`, is a type error, and eve throws when it opens the connection:
+
+```text
+Sandbox connection extensions cannot replace the session members eve provides: run. Rename them.
+```
+
+Type the connection with its extensions, such as `SandboxConnection<{ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void> }>`, and `environment.open()` and `ctx.getSandbox(environment)` return a session that includes them.
+
+## Implement the lifecycle
+
+eve calls the lifecycle methods at these points:
+
+| When                                                  | eve calls                                                                                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `eve build`, or the first sandbox access in `eve dev` | `prepare(ctx)`, and stores the artifact it returns with the deployment                                                                                                                                       |
+| The first sandbox access in a session, or prewarming  | `start(ctx, options, artifact)` from `environment.open(options)` in the selector. A prewarmed session calls it in the background before its first message, and its first turn can call it again concurrently |
+| A later workflow step or process, or a turn starting  | `resume(ctx, artifact, state)`. Each turn of a session that recorded a sandbox calls it in the background as the turn starts, whether or not the turn uses the sandbox                                       |
+| The step that opened a connection ends                | `connection.close()`, for a turn's step, a `"use step"` function, or an `invokeTool` call                                                                                                                    |
+| `sandbox.stop()`                                      | `connection.stop()`, then `connection.close()`                                                                                                                                                               |
+| `sandbox.delete()`                                    | `connection.close()`, then `onSessionEnd(ctx, state, { reason: "deleted" })`                                                                                                                                 |
+| The eve server shuts down                             | `connection.stop()`, then `connection.close()`, on every connection eve still holds: any connection mid-step, and between steps a connection without `close()`; eve logs failures and does not throw them    |
+| The owning session reaches a terminal outcome         | `connection.close()` on a connection the ending step still holds, then `onSessionEnd(ctx, state, { reason })` with `"completed"`, `"expired"`, or `"failed"`                                                 |
+
+eve calls `close()` at most once per connection, retrying only after a failure. After a turn's step ends, eve keeps a connection without `close()` registered, so server shutdown still stops the session's sandbox. eve lets go of a connection with `close()` at the end of its step or after `stop()`, so server shutdown between steps does not stop that sandbox. If your provider defines `close()` and runs remote compute, bound idle compute yourself, for example with an idle timeout. `stop()` can run again after the session uses a stopped connection, so make it a no-op when the sandbox is already stopped. A failed `close()` never prevents `onSessionEnd()` from deleting the sandbox.
+
+### `prepare()`
+
+`prepare()` builds a reusable template and returns a JSON-compatible artifact, such as a snapshot or image id. It runs during `eve build`, so the deployment ships with the artifact, and the production runtime never calls it. A running sandbox keeps the template it started from: `resume()` receives the current deployment's artifact, but reconnects existing state.
+
+`ctx.isEmpty` is `true` when the agent has no workspace files, no skill files, and no authored `prepare`. A provider can skip building a template in that case. See [Bake files into templates](#bake-files-into-templates) for `ctx.populate()` and `ctx.templateKey()`.
+
+### `start()`
+
+`start()` returns the sandbox for `ctx.session.id`, creating it when none exists, together with the minimal JSON-compatible state eve checkpoints for the session. It must be an idempotent upsert: repeated, concurrent, cross-process, and cross-deployment calls for one session id return the same sandbox while it exists and is usable. A subagent that shares its parent's sandbox can open it before the parent does, and two processes can race to create it.
+
+Derive the sandbox's native identity from `ctx.session.id` and a provider-level namespace, such as a project or account, only. Never derive it from the open options or the artifact, which can differ between callers and deployments. Apply them only when `start()` creates the sandbox.
+
+`ctx.session.id` is the id of the session that owns the sandbox. For a subagent that shares its parent's sandbox it is the parent's id. `ctx.kind` is `"tool-session"` for a keyed `invokeTool` call's sandbox and `"session"` otherwise.
+
+### `resume()`
+
+`resume()` reconnects to the sandbox that `state` names and never recreates it. Open options are not passed to `resume()`, so put anything reconnection needs in the state. When the sandbox no longer exists, throw `SandboxSessionGoneError`: eve clears the session's state and reruns the selector, which starts a fresh sandbox without the lost sandbox's files. Let other failures, such as an outage, surface unchanged.
+
+Validate the shape of your own state in `resume()`. When you change it incompatibly, raise `stateProtocolVersion` in the provider definition: state recorded under another version starts a fresh sandbox instead of reaching `resume()`.
+
+### `onSessionEnd()`
+
+`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.
+
+## Bake files into templates
+
+Call `ctx.populate(connection)` on the build instance before you capture it. `populate()` writes the agent's workspace files to the connection's workspace root and its skill files to `$HOME/.agents/skills` in one `writeFiles()` batch, then runs the authored `prepare` callback with a session over the same connection. eve finds `$HOME` by running a command through `spawn()`. When the sandbox has no usable home directory, skills go to `skills/` under the workspace root.
+
+A provider that can mount host directories can avoid writing every file. `ctx.resourcesDirectory()` resolves to a stable read-only host directory that contains `workspace/` and `skills/`, or to `undefined` when there is none. Mount it in the build instance and pass its sandbox path:
+
+```ts
+const resources = await ctx.resourcesDirectory();
+const machine = await acme.machines.create({
+  mounts:
+    resources === undefined ? [] : [{ host: resources, path: "/eve/resources", readOnly: true }],
+});
+await ctx.populate(
+  connect(machine),
+  resources === undefined ? undefined : { mountedAt: "/eve/resources" },
+);
+```
+
+With `mountedAt`, `populate()` copies `<mountedAt>/workspace/.` into the workspace root and `<mountedAt>/skills/.` into `$HOME/.agents/skills` with `cp -a`. When eve has no resource directory, `populate()` ignores `mountedAt` and writes the files instead.
+
+`ctx.templateKey(identity)` returns a SHA-256 hex key that changes whenever `identity`, the workspace files, the skill files, or the sandbox file's source changes. Pass every option that affects the template, such as the base image, and use the key to name or look up a cached template. `identity` accepts JSON values, `undefined` (omitted), plain objects and arrays, and functions (hashed by their source). `resources` and `sourceRevision` are reserved, and eve throws if `identity` sets either one. The source revision covers only the sandbox file, so a `prepare` callback imported from another module does not change the key.
+
+Only build time seeds files. A sandbox that `start()` creates gets them from the template, so a provider whose templates cannot hold files cannot provide workspace or skill files.
+
+## Keep sandboxes for keyed tool calls
+
+Set `toolSessions: true` on the implementation to let keyed `invokeTool` calls keep their sandbox between calls, as Vercel Sandbox and just-bash do. A keyed call does not own its sandbox: eve runs the selector and `start()` on every call, calls `connection.close()` when the call ends, and never calls `onSessionEnd()`. Because nothing ever ends a keyed sandbox, the provider must bound its retention, for example with snapshot expiration.
+
+Without `toolSessions`, a keyed call fails when its tool requests the sandbox:
+
+```text
+Sandbox provider "acme" cannot keep a sandbox between invokeTool calls, so a call with a key cannot open one.
+```
+
+A keyed call whose tool never requests the sandbox runs normally. See [MCP tool sessions](/docs/channels/mcp#tool-sessions).
+
+## Enforce network policy
+
+eve has no built-in network control for custom providers. To offer one, accept a `SandboxNetworkPolicy` from `eve/sandbox` as an open option, as a `setNetworkPolicy()` extension, or both. Reject any part of a policy that the backend cannot enforce instead of weakening it. For example, a backend that can only switch egress on or off accepts `"allow-all"` and `"deny-all"` and throws on allow-lists, subnets, and header transforms, as the Docker provider does.
+
+## Set environment variables
+
+`SANDBOX_AGENT_ENV` is `{ AI_AGENT: "eve" }`, which tells agent-aware CLIs to skip interactive prompts. Apply it beneath your environment-level variables when you create the sandbox, as the built-in providers do. A per-call `env` passed to `spawn()` overrides both. If the backend has no sandbox-level environment, merge it beneath the per-call `env` in `spawn()` instead, as in `{ ...SANDBOX_AGENT_ENV, ...env }`.
+
+## Report missing templates
+
+Throw `SandboxTemplateNotProvisionedError` from `start()` or `resume()` when the artifact names an image, snapshot, or template that no longer exists:
+
+```ts
+import { SandboxTemplateNotProvisionedError } from "eve/sandbox/provider";
+
+throw new SandboxTemplateNotProvisionedError({
+  providerName: "acme",
+  reason: "The snapshot expired.",
+  templateKey: artifact.snapshotId,
+});
+```
+
+eve surfaces the error to the caller and never retries or rebuilds the template at runtime. eve throws the same error when a deployment has no artifact for the sandbox. Template retention and pruning stay with the provider. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#sandbox-template--is-not-available-to-this-runtime).
+
+## Migrate from the handle-based API
+
+Earlier releases asked a provider to return a handle with a complete sandbox session. To move a provider to the current API:
+
+- Return `{ connection, state }` from `start()` and a connection from `resume()`, instead of a handle. Move provider-specific session methods to `extensions`.
+- Remove `onSandboxStop()` and `onRuntimeShutdown()`; implement `connection.stop()`. Move `onSandboxDelete()` into `onSessionEnd()`, which receives `reason: "deleted"`.
+- Replace hashes of `ctx.resources` and `ctx.sourceRevision` with `ctx.templateKey()`, and replace writes of resource files plus your own `prepare` call with `ctx.populate()`. Remove `prepare` from your environment options; eve owns it.
+- Replace `ctx.host.resolveProjectPath()` with `ctx.resolveProjectPath()`. `ctx.host.loadOptionalPackage()` is no longer available; import your SDK directly.
+- Drop the explicit type arguments to `defineSandboxProvider()` and let TypeScript infer them. `environment()` now receives `{}` instead of `undefined` when the sandbox file passes no options.
+- Rename `SandboxPreparedArtifact` to `SandboxJson`, `SandboxProviderSessionContext` to `SandboxSessionContext`, and `SandboxProviderPrepareContext` to `SandboxPrepareContext`. `SandboxProviderHandle`, `SandboxProviderResources`, `SandboxProviderResourceTree`, `SandboxProviderResourceFile`, `SandboxProviderResourceSource`, and `SandboxProviderTargetFile` are removed.
+
+Two changes in `eve/sandbox` also affect code outside providers:
+
+- `SandboxSession` has a required `writeFiles()` method, so an object you build by hand as a `SandboxSession`, such as a test double, needs one.
+- `SandboxNetworkPolicy` is an eve-owned type with `readonly` members instead of the Vercel Sandbox SDK's `NetworkPolicy`. Code that passes a policy to the SDK directly needs its own conversion.