@zhivex-ai/sandbox-docker 0.0.1 → 0.2.1

package/README.md

@@ -1,3 +1,91 @@
 # @zhivex-ai/sandbox-docker
 
-Placeholder release. See https://github.com/Zhivex/zhivex-ai-sdk
+Experimental reference `executionEnvironment` for Zhivex workspace agents. Each agent run gets its own Docker container. The package stays separate from `@zhivex-ai/core` and `@zhivex-ai/sdk` so the shared contract does not depend on a container engine.
+
+This is a container boundary you run yourself. It is not a hosted sandbox, a microVM, or a local Unix fallback.
+
+## Install
+
+```bash
+bun add @zhivex-ai/sandbox-docker @zhivex-ai/sdk
+```
+
+The Docker daemon must be reachable at `/var/run/docker.sock`, or pass `socketPath`. The default image is `alpine:3.21`. `packages/sandbox-docker/docker/Dockerfile` is an optional image if you want uid `1000` instead of the default numeric user `65534:65534`.
+
+## Usage
+
+```ts
+import { Agent } from "@zhivex-ai/sdk";
+import { createDockerSandboxEnvironment, createDockerSandboxTools } from "@zhivex-ai/sandbox-docker";
+
+const sandbox = createDockerSandboxEnvironment({
+  workspace: {
+    id: "repo",
+    files: [{ path: "README.md", contents: "# workspace\n" }],
+    directories: ["src"]
+  },
+  shell: { allow: ["echo", "ls"] }
+});
+
+const agent = new Agent({
+  model,
+  executionEnvironment: sandbox,
+  tools: createDockerSandboxTools(),
+  maxSteps: 4
+});
+```
+
+`createDockerSandboxTools()` adds `sandbox_read_file`, `sandbox_write_file`, `sandbox_list`, and `sandbox_exec`. Writes and shell commands require interrupt approval. The tools run only against the session the runtime acquired for that run.
+
+Pass the same environment object, or the same Docker client plus lease and snapshot stores, when the application resumes a run. The runtime releases the session at the end of every invocation. `waiting_approval`, `suspended`, `running`, `queued`, and `cancel_requested` keep the container and refresh the workspace snapshot. `completed`, `failed`, `cancelled`, and `timed_out` remove the container, the snapshot, and any allowlist network.
+
+A changed environment id, workspace id, or manifest fingerprint throws `ConflictError`. An expired lease is removed and is not replaced with an empty workspace. A lost container is restored from the workspace tar when a snapshot exists.
+
+## Security defaults
+
+`dockerSandboxSecurityDefaults` is the reference profile:
+
+| Control | Default |
+| --- | --- |
+| Image | `alpine:3.21` |
+| User | `65534:65534` (numeric, non-root; root is rejected) |
+| Workspace | `/workspace` tmpfs, files and directories declared up front |
+| Network | `none` |
+| Root filesystem | read-only |
+| Memory | 256 MiB, swap disabled |
+| CPU | 0.5 |
+| Process limit | 64 |
+| Capabilities | drop `ALL`, `no-new-privileges` |
+| Shell | denied until an allowlist or `shell: "allow"` is set |
+| Command timeout | 10 seconds |
+| Output cap | 1 MiB per stdout and stderr |
+| File cap | 1 MiB |
+| Workspace cap | 64 MiB |
+| Lease | 15 minutes |
+| Snapshot | workspace tar |
+| Symlinks | not followed; `realpath` must stay inside `/workspace` |
+| Undeclared tools | denied |
+| Inherited `process.env` | none |
+| Local Unix fallback | not implemented |
+
+Host source trees are copied from `workspace.source.include`. They are not bind-mounted. Each file is measured before it is read, and copying stops when the file or workspace budget is exhausted. Shell commands are argv only: a bare name or an executable in `/bin` or `/usr/bin`, with no `..` and no leading `-`. Each command runs under `/usr/bin/timeout -s KILL` in its own session, and the runtime kills that process group when the command returns, times out, is truncated, or is cancelled.
+
+Docker's archive API does not read or write the workspace tmpfs on a read-only root filesystem. Copies in and out of `/workspace` therefore use `/bin/tar` inside the container. The default `alpine:3.21` image provides that binary.
+
+## Network allowlist
+
+`network: { mode: "allowlist", allowedDomains, allowedPorts }` is opt-in. The container joins an internal Docker network and receives `HTTP_PROXY` / `HTTPS_PROXY` aimed at an in-process CONNECT proxy. The proxy allows only the declared public DNS names and ports. It resolves each CONNECT target twice and connects to the checked address. Private, loopback, link-local, metadata, documentation, and non-global addresses are rejected unless `allowPrivateNetworks` is set, including IPv4-mapped, IPv4-compatible, NAT64, and 6to4 forms.
+
+Clients that open sockets directly have no external route. Proxy-aware clients are filtered. The proxy process shares the host network namespace, so a container that can reach the gateway address can also attempt other ports on that gateway. Treat the allowlist as a fail-closed filter for proxy traffic, not as a microVM boundary. Each proxy also enforces connection, in-flight DNS, request, byte, idle, and tunnel-lifetime quotas (`allowlistProxyQuotaDefaults`). Those quotas are part of the manifest fingerprint. The default remains `network: { mode: "deny" }`.
+
+## Snapshots
+
+The workspace lives on a tmpfs, so `docker commit` does not contain it. The default snapshot is a tar of `/workspace`. `snapshot: "docker-commit"` also commits an image and still stores the tar, which is what restore uses. Replacing a snapshot keeps every previous image id until that image is deleted, and a later snapshot or sweep retries the deletion. Terminal release and lease expiry delete the image before removing the snapshot record. An image that Docker already reports as missing is treated as deleted.
+
+`sweep()` expires leases this process owns and removes only containers labeled with this environment's owner id and manifest fingerprint. Pass the same `ownerId` when several processes share one lease store and should clean up each other's orphans. A different owner or fingerprint is left alone.
+
+CPU quota, PID limit, and the numeric user are part of the manifest fingerprint. Resume fails when those limits change, and a running container whose Docker HostConfig disagrees with the current limits is rejected. File snapshot keys reject run ids `.` and `..`.
+
+## Assurance
+
+`assurance: "enforced"` is the default for the real Docker client. The in-memory client used by tests and the deterministic example is a double: it refuses `assurance: "enforced"` and records `best-effort` unless you override it. `undeclaredTools: "allow"` permits other in-process tools and does not jail them.

