withruntime 0.9.0 → 0.10.0

package/dist/runloop/index.js

@@ -93,10 +93,16 @@ export class Devboxes {
     executions;
     diskSnapshots;
     transitions = new Map();
-    transition(id, operation) {
+    transition(id, operation, signal) {
+        // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
         const pending = (this.transitions.get(id) ?? Promise.resolve())
             .catch(() => undefined)
-            .then(operation);
+            .then(() => {
+            signal?.throwIfAborted();
+            return operation();
+        });
         this.transitions.set(id, pending);
         void pending
             .finally(() => {
@@ -104,7 +110,23 @@ export class Devboxes {
                 this.transitions.delete(id);
         })
             .catch(() => undefined);
-        return pending;
+        if (!signal)
+            return pending;
+        return new Promise((resolve, reject) => {
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+            const abort = () => reject(signal.reason);
+            signal.addEventListener("abort", abort, { once: true });
+            pending.then((value) => {
+                signal.removeEventListener("abort", abort);
+                resolve(value);
+            }, (error) => {
+                signal.removeEventListener("abort", abort);
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- passes the pending call's own failure through unchanged
+                reject(error);
+            });
+            if (signal.aborted)
+                abort();
+        });
     }
     constructor(runtime) {
         this.runtime = runtime;
@@ -112,6 +134,7 @@ export class Devboxes {
         this.diskSnapshots = new DiskSnapshots(runtime);
     }
     async create(input = {}, options = {}) {
+        options.signal?.throwIfAborted();
         only("Runloop", input, [
             "name",
             "metadata",
@@ -153,22 +176,27 @@ export class Devboxes {
             idlePauseSeconds: 0,
             onLeaseEnd: "stop",
         }, input.environment_variables ?? undefined, async (sandbox) => {
-            for (const [path, content] of Object.entries(input.file_mounts ?? {}))
-                await sandbox.files.write(path, content);
+            for (const [path, content] of Object.entries(input.file_mounts ?? {})) {
+                options.signal?.throwIfAborted();
+                await sandbox.files.write(path, content, {
+                    signal: options.signal,
+                    timeoutMs: options.timeout,
+                });
+            }
             for (const command of p.launch_commands ?? [])
                 await sandbox.exec(command, {
-                    ...(await execOptions(sandbox)),
+                    ...(await execOptions(sandbox, { signal: options.signal }, nativeOptions(options))),
                     check: true,
                     signal: options.signal,
                 });
-        });
+        }, nativeOptions(options));
         return view(sandbox);
     }
     createAndAwaitRunning(input, options) {
         return this.create(input, options);
     }
-    async retrieve(id) {
-        return view(await lookup(this.runtime, id));
+    async retrieve(id, options = {}) {
+        return view(await lookup(this.runtime, id, nativeOptions(options)));
     }
     async awaitRunning(id, options = {}) {
         return this.waitForStatus(id, "running", options);
@@ -237,7 +265,13 @@ export class Devboxes {
             throw new TypeError("limit must be positive");
         const values = [];
         let cursor = null;
+        const seenCursors = new Set();
         do {
+            if (cursor !== null) {
+                if (seenCursors.has(cursor))
+                    throw new Error("Pagination returned a repeated cursor");
+                seenCursors.add(cursor);
+            }
             const page = await this.runtime.transport.json({
                 method: "GET",
                 path: "/v1/sandboxes",
@@ -268,9 +302,14 @@ export class Devboxes {
         const data = values.slice(offset, offset + (query.limit ?? 20));
         return new DevboxViewsCursorIDPage(data, offset + data.length < values.length, query.include_total_count === false ? 0 : values.length, (after) => this.listPage({ ...query, starting_after: after }, options));
     }
-    suspend(id) {
+    suspend(id, options = {}) {
+        // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+        if (options.signal?.aborted)
+            return Promise.reject(options.signal.reason);
+        if (options.idempotencyKey !== undefined)
+            return Promise.reject(new CompatibilityError("Runloop", "caller idempotency keys for compound suspend"));
         return this.transition(id, async () => {
-            const s = await lookup(this.runtime, id);
+            const s = await lookup(this.runtime, id, nativeOptions(options));
             if (s.state === "stopped") {
                 if (s.info.persistent && s.info.labels[SUSPENDED] === "true")
                     return view(s);
@@ -278,41 +317,56 @@ export class Devboxes {
             }
             // ARCHITECTURE.md section 10: paid disk persistence must be admitted
             // before stop; an uncertain stop keeps retention enabled to preserve bytes.
-            await s.update({ persistent: true, labels: { ...s.info.labels, [SUSPENDED]: "true" } });
-            await s.stop();
+            await s.update({ persistent: true, labels: { ...s.info.labels, [SUSPENDED]: "true" } }, nativeOptions(options));
+            await s.stop(nativeOptions(options));
             return view(s);
-        });
+        }, options.signal);
     }
-    resume(id) {
+    resume(id, options = {}) {
+        // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+        if (options.signal?.aborted)
+            return Promise.reject(options.signal.reason);
+        if (options.idempotencyKey !== undefined)
+            return Promise.reject(new CompatibilityError("Runloop", "caller idempotency keys for compound resume"));
         return this.transition(id, async () => {
-            const s = await lookup(this.runtime, id);
+            const s = await lookup(this.runtime, id, nativeOptions(options));
             if (s.state === "stopped") {
                 if (!s.info.persistent || s.info.labels[SUSPENDED] !== "true")
                     throw new Error("A shut down Devbox cannot be resumed");
-                await s.restart();
+                await s.restart(nativeOptions(options));
             }
             else if (s.state === "paused" || s.state === "pausing") {
                 // Migrate older adapter pauses through the same disk-only boundary.
-                await s.update({ persistent: true, labels: { ...s.info.labels, [SUSPENDED]: "true" } });
-                await s.stop();
-                await s.restart();
+                await s.update({ persistent: true, labels: { ...s.info.labels, [SUSPENDED]: "true" } }, nativeOptions(options));
+                await s.stop(nativeOptions(options));
+                await s.restart(nativeOptions(options));
             }
             else
-                await s.waitFor("running");
+                await s.waitFor("running", nativeOptions(options));
             if (s.info.labels[SUSPENDED] !== undefined) {
                 const labels = { ...s.info.labels };
                 delete labels[SUSPENDED];
-                await s.update({ labels });
+                await s.update({ labels }, nativeOptions(options));
             }
             return view(s);
-        });
+        }, options.signal);
     }
-    shutdown(id) {
+    shutdown(id, params = {}, options = {}) {
+        if (requestOptions(params))
+            return this.shutdown(id, {}, params);
+        // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+        if (options.signal?.aborted)
+            return Promise.reject(options.signal.reason);
+        if (options.idempotencyKey !== undefined)
+            return Promise.reject(new CompatibilityError("Runloop", "caller idempotency keys for compound shutdown"));
+        only("Runloop shutdown", params, ["force"]);
+        if (params.force !== undefined && params.force !== "false")
+            return Promise.reject(new CompatibilityError("Runloop", "forced shutdown during snapshots"));
         return this.transition(id, async () => {
-            const s = await lookup(this.runtime, id);
-            await destroy(s);
+            const s = await lookup(this.runtime, id, nativeOptions(options));
+            await destroy(s, nativeOptions(options));
             return view(s);
-        });
+        }, options.signal);
     }
     executeSync(id, body, options) {
         return this.executions.executeSync(id, body, options);
@@ -324,13 +378,15 @@ export class Devboxes {
         const execution = await this.executeAsync(id, body, options);
         return this.executions.awaitCompleted(id, execution.execution_id, options);
     }
-    async readFileContents(id, body) {
+    async readFileContents(id, body, options = {}) {
+        options.signal?.throwIfAborted();
         only("Runloop read", body, ["file_path"]);
-        return (await lookup(this.runtime, id)).files.readText(body.file_path);
+        return (await lookup(this.runtime, id, nativeOptions(options))).files.readText(body.file_path, nativeOptions(options));
     }
-    async writeFileContents(id, body) {
+    async writeFileContents(id, body, options = {}) {
+        options.signal?.throwIfAborted();
         only("Runloop write", body, ["file_path", "contents"]);
-        await (await lookup(this.runtime, id)).files.write(body.file_path, body.contents);
+        await (await lookup(this.runtime, id, nativeOptions(options))).files.write(body.file_path, body.contents, nativeOptions(options));
         return result(id, { stdout: "", stderr: "", exitCode: 0, timedOut: false });
     }
     async snapshotDisk(id, body = {}, options = {}) {
@@ -364,52 +420,92 @@ export class Executions {
         only("Runloop execute", body, ["command", "shell_name", "attach_stdin"]);
         if (body.attach_stdin)
             throw new TypeError("attach_stdin requires executeAsync");
-        const s = await lookup(this.runtime, id);
-        return result(id, await s.exec(await shellCommand(s, body.command, body.shell_name), await execOptions(s, {
+        options.signal?.throwIfAborted();
+        const s = await lookup(this.runtime, id, nativeOptions(options));
+        return result(id, await s.exec(await shellCommand(s, body.command, body.shell_name, {}, nativeOptions(options)), await execOptions(s, {
             signal: options.signal,
             timeoutMs: options.timeout,
             idempotencyKey: options.idempotencyKey,
             onStdout: () => { },
-        })));
+        }, nativeOptions(options))));
     }
     async executeAsync(id, body, options = {}) {
         only("Runloop execute", body, ["command", "shell_name", "attach_stdin"]);
         if (body.shell_name && body.attach_stdin)
             throw new CompatibilityError("Runloop", "interactive stdin in a named shell");
-        const s = await lookup(this.runtime, id);
-        const p = await s.spawn(await shellCommand(s, body.command, body.shell_name), {
-            ...(await execOptions(s, { signal: options.signal, idempotencyKey: options.idempotencyKey })),
+        options.signal?.throwIfAborted();
+        const s = await lookup(this.runtime, id, nativeOptions(options));
+        const p = await s.spawn(await shellCommand(s, body.command, body.shell_name, {}, nativeOptions(options)), {
+            ...(await execOptions(s, {
+                signal: options.signal,
+                idempotencyKey: options.idempotencyKey,
+            }, nativeOptions(options))),
             stdin: body.attach_stdin ? "pipe" : undefined,
+            request: nativeOptions(options),
         });
         return { devbox_id: id, execution_id: p.id, status: "running" };
     }
-    async retrieve(id, execution) {
-        const p = await (await lookup(this.runtime, id)).processes.get(execution);
+    async retrieve(id, execution, query = {}, options = {}) {
+        if (requestOptions(query))
+            return this.retrieve(id, execution, {}, query);
+        options.signal?.throwIfAborted();
+        only("Runloop execution retrieve", query, ["last_n"]);
+        if (query.last_n !== undefined)
+            throw new CompatibilityError("Runloop", "execution output tail selection (last_n)");
+        const p = await (await lookup(this.runtime, id, nativeOptions(options))).processes.get(execution, nativeOptions(options));
         return p.info.state === "running"
             ? { devbox_id: id, execution_id: execution, status: "running" }
-            : { ...result(id, await p.wait()), execution_id: execution, status: "completed" };
+            : {
+                ...result(id, await p.wait({ signal: options.signal })),
+                execution_id: execution,
+                status: "completed",
+            };
     }
     async awaitCompleted(id, execution, options = {}) {
-        const p = await (await lookup(this.runtime, id)).processes.get(execution);
+        options.signal?.throwIfAborted();
+        const p = await (await lookup(this.runtime, id, nativeOptions(options))).processes.get(execution, nativeOptions(options));
         return {
             ...result(id, await p.wait({ signal: options.signal })),
             execution_id: execution,
             status: "completed",
         };
     }
-    async kill(id, execution, body = {}) {
+    async kill(id, execution, body = {}, options = {}) {
+        if (requestOptions(body))
+            return this.kill(id, execution, {}, body);
+        options.signal?.throwIfAborted();
         only("Runloop kill", body, ["kill_process_group"]);
         if (body.kill_process_group)
             throw new CompatibilityError("Runloop", "kill_process_group");
-        await (await (await lookup(this.runtime, id)).processes.get(execution)).kill("SIGKILL");
-        return this.retrieve(id, execution);
-    }
-    async sendStdIn(id, execution, body = {}) {
-        const p = await (await lookup(this.runtime, id)).processes.get(execution);
-        if (body.text || body.signal === "EOF")
-            await p.write(body.text ?? "", { eof: body.signal === "EOF" });
-        if (body.signal === "INTERRUPT")
-            await p.kill("SIGINT");
+        await (await (await lookup(this.runtime, id, nativeOptions(options))).processes.get(execution, nativeOptions(options))).kill("SIGKILL", nativeOptions(options));
+        return this.retrieve(id, execution, {}, options);
+    }
+    async sendStdIn(id, execution, body = {}, options = {}) {
+        if (requestOptions(body) &&
+            (body.signal === undefined || (typeof body.signal === "object" && body.signal !== null)))
+            return this.sendStdIn(id, execution, {}, body);
+        options.signal?.throwIfAborted();
+        only("Runloop stdin", body, ["text", "signal"]);
+        const text = "text" in body ? body.text : undefined;
+        const bodySignal = body.signal;
+        if (text !== undefined && text !== null && typeof text !== "string")
+            throw new TypeError("Runloop stdin text must be a string");
+        if (bodySignal !== undefined &&
+            bodySignal !== null &&
+            bodySignal !== "EOF" &&
+            bodySignal !== "INTERRUPT")
+            throw new TypeError("Runloop stdin signal must be EOF or INTERRUPT");
+        if (options.idempotencyKey !== undefined && (text || bodySignal === "EOF"))
+            throw new CompatibilityError("Runloop", "caller idempotency keys for process input; native offsets protect transport retries");
+        const p = await (await lookup(this.runtime, id, nativeOptions(options))).processes.get(execution, nativeOptions(options));
+        if (text || bodySignal === "EOF")
+            await p.write(text ?? "", {
+                eof: bodySignal === "EOF",
+                signal: options.signal,
+                timeoutMs: options.timeout,
+            });
+        if (bodySignal === "INTERRUPT")
+            await p.kill("SIGINT", nativeOptions(options));
         return { devbox_id: id, execution_id: execution, success: true };
     }
     async *streamStdoutUpdates(id, execution, query = {}, options = {}) {
@@ -419,7 +515,8 @@ export class Executions {
         yield* this.stream(id, execution, "stderr", query, options);
     }
     async *stream(id, execution, channel, query, options) {
-        const p = await (await lookup(this.runtime, id)).processes.get(execution);
+        options.signal?.throwIfAborted();
+        const p = await (await lookup(this.runtime, id, nativeOptions(options))).processes.get(execution, nativeOptions(options));
         let offset = 0;
         const from = Number(query.offset ?? 0);
         for await (const event of p.output({ signal: options.signal }))

package/dist/sandbox.d.ts

@@ -5,6 +5,7 @@ import type { CommandResult, DeletedSandbox, ExecOptions, FileEntry, OutputEvent
 import { type SandboxExtensions } from "./products/index.js";
 import type { Snapshot, SnapshotOptions } from "./snapshots.js";
 import { Tunnel, type PortForward } from "./tunnel.js";
+import type { StreamUploadSource } from "./file-source.js";
 /** DELETE /v1/sandboxes/{id}, for `sandbox.delete()` and
  * `runtime.sandboxes.delete(id)`. */
 export declare function deleteSandbox(t: Transport, id: string, options?: RequestOptions): Promise<DeletedSandbox>;
@@ -67,6 +68,8 @@ export declare class Sandbox implements AsyncDisposable {
             rows?: number;
         };
         outputEncoding?: "utf8" | "base64";
+        /** HTTP request options, independently of the process execution deadline. */
+        request?: RequestOptions;
     }): Promise<Process>;
     /** An interactive terminal over a WebSocket. Bytes you write are typed;
      * onData receives what the terminal prints. */
@@ -210,8 +213,8 @@ export declare class Processes {
     private readonly t;
     private readonly sandboxId;
     constructor(t: Transport, sandboxId: string);
-    list(): Promise<ProcessInfo[]>;
-    get(processId: string): Promise<Process>;
+    list(options?: RequestOptions): Promise<ProcessInfo[]>;
+    get(processId: string, options?: RequestOptions): Promise<Process>;
     /** Output events from `cursor` until the process exits, across stream slices. */
     follow(processId: string, options?: {
         cursor?: number;
@@ -241,12 +244,13 @@ export declare class Process {
     wait(options?: {
         signal?: AbortSignal;
     }): Promise<CommandResult>;
-    /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
+    /** Sends input. Offsets protect transport retries; signal and timeoutMs cover
+     * the whole logical write, including its queue and backpressure. */
     write(data: string | Uint8Array, options?: {
         eof?: boolean;
-    }): Promise<void>;
-    kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2"): Promise<void>;
-    resize(cols: number, rows: number): Promise<void>;
+    } & Pick<RequestOptions, "signal" | "timeoutMs">): Promise<void>;
+    kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2", options?: RequestOptions): Promise<void>;
+    resize(cols: number, rows: number, options?: RequestOptions): Promise<void>;
     refresh(): Promise<ProcessInfo>;
 }
 export declare class Terminal {
@@ -319,6 +323,18 @@ export declare class Files {
         path: string;
         size: number;
     }>;
+    /** 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. */
+    writeStream(path: string, input: StreamUploadSource | Uint8Array, writeOptions?: RequestOptions & {
+        mode?: number;
+        onProgress?: (progress: {
+            bytesSent: number;
+        }) => void;
+    }): Promise<{
+        path: string;
+        size: number;
+    }>;
     /** Directory entries; `depth` goes deeper, `glob` filters (e.g. "**\/*.py"). */
     list(path?: string, options?: {
         depth?: number;
@@ -343,6 +359,19 @@ export declare class Files {
     rename(from: string, to: string, options?: {
         overwrite?: boolean;
     } & RequestOptions): Promise<void>;
+    /** Packs a directory as archive bytes; `gzip: false` returns plain tar.
+     * Exclusions are relative paths, not globs. `user: root` selects guest root. */
+    archive(path: string, options?: RequestOptions & {
+        gzip?: boolean;
+        exclude?: string[];
+        user?: "sandbox" | "root";
+    }): Promise<Uint8Array>;
+    /** Unpacks archive bytes in a directory with the sandbox user's rights by
+     * default; `user: root` explicitly selects root inside this guest. */
+    unarchive(path: string, bytes: Uint8Array, options?: RequestOptions & {
+        gzip?: boolean;
+        user?: "sandbox" | "root";
+    }): Promise<void>;
     /** Copies a local file or directory into the sandbox. A directory travels as
      * one gzipped tar to the API's folder routes, and the sandbox's own `tar`
      * unpacks it as it arrives, making the folder. */
@@ -350,9 +379,9 @@ export declare class Files {
     /** Copies a file or directory out of the sandbox. A file streams to disk,
      * any size, checked against its length; a directory comes as one tar from
      * the API's folder route. */
-    download(remotePath: string, localPath: string): Promise<void>;
+    download(remotePath: string, localPath: string, options?: RequestOptions): Promise<void>;
 }
 export declare function sandboxPage(t: Transport, body: {
     data: SandboxInfo[];
     nextCursor: string | null;
-}, query: Record<string, unknown>): Page<Sandbox>;
+}, query: Record<string, unknown>, options?: RequestOptions): Page<Sandbox>;