@capybara-hq/plugin-sandbox-e2b 0.0.0-stage → 0.1.0-rc.0

package/.capybara-plugin/plugin.json

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": 1,
+  "name": "sandbox-e2b",
+  "version": "0.1.0-rc.0",
+  "publisher": "Capybara",
+  "description": "Conversation sandboxes (sandbox@1) as E2B sandboxes (E2B cloud or self-hosted), with pause / resume and E2B egress controls",
+  "homepage": "https://github.com/capybara-hq/plugins/tree/main/plugins/sandbox-e2b#readme",
+  "extension": {
+    "entry": "./dist/index.mjs",
+    "manifest": {
+      "name": "sandbox-e2b",
+      "version": "0.1.0-rc.0",
+      "sdk": "^0.1.0-rc.0",
+      "provides": [
+        "sandbox@1"
+      ],
+      "requires": [],
+      "optional": [],
+      "permissions": {},
+      "config": {
+        "deployment": [
+          {
+            "path": "allowOpenEgress",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "apiKey",
+            "secret": true,
+            "hot": false
+          },
+          {
+            "path": "apiUrl",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "domain",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "domainAllowlist",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "template",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "timeoutSeconds",
+            "secret": false,
+            "hot": false
+          }
+        ],
+        "org": []
+      }
+    }
+  }
+}

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 [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,2 @@
+Capybara
+Copyright 2026 Meta-1 (Tianjin Yuanyilian Technology Co., Ltd.)

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @capybara-hq/plugin-sandbox-e2b
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The E2B implementation of the conversation sandbox (`sandbox@1`): one E2B sandbox per conversation (E2B cloud or self-hosted E2B), using E2B's pause for hibernation
+and connect for resume. It is an either-or choice with `@capybara-hq/plugin-sandbox-docker` (`sandbox@1` is a single-select capability), and uses the same image.
+
+## Deployment config
+
+| Key | Default | Description |
+|---|---|---|
+| `apiKey` | (required, secret) | E2B API key (`e2b_…`) |
+| `template` | (required) | Template name or id, built from `plugins/sandbox-docker/image/Dockerfile` (see below) |
+| `apiUrl` | `https://api.<domain>` | Control plane API address; for self-hosted E2B, use your own address |
+| `domain` | `e2b.app` | Sandbox domain: the envd address is `https://49983-<sandbox id>.<domain>`; when the API returns the sandbox's own `domain`, the returned one wins |
+| `timeoutSeconds` | `3600` | Sandbox timeout (60–86400 seconds); when it expires E2B **auto-pauses** (does not delete), see "Lifecycle" |
+| `domainAllowlist` | `true` | Whether E2B supports a per-domain egress allowlist; set `false` for self-hosted versions that do not, and `allowlist` degrades to `none` with a warning |
+| `allowOpenEgress` | `false` | Allow `sandbox.limits.egress = "open"`; when false, `create` fails immediately on open (an English error) |
+
+```bash
+export CAPYBARA_EXTENSIONS='["@capybara-hq/plugin-sandbox-e2b"]'
+export CAPYBARA_EXTENSION_CONFIG='{"sandbox-e2b":{"apiKey":"e2b_…","template":"capybara-sandbox"}}'
+```
+
+The deployment config schema is strict: extra keys are errors. The kernel config `sandbox.image` has no effect on this plugin (the image is decided by the template).
+
+## Template (the same image as the Docker plugin)
+
+The template is built from `plugins/sandbox-docker/image/Dockerfile` (E2B's Template SDK parses the Dockerfile's
+FROM / RUN / COPY / ADD / WORKDIR / USER / ENV / ARG / CMD / ENTRYPOINT). From the repository root:
+
+```bash
+export E2B_API_KEY=e2b_…           # for self-hosted, also set E2B_DOMAIN / E2B_API_URL
+mkdir -p /tmp/e2b-build && cd /tmp/e2b-build && npm init -y >/dev/null && npm i e2b@2.58.0
+cat > build.mjs <<'EOF'
+import { readFileSync } from "node:fs";
+import { defaultBuildLogger, Template } from "e2b";
+const dockerfile = readFileSync(process.argv[2], "utf8");
+await Template.build(Template().fromDockerfile(dockerfile), "capybara-sandbox", {
+  cpuCount: 1,        // matches the kernel's sandbox.cpu default
+  memoryMB: 2048,     // matches the kernel's sandbox.memoryMb default
+  onBuildLogs: defaultBuildLogger(),
+});
+EOF
+node build.mjs <repo path>/plugins/sandbox-docker/image/Dockerfile
+```
+
+Then set `template` to `capybara-sandbox`. Image conventions (the plugin depends on them): the user `sandbox` (uid 1000), with HOME and the working directory at
+`/workspace`; `/skills` owned by root (0755); `/opt/capybara` owned by root and 0700; `runuser` / `setsid` (util-linux),
+`pkill` / `pgrep` (procps) and GNU coreutils installed. Rebuild the template after changing the Dockerfile.
+
+## Lifecycle
+
+| Operation | E2B call |
+|---|---|
+| `create` | First lists by the metadata `capybara-sandbox-name=<name>` (`GET /v2/sandboxes?metadata=…&state=running,paused`, paginated) and deletes any old instance of the same name (the kernel may have exited before recording the handle), then `POST /v2/sandboxes` (`templateID`, `metadata`, `timeout`, `autoPause: true`, `secure: true`, egress settings); the handle id is E2B's sandbox id |
+| `resume` | `POST /v2/sandboxes/{id}/connect` (a paused one is resumed, and a running one gets its timeout pushed back); 404 → `gone` |
+| `suspend` | `POST /sandboxes/{id}/pause` (files and memory are both kept: background processes and `/tmp` are still there after resume; the Docker plugin's hibernation instead ends processes and clears `/tmp`); a missing one (404) or an already paused one (409) also counts as success |
+| `killAll` | After connect (a paused one is resumed first, and the processes in memory come back with it), runs a script as the sandbox user that kills every command started through `exec` that is still running (SIGKILL by process group and session); called when the kernel takes over from a crashed previous lock holder |
+| Concurrent use (`concurrentExec`, `killTagged`) | Declares `concurrentExec: true`: envd runs each `process.Start` independently, so parallel sub-agents of one conversation run commands and file operations in its sandbox at the same time. Each exec's control file carries the holder's tag (`/tmp/.capybara-exec-<tag>-<uuid>`, tags checked against `SANDBOX_TAG_RE`); `killTagged` runs a script as the sandbox user that kills only the commands of the given tags. Concurrent `connect` calls are idempotent (a running sandbox only gets its timeout extended); a 409 answered while another call's resume is in flight is retried briefly (5 × 500 ms; to be confirmed on real E2B, see `test/live`). Uploads use UUID names in the staging directory. When a kill cannot run, the reboot fallback (pause + cold `connect`) also ends live siblings' commands (a last resort) |
+| `destroy` / `destroyByName` | `DELETE /sandboxes/{id}` (a missing one also counts as success); by name it first lists by metadata |
+| `exec` / file operations | First connect (a paused one is resumed, which is the contract's "auto-start"; the envd access token is fetched. **If no token can be obtained it does not connect and sends no request without a token; it reports `SandboxGoneError` (`resume` returns `gone`), and the kernel rebuilds a sandbox with a token on that basis; a sandbox created before `secure: true` was added never has a token**; the timeout is pushed to at least "command timeout + 120 seconds", and not beyond 24 hours), then calls envd; a connect that returns an E2B-format 404 (`{code: 404, …}`) → `SandboxGoneError`; a bare 404 (a proxy, a misconfigured `apiUrl`), 401 / 5xx / network errors → ordinary errors. pause / delete also treat only an E2B-format 404 as "does not exist" |
+
+- **Timeout**: an E2B sandbox is handled when its timeout (`timeoutSeconds`) expires; this plugin sets `autoPause: true` when creating a sandbox, so on expiry it is **paused** instead of deleted,
+  and files are not lost even when the kernel has no chance to `suspend` (for example the whole kernel is down). Every use pushes it back through connect (it only extends, never shortens).
+  Idle hibernation and expiry destruction are handled by the kernel's maintenance tasks. E2B's continuous run limit (24 hours on Pro, 1 hour on Hobby) is recounted after pause / resume.
+- **Hobby plan**: the `timeout` of connect / create is at most 1 hour, so the deployment config `timeoutSeconds` must be ≤ 3600, and a single command can actually run at most
+  about 1 hour minus 2 minutes; however large the `sandbox_bash` `timeoutSeconds` is (capped by `sandbox.limits.maxCommandSeconds`, default 7200), it will be interrupted by the pause when the sandbox expires.
+  On Hobby, set `sandbox.limits.maxCommandSeconds` to below 3480.
+- E2B keeps a paused sandbox indefinitely until it is deleted (the kernel deletes by `destroyAfterInactiveDays`).
+
+## exec and files
+
+- **exec**: envd's `process.Process/Start` (a server stream of the Connect protocol), run as the `sandbox` user:
+  `setsid -w /bin/sh -c <wrapper> … timeout -s KILL <timeout + 5 seconds> /bin/bash -c <command>`; the wrapper first writes the session id to
+  `/tmp/.capybara-exec-<uuid>.pid`. The `timeout` inside the sandbox is the backstop: when a kernel replica crashes the timer on the plugin side is gone, disconnecting envd's stream does not end
+  the process, and pause then resume would bring the process back; on expiry it kills the process group the command is in.
+  On timeout or abort: a kill-processes script runs as the sandbox user, SIGKILLing all processes the command spawned by process group and session (the same as the Docker plugin),
+  then envd's `SendSignal` by pid serves as a backstop (it only ends the session's first process); it returns only after the kill finishes, and disconnects after a 3-second grace period (disconnecting itself does not
+  end the processes in the sandbox).
+  **Last resort: reboot the sandbox.** When the kill-processes script did not finish (could not start, for example process count exhausted, timeout, or unreachable), or the output stream still has not ended 3 seconds after the kill
+  (a process escaped the session and still holds the output): first pause, then `POST /v2/sandboxes/{id}/connect` `{timeout, memory: false}`
+  (that is, the SDK `e2b@2.58.0`'s `Sandbox.connect(id, { onResume: "reboot" })`) to cold-start from the disk state: all processes in memory end,
+  files such as `/workspace` are kept, writes not flushed before the pause may be lost, and whether things in `/tmp` survive depends on whether they are on disk. A warn log is written;
+  the call returns as usual with `timedOut: true` or the abort result. The SDK notes: this requires the control plane to support connect's `memory` field (E2B cloud; self-hosted must be a
+  `e2b-dev/runtime` after 2026-08-20), and an older control plane will **ignore the field** and restore the memory snapshot (processes still there), and an
+  environment without "restore only the filesystem" enabled will reject the request; in both cases the backstop is ineffective (only logged).
+  When a command is ended by a signal we did not send (envd's end event `exited: false`, such as OOM): by shell convention it returns `128 + signal number`
+  (when Go's signal name is recognized), and when it is not recognized it returns `exitCode: null, timedOut: false` (the kernel hints "the command did not finish, the result may be incomplete").
+  A timeout resolves `timedOut: true, exitCode: null`; an abort after start resolves `exitCode: null, timedOut: false` (with the output collected so far);
+  an already aborted call rejects immediately. stdout + stderr together are truncated by `maxOutputBytes` and set `truncated`; when truncating it backs up to a full
+  UTF-8 character boundary. envd sends a keepalive event every 50 seconds, so a command with no output for a long time is not disconnected by an intermediate proxy.
+- **readFile / stat**: small `head -c` / `stat` scripts run in the sandbox as the sandbox user (permissions and symlinks are resolved as the sandbox user). A missing file → null,
+  and readFile on a directory also returns null.
+- **writeFile**: envd's upload endpoint opens the target as root and follows symlinks, so writing to the target directly could bypass permissions with something like `/workspace/l -> /etc`.
+  So the plugin only transfers the bytes to a root-only staging directory `/opt/capybara/upload/<uuid>` (`/opt/capybara` owned by root, 0700), then runs as root
+  `runuser -u sandbox -- sh -c 'mkdir -p …; cat > target' < staging file`: root only opens the staging file, while creating the directory and writing the target are both resolved as the
+  sandbox user; the staging file is deleted whether it succeeds or not (when aborted it may remain in the root-only directory and is removed with the sandbox).
+- **/skills is read-only**: `/skills` is owned by root (0755) and the sandbox user can only read it. `writeFile("/skills/…")` writes directly as root (`umask 022`,
+  file mode 0644); the sandbox user cannot place symlinks in `/skills`, so root's writes cannot be redirected elsewhere.
+
+## Egress (`limits.egress`)
+
+E2B's egress control ([docs](https://docs.e2b.dev/sandbox/internet-access), verified 2026-10-21):
+
+| `egress` | Setting when creating the sandbox |
+|---|---|
+| `none` | `allow_internet_access: false` (equivalent to `denyOut: ["0.0.0.0/0"]`) |
+| `allowlist` | `network: { allowOut: allowHosts, denyOut: ["0.0.0.0/0"] }`; when `allowHosts` is empty it is the same as `none` |
+| `open` | `allow_internet_access: true`; `allowOpenEgress` must be turned on explicitly |
+
+Limitations of `allowlist` (decided by E2B's implementation, written here for assessment):
+
+- Per-domain filtering applies only to **HTTP on port 80 (by the Host header) and TLS on port 443 (by SNI)**; other ports are filtered only by IP / CIDR,
+  and with only domains in the allowlist they are always blocked. UDP (QUIC / HTTP3) does not support per-domain filtering.
+- When a domain allowlist is used, E2B automatically allows DNS to `8.8.8.8` (port 53), and the DNS queries themselves can be used to exfiltrate small amounts of data.
+- **E2B looks only at the Host header / SNI, and the docs do not say it checks the destination IP**: a sandbox can connect to ports 80 / 443 of any IP and write the Host / SNI as a domain on the allowlist
+  (such as `curl --resolve pypi.org:443:<any IP> https://pypi.org`), and so **may reach any address outside the allowlist** (including the intranet and cloud
+  metadata addresses, depending on whether E2B's own network allows them). The Docker plugin's egress proxy resolves the domain and checks every destination IP; the E2B version cannot do this.
+- Other sites on the same CDN / object storage may also be allowed along with it (the E2B docs say this too).
+- **For self-hosted E2B, network isolation is the operator's responsibility**: intranet services and cloud metadata addresses (169.254.169.254 and so on) that the sandbox node can reach must be blocked at E2B's node /
+  network layer; this plugin cannot do it for you.
+- If egress that "checks the destination IP after resolving" is wanted later, E2B's `network.egressProxy` can be used (SOCKS5, see SDK 2.58 `buildEgressProxyBody`):
+  it sends all sandbox egress to our own proxy (for example the same checks as the Docker plugin's egress proxy); this plugin does not use it yet.
+- A rejected TCP connection may look "connected" inside the sandbox; you only know it was rejected from the application layer (HTTP status, TLS handshake).
+- `*.example.com` matches subdomains (same as the Docker plugin, not including `example.com` itself).
+- For self-hosted E2B that does not support per-domain filtering, set `domainAllowlist: false`: `allowlist` degrades to `none` with a warning (it never silently opens up).
+- **The allowlist cannot stop data sent to allowlisted hosts** (the same as the Docker version): `git push` to github.com and publishing to npm / PyPI are within the allowlist,
+  and attachments in a conversation and data the agent has read can leak this way. Orgs that handle sensitive data should set `sandboxToolPolicy` to
+  `ask` in the org settings, and / or set the sandbox network `sandboxEgress` to `none` (org-level egress, Ruling M19: an org can replace the allowlist or cut the network, and cannot set `open`).
+
+**Limits take effect only at creation**: `sandbox.limits.egress` / `allowHosts` are written into the create-sandbox request, and changing the config affects only sandboxes created afterwards; existing
+sandboxes (including ones resumed after a pause) keep the egress settings from creation until they are destroyed and rebuilt.
+
+**Command time limit**: a single command runs at most `sandbox.limits.maxCommandSeconds`, and no more than the time left in the run it belongs to (`runtime.maxRunSeconds`,
+default 900 seconds, Ruling M20); to run long commands, raise `runtime.maxRunSeconds` to at least `maxCommandSeconds`.
+
+## Resources (`limits.cpu` / `memoryMb` / `diskMb`)
+
+E2B's CPU and memory are fixed **when the template is built** (`cpuCount` / `memoryMB` of `Template.build`) and cannot be specified per sandbox at creation; disk size is decided by
+E2B's plan / template. So for `limits` cpu / memoryMb / diskMb this plugin only validates them and **does not apply them per sandbox**: give the spec you want when
+building the template (the example above matches the kernel defaults of 1 core / 2048 MB), and use different templates for different specs. The sandbox CPU / memory overrides an enterprise admin sets for an org in the admin console
+(deployment setting `sandboxLimitOverrides`) likewise **have no effect on this plugin**: to give some orgs a bigger spec, the only way is to switch to a different deployment
+(or template).
+
+## Client
+
+It does not use the official `e2b` SDK and instead has a minimal hand-written client (`src/e2b-api.ts`, the global `fetch`, no third-party dependencies):
+
+- Every request carries the caller's AbortSignal directly, so abort semantics are controllable (the command stream is disconnected by the plugin itself: kill the process first, then disconnect);
+- The official SDK reads process environment variables such as `E2B_API_KEY` / `E2B_DOMAIN` / `E2B_SANDBOX_URL` / `E2B_DEBUG` and caches a connection pool at module level
+  (the multi-replica discipline does not allow module-level mutable state in a plugin), and it also brings undici, Connect, protobuf and a string of other dependencies;
+- It uses only 6 control plane endpoints and 3 envd endpoints, with the protocol following the SDK `e2b@2.58.0` implementation (listed in the header comment of `src/e2b-api.ts`).
+
+Protocol sources (verified 2026-10-21): `dist/index.mjs` of `e2b@2.58.0`; the E2B docs
+[internet-access](https://docs.e2b.dev/sandbox/internet-access), [persistence](https://docs.e2b.dev/sandbox/persistence),
+[sandbox lifecycle](https://docs.e2b.dev/sandbox), [template quickstart](https://docs.e2b.dev/template/quickstart),
+[template migration (fromDockerfile)](https://docs.e2b.dev/template/migration-v2); the envd source
+[upload.go](https://github.com/e2b-dev/infra/blob/main/packages/envd/internal/api/upload.go).
+
+## Test-only options
+
+The third parameter of `createE2BSandbox(config, { log }, testOptions)` can be passed only by code that calls it directly; the plugin config cannot set it:
+
+- `envdUrl`: the envd address is changed to this (routed by the `E2b-Sandbox-Id` request header), instead of being assembled from the sandbox id and domain.
+
+## Tests
+
+- `test/sandbox-e2b.test.ts`: against `startFakeE2B` from `@capybara-hq/testing` (control plane API + envd, Connect stream protocol,
+  commands really run in a local temp directory), covering each method, error mapping (404 → gone, 401 / 5xx → ordinary errors), abort, kill on timeout,
+  file reads and writes and the way `/skills` is written, egress mapping, and the reboot backstop when killing fails / the output stream does not end (the fake server's `memory: false` connect ends all processes).
+- `test/live`: real E2B, run only when `CAPYBARA_TEST_E2B_API_KEY` and `CAPYBARA_TEST_E2B_TEMPLATE` are set (optionally
+  `CAPYBARA_TEST_E2B_API_URL` / `CAPYBARA_TEST_E2B_DOMAIN`), otherwise skipped: the sandbox user, files, `/skills` read-only (including a write through a symlink being
+  rejected), the egress allowlist, output truncation, kill on timeout (including nohup child processes), abort, long periods with no output, a child process that escaped the session triggering the reboot backstop, same-name replacement,
+  pause / resume, gone after destroy. The file header lists the "assumptions that can only be confirmed on real E2B"; check them one by one on the first run.

package/dist/index.mjs

@@ -0,0 +1,795 @@
+import { createRequire as __capybaraCreateRequire } from "node:module";
+import { fileURLToPath as __capybaraFileURLToPath } from "node:url";
+import { dirname as __capybaraPathDirname } from "node:path";
+const require = __capybaraCreateRequire(import.meta.url);
+const __capybara_filename = __capybaraFileURLToPath(import.meta.url);
+const __capybara_dirname = __capybaraPathDirname(__capybara_filename);
+
+// src/index.ts
+import { defineExtension, SANDBOX_EXTENSION_POINT, secret } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+// src/provider.ts
+import { randomUUID } from "node:crypto";
+import {
+  SANDBOX_TAG_RE,
+  SandboxGoneError,
+  validateAllowHost,
+  validateSandboxPath
+} from "@capybara-hq/plugin-sdk";
+
+// src/e2b-api.ts
+var ENVD_PORT = 49983;
+var API_TIMEOUT_MS = 6e4;
+var KEEPALIVE_SECONDS = 50;
+var E2BHttpError = class extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "E2BHttpError";
+  }
+  status;
+  code;
+};
+function isStatus(e, ...status) {
+  return e instanceof E2BHttpError && status.includes(e.status);
+}
+function isE2BNotFound(e) {
+  return e instanceof E2BHttpError && e.status === 404 && e.code === 404;
+}
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+function rethrow(e, signal) {
+  if (signal.aborted) throw abortReason(signal);
+  throw e;
+}
+async function errorOf(res, what) {
+  let message = "";
+  let code;
+  try {
+    const text = await res.text();
+    try {
+      const j = JSON.parse(text);
+      message = typeof j.message === "string" ? j.message : text;
+      if (typeof j.code === "number" || typeof j.code === "string") code = j.code;
+    } catch {
+      message = text;
+    }
+  } catch {
+  }
+  return new E2BHttpError(
+    res.status,
+    `E2B ${what} failed: HTTP ${res.status}${message ? `: ${message.slice(0, 300)}` : ""}`,
+    code
+  );
+}
+function createE2BApi(apiUrl, apiKey) {
+  const base = apiUrl.replace(/\/+$/, "");
+  return {
+    async json(method, path, opts) {
+      opts.signal.throwIfAborted();
+      const url = new URL(base + path);
+      for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== void 0) url.searchParams.set(k, v);
+      }
+      let res;
+      try {
+        res = await fetch(url, {
+          method,
+          headers: {
+            "X-API-KEY": apiKey,
+            ...opts.body !== void 0 && { "content-type": "application/json" }
+          },
+          ...opts.body !== void 0 && { body: JSON.stringify(opts.body) },
+          redirect: "error",
+          signal: AbortSignal.any([opts.signal, AbortSignal.timeout(API_TIMEOUT_MS)])
+        });
+      } catch (e) {
+        rethrow(e, opts.signal);
+      }
+      if (!res.ok) throw await errorOf(res, `${method} ${path}`);
+      const text = await res.text().catch((e) => rethrow(e, opts.signal));
+      return {
+        status: res.status,
+        data: text === "" ? void 0 : JSON.parse(text),
+        headers: res.headers
+      };
+    }
+  };
+}
+var basic = (user) => `Basic ${Buffer.from(`${user}:`).toString("base64")}`;
+function envdHeaders(t, extra = {}) {
+  return {
+    "E2b-Sandbox-Id": t.sandboxId,
+    "E2b-Sandbox-Port": String(ENVD_PORT),
+    "X-Access-Token": t.accessToken,
+    ...extra
+  };
+}
+function envelope(msg) {
+  const json = Buffer.from(JSON.stringify(msg), "utf8");
+  const out = Buffer.alloc(5 + json.byteLength);
+  out.writeUInt8(0, 0);
+  out.writeUInt32BE(json.byteLength, 1);
+  json.copy(out, 5);
+  return out;
+}
+async function envdUpload(t, path, user, data, signal) {
+  const url = new URL(`${t.url}/files`);
+  url.searchParams.set("path", path);
+  url.searchParams.set("username", user);
+  const form = new FormData();
+  form.append("file", new Blob([new Uint8Array(data)]), path.split("/").pop() ?? "file");
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: envdHeaders(t),
+      body: form,
+      redirect: "error",
+      signal
+    });
+  } catch (e) {
+    rethrow(e, signal);
+  }
+  if (!res.ok) throw await errorOf(res, "file upload");
+  await res.body?.cancel().catch(() => void 0);
+}
+async function envdKill(t, pid, signal) {
+  let res;
+  try {
+    res = await fetch(`${t.url}/process.Process/SendSignal`, {
+      method: "POST",
+      headers: envdHeaders(t, {
+        "content-type": "application/json",
+        "Connect-Protocol-Version": "1"
+      }),
+      body: JSON.stringify({ process: { pid }, signal: "SIGNAL_SIGKILL" }),
+      redirect: "error",
+      signal
+    });
+  } catch (e) {
+    rethrow(e, signal);
+  }
+  if (!res.ok) {
+    const e = await errorOf(res, "process signal");
+    if (e.status === 404 && e.code === "not_found") return;
+    throw e;
+  }
+  await res.body?.cancel().catch(() => void 0);
+}
+async function envdStart(t, user, req, onEvent, signal) {
+  let res;
+  try {
+    res = await fetch(`${t.url}/process.Process/Start`, {
+      method: "POST",
+      headers: envdHeaders(t, {
+        "content-type": "application/connect+json",
+        "Connect-Protocol-Version": "1",
+        Authorization: basic(user),
+        "Keepalive-Ping-Interval": String(KEEPALIVE_SECONDS)
+      }),
+      body: envelope({ process: req, stdin: false }),
+      redirect: "error",
+      signal
+    });
+  } catch (e) {
+    rethrow(e, signal);
+  }
+  if (res.status !== 200 || !res.body) throw await errorOf(res, "process start");
+  const reader = res.body.getReader();
+  let buf = Buffer.alloc(0);
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf = buf.byteLength === 0 ? Buffer.from(value) : Buffer.concat([buf, value]);
+      while (buf.byteLength >= 5) {
+        const len = buf.readUInt32BE(1);
+        if (buf.byteLength < 5 + len) break;
+        const flags = buf.readUInt8(0);
+        const msg = JSON.parse(buf.subarray(5, 5 + len).toString("utf8"));
+        buf = buf.subarray(5 + len);
+        if (flags & 2) {
+          if (msg.error) {
+            throw new Error(
+              `E2B process stream failed: ${msg.error.code ?? "unknown"}: ${msg.error.message ?? ""}`
+            );
+          }
+          return;
+        }
+        if (msg.event) onEvent(msg.event);
+      }
+    }
+  } catch (e) {
+    await reader.cancel().catch(() => void 0);
+    rethrow(e, signal);
+  }
+  throw new Error("E2B process stream ended without an end-of-stream message");
+}
+
+// src/provider.ts
+var METADATA_NAME = "capybara-sandbox-name";
+var SANDBOX_USER = "sandbox";
+var ROOT_USER = "root";
+var UPLOAD_DIR = "/opt/capybara/upload";
+var MAX_TIMEOUT_SECONDS = 86400;
+var TIMEOUT_MARGIN_SECONDS = 120;
+var KILL_GRACE_MS = 3e3;
+var STDERR_ROOM = 64 * 1024;
+var FILE_OP_TIMEOUT_MS = 12e4;
+var CONNECT_CONFLICT_RETRIES = 5;
+var CONNECT_CONFLICT_WAIT_MS = 500;
+var LIST_LIMIT = 100;
+var NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,100}$/;
+var ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+var SANDBOX_ID_RE = /^[a-zA-Z0-9-]{1,128}$/;
+var IN_SANDBOX_GRACE_SECONDS = 5;
+var EXEC_WRAPPER = 'c=$1; echo $$ > "$c.pid" 2>/dev/null; if [ -e "$c.kill" ]; then exit 137; fi; timeout -s KILL "$3" /bin/bash -c "$2"; s=$?; rm -f "$c.pid"; exit $s';
+function execArgs(ctl, command, timeoutMs) {
+  const seconds = Math.ceil(timeoutMs / 1e3) + IN_SANDBOX_GRACE_SECONDS;
+  return ["-w", "/bin/sh", "-c", EXEC_WRAPPER, "capybara-exec", ctl, command, String(seconds)];
+}
+var KILL_TREE = 'k() { for t in $(pgrep -P "$1"); do kill -9 -"$t" 2>/dev/null; done; kill -9 -"$1" 2>/dev/null; pkill -9 -s "$1" 2>/dev/null; }; ';
+var KILL_ALL_SCRIPT = `${KILL_TREE}for q in $(pgrep -f -- "capybara-exec /tmp/[.]capybara-exec-"); do k "$q"; kill -9 "$q" 2>/dev/null; done; exit 0`;
+var KILL_TAGGED_SCRIPT = `${KILL_TREE}u='[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'; for t in "$@"; do for q in $(pgrep -f -- "capybara-exec /tmp/[.]capybara-exec-$t-$u( |$)"); do k "$q"; kill -9 "$q" 2>/dev/null; done; done; exit 0`;
+function execControlPath(tag) {
+  if (tag !== void 0 && !SANDBOX_TAG_RE.test(tag)) throw new Error("invalid sandbox tag");
+  return tag === void 0 ? `/tmp/.capybara-exec-${randomUUID()}` : `/tmp/.capybara-exec-${tag}-${randomUUID()}`;
+}
+var KILL_SCRIPT = `${KILL_TREE}c=$1; : > "$c.kill" 2>/dev/null; i=0; while [ ! -s "$c.pid" ] && [ $i -lt 20 ]; do sleep 0.05; i=$((i+1)); done; p=$(cat "$c.pid" 2>/dev/null); if [ -n "$p" ]; then k "$p"; rm -f "$c.kill"; fi; for q in $(pgrep -f -- "capybara-exec $c"); do k "$q"; kill -9 "$q" 2>/dev/null; done; rm -f "$c.pid"; exit 0`;
+var READ_SCRIPT = 'if [ ! -e "$1" ]; then exit 3; fi; if [ -d "$1" ]; then exit 4; fi; exec head -c "$2" -- "$1"';
+var STAT_SCRIPT = 'if [ ! -e "$1" ]; then exit 3; fi; s=$(stat -L -c %s -- "$1" 2>/dev/null) || s=$(($(wc -c < "$1"))); if [ -d "$1" ]; then echo "$s directory"; else echo "$s file"; fi';
+var USER_WRITE_SCRIPT = `s=1; runuser -u ${SANDBOX_USER} -- /bin/sh -c 'set -e; mkdir -p -- "$(dirname -- "$1")"; cat > "$1"' capybara-write "$1" < "$2" && s=0; rm -f -- "$2"; exit $s`;
+var SKILLS_WRITE_SCRIPT = 'umask 022; s=1; mkdir -p -- "$(dirname -- "$1")" && cat -- "$2" > "$1" && chmod 0644 "$1" && s=0; rm -f -- "$2"; exit $s';
+function after(ms, fn) {
+  const t = AbortSignal.timeout(ms);
+  t.addEventListener("abort", fn, { once: true });
+  return { cancel: () => t.removeEventListener("abort", fn) };
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      timer.cancel();
+      reject(signal.reason);
+    };
+    const timer = after(ms, () => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    });
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function checkPath(p) {
+  const errors = validateSandboxPath(p);
+  if (errors.length > 0)
+    throw new Error(`invalid sandbox path ${JSON.stringify(p)}: ${errors.join("; ")}`);
+}
+function createE2BSandbox(cfg, deps, test = {}) {
+  const api = createE2BApi(cfg.apiUrl ?? `https://api.${cfg.domain}`, cfg.apiKey);
+  const enc = encodeURIComponent;
+  const checkId = (id) => {
+    if (!SANDBOX_ID_RE.test(id)) throw new Error(`invalid E2B sandbox id: ${JSON.stringify(id)}`);
+  };
+  const targetOf = (info) => {
+    checkId(info.sandboxID);
+    const domain = info.domain || cfg.domain;
+    if (!HOSTNAME_RE.test(domain)) {
+      throw new Error(
+        `E2B returned an invalid sandbox domain: ${JSON.stringify(domain).slice(0, 100)}`
+      );
+    }
+    if (typeof info.envdAccessToken !== "string" || info.envdAccessToken === "") {
+      throw new SandboxGoneError(
+        `E2B returned no envd access token for sandbox ${info.sandboxID}; refusing to use an unauthenticated sandbox (it will be recreated)`
+      );
+    }
+    return {
+      url: test.envdUrl ?? `https://${ENVD_PORT}-${info.sandboxID}.${domain}`,
+      sandboxId: info.sandboxID,
+      accessToken: info.envdAccessToken
+    };
+  };
+  const attach = async (id, signal, minSeconds = 0) => {
+    signal.throwIfAborted();
+    checkId(id);
+    const timeout = Math.min(MAX_TIMEOUT_SECONDS, Math.max(cfg.timeoutSeconds, minSeconds));
+    for (let i = 0; ; i++) {
+      try {
+        const r = await api.json("POST", `/v2/sandboxes/${enc(id)}/connect`, {
+          body: { timeout },
+          signal
+        });
+        return targetOf({ ...r.data, sandboxID: r.data?.sandboxID ?? id });
+      } catch (e) {
+        if (isE2BNotFound(e)) {
+          throw new SandboxGoneError(`E2B sandbox ${id} no longer exists`, { cause: e });
+        }
+        if (!isStatus(e, 409) || i >= CONNECT_CONFLICT_RETRIES) throw e;
+        await sleep(CONNECT_CONFLICT_WAIT_MS, signal);
+      }
+    }
+  };
+  const destroyByName = async (name, signal) => {
+    signal.throwIfAborted();
+    const ids = [];
+    let nextToken;
+    do {
+      const r = await api.json(
+        "GET",
+        "/v2/sandboxes",
+        {
+          query: {
+            metadata: new URLSearchParams({ [enc(METADATA_NAME)]: enc(name) }).toString(),
+            state: "running,paused",
+            limit: String(LIST_LIMIT),
+            nextToken
+          },
+          signal
+        }
+      );
+      for (const s of r.data ?? []) {
+        if (s.metadata?.[METADATA_NAME] === name) ids.push(s.sandboxID);
+      }
+      nextToken = r.headers.get("x-next-token") || void 0;
+    } while (nextToken);
+    for (const id of ids) await kill(id, signal);
+  };
+  const kill = async (id, signal) => {
+    checkId(id);
+    try {
+      await api.json("DELETE", `/sandboxes/${enc(id)}`, { signal });
+    } catch (e) {
+      if (!isE2BNotFound(e)) throw e;
+    }
+  };
+  async function run(t, o) {
+    o.signal.throwIfAborted();
+    const out = [];
+    const err = [];
+    let used = 0;
+    let truncated = false;
+    let timedOut = false;
+    let aborted = false;
+    let stopping = false;
+    let pid;
+    let exitCode;
+    const collect = (kind, b64) => {
+      const data = Buffer.from(b64, "base64");
+      const room = o.maxOutputBytes - used;
+      if (data.byteLength > room) truncated = true;
+      if (room <= 0) return;
+      const keep = data.byteLength > room ? data.subarray(0, room) : data;
+      used += keep.byteLength;
+      (kind === "out" ? out : err).push(keep);
+    };
+    const conn = new AbortController();
+    let grace;
+    let killing;
+    let wedged = false;
+    const stop = () => {
+      if (stopping) return;
+      stopping = true;
+      const kill2 = o.kill;
+      if (!kill2) {
+        conn.abort();
+        return;
+      }
+      killing = (async () => {
+        const ok = await kill2(pid).catch(() => false);
+        if (!ok) {
+          wedged = true;
+          conn.abort();
+          return;
+        }
+        grace = after(KILL_GRACE_MS, () => {
+          wedged = true;
+          conn.abort();
+        });
+      })();
+    };
+    const timer = o.timeoutMs === void 0 ? void 0 : after(o.timeoutMs, () => {
+      timedOut = true;
+      stop();
+    });
+    const onAbort = () => {
+      aborted = true;
+      stop();
+    };
+    o.signal.addEventListener("abort", onAbort, { once: true });
+    const req = {
+      cmd: o.cmd,
+      args: o.args,
+      ...o.env && { envs: o.env },
+      ...o.cwd !== void 0 && { cwd: o.cwd }
+    };
+    let streamError;
+    try {
+      await envdStart(
+        t,
+        o.user,
+        req,
+        (e) => {
+          if ("start" in e) pid = e.start.pid;
+          else if ("data" in e) {
+            if (e.data.stdout) collect("out", e.data.stdout);
+            if (e.data.stderr) collect("err", e.data.stderr);
+          } else if ("end" in e) exitCode = exitCodeOf(e.end);
+        },
+        conn.signal
+      );
+    } catch (e) {
+      streamError = e;
+    }
+    await killing;
+    grace?.cancel();
+    if (wedged && o.recover) await o.recover().catch(() => void 0);
+    timer?.cancel();
+    o.signal.removeEventListener("abort", onAbort);
+    const result = {
+      stdout: Buffer.concat(out),
+      stderr: Buffer.concat(err),
+      truncated,
+      timedOut,
+      aborted
+    };
+    if (timedOut || aborted) return { ...result, exitCode: null };
+    if (streamError !== void 0) throw streamError;
+    if (exitCode === void 0) throw new Error("E2B process stream ended without an exit status");
+    return { ...result, exitCode };
+  }
+  const killer = (t, ctl) => async (pid) => {
+    const ok = await run(t, {
+      user: SANDBOX_USER,
+      cmd: "/bin/sh",
+      args: ["-c", KILL_SCRIPT, "capybara-kill", ctl],
+      cwd: "/",
+      maxOutputBytes: 4096,
+      timeoutMs: 15e3,
+      signal: AbortSignal.timeout(2e4)
+    }).then(
+      (r) => r.exitCode === 0,
+      () => false
+    );
+    if (pid !== void 0)
+      await envdKill(t, pid, AbortSignal.timeout(15e3)).catch(() => void 0);
+    return ok;
+  };
+  const reboot = async (id) => {
+    deps.log.warn("sandbox-e2b: could not stop a command cleanly; rebooting the sandbox", {
+      sandboxId: id
+    });
+    const signal = AbortSignal.timeout(12e4);
+    try {
+      await api.json("POST", `/sandboxes/${enc(id)}/pause`, { body: {}, signal });
+    } catch (e) {
+      if (!isStatus(e, 409)) throw e;
+    }
+    await api.json("POST", `/v2/sandboxes/${enc(id)}/connect`, {
+      body: { timeout: cfg.timeoutSeconds, memory: false },
+      signal
+    });
+  };
+  const fileOp = async (t, o, signal) => {
+    const r = await run(t, {
+      ...o,
+      cmd: "/bin/sh",
+      cwd: "/",
+      timeoutMs: FILE_OP_TIMEOUT_MS,
+      signal
+    });
+    if (r.aborted) throw abortReason(signal);
+    if (r.timedOut) throw new Error("sandbox file operation timed out");
+    return r;
+  };
+  const stderrOf = (r) => r.stderr.toString("utf8").trim().slice(0, 500);
+  return {
+    // envd runs every process.Start independently; connect on a running sandbox only extends its
+    // timeout, so concurrent auto-starts are idempotent (a 409 from a resume in flight is retried)
+    concurrentExec: true,
+    async create({ name, limits, signal }) {
+      signal.throwIfAborted();
+      if (!NAME_RE.test(name)) throw new Error(`invalid sandbox name: ${name}`);
+      checkLimits(limits);
+      if (limits.egress === "open" && !cfg.allowOpenEgress) {
+        throw new Error(
+          'Sandbox egress "open" (sandbox.limits.egress) is refused: the sandbox-e2b plugin setting allowOpenEgress is false. Set extensionConfig."sandbox-e2b".allowOpenEgress to true (trusted environments only), or set sandbox.limits.egress to "allowlist" or "none".'
+        );
+      }
+      let egress = limits.egress;
+      if (egress === "allowlist" && !cfg.domainAllowlist) {
+        deps.log.warn(
+          "sandbox-e2b: domain allowlists are disabled for this deployment (domainAllowlist is false); egress allowlist degraded to none",
+          { name }
+        );
+        egress = "none";
+      }
+      await destroyByName(name, signal);
+      const network = egress === "allowlist" && limits.allowHosts.length > 0 ? { network: { allowOut: [...limits.allowHosts], denyOut: ["0.0.0.0/0"] } } : { allow_internet_access: egress === "open" };
+      const r = await api.json("POST", "/v2/sandboxes", {
+        body: {
+          templateID: cfg.template,
+          metadata: { [METADATA_NAME]: name },
+          timeout: cfg.timeoutSeconds,
+          // 到点自动暂停而不是删除：内核来不及 suspend（如内核整个挂了）时文件也不丢
+          autoPause: true,
+          // envd 要求访问令牌（与 e2b SDK 的默认一致）；没拿到令牌时 targetOf 拒绝连接
+          secure: true,
+          ...network
+        },
+        signal
+      });
+      if (!r.data?.sandboxID) throw new Error("E2B create sandbox returned no sandboxID");
+      checkId(r.data.sandboxID);
+      return { id: r.data.sandboxID };
+    },
+    async resume(h, signal) {
+      try {
+        await attach(h.id, signal);
+      } catch (e) {
+        if (e instanceof SandboxGoneError) return "gone";
+        throw e;
+      }
+      return "resumed";
+    },
+    async suspend(h, signal) {
+      signal.throwIfAborted();
+      checkId(h.id);
+      try {
+        await api.json("POST", `/sandboxes/${enc(h.id)}/pause`, { body: {}, signal });
+      } catch (e) {
+        if (!isE2BNotFound(e) && !isStatus(e, 409)) throw e;
+      }
+    },
+    async destroy(h, signal) {
+      signal.throwIfAborted();
+      await kill(h.id, signal);
+    },
+    destroyByName,
+    async killAll(h, signal) {
+      signal.throwIfAborted();
+      const t = await attach(h.id, signal);
+      const r = await fileOp(
+        t,
+        {
+          user: SANDBOX_USER,
+          args: ["-c", KILL_ALL_SCRIPT, "capybara-killall"],
+          maxOutputBytes: STDERR_ROOM
+        },
+        signal
+      );
+      if (r.exitCode !== 0) throw new Error(`cannot stop leftover commands: ${stderrOf(r)}`);
+    },
+    async killTagged(h, tags, signal) {
+      signal.throwIfAborted();
+      for (const t2 of tags) {
+        if (!SANDBOX_TAG_RE.test(t2)) throw new Error("invalid sandbox tag");
+      }
+      if (tags.length === 0) return;
+      const t = await attach(h.id, signal);
+      const r = await fileOp(
+        t,
+        {
+          user: SANDBOX_USER,
+          args: ["-c", KILL_TAGGED_SCRIPT, "capybara-killtagged", ...tags],
+          maxOutputBytes: STDERR_ROOM
+        },
+        signal
+      );
+      if (r.exitCode !== 0)
+        throw new Error(`cannot stop crashed holders' commands: ${stderrOf(r)}`);
+    },
+    async exec(h, args) {
+      args.signal.throwIfAborted();
+      const ctl = execControlPath(args.tag);
+      const env = { HOME: "/workspace", LANG: "C.UTF-8" };
+      for (const [k, v] of Object.entries(args.env ?? {})) {
+        if (!ENV_KEY_RE.test(k)) throw new Error(`invalid environment variable name: ${k}`);
+        env[k] = v;
+      }
+      const t = await attach(
+        h.id,
+        args.signal,
+        Math.ceil(args.timeoutMs / 1e3) + TIMEOUT_MARGIN_SECONDS
+      );
+      const r = await run(t, {
+        user: SANDBOX_USER,
+        cmd: "setsid",
+        args: execArgs(ctl, args.command, args.timeoutMs),
+        env,
+        cwd: args.cwd ?? "/workspace",
+        maxOutputBytes: args.maxOutputBytes,
+        timeoutMs: args.timeoutMs,
+        signal: args.signal,
+        kill: killer(t, ctl),
+        // 重启也失败时只记日志（错误信息来自 API 正文与状态码，不含 apiKey 与访问令牌），照常返回本次结果
+        recover: () => reboot(h.id).catch((e) => {
+          deps.log.warn(
+            "sandbox-e2b: sandbox reboot failed; the stuck command may still be running",
+            {
+              sandboxId: h.id,
+              err: (e instanceof Error ? e.message : String(e)).slice(0, 500)
+            }
+          );
+        })
+      });
+      return {
+        exitCode: r.exitCode,
+        stdout: decodeOutput(r.stdout, r.truncated),
+        stderr: decodeOutput(r.stderr, r.truncated),
+        truncated: r.truncated,
+        timedOut: r.timedOut
+      };
+    },
+    async readFile(h, path, opts) {
+      opts.signal.throwIfAborted();
+      checkPath(path);
+      const t = await attach(h.id, opts.signal);
+      const want = opts.maxBytes + 1;
+      const r = await fileOp(
+        t,
+        {
+          user: SANDBOX_USER,
+          args: ["-c", READ_SCRIPT, "capybara-read", path, String(want)],
+          maxOutputBytes: want + STDERR_ROOM
+        },
+        opts.signal
+      );
+      if (r.exitCode === 3 || r.exitCode === 4) return null;
+      if (r.exitCode !== 0) throw new Error(`cannot read ${path}: ${stderrOf(r)}`);
+      const truncated = r.stdout.byteLength > opts.maxBytes;
+      const data = truncated ? r.stdout.subarray(0, opts.maxBytes) : r.stdout;
+      return { data: new Uint8Array(data), truncated };
+    },
+    async writeFile(h, path, data, signal) {
+      signal.throwIfAborted();
+      checkPath(path);
+      const t = await attach(h.id, signal);
+      const staging = `${UPLOAD_DIR}/${randomUUID()}`;
+      await envdUpload(t, staging, ROOT_USER, data, signal);
+      const skills = path === "/skills" || path.startsWith("/skills/");
+      const r = await fileOp(
+        t,
+        {
+          user: ROOT_USER,
+          args: [
+            "-c",
+            skills ? SKILLS_WRITE_SCRIPT : USER_WRITE_SCRIPT,
+            "capybara-write",
+            path,
+            staging
+          ],
+          maxOutputBytes: STDERR_ROOM
+        },
+        signal
+      );
+      if (r.exitCode !== 0) throw new Error(`cannot write ${path}: ${stderrOf(r)}`);
+    },
+    async stat(h, path, signal) {
+      signal.throwIfAborted();
+      checkPath(path);
+      const t = await attach(h.id, signal);
+      const r = await fileOp(
+        t,
+        {
+          user: SANDBOX_USER,
+          args: ["-c", STAT_SCRIPT, "capybara-stat", path],
+          maxOutputBytes: STDERR_ROOM
+        },
+        signal
+      );
+      if (r.exitCode === 3) return null;
+      const m = r.stdout.toString("utf8").match(/^(\d+) (file|directory)\n?$/);
+      if (r.exitCode !== 0 || !m) throw new Error(`cannot stat ${path}: ${stderrOf(r)}`);
+      return { size: Number(m[1]), isDir: m[2] === "directory" };
+    }
+  };
+}
+var SIGNALS = {
+  hangup: 1,
+  interrupt: 2,
+  quit: 3,
+  "illegal instruction": 4,
+  "trace/breakpoint trap": 5,
+  aborted: 6,
+  "bus error": 7,
+  "floating point exception": 8,
+  killed: 9,
+  "user defined signal 1": 10,
+  "segmentation fault": 11,
+  "user defined signal 2": 12,
+  "broken pipe": 13,
+  "alarm clock": 14,
+  terminated: 15
+};
+function exitCodeOf(end) {
+  const status = end.status ?? "";
+  if (end.exited === true || status.startsWith("exit status ")) return end.exitCode ?? 0;
+  const m = /^signal: (.+?)(?: \(core dumped\))?$/.exec(status);
+  const n = m ? SIGNALS[m[1]] : void 0;
+  return n !== void 0 ? 128 + n : null;
+}
+function decodeOutput(buf, truncated) {
+  let end = buf.byteLength;
+  if (truncated) {
+    for (let i = end - 1; i >= 0 && i >= end - 4; i--) {
+      const b = buf[i];
+      if ((b & 192) === 128) continue;
+      const need = b >= 240 ? 4 : b >= 224 ? 3 : b >= 192 ? 2 : 1;
+      if (end - i < need) end = i;
+      break;
+    }
+  }
+  return buf.subarray(0, end).toString("utf8");
+}
+function checkLimits(l) {
+  if (!(l.cpu > 0) || !(l.memoryMb > 0) || !(l.diskMb > 0)) {
+    throw new Error("sandbox limits cpu, memoryMb and diskMb must be positive");
+  }
+  if (l.egress === "allowlist") {
+    for (const host of l.allowHosts) {
+      const errors = validateAllowHost(host);
+      if (errors.length > 0)
+        throw new Error(`invalid allowHosts entry ${host}: ${errors.join("; ")}`);
+    }
+  }
+}
+
+// src/index.ts
+var MAX_TIMEOUT_SECONDS2 = 86400;
+var DeploymentConfig = z.object({
+  /** E2B API key（`e2b_…`）。 */
+  apiKey: secret(z.string().min(1)),
+  /** 控制面 API 地址；不填为 `https://api.<domain>`。自托管 E2B 填自己的地址。 */
+  apiUrl: z.url({ protocol: /^https?$/ }).optional(),
+  /** 沙箱域名（envd 地址为 `https://49983-<沙箱 id>.<domain>`）；API 返回了沙箱自己的域名时以返回的为准。 */
+  domain: z.string().regex(HOSTNAME_RE, {
+    message: "domain must be a lowercase hostname such as e2b.app"
+  }).default("e2b.app"),
+  /** 模板名或 id：由 plugins/sandbox-docker/image/Dockerfile 构建（见 README）。 */
+  template: z.string().min(1),
+  /**
+   * 沙箱的超时（秒，默认 3600）：到点 E2B 自动暂停（不是删除）沙箱，文件保留。内核每次用沙箱时把它往后推，
+   * 长命令会按命令超时再加余量推后；空闲休眠与过期销毁由内核负责。
+   */
+  timeoutSeconds: z.number().int().min(60).max(MAX_TIMEOUT_SECONDS2).default(3600),
+  /**
+   * E2B 是否支持按域名的出站白名单（E2B 云：支持）。为 false 时（不支持的自托管版本）`allowlist` 退化为
+   * `none` 并打告警。
+   */
+  domainAllowlist: z.boolean().default(true),
+  /** 允许 `sandbox.limits.egress = "open"`（默认 false）。为 false 时 `create` 收到 open 直接报错。 */
+  allowOpenEgress: z.boolean().default(false)
+}).strict();
+var index_default = defineExtension({
+  name: "sandbox-e2b",
+  version: "0.1.0-rc.0",
+  sdk: "^0.1.0-rc.0",
+  provides: [SANDBOX_EXTENSION_POINT],
+  // 只用部署配置与 E2B 的 API，不用任何需要声明的平台能力
+  permissions: {},
+  config: { deployment: DeploymentConfig },
+  setup(ctx) {
+    ctx.provide(
+      SANDBOX_EXTENSION_POINT,
+      createE2BSandbox(ctx.config, { log: ctx.log })
+    );
+  }
+});
+export {
+  DeploymentConfig,
+  IN_SANDBOX_GRACE_SECONDS,
+  METADATA_NAME,
+  createE2BSandbox,
+  decodeOutput,
+  index_default as default,
+  execArgs,
+  exitCodeOf
+};

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@capybara-hq/plugin-sandbox-e2b",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Conversation sandboxes (sandbox@1) as E2B sandboxes (E2B cloud or self-hosted), with pause / resume and E2B egress controls",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/capybara-hq/plugins.git",
+    "directory": "plugins/sandbox-e2b"
+  },
+  "homepage": "https://github.com/capybara-hq/plugins/tree/main/plugins/sandbox-e2b#readme",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
+  "peerDependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "zod": "^4.6.7"
+  }
+}