@evelandhq/sandbox-bwrap 0.1.1 → 0.1.3

package/README.md

@@ -21,11 +21,12 @@ the sandbox module into the release directory at build time — `agent/sandbox.j
 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
 a deployment backend themselves. If a project shipped its own sandbox module, the build
-replaces that definition and reports it in the build log; authored `bootstrap()` and
-`onSession()` behavior is not used. The sibling `agent/sandbox/workspace/**` tree is preserved,
-so Eve still seeds those files into each Session's `/workspace`. Each Eveland Release supplies a
-distinct template revision, so Sessions created against a new Deployment see its updated seeds
-while existing durable Session workspaces remain untouched. The systemd runtime invokes
+wraps that definition and reports it in the build log: Eveland overrides only `backend`, while
+authored `bootstrap()`, `onSession()`, `description`, and `revalidationKey` remain active. The
+sibling `agent/sandbox/workspace/**` tree is preserved, so Eve still seeds those files into each
+Session's `/workspace`. Each Eveland Release supplies a distinct template revision, so Sessions
+created against a new Deployment see its updated seeds while existing durable Session workspaces
+remain untouched. The systemd runtime invokes
 bwrap as its unprivileged deployment user. The local Docker runtime installs bwrap inside the Agent
 image and grants the outer container only the capabilities nested bwrap requires; the
 Agent container still receives no Docker socket. Local `eve dev` is untouched — it never runs
@@ -83,12 +84,19 @@ next callback reopens it.
 | `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.                                                                                                                                                                                                  |
+
+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
 
-- **prewarm** (build time): runs the authored `bootstrap` inside bwrap against a
-  staging directory, resolves Eve's `$HOME/.agents/skills/**` seed paths to
-  `/workspace/.agents/skills/**`, writes seed files, then atomically renames it into
+- **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
+  renaming the result into
   `<cacheDir>/templates/<hash>` (`<cacheDir>` defaults to
   `<appRoot>/.eve/sandbox-cache/bwrap` when the `cacheDir` option is not set). Idempotent
   per template key + options hash; `templateRevision` participates in that hash.
@@ -98,6 +106,9 @@ next callback reopens it.
 - **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.
 
@@ -145,9 +156,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.d.ts

@@ -1,5 +1,5 @@
 import type { SandboxBackend } from "eve/sandbox";
-import type { BwrapSandboxCreateOptions } from "./options.js";
+import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
 import type { ProcessRunner } from "./process.js";
 /**
  * Stable backend name. Participates in eve's template/session cache-key
@@ -11,4 +11,4 @@ export interface CreateBwrapSandboxBackendInput {
     /** Injectable process launcher so backend logic is testable without bwrap. */
     readonly runner?: ProcessRunner;
 }
-export declare function createBwrapSandboxBackend(input?: CreateBwrapSandboxBackendInput): SandboxBackend;
+export declare function createBwrapSandboxBackend(input?: CreateBwrapSandboxBackendInput): SandboxBackend<BwrapSandboxUseOptions, BwrapSandboxUseOptions>;

package/dist/backend.js

@@ -67,6 +67,12 @@ export function createBwrapSandboxBackend(input = {}) {
             }
         }
     }
+    async function useSession(session, useOptions) {
+        if (useOptions?.networkPolicy !== undefined) {
+            await session.setNetworkPolicy(useOptions.networkPolicy);
+        }
+        return session;
+    }
     return {
         name: BWRAP_BACKEND_NAME,
         async prewarm({ templateKey, bootstrap, seedFiles, log, runtimeContext }) {
@@ -79,9 +85,10 @@ export function createBwrapSandboxBackend(input = {}) {
             await mkdir(stagingPath, { recursive: true });
             try {
                 const session = openSession(templateKey, stagingPath, runtimeContext.appRoot);
-                if (bootstrap)
-                    await bootstrap({ use: async () => session });
                 await writeSeedFiles(session, seedFiles);
+                if (bootstrap) {
+                    await bootstrap({ use: async (useOptions) => await useSession(session, useOptions) });
+                }
                 await rename(stagingPath, templatePath);
             }
             catch (error) {
@@ -114,7 +121,7 @@ export function createBwrapSandboxBackend(input = {}) {
             const session = openSession(sessionKey, sessionPath, runtimeContext.appRoot);
             return {
                 session,
-                useSessionFn: async () => session,
+                useSessionFn: async (useOptions) => await useSession(session, useOptions),
                 async captureState() {
                     return { backendName: BWRAP_BACKEND_NAME, metadata: {}, sessionKey };
                 },

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import type { SandboxBackend } from "eve/sandbox";
-import type { BwrapSandboxCreateOptions } from "./options.js";
+import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, type CreateBwrapSandboxBackendInput, } from "./backend.js";
-export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions } from "./options.js";
+export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions, BwrapSandboxUseOptions, } from "./options.js";
+export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 export type { ProcessRunner, SpawnedProcess } from "./process.js";
 /**
@@ -17,4 +18,4 @@ export type { ProcessRunner, SpawnedProcess } from "./process.js";
  * });
  * ```
  */
-export declare function bwrap(options?: BwrapSandboxCreateOptions): SandboxBackend;
+export declare function bwrap(options?: BwrapSandboxCreateOptions): SandboxBackend<BwrapSandboxUseOptions, BwrapSandboxUseOptions>;

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,12 @@
 /** Coarse egress control, matching what eve's Docker backend supports. */
 export type BwrapNetworkPolicy = "allow-all" | "deny-all";
+/** Options lifecycle hooks can apply when they open a template or live Session. */
+export interface BwrapSandboxUseOptions {
+    /** Network policy used by subsequent commands in this lifecycle callback. */
+    readonly networkPolicy?: BwrapNetworkPolicy;
+}
+/** 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 +30,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 +45,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.1",
+  "version": "0.1.3",
   "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.33.2",
+    "eve": "0.37.0",
     "eve-floor": "npm:eve@0.27.13",
     "oxfmt": "0.58.0",
     "oxlint": "1.73.0",