The Open Framework for Building Agents
issue: "TBD (maintainer-requested research; no matching issue found)" status: in-progress 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.sandboxmust implement all tenSandboxSessionmethods. The builder that derives them from primitives,buildSandboxSession, is internal. The e2ecustom-providerfixture hand-writes all ten. - Three stop-like handle hooks.
onSandboxStop,onRuntimeShutdown, andonSandboxDelete. Docker and Vercel map the first two to the same stop call, and each built-in'sonSandboxDeleterepeats what itsonSessionEnddoes. - Recovery and capabilities are private.
SandboxSessionGoneError(#5117) is not exported. KeyedinvokeToolsandboxes require a privateWeakMapmarker (withToolSessionSandboxes). Batched writes use the privateSANDBOX_WRITE_FILESsymbol. - Built-ins duplicate the same work. Each one hashes template keys from
resource keys and
sourceRevision, seeds workspace and skill files before authoredprepare, definesresolvePath, and builds the handle trio. - Third-party types leak. Session types derive from the AI SDK,
SandboxNetworkPolicyaliasesVercel.NetworkPolicy,eve/sandbox/vercelre-exportsDrive, and just-bash options exposeCustomCommandandIFileSystem.
Constraints
- Build-time baking stays. Vercel snapshots, Docker images, and just-bash
template directories capture workspace and skill files plus authored
prepareduringeve build(or first access ineve dev). Prepared artifacts are JSON insandbox-prepared-artifacts.jsonand 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 throwSandboxSessionGoneError. - Core writes dynamic skills at runtime through the session (
writeSandboxFilesinshared/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).
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
export interface SandboxConnection<Extensions extends object = {}> {
/** Absolute; relative paths resolve from it and commands start in it. Defaults to `/workspace`. */
readonly workspaceRoot?: string;
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:
spawnrunscommandas a Bash login-shell script (bash -lc) inworkingDirectory, with the sandbox's environment plusenv.envholds only the per-call variables. Aborting kills the process tree.readFileresolves tonullonly 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.writeFilescreates 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
workingDirectoryis always set. eve is the only owner of path resolution: relative paths and a relative or missingworkingDirectoryresolve from the connection'sworkspaceRoot,/workspaceunless the connection declares another absolute directory. Every built-in keeps the default.
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
export function defineSandboxProvider<
EnvironmentOptions extends object,
OpenOptions extends object | undefined,
Artifact extends SandboxJson,
State extends SandboxJson,
Extensions extends object,
>(definition: {
readonly name: string;
readonly stateProtocolVersion?: number;
environment(
options: EnvironmentOptions,
): SandboxProviderImplementation<OpenOptions, Artifact, State, Extensions>;
}): SandboxProvider<
WithPrepareOption<EnvironmentOptions, SandboxSession & Extensions>,
OpenOptions,
SandboxSession & Extensions
>;
export interface SandboxProviderImplementation<OpenOptions, Artifact, State, Extensions> {
prepare(ctx: SandboxPrepareContext): 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 {
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 the connection's workspace root and `$HOME/.agents/skills`, then runs authored `prepare`. */
populate(
connection: SandboxConnection<object>,
options?: { readonly mountedAt?: string },
): Promise<void>;
}
export type WithPrepareOption<Options extends object, Session> = 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. environment() takes a plain parameter, and
SandboxPrepareContext is not generic over the extensions, because TypeScript
cannot infer through a conditional rest tuple and fixes a type parameter as soon
as a context-sensitive method such as prepare(ctx) uses it. State comes from
start()'s return value when start() precedes resume(). 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:
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 the workspace root 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(), which always receives an object ({} when the
caller passes none), 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
build (eve build, or first access in eve dev)
eve ─ prepare(ctx) ─▶ provider: create build instance → connection
ctx.populate(connection) ─▶ eve: write the workspace root
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
step ends → connection.close?() (a turn's step, a "use step" function, or an
invokeTool call; the next step resumes through a new connection)
sandbox.stop() → connection.stop(), connection.close?()
sandbox.delete() → connection.close?(), onSessionEnd(ctx, state, { reason: "deleted" }),
eve clears state
process exit → connection.stop(), connection.close?() on the connections the process
still holds: any connection mid-step, and each session's latest
connection without close() (failures logged, not thrown); a provider
with close() and remote compute bounds idle compute itself
terminal outcome → connection.close?() for a connection the ending step holds,
onSessionEnd(ctx, state | null, { reason })
(close runs at most once per connection; stop is idempotent and may run again after
the connection resumes; a failed close never blocks deletion)
Invariants
- Upsert.
start()returns the same sandbox for onectx.session.idwhile that sandbox exists and is usable, across repeated, concurrent, cross-process, and cross-deployment calls. Native identity comes fromctx.session.idand a provider-level namespace only, never from open options or the artifact. - No recreation on resume.
resume()never recreates native state. A missing sandbox throwsSandboxSessionGoneError; other failures surface unchanged. - Cleanup.
onSessionEnd()succeeds when nothing exists, toleratesnullstate, and is idempotent.sandbox.delete()goes through it withreason: "deleted", so a provider has one deletion path. - Keyed tool sessions. A keyed
invokeToolcall always starts withstate: nulland does not own the sandbox. eve runs the selector andstart()on every call and never callsonSessionEnd(). The oneresume()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 setstoolSessions: truemust bound retention itself, as Vercel does with snapshot expiration. WithouttoolSessions, a keyed call fails withToolSessionSandboxUnsupportedErrorwhen it requests a sandbox; a keyed call that never callsctx.getSandbox()runs normally. An unkeyed call uses a freshcall_session_id withkind: "session", and callsonSessionEnd()when it ends if it requested a sandbox. - Missing templates. A provider throws
SandboxTemplateNotProvisionedErrorwhen 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 authoredprepare, and runs only at build time. Runtime never seeds. - Paths. Relative paths and working directories resolve from the
connection's workspace root; eve resolves
$HOMEin skill targets.session.resolvePath(".")returns the root, which is how the file tools, attachment staging, and GitHub checkouts find it. This changes one behavior: Vercel passes a relativeworkingDirectoryto 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-levelenvwhen they create the sandbox, as Docker and Vercel do today. Per-callenvoverrides both. just-bash has no environment-levelenv, so its connection mergesSANDBOX_AGENT_ENVbeneath per-callenv. - Network policy. A provider that accepts a
SandboxNetworkPolicy, at open or throughsetNetworkPolicy, 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
stateProtocolVersiondiffers from the provider's. Providers validate the shape of their own state inresume(). 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 skips
preparation when ctx.isEmpty and no source is set, in
VercelSandbox.environment() itself and therefore under DefaultSandbox too.
Vercel and just-bash set toolSessions: true; no built-in needs close().
Custom provider example
A backend for a hypothetical snapshot-capable engine, @acme/sdk:
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.
- Switch the public
defineSandboxProvider()to the new shape, exportSandboxSessionGoneError,SandboxTemplateNotProvisionedError, andSANDBOX_AGENT_ENV, and addctx.kind. In the same PR, update the custom-provider docs indocs/sandbox/index.mdx, migrate the e2ecustom-providerfixture, and add evals for gone-sandbox recovery and for keyed calls on a provider withouttoolSessions. Built-ins keep the old shape through the internal type (minor changeset). Implemented: the publicwriteFiles()replacedSANDBOX_WRITE_FILESin this step, and unit tests through the public API cover keyed calls, because no e2e fixture has a custom root sandbox behind a keyed channel. - Migrate just-bash, with the golden key and name test.
- Migrate Docker, with the golden key and name test.
- Migrate Vercel Sandbox, with the golden key and name test. Its changeset
notes that a relative
workingDirectorynow resolves from/workspace. Implemented:VercelSandbox.environment()itself keeps skipping an empty preparation without asource, because deployed self-modification relies on it, and the same step removedDrive(minor changeset). - Make core consume the new shape directly. Remove the internal old shape,
and the tool-session
WeakMap. Close a connection when the step that opened it lets go of it; until then, eve closes connections only at the other lifecycle points above. Add aguard:invariantsrule for files undersrc/execution/sandbox/bindings/andsrc/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. Implemented:ensureSandboxAccessruns the implementation and its connections directly,createConnectionSession()inexecution/sandbox/session.tsderives every session, andprewarm.tsbuilds the prepare context. A workflow step, a turn's step, and a keyed or unkeyedinvokeToolcall close their connection when they end; after a turn's step, a connection withoutclose()stays registered for server shutdown.DefaultSandboxis adefineSandboxProvider()selector over the three built-ins and keeps its two internal hooks: session end receives the prepared artifact, and records the picked provider wrote still resume. The guard is rule 44. The opaque provider runtime onSandboxEnvironmentbumped six extension contract epochs, all retained. - Workspace-root paths. Implemented:
SandboxConnection.workspaceRootdeclares the root, defaulting to/workspace; eve rejects a relative one when it opens the connection. The built-in file tools accept paths relative to the root,globandgrepsearch it by default, and model-facing prompts no longer name/workspace, because they are composed before any sandbox opens. The skill root stays$HOME/.agents/skills, falling back toskills/under the workspace root. - Later: a host provider on the same contract.
Open questions
- Host provider network policy. A host provider cannot enforce any
SandboxNetworkPolicyexcept"allow-all". Under the network-policy invariant it rejects everything else; decide whether it should also omitsetNetworkPolicy. - 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
preparecallbacks.sourceRevisionmisses changes to aprepareimported from another module, so a template can stay stale. Now that eve ownsprepare, 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 (draft):
- Provider contract and handle hooks. Connections and
onSessionEndreplaceSandboxProviderHandle. prepareownership. That plan said core never reservesprepare. This one makes it a standard option so eve can seed beforeprepare, computeisEmpty, and type thepreparesandbox 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.