@evelandhq/sandbox-bwrap 0.4.1 → 0.5.0

package/README.md

@@ -120,8 +120,11 @@ directory — it is durable state. Cleanup closes that compute generation to new
 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. The provider's
-`onSessionStop()` and `onRuntimeShutdown()` do the same, and its `resume()` shares the live
-generation the same way.
+`onSandboxStop()` and `onRuntimeShutdown()` do the same, and its `resume()` shares the live
+generation the same way. eve 0.75 renamed the handle hooks from `onSessionStop()` and
+`onSessionDelete()` to `onSandboxStop()` and `onSandboxDelete()` and calls only the new names,
+while eve 0.64 through 0.74 call only the old ones; the handle carries both pairs, each pair
+the same function, so one installed copy serves every eve in the peer range.
 
 ### Options
 
@@ -163,8 +166,12 @@ The provider (eve 0.64 and later):
 - **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.
+- **onSandboxDelete** (`onSessionDelete` before eve 0.75): kills the session's processes
+  and removes its workspace and metadata; the template survives.
+- **onSessionEnd** (eve 0.75 and later, once a durable session has completed, expired or
+  failed): releases the session's workspace and metadata from the persisted state alone,
+  stopping the live generation if this process holds one, without resuming the sandbox. It
+  is idempotent, so eve may retry it, and a workspace that is already gone stays gone.
 
 The backend (eve 0.62 and 0.63):
 

package/dist/index.d.ts

@@ -3,7 +3,7 @@ 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, type MutableNetworkSandboxSession, } from "./provider-definition.js";
+export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, type BwrapPreparedArtifact, type BwrapSandboxEnvironmentOptions, type BwrapSandboxOpenOptions, type BwrapSandboxProviderDefinition, type BwrapSessionState, type CreateBwrapSandboxProviderDefinitionInput, type BwrapProviderHandle, type BwrapSandboxDeleteOptions, type MutableNetworkSandboxSession, } 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";

package/dist/provider-definition.d.ts

@@ -1,5 +1,5 @@
 import type { SandboxNetworkPolicy, SandboxSession } from "eve/sandbox";
-import type { SandboxProviderDefinition } from "eve/sandbox/provider";
+import type { SandboxProviderDefinition, SandboxProviderHandle } from "eve/sandbox/provider";
 import { type BwrapDirectoryCopier } from "./cache.js";
 import type { BwrapNetworkPolicy, BwrapSandboxCreateOptions } from "./options.js";
 import type { ProcessRunner } from "./process.js";
@@ -18,6 +18,19 @@ export declare const BWRAP_PROVIDER_STATE_PROTOCOL_VERSION = 1;
 export type MutableNetworkSandboxSession = SandboxSession & {
     setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
 };
