@evelandhq/sandbox-bwrap 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Eveland
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,232 @@
+# @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
+Linux sandbox — actual binaries, isolated filesystem, coarse network control — without
+requiring a Docker daemon or KVM.
+
+## Why
+
+eve's built-in backend chain is Vercel → Docker → microsandbox → just-bash. On a
+self-hosted Linux box without a Docker daemon or KVM (for example an eveland systemd
+deployment host), that chain bottoms out at `just-bash`: a pure-JS interpreter with a
+virtual filesystem that cannot run real binaries. This backend fills that gap with
+bubblewrap, which needs nothing but the `bwrap` binary and unprivileged user
+namespaces.
+
+## Usage
+
+**Deployed on eveland:** you do nothing. 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
+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
+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
+the eveland build pipeline, so it falls back to eve's default backend chain (usually
+`just-bash`, or Docker where available). See eveland's `docs/deploy/linux.md` for what the
+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:
+
+```ts
+// agent/sandbox.ts
+import { defineSandbox, defaultBackend } from "eve/sandbox";
+import { bwrap, isBwrapAvailable } from "@evelandhq/sandbox-bwrap";
+
+export default defineSandbox({
+  // bwrap on the Linux deploy host; eve's default chain everywhere else (dev laptops).
+  backend: () => (isBwrapAvailable() ? bwrap() : defaultBackend()),
+});
+```
+
+### eve version requirement
+
+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:
+`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.
+
+### 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`.                                                                                                                                                             |
+
+## 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
+  `<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.
+- **create** (runtime): clones the template into `<cacheDir>/sessions/<hash>` on first
+  use. The directory IS the durable session state: it persists across reconnects and
+  process restarts.
+- **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`.
+- **File I/O** (`readTextFile`, `writeFile`, …): host-side operations on the session
+  directory; no subprocess. Writes outside `/workspace` are refused.
+
+## Disk usage and cache management
+
+Session and template directories persist indefinitely under
+`<cacheDir>/{sessions,templates}` across process restarts and reconnects, enabling fast
+reattach when a session resumes. Each session key gets a directory that is reused for
+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
+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
+directory, precisely so that redeploying a project does not touch it.
+
+Reclaiming space today requires manual intervention: identify which sessions are known dead and delete their corresponding directories under the cache root. Automatic cache pruning (e.g., based on age or LRU) is a known gap and a planned follow-up.
+
+## Security boundary
+
+- The host process environment is **never** forwarded: every invocation uses
+  `--clearenv` and rebuilds the environment from `PATH`, `HOME=/workspace`, `LANG`,
+  plus your configured `env`. Deployment secrets in the agent's `process.env` stay
+  out of sandboxed code.
+- For code executed inside the sandbox (`run`/`spawn`), the cache root (all
+  other sessions and templates of the app) is hidden behind a tmpfs, so
+  sandboxed code cannot read sibling session state.
+- The host-side read methods (`readFile`, `readBinaryFile`, `readTextFile`)
+  are deliberately **not** containment-checked: eve's contract requires
+  absolute paths to pass through to the host filesystem unchanged, so these
+  calls can read anything the agent process itself can read — including a
+  sibling session's files or a template directory — not just paths inside
+  `/workspace`. Only the write and remove calls (`writeFile`, `writeTextFile`,
+  `writeBinaryFile`, `removePath`) are confined to the workspace, via the
+  realpath-aware check described below. In other words, the tmpfs above is a
+  boundary against a _sandboxed process_, not a boundary between sessions of
+  the same agent — all of an app's sessions and templates share one trust
+  domain on the host.
+- The rest of the host filesystem is _visible read-only_ to sandboxed code, and the
+  sandbox shares the host kernel. This is protection against mistakes and prompt
+  injection — not multi-tenant isolation. If untrusted tenants or code that routinely
+  handles customer credentials must run here, move to VM-level isolation
+  (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.
+- 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
+  the real target still lands inside the real session directory, closing the escape
+  where sandboxed code plants a symlink inside `/workspace` pointing outside it and a
+  later host-side write follows it out. A race between that check and the filesystem
+  call it guards remains theoretically possible — Node exposes no
+  `RESOLVE_BENEATH`/`O_NOFOLLOW`-atomic primitive to close it — so treat this as a
+  containment check against planted symlinks, not an atomic guarantee.
+- Symlink resolution cannot see inode aliasing. On the kernel this backend has been
+  tested against (Ubuntu 24.04, aarch64), creating a hard link from inside the
+  sandbox to a file outside `/workspace` (`ln <host file> /workspace/x`) was
+  **refused** — the kernel rejected the hard link across the two bind mounts. The
+  integration contract test prints this as a non-assertive probe
+  (`HARDLINK PROBE: refused …` or `succeeded …`) rather than an assertion, because
+  the outcome depends on kernel/filesystem behavior this package does not control.
+  Do not treat hard-link rejection as a guarantee the backend enforces — verify it on
+  your own kernel if it matters to your threat model.
+
+## Requirements
+
+Eveland's generated local Docker image installs `bubblewrap` and `bash`, creates
+`/workspace`, and starts the outer Agent container with its default capability set
+dropped, `SYS_ADMIN` and `NET_ADMIN` added for bwrap namespaces, `no-new-privileges`,
+and `seccomp=unconfined`. This is a local-development boundary; the supported Linux
+production topology uses the unprivileged systemd path below.
+
+- Linux with unprivileged user namespaces available to the calling process. Ubuntu's
+  packaged bubblewrap (0.9.0-1ubuntu0.1 on 24.04) ships **no** AppArmor profile. Since
+  Ubuntu sets `kernel.apparmor_restrict_unprivileged_userns=1` by default, an
+  _unconfined non-root_ process calling `bwrap` fails with
+  `bwrap: setting up uid map: Permission denied` unless the host loads an AppArmor
+  profile that grants `bwrap` the `userns` permission. Root is unaffected by this
+  sysctl, but nothing here runs as root: eveland's systemd runtime runs both this
+  backend (as the deployment user) and its own build sandbox (as a separate,
+  unprivileged build user) as unconfined non-root userns creators, so both need the
+  same AppArmor grant. Save this as `/etc/apparmor.d/bwrap`:
+
+  ```
+  abi <abi/4.0>,
+  include <tunables/global>
+
+  profile bwrap /usr/bin/bwrap flags=(unconfined) {
+    userns,
+
+    # Site-specific additions and overrides. See local/README for details.
+    include if exists <local/bwrap>
+  }
+  ```
+
+  then load it with `apparmor_parser -r -W /etc/apparmor.d/bwrap` (safe to re-run; it
+  replaces an already-loaded profile). A distro whose bubblewrap package ships its own
+  profile, or a host with the sysctl disabled, needs none of this.
+
+- `/workspace` must pre-exist on the host as an empty directory. `bwrap` binds each
+  session directory onto `/workspace` inside the sandbox but cannot create that mount
+  destination itself, because the host root is bind-mounted read-only first
+  (`bwrap: Can't mkdir /workspace: Read-only file system`). If it is missing, the
+  backend fails fast with an actionable error message before invoking `bwrap` (see
+  `describeMissingPrereqs` in `src/process.ts`).
+- `bash` and (for agents that need it) `node` on the host PATH — the sandbox reuses
+  the host rootfs read-only.
+- Works under systemd hardening (`NoNewPrivileges=yes`, `ProtectSystem=strict`):
+  apt's `bwrap` is not setuid, so it needs no privilege escalation to run — but it
+  still needs the AppArmor profile above to create a user namespace as an
+  unprivileged user.
+
+## Testing
+
+- `pnpm test` — unit tests, run anywhere, including macOS (process execution is
+  injectable; no bwrap and no Linux needed). This is what CI runs on every push, and it
+  includes the eve floor/latest compatibility typechecks.
+- `bash infra/smoke.sh` — the contract test against **real** bwrap, on macOS or Linux.
+  It provisions a Lima VM (`brew install lima`), streams this worktree in, and runs the
+  test as an unprivileged user under the systemd hardening a deployed eve agent actually
+  gets — `NoNewPrivileges=yes`, `ProtectSystem=strict`, `PrivateTmp=yes`. Prints
+  `BWRAP SMOKE OK`. Run this before pushing anything that touches `src/args.ts` or
+  `src/process.ts`: CI's smoke job covers the unprivileged-user case but not the systemd
+  constraints, and argv that looks right is not the same as a kernel that accepts it.
+- `pnpm tsx src/integration/bwrap-backend-smoke.ts` — the same test, run directly. Needs
+  a Linux host that already has the AppArmor profile loaded and `/workspace` created
+  (see [Requirements](#requirements)), and should be run as an unprivileged user: root
+  is exempt from the userns sysctl, so a root-only pass proves nothing about a real
+  deployment.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/args.d.ts

@@ -0,0 +1,15 @@
+/** PATH the sandbox sees; the host rootfs is visible read-only, so the standard dirs apply. */
+export declare const DEFAULT_SANDBOX_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export interface BwrapExecInput {
+    readonly bwrapPath: string;
+    readonly workspaceDir: string;
+    /** Host paths mounted over with an empty tmpfs. Caller filters to existing paths. */
+    readonly hidePaths: readonly string[];
+    readonly shareNetwork: boolean;
+    /** Final merged environment; with --clearenv the sandbox sees exactly these variables. */
+    readonly env: Readonly<Record<string, string>>;
+    /** Sandbox-visible working directory (already /workspace-anchored). */
+    readonly chdir: string;
+    readonly command: string;
+}
+export declare function buildBwrapExecArgs(input: BwrapExecInput): string[];

package/dist/args.js

@@ -0,0 +1,32 @@
+import { WORKSPACE_ROOT } from "./paths.js";
+/** PATH the sandbox sees; the host rootfs is visible read-only, so the standard dirs apply. */
+export const DEFAULT_SANDBOX_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export function buildBwrapExecArgs(input) {
+    const args = [
+        input.bwrapPath,
+        "--ro-bind",
+        "/",
+        "/",
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        "--tmpfs",
+        "/tmp",
+    ];
+    // Hide paths BEFORE re-binding the workspace: bind sources resolve against
+    // the host filesystem, so a later bind punches through an earlier tmpfs.
+    for (const path of input.hidePaths) {
+        args.push("--tmpfs", path);
+    }
+    args.push("--bind", input.workspaceDir, WORKSPACE_ROOT);
+    if (!input.shareNetwork) {
+        args.push("--unshare-net");
+    }
+    args.push("--unshare-pid", "--unshare-ipc", "--unshare-uts", "--die-with-parent", "--clearenv");
+    for (const [key, value] of Object.entries(input.env)) {
+        args.push("--setenv", key, value);
+    }
+    args.push("--chdir", input.chdir, "bash", "-lc", input.command);
+    return args;
+}

package/dist/backend.d.ts

@@ -0,0 +1,14 @@
+import type { SandboxBackend } from "eve/sandbox";
+import type { BwrapSandboxCreateOptions } from "./options.js";
+import type { ProcessRunner } from "./process.js";
+/**
+ * Stable backend name. Participates in eve's template/session cache-key
+ * derivation and persisted reconnect state — never change it.
+ */
+export declare const BWRAP_BACKEND_NAME = "bwrap";
+export interface CreateBwrapSandboxBackendInput {
+    readonly createOptions?: BwrapSandboxCreateOptions;
+    /** Injectable process launcher so backend logic is testable without bwrap. */
+    readonly runner?: ProcessRunner;
+}
+export declare function createBwrapSandboxBackend(input?: CreateBwrapSandboxBackendInput): SandboxBackend;

package/dist/backend.js

@@ -0,0 +1,130 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { SandboxTemplateNotProvisionedError } from "eve/sandbox";
+import { createBwrapOptionsHash, resolveBwrapSandboxOptions } from "./options.js";
+import { resolveSessionPath, resolveTemplatePath, 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";
+/**
+ * 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";
+async function copyDirectoryAtomically(sourcePath, targetPath) {
+    const tmpPath = `${targetPath}.${randomUUID()}.tmp`;
+    await mkdir(dirname(targetPath), { recursive: true });
+    try {
+        await cp(sourcePath, tmpPath, { recursive: true });
+        await rename(tmpPath, targetPath);
+    }
+    catch (error) {
+        await rm(tmpPath, { force: true, recursive: true }).catch(() => { });
+        // A concurrent writer winning the rename race is success, not failure.
+        if (existsSync(targetPath))
+            return;
+        throw error;
+    }
+}
+export function createBwrapSandboxBackend(input = {}) {
+    const options = resolveBwrapSandboxOptions(input.createOptions);
+    const optionsHash = createBwrapOptionsHash(options);
+    const runner = input.runner ?? createNodeProcessRunner();
+    // 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) {
+        return createBwrapSession({ id, workspaceDir, appRoot, runner, options });
+    }
+    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 });
+            }
+        }
+    }
+    return {
+        name: BWRAP_BACKEND_NAME,
+        async prewarm({ templateKey, bootstrap, seedFiles, log, runtimeContext }) {
+            assertBwrapAvailable();
+            const templatePath = resolveTemplatePath(runtimeContext.appRoot, templateKey, optionsHash, options.cacheDir);
+            if (existsSync(templatePath))
+                return { reused: true };
+            log?.(`bwrap: capturing template for ${templateKey}`);
+            const stagingPath = `${templatePath}.staging-${randomUUID()}`;
+            await mkdir(stagingPath, { recursive: true });
+            try {
+                const session = openSession(templateKey, stagingPath, runtimeContext.appRoot);
+                if (bootstrap)
+                    await bootstrap({ use: async () => session });
+                await writeSeedFiles(session, seedFiles);
+                await rename(stagingPath, templatePath);
+            }
+            catch (error) {
+                await rm(stagingPath, { force: true, recursive: true }).catch(() => { });
+                // A concurrent prewarm winning the race is reuse, not failure.
+                if (existsSync(templatePath))
+                    return { reused: true };
+                throw error;
+            }
+            return { reused: false };
+        },
+        async create({ templateKey, sessionKey, runtimeContext }) {
+            assertBwrapAvailable();
+            const sessionPath = resolveSessionPath(runtimeContext.appRoot, sessionKey, options.cacheDir);
+            if (!existsSync(sessionPath)) {
+                if (templateKey === null) {
+                    await mkdir(sessionPath, { recursive: true });
+                }
+                else {
+                    const templatePath = resolveTemplatePath(runtimeContext.appRoot, templateKey, optionsHash, options.cacheDir);
+                    if (!existsSync(templatePath)) {
+                        throw new SandboxTemplateNotProvisionedError({
+                            backendName: BWRAP_BACKEND_NAME,
+                            templateKey,
+                        });
+                    }
+                    await copyDirectoryAtomically(templatePath, sessionPath);
+                }
+            }
+            const session = openSession(sessionKey, sessionPath, runtimeContext.appRoot);
+            return {
+                session,
+                useSessionFn: async () => session,
+                async captureState() {
+                    return { backendName: BWRAP_BACKEND_NAME, metadata: {}, sessionKey };
+                },
+                // 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.
+                async shutdown() {
+                    await session.killAll();
+                },
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+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 { isBwrapAvailable } from "./process.js";
+export type { ProcessRunner, SpawnedProcess } from "./process.js";
+/**
+ * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.
+ *
+ * ```ts
+ * // agent/sandbox.ts
+ * import { defineSandbox, defaultBackend } from "eve/sandbox";
+ * import { bwrap, isBwrapAvailable } from "@evelandhq/sandbox-bwrap";
+ *
+ * export default defineSandbox({
+ *   backend: () => (isBwrapAvailable() ? bwrap() : defaultBackend()),
+ * });
+ * ```
+ */
+export declare function bwrap(options?: BwrapSandboxCreateOptions): SandboxBackend;

package/dist/index.js

@@ -0,0 +1,19 @@
+import { createBwrapSandboxBackend } from "./backend.js";
+export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, } from "./backend.js";
+export { isBwrapAvailable } from "./process.js";
+/**
+ * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.
+ *
+ * ```ts
+ * // agent/sandbox.ts
+ * import { defineSandbox, defaultBackend } from "eve/sandbox";
+ * import { bwrap, isBwrapAvailable } from "@evelandhq/sandbox-bwrap";
+ *
+ * export default defineSandbox({
+ *   backend: () => (isBwrapAvailable() ? bwrap() : defaultBackend()),
+ * });
+ * ```
+ */
+export function bwrap(options) {
+    return createBwrapSandboxBackend({ createOptions: options });
+}

package/dist/options.d.ts

@@ -0,0 +1,42 @@
+/** Coarse egress control, matching what eve's Docker backend supports. */
+export type BwrapNetworkPolicy = "allow-all" | "deny-all";
+/** Options accepted by `bwrap(opts)`. */
+export interface BwrapSandboxCreateOptions {
+    /** Environment variables set for every command the backend runs. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Initial network policy for sandboxed commands. Defaults to `"allow-all"`. */
+    readonly networkPolicy?: BwrapNetworkPolicy;
+    /** Extra host paths hidden from the sandbox (each mounted over with an empty tmpfs). */
+    readonly hidePaths?: readonly string[];
+    /** bwrap executable path. Defaults to `"bwrap"` resolved via PATH. */
+    readonly bwrapPath?: string;
+    /**
+     * Absolute directory holding templates and durable session workspaces.
+     * Defaults to `<appRoot>/.eve/sandbox-cache/bwrap`. Pin it outside the
+     * release directory so a redeploy does not discard durable session state
+     * (eve keys session sandboxes per durable session, not per deployment).
+     */
+    readonly cacheDir?: string;
+    /**
+     * Immutable release identity used to refresh workspace templates after a
+     * deploy. It deliberately affects templates only; durable session paths
+     * remain keyed solely by Eve's session key.
+     */
+    readonly templateRevision?: string;
+}
+/** Fully-defaulted options consumed by the backend implementation. */
+export interface ResolvedBwrapSandboxOptions {
+    readonly env: Readonly<Record<string, string>>;
+    readonly networkPolicy: BwrapNetworkPolicy;
+    readonly hidePaths: readonly string[];
+    readonly bwrapPath: string;
+    readonly cacheDir: string | null;
+    readonly templateRevision: string | null;
+}
+export declare function resolveBwrapSandboxOptions(options?: BwrapSandboxCreateOptions): ResolvedBwrapSandboxOptions;
+/**
+ * Hash of the resolved options. Participates in template path derivation so
+ * templates captured under different options never mix (parity with the
+ * Docker backend's options hash).
+ */
+export declare function createBwrapOptionsHash(options: ResolvedBwrapSandboxOptions): string;

package/dist/options.js

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+export function resolveBwrapSandboxOptions(options = {}) {
+    return {
+        env: options.env ?? {},
+        networkPolicy: options.networkPolicy ?? "allow-all",
+        hidePaths: options.hidePaths ?? [],
+        bwrapPath: options.bwrapPath ?? "bwrap",
+        cacheDir: options.cacheDir ?? null,
+        templateRevision: options.templateRevision ?? null,
+    };
+}
+/**
+ * Hash of the resolved options. Participates in template path derivation so
+ * templates captured under different options never mix (parity with the
+ * Docker backend's options hash).
+ */
+export function createBwrapOptionsHash(options) {
+    const canonical = JSON.stringify({
+        bwrapPath: options.bwrapPath,
+        cacheDir: options.cacheDir,
+        env: Object.fromEntries(Object.entries(options.env).sort(([a], [b]) => (a < b ? -1 : 1))),
+        hidePaths: [...options.hidePaths],
+        networkPolicy: options.networkPolicy,
+        templateRevision: options.templateRevision,
+    });
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}

package/dist/paths.d.ts

@@ -0,0 +1,31 @@
+/** Sandbox-visible workspace root; parity with eve's built-in local backends. */
+export declare const WORKSPACE_ROOT = "/workspace";
+/**
+ * Templates and durable session workspaces. `cacheDir` pins the location
+ * outside the release directory; without it the cache follows eve's local
+ * convention under the app root.
+ */
+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;
+/** Anchors a sandbox-relative path to /workspace; absolute paths pass through. */
+export declare function resolveWorkspacePath(path: string): string;
+/**
+ * Translates a sandbox-visible path to the host path backing it: /workspace
+ * maps to the session directory, anything else is the same path on the host.
+ */
+export declare function toHostPath(path: string, workspaceDir: string): string;
+/** True when hostPath is workspaceDir or inside it after normalization. */
+export declare function isWithinWorkspace(hostPath: string, workspaceDir: string): boolean;
+/**
+ * Symlink-aware containment: resolves the deepest existing ancestor of
+ * hostPath (following symlinks) and re-checks that the real target stays
+ * inside the real workspace directory. Not-yet-existing trailing components
+ * cannot be symlinks, so they are appended lexically. Returns false when a
+ * symlink in the chain is dangling (a write through it would create the
+ * file at the symlink's target). Note: this closes the planted-symlink
+ * escape; a race between this check and the following fs operation remains
+ * theoretically possible (Node exposes no RESOLVE_BENEATH), which is an
+ * accepted residual risk documented in the README.
+ */
+export declare function isWithinWorkspaceReal(hostPath: string, workspaceDir: string): boolean;

package/dist/paths.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { lstatSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+/** Sandbox-visible workspace root; parity with eve's built-in local backends. */
+export const WORKSPACE_ROOT = "/workspace";
+/**
+ * Templates and durable session workspaces. `cacheDir` pins the location
+ * outside the release directory; without it the cache follows eve's local
+ * convention under the app root.
+ */
+export function resolveBwrapCacheRoot(appRoot, cacheDir) {
+    return cacheDir ?? join(appRoot, ".eve", "sandbox-cache", "bwrap");
+}
+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}`);
+}
+export function resolveSessionPath(appRoot, sessionKey, cacheDir) {
+    return join(resolveBwrapCacheRoot(appRoot, cacheDir), "sessions", keyDigest(sessionKey));
+}
+/** Anchors a sandbox-relative path to /workspace; absolute paths pass through. */
+export function resolveWorkspacePath(path) {
+    return path.startsWith("/") ? path : `${WORKSPACE_ROOT}/${path}`;
+}
+/**
+ * Translates a sandbox-visible path to the host path backing it: /workspace
+ * maps to the session directory, anything else is the same path on the host.
+ */
+export function toHostPath(path, workspaceDir) {
+    const resolved = resolveWorkspacePath(path);
+    if (resolved === WORKSPACE_ROOT)
+        return workspaceDir;
+    if (resolved.startsWith(`${WORKSPACE_ROOT}/`)) {
+        return join(workspaceDir, resolved.slice(WORKSPACE_ROOT.length + 1));
+    }
+    return resolved;
+}
+/** True when hostPath is workspaceDir or inside it after normalization. */
+export function isWithinWorkspace(hostPath, workspaceDir) {
+    const rel = relative(workspaceDir, hostPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function lexists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Symlink-aware containment: resolves the deepest existing ancestor of
+ * hostPath (following symlinks) and re-checks that the real target stays
+ * inside the real workspace directory. Not-yet-existing trailing components
+ * cannot be symlinks, so they are appended lexically. Returns false when a
+ * symlink in the chain is dangling (a write through it would create the
+ * file at the symlink's target). Note: this closes the planted-symlink
+ * escape; a race between this check and the following fs operation remains
+ * theoretically possible (Node exposes no RESOLVE_BENEATH), which is an
+ * accepted residual risk documented in the README.
+ */
+export function isWithinWorkspaceReal(hostPath, workspaceDir) {
+    if (!isWithinWorkspace(hostPath, workspaceDir))
+        return false;
+    let realWorkspace;
+    try {
+        realWorkspace = realpathSync(workspaceDir);
+    }
+    catch {
+        return false;
+    }
+    let probe = hostPath;
+    const missing = [];
+    while (!lexists(probe)) {
+        const parent = dirname(probe);
+        if (parent === probe)
+            return false;
+        missing.push(basename(probe));
+        probe = parent;
+    }
+    let resolvedProbe;
+    try {
+        resolvedProbe = realpathSync(probe);
+    }
+    catch {
+        return false; // dangling symlink in the chain
+    }
+    const finalPath = missing.length === 0 ? resolvedProbe : join(resolvedProbe, ...missing.reverse());
+    return isWithinWorkspace(finalPath, realWorkspace);
+}

package/dist/process.d.ts

@@ -0,0 +1,24 @@
+/** Mirrors the AI SDK SandboxProcess surface so sessions can return it directly. */
+export interface SpawnedProcess {
+    readonly pid?: number;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    wait(): Promise<{
+        exitCode: number;
+    }>;
+    kill(): Promise<void>;
+}
+/** Injectable process launcher so backend logic is unit-testable without bwrap. */
+export interface ProcessRunner {
+    spawn(argv: readonly string[], options?: {
+        readonly abortSignal?: AbortSignal;
+    }): SpawnedProcess;
+}
+export declare function isBwrapAvailable(bwrapPath?: string): boolean;
+/** Explains missing host prerequisites, or null when the host is ready. */
+export declare function describeMissingPrereqs(probes: {
+    readonly bwrapPresent: boolean;
+    readonly workspaceMountpointPresent: boolean;
+    readonly bwrapPath: string;
+}): string | null;
+export declare function createNodeProcessRunner(): ProcessRunner;

package/dist/process.js

@@ -0,0 +1,84 @@
+import { spawn, spawnSync } from "node:child_process";
+import { Readable } from "node:stream";
+import { WORKSPACE_ROOT } from "./paths.js";
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGKILL: 137, SIGTERM: 143 };
+export function isBwrapAvailable(bwrapPath = "bwrap") {
+    return spawnSync(bwrapPath, ["--version"], { stdio: "ignore" }).status === 0;
+}
+/** Explains missing host prerequisites, or null when the host is ready. */
+export function describeMissingPrereqs(probes) {
+    const problems = [];
+    if (!probes.bwrapPresent) {
+        problems.push(`bubblewrap is not available (tried "${probes.bwrapPath} --version"). ` +
+            "Install it with your distro package manager (Ubuntu/Debian: apt-get install bubblewrap), " +
+            "or select a different backend outside Linux, e.g. " +
+            "backend: () => (isBwrapAvailable() ? bwrap() : defaultBackend()).");
+    }
+    if (!probes.workspaceMountpointPresent) {
+        problems.push(`${WORKSPACE_ROOT} does not exist on the host. bwrap binds each session directory onto ` +
+            `${WORKSPACE_ROOT} inside the sandbox, but it cannot create that mountpoint itself because the ` +
+            `host root is bind-mounted read-only first. Create it once: sudo install -d -m 0755 ${WORKSPACE_ROOT}`);
+    }
+    return problems.length === 0 ? null : problems.join(" ");
+}
+export function createNodeProcessRunner() {
+    return {
+        spawn(argv, options) {
+            const [command, ...rest] = argv;
+            if (!command) {
+                throw new Error("ProcessRunner.spawn requires a non-empty argv");
+            }
+            // detached: the child leads its own process group, so kill(-pid) reaps
+            // the entire sandboxed tree (bwrap and everything inside it).
+            const child = spawn(command, rest, { detached: true, stdio: ["ignore", "pipe", "pipe"] });
+            const exit = new Promise((resolvePromise, reject) => {
+                child.once("error", reject);
+                child.once("exit", (code, signal) => {
+                    resolvePromise({ exitCode: code ?? (signal ? (SIGNAL_EXIT_CODES[signal] ?? 1) : 1) });
+                });
+            });
+            exit.catch(() => { });
+            const killTree = () => {
+                if (child.pid !== undefined) {
+                    try {
+                        process.kill(-child.pid, "SIGKILL");
+                        return;
+                    }
+                    catch {
+                        // fall through: group already gone or not yet set up
+                    }
+                }
+                child.kill("SIGKILL");
+            };
+            let aborted = false;
+            let abortReason;
+            const signal = options?.abortSignal;
+            if (signal) {
+                const onAbort = () => {
+                    aborted = true;
+                    abortReason = signal.reason;
+                    killTree();
+                };
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            }
+            return {
+                pid: child.pid,
+                stdout: Readable.toWeb(child.stdout),
+                stderr: Readable.toWeb(child.stderr),
+                async wait() {
+                    const result = await exit;
+                    if (aborted)
+                        throw abortReason;
+                    return result;
+                },
+                async kill() {
+                    killTree();
+                    await exit.catch(() => { });
+                },
+            };
+        },
+    };
+}

package/dist/session.d.ts

@@ -0,0 +1,20 @@
+import type { 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;
+    readonly runner: ProcessRunner;
+    readonly options: ResolvedBwrapSandboxOptions;
+}
+/**
+ * A sandbox session plus the lifecycle hook the backend handle needs.
+ * eve's `shutdown()` contract requires that nothing is left running, so the
+ * session tracks the processes it spawned and can terminate them on demand.
+ */
+export type BwrapSession = SandboxSession & {
+    /** Kills every process this session spawned that has not yet exited. Idempotent. */
+    killAll(): Promise<void>;
+};
+export declare function createBwrapSession(input: CreateBwrapSessionInput): BwrapSession;

package/dist/session.js

@@ -0,0 +1,183 @@
+import { createReadStream, existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+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";
+function isMissingFileError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === "ENOENT");
+}
+async function collectStream(stream) {
+    const chunks = [];
+    const reader = stream.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function decodeText(bytes, encoding) {
+    if (encoding === "utf-8" || encoding === "utf8") {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    return bytes.toString(encoding);
+}
+function sliceLines(text, startLine, endLine) {
+    if (startLine === undefined && endLine === undefined)
+        return text;
+    const lines = text.split("\n");
+    return lines.slice((startLine ?? 1) - 1, endLine ?? lines.length).join("\n");
+}
+export function createBwrapSession(input) {
+    const { id, workspaceDir, appRoot, runner, options } = input;
+    let networkPolicy = options.networkPolicy;
+    const host = (path) => toHostPath(path, workspaceDir);
+    function writableHostPath(path, operation) {
+        const hostPath = host(path);
+        if (!isWithinWorkspaceReal(hostPath, workspaceDir)) {
+            throw new Error(`bwrap sandbox: refusing to ${operation} outside ${WORKSPACE_ROOT}: ${path}`);
+        }
+        return hostPath;
+    }
+    const live = new Set();
+    // Wrap wait()/kill() rather than eagerly calling proc.wait() ourselves to
+    // watch for exit: a fire-and-forget wait() started at spawn time races
+    // ahead of the caller (its resolution is not tied to when anyone actually
+    // observes the process), so a process can be silently untracked before
+    // killAll() ever sees it. Tying removal to the caller's own wait()/kill()
+    // call keeps "still tracked" in sync with "still owned by the caller":
+    // run() untracks itself the moment its internal wait() settles, and a
+    // bare spawn() stays tracked (and killable) until its holder collects it.
+    function track(proc) {
+        const wrapped = {
+            pid: proc.pid,
+            stdout: proc.stdout,
+            stderr: proc.stderr,
+            async wait() {
+                try {
+                    return await proc.wait();
+                }
+                finally {
+                    live.delete(wrapped);
+                }
+            },
+            async kill() {
+                try {
+                    await proc.kill();
+                }
+                finally {
+                    live.delete(wrapped);
+                }
+            },
+        };
+        live.add(wrapped);
+        return wrapped;
+    }
+    async function spawnProcess(spawnOptions) {
+        const env = {
+            PATH: DEFAULT_SANDBOX_PATH,
+            HOME: WORKSPACE_ROOT,
+            LANG: "C.UTF-8",
+            ...options.env,
+            ...spawnOptions.env,
+        };
+        const hidePaths = [
+            resolveBwrapCacheRoot(appRoot, options.cacheDir),
+            ...options.hidePaths,
+        ].filter((path) => existsSync(path));
+        const argv = buildBwrapExecArgs({
+            bwrapPath: options.bwrapPath,
+            workspaceDir,
+            hidePaths,
+            shareNetwork: networkPolicy === "allow-all",
+            env,
+            chdir: resolveWorkspacePath(spawnOptions.workingDirectory ?? WORKSPACE_ROOT),
+            command: spawnOptions.command,
+        });
+        return track(runner.spawn(argv, { abortSignal: spawnOptions.abortSignal }));
+    }
+    return {
+        id,
+        resolvePath: resolveWorkspacePath,
+        async killAll() {
+            const pending = [...live];
+            live.clear();
+            await Promise.all(pending.map((proc) => proc.kill().catch(() => undefined)));
+        },
+        async spawn(spawnOptions) {
+            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 };
+        },
+        async setNetworkPolicy(policy) {
+            if (policy !== "allow-all" && policy !== "deny-all") {
+                throw new Error('bwrap backend supports only the "allow-all" and "deny-all" network policies');
+            }
+            networkPolicy = policy;
+        },
+        async readFile({ path }) {
+            const hostPath = host(path);
+            if (!existsSync(hostPath))
+                return null;
+            return Readable.toWeb(createReadStream(hostPath));
+        },
+        async readBinaryFile({ path }) {
+            try {
+                const bytes = await readFile(host(path));
+                return new Uint8Array(bytes);
+            }
+            catch (error) {
+                if (isMissingFileError(error))
+                    return null;
+                throw error;
+            }
+        },
+        async readTextFile({ path, encoding, startLine, endLine }) {
+            try {
+                const bytes = await readFile(host(path));
+                return sliceLines(decodeText(bytes, encoding ?? "utf-8"), startLine, endLine);
+            }
+            catch (error) {
+                if (isMissingFileError(error))
+                    return null;
+                throw error;
+            }
+        },
+        async writeFile({ path, content }) {
+            const hostPath = writableHostPath(path, "write");
+            await mkdir(dirname(hostPath), { recursive: true });
+            await pipeline(Readable.fromWeb(content), createWriteStream(hostPath));
+        },
+        async writeBinaryFile({ path, content }) {
+            const hostPath = writableHostPath(path, "write");
+            await mkdir(dirname(hostPath), { recursive: true });
+            await writeFile(hostPath, content);
+        },
+        async writeTextFile({ path, content, encoding }) {
+            const hostPath = writableHostPath(path, "write");
+            await mkdir(dirname(hostPath), { recursive: true });
+            const enc = encoding === undefined || encoding === "utf-8" ? "utf8" : encoding;
+            await writeFile(hostPath, Buffer.from(content, enc));
+        },
+        async removePath({ path, force, recursive }) {
+            const hostPath = writableHostPath(path, "remove");
+            if (force !== true && !existsSync(hostPath)) {
+                throw new Error(`bwrap sandbox: path does not exist: ${path}`);
+            }
+            await rm(hostPath, { force: force === true, recursive: recursive === true });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@evelandhq/sandbox-bwrap",
+  "version": "0.1.0",
+  "description": "bubblewrap SandboxBackend for eve agents — real exec sandboxing without Docker or KVM",
+  "keywords": [
+    "agent",
+    "bubblewrap",
+    "bwrap",
+    "eve",
+    "sandbox"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evelandhq/sandbox-bwrap.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "ai": "^7.0.44",
+    "eve": "0.30.8",
+    "eve-floor": "npm:eve@0.27.13",
+    "oxfmt": "0.58.0",
+    "oxlint": "1.73.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "peerDependencies": {
+    "eve": ">=0.27.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0"
+}