package/dist/docker-client.d.ts

@@ -0,0 +1,92 @@
+export interface DockerPathStat {
+    name: string;
+    size: number;
+    mode: number;
+    linkTarget: string;
+}
+export interface DockerCreateSpec {
+    image: string;
+    user: string;
+    workingDir: string;
+    env: string[];
+    cmd: string[];
+    networkMode: string;
+    readonlyRootfs: boolean;
+    memoryBytes: number;
+    nanoCpus: number;
+    pidsLimit: number;
+    tmpfs: Record<string, string>;
+    labels: Record<string, string>;
+    init: boolean;
+}
+export interface DockerExecOptions {
+    cmd: string[];
+    user: string;
+    env?: string[];
+    workingDir: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    signal?: AbortSignal;
+    /** Internal kill helper must not recurse into another terminate attempt. */
+    skipTerminate?: boolean;
+    marker?: string;
+}
+export interface DockerExecResult {
+    exitCode: number;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    truncated: boolean;
+    timedOut: boolean;
+}
+export interface DockerContainerInspection {
+    Id: string;
+    State: {
+        Running: boolean;
+        Status: string;
+        OOMKilled: boolean;
+        ExitCode: number;
+    };
+    HostConfig?: {
+        NanoCpus?: number;
+        PidsLimit?: number;
+        Memory?: number;
+    };
+}
+export interface DockerListedContainer {
+    Id: string;
+    Labels: Record<string, string>;
+}
+export interface DockerClient {
+    readonly kind: "node" | "memory";
+    createContainer(spec: DockerCreateSpec): Promise<{
+        Id: string;
+    }>;
+    startContainer(id: string): Promise<void>;
+    inspectContainer(id: string): Promise<DockerContainerInspection>;
+    removeContainer(id: string): Promise<void>;
+    killContainer(id: string, signal?: string): Promise<void>;
+    listContainers(label: string): Promise<DockerListedContainer[]>;
+    putArchive(id: string, containerPath: string, tar: Uint8Array): Promise<void>;
+    getArchive(id: string, containerPath: string, maxOutputBytes?: number): Promise<{
+        tar: Uint8Array;
+        stat: DockerPathStat;
+    }>;
+    exec(id: string, options: DockerExecOptions): Promise<DockerExecResult>;
+    /** Canonicalize a container path. Callers compare it with the lexical path and refuse escapes. */
+    realpath(id: string, containerPath: string): Promise<string>;
+    commitContainer(id: string, repo: string, tag: string, labels?: Record<string, string>): Promise<{
+        Id: string;
+    }>;
+    removeImage(id: string): Promise<void>;
+    createNetwork(name: string): Promise<{
+        Id: string;
+        gateway?: string;
+    }>;
+    removeNetwork(id: string): Promise<void>;
+}
+export interface NodeDockerClientOptions {
+    socketPath?: string;
+    apiVersion?: string;
+}
+export declare const createNodeDockerClient: (options?: NodeDockerClientOptions) => DockerClient;
+//# sourceMappingURL=docker-client.d.ts.map