+/**
+ * The handle this provider hands eve. eve 0.75 renamed the handle's lifecycle
+ * hooks from `onSessionStop`/`onSessionDelete` to `onSandboxStop`/`onSandboxDelete`
+ * and calls only the new names, while 0.64 through 0.74 call only the old ones.
+ * One installed copy of this package serves every eve in the peer range, so the
+ * handle answers to both names, each pair being the same function.
+ */
+export type BwrapProviderHandle = SandboxProviderHandle<MutableNetworkSandboxSession> & {
+    onSessionStop(): Promise<void>;
+    onSessionDelete(options?: BwrapSandboxDeleteOptions): Promise<void>;
+};
+/** What eve passes when it deletes a sandbox: at most an abort signal. */
+export type BwrapSandboxDeleteOptions = Parameters<SandboxProviderHandle<MutableNetworkSandboxSession>["onSandboxDelete"]>[0];
 /** Options for `BwrapSandbox.environment(...)`. */
 export type BwrapSandboxEnvironmentOptions = Omit<BwrapSandboxCreateOptions, "templateRevision"> & {
     /**

package/dist/provider-definition.js

@@ -52,31 +52,38 @@ export function createBwrapSandboxProviderDefinition(input = {}) {
                     leaseRoot: roots.sessionRoot,
                 });
                 await applyNetworkPolicy(session, created);
+                // The processes are the compute and the workspace directory is the
+                // durable session: stopping kills the processes and keeps the files.
+                const stop = async () => {
+                    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.
+                const remove = async (deleteOptions) => {
+                    deleteOptions?.abortSignal?.throwIfAborted();
+                    await session.killAll();
+                    runtime.forgetRuntimeSession(sessionPath);
+                    await removeSessionWorkspace(roots.sessionRoot, sessionPath);
+                };
                 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();
-                    },
+                    onSandboxStop: stop,
+                    onSessionStop: stop,
                     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),
-                        });
-                    },
+                    onSandboxDelete: remove,
+                    onSessionDelete: remove,
                 };
             }
+            async function removeSessionWorkspace(sessionRoot, sessionPath) {
+                await rm(sessionPath, { force: true, recursive: true });
+                await removeCacheMetadata({
+                    cacheRoot: sessionRoot,
+                    kind: "session",
+                    id: basename(sessionPath),
+                });
+            }
             return {
                 async prepare(ctx) {
                     const templateKey = JSON.stringify({
@@ -176,6 +183,18 @@ export function createBwrapSandboxProviderDefinition(input = {}) {
                             await session.setNetworkPolicy(state.networkPolicy);
                     });
                 },
+                // eve 0.75 releases a durable session's sandbox once the session has
+                // completed, expired or failed, from persisted state alone. Only the
+                // workspace is touched, never the template, and nothing is resumed to
+                // do it: a live generation in this process is stopped, a workspace that
+                // is already gone is left gone, so the step may retry.
+                async onSessionEnd(ctx, _preparedArtifact, sessionState) {
+                    const state = requireSessionState(sessionState);
+                    const roots = cacheRoots(ctx.storagePath);
+                    const sessionPath = sessionPathIn(roots.sessionRoot, state.sessionKey);
+                    await runtime.closeRuntimeSession(sessionPath);
+                    await removeSessionWorkspace(roots.sessionRoot, sessionPath);
+                },
             };
         },
     };

package/dist/provider.d.ts

@@ -1,4 +1,4 @@
-export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, type BwrapPreparedArtifact, type BwrapSandboxEnvironmentOptions, type BwrapSandboxOpenOptions, type BwrapSandboxProviderDefinition, type BwrapSessionState, type CreateBwrapSandboxProviderDefinitionInput, type MutableNetworkSandboxSession, } from "./provider-definition.js";
+export { BWRAP_PROVIDER_STATE_PROTOCOL_VERSION, createBwrapSandboxProviderDefinition, type BwrapPreparedArtifact, type BwrapSandboxEnvironmentOptions, type BwrapSandboxOpenOptions, type BwrapSandboxProviderDefinition, type BwrapSessionState, type CreateBwrapSandboxProviderDefinitionInput, type BwrapProviderHandle, type BwrapSandboxDeleteOptions, type MutableNetworkSandboxSession, } from "./provider-definition.js";
 export { isBwrapAvailable } from "./process.js";
 /**
  * The bubblewrap sandbox provider for eve 0.64 and later.

package/dist/runtime.d.ts

@@ -35,6 +35,12 @@ export interface BwrapRuntime {
     }>;
     /** Drops a deleted workspace's generation so the next open starts fresh. */
     forgetRuntimeSession(workspaceDir: string): void;
+    /**
+     * Stops the live generation over this workspace, if there is one, and drops
+     * it. Nothing is started for a workspace that has no generation, so this is
+     * safe to call for a session whose sandbox was never resumed in this process.
+     */
+    closeRuntimeSession(workspaceDir: string): Promise<void>;
 }
 export declare function createBwrapRuntime(input: {
     readonly options: ResolvedBwrapSandboxOptions;

package/dist/runtime.js

@@ -68,6 +68,11 @@ export function createBwrapRuntime(input) {
         forgetRuntimeSession(workspaceDir) {
             generations.delete(workspaceDir);
         },
+        async closeRuntimeSession(workspaceDir) {
+            const current = generations.get(workspaceDir);
+            generations.delete(workspaceDir);
+            await current?.killAll();
+        },
     };
 }
 function resolveSeedPath(seedPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evelandhq/sandbox-bwrap",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "bubblewrap sandbox for eve agents — real exec sandboxing without Docker or KVM",
   "keywords": [
     "agent",
@@ -45,7 +45,7 @@
   "devDependencies": {
     "@types/node": "^26.0.1",
     "ai": "^7.0.44",
-    "eve": "0.72.1",
+    "eve": "0.75.1",
     "eve-floor": "npm:eve@0.62.0",
     "oxfmt": "0.58.0",
     "oxlint": "1.73.0",