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

package/dist/index.mjs

@@ -0,0 +1,806 @@
+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, ui } 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: ui(secret(z.string().min(1)), { label: { zh: "API 密钥", en: "API key" } }),
+  /** 控制面 API 地址；不填为 `https://api.<domain>`。自托管 E2B 填自己的地址。 */
+  apiUrl: ui(z.url({ protocol: /^https?$/ }).optional(), {
+    label: { zh: "接口地址", en: "API URL" }
+  }),
+  /** 沙箱域名（envd 地址为 `https://49983-<沙箱 id>.<domain>`）；API 返回了沙箱自己的域名时以返回的为准。 */
+  domain: ui(
+    z.string().regex(HOSTNAME_RE, {
+      message: "domain must be a lowercase hostname such as e2b.app"
+    }).default("e2b.app"),
+    { label: { zh: "沙箱域名", en: "Sandbox domain" } }
+  ),
+  /** 模板名或 id：由 plugins/sandbox-docker/image/Dockerfile 构建（见 README）。 */
+  template: ui(z.string().min(1), { label: { zh: "模板", en: "Template" } }),
+  /**
+   * 沙箱的超时（秒，默认 3600）：到点 E2B 自动暂停（不是删除）沙箱，文件保留。内核每次用沙箱时把它往后推，
+   * 长命令会按命令超时再加余量推后；空闲休眠与过期销毁由内核负责。
+   */
+  timeoutSeconds: ui(z.number().int().min(60).max(MAX_TIMEOUT_SECONDS2).default(3600), {
+    label: { zh: "沙箱超时", en: "Sandbox timeout" }
+  }),
+  /**
+   * E2B 是否支持按域名的出站白名单（E2B 云：支持）。为 false 时（不支持的自托管版本）`allowlist` 退化为
+   * `none` 并打告警。
+   */
+  domainAllowlist: ui(z.boolean().default(true), {
+    label: { zh: "按域名出站白名单", en: "Domain egress allowlist" }
+  }),
+  /** 允许 `sandbox.limits.egress = "open"`（默认 false）。为 false 时 `create` 收到 open 直接报错。 */
+  allowOpenEgress: ui(z.boolean().default(false), {
+    label: { zh: "允许开放出站", en: "Allow open egress" }
+  })
+}).strict();
+var index_default = defineExtension({
+  name: "sandbox-e2b",
+  version: "0.1.0-rc.1",
+  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
+};