@molecule/api-code-sandbox-docker 1.0.1 → 1.1.0

package/dist/provider.js

@@ -6,10 +6,19 @@
  *
  * @module
  */
+import { readFile, statfs } from 'fs/promises';
 import http from 'http';
+import { freemem } from 'os';
+import { Readable } from 'stream';
 import { getLogger } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
 const logger = getLogger();
+import { exportContainerFiles, importContainerFiles } from './archive.js';
+import { measureDockerCapacity } from './capacity.js';
+import { verifyDockerEgress } from './egress.js';
+import { hibernateContainer, resumeContainer } from './hibernate.js';
+import { describeContainer, findContainers, listDockerVolumes, updateContainerResources, } from './inspect.js';
+import * as templates from './templates.js';
 const DEFAULT_IMAGE = 'node:22-slim';
 /**
  * Shell-safe single-quote escaping for file paths. Prevents command injection
@@ -34,6 +43,17 @@ const LABEL_PREFIX = 'molecule-sandbox';
 const DEFAULT_SANDBOX_NETWORK = 'molecule-sandbox';
 /** Default Docker daemon TCP port for a plain (unencrypted) `tcp://` endpoint. */
 const DEFAULT_DOCKER_TCP_PORT = 2375;
+/**
+ * Repository that holds sandbox templates, kept separate from the base image's
+ * repository so a template sweep can never reach `molecule-sandbox:latest`.
+ */
+const DEFAULT_TEMPLATE_REPOSITORY = 'molecule-sandbox-template';
+/** `X-Registry-Auth` for an anonymous or already-logged-in daemon. */
+const EMPTY_REGISTRY_AUTH = Buffer.from('{}').toString('base64');
+/** Ports published for every sandbox when the caller names none. */
+const DEFAULT_PUBLISH_PORTS = [4000, 5173];
+/** Maximum processes a sandbox may hold when the caller sets no `pidsLimit`. */
+const DEFAULT_PIDS_LIMIT = 512;
 /**
  * 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`
@@ -135,6 +155,63 @@ class DockerMuxParser {
         }
     }
 }
+/**
+ * Validate the ports a caller asked to publish, falling back to this provider's
+ * historical API + Vite pair when it named none.
+ *
+ * Rejects rather than filters: a caller that asked for a port it cannot have
+ * needs to hear so, because the alternative is a dev server running inside a
+ * sandbox that nothing on the outside can ever reach — which looks like a broken
+ * application, not a bad argument.
+ *
+ * @param ports - Ports inside the sandbox the caller wants reachable.
+ * @returns The ports to expose and bind.
+ * @throws {Error} When a port is not a valid TCP port number.
+ */
+export function resolvePublishPorts(ports) {
+    if (!ports || ports.length === 0)
+        return DEFAULT_PUBLISH_PORTS;
+    for (const port of ports) {
+        if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+            throw new Error(`Invalid publish port ${String(port)}: must be an integer in 1-65535`);
+        }
+    }
+    return [...new Set(ports)];
+}
+/**
+ * Available memory in bytes, or `null` when it cannot be read.
+ *
+ * Prefers Linux `MemAvailable`, which is the kernel's estimate of what a new
+ * workload can use WITHOUT swapping and counts reclaimable page cache.
+ * `os.freemem()` excludes that cache and badly understates free memory on any
+ * warm host, so it is only the off-Linux fallback — using it as the primary
+ * signal rejects boots the host could comfortably serve.
+ *
+ * @returns Available bytes, or `null` when unreadable.
+ */
+async function availableMemoryBytes() {
+    try {
+        const match = /^MemAvailable:\s+(\d+)\s+kB/m.exec(await readFile('/proc/meminfo', 'utf-8'));
+        if (match) {
+            const kb = Number.parseInt(match[1], 10);
+            if (Number.isFinite(kb) && kb > 0)
+                return kb * 1024;
+        }
+    }
+    catch (_error) {
+        // /proc/meminfo is absent on non-Linux hosts and unreadable in some
+        // sandboxes — fall through to the portable estimate rather than failing.
+    }
+    try {
+        const bytes = freemem();
+        return Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+    }
+    catch (_error) {
+        // No usable memory reading at all — report "unknown" so the caller does not
+        // mistake it for "exhausted".
+        return null;
+    }
+}
 /**
  * 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,
@@ -209,6 +286,20 @@ class DockerSandboxProvider {
     configNetwork;
     /** [C1-1] Memoize the one-time ICC-off network ensure so create() pays it only once. */
     networkEnsured = false;
