@evelandhq/sandbox-bwrap 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,8 @@
 # @evelandhq/sandbox-bwrap
 
-A [bubblewrap](https://github.com/containers/bubblewrap)-based `SandboxBackend` for
-[eve](https://www.npmjs.com/package/eve) agents. It gives agent-executed code a real
+A [bubblewrap](https://github.com/containers/bubblewrap)-based sandbox for
+[eve](https://www.npmjs.com/package/eve) agents: a sandbox provider for eve 0.64 and later,
+and a `SandboxBackend` for eve 0.62 and 0.63. It gives agent-executed code a real
 Linux sandbox — actual binaries, isolated filesystem, coarse network control — without
 requiring a Docker daemon or KVM.
 
@@ -16,7 +17,8 @@ namespaces.
 
 ## Usage
 
-**Deployed on eveland:** you do nothing. eveland's Docker and systemd runtimes generate
+**Deployed on eveland:** you do nothing. (What follows describes the integration for eve
+0.63 and earlier.) eveland's Docker and systemd runtimes generate
 the sandbox module into the release directory at build time — `agent/sandbox.js` for a flat
 agent, or `agent/sandbox/sandbox.js` when a sandbox folder exists, recursively for every
 subagent — and vendors this package's built output beside it, so agent projects never declare
@@ -35,7 +37,47 @@ the eveland build pipeline, so it falls back to eve's default backend chain (usu
 build log looks like and what happens when the sandbox does not work on the host.
 
 **Standalone use of this package** (outside eveland, or in any project that manages its
-own `agent/sandbox.ts`) still works the manual way:
+own `agent/sandbox.ts`) depends on which sandbox API your eve has.
+
+### eve 0.64 and later: `BwrapSandbox`
+
+eve 0.64 replaced sandbox backends with providers. Import the provider from the
+`/provider` entry point and export its environment:
+
+```ts
+// agent/sandbox.ts
+import { defineSandbox } from "eve/sandbox";
+import { BwrapSandbox } from "@evelandhq/sandbox-bwrap/provider";
+
+export const environment = BwrapSandbox.environment({
+  // Optional: setup every new sandbox inherits. Runs once, during `eve build`.
+  prepare: async (sandbox) => {
+    const result = await sandbox.run({ command: "pip install --user requests" });
+    if (result.exitCode !== 0) throw new Error(result.stderr);
+  },
+});
+
+export default defineSandbox(() => environment.open());
+```
+
+- `eve build` prepares the template: it writes the workspace and skill trees, then runs
+  `prepare` inside bwrap, so a build that runs `prepare` needs bwrap on the build host. The
+  template lives under `.eve/sandbox-cache/bwrap/templates` in the built app, and eve records
+  its absolute path. Serve the build from where it was built, or rebuild on the deploy host;
+  a missing template fails the first sandbox access with a rebuild message.
+- eve records which provider prepared each sandbox and refuses to open it with a different
+  one. Choose the provider from something that is the same at build and run time, not from
+  `isBwrapAvailable()` on hosts that differ.
+- `environment.open({ networkPolicy: "deny-all" })` sets a session's initial network policy.
+  It is recorded in the session state and applied again after a restart.
+- eve resumes a session from its recorded state alone. The template is not needed, so with a
+  shared `cacheDir` a session keeps its workspace when it moves to a newer deployment.
+- The `/provider` entry point imports `eve/sandbox/provider`, which exists only from eve
+  0.64 on. The package root imports nothing from eve at runtime and also exports the plain
+  provider definition, `createBwrapSandboxProviderDefinition()`, for callers that call eve's
+  `defineSandboxProvider` themselves.
+
+### eve 0.62 and 0.63: `bwrap()`
 
 ```ts
 // agent/sandbox.ts
@@ -50,20 +92,23 @@ export default defineSandbox({
 
 ### eve version requirement
 
-This package requires `eve` `>=0.27.0 <1.0.0`.
+This package requires `eve` `>=0.62.0 <1.0.0`.
 
 The range is deliberately wide. eve's 0.x releases use caret-incompatible minor bumps,
 so a package that pins a narrow window has to republish for every eve minor — which is
 churn for consumers, not safety, when the surface actually consumed is one small
-interface (`SandboxBackend` from `eve/sandbox`) that changes rarely. Rather than
+interface that changes rarely. The range spans two such interfaces: `SandboxBackend` for
+eve 0.62 and 0.63, and the sandbox provider contract from eve 0.64 on. Rather than
 re-declaring the window, CI keeps the claim honest from both ends:
 `src/eve-compatibility.test.ts` typechecks the backend against the range's exact floor
-(0.27.13) and the newest verified release on every run, and a scheduled workflow re-runs
-the suite against `eve@latest` so a breaking eve minor shows up as a red build here
-instead of a bug report from your deployment. That is not theoretical: eve 0.32.0 added a
-required `stop()` to the backend handle. This package implements it; 0.1.0 does not, and
-pairing that release with eve `>=0.32.0` resolves cleanly and then fails at runtime the
-first time authored code calls `ctx.getSandbox().stop()`.
+(0.62.0; 0.63.0, the last eve that calls backends, ships identical sandbox types), and
+typechecks the provider against the newest verified release; a scheduled workflow re-runs the suite against
+`eve@latest` so a breaking eve minor shows up as a red build here instead of a bug report
+from your deployment. That is not theoretical: eve 0.32.0 added a required `stop()` to the
+backend handle. This package implements it; 0.1.0 does not, and pairing that release with
+eve `>=0.32.0` resolves cleanly and then fails at runtime the first time authored code calls
+`ctx.getSandbox().stop()`. Likewise, releases up to 0.3.0 import a value that eve 0.64
+removed, so they cannot load at all on eve 0.64 and later.
 
 The backend implements both handle lifecycle methods by killing every process the session
 has spawned that has not yet exited: `shutdown()`, which eve calls at server teardown and
@@ -74,30 +119,55 @@ because the processes are the compute. Neither method touches the session's work
 directory — it is durable state. Cleanup closes that compute generation to new commands;
 the next backend `create()` opens a fresh generation over the same workspace. Repeated
 `create()` calls through one backend instance share the live generation, so one handle
-cannot race a new spawn past another handle's cleanup barrier.
+cannot race a new spawn past another handle's cleanup barrier. The provider's
+`onSessionStop()` and `onRuntimeShutdown()` do the same, and its `resume()` shares the live
+generation the same way.
 
 ### Options
 
-| Option                   | Default                              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`                    | `{}`                                 | Environment variables set for every sandboxed command.                                                                                                                                                                                                                                                                                                                                                                                            |
-| `networkPolicy`          | `"allow-all"`                        | `"allow-all"` shares the host network; `"deny-all"` runs each command with no network (`--unshare-net`). `setNetworkPolicy` can switch between the two at run time; granular domain policies are rejected (use the Vercel backend for those).                                                                                                                                                                                                     |
-| `hidePaths`              | `[]`                                 | Extra host paths hidden from the sandbox (each covered by an empty tmpfs).                                                                                                                                                                                                                                                                                                                                                                        |
-| `bwrapPath`              | `"bwrap"`                            | bwrap executable to invoke.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `cacheDir`               | `<appRoot>/.eve/sandbox-cache/bwrap` | Absolute directory holding templates and durable session workspaces. Pin this outside the release directory so a redeploy does not discard durable session state: since eve 0.22.0, eve keys session sandboxes per durable session, not per deployment, so an `appRoot`-derived default would silently destroy every session's `/workspace` on the next redeploy. The generated eveland module always sets this from `EVELAND_SANDBOX_CACHE_DIR`. |
-| `templateRevision`       | `null`                               | Optional immutable release identity included in the template cache key but not the session path. Change it when seed files change so new Sessions use a fresh template without overwriting durable workspaces. Eveland sets it from its internal `EVELAND_SANDBOX_TEMPLATE_REVISION`.                                                                                                                                                             |
-| `runTimeoutMs`           | `600000`                             | Hard wall-clock limit for one `run()` command. Timeout aborts the command and kills its complete bwrap process group. Set `null` to disable it. The limit deliberately does not apply to `spawn()`, which is the API for long-running processes.                                                                                                                                                                                                  |
-| `maxConcurrentProcesses` | `64`                                 | Maximum live `run()`/`spawn()` commands admitted in one compute generation. A live `spawn()` counts until it actually exits, even when its caller never waits. Set `null` to disable.                                                                                                                                                                                                                                                             |
-| `maxOutputBytes`         | `16777216`                           | Maximum combined stdout and stderr retained by one `run()` call. Exceeding it aborts and reaps the complete process group. Set `null` to disable. Streaming `spawn()` output is not retained by this backend.                                                                                                                                                                                                                                     |
-| `onEvent`                | `undefined`                          | Best-effort structured lifecycle sink for generation, command, and cleanup events. Sink failures are ignored so telemetry cannot change command behavior.                                                                                                                                                                                                                                                                                         |
-
-Both lifecycle callbacks may call `use({ networkPolicy: "allow-all" | "deny-all" })`. The
+| Option                   | Default                              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`                    | `{}`                                 | Environment variables set for every sandboxed command.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `networkPolicy`          | `"allow-all"`                        | `"allow-all"` shares the host network; `"deny-all"` runs each command with no network (`--unshare-net`). `setNetworkPolicy` can switch between the two at run time; granular domain policies are rejected (use the Vercel backend for those).                                                                                                                                                                                                                                                                                                            |
+| `hidePaths`              | `[]`                                 | Extra host paths hidden from the sandbox (each covered by an empty tmpfs).                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `bwrapPath`              | `"bwrap"`                            | bwrap executable to invoke.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `cacheDir`               | `<appRoot>/.eve/sandbox-cache/bwrap` | Absolute directory holding durable session workspaces, and, for the backend, templates. The provider always keeps templates in eve's build storage, where eve records them. Pin this outside the release directory so a redeploy does not discard durable session state: since eve 0.22.0, eve keys session sandboxes per durable session, not per deployment, so an `appRoot`-derived default would silently destroy every session's `/workspace` on the next redeploy. The generated eveland module always sets this from `EVELAND_SANDBOX_CACHE_DIR`. |
+| `templateRevision`       | `null`                               | Backend only. Optional immutable release identity included in the template cache key but not the session path. Change it when seed files change so new Sessions use a fresh template without overwriting durable workspaces. Eveland sets it from its internal `EVELAND_SANDBOX_TEMPLATE_REVISION`.                                                                                                                                                                                                                                                      |
+| `runTimeoutMs`           | `600000`                             | Hard wall-clock limit for one `run()` command. Timeout aborts the command and kills its complete bwrap process group. Set `null` to disable it. The limit deliberately does not apply to `spawn()`, which is the API for long-running processes.                                                                                                                                                                                                                                                                                                         |
+| `maxConcurrentProcesses` | `64`                                 | Maximum live `run()`/`spawn()` commands admitted in one compute generation. A live `spawn()` counts until it actually exits, even when its caller never waits. Set `null` to disable.                                                                                                                                                                                                                                                                                                                                                                    |
+| `maxOutputBytes`         | `16777216`                           | Maximum combined stdout and stderr retained by one `run()` call. Exceeding it aborts and reaps the complete process group. Set `null` to disable. Streaming `spawn()` output is not retained by this backend.                                                                                                                                                                                                                                                                                                                                            |
+| `onEvent`                | `undefined`                          | Best-effort structured lifecycle sink for generation, command, and cleanup events. Sink failures are ignored so telemetry cannot change command behavior.                                                                                                                                                                                                                                                                                                                                                                                                |
+
+`BwrapSandbox.environment()` takes the same options except `templateRevision`, which the
+provider does not need: eve's source revision and resource keys already key its templates.
+It adds `prepare`, described above.
+
+With the backend, both lifecycle callbacks may call `use({ networkPolicy: "allow-all" | "deny-all" })`. The
 policy is applied before `use()` returns the template or live Session, so subsequent commands in
 that callback use the requested network boundary. Calling `use()` without options keeps the
 backend's configured policy.
 
 ## How it works
 
+The provider (eve 0.64 and later):
+
+- **prepare** (`eve build`): writes eve's workspace tree and skill tree
+  (`$HOME/.agents/skills/**` lands at `/workspace/.agents/skills/**`) into a staging
+  directory, runs the authored `prepare` inside bwrap, stops anything it left running, and
+  atomically renames the result into `<storage>/bwrap/templates/<hash>`, where `<storage>`
+  is eve's sandbox storage directory, `<appRoot>/.eve/sandbox-cache`. The key covers eve's
+  source revision, the resource keys, the options, and the source of `prepare`.
+- **start** (first sandbox access of a session): clones the template into
+  `<cacheDir>/sessions/<hash>`, keyed by eve's session id, and returns the session state eve
+  persists: the session key and the network policy.
+- **resume** (every later access, and after restarts): reopens the recorded workspace and
+  applies the recorded network policy to a new compute generation. It fails instead of
+  recreating a workspace that is gone.
+- **onSessionDelete**: kills the session's processes and removes its workspace and
+  metadata; the template survives.
+
+The backend (eve 0.62 and 0.63):
+
 - **prewarm** (build time): resolves Eve's `$HOME/.agents/skills/**` seed paths to
   `/workspace/.agents/skills/**`, writes every seed into a staging directory, then runs the
   authored `bootstrap` inside bwrap so it can consume those canonical inputs, before atomically
@@ -123,7 +193,10 @@ backend's configured policy.
 ## Disk usage and cache management
 
 Session and template directories persist under `<cacheDir>/{sessions,templates}` across
-process restarts and reconnects, enabling fast reattach. `stop()` and `shutdown()` never
+process restarts and reconnects, enabling fast reattach. The provider keeps its templates
+under eve's storage directory instead (`<appRoot>/.eve/sandbox-cache/bwrap/templates`), so
+they go away with the build that prepared them; pass that `appRoot` without `cacheDir` to the
+APIs below to inspect them. `stop()` and `shutdown()` never
 delete durable state, and this package never schedules automatic deletion. On Eveland,
 the cache lives at `EVELAND_SANDBOX_CACHE_DIR` outside every release directory, so a
 redeploy does not touch it.

package/dist/backend-contract.d.ts

@@ -0,0 +1,49 @@
+import type { BwrapSandboxUseOptions } from "./options.js";
+import type { BwrapSession } from "./session.js";
+export interface BwrapSeedFile {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+}
+export interface BwrapBackendRuntimeContext {
+    readonly appRoot: string;
+}
+export interface BwrapBackendCreateInput {
+    readonly templateKey: string | null;
+    readonly sessionKey: string;
+    readonly existingMetadata?: Record<string, unknown>;
+    readonly tags?: Readonly<Record<string, string>>;
+    readonly runtimeContext: BwrapBackendRuntimeContext;
+}
+export interface BwrapBackendBootstrapContext {
+    use(options?: BwrapSandboxUseOptions): Promise<BwrapSession>;
+}
+export interface BwrapBackendPrewarmInput {
+    readonly templateKey: string;
+    readonly bootstrap?: (input: BwrapBackendBootstrapContext) => void | Promise<void>;
+    readonly log?: (message: string) => void;
+    readonly runtimeContext: BwrapBackendRuntimeContext;
+    readonly seedFiles: ReadonlyArray<BwrapSeedFile>;
+}
+export interface BwrapBackendSessionState {
+    readonly backendName: string;
+    readonly metadata: Record<string, unknown>;
+    readonly sessionKey: string;
+}
+export interface BwrapBackendHandle {
+    readonly session: BwrapSession;
+    readonly useSessionFn: (options?: BwrapSandboxUseOptions) => Promise<BwrapSession>;
+    captureState(): Promise<BwrapBackendSessionState>;
+    delete(options?: {
+        readonly abortSignal?: AbortSignal;
+    }): Promise<void>;
+    stop(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/** The bubblewrap sandbox backend, for eve 0.62 and 0.63. */
+export interface BwrapSandboxBackend {
+    readonly name: string;
+    create(input: BwrapBackendCreateInput): Promise<BwrapBackendHandle>;
+    prewarm(input: BwrapBackendPrewarmInput): Promise<{
+        readonly reused: boolean;
+    }>;
+}

package/dist/backend-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/backend.d.ts

@@ -1,5 +1,5 @@
-import type { SandboxBackend } from "eve/sandbox";
-import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
+import type { BwrapSandboxBackend } from "./backend-contract.js";
+import type { BwrapSandboxCreateOptions } from "./options.js";
 import type { ProcessRunner } from "./process.js";
 import { type BwrapDirectoryCopier } from "./cache.js";
 /**
@@ -14,4 +14,5 @@ export interface CreateBwrapSandboxBackendInput {
     /** Injectable clone primitive for filesystem-capability tests. */
     readonly copyDirectory?: BwrapDirectoryCopier;
 }
-export declare function createBwrapSandboxBackend(input?: CreateBwrapSandboxBackendInput): SandboxBackend<BwrapSandboxUseOptions, BwrapSandboxUseOptions>;
+/** The backend for eve 0.62 and 0.63. eve 0.64 and later use `BwrapSandbox` instead. */
+export declare function createBwrapSandboxBackend(input?: CreateBwrapSandboxBackendInput): BwrapSandboxBackend;

package/dist/backend.js

@@ -2,92 +2,21 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, rename, rm } from "node:fs/promises";
 import { basename } from "node:path";
-import { SandboxTemplateNotProvisionedError } from "eve/sandbox";
+import { BwrapTemplateNotProvisionedError } from "./errors.js";
 import { createBwrapOptionsHash, resolveBwrapSandboxOptions } from "./options.js";
-import { resolveBwrapCacheRoot, resolveSessionPath, resolveTemplatePath, WORKSPACE_ROOT, } from "./paths.js";
-import { createNodeProcessRunner, describeMissingPrereqs, isBwrapAvailable } from "./process.js";
-import { createBwrapSession } from "./session.js";
-import { cloneDirectoryAtomically, createBwrapCacheLease, registerActiveCachePath, removeCacheMetadata, touchCacheMetadata, } from "./cache.js";
-const EVE_MODEL_SKILL_ROOT = "$HOME/.agents/skills";
+import { resolveBwrapCacheRoot, resolveSessionPath, resolveTemplatePath } from "./paths.js";
+import { createBwrapRuntime, writeSeedFiles } from "./runtime.js";
+import { cloneDirectoryAtomically, removeCacheMetadata, touchCacheMetadata, } from "./cache.js";
 /**
  * Stable backend name. Participates in eve's template/session cache-key
  * derivation and persisted reconnect state — never change it.
  */
 export const BWRAP_BACKEND_NAME = "bwrap";
+/** The backend for eve 0.62 and 0.63. eve 0.64 and later use `BwrapSandbox` instead. */
 export function createBwrapSandboxBackend(input = {}) {
     const options = resolveBwrapSandboxOptions(input.createOptions);
     const optionsHash = createBwrapOptionsHash(options);
-    const runner = input.runner ?? createNodeProcessRunner();
-    const generations = new Map();
-    // Probe only when running against the real bwrap; injected runners skip it.
-    const shouldProbe = input.runner === undefined;
-    let probed = false;
-    function assertBwrapAvailable() {
-        if (!shouldProbe || probed)
-            return;
-        const missing = describeMissingPrereqs({
-            bwrapPresent: isBwrapAvailable(options.bwrapPath),
-            workspaceMountpointPresent: existsSync(WORKSPACE_ROOT),
-            bwrapPath: options.bwrapPath,
-        });
-        if (missing)
-            throw new Error(missing);
-        probed = true;
-    }
-    function openSession(id, workspaceDir, appRoot, tags, generationId, onStopped) {
-        return createBwrapSession({
-            id,
-            workspaceDir,
-            appRoot,
-            runner,
-            options,
-            tags,
-            generationId,
-            onStopped,
-        });
-    }
-    async function openRuntimeSession(id, workspaceDir, appRoot, tags) {
-        const current = generations.get(workspaceDir);
-        if (current && current.lifecycleState() !== "stopped")
-            return current;
-        const releaseActive = registerActiveCachePath(workspaceDir);
-        const cacheRoot = resolveBwrapCacheRoot(appRoot, options.cacheDir);
-        const activeLease = await createBwrapCacheLease({
-            cacheRoot,
-            sessionId: basename(workspaceDir),
-        });
-        let session;
-        try {
-            session = openSession(id, workspaceDir, appRoot, tags, activeLease.lease.generationId, async () => {
-                releaseActive();
-                await activeLease.release();
-            });
-        }
-        catch (error) {
-            releaseActive();
-            await activeLease.release();
-            throw error;
-        }
-        generations.set(workspaceDir, session);
-        return session;
-    }
-    function resolveSeedPath(seedPath) {
-        if (seedPath === EVE_MODEL_SKILL_ROOT || seedPath.startsWith(`${EVE_MODEL_SKILL_ROOT}/`)) {
-            return `${WORKSPACE_ROOT}/.agents/skills${seedPath.slice(EVE_MODEL_SKILL_ROOT.length)}`;
-        }
-        return seedPath;
-    }
-    async function writeSeedFiles(session, seedFiles) {
-        for (const seed of seedFiles) {
-            const seedPath = resolveSeedPath(seed.path);
-            if (typeof seed.content === "string") {
-                await session.writeTextFile({ path: seedPath, content: seed.content });
-            }
-            else {
-                await session.writeBinaryFile({ path: seedPath, content: seed.content });
-            }
-        }
-    }
+    const runtime = createBwrapRuntime({ options, runner: input.runner });
     async function useSession(session, useOptions) {
         if (useOptions?.networkPolicy !== undefined) {
             await session.setNetworkPolicy(useOptions.networkPolicy);
@@ -97,7 +26,7 @@ export function createBwrapSandboxBackend(input = {}) {
     return {
         name: BWRAP_BACKEND_NAME,
         async prewarm({ templateKey, bootstrap, seedFiles, log, runtimeContext }) {
-            assertBwrapAvailable();
+            runtime.assertBwrapAvailable();
             const templatePath = resolveTemplatePath(runtimeContext.appRoot, templateKey, optionsHash, options.cacheDir);
             const touchTemplate = async () => await touchCacheMetadata({
                 cacheRoot: resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir),
@@ -113,7 +42,11 @@ export function createBwrapSandboxBackend(input = {}) {
             const stagingPath = `${templatePath}.staging-${randomUUID()}`;
             await mkdir(stagingPath, { recursive: true });
             try {
-                const session = openSession(templateKey, stagingPath, runtimeContext.appRoot);
+                const session = runtime.openTemplateSession({
+                    id: templateKey,
+                    workspaceDir: stagingPath,
+                    cacheRoots: [resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir)],
+                });
                 await writeSeedFiles(session, seedFiles);
                 if (bootstrap) {
                     await bootstrap({ use: async (useOptions) => await useSession(session, useOptions) });
@@ -133,7 +66,7 @@ export function createBwrapSandboxBackend(input = {}) {
             return { reused: false };
         },
         async create({ templateKey, sessionKey, runtimeContext, tags }) {
-            assertBwrapAvailable();
+            runtime.assertBwrapAvailable();
             const sessionPath = resolveSessionPath(runtimeContext.appRoot, sessionKey, options.cacheDir);
             let cloneStrategy = "existing";
             if (!existsSync(sessionPath)) {
@@ -144,10 +77,7 @@ export function createBwrapSandboxBackend(input = {}) {
                 else {
                     const templatePath = resolveTemplatePath(runtimeContext.appRoot, templateKey, optionsHash, options.cacheDir);
                     if (!existsSync(templatePath)) {
-                        throw new SandboxTemplateNotProvisionedError({
-                            backendName: BWRAP_BACKEND_NAME,
-                            templateKey,
-                        });
+                        throw new BwrapTemplateNotProvisionedError({ templateKey });
                     }
                     cloneStrategy = await cloneDirectoryAtomically({
                         sourcePath: templatePath,
@@ -163,7 +93,14 @@ export function createBwrapSandboxBackend(input = {}) {
                 tags,
                 cloneStrategy,
             });
-            const session = await openRuntimeSession(sessionKey, sessionPath, runtimeContext.appRoot, tags);
+            const cacheRoot = resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir);
+            const { session } = await runtime.openRuntimeSession({
+                id: sessionKey,
+                workspaceDir: sessionPath,
+                cacheRoots: [cacheRoot],
+                leaseRoot: cacheRoot,
+                tags,
+            });
             return {
                 session,
                 useSessionFn: async (useOptions) => await useSession(session, useOptions),
@@ -195,7 +132,7 @@ export function createBwrapSandboxBackend(input = {}) {
                 async delete(deleteOptions) {
                     deleteOptions?.abortSignal?.throwIfAborted();
                     await session.killAll();
-                    generations.delete(sessionPath);
+                    runtime.forgetRuntimeSession(sessionPath);
                     await rm(sessionPath, { force: true, recursive: true });
                     await removeCacheMetadata({
                         cacheRoot: resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir),

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Thrown when a session needs a template that was never prepared.
+ *
+ * eve recognizes this error structurally rather than by class, so this package
+ * can throw it without importing eve at runtime. `name` and `templateKey` are
+ * checked by every eve line; `backendName` is what eve 0.62 and 0.63 look for,
+ * and `providerName` is what 0.64 and later look for. It carries both, so
+ * the same error works for the backend and the provider.
+ */
+export declare class BwrapTemplateNotProvisionedError extends Error {
+    readonly name = "SandboxTemplateNotProvisionedError";
+    readonly backendName = "bwrap";
+    readonly providerName = "bwrap";
+    readonly templateKey: string;
+    constructor(input: {
+        readonly templateKey: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Thrown when a session needs a template that was never prepared.
+ *
+ * eve recognizes this error structurally rather than by class, so this package
+ * can throw it without importing eve at runtime. `name` and `templateKey` are
+ * checked by every eve line; `backendName` is what eve 0.62 and 0.63 look for,
+ * and `providerName` is what 0.64 and later look for. It carries both, so
+ * the same error works for the backend and the provider.
+ */
+export class BwrapTemplateNotProvisionedError extends Error {
+    name = "SandboxTemplateNotProvisionedError";
+    backendName = "bwrap";
+    providerName = "bwrap";
+    templateKey;
+    constructor(input) {
+        super(`Sandbox template "${input.templateKey}" is not provisioned for bwrap. ` +
+            "Run `eve build` before serving traffic.");
+        this.templateKey = input.templateKey;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-import type { SandboxBackend } from "eve/sandbox";
-import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
+import type { BwrapSandboxBackend } from "./backend-contract.js";
+import type { BwrapSandboxCreateOptions } from "./options.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, type CreateBwrapSandboxBackendInput, } from "./backend.js";
+export type { BwrapBackendBootstrapContext, BwrapBackendCreateInput, BwrapBackendHandle, BwrapBackendPrewarmInput, BwrapBackendRuntimeContext, BwrapBackendSessionState, BwrapSandboxBackend, BwrapSeedFile, } from "./backend-contract.js";
+export { BwrapTemplateNotProvisionedError } from "./errors.js";
+export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, type BwrapPreparedArtifact, type BwrapSandboxEnvironmentOptions, type BwrapSandboxOpenOptions, type BwrapSandboxProviderDefinition, type BwrapSessionState, type CreateBwrapSandboxProviderDefinitionInput, } from "./provider-definition.js";
+export type { BwrapSession } from "./session.js";
 export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions, BwrapSandboxUseOptions, } from "./options.js";
 export type { BwrapCommandFinishReason, BwrapSandboxEvent, BwrapSandboxEventSink, } from "./events.js";
 export { listBwrapCache, listBwrapCacheLeases, pruneBwrapCache } from "./cache.js";
@@ -9,7 +13,9 @@ export { DEFAULT_MAX_CONCURRENT_PROCESSES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_RUN
 export { isBwrapAvailable } from "./process.js";
 export type { ProcessRunner, SpawnedProcess } from "./process.js";
 /**
- * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.
+ * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`, the
+ * sandbox API of eve 0.62 and 0.63. On eve 0.64 and later use `BwrapSandbox`
+ * from `@evelandhq/sandbox-bwrap/provider` instead.
  *
  * ```ts
  * // agent/sandbox.ts
@@ -21,4 +27,4 @@ export type { ProcessRunner, SpawnedProcess } from "./process.js";
  * });
  * ```
  */
-export declare function bwrap(options?: BwrapSandboxCreateOptions): SandboxBackend<BwrapSandboxUseOptions, BwrapSandboxUseOptions>;
+export declare function bwrap(options?: BwrapSandboxCreateOptions): BwrapSandboxBackend;

package/dist/index.js

@@ -1,10 +1,14 @@
 import { createBwrapSandboxBackend } from "./backend.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, } from "./backend.js";
+export { BwrapTemplateNotProvisionedError } from "./errors.js";
+export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, } from "./provider-definition.js";
 export { listBwrapCache, listBwrapCacheLeases, pruneBwrapCache } from "./cache.js";
 export { DEFAULT_MAX_CONCURRENT_PROCESSES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_RUN_TIMEOUT_MS, } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 /**
- * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.
+ * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`, the
+ * sandbox API of eve 0.62 and 0.63. On eve 0.64 and later use `BwrapSandbox`
+ * from `@evelandhq/sandbox-bwrap/provider` instead.
  *
  * ```ts
  * // agent/sandbox.ts

package/dist/paths.d.ts

@@ -8,6 +8,16 @@ export declare const WORKSPACE_ROOT = "/workspace";
 export declare function resolveBwrapCacheRoot(appRoot: string, cacheDir?: string | null): string;
 export declare function resolveTemplatePath(appRoot: string, templateKey: string, optionsHash: string, cacheDir?: string | null): string;
 export declare function resolveSessionPath(appRoot: string, sessionKey: string, cacheDir?: string | null): string;
+/**
+ * The provider's cache root inside eve's sandbox storage directory
+ * (`<appRoot>/.eve/sandbox-cache`), the same place the backend's default
+ * cache root resolves to. eve prepares templates there at build time and
+ * records their path, so templates always live here, even when `cacheDir`
+ * moves session workspaces elsewhere.
+ */
+export declare function resolveProviderCacheRoot(storagePath: string): string;
+export declare function templatePathIn(cacheRoot: string, templateKey: string, optionsHash: string): string;
+export declare function sessionPathIn(cacheRoot: string, sessionKey: string): string;
 /** Anchors a sandbox-relative path to /workspace; absolute paths pass through. */
 export declare function resolveWorkspacePath(path: string): string;
 /**

package/dist/paths.js

@@ -15,10 +15,26 @@ function keyDigest(value) {
     return createHash("sha256").update(value).digest("hex").slice(0, 32);
 }
 export function resolveTemplatePath(appRoot, templateKey, optionsHash, cacheDir) {
-    return join(resolveBwrapCacheRoot(appRoot, cacheDir), "templates", `${keyDigest(templateKey)}-${optionsHash}`);
+    return templatePathIn(resolveBwrapCacheRoot(appRoot, cacheDir), templateKey, optionsHash);
 }
 export function resolveSessionPath(appRoot, sessionKey, cacheDir) {
-    return join(resolveBwrapCacheRoot(appRoot, cacheDir), "sessions", keyDigest(sessionKey));
+    return sessionPathIn(resolveBwrapCacheRoot(appRoot, cacheDir), sessionKey);
+}
+/**
+ * The provider's cache root inside eve's sandbox storage directory
+ * (`<appRoot>/.eve/sandbox-cache`), the same place the backend's default
+ * cache root resolves to. eve prepares templates there at build time and
+ * records their path, so templates always live here, even when `cacheDir`
+ * moves session workspaces elsewhere.
+ */
+export function resolveProviderCacheRoot(storagePath) {
+    return join(storagePath, "bwrap");
+}
+export function templatePathIn(cacheRoot, templateKey, optionsHash) {
+    return join(cacheRoot, "templates", `${keyDigest(templateKey)}-${optionsHash}`);
+}
+export function sessionPathIn(cacheRoot, sessionKey) {
+    return join(cacheRoot, "sessions", keyDigest(sessionKey));
 }
 /** Anchors a sandbox-relative path to /workspace; absolute paths pass through. */
 export function resolveWorkspacePath(path) {

package/dist/provider-definition.d.ts

@@ -0,0 +1,49 @@
+import type { MutableNetworkSandboxSession } from "eve/sandbox";
+import type { SandboxProviderDefinition } from "eve/sandbox/provider";
+import { type BwrapDirectoryCopier } from "./cache.js";
+import type { BwrapNetworkPolicy, BwrapSandboxCreateOptions } from "./options.js";
+import type { ProcessRunner } from "./process.js";
+/**
+ * Version of the session state this provider persists through eve. eve refuses
+ * to resume state written under a different version, so bump it only together
+ * with a reader for the old shape.
+ */
+export declare const BWRAP_PROVIDER_STATE_PROTOCOL_VERSION = 1;
+/** Options for `BwrapSandbox.environment(...)`. */
+export type BwrapSandboxEnvironmentOptions = Omit<BwrapSandboxCreateOptions, "templateRevision"> & {
+    /**
+     * Setup every new sandbox inherits. eve runs it once, when `eve build`
+     * prepares the template, not for each session. Commands it runs execute in
+     * bwrap, so the build host needs bwrap too.
+     */
+    readonly prepare?: (sandbox: MutableNetworkSandboxSession) => Promise<void>;
+};
+/** Options for `environment.open(...)`, applied when a session's sandbox is first started. */
+export interface BwrapSandboxOpenOptions {
+    readonly networkPolicy?: BwrapNetworkPolicy;
+}
+/** What `eve build` records for a prepared template. */
+export type BwrapPreparedArtifact = {
+    readonly version: 1;
+    readonly templatePath: string;
+};
+/** What eve persists for one durable session's sandbox. */
+export type BwrapSessionState = {
+    readonly version: 1;
+    readonly sessionKey: string;
+    readonly networkPolicy: BwrapNetworkPolicy;
+};
+export interface CreateBwrapSandboxProviderDefinitionInput {
+    /** Injectable process launcher so provider logic is testable without bwrap. */
+    readonly runner?: ProcessRunner;
+    /** Injectable clone primitive for filesystem-capability tests. */
+    readonly copyDirectory?: BwrapDirectoryCopier;
+}
+export type BwrapSandboxProviderDefinition = SandboxProviderDefinition<BwrapSandboxEnvironmentOptions, BwrapSandboxOpenOptions, BwrapPreparedArtifact, BwrapSessionState, MutableNetworkSandboxSession>;
+/**
+ * The bubblewrap sandbox provider for eve 0.64 and later, as a plain
+ * definition. Pass it to eve's `defineSandboxProvider`, or import the ready
+ * `BwrapSandbox` from `@evelandhq/sandbox-bwrap/provider`. This module imports
+ * nothing from eve at runtime, so it loads on every eve in the peer range.
+ */
+export declare function createBwrapSandboxProviderDefinition(input?: CreateBwrapSandboxProviderDefinitionInput): BwrapSandboxProviderDefinition;

package/dist/provider-definition.js

@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { basename } from "node:path";
+import { cloneDirectoryAtomically, removeCacheMetadata, touchCacheMetadata, } from "./cache.js";
+import { BwrapTemplateNotProvisionedError } from "./errors.js";
+import { createBwrapOptionsHash, resolveBwrapSandboxOptions } from "./options.js";
+import { resolveProviderCacheRoot, sessionPathIn, templatePathIn } from "./paths.js";
+import { createBwrapRuntime, writeSeedFiles } from "./runtime.js";
+/**
+ * Version of the session state this provider persists through eve. eve refuses
+ * to resume state written under a different version, so bump it only together
+ * with a reader for the old shape.
+ */
+export const BWRAP_PROVIDER_STATE_PROTOCOL_VERSION = 1;
+/**
+ * The bubblewrap sandbox provider for eve 0.64 and later, as a plain
+ * definition. Pass it to eve's `defineSandboxProvider`, or import the ready
+ * `BwrapSandbox` from `@evelandhq/sandbox-bwrap/provider`. This module imports
+ * nothing from eve at runtime, so it loads on every eve in the peer range.
+ */
+export function createBwrapSandboxProviderDefinition(input = {}) {
+    return {
+        name: "bwrap",
+        stateProtocolVersion: BWRAP_PROVIDER_STATE_PROTOCOL_VERSION,
+        environment(environmentOptions) {
+            const { prepare, ...createOptions } = environmentOptions ?? {};
+            const options = resolveBwrapSandboxOptions(createOptions);
+            const optionsHash = createBwrapOptionsHash(options);
+            const runtime = createBwrapRuntime({ options, runner: input.runner });
+            // Templates live beside eve's own prepared artifacts; sessions follow
+            // `cacheDir` when it is set, so they outlive the release that made them.
+            const cacheRoots = (storagePath) => {
+                const templateRoot = resolveProviderCacheRoot(storagePath);
+                const sessionRoot = options.cacheDir ?? templateRoot;
+                return { templateRoot, sessionRoot, hidden: [templateRoot, sessionRoot] };
+            };
+            async function openHandle(ctx, sessionKey, cloneStrategy, applyNetworkPolicy) {
+                const roots = cacheRoots(ctx.storagePath);
+                const sessionPath = sessionPathIn(roots.sessionRoot, sessionKey);
+                await touchCacheMetadata({
+                    cacheRoot: roots.sessionRoot,
+                    kind: "session",
+                    id: basename(sessionPath),
+                    tags: { sessionId: ctx.session.id },
+                    cloneStrategy,
+                });
+                const { session, created } = await runtime.openRuntimeSession({
+                    id: ctx.session.id,
+                    workspaceDir: sessionPath,
+                    cacheRoots: roots.hidden,
+                    leaseRoot: roots.sessionRoot,
+                });
+                await applyNetworkPolicy(session, created);
+                return {
+                    sandbox: session,
+                    // The processes are the compute and the workspace directory is the
+                    // durable session: stopping kills the processes and keeps the files.
+                    async onSessionStop() {
+                        await session.killAll();
+                    },
+                    async onRuntimeShutdown() {
+                        await session.killAll();
+                    },
+                    // The session's own workspace is disposable; the template it was
+                    // cloned from is shared by every other session and must survive.
+                    async onSessionDelete(deleteOptions) {
+                        deleteOptions?.abortSignal?.throwIfAborted();
+                        await session.killAll();
+                        runtime.forgetRuntimeSession(sessionPath);
+                        await rm(sessionPath, { force: true, recursive: true });
+                        await removeCacheMetadata({
+                            cacheRoot: roots.sessionRoot,
+                            kind: "session",
+                            id: basename(sessionPath),
+                        });
+                    },
+                };
+            }
+            return {
+                async prepare(ctx) {
+                    const templateKey = JSON.stringify({
+                        version: 1,
+                        sourceRevision: ctx.sourceRevision,
+                        workspace: ctx.resources.workspace?.key ?? null,
+                        skills: ctx.resources.skills?.key ?? null,
+                        // eve's source revision covers the sandbox module, not helpers it
+                        // imports, so the preparation's own source joins the key.
+                        prepare: prepare?.toString() ?? null,
+                    });
+                    const roots = cacheRoots(ctx.storagePath);
+                    const templatePath = templatePathIn(roots.templateRoot, templateKey, optionsHash);
+                    const artifact = { version: 1, templatePath };
+                    const touchTemplate = async () => await touchCacheMetadata({
+                        cacheRoot: roots.templateRoot,
+                        kind: "template",
+                        id: basename(templatePath),
+                    });
+                    if (existsSync(templatePath)) {
+                        await touchTemplate();
+                        ctx.log?.("bwrap: reusing the prepared template");
+                        return artifact;
+                    }
+                    ctx.log?.("bwrap: capturing the template");
+                    const stagingPath = `${templatePath}.staging-${randomUUID()}`;
+                    await mkdir(stagingPath, { recursive: true });
+                    try {
+                        const session = runtime.openTemplateSession({
+                            id: basename(templatePath),
+                            workspaceDir: stagingPath,
+                            cacheRoots: roots.hidden,
+                        });
+                        try {
+                            await writeSeedFiles(session, resourceSeeds(ctx.resources));
+                            if (prepare) {
+                                runtime.assertBwrapAvailable();
+                                ctx.log?.("bwrap: running sandbox preparation");
+                                await prepare(session);
+                            }
+                        }
+                        finally {
+                            // Nothing authored preparation started may outlive the capture.
+                            await session.killAll();
+                        }
+                        await rename(stagingPath, templatePath);
+                    }
+                    catch (error) {
+                        await rm(stagingPath, { force: true, recursive: true }).catch(() => { });
+                        // A concurrent preparation winning the race is reuse, not failure.
+                        if (existsSync(templatePath)) {
+                            await touchTemplate();
+                            return artifact;
+                        }
+                        throw error;
+                    }
+                    await touchTemplate();
+                    return artifact;
+                },
+                async start(ctx, openOptions, preparedArtifact) {
+                    runtime.assertBwrapAvailable();
+                    const { templatePath } = requireArtifact(preparedArtifact);
+                    const sessionKey = `session:${ctx.session.id}`;
+                    const sessionPath = sessionPathIn(cacheRoots(ctx.storagePath).sessionRoot, sessionKey);
+                    let cloneStrategy = "existing";
+                    if (!existsSync(sessionPath)) {
+                        if (!existsSync(templatePath)) {
+                            throw new BwrapTemplateNotProvisionedError({ templateKey: templatePath });
+                        }
+                        cloneStrategy = await cloneDirectoryAtomically({
+                            sourcePath: templatePath,
+                            targetPath: sessionPath,
+                            copyDirectory: input.copyDirectory,
+                        });
+                    }
+                    const networkPolicy = openOptions?.networkPolicy ?? options.networkPolicy;
+                    const handle = await openHandle(ctx, sessionKey, cloneStrategy, async (session) => {
+                        await session.setNetworkPolicy(networkPolicy);
+                    });
+                    return { handle, state: { version: 1, sessionKey, networkPolicy } };
+                },
+                // eve resumes at every durable step, and after a restart or a move to
+                // another deployment. Only the session workspace is needed, never the
+                // template, so the artifact passed here may belong to a newer build.
+                async resume(ctx, preparedArtifact, sessionState) {
+                    runtime.assertBwrapAvailable();
+                    requireArtifact(preparedArtifact);
+                    const state = requireSessionState(sessionState);
+                    const sessionPath = sessionPathIn(cacheRoots(ctx.storagePath).sessionRoot, state.sessionKey);
+                    if (!existsSync(sessionPath)) {
+                        throw new Error(`bwrap sandbox: session workspace ${sessionPath} no longer exists, so the sandbox cannot be resumed`);
+                    }
+                    // A live generation keeps whatever policy the session set since;
+                    // only a new generation starts over from the recorded one.
+                    return await openHandle(ctx, state.sessionKey, "existing", async (session, created) => {
+                        if (created)
+                            await session.setNetworkPolicy(state.networkPolicy);
+                    });
+                },
+            };
+        },
+    };
+}
+/** eve's workspace and skill trees as seeds at their sandbox target paths. */
+function resourceSeeds(resources) {
+    return [resources.workspace, resources.skills].flatMap((tree) => tree === undefined
+        ? []
+        : tree.files.map((file) => ({
+            path: `${tree.targetPath}/${file.relativePath}`,
+            content: file.content,
+        })));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireArtifact(value) {
+    if (!isRecord(value) || value.version !== 1 || typeof value.templatePath !== "string") {
+        throw new Error("bwrap sandbox: invalid prepared artifact; rebuild the agent with `eve build`");
+    }
+    return { version: 1, templatePath: value.templatePath };
+}
+function isNetworkPolicy(value) {
+    return value === "allow-all" || value === "deny-all";
+}
+function requireSessionState(value) {
+    if (!isRecord(value) ||
+        value.version !== 1 ||
+        typeof value.sessionKey !== "string" ||
+        !isNetworkPolicy(value.networkPolicy)) {
+        throw new Error("bwrap sandbox: invalid session state");
+    }
+    return { version: 1, sessionKey: value.sessionKey, networkPolicy: value.networkPolicy };
+}

package/dist/provider.d.ts

@@ -0,0 +1,18 @@
+export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, type BwrapPreparedArtifact, type BwrapSandboxEnvironmentOptions, type BwrapSandboxOpenOptions, type BwrapSandboxProviderDefinition, type BwrapSessionState, type CreateBwrapSandboxProviderDefinitionInput, } from "./provider-definition.js";
+export { isBwrapAvailable } from "./process.js";
+/**
+ * The bubblewrap sandbox provider for eve 0.64 and later.
+ *
+ * ```ts
+ * // agent/sandbox.ts
+ * import { defineSandbox } from "eve/sandbox";
+ * import { BwrapSandbox } from "@evelandhq/sandbox-bwrap/provider";
+ *
+ * export const environment = BwrapSandbox.environment();
+ * export default defineSandbox(() => environment.open());
+ * ```
+ *
+ * This entry point imports `eve/sandbox/provider`, which exists only from eve
+ * 0.64 on. On eve 0.62 and 0.63 use `bwrap()` from the package root.
+ */
+export declare const BwrapSandbox: import("eve/sandbox/provider").SandboxProvider<import("./provider-definition.js").BwrapSandboxEnvironmentOptions, import("./provider-definition.js").BwrapSandboxOpenOptions, import("eve/sandbox").MutableNetworkSandboxSession>;

package/dist/provider.js

@@ -0,0 +1,20 @@
+import { defineSandboxProvider } from "eve/sandbox/provider";
+import { createBwrapSandboxProviderDefinition } from "./provider-definition.js";
+export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, } from "./provider-definition.js";
+export { isBwrapAvailable } from "./process.js";
+/**
+ * The bubblewrap sandbox provider for eve 0.64 and later.
+ *
+ * ```ts
+ * // agent/sandbox.ts
+ * import { defineSandbox } from "eve/sandbox";
+ * import { BwrapSandbox } from "@evelandhq/sandbox-bwrap/provider";
+ *
+ * export const environment = BwrapSandbox.environment();
+ * export default defineSandbox(() => environment.open());
+ * ```
+ *
+ * This entry point imports `eve/sandbox/provider`, which exists only from eve
+ * 0.64 on. On eve 0.62 and 0.63 use `bwrap()` from the package root.
+ */
+export const BwrapSandbox = defineSandboxProvider(createBwrapSandboxProviderDefinition());

package/dist/runtime.d.ts

@@ -0,0 +1,45 @@
+import type { ResolvedBwrapSandboxOptions } from "./options.js";
+import type { ProcessRunner } from "./process.js";
+import type { BwrapSession } from "./session.js";
+export interface BwrapSeed {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+}
+export interface BwrapSessionLocation {
+    readonly id: string;
+    readonly workspaceDir: string;
+    /** Hidden from every sandboxed command; see `CreateBwrapSessionInput.cacheRoots`. */
+    readonly cacheRoots: readonly string[];
+    readonly tags?: Readonly<Record<string, string>>;
+}
+/**
+ * The session machinery the backend and the provider share: one live compute
+ * generation per workspace directory, each holding a cache lease so pruning
+ * never removes a workspace in use.
+ */
+export interface BwrapRuntime {
+    /** Throws a setup message when the host cannot run bwrap. Probed once. */
+    assertBwrapAvailable(): void;
+    /** A throwaway session over a template being captured; it holds no lease. */
+    openTemplateSession(location: BwrapSessionLocation): BwrapSession;
+    /**
+     * Returns the live generation for this workspace, or starts a new one.
+     * `created` tells the caller whether per-generation state such as the
+     * network policy still needs to be applied.
+     */
+    openRuntimeSession(location: BwrapSessionLocation & {
+        readonly leaseRoot: string;
+    }): Promise<{
+        readonly session: BwrapSession;
+        readonly created: boolean;
+    }>;
+    /** Drops a deleted workspace's generation so the next open starts fresh. */
+    forgetRuntimeSession(workspaceDir: string): void;
+}
+export declare function createBwrapRuntime(input: {
+    readonly options: ResolvedBwrapSandboxOptions;
+    /** Injectable process launcher so logic is testable without bwrap. */
+    readonly runner?: ProcessRunner;
+}): BwrapRuntime;
+/** Writes seeds into a session; eve's `$HOME/.agents/skills` lands under the sandbox HOME. */
+export declare function writeSeedFiles(session: BwrapSession, seedFiles: ReadonlyArray<BwrapSeed>): Promise<void>;

package/dist/runtime.js

@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { createBwrapCacheLease, registerActiveCachePath } from "./cache.js";
+import { WORKSPACE_ROOT } from "./paths.js";
+import { createNodeProcessRunner, describeMissingPrereqs, isBwrapAvailable } from "./process.js";
+import { createBwrapSession } from "./session.js";
+const EVE_MODEL_SKILL_ROOT = "$HOME/.agents/skills";
+export function createBwrapRuntime(input) {
+    const { options } = input;
+    const runner = input.runner ?? createNodeProcessRunner();
+    const generations = new Map();
+    // Probe only when running against the real bwrap; injected runners skip it.
+    const shouldProbe = input.runner === undefined;
+    let probed = false;
+    function openSession(location, generationId, onStopped) {
+        return createBwrapSession({
+            id: location.id,
+            workspaceDir: location.workspaceDir,
+            cacheRoots: location.cacheRoots,
+            runner,
+            options,
+            tags: location.tags,
+            generationId,
+            onStopped,
+        });
+    }
+    return {
+        assertBwrapAvailable() {
+            if (!shouldProbe || probed)
+                return;
+            const missing = describeMissingPrereqs({
+                bwrapPresent: isBwrapAvailable(options.bwrapPath),
+                workspaceMountpointPresent: existsSync(WORKSPACE_ROOT),
+                bwrapPath: options.bwrapPath,
+            });
+            if (missing)
+                throw new Error(missing);
+            probed = true;
+        },
+        openTemplateSession(location) {
+            return openSession(location);
+        },
+        async openRuntimeSession(location) {
+            const current = generations.get(location.workspaceDir);
+            if (current && current.lifecycleState() !== "stopped") {
+                return { session: current, created: false };
+            }
+            const releaseActive = registerActiveCachePath(location.workspaceDir);
+            const activeLease = await createBwrapCacheLease({
+                cacheRoot: location.leaseRoot,
+                sessionId: basename(location.workspaceDir),
+            });
+            let session;
+            try {
+                session = openSession(location, activeLease.lease.generationId, async () => {
+                    releaseActive();
+                    await activeLease.release();
+                });
+            }
+            catch (error) {
+                releaseActive();
+                await activeLease.release();
+                throw error;
+            }
+            generations.set(location.workspaceDir, session);
+            return { session, created: true };
+        },
+        forgetRuntimeSession(workspaceDir) {
+            generations.delete(workspaceDir);
+        },
+    };
+}
+function resolveSeedPath(seedPath) {
+    if (seedPath === EVE_MODEL_SKILL_ROOT || seedPath.startsWith(`${EVE_MODEL_SKILL_ROOT}/`)) {
+        return `${WORKSPACE_ROOT}/.agents/skills${seedPath.slice(EVE_MODEL_SKILL_ROOT.length)}`;
+    }
+    return seedPath;
+}
+/** Writes seeds into a session; eve's `$HOME/.agents/skills` lands under the sandbox HOME. */
+export async function writeSeedFiles(session, seedFiles) {
+    for (const seed of seedFiles) {
+        const seedPath = resolveSeedPath(seed.path);
+        if (typeof seed.content === "string") {
+            await session.writeTextFile({ path: seedPath, content: seed.content });
+        }
+        else {
+            await session.writeBinaryFile({ path: seedPath, content: seed.content });
+        }
+    }
+}

package/dist/session.d.ts

@@ -1,10 +1,15 @@
-import type { SandboxSession } from "eve/sandbox";
+import type { SandboxNetworkPolicy, SandboxSession } from "eve/sandbox";
 import type { ResolvedBwrapSandboxOptions } from "./options.js";
 import type { ProcessRunner } from "./process.js";
 export interface CreateBwrapSessionInput {
     readonly id: string;
     readonly workspaceDir: string;
-    readonly appRoot: string;
+    /**
+     * Host directories holding templates and session workspaces. Every one is
+     * masked with an empty tmpfs so a sandboxed command can never read another
+     * session's workspace or a template it was not cloned from.
+     */
+    readonly cacheRoots: readonly string[];
     readonly runner: ProcessRunner;
     readonly options: ResolvedBwrapSandboxOptions;
     readonly generationId?: string;
@@ -17,6 +22,13 @@ export interface CreateBwrapSessionInput {
  * session tracks the processes it spawned and can terminate them on demand.
  */
 export type BwrapSession = SandboxSession & {
+    /**
+     * Stable identifier of the durable session this handle wraps. eve 0.64
+     * dropped `id` from `SandboxSession`, but every earlier line requires it.
+     */
+    readonly id: string;
+    /** Coarse egress switch; always present here, optional on eve 0.64's `SandboxSession`. */
+    setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
     /** Kills every process this session spawned that has not yet exited. Idempotent. */
     killAll(): Promise<void>;
     /** Internal compute-generation state used to coordinate repeated handles. */

package/dist/session.js

@@ -6,7 +6,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createWriteStream } from "node:fs";
 import { buildBwrapExecArgs, DEFAULT_SANDBOX_PATH } from "./args.js";
-import { isWithinWorkspaceReal, resolveBwrapCacheRoot, resolveWorkspacePath, toHostPath, WORKSPACE_ROOT, } from "./paths.js";
+import { isWithinWorkspaceReal, resolveWorkspacePath, toHostPath, WORKSPACE_ROOT, } from "./paths.js";
 function isMissingFileError(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -62,7 +62,7 @@ function createRunAbortSignal(callerSignal, timeoutMs, outputSignal) {
     };
 }
 export function createBwrapSession(input) {
-    const { id, workspaceDir, appRoot, runner, options } = input;
+    const { id, workspaceDir, cacheRoots, runner, options } = input;
     const generationId = input.generationId ?? randomUUID();
     const tags = input.tags ?? {};
     let networkPolicy = options.networkPolicy;
@@ -205,10 +205,7 @@ export function createBwrapSession(input) {
             ...options.env,
             ...spawnOptions.env,
         };
-        const hidePaths = [
-            resolveBwrapCacheRoot(appRoot, options.cacheDir),
-            ...options.hidePaths,
-        ].filter((path) => existsSync(path));
+        const hidePaths = [...new Set([...cacheRoots, ...options.hidePaths])].filter((path) => existsSync(path));
         const argv = buildBwrapExecArgs({
             bwrapPath: options.bwrapPath,
             workspaceDir,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evelandhq/sandbox-bwrap",
-  "version": "0.3.0",
-  "description": "bubblewrap SandboxBackend for eve agents — real exec sandboxing without Docker or KVM",
+  "version": "0.4.0",
+  "description": "bubblewrap sandbox for eve agents — real exec sandboxing without Docker or KVM",
   "keywords": [
     "agent",
     "bubblewrap",
@@ -25,6 +25,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "import": "./dist/provider.js",
+      "default": "./dist/provider.js"
     }
   },
   "scripts": {
@@ -40,8 +45,8 @@
   "devDependencies": {
     "@types/node": "^26.0.1",
     "ai": "^7.0.44",
-    "eve": "0.47.2",
-    "eve-floor": "npm:eve@0.27.13",
+    "eve": "0.64.1",
+    "eve-floor": "npm:eve@0.62.0",
     "oxfmt": "0.58.0",
     "oxlint": "1.73.0",
     "tsx": "^4.22.4",
@@ -49,7 +54,7 @@
     "vitest": "^4.1.9"
   },
   "peerDependencies": {
-    "eve": ">=0.27.0 <1.0.0"
+    "eve": ">=0.62.0 <1.0.0"
   },
   "engines": {
     "node": ">=24.0.0"