@evelandhq/sandbox-bwrap 0.1.2 → 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
@@ -85,11 +86,17 @@ next callback reopens it.
 | `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.

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,7 @@
 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";
@@ -18,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/options.d.ts

@@ -1,5 +1,10 @@
 /** 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)`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evelandhq/sandbox-bwrap",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "bubblewrap SandboxBackend for eve agents — real exec sandboxing without Docker or KVM",
   "keywords": [
     "agent",