package/dist/docker-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-client.d.ts","sourceRoot":"","sources":["../src/docker-client.ts"],"names":[],"mappings":"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"}

package/dist/docker-client.js

@@ -0,0 +1,464 @@
+import http from "node:http";
+import { SandboxError } from "./errors.js";
+import { readMultiplexedStream } from "./stream.js";
+import { unpackTar } from "./tar.js";
+const empty = new Uint8Array();
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const TAR_EXTRACT_DEADLINE_MS = 30_000;
+const clampTimeout = (timeoutMs) => {
+    if (!Number.isFinite(timeoutMs))
+        return 1;
+    return Math.min(MAX_TIMER_DELAY_MS, Math.max(1, Math.floor(timeoutMs)));
+};
+export const createNodeDockerClient = (options = {}) => {
+    const socketPath = options.socketPath ?? "/var/run/docker.sock";
+    let apiVersion = options.apiVersion;
+    const prefix = () => `/${apiVersion}`;
+    const request = (method, requestPath, body, headers, signal) => new Promise((resolve, reject) => {
+        const payload = body ? Buffer.from(body) : undefined;
+        const req = http.request({
+            socketPath,
+            method,
+            path: requestPath,
+            headers: {
+                ...(payload ? { "Content-Type": "application/json", "Content-Length": String(payload.length) } : {}),
+                ...headers
+            },
+            signal
+        }, response => {
+            const chunks = [];
+            response.on("data", chunk => chunks.push(Buffer.from(chunk)));
+            response.on("end", () => resolve({
+                status: response.statusCode ?? 0,
+                headers: response.headers,
+                body: Buffer.concat(chunks)
+            }));
+        });
+        req.on("error", error => {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ECONNREFUSED") {
+                reject(new SandboxError("DOCKER_UNAVAILABLE", `Docker socket ${socketPath} is not available.`, { cause: error }));
+                return;
+            }
+            reject(error);
+        });
+        req.end(payload);
+    });
+    const ensureVersion = async () => {
+        if (apiVersion)
+            return;
+        const response = await request("GET", "/version");
+        if (response.status >= 300) {
+            throw new SandboxError("DOCKER_API", dockerMessage(response.body) || "Docker /version failed.");
+        }
+        const info = JSON.parse(response.body.toString("utf8"));
+        if (!info.ApiVersion || !/^\d+\.\d+$/.test(info.ApiVersion)) {
+            throw new SandboxError("DOCKER_API", "Docker /version did not report an API version.");
+        }
+        apiVersion = `v${info.ApiVersion}`;
+    };
+    const requestJson = async (method, requestPath, body, signal) => {
+        await ensureVersion();
+        const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body));
+        const response = await request(method, `${prefix()}${requestPath}`, payload, undefined, signal);
+        if (response.status === 404) {
+            throw new SandboxError("NOT_FOUND", dockerMessage(response.body) || `Docker resource was not found: ${requestPath}`);
+        }
+        if (response.status >= 300) {
+            throw new SandboxError("DOCKER_API", dockerMessage(response.body) || `Docker API ${method} ${requestPath} returned ${response.status}.`);
+        }
+        if (response.body.length === 0)
+            return undefined;
+        return JSON.parse(response.body.toString("utf8"));
+    };
+    const terminate = async (id, marker, user) => {
+        const top = await requestJson("GET", `/containers/${id}/top?ps_args=${encodeURIComponent("e -o pid,pgid,args")}`);
+        const titles = top.Titles ?? [];
+        const pidIndex = titles.findIndex(title => title.toUpperCase() === "PID");
+        const pgidIndex = titles.findIndex(title => title.toUpperCase() === "PGID");
+        const argsIndex = Math.max(0, titles.findIndex(title => /cmd|command|args/i.test(title)));
+        const groups = new Set();
+        for (const row of top.Processes ?? []) {
+            if (!(row[argsIndex] ?? "").includes(marker))
+                continue;
+            const pgid = pgidIndex === -1 ? row[pidIndex === -1 ? 0 : pidIndex] : row[pgidIndex];
+            if (!pgid || pgid === "0" || pgid === "1")
+                continue;
+            groups.add(`-${pgid}`);
+        }
+        if (!groups.size)
+            return;
+        await ensureVersion();
+        await createNodeDockerClient({ socketPath, apiVersion }).exec(id, {
+            cmd: ["/bin/kill", "-KILL", "--", ...groups],
+            user,
+            workingDir: "/",
+            timeoutMs: 2_000,
+            maxOutputBytes: 1_024,
+            skipTerminate: true
+        });
+    };
+    return {
+        kind: "node",
+        async createContainer(spec) {
+            return requestJson("POST", "/containers/create", {
+                Image: spec.image,
+                User: spec.user,
+                WorkingDir: spec.workingDir,
+                Env: spec.env,
+                Cmd: spec.cmd,
+                Labels: spec.labels,
+                HostConfig: {
+                    NetworkMode: spec.networkMode,
+                    ReadonlyRootfs: spec.readonlyRootfs,
+                    Memory: spec.memoryBytes,
+                    MemorySwap: spec.memoryBytes,
+                    NanoCpus: spec.nanoCpus,
+                    PidsLimit: spec.pidsLimit,
+                    CapDrop: ["ALL"],
+                    SecurityOpt: ["no-new-privileges:true"],
+                    Init: spec.init,
+                    Tmpfs: spec.tmpfs
+                }
+            });
+        },
+        async startContainer(id) {
+            await requestJson("POST", `/containers/${id}/start`);
+        },
+        async inspectContainer(id) {
+            return requestJson("GET", `/containers/${id}/json`);
+        },
+        async removeContainer(id) {
+            await requestJson("DELETE", `/containers/${id}?force=true`);
+        },
+        async killContainer(id, signal = "SIGKILL") {
+            await requestJson("POST", `/containers/${id}/kill?signal=${encodeURIComponent(signal)}`);
+        },
+        async listContainers(label) {
+            const filters = encodeURIComponent(JSON.stringify({ label: [label] }));
+            const listed = await requestJson("GET", `/containers/json?all=true&filters=${filters}`);
+            return listed.map(container => ({ Id: container.Id, Labels: container.Labels ?? {} }));
+        },
+        async putArchive(id, containerPath, tar) {
+            await ensureVersion();
+            const response = await request("PUT", `${prefix()}/containers/${id}/archive?path=${encodeURIComponent(containerPath)}`, tar, {
+                "Content-Type": "application/x-tar",
+                "Content-Length": String(tar.byteLength)
+            });
+            if (response.status < 300)
+                return;
+            const message = dockerMessage(response.body) || `Docker archive upload returned ${response.status}.`;
+            if (!/read-only/i.test(message))
+                throw new SandboxError("DOCKER_API", message);
+            await extractTar(socketPath, prefix(), id, containerPath, tar);
+        },
+        async getArchive(id, containerPath, maxOutputBytes = 256 * 1024 * 1024) {
+            const slash = containerPath.lastIndexOf("/");
+            const parent = slash <= 0 ? "/" : containerPath.slice(0, slash);
+            const name = containerPath.slice(slash + 1);
+            if (!name || name === "." || name === ".." || name.includes("/")) {
+                throw new SandboxError("PATH_INVALID", `Sandbox archive path ${containerPath} is not a single container path.`);
+            }
+            const archived = await this.exec(id, {
+                cmd: ["/bin/tar", "-c", "-C", parent, name],
+                user: "",
+                workingDir: "/",
+                timeoutMs: 30_000,
+                maxOutputBytes,
+                skipTerminate: true
+            });
+            if (archived.timedOut || archived.truncated) {
+                throw new SandboxError("LIMIT", "Sandbox archive exceeds the output cap.");
+            }
+            if (archived.exitCode !== 0) {
+                const detail = new TextDecoder().decode(archived.stderr).trim();
+                throw new SandboxError("NOT_FOUND", detail || `Sandbox path ${containerPath} was not found.`);
+            }
+            const entries = unpackTar(archived.stdout);
+            const root = entries.find(entry => entry.path === name);
+            return {
+                tar: archived.stdout,
+                stat: {
+                    name,
+                    size: root?.content?.byteLength ?? 0,
+                    mode: root?.mode ?? 0,
+                    linkTarget: root?.type === "symlink" ? root.linkTarget ?? "" : ""
+                }
+            };
+        },
+        async exec(id, options) {
+            const marker = options.marker ?? "";
+            const created = await requestJson("POST", `/containers/${id}/exec`, {
+                AttachStdout: true,
+                AttachStderr: true,
+                Tty: false,
+                ...(options.user ? { User: options.user } : {}),
+                WorkingDir: options.workingDir,
+                Env: options.env,
+                Cmd: options.cmd
+            });
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), clampTimeout(options.timeoutMs));
+            const onAbort = () => controller.abort();
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            let timedOut = false;
+            try {
+                const streamed = await streamExec(socketPath, prefix(), created.Id, options.maxOutputBytes, controller.signal);
+                timedOut = controller.signal.aborted && !options.signal?.aborted;
+                const inspected = await requestJson("GET", `/exec/${created.Id}/json`).catch(() => ({ ExitCode: timedOut ? 137 : 1 }));
+                if (options.signal?.aborted) {
+                    throw new SandboxError("CANCELLED", "Sandbox command was cancelled.");
+                }
+                return {
+                    exitCode: inspected.ExitCode ?? (timedOut ? 137 : 1),
+                    stdout: streamed.stdout,
+                    stderr: streamed.stderr,
+                    truncated: streamed.truncated,
+                    timedOut
+                };
+            }
+            finally {
+                clearTimeout(timer);
+                options.signal?.removeEventListener("abort", onAbort);
+                if (!options.skipTerminate && marker) {
+                    await terminate(id, marker, options.user).catch(() => undefined);
+                }
+            }
+        },
+        async realpath(id, containerPath) {
+            if (!containerPath.startsWith("/") || containerPath.includes("\0") || containerPath.length > 4096) {
+                throw new SandboxError("PATH_INVALID", "Sandbox realpath requires an absolute container path.");
+            }
+            const result = await this.exec(id, {
+                // Alpine busybox links this applet at /usr/bin/realpath. /bin/realpath is absent.
+                cmd: ["/usr/bin/realpath", containerPath],
+                user: "",
+                workingDir: "/",
+                timeoutMs: 5_000,
+                maxOutputBytes: 8_192,
+                skipTerminate: true
+            });
+            if (result.exitCode !== 0 || result.timedOut || result.truncated) {
+                throw new SandboxError("NOT_FOUND", `Sandbox path ${containerPath} was not found.`);
+            }
+            const resolved = new TextDecoder().decode(result.stdout).replace(/\n$/, "");
+            if (!resolved.startsWith("/") || resolved.includes("\0")) {
+                throw new SandboxError("PATH_INVALID", "Sandbox realpath returned an unusable path.");
+            }
+            return resolved;
+        },
+        async commitContainer(id, repo, tag, labels) {
+            return requestJson("POST", `/commit?container=${encodeURIComponent(id)}&repo=${encodeURIComponent(repo)}&tag=${encodeURIComponent(tag)}`, labels ? { Labels: labels } : undefined);
+        },
+        async removeImage(id) {
+            await requestJson("DELETE", `/images/${encodeURIComponent(id)}?force=true`);
+        },
+        async createNetwork(name) {
+            const created = await requestJson("POST", "/networks/create", {
+                Name: name,
+                Internal: true,
+                CheckDuplicate: true,
+                Labels: { "zhivex.sandbox": "1" }
+            });
+            const inspected = await requestJson("GET", `/networks/${created.Id}`);
+            return { Id: created.Id, gateway: inspected.IPAM?.Config?.[0]?.Gateway };
+        },
+        async removeNetwork(id) {
+            await requestJson("DELETE", `/networks/${id}`);
+        }
+    };
+};
+const extractTar = (socketPath, apiPrefix, id, containerPath, tar) => new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TAR_EXTRACT_DEADLINE_MS);
+    let settled = false;
+    const finish = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (error)
+            reject(error instanceof Error ? error : new Error(String(error)));
+        else
+            resolve();
+    };
+    controller.signal.addEventListener("abort", () => {
+        finish(new SandboxError("LIMIT", "Sandbox tar extract exceeded its deadline."));
+    }, { once: true });
+    const createBody = Buffer.from(JSON.stringify({
+        AttachStdin: true,
+        AttachStdout: true,
+        AttachStderr: true,
+        Tty: false,
+        Cmd: ["/bin/tar", "-x", "-C", containerPath]
+    }));
+    const create = http.request({
+        socketPath,
+        method: "POST",
+        path: `${apiPrefix}/containers/${id}/exec`,
+        headers: { "Content-Type": "application/json", "Content-Length": String(createBody.length) },
+        signal: controller.signal
+    }, response => {
+        const chunks = [];
+        response.on("data", chunk => chunks.push(Buffer.from(chunk)));
+        response.on("end", () => {
+            const body = Buffer.concat(chunks);
+            if ((response.statusCode ?? 500) >= 300) {
+                finish(new SandboxError("DOCKER_API", dockerMessage(body) || "Docker tar exec create failed."));
+                return;
+            }
+            const created = JSON.parse(body.toString("utf8"));
+            if (!created.Id) {
+                finish(new SandboxError("DOCKER_API", "Docker tar exec did not return an id."));
+                return;
+            }
+            startTarExtract(socketPath, apiPrefix, created.Id, tar, controller.signal).then(() => finish(), finish);
+        });
+    });
+    create.on("error", error => {
+        if (controller.signal.aborted)
+            finish(new SandboxError("LIMIT", "Sandbox tar extract exceeded its deadline."));
+        else
+            finish(error);
+    });
+    create.end(createBody);
+});
+const startTarExtract = (socketPath, apiPrefix, execId, tar, signal) => new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        if (error)
+            reject(error instanceof Error ? error : new Error(String(error)));
+        else
+            resolve();
+    };
+    const payload = Buffer.from(JSON.stringify({ Detach: false, Tty: false }));
+    const req = http.request({
+        socketPath,
+        method: "POST",
+        path: `${apiPrefix}/exec/${execId}/start`,
+        headers: {
+            "Content-Type": "application/json",
+            Connection: "Upgrade",
+            Upgrade: "tcp",
+            "Content-Length": String(payload.length)
+        },
+        signal
+    });
+    let upgraded;
+    const fail = (error) => {
+        upgraded?.destroy();
+        req.destroy();
+        finish(error);
+    };
+    signal.addEventListener("abort", () => fail(new SandboxError("LIMIT", "Sandbox tar extract exceeded its deadline.")), { once: true });
+    req.on("upgrade", (_response, socket) => {
+        upgraded = socket;
+        const output = [];
+        socket.on("data", chunk => output.push(Buffer.from(chunk)));
+        socket.on("error", fail);
+        socket.on("end", () => {
+            inspectExec(socketPath, apiPrefix, execId, signal).then(exitCode => {
+                if (exitCode !== 0) {
+                    fail(new SandboxError("DOCKER_API", `Sandbox tar extract exited ${exitCode}: ${Buffer.concat(output).toString("utf8").slice(0, 300)}`));
+                    return;
+                }
+                finish();
+            }).catch(fail);
+        });
+        socket.end(tar);
+    });
+    req.on("response", response => {
+        const chunks = [];
+        response.on("data", chunk => chunks.push(Buffer.from(chunk)));
+        response.on("end", () => fail(new SandboxError("DOCKER_API", dockerMessage(Buffer.concat(chunks)) || "Docker tar extract did not upgrade the connection.")));
+    });
+    req.on("error", error => {
+        if (signal.aborted)
+            fail(new SandboxError("LIMIT", "Sandbox tar extract exceeded its deadline."));
+        else
+            fail(error);
+    });
+    req.end(payload);
+});
+const inspectExec = (socketPath, apiPrefix, execId, signal) => new Promise((resolve, reject) => {
+    const req = http.request({
+        socketPath,
+        method: "GET",
+        path: `${apiPrefix}/exec/${execId}/json`,
+        signal
+    }, response => {
+        const chunks = [];
+        response.on("data", chunk => chunks.push(Buffer.from(chunk)));
+        response.on("end", () => {
+            const body = Buffer.concat(chunks);
+            if ((response.statusCode ?? 500) >= 300) {
+                reject(new SandboxError("DOCKER_API", dockerMessage(body) || "Docker exec inspect failed."));
+                return;
+            }
+            const inspected = JSON.parse(body.toString("utf8"));
+            resolve(inspected.ExitCode ?? 1);
+        });
+    });
+    req.on("error", reject);
+    req.end();
+});
+const dockerMessage = (body) => {
+    try {
+        const parsed = JSON.parse(body.toString("utf8"));
+        return parsed.message ?? "";
+    }
+    catch {
+        return body.toString("utf8").slice(0, 300);
+    }
+};
+const streamExec = (socketPath, prefix, execId, maxBytes, signal) => new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (value) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(value);
+    };
+    const fail = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        reject(error);
+    };
+    const payload = Buffer.from(JSON.stringify({ Detach: false, Tty: false }));
+    const req = http.request({
+        socketPath,
+        method: "POST",
+        path: `${prefix}/exec/${execId}/start`,
+        headers: { "Content-Type": "application/json", "Content-Length": String(payload.length) },
+        signal
+    }, response => {
+        if ((response.statusCode ?? 500) >= 300) {
+            const chunks = [];
+            response.on("data", chunk => chunks.push(Buffer.from(chunk)));
+            response.on("end", () => fail(new SandboxError("DOCKER_API", dockerMessage(Buffer.concat(chunks)) || "Docker exec start failed.")));
+            return;
+        }
+        void readMultiplexedStream(response, maxBytes).then(result => {
+            if (result.truncated)
+                response.destroy();
+            finish(result);
+        }).catch(error => {
+            if (signal.aborted)
+                finish({ stdout: empty, stderr: empty, truncated: false });
+            else
+                fail(error);
+        });
+    });
+    req.on("error", error => {
+        if (signal.aborted)
+            finish({ stdout: empty, stderr: empty, truncated: false });
+        else
+            fail(error);
+    });
+    req.end(payload);
+});
+//# sourceMappingURL=docker-client.js.map