withruntime 0.8.4 → 0.10.0

package/dist/sandbox.js

@@ -1,3 +1,4 @@
+import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
 import { CommandError, ConnectionError, NotFoundError, RuntimeError } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
@@ -12,6 +13,58 @@ const CHUNK = 1_048_576;
  * connections at once. */
 const PARALLEL = 8;
 const enc = (id) => encodeURIComponent(id);
+/** One explicit deadline across a composed operation and its queue/retries. */
+function requestScope(options) {
+    const deadline = options.timeoutMs === undefined || options.timeoutMs === 0
+        ? undefined
+        : AbortSignal.timeout(options.timeoutMs);
+    const signal = deadline && options.signal
+        ? AbortSignal.any([deadline, options.signal])
+        : (deadline ?? options.signal);
+    const request = {
+        ...options,
+        ...(deadline ? { timeoutMs: 0 } : {}),
+        ...(signal ? { signal } : {}),
+    };
+    const cancelled = () => new ConnectionError({
+        message: "The call was cancelled or ran past its deadline.",
+        code: "timeout",
+        status: 0,
+        cause: signal?.reason,
+    });
+    const check = () => {
+        if (signal?.aborted)
+            throw cancelled();
+    };
+    const wait = (pending) => {
+        if (!signal)
+            return pending;
+        return new Promise((resolve, reject) => {
+            const abort = () => reject(cancelled());
+            if (signal.aborted)
+                abort();
+            else
+                signal.addEventListener("abort", abort, { once: true });
+            pending.then((value) => {
+                signal.removeEventListener("abort", abort);
+                resolve(value);
+            }, (error) => {
+                signal.removeEventListener("abort", abort);
+                reject(error instanceof Error ? error : new Error(String(error), { cause: error }));
+            });
+        });
+    };
+    return { request, check, wait };
+}
+/** DELETE /v1/sandboxes/{id}, for `sandbox.delete()` and
+ * `runtime.sandboxes.delete(id)`. */
+export function deleteSandbox(t, id, options = {}) {
+    return t.json({
+        method: "DELETE",
+        path: `/v1/sandboxes/${enc(id)}`,
+        ...options,
+    });
+}
 /* Web APIs only, so the sandbox's commands, processes and files work in a
    browser with a session token (Sandbox.fromSession): no Buffer, no
    node:crypto. */
@@ -85,6 +138,13 @@ export class Sandbox {
         });
         return new Sandbox(transport, { id: session.sandboxId });
     }
+    /** The API's latest answer. `start`, the report of an image's start
+     * command, is the create's alone: the API keeps no record of it, so a
+     * later read of this sandbox keeps it here. */
+    #keep(info) {
+        const start = this.#info?.start;
+        this.#info = info.start === undefined && start !== undefined ? { ...info, start } : info;
+    }
     /** What the API last said about this sandbox. `refresh()` asks again. */
     get info() {
         return this.#info;
@@ -93,21 +153,24 @@ export class Sandbox {
         return this.#info.state;
     }
     async refresh(options = {}) {
-        this.#info = await this.#t.json({
+        this.#keep(await this.#t.json({
             method: "GET",
             path: `/v1/sandboxes/${enc(this.id)}`,
             ...options,
-        });
+        }));
         return this;
     }
     /** Waits (server-side, no polling) until the sandbox reaches `state`. */
     async waitFor(state, options = {}) {
-        this.#info = await this.#t.json({
+        this.#keep(await this.#t.json({
             method: "GET",
             path: `/v1/sandboxes/${enc(this.id)}`,
-            query: { waitFor: state, timeoutSeconds: options.timeoutSeconds ?? 60 },
+            query: {
+                waitFor: state,
+                timeoutSeconds: options.timeoutSeconds ?? WAIT_FOR_TIMEOUT_SECONDS,
+            },
             ...options,
-        });
+        }));
         return this;
     }
     /** Runs a command and returns its exit code and output. A string runs under
@@ -136,7 +199,7 @@ export class Sandbox {
                         processId = event.processId;
                     else if (event.type === "stdout" || event.type === "stderr") {
                         out[event.type] += event.data;
-                        (event.type === "stdout" ? options.onStdout : options.onStderr)?.(event.data);
+                        await (event.type === "stdout" ? options.onStdout : options.onStderr)?.(event.data);
                     }
                     else if (event.type === "truncated")
                         dropped = true;
@@ -206,9 +269,12 @@ export class Sandbox {
         const events = this.#t.events({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}:exec`,
-            body: { ...commandBody(command, { timeoutMs: 86_400_000, ...options }), stream: true },
+            body: {
+                ...commandBody(command, { timeoutMs: STREAMED_EXEC_TIMEOUT_MS, ...options }),
+                stream: true,
+            },
             ...pick(options),
-            timeoutMs: options.timeoutMs === undefined ? 86_400_000 : options.timeoutMs + 60_000,
+            timeoutMs: options.timeoutMs === undefined ? STREAMED_EXEC_TIMEOUT_MS : options.timeoutMs + 60_000,
         });
         try {
             for await (const event of events) {
@@ -245,7 +311,7 @@ export class Sandbox {
      * once. `stdin: "pipe"` keeps its input open for write(); `pty` gives it a
      * terminal. */
     async spawn(command, options = {}) {
-        const { stdin, pty, ...rest } = options;
+        const { stdin, pty, outputEncoding, request, ...rest } = options;
         const info = await this.#t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}/processes`,
@@ -253,8 +319,10 @@ export class Sandbox {
                 ...commandBody(command, rest),
                 ...(stdin === "pipe" ? { stdinMode: "pipe" } : stdin === undefined ? {} : { stdin }),
                 ...(pty ? { pty } : {}),
+                ...(outputEncoding ? { outputEncoding } : {}),
             },
             ...pick(rest),
+            ...request,
         });
         return new Process(this.#t, this.id, info);
     }
