Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs(research): propose a low-level sandbox provider API (#5229)

Andrew Barba2487542522a0
diff --git a/research/sandbox-environments-open.md b/research/sandbox-environments-open.md
index c2b983c08..309954e51 100644
--- a/research/sandbox-environments-open.md
+++ b/research/sandbox-environments-open.md
@@ -6,6 +6,9 @@ last_updated: "2026-10-22"
# Sandbox environments and provider sessions
+> [!NOTE]
+> [`sandbox-provider-api.md`](./sandbox-provider-api.md) supersedes the provider contract, provider-handle lifecycle hooks, the rule that core never reserves `prepare`, and the native identity section of this plan. The environment `open()` model, immutable session state, and gone semantics still apply.
+
## Decision
Authors configure an immutable provider environment, then open its sandbox for the current eve session:
diff --git a/research/sandbox-provider-api.md b/research/sandbox-provider-api.md
new file mode 100644
index 000000000..82ce01589
--- /dev/null
+++ b/research/sandbox-provider-api.md
@@ -0,0 +1,554 @@
+---
+issue: "TBD (maintainer-requested research; no matching issue found)"
+status: proposed
+last_updated: "2026-10-22"
+---
+
+# Low-level sandbox provider API
+
+## Summary
+
+Replace the public `defineSandboxProvider()` contract with a smaller one that
+custom backends and eve's built-in providers (Vercel Sandbox, Docker,
+just-bash, and a later host provider) all use. A backend implements a
+byte-level `SandboxConnection` and a lifecycle of `prepare`, `start`, `resume`,
+and `onSessionEnd`. eve derives the full `SandboxSession`, seeds build
+instances, hashes template keys, and maps stop, delete, and shutdown onto that
+lifecycle.
+
+Related: #3502 (third-party provider), #3717 (typed `prepare` sandbox), #4774
+(batched writes), #5020 (custom session methods).
+
+## Problem
+
+Verified against `main` at `a2c6d64ed3`:
+
+- **Custom providers write the whole session.** `SandboxProviderHandle.sandbox`
+ must implement all ten `SandboxSession` methods. The builder that derives them
+ from primitives, `buildSandboxSession`, is internal. The e2e `custom-provider`
+ fixture hand-writes all ten.
+- **Three stop-like handle hooks.** `onSandboxStop`, `onRuntimeShutdown`, and
+ `onSandboxDelete`. Docker and Vercel map the first two to the same stop call,
+ and each built-in's `onSandboxDelete` repeats what its `onSessionEnd` does.
+- **Recovery and capabilities are private.** `SandboxSessionGoneError` (#5117)
+ is not exported. Keyed `invokeTool` sandboxes require a private `WeakMap`
+ marker (`withToolSessionSandboxes`). Batched writes use the private
+ `SANDBOX_WRITE_FILES` symbol.
+- **Built-ins duplicate the same work.** Each one hashes template keys from
+ resource keys and `sourceRevision`, seeds workspace and skill files before
+ authored `prepare`, defines `resolvePath`, and builds the handle trio.
+- **Third-party types leak.** Session types derive from the AI SDK,
+ `SandboxNetworkPolicy` aliases `Vercel.NetworkPolicy`, `eve/sandbox/vercel`
+ re-exports `Drive`, and just-bash options expose `CustomCommand` and
+ `IFileSystem`.
+
+## Constraints
+
+- **Build-time baking stays.** Vercel snapshots, Docker images, and just-bash
+ template directories capture workspace and skill files plus authored `prepare`
+ during `eve build` (or first access in `eve dev`). Prepared artifacts are JSON
+ in `sandbox-prepared-artifacts.json` and ship with the deployment. Snapshot
+ providers cannot seed skills on first open.
+- **A running sandbox keeps its build.** The artifact applies only when `start()`
+ creates the sandbox. `resume()` receives the current deployment's artifact but
+ reconnects existing native state.
+- **Contract from #5132 and #5117.** `start()` is an idempotent upsert keyed by
+ the session. `onSessionEnd(ctx, state | null, { reason })` is required and
+ idempotent. `resume()` may throw `SandboxSessionGoneError`.
+- **Core writes dynamic skills at runtime** through the session (`writeSandboxFiles`
+ in `shared/skill-package.ts`).
+- **Migration is invisible to running sessions.** Native session names, session
+ state shapes, and template keys stay byte-identical.
+
+## Proposal
+
+### Layer 0: eve-owned session types
+
+`eve/sandbox` declares its own `SandboxSession`, run, spawn, process, read,
+write, and network-policy types instead of deriving them from `ai` or
+`@vercel/sandbox`. A type test asserts that `SandboxSession` stays assignable to
+the AI SDK's `Experimental_SandboxSession` method set. `SandboxSession` gains a
+public `writeFiles()`; a batch is not atomic, and a rejected batch may leave
+earlier files written (#4774).
+
+```ts
+export interface SandboxProcess {
+ readonly pid?: number;
+ readonly stdout: ReadableStream<Uint8Array>;
+ readonly stderr: ReadableStream<Uint8Array>;
+ wait(): Promise<{ readonly exitCode: number }>;
+ kill(): Promise<void>;
+}
+
+export type SandboxNetworkPolicy =
+ | "allow-all"
+ | "deny-all"
+ | {
+ readonly allow?: readonly string[] | Readonly<Record<string, readonly SandboxNetworkRule[]>>;
+ readonly subnets?: { readonly allow?: readonly string[]; readonly deny?: readonly string[] };
+ };
+
+/** Exactly one of `transform` (inject headers) or `forwardURL` (proxy the request). */
+export type SandboxNetworkRule = { readonly match?: SandboxNetworkMatch } & (
+ | { readonly transform: readonly { readonly headers?: Readonly<Record<string, string>> }[] }
+ | { readonly forwardURL: string }
+);
+
+/** Each matcher sets exactly one of `exact`, `startsWith`, or `regex`. */
+export interface SandboxNetworkMatch {
+ readonly path?: SandboxNetworkMatcher;
+ readonly method?: readonly string[];
+ readonly queryString?: readonly { key?: SandboxNetworkMatcher; value?: SandboxNetworkMatcher }[];
+ readonly headers?: readonly { key?: SandboxNetworkMatcher; value?: SandboxNetworkMatcher }[];
+}
+```
+
+`SandboxNetworkPolicy` keeps the shape that today's `isSandboxNetworkPolicy`
+validator accepts. The Vercel provider type-checks it against
+`@vercel/sandbox`'s `NetworkPolicy` internally.
+
+### Layer 1: the connection a backend implements
+
+```ts
+export interface SandboxConnection<Extensions extends object = {}> {
+ spawn(options: {
+ readonly command: string;
+ readonly workingDirectory: string;
+ readonly env: Readonly<Record<string, string>>;
+ readonly abortSignal?: AbortSignal;
+ }): Promise<SandboxProcess>;
+ readFile(options: {
+ readonly path: string;
+ readonly abortSignal?: AbortSignal;
+ }): Promise<Uint8Array | ReadableStream<Uint8Array> | null>;
+ writeFiles(options: SandboxWriteFilesOptions): Promise<void>;
+ removePath(options: SandboxRemovePathOptions): Promise<void>;
+ /** Releases compute and keeps the sandbox's files. */
+ stop(): Promise<void>;
+ /** Releases what this process holds, such as a local interpreter, without touching the sandbox. */
+ close?(): Promise<void>;
+ /** Provider capabilities merged onto the session, such as `setNetworkPolicy`. */
+ readonly extensions?: Extensions;
+}
+```
+
+Each method has a fixed contract:
+
+- `spawn` 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.
+- `readFile` resolves to `null` only when the path does not exist. A directory
+ or an unreadable path rejects. A backend returns bytes or a stream, whichever
+ it has; eve normalizes both.
+- `writeFiles` creates missing parent directories and overwrites existing files.
+ It is the only write primitive. Every built-in already buffers each write
+ before sending it, so a bytes-only primitive does not regress them.
+- Every path a connection receives is absolute, and `workingDirectory` is
+ always set. eve is the only owner of path resolution: relative paths and a
+ relative or missing `workingDirectory` resolve from `/workspace`, which every
+ built-in's `resolvePath` already does.
+
+eve derives the rest of `SandboxSession`: `run` over `spawn`, binary and text
+variants, encodings and line ranges, single-file writes over `writeFiles`, path
+and working-directory resolution, abort-signal binding, and logging during
+preparation. Extension members that collide with a `SandboxSession` member are
+a type error (`never`), and eve throws on them at runtime.
+
+### Layer 2: the provider lifecycle
+
+```ts
+export function defineSandboxProvider<
+ EnvironmentOptions extends object | undefined,
+ OpenOptions extends object | undefined,
+ Artifact extends SandboxJson,
+ State extends SandboxJson,
+ Extensions extends object,
+>(definition: {
+ readonly name: string;
+ readonly stateProtocolVersion?: number;
+ environment(
+ ...args: SandboxOptionArguments<EnvironmentOptions>
+ ): SandboxProviderImplementation<OpenOptions, Artifact, State, Extensions>;
+}): SandboxProvider<
+ WithPrepareOption<EnvironmentOptions, SandboxSession & Extensions>,
+ OpenOptions,
+ SandboxSession & Extensions
+>;
+
+export interface SandboxProviderImplementation<OpenOptions, Artifact, State, Extensions> {
+ prepare(ctx: SandboxPrepareContext<Extensions>): Promise<Artifact>;
+ start(
+ ctx: SandboxSessionContext,
+ options: Readonly<OpenOptions> | undefined,
+ artifact: Readonly<Artifact>,
+ ): Promise<{ readonly connection: SandboxConnection<Extensions>; readonly state: State }>;
+ resume(
+ ctx: SandboxSessionContext,
+ artifact: Readonly<Artifact>,
+ state: Readonly<State>,
+ ): Promise<SandboxConnection<Extensions>>;
+ onSessionEnd(
+ ctx: SandboxSessionContext,
+ state: Readonly<State> | null,
+ options: {
+ readonly reason: "completed" | "expired" | "failed" | "deleted";
+ readonly abortSignal?: AbortSignal;
+ },
+ ): Promise<void>;
+ /** Set when sandboxes may outlive one keyed `invokeTool` call. See invariants. */
+ readonly toolSessions?: true;
+}
+
+export interface SandboxSessionContext {
+ /** Unchanged: `session.id` is the sandbox owner's id, which native names derive from. */
+ readonly session: SandboxSelectorContext["session"];
+ readonly kind: "session" | "tool-session";
+ readonly storagePath: string;
+ resolveProjectPath(path: string): string;
+}
+
+export interface SandboxPrepareContext<Extensions extends object> {
+ readonly files: SandboxProviderFiles;
+ readonly storagePath: string;
+ /** No workspace or skill files and no authored `prepare`. */
+ readonly isEmpty: boolean;
+ log(message: string): void;
+ resolveProjectPath(path: string): string;
+ templateKey(identity: SandboxIdentity): string;
+ /** A stable read-only host directory with `workspace/` and `skills/`, when one exists. */
+ resourcesDirectory(): Promise<string | undefined>;
+ /** Seeds `/workspace` and `$HOME/.agents/skills`, then runs authored `prepare`. */
+ populate(
+ connection: SandboxConnection<Extensions>,
+ options?: { readonly mountedAt?: string },
+ ): Promise<void>;
+}
+
+export type WithPrepareOption<Options, Session> = Options extends undefined
+ ? SandboxPrepareOption<Session> | undefined
+ : Options & SandboxPrepareOption<Session>;
+
+export interface SandboxPrepareOption<Session> {
+ readonly prepare?: (sandbox: Session) => void | Promise<void>;
+}
+```
+
+Type parameters are inferred from the returned implementation, so authors do
+not pass five explicit generics. `SandboxJson` is today's
+`SandboxPreparedArtifact` under a name that fits both artifacts and state.
+
+`ctx.session.id` keeps its current meaning: the id of the session that owns
+the sandbox. For a subagent that shares its parent's sandbox, that is the
+parent's id. For a keyed `invokeTool` call, it is the derived `tool_session_`
+id. `kind` replaces the internal `isToolSessionId` check that Vercel uses
+today.
+
+`templateKey(identity)` returns exactly:
+
+```ts
+createSandboxProviderIdentity({
+ ...identity,
+ resources: { skills: skillsTreeKey, workspace: workspaceTreeKey },
+ sourceRevision,
+});
+```
+
+This is the same SHA-256 hex that each built-in computes today. `resources`
+and `sourceRevision` are reserved, and eve throws if `identity` sets either one.
+`SandboxIdentity` is whatever the hasher accepts: JSON values, `undefined`
+(omitted), plain objects and arrays, and functions (hashed as
+`function:<source>`). Circular values and other types reject. just-bash
+includes its `customCommands` and `filesystem` functions, so its key stays
+reproducible.
+
+`populate()` writes the workspace and skill files through
+`connection.writeFiles()` in one batch. With `mountedAt`, the provider has
+mounted `resourcesDirectory()` read-only at that sandbox path, and `populate()`
+copies `<mountedAt>/workspace/.` into `/workspace` and `<mountedAt>/skills/.`
+into `$HOME/.agents/skills` instead of writing them, as Docker does today.
+Either way, authored `prepare` runs next, with a logging session over the same
+connection.
+
+`resolveProjectPath` stays on both contexts because just-bash's `filesystem`
+callback and a host provider need project paths. `host.loadOptionalPackage`
+leaves the public context. just-bash calls eve's internal optional-package
+loaders directly, an allowed internal engine helper: the installing loader in
+`prepare` and the import-only loader in `start` and `resume`, as the two host
+implementations do today. It passes `ctx.resolveProjectPath(".")` as the app
+root.
+
+`prepare` becomes a standard environment option through `WithPrepareOption`,
+typed with the provider's extensions (#3717). A provider without environment
+options still accepts `{ prepare }`. eve removes `prepare` before calling the
+provider's `environment()` and runs it inside `populate()`. No built-in
+includes `prepare` in its template identity today. `sourceRevision` hashes only
+the sandbox definition's source file, so it captures a `prepare` written there
+but not one imported from another module (see open questions).
+
+### Export inventory
+
+| Module | Export | Change |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `eve/sandbox/provider` | `defineSandboxProvider`, `SandboxProviderDefinition`, `SandboxProviderImplementation` | New shape |
+| `eve/sandbox/provider` | `SandboxProvider`, `SandboxProviderFiles`, `SandboxDeleteOptions` | Unchanged |
+| `eve/sandbox/provider` | `SandboxPreparedArtifact`, `SandboxProviderSessionContext`, `SandboxProviderPrepareContext` | Renamed `SandboxJson`, `SandboxSessionContext`, `SandboxPrepareContext` |
+| `eve/sandbox/provider` | `SandboxConnection`, `SandboxIdentity`, `SandboxPrepareOption`, `WithPrepareOption`, `SandboxSessionGoneError`, `SandboxTemplateNotProvisionedError`, `SANDBOX_AGENT_ENV` | Added |
+| `eve/sandbox/provider` | `SandboxProviderHandle`, `SandboxProviderResources`, `SandboxProviderResourceTree`, `SandboxProviderResourceFile`, `SandboxProviderResourceSource`, `SandboxProviderTargetFile` | Removed |
+| `eve/sandbox` | `SandboxSession` and its option, process, and result types; `SandboxNetworkPolicy` | eve-owned declarations; `SandboxSession` gains `writeFiles` |
+| `eve/sandbox` | `SandboxNetworkRule`, `SandboxNetworkMatch`, `SandboxNetworkMatcher`, `SandboxWriteFilesOptions`, `SandboxRemovePathOptions` | Added |
+| `eve/sandbox/vercel` | `Drive`; `VercelSandboxMount`, `VercelSandboxMounts`, `VercelSandboxMountMode` | `Drive` removed; mount types become eve-owned structural types |
+| `eve/sandbox/just-bash` | `JustBashEnvironmentOptions`, `JustBashFilesystemContext` | `customCommands` and `filesystem` use eve-owned structural types |
+
+Ensure orchestration, the artifact store, identity hashing, `invokeTool`
+wiring, and Docker CLI and Vercel SDK glue stay internal.
+
+## Lifecycle
+
+```text
+build (eve build, or first access in eve dev)
+ eve ─ prepare(ctx) ─▶ provider: create build instance → connection
+ ctx.populate(connection) ─▶ eve: write /workspace and
+ $HOME/.agents/skills, then run authored prepare
+ provider: capture image or snapshot → artifact (JSON)
+ eve: store artifact in sandbox-prepared-artifacts.json (ships with deployment)
+
+runtime
+ first access ─ selector → environment.open(options)
+ → start(ctx, options, artifact) → { connection, state }
+ eve checkpoints { providerName, state, stateProtocolVersion }
+ later step ─ resume(ctx, artifact, state) → connection
+ └─ throws SandboxSessionGoneError → eve clears state, reruns selector
+ sandbox.stop() → connection.stop()
+ sandbox.delete() → connection.close?(), onSessionEnd(ctx, state, { reason: "deleted" }),
+ eve clears state
+ process exit → connection.stop() (failures logged, not thrown)
+ keyed call ends → connection.close?()
+ terminal outcome → onSessionEnd(ctx, state | null, { reason })
+```
+
+## Invariants
+
+- **Upsert.** `start()` returns the same sandbox for one `ctx.session.id` while
+ that sandbox exists and is usable, across repeated, concurrent,
+ cross-process, and cross-deployment calls. Native identity comes from
+ `ctx.session.id` and a provider-level namespace only, never from open options
+ or the artifact.
+- **No recreation on resume.** `resume()` never recreates native state. A
+ missing sandbox throws `SandboxSessionGoneError`; other failures surface
+ unchanged.
+- **Cleanup.** `onSessionEnd()` succeeds when nothing exists, tolerates `null`
+ state, and is idempotent. `sandbox.delete()` goes through it with
+ `reason: "deleted"`, so a provider has one deletion path.
+- **Keyed tool sessions.** A keyed `invokeTool` call always starts with
+ `state: null` and does not own the sandbox. eve runs the selector and
+ `start()` on every call and never calls `onSessionEnd()`. The one `resume()`
+ is for a call that overlaps another call's start in the same process: it
+ resumes from that start's state. Because nothing ever ends a keyed sandbox, a
+ provider that sets `toolSessions: true` must bound retention itself, as Vercel
+ does with snapshot expiration. Without `toolSessions`, a keyed call fails with
+ `ToolSessionSandboxUnsupportedError` when it requests a sandbox; a keyed
+ call that never calls `ctx.getSandbox()` runs normally. An unkeyed call uses a fresh
+ `call_session_` id with `kind: "session"`, and calls `onSessionEnd()` when it
+ ends if it requested a sandbox.
+- **Missing templates.** A provider throws `SandboxTemplateNotProvisionedError`
+ when the artifact references an image, snapshot, or template that no longer
+ exists. eve throws it too when a deployment has no artifact for the sandbox.
+ eve surfaces it to the caller without retrying or rebuilding in production.
+ Template retention and pruning stay with the provider.
+- **Seeding.** `populate()` writes workspace and skill files before authored
+ `prepare`, and runs only at build time. Runtime never seeds.
+- **Paths.** Relative paths and working directories resolve from `/workspace`;
+ eve resolves `$HOME` in skill targets. This changes one behavior: Vercel
+ passes a relative `workingDirectory` to the SDK unchanged today, while Docker
+ and just-bash already resolve it from `/workspace`. The Vercel migration PR
+ states this in its changeset.
+- **Environment.** Providers apply `SANDBOX_AGENT_ENV` (`AI_AGENT=eve`) beneath
+ environment-level `env` when they create the sandbox, as Docker and Vercel do
+ today. Per-call `env` overrides both. just-bash has no environment-level
+ `env`, so its connection merges `SANDBOX_AGENT_ENV` beneath per-call `env`.
+- **Network policy.** A provider that accepts a `SandboxNetworkPolicy`, at open
+ or through `setNetworkPolicy`, rejects any part it cannot enforce instead of
+ weakening it. Docker accepts only `"allow-all"` and `"deny-all"` and throws
+ on allow-lists, subnets, and credential brokering (`docker-network.ts`).
+- **Serialization.** eve rejects artifacts and state that are not
+ JSON-compatible, and state whose `stateProtocolVersion` differs from the
+ provider's. Providers validate the shape of their own state in `resume()`.
+ The contract has no validator hooks.
+
+## Byte-identical built-ins
+
+Each built-in keeps its own native-name derivation from `ctx.session.id` and
+passes exactly its current identity fields to `ctx.templateKey()`. Each
+migration PR adds a golden test that the old and new template keys and session
+names match.
+
+| Provider | Session name (unchanged) | Template identity passed to `templateKey` |
+| -------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Docker | `eve-sbx-` + hash of `{ namespace: storagePath, sessionId, version: 2 }` | `{ dockerfile: dockerfile?.contentHash, optionsHash, version: 2 }`, first 24 hex |
+| Vercel Sandbox | `eve-sbx-vercel-` + hash of `{ sessionId, version: 2 }` | `{ createOptions: vercelIdentityOptions(createOptions), resolvedImage, version: 3 }`, where `resolvedImage` is `undefined` when `source` is set; first 32 hex, `eve-sbx-tpl-vercel-` prefix |
+| just-bash | root directory from hash of `{ sessionId, version: 2 }` | `{ autoInstall, customCommands, filesystem, version: 2 }`, first 24 hex |
+
+Docker mounts `await ctx.resourcesDirectory()` and calls
+`ctx.populate(connection, { mountedAt: "/eve/resources" })`. Vercel's
+`DefaultSandbox` facade skips preparation when `ctx.isEmpty`;
+`VercelSandbox.environment()` does not. Vercel and just-bash set
+`toolSessions: true`; only just-bash needs `close()`.
+
+## Custom provider example
+
+A backend for a hypothetical snapshot-capable engine, `@acme/sdk`:
+
+```ts
+import { createHash } from "node:crypto";
+import { defineSandbox } from "eve/sandbox";
+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 key = ctx.templateKey({ project: options.project, version: 1 });
+ const template = `eve-tpl-${key.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 as const } };
+ },
+ 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(),
+ };
+}
+
+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" }));
+```
+
+## Migration
+
+The public shape changes once, in the first implementation PR. Until each
+built-in migrates, core keeps running today's `SandboxProviderImplementation`
+as an internal type. An internal adapter compiles the new public shape to it,
+so `ensureSandboxAccess`, prewarm, and the artifact store stay unchanged until
+the last step. There are no public dual-shape overloads.
+
+1. Switch the public `defineSandboxProvider()` to the new shape, export
+ `SandboxSessionGoneError`, `SandboxTemplateNotProvisionedError`, and
+ `SANDBOX_AGENT_ENV`, and add `ctx.kind`. In the same PR, update the
+ custom-provider docs in `docs/sandbox/index.mdx`, migrate the e2e
+ `custom-provider` fixture, and add evals for gone-sandbox recovery and for
+ keyed calls on a provider without `toolSessions`. Built-ins keep the old
+ shape through the internal type (minor changeset).
+2. Migrate just-bash, with the golden key and name test.
+3. Migrate Docker, with the golden key and name test.
+4. Migrate Vercel Sandbox, with the golden key and name test. Its changeset
+ notes that a relative `workingDirectory` now resolves from `/workspace`.
+5. Make core consume the new shape directly. Remove the internal old shape,
+ the tool-session `WeakMap`, and `SANDBOX_WRITE_FILES`. Add a
+ `guard:invariants` rule for files under `src/execution/sandbox/bindings/`
+ and `src/sandbox/providers/`: they may import the provider contract only
+ through `#public/sandbox/*`, and may not import core sandbox modules
+ (`#execution/sandbox/{ensure,prewarm,session,logging-session}.js`,
+ `#execution/tool-session/*`, `#runtime/sandbox/*`, or
+ `#shared/sandbox-{provider,session,write-files}.js`). Engine helpers such
+ as other binding modules, stream utilities, and the optional-package loader
+ stay allowed.
+6. Later: a host provider on the same contract.
+
+## Open questions
+
+- **Host provider network policy.** A host provider cannot enforce any
+ `SandboxNetworkPolicy` except `"allow-all"`. Under the network-policy
+ invariant it rejects everything else; decide whether it should also omit
+ `setNetworkPolicy`.
+- **Extension types through wrappers.** Abort binding, logging, and the runtime
+ lifecycle proxy must keep extension members and their types. #5020 needs a
+ type test that covers each wrapper.
+- **Imported `prepare` callbacks.** `sourceRevision` misses changes to a
+ `prepare` imported from another module, so a template can stay stale. Now
+ that eve owns `prepare`, it could hash the bundled callback's module graph
+ into the template key. That changes every key once, so it belongs in its own
+ PR.
+
+## Relationship to other plans
+
+This proposal supersedes three parts of
+[`sandbox-environments-open.md`](./sandbox-environments-open.md) (draft):
+
+- **Provider contract and handle hooks.** Connections and `onSessionEnd` replace
+ `SandboxProviderHandle`.
+- **`prepare` ownership.** That plan said core never reserves `prepare`. This
+ one makes it a standard option so eve can seed before `prepare`, compute
+ `isEmpty`, and type the `prepare` sandbox with provider extensions.
+- **Native identity.** That plan derived native identity from the session id,
+ artifact, environment options, and open options, with no core-computed keys.
+ Since #5132, native identity comes from the session id and a provider
+ namespace only, and this proposal adds the core-computed `templateKey`.
+
+Its environment `open()` model, immutable session state, and gone semantics
+still apply.