+    /** Explicit template repository from config; env is consulted at call time. */
+    configTemplateRepository;
+    /** Explicit template registry from config; env is consulted at call time. */
+    configTemplateRegistry;
+    /** Explicit registry credential from config; env is consulted at call time. */
+    configTemplateRegistryAuth;
+    /**
+     * Whether this host still looks capable of CRIU checkpoints. Shared by
+     * `hibernate` and `resume` for every sandbox this provider hands out, so a host
+     * without CRIU pays one rejected request per process instead of one per
+     * hibernation. Held on the instance rather than at module scope so two
+     * providers (and two tests) do not inherit each other's verdict.
+     */
+    checkpoints = { supported: true };
     constructor(config = {}) {
         this.endpoint = resolveDockerEndpoint(config);
         this.baseImage = config.baseImage ?? DEFAULT_IMAGE;
@@ -217,6 +308,48 @@ class DockerSandboxProvider {
         this.defaultCpu = config.defaultCpu ?? 1;
         this.defaultMemoryMB = config.defaultMemoryMB ?? 1024;
         this.configNetwork = config.network;
+        this.configTemplateRepository = config.templateRepository;
+        this.configTemplateRegistry = config.templateRegistry;
+        this.configTemplateRegistryAuth = config.templateRegistryAuth;
+    }
+    /**
+     * Assemble the context every template operation runs against. Env is read here
+     * rather than in the constructor, matching {@link resolveNetwork}: this
+     * provider is commonly constructed before the process has loaded its
+     * environment.
+     *
+     * @returns The template context.
+     */
+    templateContext() {
+        return {
+            request: (path, method, body, timeoutMs, headers) => this.dockerApi(path, method, body, timeoutMs, headers),
+            download: (path, timeoutMs) => this.dockerDownload(path, timeoutMs),
+            upload: (path, body, timeoutMs) => this.dockerUpload(path, body, timeoutMs),
+            baseImage: this.baseImage,
+            repository: this.configTemplateRepository ??
+                process.env.SANDBOX_TEMPLATE_REPOSITORY ??
+                DEFAULT_TEMPLATE_REPOSITORY,
+            registry: this.configTemplateRegistry ?? process.env.SANDBOX_TEMPLATE_REGISTRY ?? '',
+            registryAuth: this.configTemplateRegistryAuth ??
+                process.env.SANDBOX_TEMPLATE_REGISTRY_AUTH ??
+                EMPTY_REGISTRY_AUTH,
+            labelPrefix: this.labelPrefix,
+            warn: (message, meta) => logger.warn(message, meta),
+            debug: (message, meta) => logger.debug(message, meta),
+        };
+    }
+    /**
+     * The context shared by the inspection capabilities.
+     *
+     * @returns The inspection context.
+     */
+    inspectContext() {
+        return {
+            request: (path, method, body, timeoutMs, headers) => this.dockerApi(path, method, body, timeoutMs, headers),
+            labelPrefix: this.labelPrefix,
+            warn: (message, meta) => logger.warn(message, meta),
+            debug: (message, meta) => logger.debug(message, meta),
+        };
     }
     /**
      * Resolve the Docker network to attach containers to. Precedence:
@@ -285,7 +418,22 @@ class DockerSandboxProvider {
         await this.ensureSandboxNetwork();
         const cpu = config.resources?.cpu ?? this.defaultCpu;
         const memoryMB = config.resources?.memoryMB ?? this.defaultMemoryMB;
-        const image = config.image ?? this.baseImage;
+        let image = config.image ?? this.baseImage;
+        // Booting from a template is the caller naming a filesystem it captured. If
+        // it is gone, FAIL — falling back to the base image would hand back a
+        // healthy-looking sandbox whose contents are not the ones that were asked
+        // for, and nothing downstream would notice.
+        if (config.templateId) {
+            const template = await templates.getTemplate(this.templateContext(), config.templateId);
+            if (!template) {
+                throw new Error(t('codeSandbox.docker.error.templateMissing', { templateId: config.templateId }, {
+                    defaultValue: `Cannot create a sandbox from template "${config.templateId}": it does not exist. ` +
+                        'Commit it first, or fetch it from the shared template store.',
+                }));
+            }
+            image = template.ref;
+        }
+        const publishPorts = resolvePublishPorts(config.publishPorts);
         const env = Object.entries(config.env ?? {}).map(([k, v]) => `${k}=${v}`);
         const labels = {
             [`${this.labelPrefix}.projectId`]: config.projectId,
@@ -311,7 +459,7 @@ class DockerSandboxProvider {
             // the Memory cap does not bound swap. [C1-2]
             MemorySwap: memoryBytes * 2,
             Init: true, // Use tini init to reap zombie processes
-            PidsLimit: 512,
+            PidsLimit: config.resources?.pidsLimit ?? DEFAULT_PIDS_LIMIT,
             SecurityOpt: ['no-new-privileges'],
             CapDrop: ['ALL'],
             // Minimal caps for the dev toolchain (file ownership + tini privilege drop).
@@ -320,11 +468,10 @@ class DockerSandboxProvider {
             // 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: '' }],
-            },
+            // Bind ports to localhost only — prevents external access. Which ports is
+            // the caller's business (`config.publishPorts`); the historical
+            // API + Vite pair is the default so existing callers are unaffected.
+            PortBindings: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, [{ HostIp: '127.0.0.1', HostPort: '' }]])),
             Tmpfs: { '/tmp': 'rw,noexec,nosuid,size=256m' },
             ReadonlyPaths: [
                 '/proc/asound',
@@ -361,16 +508,29 @@ class DockerSandboxProvider {
             labels[`${this.labelPrefix}.volumeName`] = config.volumeName;
             hostConfig.Binds = [`${config.volumeName}:/workspace`];
         }
+        // What the container does when its main process exits. Docker's default is
+        // `no`, matching this provider's historical behaviour: a sandbox whose
+        // process exits stays stopped for the caller to inspect. A caller running
+        // something long-lived (a production instance) asks for `always`/`on-failure`
+        // so the workload comes back after a crash or a daemon restart without a
+        // control plane in the loop.
+        if (config.restartPolicy && config.restartPolicy !== 'no') {
+            hostConfig.RestartPolicy = { Name: config.restartPolicy };
+        }
         const body = {
             Image: image,
             Env: env,
             Labels: labels,
             HostConfig: hostConfig,
-            ExposedPorts: {
-                '4000/tcp': {},
-                '5173/tcp': {},
-            },
+            ExposedPorts: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, {}])),
         };
+        // The caller's own main process, replacing the image's CMD. Without it a
+        // container that Docker restarts comes back running the image's idle command
+        // and serving nothing, while `status` still reports it as running — which it
+        // is, and empty. `Cmd` (not `Entrypoint`) so the image's entrypoint — tini,
+        // enabled above via `Init` — still wraps it and reaps its children.
+        if (config.command?.length)
+            body.Cmd = [...config.command];
         // 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
@@ -679,17 +839,32 @@ class DockerSandboxProvider {
                 // (e.g. a per-sandbox subdomain `sb-{port}.preview.localhost:{port}`).
                 return provider.previewUrlTemplate.replace(/\{port\}/g, String(port ?? 5173));
             },
+            /**
+             * Spawn a long-running process with streaming I/O, optionally on a PTY.
+             *
+             * `opts.pty` asks Docker for `Tty: true`, which gives the process a real
+             * controlling terminal: Ctrl-C (`0x03`) becomes SIGINT for the foreground
+             * job and the width can be renegotiated through `handle.resize()`. A TTY
+             * exec stream is NOT multiplexed, so the frame parser is bypassed and
+             * everything (stderr included, as on a real terminal) arrives on stdout.
+             *
+             * @param command - The command to run.
+             * @param opts - Working directory, env, and optional PTY size.
+             * @returns A handle with streaming I/O, stdin, kill, and (on a PTY) resize.
+             */
             async spawn(command, opts) {
+                const tty = Boolean(opts?.pty);
                 const execCreate = (await provider.dockerApi(`/containers/${containerId}/exec`, 'POST', {
                     Cmd: ['sh', '-c', command],
                     AttachStdin: true,
                     AttachStdout: true,
                     AttachStderr: true,
-                    Tty: false,
+                    Tty: tty,
+                    ...(opts?.pty ? { ConsoleSize: [opts.pty.rows, opts.pty.cols] } : {}),
                     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 socket = await provider.dockerExecUpgrade(execCreate.Id, tty);
                 const parser = new DockerMuxParser();
                 let closeCb = null;
                 // Kill idle spawn sockets after 10 minutes to prevent descriptor leaks
@@ -697,7 +872,17 @@ class DockerSandboxProvider {
                 socket.on('timeout', () => {
                     socket.destroy();
                 });
+                // A TTY exec stream carries raw terminal bytes — there are no 8-byte
+                // frame headers to strip, and feeding them to the mux parser would read
+                // the first byte of the shell's output as a stream descriptor.
+                const ttyListeners = [];
                 socket.on('data', (chunk) => {
+                    if (tty) {
+                        const text = chunk.toString('utf8');
+                        for (const cb of ttyListeners)
+                            cb(text);
+                        return;
+                    }
                     try {
                         parser.feed(chunk);
                     }
@@ -723,10 +908,16 @@ class DockerSandboxProvider {
                             socket.write(data);
                     },
                     onStdout(cb) {
-                        parser.onStdout(cb);
+                        if (tty)
+                            ttyListeners.push(cb);
+                        else
+                            parser.onStdout(cb);
                     },
                     onStderr(cb) {
-                        parser.onStderr(cb);
+                        // On a TTY both streams share one descriptor, so nothing arrives
+                        // here — registering is harmless and keeps the handle uniform.
+                        if (!tty)
+                            parser.onStderr(cb);
                     },
                     onClose(cb) {
                         closeCb = cb;
@@ -735,8 +926,64 @@ class DockerSandboxProvider {
                         if (!socket.destroyed)
                             socket.destroy();
                     },
+                    ...(tty
+                        ? {
+                            resize(size) {
+                                void provider
+                                    .dockerApi(`/exec/${execCreate.Id}/resize?h=${Math.max(1, Math.floor(size.rows))}&w=${Math.max(1, Math.floor(size.cols))}`, 'POST')
+                                    .catch((error) => {
+                                    // Best-effort: a resize races the exec exiting, and a
+                                    // failed one only leaves the remote width stale — never a
+                                    // reason to tear down a live session.
+                                    logger.debug('Spawn resize failed', {
+                                        error: error instanceof Error ? error.message : error,
+                                    });
+                                });
+                            },
+                        }
+                        : {}),
                 };
             },
+            async hibernate() {
+                const outcome = await hibernateContainer({
+                    request: (path, method, body, timeoutMs, headers) => provider.dockerApi(path, method, body, timeoutMs, headers),
+                    checkpoints: provider.checkpoints,
+                    warn: (message, meta) => logger.warn(message, meta),
+                    info: (message, meta) => logger.info(message, meta),
+                }, containerId);
+                this.status = 'sleeping';
+                return outcome;
+            },
+            async resume() {
+                const outcome = await resumeContainer({
+                    request: (path, method, body, timeoutMs, headers) => provider.dockerApi(path, method, body, timeoutMs, headers),
+                    checkpoints: provider.checkpoints,
+                    warn: (message, meta) => logger.warn(message, meta),
+                    info: (message, meta) => logger.info(message, meta),
+                }, containerId);
+                this.status = 'running';
+                return outcome;
+            },
+            async setResources(resources) {
+                await updateContainerResources({
+                    request: (path, method, body, timeoutMs, headers) => provider.dockerApi(path, method, body, timeoutMs, headers),
+                    labelPrefix: provider.labelPrefix,
+                    warn: (message, meta) => logger.warn(message, meta),
+                    debug: (message, meta) => logger.debug(message, meta),
+                }, containerId, resources);
+            },
+            async exportFiles(path) {
+                return exportContainerFiles({
+                    download: (p, timeoutMs) => provider.dockerDownload(p, timeoutMs),
+                    upload: (p, body, timeoutMs) => provider.dockerUpload(p, body, timeoutMs),
+                }, containerId, path);
+            },
+            async importFiles(path, archive) {
+                await importContainerFiles({
+                    download: (p, timeoutMs) => provider.dockerDownload(p, timeoutMs),
+                    upload: (p, body, timeoutMs) => provider.dockerUpload(p, body, timeoutMs),
+                }, containerId, path, archive);
+            },
             onFileChange(_cb) {
                 let active = true;
                 const poll = async () => {
@@ -796,6 +1043,138 @@ class DockerSandboxProvider {
             return false;
         }
     }
+    /**
+     * Prove whether the host actually denies sandbox egress.
+     *
+     * Delegates to {@link verifyDockerEgress}, which runs BOTH legs — outbound
+     * (DOCKER-USER) and host-bound (INPUT). See that module for why one leg is not
+     * enough: host-gateway traffic never traverses DOCKER-USER, so an outbound-only
+     * check reports "filtered" on a host whose SSH, Redis, monitoring and admin
+     * consoles are reachable from every sandbox.
+     *
+     * @returns What was observed about egress filtering.
+     */
+    async verifyEgress() {
+        return verifyDockerEgress({
+            request: (path, method, body, timeoutMs) => this.dockerApi(path, method, body, timeoutMs),
+            network: this.resolveNetwork(),
+            baseImage: this.baseImage,
+            labelPrefix: this.labelPrefix,
+            warn: (message, meta) => logger.warn(message, meta),
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Templates
+    // ---------------------------------------------------------------------------
+    /**
+     * Capture a sandbox's filesystem as a reusable template.
+     *
+     * See `templates.ts` for why this is not a plain `commit`: a sandbox keeps the
+     * project on a volume, and a volume is not part of a container's writable
+     * layer — so committing the sandbox itself produces an image that boots
+     * successfully with an empty workspace.
+     *
+     * @param options - What to capture and what to call it.
+     * @returns The template as it now exists.
+     */
+    async commitTemplate(options) {
+        return templates.commitTemplate(this.templateContext(), options);
+    }
+    /**
+     * Read one template by the caller's identifier.
+     *
+     * @param templateId - The caller's identifier.
+     * @returns The template, or `null` when no image carries that tag.
+     */
+    async getTemplate(templateId) {
+        return templates.getTemplate(this.templateContext(), templateId);
+    }
+    /**
+     * Enumerate templates in this provider's template repository.
+     *
+     * @param options - Narrowing by id prefix.
+     * @returns Every matching template.
+     */
+    async listTemplates(options) {
+        return templates.listTemplates(this.templateContext(), options);
+    }
+    /**
+     * Delete a template, refusing while a container is still backed by it.
+     *
+     * @param templateId - The caller's identifier.
+     */
+    async removeTemplate(templateId) {
+        return templates.removeTemplate(this.templateContext(), templateId);
+    }
+    /**
+     * Push a template to the configured registry so other hosts can boot from it.
+     *
+     * @param templateId - The caller's identifier.
+     */
+    async publishTemplate(templateId) {
+        return templates.publishTemplate(this.templateContext(), templateId);
+    }
+    /**
+     * Pull a template from the configured registry onto this host.
+     *
+     * @param templateId - The caller's identifier.
+     * @returns The now-local template, or `null` when the registry does not have it.
+     */
+    async fetchTemplate(templateId) {
+        return templates.fetchTemplate(this.templateContext(), templateId);
+    }
+    // ---------------------------------------------------------------------------
+    // Inspection
+    // ---------------------------------------------------------------------------
+    /**
+     * Describe one sandbox without building a handle for it.
+     *
+     * @param id - The container id.
+     * @returns The descriptor, or `null` when no such container exists.
+     */
+    async describe(id) {
+        return describeContainer(this.inspectContext(), id);
+    }
+    /**
+     * Find sandboxes by the labels the caller put on them.
+     *
+     * @param query - Narrowing by label, status and project.
+     * @returns Descriptors for every match.
+     */
+    async find(query) {
+        return findContainers(this.inspectContext(), query);
+    }
+    /**
+     * Enumerate named volumes and whether anything still has them attached.
+     *
+     * @param options - Narrowing by name prefix and attachment.
+     * @returns Every matching volume.
+     */
+    async listVolumes(options) {
+        return listDockerVolumes(this.inspectContext(), options);
+    }
+    /**
+     * Measure what the host backing this daemon can still fit.
+     *
+     * @returns Measured headroom and an explanation of anything unmeasurable.
+     */
+    async capacity() {
+        return measureDockerCapacity({
+            request: (path, method, body, timeoutMs, headers) => this.dockerApi(path, method, body, timeoutMs, headers),
+            // Only a unix-socket daemon writes to storage this process can measure.
+            daemonIsLocal: 'socketPath' in this.endpoint,
+            statfs: async (path) => {
+                const stats = await statfs(path);
+                return {
+                    bsize: Number(stats.bsize),
+                    bavail: Number(stats.bavail),
+                    ffree: Number(stats.ffree),
+                };
+            },
+            availableMemoryBytes,
+            warn: (message, meta) => logger.warn(message, meta),
+        });
+    }
     /**
      * Makes an HTTP request to the Docker Engine API via the Unix socket.
      * @param path - The API endpoint path (e.g. `/containers/create`).
@@ -806,15 +1185,20 @@ class DockerSandboxProvider {
      *   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.
+     * @param headers - Extra request headers. Registry operations need
+     *   `X-Registry-Auth`, which the daemon requires even for anonymous pulls.
      * @returns The parsed JSON response, or raw text for non-JSON responses.
      */
-    async dockerApi(path, method = 'GET', body, timeoutMs = 30_000) {
+    async dockerApi(path, method = 'GET', body, timeoutMs = 30_000, headers) {
         return new Promise((resolve, reject) => {
             const opts = {
                 ...this.endpoint,
                 path: `/v1.44${path}`,
                 method,
-                headers: body ? { 'Content-Type': 'application/json' } : undefined,
+                headers: {
+                    ...(body ? { 'Content-Type': 'application/json' } : {}),
+                    ...headers,
+                },
             };
             const req = http.request(opts, (res) => {
                 const chunks = [];
@@ -845,6 +1229,96 @@ class DockerSandboxProvider {
             req.end();
         });
     }
+    /**
+     * Issue a Docker Engine API GET and hand back the response body as a byte
+     * stream.
+     *
+     * Unbuffered on purpose: this carries whole project trees, and materializing
+     * one in this process to hand it to the next call trades a slow transfer for
+     * an out-of-memory API. The error path DOES buffer, because an error body is
+     * a sentence and the caller needs to read it.
+     *
+     * @param path - The API endpoint path.
+     * @param timeoutMs - Request timeout (default 10 min).
+     * @returns The response body as an async byte stream.
+     */
+    dockerDownload(path, timeoutMs = 600_000) {
+        return new Promise((resolve, reject) => {
+            const req = http.request({ ...this.endpoint, path: `/v1.44${path}`, method: 'GET' }, (res) => {
+                if (res.statusCode && res.statusCode >= 400) {
+                    const chunks = [];
+                    res.on('data', (chunk) => chunks.push(chunk));
+                    res.on('end', () => {
+                        reject(new Error(t('codeSandbox.docker.error.apiError', {
+                            method: 'GET',
+                            path,
+                            status: String(res.statusCode),
+                            error: Buffer.concat(chunks).toString(),
+                        }, {
+                            defaultValue: `Docker API GET ${path}: ${res.statusCode} ${Buffer.concat(chunks).toString()}`,
+                        })));
+                    });
+                    res.on('error', reject);
+                    return;
+                }
+                resolve(res);
+            });
+            req.setTimeout(timeoutMs, () => {
+                req.destroy(new Error(`Docker API timeout: GET ${path}`));
+            });
+            req.on('error', reject);
+            req.end();
+        });
+    }
+    /**
+     * Issue a Docker Engine API PUT whose request body is a byte stream.
+     *
+     * Piped rather than written in a loop so Node applies backpressure — without
+     * it, a fast source fills this process's memory with everything the socket has
+     * not drained yet, which for a project tree is the whole tree.
+     *
+     * @param path - The API endpoint path.
+     * @param body - The request body as an async byte stream.
+     * @param timeoutMs - Request timeout (default 10 min).
+     */
+    dockerUpload(path, body, timeoutMs = 600_000) {
+        return new Promise((resolve, reject) => {
+            const req = http.request({
+                ...this.endpoint,
+                path: `/v1.44${path}`,
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/x-tar' },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(t('codeSandbox.docker.error.apiError', {
+                            method: 'PUT',
+                            path,
+                            status: String(res.statusCode),
+                            error: Buffer.concat(chunks).toString(),
+                        }, {
+                            defaultValue: `Docker API PUT ${path}: ${res.statusCode} ${Buffer.concat(chunks).toString()}`,
+                        })));
+                        return;
+                    }
+                    resolve();
+                });
+                res.on('error', reject);
+            });
+            req.setTimeout(timeoutMs, () => {
+                req.destroy(new Error(`Docker API timeout: PUT ${path}`));
+            });
+            req.on('error', reject);
+            const source = Readable.from(body);
+            source.on('error', (error) => {
+                req.destroy(error);
+                reject(error);
+            });
+            source.pipe(req);
+        });
+    }
     /**
      * Like `dockerApi` but returns the raw response Buffer without parsing.
      * Used for exec start responses which return a multiplexed binary stream.
@@ -900,11 +1374,14 @@ class DockerSandboxProvider {
      * 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.
+     * @param tty - Whether the exec was created with a TTY; the start call must
+     *   agree, or Docker streams multiplexed frames to a terminal expecting raw
+     *   bytes.
      * @returns The raw socket for stdin writes and multiplexed stdout/stderr reads.
      */
-    dockerExecUpgrade(execId) {
+    dockerExecUpgrade(execId, tty = false) {
         return new Promise((resolve, reject) => {
-            const body = JSON.stringify({ Detach: false, Tty: false });
+            const body = JSON.stringify({ Detach: false, Tty: tty });
             const req = http.request({
                 ...this.endpoint,
                 path: `/v1.44/exec/${execId}/start`,