@@ -304,6 +372,14 @@ export class Sandbox {
     async pause(options = {}) {
         return this.#lifecycle("pause", options);
     }
+    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
+     * and paused memory, revokes its previews and ports, and removes it from
+     * lists. Its snapshots, usage and audit entries stay. Deleting it again
+     * answers the same. */
+    async delete(options = {}) {
+        this.#keepAlive?.();
+        return deleteSandbox(this.#t, this.id, options);
+    }
     /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
     async wake(options = {}) {
         const { timeoutSeconds, ...rest } = options;
@@ -331,6 +407,26 @@ export class Sandbox {
     async update(settings, options = {}) {
         return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
     }
+    /** Moves it to another image (id, name, name:tag or name@version), keeping
+     * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
+     * volumes, environment, name and previews. Its processes restart, and
+     * everything else on its old disk (sudo installs, apt packages, /etc) is
+     * lost, which `keep: "workspace"` says you know; snapshot it first to keep
+     * everything. A running sandbox is paused first. A switch that fails is
+     * undone (`switch_undone`), the sandbox on its old image with nothing lost.
+     * Charged as a wake. */
+    async switchImage(image, options) {
+        const { keep, ...rest } = options;
+        this.#keep(await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:switch-image`,
+            body: { image, keep },
+            // A pause, two boots and the copy between them.
+            wait: 120,
+            ...pick(rest),
+        }));
+        return this;
+    }
     /** Keeps a running sandbox's lease ahead of now, in the background, until
      * stop() or the returned function ends it: every `everySeconds` (60) it
      * extends the lease so that `marginSeconds` (600) remain, never more than
@@ -341,7 +437,7 @@ export class Sandbox {
     keepAlive(options = {}) {
         this.#keepAlive?.();
         const every = Math.max(10, options.everySeconds ?? 60) * 1000;
-        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? 600));
+        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? KEEP_ALIVE_MARGIN_SECONDS));
         let ended = false;
         let timer;
         const end = () => {
@@ -386,34 +482,112 @@ export class Sandbox {
      * the moment it takes, then woken; a paused one stays paused. */
     async snapshot(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
-        await this.refresh();
+        if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
+            throw new TypeError("Snapshot mode must be memory or disk.");
+        signal?.throwIfAborted();
+        const until = performance.now() + Math.min(timeoutMs && timeoutMs > 0 ? timeoutMs : 60_000, 60_000);
+        const request = () => {
+            signal?.throwIfAborted();
+            const left = Math.ceil(until - performance.now());
+            if (left <= 0)
+                throw new RuntimeError({
+                    code: "snapshot_timeout",
+                    status: 0,
+                    message: "Snapshot capture ran past its deadline.",
+                });
+            return { ...(signal ? { signal } : {}), timeoutMs: left };
+        };
+        await this.refresh(request());
         // Straight after a fork or a wake the sandbox is still `resuming`, and
         // after a pause still `pausing`: wait for where it is going, or a
         // snapshot of it is refused as not paused (user lane, 23 September 2026).
         if (this.state === "resuming" || this.state === "starting")
-            await this.waitFor("running");
+            await this.waitFor("running", request());
         else if (this.state === "pausing")
-            await this.waitFor("paused");
+            await this.waitFor("paused", request());
         const running = this.state === "running";
-        if (running)
-            await this.pause();
+        // Check before entering cleanup: an abort during refresh must not pause or wake.
+        const pauseOptions = running ? request() : undefined;
+        let captured;
+        let primary;
+        let failed = false;
         try {
-            return await this.#t.json({
+            if (running)
+                await this.pause(pauseOptions);
+            let snapshot = await this.#t.json({
                 method: "POST",
                 path: `/v1/sandboxes/${enc(this.id)}:snapshot`,
                 body,
                 wait: 10,
-                ...pick({
-                    ...(idempotencyKey ? { idempotencyKey } : {}),
-                    ...(signal ? { signal } : {}),
-                    ...(timeoutMs ? { timeoutMs } : {}),
-                }),
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+                ...request(),
             });
+            captured = snapshot;
+            // Prefer: wait is bounded on the server. A capture still in progress
+            // must keep its source paused, or the worker refuses it after we wake.
+            while (snapshot.state === "capturing") {
+                signal?.throwIfAborted();
+                if (performance.now() >= until)
+                    throw new RuntimeError({
+                        code: "snapshot_timeout",
+                        status: 0,
+                        message: "Snapshot capture did not finish within one minute.",
+                        details: { snapshotId: snapshot.id },
+                    });
+                await new Promise((resolve) => setTimeout(resolve, 200));
+                snapshot = await this.#t.json({
+                    method: "GET",
+                    path: `/v1/snapshots/${enc(snapshot.id)}`,
+                    ...request(),
+                });
+            }
+            if (snapshot.state !== "ready")
+                throw new RuntimeError({
+                    code: "snapshot_failed",
+                    status: 409,
+                    message: snapshot.error ?? `Snapshot capture ended in state ${snapshot.state}.`,
+                    details: { snapshotId: snapshot.id },
+                });
+            if (body.mode === "disk" && snapshot.mode !== "disk")
+                throw new RuntimeError({
+                    code: "snapshot_mode_mismatch",
+                    status: 409,
+                    message: "The server did not confirm a disk-only snapshot.",
+                    details: { snapshotId: snapshot.id },
+                });
+            captured = snapshot;
         }
