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

package/dist/index.mjs

@@ -0,0 +1,957 @@
+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, 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/docker-api.ts
+import { request } from "node:http";
+var DOCKER_API_VERSION = "v1.44";
+var MAX_BODY_BYTES = 4 * 1024 * 1024;
+var DockerApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "DockerApiError";
+  }
+  status;
+};
+var isStatus = (e, ...status) => e instanceof DockerApiError && status.includes(e.status);
+function parseEndpoint(endpoint) {
+  if (endpoint.startsWith("unix://")) {
+    const socketPath = endpoint.slice("unix://".length);
+    if (!socketPath.startsWith("/")) throw new Error(`invalid unix endpoint: ${endpoint}`);
+    return { socketPath };
+  }
+  const m = endpoint.match(/^tcp:\/\/(\[[^\]]+\]|[^:/]+):(\d{1,5})\/?$/);
+  if (!m)
+    throw new Error(`invalid endpoint (expected tcp://host:port or unix:///path): ${endpoint}`);
+  return { host: m[1].replace(/^\[|\]$/g, ""), port: Number(m[2]) };
+}
+function readBody(res, signal) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    const onAbort = () => {
+      res.destroy();
+      reject(abortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    res.on("data", (c) => {
+      size += c.byteLength;
+      if (size <= MAX_BODY_BYTES) chunks.push(c);
+    });
+    res.on("end", () => {
+      signal.removeEventListener("abort", onAbort);
+      resolve(Buffer.concat(chunks));
+    });
+    res.on("error", (e) => {
+      signal.removeEventListener("abort", onAbort);
+      reject(e);
+    });
+  });
+}
+function abortReason(signal) {
+  return signal.reason instanceof Error ? signal.reason : new Error("aborted");
+}
+function errorMessage(status, body) {
+  try {
+    const j = JSON.parse(body.toString("utf8"));
+    if (typeof j.message === "string") return j.message;
+  } catch {
+  }
+  return body.toString("utf8").trim() || `HTTP ${status}`;
+}
+function createDockerClient(endpoint) {
+  const target = parseEndpoint(endpoint);
+  const pathOf = (path, query) => {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query ?? {})) if (v !== void 0) qs.set(k, String(v));
+    const s = qs.toString();
+    return `/${DOCKER_API_VERSION}${path}${s === "" ? "" : `?${s}`}`;
+  };
+  return {
+    json(method, path, opts) {
+      opts.signal.throwIfAborted();
+      const payload = opts.body === void 0 ? void 0 : Buffer.from(JSON.stringify(opts.body));
+      return new Promise((resolve, reject) => {
+        const req = request({
+          ...target,
+          method,
+          path: pathOf(path, opts.query),
+          headers: {
+            ...payload && {
+              "content-type": "application/json",
+              "content-length": payload.byteLength
+            }
+          },
+          signal: opts.signal
+        });
+        req.on("error", (e) => reject(opts.signal.aborted ? abortReason(opts.signal) : e));
+        req.on("response", (res) => {
+          readBody(res, opts.signal).then((body) => {
+            const status = res.statusCode ?? 0;
+            if (status < 200 || status >= 300) {
+              reject(new DockerApiError(status, errorMessage(status, body)));
+              return;
+            }
+            const text = body.toString("utf8").trim();
+            if (text === "") {
+              resolve(void 0);
+              return;
+            }
+            const lines = text.split("\n").filter((l) => l.trim() !== "");
+            try {
+              let last;
+              for (const l of lines) {
+                last = JSON.parse(l);
+                const err = last.error;
+                if (typeof err === "string") {
+                  reject(new DockerApiError(500, err));
+                  return;
+                }
+              }
+              resolve(last);
+            } catch {
+              resolve(text);
+            }
+          }, reject);
+        });
+        req.end(payload);
+      });
+    },
+    hijack(path, body, signal) {
+      signal.throwIfAborted();
+      const payload = Buffer.from(JSON.stringify(body));
+      return new Promise((resolve, reject) => {
+        const req = request({
+          ...target,
+          method: "POST",
+          path: pathOf(path),
+          headers: {
+            "content-type": "application/json",
+            "content-length": payload.byteLength,
+            connection: "Upgrade",
+            upgrade: "tcp"
+          }
+        });
+        const onAbort = () => req.destroy(abortReason(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        const done = () => signal.removeEventListener("abort", onAbort);
+        req.on("error", (e) => {
+          done();
+          reject(signal.aborted ? abortReason(signal) : e);
+        });
+        req.on("upgrade", (_res, socket, head) => {
+          done();
+          if (head.byteLength > 0) socket.unshift(head);
+          resolve(socket);
+        });
+        req.on("response", (res) => {
+          done();
+          readBody(res, AbortSignal.timeout(1e4)).then((b) => {
+            const status = res.statusCode ?? 0;
+            reject(new DockerApiError(status, errorMessage(status, b)));
+          }, reject);
+        });
+        req.end(payload);
+      });
+    }
+  };
+}
+var StreamDemuxer = class {
+  constructor(onFrame) {
+    this.onFrame = onFrame;
+  }
+  onFrame;
+  buf = Buffer.alloc(0);
+  push(chunk) {
+    this.buf = this.buf.byteLength === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+    while (this.buf.byteLength >= 8) {
+      const size = this.buf.readUInt32BE(4);
+      if (this.buf.byteLength < 8 + size) return;
+      const kind = this.buf[0];
+      const data = this.buf.subarray(8, 8 + size);
+      this.buf = this.buf.subarray(8 + size);
+      if (kind === 1 || kind === 2) this.onFrame(kind, data);
+    }
+  }
+};
+
+// src/provider.ts
+var SANDBOX_USER = "1000:1000";
+var ROOT_USER = "0:0";
+var INIT_USER = ROOT_USER;
+var PROXY_PORT = 3128;
+var PIDS_LIMIT = 1024;
+var MIB = 1024 * 1024;
+var STOP_SECONDS = 5;
+var KILL_GRACE_MS = 3e3;
+var EXIT_WAIT_MS = 3e4;
+var STDERR_ROOM = 64 * 1024;
+var LABEL = "dev.capybara.sandbox";
+var LABEL_NAME = "dev.capybara.sandbox.name";
+var LABEL_ROLE = "dev.capybara.sandbox.role";
+var LABEL_EGRESS = "dev.capybara.sandbox.egress";
+var LABEL_ALLOW = "dev.capybara.sandbox.allow-hosts";
+var NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,100}$/;
+var ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function sandboxResourceNames(name) {
+  return {
+    container: name,
+    egress: `${name}-egress`,
+    network: `${name}-net`,
+    workspace: `${name}-workspace`,
+    skills: `${name}-skills`
+  };
+}
+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 execArgv(ctl, command, timeoutMs) {
+  const seconds = Math.ceil(timeoutMs / 1e3) + IN_SANDBOX_GRACE_SECONDS;
+  return [
+    "setsid",
+    "-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 WRITE_SCRIPT = 'set -e; mkdir -p -- "$(dirname -- "$1")"; head -c "$2" > "$1"';
+var STAT_SCRIPT = 'if [ ! -e "$1" ]; then exit 3; fi; exec stat -L -c "%s %F" -- "$1"';
+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) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      t.cancel();
+      reject(abortReason(signal));
+    };
+    const t = 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("; ")}`);
+}
+var NotRunningError = class extends Error {
+  constructor(container, opts) {
+    super(`sandbox container ${container} is not running`, opts);
+    this.name = "NotRunningError";
+  }
+};
+function createDockerSandbox(cfg, test = {}, log) {
+  const api = createDockerClient(cfg.endpoint);
+  const baseLabels = (name, role) => ({
+    ...test.labels,
+    [LABEL]: "1",
+    [LABEL_NAME]: name,
+    [LABEL_ROLE]: role
+  });
+  const enc = encodeURIComponent;
+  const postCreate = async (path, opts) => {
+    const text = JSON.stringify(opts.body ?? null);
+    if (/[^\x00-\x7f]/.test(text)) {
+      throw new Error(
+        `sandbox-docker: ${path} request contains non-ASCII characters (image, names, labels, environment and allowHosts must be ASCII; use punycode for hostnames)`
+      );
+    }
+    return api.json("POST", path, opts);
+  };
+  const ignore = (...status) => (e) => {
+    if (!isStatus(e, ...status)) throw e;
+  };
+  const removeWithRetry = async (path, signal) => {
+    for (let i = 0; ; i++) {
+      try {
+        await api.json("DELETE", path, { signal });
+        return;
+      } catch (e) {
+        if (isStatus(e, 404)) return;
+        if (i >= 20 || !isStatus(e, 403, 409, 500)) throw e;
+        await sleep(250, signal);
+      }
+    }
+  };
+  const destroyByName = async (name, signal) => {
+    signal.throwIfAborted();
+    const n = sandboxResourceNames(name);
+    await Promise.all(
+      [n.container, n.egress].map(
+        (c) => api.json("DELETE", `/containers/${enc(c)}`, { query: { force: true }, signal }).catch(ignore(404, 409))
+      )
+    );
+    await Promise.all([
+      removeWithRetry(`/networks/${enc(n.network)}`, signal),
+      removeWithRetry(`/volumes/${enc(n.workspace)}`, signal),
+      removeWithRetry(`/volumes/${enc(n.skills)}`, signal)
+    ]);
+  };
+  const pull = async (image, signal) => {
+    await api.json("POST", "/images/create", { query: { fromImage: image }, signal });
+  };
+  const createContainer = async (name, body, signal) => {
+    const go = () => postCreate("/containers/create", { query: { name }, body, signal });
+    try {
+      await go();
+    } catch (e) {
+      if (!(isStatus(e, 404) && /no such image/i.test(e.message))) throw e;
+      await pull(String(body.Image), signal);
+      await go();
+    }
+  };
+  const start = (container, signal) => api.json("POST", `/containers/${enc(container)}/start`, { signal }).catch(ignore(304));
+  const unpause = (container, signal) => api.json("POST", `/containers/${enc(container)}/unpause`, { signal }).catch(ignore(409));
+  const ensureSharedNetwork = async (signal) => {
+    try {
+      await api.json("GET", `/networks/${enc(cfg.network)}`, { signal });
+    } catch (e) {
+      if (!isStatus(e, 404)) throw e;
+      await postCreate("/networks/create", {
+        body: {
+          Name: cfg.network,
+          Driver: "bridge",
+          // 共用网络上的容器（open 的沙箱、各出站代理）互相不通
+          Options: { "com.docker.network.bridge.enable_icc": "false" },
+          Labels: { ...test.labels, [LABEL]: "1", [LABEL_ROLE]: "shared-network" }
+        },
+        signal
+      }).catch(ignore(409));
+    }
+  };
+  const ensureInternalNetwork = async (name, signal) => {
+    const n = sandboxResourceNames(name);
+    try {
+      await api.json("GET", `/networks/${enc(n.network)}`, { signal });
+    } catch (e) {
+      if (!isStatus(e, 404)) throw e;
+      await postCreate("/networks/create", {
+        body: {
+          Name: n.network,
+          Driver: "bridge",
+          Internal: true,
+          Labels: baseLabels(name, "network")
+        },
+        signal
+      }).catch(ignore(409));
+    }
+  };
+  const waitEgressReady = async (container, signal) => {
+    for (let i = 0; ; i++) {
+      const r = await run(container, {
+        cmd: ["wget", "-q", "-O", "-", `http://127.0.0.1:${PROXY_PORT}/healthz`],
+        user: "",
+        maxOutputBytes: 1024,
+        signal
+      }).catch((e) => {
+        if (signal.aborted) throw abortReason(signal);
+        if (i >= 50) throw e;
+        return null;
+      });
+      if (r?.exitCode === 0) return;
+      if (i >= 50) throw new Error("sandbox egress proxy did not become ready");
+      await sleep(100, signal);
+    }
+  };
+  const createEgress = async (name, allowHosts, signal, mayExist = false) => {
+    const n = sandboxResourceNames(name);
+    const env = [`ALLOW_HOSTS=${JSON.stringify(allowHosts)}`, `PORT=${PROXY_PORT}`];
+    if (test.egressTestHosts) {
+      env.push(`CAPYBARA_EGRESS_TEST_HOSTS=${JSON.stringify(test.egressTestHosts)}`);
+    }
+    const made = createContainer(
+      n.egress,
+      {
+        Image: cfg.egressProxyImage,
+        Env: env,
+        Labels: baseLabels(name, "egress"),
+        HostConfig: {
+          NetworkMode: cfg.network,
+          Init: true,
+          ReadonlyRootfs: true,
+          CapDrop: ["ALL"],
+          SecurityOpt: ["no-new-privileges:true"],
+          Memory: 128 * MIB,
+          MemorySwap: 128 * MIB,
+          NanoCpus: 5e8,
+          PidsLimit: 128
+        },
+        NetworkingConfig: { EndpointsConfig: { [cfg.network]: {}, [n.network]: {} } }
+      },
+      signal
+    );
+    await (mayExist ? made.catch(ignore(409)) : made);
+    await start(n.egress, signal);
+    await waitEgressReady(n.egress, signal);
+  };
+  const ensureEgressRunning = async (name, allowHosts, signal) => {
+    const n = sandboxResourceNames(name);
+    await ensureSharedNetwork(signal);
+    await ensureInternalNetwork(name, signal);
+    let running;
+    try {
+      const c = await api.json(
+        "GET",
+        `/containers/${enc(n.egress)}/json`,
+        { signal }
+      );
+      if (c.State.Paused) await unpause(n.egress, signal);
+      running = c.State.Running;
+    } catch (e) {
+      if (!isStatus(e, 404)) throw e;
+      await createEgress(name, allowHosts, signal, true);
+      return;
+    }
+    if (!running) {
+      await start(n.egress, signal);
+      await waitEgressReady(n.egress, signal);
+    }
+  };
+  async function run(container, o) {
+    o.signal.throwIfAborted();
+    const startedAt = Date.now();
+    let execId;
+    try {
+      const r = await api.json("POST", `/containers/${enc(container)}/exec`, {
+        body: {
+          AttachStdin: o.stdin !== void 0,
+          AttachStdout: true,
+          AttachStderr: true,
+          Tty: false,
+          Cmd: o.cmd,
+          ...o.user !== "" && { User: o.user },
+          ...o.env && { Env: o.env },
+          ...o.cwd !== void 0 && { WorkingDir: o.cwd }
+        },
+        signal: o.signal
+      });
+      execId = r.Id;
+    } catch (e) {
+      if (isStatus(e, 404)) {
+        throw new SandboxGoneError(`sandbox container ${container} no longer exists`, { cause: e });
+      }
+      if (isStatus(e, 409)) throw new NotRunningError(container, { cause: e });
+      throw e;
+    }
+    let socket;
+    try {
+      socket = await api.hijack(`/exec/${execId}/start`, { Detach: false, Tty: false }, o.signal);
+    } catch (e) {
+      if (isStatus(e, 404)) {
+        throw new SandboxGoneError(`sandbox container ${container} no longer exists`, { cause: e });
+      }
+      if (isStatus(e, 409)) throw new NotRunningError(container, { cause: e });
+      if (!o.signal.aborted) throw e;
+      await o.kill?.().catch(() => void 0);
+      return {
+        exitCode: null,
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.alloc(0),
+        truncated: false,
+        timedOut: false,
+        aborted: true
+      };
+    }
+    const out = [];
+    const err = [];
+    let used = 0;
+    let truncated = false;
+    let timedOut = false;
+    let aborted = false;
+    let stopping = false;
+    const demux = new StreamDemuxer((kind, data) => {
+      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 === 1 ? out : err).push(Buffer.from(keep));
+    });
+    const ended = new Promise((resolve) => {
+      socket.on("data", (c) => demux.push(c));
+      socket.on("error", (e) => resolve(e));
+      socket.on("close", () => resolve(null));
+      socket.on("end", () => {
+        socket.destroy();
+        resolve(null);
+      });
+    });
+    let grace;
+    let killing;
+    const stop = () => {
+      if (stopping) return;
+      stopping = true;
+      const cut = () => {
+        grace = after(KILL_GRACE_MS, () => socket.destroy());
+      };
+      if (o.kill)
+        killing = o.kill().catch(() => void 0).finally(cut);
+      else socket.destroy();
+    };
+    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 });
+    if (o.signal.aborted) onAbort();
+    if (o.stdin !== void 0 && o.stdin.byteLength > 0) socket.write(o.stdin);
+    const streamError = await ended;
+    await killing;
+    timer?.cancel();
+    grace?.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) throw streamError;
+    const deadline = o.timeoutMs !== void 0 ? startedAt + o.timeoutMs : Date.now() + EXIT_WAIT_MS;
+    try {
+      for (; ; ) {
+        const s = await api.json(
+          "GET",
+          `/exec/${execId}/json`,
+          { signal: AbortSignal.any([o.signal, AbortSignal.timeout(1e4)]) }
+        );
+        if (!s.Running) return { ...result, exitCode: s.ExitCode };
+        if (Date.now() >= deadline) {
+          if (!o.kill) throw new Error("sandbox command did not report an exit status");
+          await o.kill().catch(() => void 0);
+          return { ...result, timedOut: true, exitCode: null };
+        }
+        await sleep(50, o.signal);
+      }
+    } catch (e) {
+      if (o.signal.aborted) {
+        await o.kill?.().catch(() => void 0);
+        return { ...result, aborted: true, exitCode: null };
+      }
+      throw e;
+    }
+  }
+  const killer = (container, ctl) => () => (
+    // 杀进程不受调用方 signal 影响（它往往正是已中止的那个）
+    killOrRestart(container, ["/bin/sh", "-c", KILL_SCRIPT, "capybara-kill", ctl])
+  );
+  const killOrRestart = async (container, cmd, signal) => {
+    const within = (ms) => signal ? AbortSignal.any([signal, AbortSignal.timeout(ms)]) : AbortSignal.timeout(ms);
+    const ok = await run(container, {
+      cmd,
+      user: SANDBOX_USER,
+      maxOutputBytes: 4096,
+      signal: within(15e3)
+    }).then(
+      (r) => r.exitCode === 0 && !r.aborted,
+      () => false
+    );
+    if (ok) return;
+    signal?.throwIfAborted();
+    log?.warn(
+      "sandbox-docker: the kill command could not run; restarting the container, which also ends other commands in it",
+      { container }
+    );
+    await api.json("POST", `/containers/${enc(container)}/restart`, {
+      query: { t: 0 },
+      signal: within(6e4)
+    });
+  };
+  const fileOp = async (h, o, signal) => {
+    const r = await autoStart(h, signal, () => run(h.id, { ...o, signal }));
+    if (r.aborted) throw abortReason(signal);
+    return r;
+  };
+  async function autoStart(h, signal, fn) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (!(e instanceof NotRunningError)) throw e;
+      if (await resume(h, signal) === "gone") {
+        throw new SandboxGoneError(`sandbox container ${h.id} no longer exists`, { cause: e });
+      }
+      return await fn();
+    }
+  }
+  async function resume(h, signal) {
+    signal.throwIfAborted();
+    let c;
+    try {
+      c = await api.json("GET", `/containers/${enc(h.id)}/json`, { signal });
+    } catch (e) {
+      if (isStatus(e, 404)) return "gone";
+      throw e;
+    }
+    const labels = c.Config.Labels ?? {};
+    if (labels[LABEL_EGRESS] === "open") await ensureSharedNetwork(signal);
+    if (labels[LABEL_EGRESS] === "allowlist") {
+      await ensureEgressRunning(h.id, JSON.parse(labels[LABEL_ALLOW] ?? "[]"), signal);
+    }
+    try {
+      if (c.State.Paused) await unpause(h.id, signal);
+      else if (!c.State.Running) await start(h.id, signal);
+    } catch (e) {
+      if (isStatus(e, 404)) return "gone";
+      throw e;
+    }
+    return "resumed";
+  }
+  const stderrOf = (r) => r.stderr.toString("utf8").trim().slice(0, 500);
+  return {
+    // docker exec instances are independent; auto-start tolerates concurrent starts (304 / 409)
+    concurrentExec: true,
+    async create({ name, image, limits, signal }) {
+      signal.throwIfAborted();
+      if (!NAME_RE.test(name)) throw new Error(`invalid sandbox name: ${name}`);
+      checkLimits(limits);
+      if (limits.egress === "open" && cfg.allowOpenEgress !== true) {
+        throw new Error(
+          'Sandbox egress "open" (sandbox.limits.egress) is refused: the sandbox-docker plugin setting allowOpenEgress is false. Set extensionConfig."sandbox-docker".allowOpenEgress to true (trusted environments only), or set sandbox.limits.egress to "allowlist" or "none".'
+        );
+      }
+      const n = sandboxResourceNames(name);
+      await destroyByName(name, signal);
+      try {
+        await postCreate("/volumes/create", {
+          body: {
+            Name: n.workspace,
+            Labels: baseLabels(name, "workspace"),
+            ...cfg.volumeDriver !== void 0 && {
+              Driver: cfg.volumeDriver,
+              DriverOpts: { size: `${limits.diskMb}M` }
+            }
+          },
+          signal
+        });
+        await postCreate("/volumes/create", {
+          body: { Name: n.skills, Labels: baseLabels(name, "skills") },
+          signal
+        });
+        const env = ["HOME=/workspace", "LANG=C.UTF-8"];
+        let networkMode = "none";
+        if (limits.egress === "open") {
+          await ensureSharedNetwork(signal);
+          networkMode = cfg.network;
+        } else if (limits.egress === "allowlist") {
+          await ensureSharedNetwork(signal);
+          await ensureInternalNetwork(name, signal);
+          await createEgress(name, limits.allowHosts, signal);
+          networkMode = n.network;
+          const proxy = `http://${n.egress}:${PROXY_PORT}`;
+          env.push(
+            `HTTP_PROXY=${proxy}`,
+            `HTTPS_PROXY=${proxy}`,
+            `http_proxy=${proxy}`,
+            `https_proxy=${proxy}`,
+            "NO_PROXY=localhost,127.0.0.1,::1",
+            "no_proxy=localhost,127.0.0.1,::1"
+          );
+        }
+        const memory = limits.memoryMb * MIB;
+        const tmpMb = Math.max(16, Math.min(limits.diskMb, Math.floor(limits.memoryMb / 2)));
+        await createContainer(
+          n.container,
+          {
+            Image: image,
+            User: INIT_USER,
+            WorkingDir: "/workspace",
+            Cmd: ["sleep", "infinity"],
+            Env: env,
+            Labels: {
+              ...baseLabels(name, "sandbox"),
+              [LABEL_EGRESS]: limits.egress,
+              [LABEL_ALLOW]: JSON.stringify(limits.egress === "allowlist" ? limits.allowHosts : [])
+            },
+            HostConfig: {
+              Runtime: cfg.runtime,
+              Init: true,
+              NanoCpus: Math.round(limits.cpu * 1e9),
+              Memory: memory,
+              MemorySwap: memory,
+              PidsLimit: PIDS_LIMIT,
+              ReadonlyRootfs: true,
+              CapDrop: ["ALL"],
+              SecurityOpt: ["no-new-privileges:true"],
+              IpcMode: "private",
+              NetworkMode: networkMode,
+              Tmpfs: { "/tmp": `rw,nosuid,nodev,size=${tmpMb}m,mode=1777` },
+              Mounts: [
+                { Type: "volume", Source: n.workspace, Target: "/workspace" },
+                { Type: "volume", Source: n.skills, Target: "/skills", ReadOnly: true },
+                // 同一个卷的可写挂载：只有 root 进得去（/opt/capybara 是 0700），插件经它写技能
+                { Type: "volume", Source: n.skills, Target: "/opt/capybara/skills" }
+              ]
+            }
+          },
+          signal
+        );
+        await start(n.container, signal);
+      } catch (e) {
+        if (!signal.aborted) {
+          await destroyByName(name, AbortSignal.timeout(6e4)).catch(() => void 0);
+        }
+        throw e;
+      }
+      return { id: name };
+    },
+    resume,
+    async suspend(h, signal) {
+      signal.throwIfAborted();
+      const n = sandboxResourceNames(h.id);
+      for (const c of [n.container, n.egress]) {
+        await api.json("POST", `/containers/${enc(c)}/stop`, { query: { t: STOP_SECONDS }, signal }).catch(ignore(304, 404));
+      }
+    },
+    async destroy(h, signal) {
+      await destroyByName(h.id, signal);
+    },
+    destroyByName,
+    async killAll(h, signal) {
+      signal.throwIfAborted();
+      await autoStart(
+        h,
+        signal,
+        () => run(h.id, { cmd: ["true"], user: SANDBOX_USER, maxOutputBytes: 1024, signal })
+      );
+      await killOrRestart(h.id, ["/bin/sh", "-c", KILL_ALL_SCRIPT, "capybara-killall"], signal);
+    },
+    async killTagged(h, tags, signal) {
+      signal.throwIfAborted();
+      for (const t of tags) {
+        if (!SANDBOX_TAG_RE.test(t)) throw new Error("invalid sandbox tag");
+      }
+      if (tags.length === 0) return;
+      await autoStart(
+        h,
+        signal,
+        () => run(h.id, { cmd: ["true"], user: SANDBOX_USER, maxOutputBytes: 1024, signal })
+      );
+      await killOrRestart(
+        h.id,
+        ["/bin/sh", "-c", KILL_TAGGED_SCRIPT, "capybara-killtagged", ...tags],
+        signal
+      );
+    },
+    async exec(h, args) {
+      args.signal.throwIfAborted();
+      const ctl = execControlPath(args.tag);
+      const env = [];
+      for (const [k, v] of Object.entries(args.env ?? {})) {
+        if (!ENV_KEY_RE.test(k)) throw new Error(`invalid environment variable name: ${k}`);
+        env.push(`${k}=${v}`);
+      }
+      const r = await autoStart(
+        h,
+        args.signal,
+        () => run(h.id, {
+          cmd: execArgv(ctl, args.command, args.timeoutMs),
+          user: SANDBOX_USER,
+          env,
+          cwd: args.cwd ?? "/workspace",
+          maxOutputBytes: args.maxOutputBytes,
+          timeoutMs: args.timeoutMs,
+          signal: args.signal,
+          kill: killer(h.id, ctl)
+        })
+      );
+      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 want = opts.maxBytes + 1;
+      const r = await fileOp(
+        h,
+        {
+          cmd: ["/bin/sh", "-c", READ_SCRIPT, "capybara-read", path, String(want)],
+          user: SANDBOX_USER,
+          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 skills = path === "/skills" || path.startsWith("/skills/");
+      const r = await fileOp(
+        h,
+        {
+          cmd: [
+            "/bin/sh",
+            "-c",
+            WRITE_SCRIPT,
+            "capybara-write",
+            skills ? `/opt/capybara${path}` : path,
+            String(data.byteLength)
+          ],
+          user: skills ? ROOT_USER : SANDBOX_USER,
+          stdin: data,
+          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 r = await fileOp(
+        h,
+        {
+          cmd: ["/bin/sh", "-c", STAT_SCRIPT, "capybara-stat", path],
+          user: SANDBOX_USER,
+          maxOutputBytes: STDERR_ROOM
+        },
+        signal
+      );
+      if (r.exitCode === 3) return null;
+      const m = r.stdout.toString("utf8").match(/^(\d+) (.+)\n?$/);
+      if (r.exitCode !== 0 || !m) throw new Error(`cannot stat ${path}: ${stderrOf(r)}`);
+      return { size: Number(m[1]), isDir: m[2] === "directory" };
+    }
+  };
+}
+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 NETWORK_NAME = /^cap[a-zA-Z0-9_.-]*$/;
+var DeploymentConfig = z.object({
+  /** Docker socket 代理地址（docker/sandbox-proxy）：`tcp://sandbox-proxy:2375` 或 `unix:///path`。 */
+  endpoint: ui(
+    z.string().regex(/^(tcp:\/\/(\[[^\]]+\]|[^:/]+):\d{1,5}\/?|unix:\/\/\/.+)$/, {
+      message: "endpoint must be tcp://host:port or unix:///path"
+    }),
+    { label: { zh: "Docker 代理地址", en: "Docker proxy endpoint" } }
+  ),
+  /** 容器运行时：runc（默认）或 gVisor 的 runsc（需在 Docker 守护进程上登记）。 */
+  runtime: ui(z.enum(["runc", "runsc"]).default("runc"), {
+    label: { zh: "容器运行时", en: "Container runtime" }
+  }),
+  /**
+   * 共用的沙箱网络名：egress 为 open 的沙箱与出站代理接在上面；不存在时自动创建（bridge、禁止容器互访）。
+   * 须以 `cap` 开头（socket 代理只放行这样的网络名）。
+   */
+  network: ui(
+    z.string().regex(NETWORK_NAME, {
+      message: "network must start with 'cap' (the socket proxy only allows cap* networks)"
+    }).default("capybara-sandbox"),
+    { label: { zh: "沙箱网络", en: "Sandbox network" } }
+  ),
+  /** 出站代理镜像（plugins/sandbox-docker/egress-proxy/Dockerfile）。 */
+  egressProxyImage: ui(z.string().min(1).default("capybara-sandbox-egress:latest"), {
+    label: { zh: "出站代理镜像", en: "Egress proxy image" }
+  }),
+  /** 工作区卷的驱动（支持 `size` 选项的驱动才能限制磁盘）；不填用 local（不限大小）。 */
+  volumeDriver: ui(z.string().min(1).optional(), {
+    label: { zh: "卷驱动", en: "Volume driver" }
+  }),
+  /**
+   * 允许 `sandbox.limits.egress = "open"`（默认 false）。open 的沙箱能访问宿主机网络能访问的一切
+   * （宿主机上的服务、内网、云元数据地址），只在可信环境打开。
+   */
+  allowOpenEgress: ui(z.boolean().default(false), {
+    label: { zh: "允许开放出站", en: "Allow open egress" }
+  })
+}).strict();
+var index_default = defineExtension({
+  name: "sandbox-docker",
+  version: "0.1.0-rc.1",
+  sdk: "^0.1.0-rc.0",
+  provides: [SANDBOX_EXTENSION_POINT],
+  // 只用部署配置与 Docker endpoint，不用任何需要声明的平台能力
+  permissions: {},
+  config: { deployment: DeploymentConfig },
+  setup(ctx) {
+    ctx.provide(
+      SANDBOX_EXTENSION_POINT,
+      createDockerSandbox(ctx.config, {}, ctx.log)
+    );
+  }
+});
+export {
+  DeploymentConfig,
+  IN_SANDBOX_GRACE_SECONDS,
+  createDockerSandbox,
+  decodeOutput,
+  index_default as default,
+  execArgv,
+  sandboxResourceNames
+};