@evelandhq/sandbox-bwrap 0.1.0 → 0.1.2

package/README.md

@@ -54,18 +54,24 @@ This package requires `eve` `>=0.27.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 has been stable across the whole
-range. Rather than re-declaring the window, CI keeps the claim honest from both ends:
+interface (`SandboxBackend` from `eve/sandbox`) that changes rarely. 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.
-
-The backend implements the required `shutdown()` contract by killing every process the
-session has spawned that has not yet exited, honoring eve's requirement that nothing may
-be left running once the handle is shut down. The session's workspace directory is not
-touched by `shutdown()` — it is durable state and remains available when the session
-reattaches.
+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()`.
+
+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
+which requires that nothing be left running afterwards, and `stop()`, which authored code
+triggers mid-run through `ctx.getSandbox().stop()`. Backends with provider-side compute
+distinguish the two — a container to pause, a VM to snapshot; bwrap has no such resource,
+because the processes are the compute. Neither method touches the session's workspace
+directory — it is durable state, and remains available when the session reattaches or the
+next callback reopens it.
 
 ### Options
 
@@ -77,6 +83,7 @@ reattaches.
 | `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.                                                                                                                                                                                                  |
 
 ## How it works
 
@@ -92,6 +99,9 @@ reattaches.
 - **run/spawn**: every command is one transient bwrap invocation —
   read-only host rootfs, the session directory bound read-write at `/workspace`,
   tmpfs `/tmp`, PID/IPC/UTS namespaces unshared, `--die-with-parent`.
+  `run()` also applies `runTimeoutMs` and kills the entire detached process group
+  when the deadline or caller AbortSignal fires; `spawn()` remains unbounded until
+  its holder calls `kill()`, the Session is stopped, or the backend shuts down.
 - **File I/O** (`readTextFile`, `writeFile`, …): host-side operations on the session
   directory; no subprocess. Writes outside `/workspace` are refused.
 
@@ -103,8 +113,8 @@ reattach when a session resumes. Each session key gets a directory that is reuse
 the lifetime of the session; each template is cached per (template key, options hash), with
 an optional release revision in the options hash,
 and reused across sessions. This backend intentionally does not prune either — its
-`shutdown()` method only kills the session's live processes and leaves the workspace on
-disk, so reattach is instant and stateless from the agent's perspective. On a long-lived
+`stop()` and `shutdown()` methods only kill the session's live processes and leave the
+workspace on disk, so reattach is instant and stateless from the agent's perspective. On a long-lived
 host, this means the cache will grow with the number of durable sessions and unique
 templates, consuming disk space indefinitely. On eveland deployments this cache lives at
 `EVELAND_SANDBOX_CACHE_DIR` (one subdirectory per project), outside every release
@@ -139,9 +149,10 @@ Reclaiming space today requires manual intervention: identify which sessions are
   (Firecracker/microsandbox) instead of hardening this backend further.
   Under Eveland's local Docker runtime, "host filesystem" here means the outer Agent
   container's filesystem, not the Docker host; no host root or Docker socket is mounted.
-- Resource limits are inherited from whatever cgroup the agent runs in (on eveland's
-  systemd runtime: the deployment unit's `MemoryMax`/`CPUQuota` cover sandbox
-  children too). The backend sets no per-command limits itself.
+- CPU, memory, and PID limits are inherited from whatever cgroup the agent runs in
+  (on eveland, the deployment's Docker container or systemd unit covers sandbox
+  children too). The backend adds only the `run()` wall-clock deadline; it does not
+  create a per-command cgroup or impose resource quotas on `spawn()`.
 - Host-side write/remove calls (`writeFile`, `writeTextFile`, `writeBinaryFile`,
   `removePath`) verify containment with a realpath-aware check
   (`isWithinWorkspaceReal`): they resolve symlinks along the path and re-check that

package/dist/backend.js

@@ -118,6 +118,16 @@ export function createBwrapSandboxBackend(input = {}) {
                 async captureState() {
                     return { backendName: BWRAP_BACKEND_NAME, metadata: {}, sessionKey };
                 },
+                // eve (>=0.32) calls this when authored code runs
+                // `ctx.getSandbox().stop()` mid-run: stop the compute, keep the durable
+                // session. Backends with provider-side compute distinguish this from
+                // shutdown() — a container to pause, a VM to snapshot. bwrap has no such
+                // resource: the processes are the compute and the workspace directory is
+                // the session, so stopping is killing the processes, and the next
+                // create() reopens the same workspace.
+                async stop() {
+                    await session.killAll();
+                },
                 // eve calls this when the server is shutting down: nothing may be left
                 // running afterwards. The workspace directory IS the durable state, so
                 // it stays on disk and the session reattaches on the next start.

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { SandboxBackend } from "eve/sandbox";
 import type { BwrapSandboxCreateOptions } from "./options.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, type CreateBwrapSandboxBackendInput, } from "./backend.js";
 export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions } from "./options.js";
+export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 export type { ProcessRunner, SpawnedProcess } from "./process.js";
 /**

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createBwrapSandboxBackend } from "./backend.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, } from "./backend.js";
+export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 /**
  * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.

package/dist/options.d.ts

@@ -1,5 +1,7 @@
 /** Coarse egress control, matching what eve's Docker backend supports. */
 export type BwrapNetworkPolicy = "allow-all" | "deny-all";
+/** Commands executed through `run()` are bounded by default; use `spawn()` for daemons. */
+export declare const DEFAULT_RUN_TIMEOUT_MS = 600000;
 /** Options accepted by `bwrap(opts)`. */
 export interface BwrapSandboxCreateOptions {
     /** Environment variables set for every command the backend runs. */
@@ -23,6 +25,12 @@ export interface BwrapSandboxCreateOptions {
      * remain keyed solely by Eve's session key.
      */
     readonly templateRevision?: string;
+    /**
+     * Hard wall-clock limit for one `run()` command. Defaults to 10 minutes.
+     * Set to `null` to disable. This does not apply to the deliberately
+     * long-running `spawn()` API.
+     */
+    readonly runTimeoutMs?: number | null;
 }
 /** Fully-defaulted options consumed by the backend implementation. */
 export interface ResolvedBwrapSandboxOptions {
@@ -32,6 +40,7 @@ export interface ResolvedBwrapSandboxOptions {
     readonly bwrapPath: string;
     readonly cacheDir: string | null;
     readonly templateRevision: string | null;
+    readonly runTimeoutMs: number | null;
 }
 export declare function resolveBwrapSandboxOptions(options?: BwrapSandboxCreateOptions): ResolvedBwrapSandboxOptions;
 /**

package/dist/options.js

@@ -1,4 +1,15 @@
 import { createHash } from "node:crypto";
+/** Commands executed through `run()` are bounded by default; use `spawn()` for daemons. */
+export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+function resolveRunTimeoutMs(value) {
+    if (value === null)
+        return null;
+    const resolved = value ?? DEFAULT_RUN_TIMEOUT_MS;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new Error("bwrap sandbox: runTimeoutMs must be a positive safe integer or null");
+    }
+    return resolved;
+}
 export function resolveBwrapSandboxOptions(options = {}) {
     return {
         env: options.env ?? {},
@@ -7,6 +18,7 @@ export function resolveBwrapSandboxOptions(options = {}) {
         bwrapPath: options.bwrapPath ?? "bwrap",
         cacheDir: options.cacheDir ?? null,
         templateRevision: options.templateRevision ?? null,
+        runTimeoutMs: resolveRunTimeoutMs(options.runTimeoutMs),
     };
 }
 /**
@@ -21,6 +33,7 @@ export function createBwrapOptionsHash(options) {
         env: Object.fromEntries(Object.entries(options.env).sort(([a], [b]) => (a < b ? -1 : 1))),
         hidePaths: [...options.hidePaths],
         networkPolicy: options.networkPolicy,
+        runTimeoutMs: options.runTimeoutMs,
         templateRevision: options.templateRevision,
     });
     return createHash("sha256").update(canonical).digest("hex").slice(0, 16);

package/dist/session.js

@@ -34,6 +34,19 @@ function sliceLines(text, startLine, endLine) {
     const lines = text.split("\n");
     return lines.slice((startLine ?? 1) - 1, endLine ?? lines.length).join("\n");
 }
+function createRunAbortSignal(callerSignal, timeoutMs) {
+    if (timeoutMs === null)
+        return { signal: callerSignal, clear() { } };
+    const timeout = new AbortController();
+    const timer = setTimeout(() => {
+        timeout.abort(new Error(`bwrap sandbox: run timed out after ${timeoutMs} ms`));
+    }, timeoutMs);
+    timer.unref?.();
+    return {
+        signal: callerSignal ? AbortSignal.any([callerSignal, timeout.signal]) : timeout.signal,
+        clear: () => clearTimeout(timer),
+    };
+}
 export function createBwrapSession(input) {
     const { id, workspaceDir, appRoot, runner, options } = input;
     let networkPolicy = options.networkPolicy;
@@ -114,13 +127,19 @@ export function createBwrapSession(input) {
             return await spawnProcess(spawnOptions);
         },
         async run(runOptions) {
-            const proc = await spawnProcess(runOptions);
-            const [stdout, stderr] = await Promise.all([
-                collectStream(proc.stdout),
-                collectStream(proc.stderr),
-            ]);
-            const { exitCode } = await proc.wait();
-            return { exitCode, stdout, stderr };
+            const runAbort = createRunAbortSignal(runOptions.abortSignal, options.runTimeoutMs);
+            try {
+                const proc = await spawnProcess({ ...runOptions, abortSignal: runAbort.signal });
+                const [stdout, stderr, { exitCode }] = await Promise.all([
+                    collectStream(proc.stdout),
+                    collectStream(proc.stderr),
+                    proc.wait(),
+                ]);
+                return { exitCode, stdout, stderr };
+            }
+            finally {
+                runAbort.clear();
+            }
         },
         async setNetworkPolicy(policy) {
             if (policy !== "allow-all" && policy !== "deny-all") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evelandhq/sandbox-bwrap",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "bubblewrap SandboxBackend for eve agents — real exec sandboxing without Docker or KVM",
   "keywords": [
     "agent",
@@ -40,7 +40,7 @@
   "devDependencies": {
     "@types/node": "^26.0.1",
     "ai": "^7.0.44",
-    "eve": "0.30.8",
+    "eve": "0.37.0",
     "eve-floor": "npm:eve@0.27.13",
     "oxfmt": "0.58.0",
     "oxlint": "1.73.0",