-        finally {
-            if (running)
+        catch (error) {
+            failed = true;
+            primary = error;
+        }
+        if (running) {
+            try {
                 await this.wake();
+            }
+            catch (wakeError) {
+                const recovery = {
+                    ...(captured ? { snapshotId: captured.id } : {}),
+                    sourceSandboxId: this.id,
+                    sourceWakeError: {
+                        ...(wakeError instanceof RuntimeError ? { code: wakeError.code } : {}),
+                        message: wakeError instanceof Error ? wakeError.message : String(wakeError),
+                    },
+                };
+                const reported = failed ? primary : wakeError;
+                if (reported instanceof Error && Object.isExtensible(reported)) {
+                    if (reported instanceof RuntimeError)
+                        Object.assign(reported, { details: { ...reported.details, ...recovery } });
+                    else
+                        Object.assign(reported, recovery);
+                }
+                if (!failed)
+                    throw wakeError;
+            }
         }
+        if (failed)
+            throw primary;
+        return captured;
     }
     async fork(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
@@ -436,13 +610,13 @@ export class Sandbox {
         return this.#lifecycle("restart", options);
     }
     async #lifecycle(verb, options, body = {}) {
-        this.#info = await this.#t.json({
+        this.#keep(await this.#t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
             body,
             wait: options.wait === false ? 0 : 60,
             ...pick(options),
-        });
+        }));
         return this;
     }
     async [Symbol.asyncDispose]() {
@@ -481,11 +655,27 @@ class OutputCursor {
                     droppedBytes: event.offset - this.cursor,
                     resumeAt: event.offset,
                 };
-            this.cursor = Math.max(this.cursor, event.offset + utf8(event.data).byteLength);
+            this.cursor = Math.max(this.cursor, event.offset +
+                (event.base64 === undefined
+                    ? utf8(event.data).byteLength
+                    : processBytes(event.base64).length));
         }
         yield event;
     }
 }
