@molecule/api-code-sandbox-docker 1.0.0

package/dist/provider.js

@@ -0,0 +1,943 @@
+/**
+ * Docker implementation of SandboxProvider.
+ *
+ * Uses the Docker Engine API via HTTP to manage containers.
+ * Each sandbox runs as an isolated Docker container with resource limits.
+ *
+ * @module
+ */
+import http from 'http';
+import { getLogger } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const logger = getLogger();
+const DEFAULT_IMAGE = 'node:22-slim';
+/**
+ * Shell-safe single-quote escaping for file paths. Prevents command injection
+ * via `$()`, backticks, or other shell metacharacters inside double quotes.
+ * @param s - The string to escape for shell use.
+ * @returns A single-quoted shell-safe string.
+ */
+function shellQuote(s) {
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+const LABEL_PREFIX = 'molecule-sandbox';
+/**
+ * [C1-1] Default sandbox network. The shared docker `bridge` has inter-container communication
+ * ENABLED, so two tenants' sandboxes can reach each other's Vite/API dev-server ports by IP —
+ * a cross-tenant info-disclosure gap for any multi-tenant app that runs untrusted code in these
+ * sandboxes. We default to a dedicated user-defined network created with ICC DISABLED
+ * (`com.docker.network.bridge.enable_icc=false`) so each tenant is isolated at L2 out of the
+ * box. Operators can override with `config.network` or `SANDBOX_DOCKER_NETWORK`; setting it to
+ * `bridge` is refused in production (see {@link DockerSandboxProvider.ensureSandboxNetwork}).
+ * Host-layer default-deny egress filtering remains a separate, operator-provisioned control.
+ */
+const DEFAULT_SANDBOX_NETWORK = 'molecule-sandbox';
+/** Default Docker daemon TCP port for a plain (unencrypted) `tcp://` endpoint. */
+const DEFAULT_DOCKER_TCP_PORT = 2375;
+/**
+ * Parse a `DOCKER_HOST`-style value into an endpoint, honoring the docker-client
+ * conventions: `unix:///path/to/docker.sock` selects a socket; `tcp://host:port`
+ * (or bare `http://host:port`) selects a plain-TCP endpoint (port defaults to
+ * {@link DEFAULT_DOCKER_TCP_PORT}). Unknown schemes (e.g. Windows `npipe://`)
+ * return `null` so the caller falls back to the unix socket.
+ *
+ * TLS-protected daemons (`tcp://…:2376`, `DOCKER_TLS_VERIFY=1`) are NOT handled —
+ * the transport is plain HTTP; front such a daemon with a local socket proxy.
+ * @param value - the raw `DOCKER_HOST` value (or any endpoint string).
+ * @returns the parsed endpoint, or `null` if it does not name a supported endpoint.
+ */
+function parseDockerHost(value) {
+    const raw = value?.trim();
+    if (!raw)
+        return null;
+    if (raw.startsWith('unix://')) {
+        return { socketPath: raw.slice('unix://'.length) || '/var/run/docker.sock' };
+    }
+    const tcp = /^(?:tcp|http):\/\/([^/:]+)(?::(\d+))?/.exec(raw);
+    if (tcp)
+        return { host: tcp[1], port: tcp[2] ? Number(tcp[2]) : DEFAULT_DOCKER_TCP_PORT };
+    return null;
+}
+/**
+ * Resolve which Docker daemon endpoint the provider connects to. Explicit config
+ * beats env; precedence:
+ * 1. `config.host`/`config.port` → plain-TCP endpoint (host defaults to
+ *    `127.0.0.1`, port to {@link DEFAULT_DOCKER_TCP_PORT});
+ * 2. `config.socketPath` → that unix socket;
+ * 3. `DOCKER_HOST` env (`tcp://` or `unix://`, the docker-client convention);
+ * 4. `DOCKER_SOCKET_PATH` env, else `/var/run/docker.sock` (the default transport).
+ * @param config - the provider configuration.
+ * @returns the resolved endpoint to spread into every Docker API request.
+ */
+function resolveDockerEndpoint(config) {
+    if (config.host !== undefined || config.port !== undefined) {
+        return { host: config.host ?? '127.0.0.1', port: config.port ?? DEFAULT_DOCKER_TCP_PORT };
+    }
+    if (config.socketPath !== undefined) {
+        return { socketPath: config.socketPath };
+    }
+    const fromEnv = parseDockerHost(process.env.DOCKER_HOST);
+    if (fromEnv)
+        return fromEnv;
+    return { socketPath: process.env.DOCKER_SOCKET_PATH ?? '/var/run/docker.sock' };
+}
+/**
+ * Parses Docker's multiplexed binary stream from a raw socket.
+ * Each frame: 8-byte header [streamType(1), 0, 0, 0, size(4 BE uint32)] + payload.
+ * Buffers partial frames across data events.
+ */
+/** Maximum single frame size in Docker multiplexed stream (50 MB). */
+const MAX_MUX_FRAME_SIZE = 50 * 1024 * 1024;
+/** Parses Docker multiplexed binary stream frames into stdout/stderr callbacks. */
+class DockerMuxParser {
+    buffer = Buffer.alloc(0);
+    stdoutCb = null;
+    stderrCb = null;
+    /**
+     * Registers a callback for stdout data events.
+     * @param cb - The callback invoked with each stdout data chunk.
+     */
+    onStdout(cb) {
+        this.stdoutCb = cb;
+    }
+    /**
+     * Registers a callback for stderr data events.
+     * @param cb - The callback invoked with each stderr data chunk.
+     */
+    onStderr(cb) {
+        this.stderrCb = cb;
+    }
+    /** Clear internal buffer (e.g. on connection close). */
+    clear() {
+        this.buffer = Buffer.alloc(0);
+    }
+    /**
+     * Feeds a buffer chunk into the parser, extracting complete frames.
+     * @param chunk - The raw data chunk from the Docker stream.
+     */
+    feed(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        while (this.buffer.length >= 8) {
+            const streamType = this.buffer[0];
+            const frameSize = this.buffer.readUInt32BE(4);
+            if (frameSize > MAX_MUX_FRAME_SIZE) {
+                this.buffer = Buffer.alloc(0);
+                throw new Error(`Docker stream frame size ${frameSize} exceeds ${MAX_MUX_FRAME_SIZE} byte limit`);
+            }
+            if (this.buffer.length < 8 + frameSize)
+                break;
+            const payload = this.buffer.subarray(8, 8 + frameSize).toString('utf-8');
+            this.buffer = this.buffer.subarray(8 + frameSize);
+            if (streamType === 1)
+                this.stdoutCb?.(payload);
+            else if (streamType === 2)
+                this.stderrCb?.(payload);
+        }
+    }
+}
+/**
+ * Retry a Docker API operation that failed with a TRANSIENT fault — a request
+ * timeout or a connection-level reset, i.e. the daemon was momentarily overwhelmed,
+ * not the request malformed. This is the fix for the observed "first cold boot of a
+ * concurrent batch dies on `Docker API timeout: POST /containers/create`" failure:
+ * a single 30 s create timeout under daemon load currently kills the whole boot.
+ *
+ * HTTP error responses (4xx/5xx) are deliberately NOT retried — those are real
+ * answers (no-such-image, name conflict), not transient network faults. Bounded
+ * attempts with linear backoff.
+ *
+ * `onRetry` is the idempotency guard: a create that TIMED OUT client-side may have
+ * still succeeded server-side, so before re-issuing it the caller can adopt the
+ * already-created resource (looked up by a unique label) instead of leaking a
+ * duplicate container. If `onRetry` returns non-null, that value is used and the
+ * operation is not re-issued.
+ *
+ * @param op - the operation to attempt.
+ * @param opts - tuning + the optional adopt-on-retry guard.
+ * @param opts.label - short operation name for log lines.
+ * @param opts.attempts - max attempts (default 3).
+ * @param opts.onRetry - adopt-an-existing-resource guard, run before each retry.
+ * @param opts.delayMs - backoff for attempt N (default `400 * N` ms).
+ * @param opts.log - optional logger for retry warnings.
+ * @returns the operation's result, or an adopted result from `onRetry`.
+ */
+export async function withTransientRetry(op, opts) {
+    const attempts = opts.attempts ?? 3;
+    const backoff = opts.delayMs ?? ((n) => 400 * n);
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await op();
+        }
+        catch (error) {
+            lastError = error;
+            const message = String(error?.message ?? error);
+            const transient = /Docker API timeout|ECONNRESET|EPIPE|socket hang ?up|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT/i.test(message);
+            if (!transient || attempt === attempts)
+                break;
+            if (opts.onRetry) {
+                const adopted = await opts.onRetry().catch(() => null);
+                if (adopted != null)
+                    return adopted;
+            }
+            opts.log?.warn(`Docker API transient failure on ${opts.label} (attempt ${attempt}/${attempts}) — retrying`, { error: message });
+            await new Promise((resolve) => setTimeout(resolve, backoff(attempt)));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Docker-based implementation of `SandboxProvider`. Each sandbox runs as an isolated
+ * Docker container with configurable CPU/memory limits. Communicates with the Docker
+ * Engine API over a Unix socket by default, or a plain-TCP endpoint when one is
+ * selected via `config.host`/`config.port` or a `DOCKER_HOST` env var.
+ */
+class DockerSandboxProvider {
+    name = 'docker';
+    /** Resolved daemon endpoint (unix socket or TCP host:port); see {@link resolveDockerEndpoint}. */
+    endpoint;
+    baseImage;
+    labelPrefix;
+    previewUrlTemplate;
+    defaultCpu;
+    defaultMemoryMB;
+    /**
+     * Explicit network from `config.network`, if any. Takes precedence over the
+     * `SANDBOX_DOCKER_NETWORK` env var — which is still read at create time when
+     * this is unset, so operators can set it after construction. See {@link resolveNetwork}.
+     */
+    configNetwork;
+    /** [C1-1] Memoize the one-time ICC-off network ensure so create() pays it only once. */
+    networkEnsured = false;
+    constructor(config = {}) {
+        this.endpoint = resolveDockerEndpoint(config);
+        this.baseImage = config.baseImage ?? DEFAULT_IMAGE;
+        this.labelPrefix = config.labelPrefix ?? LABEL_PREFIX;
+        this.previewUrlTemplate = config.previewUrlTemplate ?? 'http://localhost:{port}';
+        this.defaultCpu = config.defaultCpu ?? 1;
+        this.defaultMemoryMB = config.defaultMemoryMB ?? 1024;
+        this.configNetwork = config.network;
+    }
+    /**
+     * Resolve the Docker network to attach containers to. Precedence:
+     * `config.network` (captured at construction) → `SANDBOX_DOCKER_NETWORK` env
+     * (read here, at create time) → {@link DEFAULT_SANDBOX_NETWORK}.
+     * @returns the network name for the container's `NetworkMode`.
+     */
+    resolveNetwork() {
+        return this.configNetwork ?? process.env.SANDBOX_DOCKER_NETWORK ?? DEFAULT_SANDBOX_NETWORK;
+    }
+    /**
+     * [C1-1] Idempotently ensure the sandbox network exists with inter-container communication
+     * DISABLED, so tenants can't reach each other's containers over a shared bridge. Resolves the
+     * network via {@link resolveNetwork} (`config.network` → `SANDBOX_DOCKER_NETWORK` →
+     * {@link DEFAULT_SANDBOX_NETWORK}). The shared
+     * `bridge` has ICC enabled and gives NO isolation, so it is refused in production and only
+     * warned about elsewhere. Memoized; tolerant of "already exists" (409); non-fatal on other
+     * errors (container create surfaces a clear error if the network is genuinely missing).
+     */
+    async ensureSandboxNetwork() {
+        if (this.networkEnsured)
+            return;
+        const network = this.resolveNetwork();
+        if (network === 'bridge') {
+            if (process.env.NODE_ENV === 'production') {
+                throw new Error('Sandbox network "bridge" is forbidden in production (via SANDBOX_DOCKER_NETWORK or ' +
+                    'config.network): the shared docker bridge has inter-container communication enabled, ' +
+                    "so one tenant can reach another tenant's sandbox dev-server ports by IP (C1-1). Use " +
+                    `the isolated default ("${DEFAULT_SANDBOX_NETWORK}") or a dedicated ICC-off network.`);
+            }
+            logger.warn('Sandbox network is the shared docker "bridge" — NO cross-tenant isolation (C1-1). ' +
+                'Use the isolated default network (unset SANDBOX_DOCKER_NETWORK / config.network).');
+            this.networkEnsured = true;
+            return;
+        }
+        this.networkEnsured = true;
+        try {
+            await this.dockerApi('/networks/create', 'POST', {
+                Name: network,
+                Driver: 'bridge',
+                CheckDuplicate: true,
+                Options: { 'com.docker.network.bridge.enable_icc': 'false' },
+            });
+            logger.info('Sandbox network ready', { network });
+        }
+        catch (error) {
+            // dockerApi rejects on 409 (already exists) — that is success for our purposes.
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.includes('409') || /already exists/i.test(msg)) {
+                logger.debug('Sandbox network already exists', { network });
+            }
+            else {
+                // Non-fatal: container create surfaces a clear error if the network is truly missing.
+                logger.warn('Failed to ensure sandbox network', { network, error });
+            }
+        }
+    }
+    /**
+     * Creates a new Docker container as a sandbox with the specified resource limits,
+     * environment variables, and exposed ports (4000 for API, 5173 for Vite preview).
+     * @param config - The sandbox configuration including project ID, image, env vars, and resource limits.
+     * @returns A `Sandbox` object wrapping the created container.
+     */
+    async create(config) {
+        // [C1-1] Ensure the ICC-off isolated network exists before placing the container on it.
+        await this.ensureSandboxNetwork();
+        const cpu = config.resources?.cpu ?? this.defaultCpu;
+        const memoryMB = config.resources?.memoryMB ?? this.defaultMemoryMB;
+        const image = config.image ?? this.baseImage;
+        const env = Object.entries(config.env ?? {}).map(([k, v]) => `${k}=${v}`);
+        const labels = {
+            [`${this.labelPrefix}.projectId`]: config.projectId,
+            [`${this.labelPrefix}.managed`]: 'true',
+        };
+        // Merge any caller-supplied labels FIRST so the provider's own managed
+        // labels above (set last via reassignment below) always win — a caller can
+        // never clobber `${prefix}.managed`/`projectId`. Additive + backward
+        // compatible: existing callers pass no `labels` and are unaffected.
+        if (config.labels && typeof config.labels === 'object' && !Array.isArray(config.labels)) {
+            for (const [k, v] of Object.entries(config.labels)) {
+                if (k === `${this.labelPrefix}.projectId` || k === `${this.labelPrefix}.managed`)
+                    continue;
+                labels[k] = String(v);
+            }
+        }
+        const memoryBytes = memoryMB * 1024 * 1024;
+        const hostConfig = {
+            NanoCPUs: cpu * 1e9,
+            Memory: memoryBytes,
+            // Bound total memory+swap to 2× RAM (up to 1× RAM of swap) for transient spikes.
+            // `-1` (unlimited swap) let a tenant exhaust HOST swap — a cross-tenant DoS — since
+            // the Memory cap does not bound swap. [C1-2]
+            MemorySwap: memoryBytes * 2,
+            Init: true, // Use tini init to reap zombie processes
+            PidsLimit: 512,
+            SecurityOpt: ['no-new-privileges'],
+            CapDrop: ['ALL'],
+            // Minimal caps for the dev toolchain (file ownership + tini privilege drop).
+            // NET_ADMIN is deliberately NOT granted: it let a tenant flush in-container
+            // egress (SMTP) rules and enabled promiscuous-mode/ARP tricks on the shared
+            // bridge. Egress filtering must be enforced host-side, not in a tenant-rooted
+            // container.
+            CapAdd: ['CHOWN', 'SETGID', 'SETUID'],
+            // Bind ports to localhost only — prevents external access
+            PortBindings: {
+                '4000/tcp': [{ HostIp: '127.0.0.1', HostPort: '' }],
+                '5173/tcp': [{ HostIp: '127.0.0.1', HostPort: '' }],
+            },
+            Tmpfs: { '/tmp': 'rw,noexec,nosuid,size=256m' },
+            ReadonlyPaths: [
+                '/proc/asound',
+                '/proc/bus',
+                '/proc/fs',
+                '/proc/irq',
+                '/proc/sys',
+                '/proc/sysrq-trigger',
+            ],
+            MaskedPaths: [
+                '/proc/kcore',
+                '/proc/keys',
+                '/proc/latency_stats',
+                '/proc/sched_debug',
+                '/proc/timer_list',
+                '/proc/timer_stats',
+                '/proc/self/environ',
+                '/proc/1/environ',
+            ],
+        };
+        // [C1-1] Network: default to the dedicated ICC-OFF network (ensured above) so tenants are
+        // L2-isolated out of the box — NOT the shared `bridge`, whose inter-container communication
+        // lets one tenant reach another's dev-server ports by IP. Operators can override with
+        // `config.network` or SANDBOX_DOCKER_NETWORK (a `bridge` value is refused in production); pair
+        // it with host.docker.internal (below) + SANDBOX_DB_HOST=host.docker.internal so the sandbox
+        // still reaches its own DB. Resolved identically to ensureSandboxNetwork() above.
+        hostConfig.NetworkMode = this.resolveNetwork();
+        // Map host.docker.internal → host gateway on all networks (not added
+        // automatically on user-defined bridges). Harmless on the default bridge.
+        hostConfig.ExtraHosts = ['host.docker.internal:host-gateway'];
+        // Mount a named Docker volume at /workspace for persistent storage.
+        // Docker copies image contents (molecule/, node_modules/) into empty volumes.
+        if (config.volumeName) {
+            labels[`${this.labelPrefix}.volumeName`] = config.volumeName;
+            hostConfig.Binds = [`${config.volumeName}:/workspace`];
+        }
+        const body = {
+            Image: image,
+            Env: env,
+            Labels: labels,
+            HostConfig: hostConfig,
+            ExposedPorts: {
+                '4000/tcp': {},
+                '5173/tcp': {},
+            },
+        };
+        // Retry a transient create timeout (daemon momentarily overwhelmed under
+        // concurrent boots) instead of failing the whole sandbox boot. The onRetry
+        // guard adopts a container a timed-out create may have already made — keyed on
+        // the unique volumeName label — so a retry never leaks a duplicate.
+        const createRes = (await withTransientRetry(
+        // 120 s: creating a container with a fresh named volume copies the image's
+        // /workspace (molecule dist + node_modules, multi-GB) into the volume —
+        // measured at 33 s+ against the current base image, past the default 30 s.
+        () => this.dockerApi('/containers/create', 'POST', body, 120_000), {
+            label: 'containers/create',
+            log: logger,
+            onRetry: config.volumeName
+                ? async () => await this.findContainerIdByLabel(`${this.labelPrefix}.volumeName`, config.volumeName).then((id) => (id ? { Id: id } : null))
+                : undefined,
+        }));
+        return this.buildSandbox(createRes.Id, config.projectId);
+    }
+    /**
+     * Finds the id of a managed container by an exact `label=value` match. Used by
+     * the create-retry adoption guard to detect a container a timed-out create may
+     * have already produced (keyed on the unique volumeName label), so a retry adopts
+     * it rather than leaking a duplicate.
+     * @param key - the full label key (e.g. `molecule-sandbox.volumeName`).
+     * @param value - the exact label value to match.
+     * @returns the matching container id, or `null` if none exists.
+     */
+    async findContainerIdByLabel(key, value) {
+        const filters = JSON.stringify({ label: [`${key}=${value}`] });
+        const containers = (await this.dockerApi(`/containers/json?all=true&filters=${encodeURIComponent(filters)}`));
+        return Array.isArray(containers) && containers[0]?.Id ? containers[0].Id : null;
+    }
+    /**
+     * Retrieves an existing sandbox by its Docker container ID.
+     * @param id - The Docker container ID.
+     * @returns A `Sandbox` wrapping the container, or `null` if the container does not exist.
+     */
+    async get(id) {
+        try {
+            const info = (await this.dockerApi(`/containers/${id}/json`));
+            const projectId = info.Config.Labels[`${this.labelPrefix}.projectId`] ?? '';
+            // Derive the real status from Docker's container state rather than
+            // hardcoding 'stopped'. Otherwise GET /sandbox/status reports a live
+            // container as stopped, and the status handler syncs that bogus state
+            // back into the DB — corrupting sandboxStatus and stalling the build.
+            const status = info.State?.Running ? 'running' : 'stopped';
+            return this.buildSandbox(info.Id, projectId, status);
+        }
+        catch (error) {
+            logger.debug('Failed to get sandbox container', { id, error });
+            return null;
+        }
+    }
+    /**
+     * Lists all sandbox containers managed by this provider (filtered by the `managed=true` label).
+     * @param _userId - Reserved for future per-user filtering; currently returns all managed containers.
+     * @returns An array of `Sandbox` objects for each managed container.
+     */
+    async list(_userId) {
+        const filters = JSON.stringify({
+            label: [`${this.labelPrefix}.managed=true`],
+        });
+        const containers = (await this.dockerApi(`/containers/json?all=true&filters=${encodeURIComponent(filters)}`));
+        return containers.map((c) => this.buildSandbox(c.Id, c.Labels[`${this.labelPrefix}.projectId`] ?? '', c.State === 'running' ? 'running' : 'stopped'));
+    }
+    /**
+     * Force-removes a Docker container by ID and its associated volume (if any).
+     * Silently succeeds if already removed.
+     * @param id - The Docker container ID to destroy.
+     */
+    async destroy(id) {
+        // Read volume name from container labels before removing
+        let volumeName;
+        try {
+            const info = (await this.dockerApi(`/containers/${id}/json`));
+            volumeName = info.Config.Labels[`${this.labelPrefix}.volumeName`];
+        }
+        catch (_error) {
+            // Container may already be gone — reading labels is best-effort; destroy proceeds regardless
+        }
+        try {
+            await this.dockerApi(`/containers/${id}?force=true`, 'DELETE');
+        }
+        catch (error) {
+            logger.debug('Failed to destroy sandbox container (may already be removed)', { id, error });
+        }
+        // Clean up the associated volume
+        if (volumeName) {
+            try {
+                await this.dockerApi(`/volumes/${volumeName}`, 'DELETE');
+                logger.debug('Removed sandbox volume', { volumeName });
+            }
+            catch (error) {
+                logger.debug('Failed to remove sandbox volume (may already be removed)', {
+                    volumeName,
+                    error,
+                });
+            }
+        }
+    }
+    /**
+     * Builds a `Sandbox` object that wraps a Docker container with methods for
+     * start/stop/exec/file operations. All file operations are implemented via `docker exec`.
+     * @param containerId - The Docker container ID.
+     * @param _projectId - The project ID label (stored for metadata reference).
+     * @param initialStatus - The container's current status, derived from Docker
+     *   state by the caller (`get`/`list`). Defaults to 'stopped' for callers that
+     *   create a brand-new (not-yet-started) container.
+     * @returns A `Sandbox` with lifecycle and file system methods bound to the container.
+     */
+    buildSandbox(containerId, _projectId, initialStatus = 'stopped') {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const provider = this;
+        return {
+            id: containerId,
+            status: initialStatus,
+            previewUrl: provider.previewUrlTemplate.replace(/\{port\}/g, '5173'),
+            async start() {
+                // 120 s: on graphdriver storage the image→empty-volume copy happens at
+                // START (not create), so the first start pays the same multi-GB copy the
+                // create path does under the containerd snapshotter.
+                await provider.dockerApi(`/containers/${containerId}/start`, 'POST', undefined, 120_000);
+                this.status = 'running';
+            },
+            async stop() {
+                await provider.dockerApi(`/containers/${containerId}/stop`, 'POST');
+                this.status = 'stopped';
+            },
+            async sleep() {
+                await provider.dockerApi(`/containers/${containerId}/stop`, 'POST');
+                this.status = 'sleeping';
+            },
+            async wake() {
+                // Same 120 s rationale as start() — a first-ever start pays the volume copy.
+                await provider.dockerApi(`/containers/${containerId}/start`, 'POST', undefined, 120_000);
+                this.status = 'running';
+            },
+            async exec(command, opts) {
+                // Wrap the command in a timeout if specified to enforce time limits
+                const timeoutMs = opts?.timeout;
+                // Use single-quote shell escaping — JSON.stringify produces double quotes which
+                // still allow $(), backtick, and ! expansion inside sh -c.
+                const shellQuote = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+                const wrappedCommand = timeoutMs
+                    ? `timeout ${Math.ceil(timeoutMs / 1000)} sh -c ${shellQuote(command)}`
+                    : command;
+                const attempt = async () => {
+                    const execCreate = (await provider.dockerApi(`/containers/${containerId}/exec`, 'POST', {
+                        Cmd: ['sh', '-c', wrappedCommand],
+                        AttachStdout: true,
+                        AttachStderr: true,
+                        WorkingDir: opts?.cwd ?? '/workspace',
+                        Env: opts?.env ? Object.entries(opts.env).map(([k, v]) => `${k}=${v}`) : undefined,
+                    }));
+                    const rawBuf = await provider.dockerApiRaw(`/exec/${execCreate.Id}/start`, 'POST', {
+                        Detach: false,
+                        Tty: false,
+                    });
+                    // Docker multiplexed stream: each frame has an 8-byte header
+                    // [stream_type(1), 0, 0, 0, size(4 bytes big-endian)] + payload
+                    const stdoutChunks = [];
+                    const stderrChunks = [];
+                    let offset = 0;
+                    while (offset + 8 <= rawBuf.length) {
+                        const streamType = rawBuf[offset];
+                        const frameSize = rawBuf.readUInt32BE(offset + 4);
+                        offset += 8;
+                        const end = Math.min(offset + frameSize, rawBuf.length);
+                        const payload = rawBuf.subarray(offset, end);
+                        if (streamType === 2) {
+                            stderrChunks.push(payload);
+                        }
+                        else {
+                            stdoutChunks.push(payload);
+                        }
+                        offset = end;
+                    }
+                    // The attach stream ending does NOT mean the command finished: a
+                    // daemon under I/O load can FIN the stream early, and Node resolves
+                    // the partial body as a normal 'end'. Trusting it returned truncated
+                    // stdout + a null ExitCode (Docker reports null while the process
+                    // runs) that callers took as success — a scaffold `npm install` once
+                    // "completed" in seconds while npm kept installing for 9 more
+                    // minutes. Inspect is authoritative: if the process is still
+                    // running, poll until it actually exits before reporting.
+                    const inspectExec = async () => (await provider.dockerApi(`/exec/${execCreate.Id}/json`));
+                    let inspectRes = await inspectExec();
+                    if (inspectRes.Running) {
+                        // The in-container `timeout` wrapper bounds the command itself when
+                        // opts.timeout is set; +30s covers signal/reap latency. Without a
+                        // caller timeout, cap the wait at the same 10 min as the stream.
+                        const deadline = Date.now() + (timeoutMs ? timeoutMs + 30_000 : 600_000);
+                        while (inspectRes.Running && Date.now() < deadline) {
+                            await new Promise((resolve) => setTimeout(resolve, 2000));
+                            inspectRes = await inspectExec();
+                        }
+                    }
+                    return {
+                        stdout: Buffer.concat(stdoutChunks).toString(),
+                        stderr: Buffer.concat(stderrChunks).toString(),
+                        // -1 = indeterminate: still running at deadline (or Docker gave no
+                        // code). Distinct from any real shell exit status (0-255) so
+                        // callers can tell "unfinished/unknown" from "failed".
+                        exitCode: inspectRes.ExitCode ?? -1,
+                    };
+                };
+                try {
+                    return await attempt();
+                }
+                catch (error) {
+                    // A stopped/hibernated container returns Docker 409 "is not running".
+                    // This happens when the auto-hibernation loop sleeps a sandbox that is
+                    // actually still in use (e.g. a long agentic turn, or a brief race at
+                    // turn start). Surfacing it as a raw failure makes every file tool
+                    // error out mid-build. Instead, transparently start the container and
+                    // retry once so the exec succeeds. Any other error is rethrown.
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (/is not running|\b409\b/.test(message)) {
+                        try {
+                            // Same 120 s rationale as start() — a first-ever start pays the volume copy.
+                            await provider.dockerApi(`/containers/${containerId}/start`, 'POST', undefined, 120_000);
+                        }
+                        catch (_error) {
+                            // 304 (already started) or a genuine start failure — let the retry
+                            // below surface the real error if the container is truly gone.
+                        }
+                        return await attempt();
+                    }
+                    throw error;
+                }
+            },
+            async readFile(path) {
+                const result = await this.exec(`cat ${shellQuote(path)}`);
+                if (result.exitCode !== 0)
+                    throw new Error(t('codeSandbox.docker.error.readFailed', { path, error: result.stderr }, { defaultValue: `Failed to read ${path}: ${result.stderr}` }));
+                return result.stdout;
+            },
+            async writeFile(path, content) {
+                const b64 = Buffer.from(content).toString('base64');
+                const qp = shellQuote(path);
+                const failIfError = (result) => {
+                    if (result.exitCode !== 0)
+                        throw new Error(t('codeSandbox.docker.error.writeFailed', { path, error: result.stderr }, { defaultValue: `Failed to write ${path}: ${result.stderr}` }));
+                };
+                // A single `echo '<b64>' | base64 -d` command is passed as ONE argument to
+                // `sh -c`, which Linux caps at MAX_ARG_STRLEN (128KB). Any file whose base64
+                // exceeds that — i.e. content over ~96KB (a large component, data file, or
+                // migration) — would E2BIG and the write would FAIL. Split the base64 into
+                // sub-limit chunks: the first (with mkdir) truncates, the rest append. Each
+                // chunk is a multiple of 4 base64 chars (= 3 decoded bytes) so it decodes
+                // cleanly on its own and the bytes concatenate exactly. Small files (base64
+                // ≤ one chunk, ~45KB raw) stay a single exec — no extra round-trips.
+                const CHUNK = 60_000;
+                failIfError(await this.exec(`mkdir -p "$(dirname ${qp})" && echo ${shellQuote(b64.slice(0, CHUNK))} | base64 -d > ${qp}`));
+                for (let i = CHUNK; i < b64.length; i += CHUNK) {
+                    failIfError(await this.exec(`echo ${shellQuote(b64.slice(i, i + CHUNK))} | base64 -d >> ${qp}`));
+                }
+            },
+            async readDir(path) {
+                // Append trailing slash so ls follows symlinks (e.g. /workspace -> /sandbox/project)
+                const dirPath = path.endsWith('/') ? path : `${path}/`;
+                // NO pipeline here: `ls … | tail -n +2` reported TAIL's exit code (always 0), which
+                // silently defeated the missing-dir check below — verified live in the sandbox image
+                // (`sh -c "ls /nonexistent/ | tail -n +2"` exits 0; without the pipe, 2). The `total`
+                // header line tail used to drop is filtered in JS instead.
+                const result = await this.exec(`ls -la --time-style=+%s ${shellQuote(dirPath)}`);
+                // A nonexistent directory must THROW (like readFile), never return [] — an empty
+                // list reads as "the directory exists and is empty", and an AI executor building
+                // on that spent a whole turn theorizing about "virtual" files that were never there.
+                if (result.exitCode !== 0)
+                    throw new Error(t('codeSandbox.docker.error.readDirFailed', { path, error: result.stderr }, { defaultValue: `Failed to list ${path}: ${result.stderr}` }));
+                return result.stdout
+                    .trim()
+                    .split('\n')
+                    .filter(Boolean)
+                    .filter((line) => !/^total\s/.test(line)) // ls's summary header (was `tail -n +2`)
+                    .filter((line) => {
+                    // Skip . and .. entries
+                    const name = line.split(/\s+/).slice(6).join(' ');
+                    return name !== '.' && name !== '..';
+                })
+                    .map((line) => {
+                    const parts = line.split(/\s+/);
+                    const isDir = line.startsWith('d');
+                    const isSymlink = line.startsWith('l');
+                    const size = parseInt(parts[4] ?? '0', 10);
+                    const rawName = parts.slice(6).join(' ');
+                    // Symlinks show as "name -> target" in ls -la
+                    const arrowIdx = rawName.indexOf(' -> ');
+                    const name = isSymlink && arrowIdx !== -1 ? rawName.slice(0, arrowIdx) : rawName;
+                    const symlinkTarget = isSymlink && arrowIdx !== -1 ? rawName.slice(arrowIdx + 4) : undefined;
+                    return {
+                        name,
+                        type: isDir ? 'directory' : 'file',
+                        size: isDir ? undefined : size,
+                        ...(symlinkTarget ? { symlinkTarget } : {}),
+                    };
+                });
+            },
+            async deleteFile(path) {
+                const result = await this.exec(`rm -rf ${shellQuote(path)}`);
+                if (result.exitCode !== 0)
+                    throw new Error(t('codeSandbox.docker.error.deleteFailed', { path, error: result.stderr }, { defaultValue: `Failed to delete ${path}: ${result.stderr}` }));
+            },
+            getPreviewUrl(port) {
+                // Replace ALL {port} occurrences — the template may use it more than once
+                // (e.g. a per-sandbox subdomain `sb-{port}.preview.localhost:{port}`).
+                return provider.previewUrlTemplate.replace(/\{port\}/g, String(port ?? 5173));
+            },
+            async spawn(command, opts) {
+                const execCreate = (await provider.dockerApi(`/containers/${containerId}/exec`, 'POST', {
+                    Cmd: ['sh', '-c', command],
+                    AttachStdin: true,
+                    AttachStdout: true,
+                    AttachStderr: true,
+                    Tty: false,
+                    WorkingDir: opts?.cwd ?? '/workspace',
+                    Env: opts?.env ? Object.entries(opts.env).map(([k, v]) => `${k}=${v}`) : undefined,
+                }));
+                const socket = await provider.dockerExecUpgrade(execCreate.Id);
+                const parser = new DockerMuxParser();
+                let closeCb = null;
+                // Kill idle spawn sockets after 10 minutes to prevent descriptor leaks
+                socket.setTimeout(600_000);
+                socket.on('timeout', () => {
+                    socket.destroy();
+                });
+                socket.on('data', (chunk) => {
+                    try {
+                        parser.feed(chunk);
+                    }
+                    catch (err) {
+                        logger.debug('Spawn parser error, destroying socket', {
+                            error: err instanceof Error ? err.message : err,
+                        });
+                        socket.destroy();
+                    }
+                });
+                socket.on('close', () => {
+                    parser.clear();
+                    closeCb?.();
+                });
+                socket.on('error', (err) => {
+                    logger.debug('Spawn socket error', { error: err.message });
+                    parser.clear();
+                    closeCb?.();
+                });
+                return {
+                    write(data) {
+                        if (!socket.destroyed)
+                            socket.write(data);
+                    },
+                    onStdout(cb) {
+                        parser.onStdout(cb);
+                    },
+                    onStderr(cb) {
+                        parser.onStderr(cb);
+                    },
+                    onClose(cb) {
+                        closeCb = cb;
+                    },
+                    kill() {
+                        if (!socket.destroyed)
+                            socket.destroy();
+                    },
+                };
+            },
+            onFileChange(_cb) {
+                let active = true;
+                const poll = async () => {
+                    while (active) {
+                        await new Promise((r) => setTimeout(r, 2000));
+                    }
+                };
+                poll().catch(() => { });
+                return () => {
+                    active = false;
+                };
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Volume management
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a named Docker volume. No-op if it already exists.
+     * @param name - The Docker volume name to create.
+     */
+    async createVolume(name) {
+        try {
+            await this.dockerApi('/volumes/create', 'POST', { Name: name });
+        }
+        catch (error) {
+            // 409 Conflict means the volume already exists — idempotent success
+            if (error instanceof Error && error.message.includes('409'))
+                return;
+            throw error;
+        }
+    }
+    /**
+     * Remove a named Docker volume. Silently succeeds if already removed.
+     * @param name - The Docker volume name to remove.
+     */
+    async removeVolume(name) {
+        try {
+            await this.dockerApi(`/volumes/${name}`, 'DELETE');
+        }
+        catch (error) {
+            logger.debug('Failed to remove volume', { name, error });
+        }
+    }
+    /**
+     * Check if a named Docker volume exists.
+     * @param name - The Docker volume name to check.
+     * @returns `true` if the volume exists, `false` otherwise.
+     */
+    async volumeExists(name) {
+        try {
+            await this.dockerApi(`/volumes/${name}`);
+            return true;
+        }
+        catch (_error) {
+            // 404 means the volume does not exist — that is the expected "false" result
+            return false;
+        }
+    }
+    /**
+     * Makes an HTTP request to the Docker Engine API via the Unix socket.
+     * @param path - The API endpoint path (e.g. `/containers/create`).
+     * @param method - The HTTP method (defaults to `'GET'`).
+     * @param body - Optional JSON request body.
+     * @param timeoutMs - Request timeout (default 30 s). Container create/start
+     *   pass a longer one: the daemon populates a fresh named volume from the
+     *   image's contents during those calls, which scales with image size — a
+     *   multi-GB `/workspace` reliably exceeds 30 s, and a client-side timeout on
+     *   a create that succeeds server-side leaks a duplicate container.
+     * @returns The parsed JSON response, or raw text for non-JSON responses.
+     */
+    async dockerApi(path, method = 'GET', body, timeoutMs = 30_000) {
+        return new Promise((resolve, reject) => {
+            const opts = {
+                ...this.endpoint,
+                path: `/v1.44${path}`,
+                method,
+                headers: body ? { 'Content-Type': 'application/json' } : undefined,
+            };
+            const req = http.request(opts, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const text = Buffer.concat(chunks).toString();
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(t('codeSandbox.docker.error.apiError', { method, path, status: String(res.statusCode), error: text }, { defaultValue: `Docker API ${method} ${path}: ${res.statusCode} ${text}` })));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(text));
+                    }
+                    catch (_error) {
+                        // Non-JSON response (e.g. plain-text or empty body) — return raw text
+                        resolve(text);
+                    }
+                });
+                res.on('error', reject);
+            });
+            // Timeout to prevent hanging on unresponsive Docker daemon
+            req.setTimeout(timeoutMs, () => {
+                req.destroy(new Error(`Docker API timeout: ${method} ${path}`));
+            });
+            req.on('error', reject);
+            if (body)
+                req.write(JSON.stringify(body));
+            req.end();
+        });
+    }
+    /**
+     * Like `dockerApi` but returns the raw response Buffer without parsing.
+     * Used for exec start responses which return a multiplexed binary stream.
+     * @param path - The API endpoint path.
+     * @param method - The HTTP method (defaults to `'GET'`).
+     * @param body - Optional JSON request body.
+     * @returns The raw response buffer.
+     */
+    async dockerApiRaw(path, method = 'GET', body) {
+        return new Promise((resolve, reject) => {
+            const opts = {
+                ...this.endpoint,
+                path: `/v1.44${path}`,
+                method,
+                headers: body ? { 'Content-Type': 'application/json' } : undefined,
+            };
+            const MAX_RAW_RESPONSE = 50 * 1024 * 1024; // 50 MB cap on exec output
+            let totalSize = 0;
+            const req = http.request(opts, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => {
+                    totalSize += chunk.length;
+                    if (totalSize > MAX_RAW_RESPONSE) {
+                        req.destroy(new Error(`Docker exec output exceeded ${MAX_RAW_RESPONSE / (1024 * 1024)}MB limit`));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                res.on('end', () => {
+                    const buf = Buffer.concat(chunks);
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(t('codeSandbox.docker.error.apiError', { method, path, status: String(res.statusCode), error: buf.toString() }, {
+                            defaultValue: `Docker API ${method} ${path}: ${res.statusCode} ${buf.toString()}`,
+                        })));
+                        return;
+                    }
+                    resolve(buf);
+                });
+                res.on('error', reject);
+            });
+            // Longer timeout for exec responses (commands can take minutes)
+            req.setTimeout(600_000, () => {
+                req.destroy(new Error(`Docker exec timeout: ${method} ${path}`));
+            });
+            req.on('error', reject);
+            if (body)
+                req.write(JSON.stringify(body));
+            req.end();
+        });
+    }
+    /**
+     * Starts a Docker exec instance and upgrades the HTTP connection to a raw
+     * bidirectional socket. Docker hijacks the connection (101 Switching Protocols)
+     * when stdin is attached, giving us a raw TCP socket for streaming I/O.
+     * @param execId - The exec instance ID from the create step.
+     * @returns The raw socket for stdin writes and multiplexed stdout/stderr reads.
+     */
+    dockerExecUpgrade(execId) {
+        return new Promise((resolve, reject) => {
+            const body = JSON.stringify({ Detach: false, Tty: false });
+            const req = http.request({
+                ...this.endpoint,
+                path: `/v1.44/exec/${execId}/start`,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Connection: 'Upgrade',
+                    Upgrade: 'tcp',
+                },
+            }, (res) => {
+                // Fallback: if Docker doesn't upgrade (e.g. old version), reject
+                reject(new Error(`Expected 101 upgrade, got ${res.statusCode}`));
+            });
+            req.on('upgrade', (_res, socket, head) => {
+                // Process any initial data that arrived with the upgrade response
+                if (head.length > 0) {
+                    socket.unshift(head);
+                }
+                resolve(socket);
+            });
+            req.on('error', reject);
+            req.write(body);
+            req.end();
+        });
+    }
+}
+/**
+ * Creates a new `DockerSandboxProvider` instance with the given configuration.
+ * @param config - Optional Docker-specific configuration: daemon endpoint
+ *   (`socketPath`, or `host`/`port` for a TCP daemon; `DOCKER_HOST` is also
+ *   honored), `baseImage`, CPU/memory defaults, and the sandbox `network`.
+ * @returns A `SandboxProvider` that manages Docker containers as sandboxes.
+ */
+export function createProvider(config) {
+    return new DockerSandboxProvider(config);
+}