@hotcell/daemon 0.1.0

package/dist/driver/container.js

@@ -0,0 +1,733 @@
+import Docker from "dockerode";
+import { gatewayOf } from "../net/firewall.js";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Duplex, PassThrough } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { shellEscape } from "../util.js";
+import { log } from "../logger.js";
+export class ContainerDriver {
+    name = "container";
+    docker;
+    ensured = new Set();
+    egress;
+    egressNetReady = false;
+    constructor(docker, egress) {
+        this.docker = docker ?? new Docker();
+        this.egress = egress;
+    }
+    containerName(id) {
+        return `sbx-${id}`;
+    }
+    /** Deterministic name for the sandbox's persistent workspace volume. */
+    volumeName(id) {
+        return `sbx-${id}-workspace`;
+    }
+    async ping() {
+        await this.docker.ping();
+    }
+    async hostInfo() {
+        const info = (await this.docker.info());
+        return {
+            memoryMb: Math.floor((info.MemTotal ?? 0) / (1024 * 1024)),
+            cpus: info.NCPU ?? 0,
+        };
+    }
+    /**
+     * Create the egress-enforcement bridge network if missing (idempotent). Uses the
+     * configured subnet so the host firewall's `-s <subnet>` rules match, with the
+     * gateway pinned to `.1`. Safe to call repeatedly; a 409 (already exists) is fine.
+     */
+    async ensureEgressNetwork() {
+        if (!this.egress || this.egressNetReady)
+            return;
+        const { network, subnet } = this.egress;
+        const gateway = gatewayOf(subnet);
+        try {
+            await this.docker.createNetwork({
+                Name: network,
+                Driver: "bridge",
+                CheckDuplicate: true,
+                IPAM: { Driver: "default", Config: [{ Subnet: subnet, Gateway: gateway }] },
+                Labels: { "sbx.managed": "true" },
+            });
+        }
+        catch (err) {
+            if (!isConflict(err))
+                throw err; // 409 = already exists
+        }
+        this.egressNetReady = true;
+    }
+    /** Create the workspace volume if it does not already exist (idempotent). */
+    async ensureVolume(id) {
+        const name = this.volumeName(id);
+        await this.docker.createVolume({
+            Name: name,
+            Labels: { "sbx.managed": "true", "sbx.id": id },
+        });
+    }
+    /** Pull the image if it is not already present locally. */
+    async ensureImage(image) {
+        if (this.ensured.has(image))
+            return;
+        const images = await this.docker.listImages({
+            filters: { reference: [image] },
+        });
+        if (images.length === 0) {
+            await new Promise((resolve, reject) => {
+                this.docker.pull(image, (err, stream) => {
+                    if (err)
+                        return reject(err);
+                    this.docker.modem.followProgress(stream, (doneErr) => doneErr ? reject(doneErr) : resolve());
+                });
+            });
+        }
+        this.ensured.add(image);
+    }
+    async create(opts) {
+        await this.launchContainer(opts);
+        if (opts.repo)
+            await this.cloneRepo(opts.id, opts.repo, opts.repoRef);
+        await this.runSetup(opts.id, opts.setup ?? []);
+    }
+    /**
+     * Clone a git repo into `/workspace` at create time so an agent comes up with
+     * the code in place. Installs git first if the image lacks it (the default
+     * slim image), then shallow-clones into a subdir named after the repo. A
+     * failure throws — unlike best-effort `setup`, the agent needs the code.
+     */
+    async cloneRepo(id, repo, ref) {
+        const refFlag = ref ? `--branch ${shellEscape(ref)} ` : "";
+        const script = `if ! command -v git >/dev/null 2>&1; then apt-get update && apt-get install -y git >/dev/null 2>&1; fi\n` +
+            `cd /workspace && git clone --depth 1 ${refFlag}${shellEscape(repo)}`;
+        const { stdout, stderr, exitCode } = await this.execCapture(id, script);
+        if (exitCode !== 0) {
+            throw new Error(`git clone failed: ${(stderr || stdout).trim() || `exit ${exitCode}`}`);
+        }
+        log.info("repo cloned", { sandbox: id, repo });
+    }
+    /**
+     * Run declarative setup commands in order, once, after the container starts.
+     * Best-effort: a non-zero exit is logged but does not fail create. Kept out of
+     * `launchContainer` on purpose so it does not re-fire on `start()`/resume.
+     */
+    async runSetup(id, commands) {
+        for (const command of commands) {
+            const { stderr, exitCode } = await this.execCapture(id, command);
+            if (exitCode === 0) {
+                log.info("setup command ok", { sandbox: id, command });
+            }
+            else {
+                log.warn("setup command failed (continuing)", {
+                    sandbox: id,
+                    command,
+                    exitCode,
+                    stderr: stderr.trim(),
+                });
+            }
+        }
+    }
+    async start(opts) {
+        try {
+            await this.launchContainer(opts);
+        }
+        catch (err) {
+            // A 409 means the container already exists (already started) — treat as ok.
+            if (!isConflict(err))
+                throw err;
+        }
+    }
+    async stop(id) {
+        // Remove the container but keep the workspace volume. With persistence the
+        // data survives; without it, stop is effectively a destroy of the rootfs.
+        const container = this.docker.getContainer(this.containerName(id));
+        try {
+            await container.remove({ force: true });
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                throw err;
+        }
+    }
+    /** Shared create/start path: ensure image (+volume), then run the container. */
+    async launchContainer(opts) {
+        await this.ensureImage(opts.image);
+        const persist = opts.persist ?? true;
+        if (persist)
+            await this.ensureVolume(opts.id);
+        // Under egress enforcement, put the sandbox on the dedicated bridge network
+        // (whose egress is locked down by the host firewall) and pin its DNS resolver.
+        const enforced = this.egress?.enforce === true;
+        if (enforced)
+            await this.ensureEgressNetwork();
+        const env = Object.entries(opts.env ?? {}).map(([k, v]) => `${k}=${v}`);
+        const container = await this.docker.createContainer({
+            name: this.containerName(opts.id),
+            Image: opts.image,
+            // Keep the sandbox alive regardless of the image's default CMD.
+            Entrypoint: ["/bin/sh", "-c"],
+            Cmd: ["sleep infinity"],
+            Env: env,
+            Labels: { "sbx.managed": "true", "sbx.id": opts.id, ...opts.labels },
+            WorkingDir: "/workspace",
+            HostConfig: {
+                AutoRemove: false,
+                // Back /workspace with the named volume so it outlives the container.
+                ...(persist ? { Binds: [`${this.volumeName(opts.id)}:/workspace`] } : {}),
+                // Join the locked-down egress network when enforcement is on; otherwise the
+                // default bridge.
+                ...(enforced ? { NetworkMode: this.egress.network } : {}),
+                // Pin DNS to a controlled resolver under enforcement (blocks DNS exfil; DoH
+                // is separately denied by the allowlist). Empty = Docker's embedded resolver.
+                ...(enforced && this.egress.dns ? { Dns: [this.egress.dns] } : {}),
+                // Make `host.docker.internal` resolve to the daemon host from inside the
+                // sandbox so the egress LLM gateway is reachable. Docker Desktop (macOS)
+                // injects this name automatically; native Linux dockerd does not, so we
+                // map it to the bridge gateway explicitly (Docker ≥20.10). Harmless on
+                // Desktop, which already defines it — keeps one codepath across hosts.
+                ExtraHosts: ["host.docker.internal:host-gateway"],
+                // Hard per-sandbox resource caps (cgroups). Each is omitted when 0/unset.
+                ...resourceHostConfig(opts.limits),
+            },
+        });
+        await container.start();
+    }
+    async exec(id, command, opts, onEvent) {
+        const container = this.docker.getContainer(this.containerName(id));
+        const exec = await container.exec({
+            Cmd: ["/bin/bash", "-lc", command],
+            AttachStdout: true,
+            AttachStderr: true,
+            WorkingDir: opts.cwd ?? "/workspace",
+            Env: Object.entries(opts.env ?? {}).map(([k, v]) => `${k}=${v}`),
+        });
+        const stream = await exec.start({ hijack: true, stdin: false });
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        stdout.on("data", (chunk) => onEvent({ type: "stdout", data: chunk.toString("utf8") }));
+        stderr.on("data", (chunk) => onEvent({ type: "stderr", data: chunk.toString("utf8") }));
+        // Demultiplex Docker's combined stdout/stderr framing.
+        this.docker.modem.demuxStream(stream, stdout, stderr);
+        await new Promise((resolve, reject) => {
+            stream.on("end", resolve);
+            stream.on("error", reject);
+        });
+        stdout.end();
+        stderr.end();
+        const info = await exec.inspect();
+        const exitCode = info.ExitCode ?? 0;
+        onEvent({ type: "exit", exitCode });
+        return exitCode;
+    }
+    /**
+     * Run a non-interactive command and capture its streams + exit code. Never
+     * throws on a non-zero exit — callers decide what a failure means.
+     */
+    async execCapture(id, command, opts = {}) {
+        const container = this.docker.getContainer(this.containerName(id));
+        const exec = await container.exec({
+            Cmd: ["/bin/bash", "-c", command],
+            AttachStdout: true,
+            AttachStderr: true,
+            WorkingDir: opts.cwd ?? "/workspace",
+            Env: Object.entries(opts.env ?? {}).map(([k, v]) => `${k}=${v}`),
+        });
+        const stream = await exec.start({ hijack: true, stdin: false });
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        let out = "";
+        let err = "";
+        stdout.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+        });
+        stderr.on("data", (chunk) => {
+            err += chunk.toString("utf8");
+        });
+        this.docker.modem.demuxStream(stream, stdout, stderr);
+        await new Promise((resolve, reject) => {
+            stream.on("end", resolve);
+            stream.on("error", reject);
+        });
+        stdout.end();
+        stderr.end();
+        const info = await exec.inspect();
+        return { stdout: out, stderr: err, exitCode: info.ExitCode ?? 0 };
+    }
+    /**
+     * Run a non-interactive command and return its stdout as a UTF-8 string.
+     * Throws if the command exits non-zero.
+     */
+    async runAndCapture(id, command) {
+        const { stdout, stderr, exitCode } = await this.execCapture(id, command);
+        if (exitCode !== 0) {
+            throw new Error(stderr.trim() || `command failed with exit code ${exitCode}`);
+        }
+        return stdout;
+    }
+    async writeFile(id, opts) {
+        if (opts.mode !== undefined && !/^[0-7]{3,4}$/.test(opts.mode)) {
+            throw new Error(`invalid file mode: ${opts.mode}`);
+        }
+        const dir = opts.path.includes("/")
+            ? opts.path.slice(0, opts.path.lastIndexOf("/"))
+            : "/workspace";
+        const encoded = Buffer.from(opts.content, "utf8").toString("base64");
+        // `mode` is validated above to be octal digits only, so it's safe unquoted.
+        const mode = opts.mode ? `chmod ${opts.mode} ${shellEscape(opts.path)} && ` : "";
+        const command = `mkdir -p ${shellEscape(dir)} && printf '%s' '${encoded}' | base64 -d > ${shellEscape(opts.path)} && ${mode}echo ok`;
+        const output = await this.runAndCapture(id, command);
+        if (output.trim() !== "ok") {
+            throw new Error(`writeFile failed: ${output}`);
+        }
+    }
+    async readFile(id, opts) {
+        return this.runAndCapture(id, `cat ${shellEscape(opts.path)}`);
+    }
+    async mkdir(id, opts) {
+        const flag = opts.parents ? "-p" : "";
+        await this.runAndCapture(id, `mkdir ${flag} ${shellEscape(opts.path)}`);
+    }
+    async listFiles(id, opts) {
+        const container = this.docker.getContainer(this.containerName(id));
+        const exec = await container.exec({
+            Cmd: [
+                "/bin/sh",
+                "-c",
+                `find ${shellEscape(opts.path)} -maxdepth 1 -printf '%y|%p|%s|%TY-%Tm-%TdT%TH:%TM:%TS\\n'`,
+            ],
+            AttachStdout: true,
+            AttachStderr: true,
+            WorkingDir: "/workspace",
+        });
+        const stream = await exec.start({ hijack: true, stdin: false });
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        let out = "";
+        let err = "";
+        stdout.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+        });
+        stderr.on("data", (chunk) => {
+            err += chunk.toString("utf8");
+        });
+        this.docker.modem.demuxStream(stream, stdout, stderr);
+        await new Promise((resolve, reject) => {
+            stream.on("end", resolve);
+            stream.on("error", reject);
+        });
+        stdout.end();
+        stderr.end();
+        const info = await exec.inspect();
+        if ((info.ExitCode ?? 0) !== 0) {
+            throw new Error(`listFiles failed: ${err || "unknown error"}`);
+        }
+        const lines = out
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+        return lines.map((line) => {
+            const [type, rawPath, size, mtime] = line.split("|");
+            const path = rawPath;
+            const name = path.slice(path.lastIndexOf("/") + 1);
+            return {
+                path,
+                name,
+                isDirectory: type === "d",
+                size: Number(size ?? 0),
+                modifiedAt: mtime ?? new Date().toISOString(),
+            };
+        });
+    }
+    async watchFiles(id, path, opts, onEvent) {
+        const intervalSec = ((opts.intervalMs ?? 1000) / 1000).toFixed(3);
+        const container = this.docker.getContainer(this.containerName(id));
+        // A portable poll-based watcher in python3 (guaranteed in the base image);
+        // avoids depending on inotify-tools. Emits `<type>\t<path>` lines.
+        const cmd = `python3 -u -c ${shellEscape(WATCHER_PY)} ${shellEscape(path)} ${intervalSec}`;
+        const exec = await container.exec({
+            Cmd: ["/bin/sh", "-c", cmd],
+            AttachStdout: true,
+            AttachStderr: true,
+            Tty: false,
+        });
+        const stream = await exec.start({ hijack: true, stdin: false });
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        stderr.resume();
+        let buffer = "";
+        stdout.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            let idx;
+            while ((idx = buffer.indexOf("\n")) !== -1) {
+                const line = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 1);
+                const tab = line.indexOf("\t");
+                if (tab === -1)
+                    continue;
+                const type = line.slice(0, tab);
+                if (type === "created" || type === "modified" || type === "deleted") {
+                    onEvent({ type, path: line.slice(tab + 1) });
+                }
+            }
+        });
+        this.docker.modem.demuxStream(stream, stdout, stderr);
+        const onAbort = () => {
+            stream.destroy?.();
+        };
+        if (opts.signal.aborted)
+            onAbort();
+        else
+            opts.signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            await new Promise((resolve) => {
+                stream.on("end", resolve);
+                stream.on("close", resolve);
+                stream.on("error", () => resolve());
+            });
+        }
+        finally {
+            opts.signal.removeEventListener("abort", onAbort);
+            stdout.end();
+            stderr.end();
+        }
+    }
+    async startProcess(id, procId, command, opts) {
+        const logPath = `/tmp/hotcell-proc-${procId}.log`;
+        // `setsid` gives the process its own session + group (pgid == its pid), so we
+        // can later signal the whole tree, and it survives the exec that launched it.
+        // The inner `bash -lc` runs the user command with a login PATH like `exec`.
+        const launch = `setsid bash -lc ${shellEscape(command)} > ${shellEscape(logPath)} 2>&1 & echo $!`;
+        const { stdout, stderr, exitCode } = await this.execCapture(id, launch, {
+            cwd: opts.cwd,
+            env: opts.env,
+        });
+        const pid = Number.parseInt(stdout.trim(), 10);
+        if (exitCode !== 0 || !Number.isFinite(pid)) {
+            throw new Error(stderr.trim() || `startProcess failed (exit ${exitCode})`);
+        }
+        return { procId, pid, logPath };
+    }
+    async listProcesses(id, procs) {
+        if (procs.length === 0)
+            return [];
+        // Emit `<pid> 1` if alive, `<pid> 0` otherwise.
+        const pids = procs.map((p) => p.pid).join(" ");
+        const cmd = `for p in ${pids}; do if kill -0 "$p" 2>/dev/null; then echo "$p 1"; else echo "$p 0"; fi; done`;
+        const { stdout } = await this.execCapture(id, cmd);
+        const alive = new Map();
+        for (const line of stdout.split("\n")) {
+            const [p, state] = line.trim().split(" ");
+            if (p)
+                alive.set(Number(p), state === "1");
+        }
+        return procs.map((p) => ({
+            procId: p.procId,
+            pid: p.pid,
+            running: alive.get(p.pid) ?? false,
+        }));
+    }
+    async killProcess(id, pid, signal = "TERM") {
+        const stripped = signal.replace(/^SIG/, "");
+        // Whitelist signal names/numbers; anything else (incl. shell metacharacters)
+        // falls back to TERM so a crafted `signal` can't inject into the kill command.
+        const sig = /^[A-Z0-9]+$/.test(stripped) ? stripped : "TERM";
+        // Signal the process group first (pid == pgid via setsid), then the pid.
+        const cmd = `kill -${sig} -${pid} 2>/dev/null; kill -${sig} ${pid} 2>/dev/null; true`;
+        await this.execCapture(id, cmd);
+    }
+    async streamProcessLogs(id, logPath, opts, onData) {
+        const container = this.docker.getContainer(this.containerName(id));
+        // `-F` tolerates the logfile not existing yet (it waits for it).
+        const cmd = opts.follow
+            ? `tail -n +1 -F ${shellEscape(logPath)}`
+            : `cat ${shellEscape(logPath)}`;
+        const exec = await container.exec({
+            Cmd: ["/bin/sh", "-c", cmd],
+            AttachStdout: true,
+            AttachStderr: true,
+        });
+        const stream = await exec.start({ hijack: true, stdin: false });
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        stdout.on("data", (chunk) => onData(chunk.toString("utf8")));
+        stderr.on("data", (chunk) => onData(chunk.toString("utf8")));
+        this.docker.modem.demuxStream(stream, stdout, stderr);
+        const onAbort = () => {
+            stream.destroy?.();
+        };
+        if (opts.signal.aborted)
+            onAbort();
+        else
+            opts.signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            await new Promise((resolve) => {
+                stream.on("end", resolve);
+                stream.on("close", resolve);
+                stream.on("error", () => resolve());
+            });
+        }
+        finally {
+            opts.signal.removeEventListener("abort", onAbort);
+            stdout.end();
+            stderr.end();
+        }
+    }
+    async waitForPort(id, port, opts) {
+        const host = opts.host ?? "127.0.0.1";
+        assertHost(host);
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        const intervalSec = ((opts.intervalMs ?? 250) / 1000).toFixed(3);
+        // bash `/dev/tcp` probe loop with a millisecond deadline.
+        const cmd = `deadline=$(( $(date +%s%3N) + ${timeoutMs} )); ` +
+            `while true; do ` +
+            `if (exec 3<>/dev/tcp/${host}/${port}) 2>/dev/null; then exit 0; fi; ` +
+            `if [ "$(date +%s%3N)" -ge "$deadline" ]; then exit 1; fi; ` +
+            `sleep ${intervalSec}; ` +
+            `done`;
+        const { exitCode } = await this.execCapture(id, cmd);
+        return exitCode === 0;
+    }
+    async openTcpBridge(id, port, host) {
+        assertHost(host);
+        const container = this.docker.getContainer(this.containerName(id));
+        // Relay raw bytes to the in-container port. socat is binary-safe and handles
+        // half-close cleanly; fall back to a bash /dev/tcp bridge when socat is
+        // absent (default slim image). We run WITHOUT a TTY (Tty:false) so no pty
+        // line discipline can cook the bytes — the response is demultiplexed below
+        // to strip Docker's 8-byte stream frames, leaving a clean byte stream.
+        const relay = `if command -v socat >/dev/null 2>&1; then ` +
+            `exec socat - TCP:${host}:${port}; ` +
+            `else exec bash -c 'exec 3<>/dev/tcp/${host}/${port}; cat <&3 & cat >&3; wait'; fi`;
+        const exec = await container.exec({
+            Cmd: ["/bin/sh", "-c", relay],
+            AttachStdin: true,
+            AttachStdout: true,
+            AttachStderr: true,
+            Tty: false,
+        });
+        const hijacked = await exec.start({ hijack: true, stdin: true });
+        // Demux the multiplexed output into a clean readable; drain stderr.
+        const outbound = new PassThrough();
+        const errSink = new PassThrough();
+        errSink.resume();
+        this.docker.modem.demuxStream(hijacked, outbound, errSink);
+        // Present a single duplex: writes -> exec stdin, reads <- demuxed stdout.
+        const writable = hijacked;
+        const stream = Duplex.from({ readable: outbound, writable });
+        return {
+            stream,
+            close() {
+                hijacked.destroy?.();
+                outbound.destroy();
+            },
+        };
+    }
+    async openTerminal(id, opts) {
+        const container = this.docker.getContainer(this.containerName(id));
+        // A real PTY: Tty:true makes Docker allocate a pseudo-terminal, so the output
+        // is raw (no 8-byte stream framing) and line discipline / control chars work.
+        // Prefer an interactive login bash, falling back to sh on minimal images.
+        const exec = await container.exec({
+            Cmd: [
+                "/bin/sh",
+                "-c",
+                "if command -v bash >/dev/null 2>&1; then exec bash -l; else exec sh -l; fi",
+            ],
+            AttachStdin: true,
+            AttachStdout: true,
+            AttachStderr: true,
+            Tty: true,
+            WorkingDir: opts.cwd ?? "/workspace",
+            Env: Object.entries(opts.env ?? {}).map(([k, v]) => `${k}=${v}`),
+        });
+        const stream = (await exec.start({
+            hijack: true,
+            stdin: true,
+            // Tell dockerode this is a TTY stream so it doesn't try to demux frames.
+            Tty: true,
+        }));
+        if (opts.cols && opts.rows) {
+            await exec.resize({ w: opts.cols, h: opts.rows }).catch(() => { });
+        }
+        return {
+            stream,
+            resize(cols, rows) {
+                exec.resize({ w: cols, h: rows }).catch(() => { });
+            },
+            close() {
+                stream.destroy?.();
+            },
+        };
+    }
+    async createBackup(id, tarPath) {
+        const container = this.docker.getContainer(this.containerName(id));
+        // getArchive streams a tar of the path's contents (entries rooted at
+        // `workspace/...`) straight from the container fs over the Docker socket.
+        const stream = (await container.getArchive({
+            path: "/workspace",
+        }));
+        await mkdir(dirname(tarPath), { recursive: true });
+        let bytes = 0;
+        stream.on("data", (chunk) => {
+            bytes += chunk.length;
+        });
+        await pipeline(stream, createWriteStream(tarPath));
+        return { bytes };
+    }
+    async restoreBackup(id, tarPath) {
+        // Clear the existing workspace so the restore is a replacement, not a merge.
+        await this.execCapture(id, "find /workspace -mindepth 1 -maxdepth 1 -exec rm -rf {} +");
+        const container = this.docker.getContainer(this.containerName(id));
+        // The tar entries are rooted at `workspace/`, so extract at `/`.
+        await container.putArchive(createReadStream(tarPath), { path: "/" });
+    }
+    async stats(id) {
+        const container = this.docker.getContainer(this.containerName(id));
+        // `stream:false` makes the daemon take two samples ~1s apart and populate
+        // `precpu_stats`, so the CPU% delta is correct from a single call (a
+        // `one-shot` read would leave precpu zero and inflate CPU%). Depending on the
+        // dockerode version this resolves either to a parsed object or a one-shot
+        // stream, so handle both.
+        const result = await container.stats({ stream: false });
+        const raw = isReadable(result)
+            ? await collectJson(result)
+            : result;
+        return normalizeStats(raw);
+    }
+    async destroy(id) {
+        const container = this.docker.getContainer(this.containerName(id));
+        try {
+            await container.remove({ force: true });
+        }
+        catch (err) {
+            // Already gone is fine; rethrow anything else.
+            if (!isNotFound(err))
+                throw err;
+        }
+        // Drop the persistent volume too — destroy is irreversible.
+        try {
+            await this.docker.getVolume(this.volumeName(id)).remove({ force: true });
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                throw err;
+        }
+    }
+}
+/** Duck-type check for a Node readable stream. */
+function isReadable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.pipe === "function");
+}
+/** Read a readable stream to completion and JSON.parse its contents. */
+async function collectJson(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8").trim() || "{}");
+}
+/** Normalize Docker's raw stats JSON into our cross-driver SandboxStats shape. */
+function normalizeStats(s) {
+    const cpu = s.cpu_stats ?? {};
+    const precpu = s.precpu_stats ?? {};
+    const cpuDelta = (cpu.cpu_usage?.total_usage ?? 0) - (precpu.cpu_usage?.total_usage ?? 0);
+    const systemDelta = (cpu.system_cpu_usage ?? 0) - (precpu.system_cpu_usage ?? 0);
+    const onlineCpus = cpu.online_cpus || cpu.cpu_usage?.percpu_usage?.length || 1;
+    let cpuPercent = 0;
+    if (systemDelta > 0 && cpuDelta > 0) {
+        cpuPercent = (cpuDelta / systemDelta) * onlineCpus * 100;
+    }
+    const mem = s.memory_stats ?? {};
+    // Exclude reclaimable page cache where the runtime breaks it out (cgroup v2
+    // reports `inactive_file`; v1 reports `cache`).
+    const cache = mem.stats?.inactive_file ?? mem.stats?.cache ?? 0;
+    const memBytes = Math.max(0, (mem.usage ?? 0) - cache);
+    let netRxBytes = 0;
+    let netTxBytes = 0;
+    for (const net of Object.values(s.networks ?? {})) {
+        netRxBytes += net.rx_bytes ?? 0;
+        netTxBytes += net.tx_bytes ?? 0;
+    }
+    return {
+        cpuPercent,
+        cpuTotalUsageNs: cpu.cpu_usage?.total_usage ?? 0,
+        onlineCpus,
+        memBytes,
+        memLimitBytes: mem.limit ?? 0,
+        netRxBytes,
+        netTxBytes,
+        pids: s.pids_stats?.current ?? 0,
+        sampledAt: new Date().toISOString(),
+    };
+}
+function isNotFound(err) {
+    return statusCode(err) === 404;
+}
+function isConflict(err) {
+    return statusCode(err) === 409;
+}
+function statusCode(err) {
+    return typeof err === "object" && err !== null && "statusCode" in err
+        ? err.statusCode
+        : undefined;
+}
+/**
+ * Translate sandbox resource limits into Docker `HostConfig` cgroup fields.
+ * Omits any limit that's 0/undefined so it stays unlimited. `cpus` → `NanoCpus`
+ * (1 core = 1e9), `memoryMb` → `Memory` bytes, `pidsLimit` → `PidsLimit`.
+ */
+function resourceHostConfig(limits) {
+    const cfg = {};
+    if (limits?.memoryMb && limits.memoryMb > 0) {
+        cfg.Memory = Math.round(limits.memoryMb * 1024 * 1024);
+    }
+    if (limits?.cpus && limits.cpus > 0) {
+        cfg.NanoCpus = Math.round(limits.cpus * 1e9);
+    }
+    if (limits?.pidsLimit && limits.pidsLimit > 0) {
+        cfg.PidsLimit = Math.round(limits.pidsLimit);
+    }
+    return cfg;
+}
+/**
+ * Reject a host that isn't a plain IP/hostname before it's interpolated into a
+ * `/dev/tcp/<host>/...` redirect or `socat TCP:<host>` arg, where shell quoting
+ * is awkward. Allows letters, digits, `.`, `-`, `_`, and `:` (IPv6) only.
+ */
+function assertHost(host) {
+    if (!/^[A-Za-z0-9._:-]+$/.test(host)) {
+        throw new Error(`invalid host: ${host}`);
+    }
+}
+/**
+ * Poll-based recursive file watcher (python3, no inotify dependency). Snapshots
+ * mtimes under argv[1] every argv[2] seconds and prints `<type>\t<path>` lines
+ * for created/modified/deleted files. Contains no single quotes so it survives
+ * single-quote shell escaping.
+ */
+const WATCHER_PY = [
+    "import os,sys,time",
+    "path=sys.argv[1]; interval=float(sys.argv[2])",
+    "def snap():",
+    "    s={}",
+    "    for root,_,files in os.walk(path):",
+    "        for n in files:",
+    "            p=os.path.join(root,n)",
+    "            try: s[p]=os.path.getmtime(p)",
+    "            except OSError: pass",
+    "    return s",
+    "prev=snap()",
+    "while True:",
+    "    time.sleep(interval)",
+    "    cur=snap()",
+    '    for p in cur:',
+    '        if p not in prev: print("created\\t"+p,flush=True)',
+    '        elif cur[p]!=prev[p]: print("modified\\t"+p,flush=True)',
+    '    for p in prev:',
+    '        if p not in cur: print("deleted\\t"+p,flush=True)',
+    "    prev=cur",
+].join("\n");
+//# sourceMappingURL=container.js.map