+function processBytes(encoded) {
+    try {
+        return atob(encoded);
+    }
+    catch (cause) {
+        throw new RuntimeError({
+            code: "invalid_process_output",
+            status: 502,
+            message: "The process returned invalid base64 output.",
+            cause,
+        });
+    }
+}
 /** A stream cut off by the network rather than refused by Runtime: worth
  * reconnecting to from the cursor. */
 function cutOff(error) {
@@ -575,16 +765,18 @@ export class Processes {
         this.t = t;
         this.sandboxId = sandboxId;
     }
-    async list() {
+    async list(options = {}) {
         return (await this.t.json({
             method: "GET",
             path: `/v1/sandboxes/${enc(this.sandboxId)}/processes`,
+            ...options,
         })).data;
     }
-    async get(processId) {
+    async get(processId, options = {}) {
         const info = await this.t.json({
             method: "GET",
             path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(processId)}`,
+            ...options,
         });
         return new Process(this.t, this.sandboxId, info);
     }
@@ -637,6 +829,7 @@ export class Process {
     sandboxId;
     info;
     #inputOffset;
+    #inputWrites = Promise.resolve();
     constructor(t, sandboxId, info) {
         this.t = t;
         this.sandboxId = sandboxId;
@@ -650,6 +843,34 @@ export class Process {
     output(options = {}) {
         return new Processes(this.t, this.sandboxId).follow(this.id, options);
     }
+    /** Lossless output for a process spawned with outputEncoding: "base64".
+     * Refuses text-only output rather than inventing bytes that were discarded. */
+    async *outputBytes(options = {}) {
+        if (this.info.outputEncoding !== "base64")
+            throw new RuntimeError({
+                code: "binary_output_unavailable",
+                status: 409,
+                message: "Spawn the process with outputEncoding: base64 to read lossless bytes.",
+            });
+        for await (const event of this.output(options)) {
+            if (event.type === "stdout" || event.type === "stderr") {
+                if (event.base64 === undefined)
+                    throw new RuntimeError({
+                        code: "binary_output_unavailable",
+                        status: 502,
+                        message: "The process returned text without its original bytes.",
+                    });
+                const raw = processBytes(event.base64);
+                yield {
+                    type: event.type,
+                    offset: event.offset,
+                    data: Uint8Array.from(raw, (c) => c.charCodeAt(0)),
+                };
+            }
+            else
+                yield event;
+        }
+    }
     /** Waits for the process to end and returns its result. */
     async wait(options = {}) {
         const out = { stdout: "", stderr: "" };
@@ -671,36 +892,76 @@ export class Process {
             processId: this.id,
         };
     }
-    /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
-    async write(data, options = {}) {
-        const bytes = utf8(data);
-        let sent = 0;
-        do {
-            const reply = await this.t.json({
-                method: "POST",
-                path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:write`,
-                body: {
-                    base64: base64(bytes.subarray(sent)),
-                    offset: this.#inputOffset,
-                    ...(options.eof ? { eof: true } : {}),
-                },
-            });
-            sent += reply.offset - this.#inputOffset;
-            this.#inputOffset = reply.offset;
-        } while (sent < bytes.length);
+    /** Sends input. Offsets protect transport retries; signal and timeoutMs cover
+     * the whole logical write, including its queue and backpressure. */
+    write(data, options = {}) {
+        if (options.idempotencyKey !== undefined)
+            return Promise.reject(new RuntimeError({
+                message: "Process input writes do not accept caller idempotency keys; offsets protect transport retries.",
+                code: "unsupported_process_write_option",
+                status: 400,
+            }));
+        // Copy before queuing: callers may reuse their buffer while a previous
+        // write waits for the guest to drain its pipe.
+        const bytes = new Uint8Array(utf8(data));
+        const eof = options.eof === true;
+        const { eof: _eof, ...requestOptions } = options;
+        const scope = requestScope(requestOptions);
+        const write = this.#inputWrites.then(async () => {
+            let sent = 0;
+            let chunkSize = CHUNK;
+            do {
+                scope.check();
+                const chunk = bytes.subarray(sent, sent + chunkSize);
+                const reply = await this.t.json({
+                    method: "POST",
+                    path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:write`,
+                    body: {
+                        base64: base64(chunk),
+                        offset: this.#inputOffset,
+                        ...(eof && sent + chunk.length === bytes.length ? { eof: true } : {}),
+                    },
+                    ...scope.request,
+                });
+                const accepted = reply.offset - this.#inputOffset;
+                if (!Number.isSafeInteger(reply.offset) || accepted < 0 || accepted > chunk.length)
+                    throw new ConnectionError({
+                        message: "The process returned an invalid input offset.",
+                        code: "connection_error",
+                        status: 0,
+                    });
+                sent += accepted;
+                this.#inputOffset = reply.offset;
+                // A slow pipe may take only part of a chunk. Keep later uploads within
+                // that observed capacity instead of resending almost a MiB each time.
+                // Zero is legitimate backpressure: retry a bounded probe at the same
+                // offset without discarding bytes or inventing progress.
+                if (accepted < chunk.length) {
+                    chunkSize = accepted > 0 ? accepted : Math.min(chunkSize, 65_536);
+                    // A full pipe must yield even if a proxy answers immediately; don't
+                    // spin requests while the guest has accepted none of this input.
+                    if (accepted === 0)
+                        await scope.wait(new Promise((resolve) => setTimeout(resolve, 100)));
+                }
+            } while (sent < bytes.length);
+        });
+        this.#inputWrites = write.catch(() => undefined);
+        return scope.wait(write);
     }
-    async kill(signal = "SIGTERM") {
+    async kill(signal = "SIGTERM", options = {}) {
         await this.t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:signal`,
             body: { signal },
+            ...options,
         });
     }
-    async resize(cols, rows) {
+    async resize(cols, rows, options = {}) {
         await this.t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:resize`,
             body: { cols, rows },
+            ...options,
         });
     }
     async refresh() {
@@ -834,6 +1095,8 @@ export class Files {
      * sets its permissions (0o755 for a program); 0o644 when left out. */
     async write(path, data, writeOptions = {}) {
         const { mode, ...options } = writeOptions;
+        const scope = requestScope(options);
+        scope.check();
         const octal = mode === undefined ? undefined : (mode & 0o777).toString(8).padStart(3, "0");
         const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
         if (bytes.length <= CHUNK) {
@@ -844,27 +1107,100 @@ export class Files {
                 path: this.#path("/files/content"),
                 query: { path, ...(octal ? { mode: octal } : {}) },
                 bytes,
-                ...options,
+                ...scope.request,
             });
             return { path, size: bytes.length };
         }
-        const sha256 = await sha256Hex(bytes);
+        const sha256 = await scope.wait(sha256Hex(bytes));
+        return this.#writeUpload(path, {
+            size: bytes.length,
+            sha256,
+            chunkAt: (offset, length) => bytes.subarray(offset, offset + length),
+        }, octal, scope);
+    }
+    /** Uploads byte streams with bounded memory on Node/Bun. Unknown-length
+     * inputs stage once in a private local temporary file; known local files
+     * and Blobs avoid that extra disk copy. Paths are local file paths. */
+    async writeStream(path, input, writeOptions = {}) {
+        const { mode, onProgress, ...options } = writeOptions;
+        if (input instanceof Uint8Array) {
+            const result = await this.write(path, input, {
+                ...options,
+                ...(mode === undefined ? {} : { mode }),
+            });
+            onProgress?.({ bytesSent: result.size });
+            return result;
+        }
+        const scope = requestScope(options);
+        scope.check();
+        if (!globalThis.process
+            ?.versions?.node)
+            throw new RuntimeError({
+                message: "Streamed file uploads require Node or Bun for incremental hashing and private local staging. Use files.write with byte data in a browser.",
+                code: "unsupported_runtime",
+                status: 0,
+            });
+        const { prepareFileSource } = await import("./file-source.js");
+        const source = await prepareFileSource(input, { ...scope, signal: scope.request.signal });
+        let written;
+        try {
+            if (source.size <= CHUNK) {
+                written = await this.write(path, await scope.wait(source.chunkAt(0, source.size)), {
+                    ...scope.request,
+                    ...(mode === undefined ? {} : { mode }),
+                });
+                onProgress?.({ bytesSent: written.size });
+            }
+            else {
+                const octal = mode === undefined ? undefined : (mode & 0o777).toString(8).padStart(3, "0");
+                written = await this.#writeUpload(path, source, octal, scope, onProgress);
+            }
+        }
+        catch (primary) {
+            try {
+                await source.close();
+            }
+            catch (cleanupError) {
+                if (primary === undefined)
+                    throw cleanupError;
+                if (primary instanceof Error && Object.isExtensible(primary)) {
+                    try {
+                        Object.defineProperty(primary, "cleanupError", {
+                            value: cleanupError,
+                            configurable: true,
+                        });
+                    }
+                    catch {
+                        /* Keep the original upload failure. */
+                    }
+                }
+            }
+            throw primary;
+        }
+        // A failed close after a good upload is the call's failure.
+        await source.close();
+        return written;
+    }
+    /** One implementation of atomic, checked chunk uploads for bytes and streams. */
+    async #writeUpload(path, source, octal, scope, onProgress) {
+        const sha256 = source.sha256;
         // A guest journals mutations across operations, not per URL. One logical
         // write therefore owns separate stable keys for each mutation phase.
-        const uploadKey = options.idempotencyKey ?? crypto.randomUUID();
+        const uploadKey = scope.request.idempotencyKey ?? crypto.randomUUID();
         const phaseKeys = new Map();
         for (const phase of ["begin", "legacy-begin", "commit", "chmod", "abort"])
             phaseKeys.set(phase, await sha256Hex(JSON.stringify(["files.write", uploadKey, phase])));
         const phaseOptions = (phase) => ({
-            ...options,
+            ...scope.request,
             idempotencyKey: phaseKeys.get(phase),
         });
         let begin;
+        scope.check();
         try {
             begin = await this.t.json({
                 method: "POST",
                 path: this.#path("/uploads"),
-                body: { path, size: bytes.length, sha256, ...(octal ? { mode: octal } : {}) },
+                body: { path, size: source.size, sha256, ...(octal ? { mode: octal } : {}) },
                 ...phaseOptions("begin"),
             });
         }
@@ -873,114 +1209,293 @@ export class Files {
                 throw error;
             // The API aborted the unsupported transfer before accepting chunks.
             // A different body needs a different key; retain deterministic retries.
+            scope.check();
             begin = await this.t.json({
                 method: "POST",
                 path: this.#path("/uploads"),
-                body: { path, size: bytes.length, sha256 },
+                body: { path, size: source.size, sha256 },
                 ...phaseOptions("legacy-begin"),
             });
         }
-        const commit = () => this.t.json({
-            method: "POST",
-            path: this.#path(`/uploads/${enc(begin.uploadId)}:commit`),
-            body: {},
-            ...phaseOptions("commit"),
-        });
+        // A malformed response does not prove ownership of any transfer to abort.
+        if (typeof begin.uploadId !== "string" || begin.uploadId.length === 0)
+            throw new ConnectionError({
+                message: "The file upload returned no transfer identifier.",
+                code: "connection_error",
+                status: 0,
+            });
+        const commit = () => {
+            scope.check();
+            return this.t.json({
+                method: "POST",
+                path: this.#path(`/uploads/${enc(begin.uploadId)}:commit`),
+                body: {},
+                ...phaseOptions("commit"),
+            });
+        };
         let committed = false;
-        if (begin.replayed) {
-            // A completed commit removed the transfer. Ask its journal before
-            // resending chunks; an incomplete transfer alone is safe to continue.
+        let nextOffset = 0;
+        const stopChunks = new AbortController();
+        const chunkSignal = scope.request.signal
+            ? AbortSignal.any([scope.request.signal, stopChunks.signal])
+            : stopChunks.signal;
+        const chunkScope = requestScope({ ...scope.request, signal: chunkSignal });
+        let bytesSent = 0;
+        let failed = false;
+        let primaryFailure;
+        const worker = async () => {
             try {
-                await commit();
-                committed = true;
+                while (nextOffset < source.size) {
+                    scope.check();
+                    if (stopChunks.signal.aborted)
+                        return;
+                    const offset = nextOffset;
+                    nextOffset += begin.chunkBytes;
+                    const offered = source.chunkAt(offset, Math.min(begin.chunkBytes, source.size - offset));
+                    const chunk = offered instanceof Promise ? await chunkScope.wait(offered) : offered;
+                    chunkScope.check();
+                    if (chunk.length !== Math.min(begin.chunkBytes, source.size - offset))
+                        throw new ConnectionError({
+                            message: "The local upload source returned an incomplete chunk.",
+                            code: "source_changed",
+                            status: 0,
+                        });
+                    const receipt = await this.t.json({
+                        method: "PUT",
+                        path: this.#path(`/uploads/${enc(begin.uploadId)}`),
+                        query: { offset },
+                        bytes: chunk,
+                        ...scope.request,
+                        signal: chunkSignal,
+                        // Offsets and byte hashes make chunk replay safe without mutation keys.
+                        idempotencyKey: undefined,
+                    });
+                    // Parallel receipts report cumulative accepted bytes, not this offset.
+                    if (!Number.isSafeInteger(receipt.received) ||
+                        receipt.received < chunk.length ||
+                        receipt.received > source.size)
+                        throw new ConnectionError({
+                            message: "The file upload returned invalid byte progress.",
+                            code: "connection_error",
+                            status: 0,
+                        });
+                    bytesSent += chunk.length;
+                    onProgress?.({ bytesSent });
+                }
             }
             catch (error) {
-                if (!(error instanceof RuntimeError) || error.code !== "upload_incomplete")
-                    throw error;
-            }
-        }
-        const offsets = [];
-        for (let offset = 0; offset < bytes.length; offset += begin.chunkBytes)
-            offsets.push(offset);
-        let next = 0;
-        const worker = async () => {
-            while (next < offsets.length) {
-                const offset = offsets[next++];
-                await this.t.bytes({
-                    method: "PUT",
-                    path: this.#path(`/uploads/${enc(begin.uploadId)}`),
-                    query: { offset },
-                    bytes: bytes.subarray(offset, offset + begin.chunkBytes),
-                });
+                if (!failed) {
+                    failed = true;
+                    primaryFailure = error;
+                    stopChunks.abort(error);
+                }
+                throw error;
             }
         };
         try {
+            if (!Number.isSafeInteger(begin.chunkBytes) ||
+                begin.chunkBytes <= 0 ||
+                begin.chunkBytes > CHUNK)
+                throw new ConnectionError({
+                    message: "The file upload returned an invalid chunk size.",
+                    code: "connection_error",
+                    status: 0,
+                });
+            if (begin.replayed) {
+                // A completed commit removed the transfer. Ask its journal before
+                // resending chunks; an incomplete transfer alone is safe to continue.
+                try {
+                    await commit();
+                    committed = true;
+                    onProgress?.({ bytesSent: source.size });
+                }
+                catch (error) {
+                    if (!(error instanceof RuntimeError) || error.code !== "upload_incomplete")
+                        throw error;
+                }
+            }
             if (!committed) {
-                await Promise.all(Array.from({ length: Math.min(PARALLEL, offsets.length) }, worker));
+                const workers = Array.from({ length: Math.min(PARALLEL, Math.ceil(source.size / begin.chunkBytes)) }, worker);
+                // Drain every owned in-flight chunk before aborting its transfer.
+                // Promise.all's early rejection could otherwise leave writes racing cleanup.
+                await Promise.allSettled(workers);
+                if (failed)
+                    throw primaryFailure;
                 await commit();
             }
             // An older sandbox image ignores the mode in the upload; set it after.
-            if (octal && begin.mode !== octal)
+            if (octal && begin.mode !== octal) {
+                scope.check();
                 await this.t.json({
                     method: "POST",
                     path: this.#path("/files:chmod"),
                     body: { path, mode: octal },
                     ...phaseOptions("chmod"),
                 });
+            }
         }
         catch (error) {
-            await this.t
-                .json({
-                method: "POST",
-                path: this.#path(`/uploads/${enc(begin.uploadId)}:abort`),
-                body: {},
-                ...phaseOptions("abort"),
-            })
-                .catch(() => undefined);
+            try {
+                await this.t.json({
+                    method: "POST",
+                    path: this.#path(`/uploads/${enc(begin.uploadId)}:abort`),
+                    body: {},
+                    idempotencyKey: phaseKeys.get("abort"),
+                    timeoutMs: 5000,
+                });
+            }
+            catch (cleanupError) {
+                // Keep the original failure; retain cleanup evidence when possible.
+                if (error instanceof Error && Object.isExtensible(error)) {
+                    try {
+                        Object.defineProperty(error, error.cause === undefined ? "cause" : "cleanupError", {
+                            value: cleanupError,
+                            configurable: true,
+                        });
+                    }
+                    catch {
+                        /* A frozen property cannot replace the primary failure. */
+                    }
+                }
+            }
             throw error;
         }
-        return { path, size: bytes.length };
+        return { path, size: source.size };
     }
     /** Directory entries; `depth` goes deeper, `glob` filters (e.g. "**\/*.py"). */
     async list(path = "/workspace", options = {}) {
+        const { signal, timeoutMs, idempotencyKey, ...query } = options;
         return (await this.t.json({
             method: "GET",
             path: this.#path("/files/list"),
-            query: { path, ...options },
+            query: { path, ...query },
+            signal,
+            timeoutMs,
+            idempotencyKey,
         })).data;
     }
     async glob(pattern, root = "/workspace") {
         return this.list(root, { glob: pattern });
     }
-    async stat(path) {
-        return this.t.json({ method: "GET", path: this.#path("/files/stat"), query: { path } });
+    async stat(path, options = {}) {
+        return this.t.json({
+            method: "GET",
+            path: this.#path("/files/stat"),
+            query: { path },
+            ...options,
+        });
     }
-    async exists(path) {
-        return (await this.stat(path)).exists;
+    async exists(path, options = {}) {
+        return (await this.stat(path, options)).exists;
     }
     async mkdir(path, options = {}) {
+        const { parents, ...request } = options;
         await this.t.json({
             method: "POST",
             path: this.#path("/files:mkdir"),
-            body: { path, ...options },
+            body: { path, parents },
+            ...request,
         });
     }
     async remove(path, options = {}) {
+        const { recursive, ...request } = options;
         return (await this.t.json({
             method: "POST",
             path: this.#path("/files:remove"),
-            body: { path, ...options },
+            body: { path, recursive },
+            ...request,
         })).removed;
     }
     async rename(from, to, options = {}) {
+        const { overwrite, ...request } = options;
         await this.t.json({
             method: "POST",
             path: this.#path("/files:rename"),
-            body: { from, to, ...options },
+            body: {
+                from,
+                to,
+                ...(overwrite === undefined ? {} : { overwrite }),
+            },
+            ...request,
         });
     }
+    /** Packs a directory as archive bytes; `gzip: false` returns plain tar.
+     * Exclusions are relative paths, not globs. `user: root` selects guest root. */
+    async archive(path, options = {}) {
+        const { gzip = true, exclude, user, ...request } = options;
+        return this.t.fileBytes({
+            method: "GET",
+            path: this.#path("/files/archive"),
+            query: { path, gzip, ...(exclude ? { exclude } : {}), ...(user ? { user } : {}) },
+            accept: gzip ? "application/gzip" : "application/x-tar",
+            ...request,
+        });
+    }
+    /** Unpacks archive bytes in a directory with the sandbox user's rights by
+     * default; `user: root` explicitly selects root inside this guest. */
+    async unarchive(path, bytes, options = {}) {
+        const { gzip = bytes[0] === 0x1f && bytes[1] === 0x8b, user, ...request } = options;
+        const scope = requestScope(request);
+        scope.check();
+        if (bytes.length <= CHUNK) {
+            await this.t.bytes({
+                method: "PUT",
+                path: this.#path("/files/archive"),
+                query: { path, ...(user ? { user } : {}) },
+                bytes,
+                ...scope.request,
+            });
+            return;
+        }
+        const key = request.idempotencyKey ?? crypto.randomUUID();
+        const phase = async (name) => ({
+            ...scope.request,
+            idempotencyKey: await sha256Hex(JSON.stringify(["files.unarchive", key, name])),
+        });
+        const begin = await this.t.json({
+            method: "POST",
+            path: this.#path("/files/archive/uploads"),
+            body: { path, gzip, ...(user ? { user } : {}) },
+            ...(await phase("begin")),
+        });
+        const upload = (suffix = "") => this.#path(`/files/archive/uploads/${enc(begin.uploadId)}${suffix}`);
+        try {
+            if (!Number.isSafeInteger(begin.chunkBytes) || begin.chunkBytes <= 0)
+                throw new ConnectionError({
+                    message: "The archive upload returned an invalid chunk size.",
+                    code: "connection_error",
+                    status: 0,
+                });
+            for (let offset = 0; offset < bytes.length; offset += begin.chunkBytes) {
+                scope.check();
+                await this.t.bytes({
+                    method: "PUT",
+                    path: upload(),
+                    query: { offset },
+                    bytes: bytes.subarray(offset, offset + begin.chunkBytes),
+                    ...(await phase(`chunk:${offset}`)),
+                });
+            }
+            scope.check();
+            await this.t.json({
+                method: "POST",
+                path: upload(":commit"),
+                body: {},
+                ...(await phase("commit")),
+            });
+        }
+        catch (error) {
+            // Cleanup must still run when the caller's signal/deadline has expired.
+            const idempotencyKey = await sha256Hex(JSON.stringify(["files.unarchive", key, "abort"]));
+            await this.t
+                .json({ method: "POST", path: upload(":abort"), body: {}, idempotencyKey })
+                .catch(() => undefined);
+            throw error;
+        }
+    }
     /** Copies a local file or directory into the sandbox. A directory travels as
-     * one gzipped tar and is unpacked in place. */
+     * one gzipped tar to the API's folder routes, and the sandbox's own `tar`
+     * unpacks it as it arrives, making the folder. */
     async upload(localPath, remotePath) {
         const { stat, readFile } = await import("node:fs/promises");
         const info = await stat(localPath);
@@ -1000,41 +1515,77 @@ export class Files {
         }
         const { packDirectory } = await import("./tar.js");
         const archive = await packDirectory(localPath);
-        // Large writes go only to /workspace (the server refuses others), so the
-        // archive is staged there and removed after unpacking.
-        const staging = `/workspace/.runtime-upload-${crypto.randomUUID()}.tar.gz`;
-        await this.write(staging, archive);
-        const result = await new Sandbox(this.t, { id: this.sandboxId }).exec([
-            "sh",
-            "-c",
-            'mkdir -p "$1" && tar -xpzf "$2" -C "$1"; code=$?; rm -f "$2"; exit $code',
-            "sh",
-            remotePath,
-            staging,
-        ]);
-        if (result.exitCode !== 0)
-            throw new CommandError(result);
+        if (archive.length <= CHUNK) {
+            await this.t.bytes({
+                method: "PUT",
+                path: this.#path("/files/archive"),
+                query: { path: remotePath },
+                bytes: archive,
+            });
+            return;
+        }
+        // Larger: parts in order, each unpacked as it arrives; a part resent
+        // after a lost answer is not written twice.
+        const begin = await this.t.json({
+            method: "POST",
+            path: this.#path("/files/archive/uploads"),
+            body: { path: remotePath, gzip: true },
+        });
+        const upload = (suffix = "") => this.#path(`/files/archive/uploads/${enc(begin.uploadId)}${suffix}`);
+        try {
+            for (let offset = 0; offset < archive.length; offset += begin.chunkBytes)
+                await this.t.bytes({
+                    method: "PUT",
+                    path: upload(),
+                    query: { offset },
+                    bytes: archive.subarray(offset, offset + begin.chunkBytes),
+                });
+            await this.t.json({ method: "POST", path: upload(":commit"), body: {} });
+        }
+        catch (error) {
+            await this.t
+                .json({ method: "POST", path: upload(":abort"), body: {} })
+                .catch(() => undefined);
+            throw error;
+        }
     }
     /** Streams a file to disk through a partial file beside the target, renamed
      * into place only once every byte has arrived: a failed copy never leaves
      * a short file under the name asked for. A short stream is tried again,
      * twice, as a short `read` is. */
-    async #streamTo(remotePath, localPath) {
+    async #streamTo(remotePath, localPath, options = {}) {
+        const scope = requestScope(options);
         const fs = await import("node:fs/promises");
         const partial = `${localPath}.runtime-partial-${crypto.randomUUID().slice(0, 8)}`;
         for (let attempt = 0;; attempt++) {
             try {
-                const stream = await this.readStream(remotePath);
+                scope.check();
+                const stream = await this.readStream(remotePath, scope.request);
                 // The handle is closed before anything else touches the file, so a
                 // failed copy's partial file is really gone when the error returns.
-                const file = await fs.open(partial, "w");
                 try {
-                    for await (const chunk of stream)
-                        await file.write(chunk);
+                    const file = await fs.open(partial, "w");
+                    try {
+                        for await (const chunk of stream) {
+                            let written = 0;
+                            while (written < chunk.length) {
+                                scope.check();
+                                const result = await file.write(chunk.subarray(written));
+                                if (result.bytesWritten === 0)
+                                    throw new Error("The local file accepted no bytes.");
+                                written += result.bytesWritten;
+                            }
+                        }
+                    }
+                    finally {
+                        await file.close();
+                    }
                 }
                 finally {
-                    await file.close();
+                    // Opening or writing the local file can fail before consumption.
+                    await stream.cancel().catch(() => undefined);
                 }
+                scope.check();
                 await fs.rename(partial, localPath);
                 return;
             }
@@ -1048,11 +1599,14 @@ export class Files {
         }
     }
     /** Copies a file or directory out of the sandbox. A file streams to disk,
-     * any size, checked against its length. */
-    async download(remotePath, localPath) {
+     * any size, checked against its length; a directory comes as one tar from
+     * the API's folder route. */
+    async download(remotePath, localPath, options = {}) {
+        const scope = requestScope(options);
+        scope.check();
         const fs = await import("node:fs/promises");
         const paths = await import("node:path");
-        const entry = await this.stat(remotePath);
+        const entry = await this.stat(remotePath, scope.request);
         if (!entry.exists)
             throw new RuntimeError({
                 message: `${remotePath} does not exist.`,
@@ -1061,27 +1615,34 @@ export class Files {
             });
         if (entry.type !== "directory") {
             await fs.mkdir(paths.dirname(localPath), { recursive: true });
-            await this.#streamTo(remotePath, localPath);
+            await this.#streamTo(remotePath, localPath, scope.request);
             return;
         }
-        const staging = `/tmp/.runtime-download-${crypto.randomUUID()}.tar.gz`;
-        const sandbox = new Sandbox(this.t, { id: this.sandboxId });
-        const packed = await sandbox.exec(["tar", "-czf", staging, "-C", remotePath, "."]);
-        if (packed.exitCode !== 0)
-            throw new CommandError(packed);
+        // The sandbox's own `tar` packs it as it streams, and it is unpacked as
+        // it arrives; one cut short is refused and nothing is put in place.
+        const archive = await this.t.fileStream({
+            method: "GET",
+            path: this.#path("/files/archive"),
+            query: { path: remotePath, gzip: true },
+            accept: "application/gzip",
+            ...scope.request,
+        });
+        const { unpackStream } = await import("./tar.js");
         try {
-            const { unpackArchive } = await import("./tar.js");
-            await unpackArchive(await this.read(staging), localPath);
+            await unpackStream(archive, localPath, {
+                signal: scope.request.signal,
+            });
         }
         finally {
-            await this.remove(staging).catch(() => undefined);
+            await archive.cancel().catch(() => undefined);
         }
     }
 }
-export function sandboxPage(t, body, query) {
+export function sandboxPage(t, body, query, options = {}) {
     return new Page(body.data.map((info) => new Sandbox(t, info)), body.nextCursor, async (cursor) => sandboxPage(t, await t.json({
         method: "GET",
         path: "/v1/sandboxes",
         query: Object.assign({}, query, { cursor }),
-    }), query));
+        ...options,
+    }), query, options));
 }