withruntime 0.8.4 → 0.10.0

package/dist/runloop/snapshots.d.ts

@@ -0,0 +1,52 @@
+import type { Runtime } from "../client.js";
+import type { Snapshot, SnapshotOptions } from "../snapshots.js";
+import { type RequestOptions, type LongPollRequestOptions } from "./index.js";
+import { DevboxSnapshotViewsDiskSnapshotsCursorIDPage, PagePromise } from "./pagination.js";
+export interface DevboxSnapshotDiskParams {
+    name?: string | null;
+    metadata?: Record<string, string> | null;
+    commit_message?: string | null;
+}
+export interface DevboxSnapshotView {
+    id: string;
+    create_time_ms: number;
+    metadata: Record<string, string>;
+    source_devbox_id: string;
+    commit_message?: string | null;
+    name?: string | null;
+    size_bytes?: number | null;
+    source_blueprint_id?: string | null;
+}
+export interface DevboxSnapshotAsyncStatusView {
+    status: "in_progress" | "error" | "complete" | "deleted";
+    error_message?: string | null;
+    snapshot?: DevboxSnapshotView | null;
+}
+export interface DiskSnapshotListParams {
+    starting_after?: string;
+    limit?: number;
+    devbox_id?: string;
+    include_total_count?: boolean;
+    source_blueprint_id?: string;
+    [key: `metadata[${string}]`]: string | undefined;
+}
+export declare function requestOptions(value: object): value is RequestOptions;
+export declare function nativeOptions(options: RequestOptions): {
+    signal: AbortSignal | undefined;
+    timeoutMs: number | undefined;
+    idempotencyKey: string | undefined;
+};
+export declare function snapshotOptions(body: DevboxSnapshotDiskParams): SnapshotOptions;
+export declare function snapshotView(snapshot: Snapshot): DevboxSnapshotView;
+export declare class DiskSnapshots {
+    private readonly runtime;
+    constructor(runtime: Runtime);
+    update(id: string, body?: DevboxSnapshotDiskParams, options?: RequestOptions): Promise<DevboxSnapshotView>;
+    update(id: string, options?: RequestOptions): Promise<DevboxSnapshotView>;
+    awaitCompleted(id: string, options?: LongPollRequestOptions): Promise<DevboxSnapshotAsyncStatusView>;
+    queryStatus(id: string, options?: RequestOptions): Promise<DevboxSnapshotAsyncStatusView>;
+    delete(id: string, options?: RequestOptions): Promise<unknown>;
+    list(query?: DiskSnapshotListParams, options?: RequestOptions): PagePromise<DevboxSnapshotView, DevboxSnapshotViewsDiskSnapshotsCursorIDPage<DevboxSnapshotView>>;
+    list(options?: RequestOptions): PagePromise<DevboxSnapshotView, DevboxSnapshotViewsDiskSnapshotsCursorIDPage<DevboxSnapshotView>>;
+    private page;
+}

package/dist/runloop/snapshots.js

@@ -0,0 +1,244 @@
+import { RuntimeError } from "../errors.js";
+import { CompatibilityError, only } from "../compat/core.js";
+import { LongPollAbortError, PollingTimeoutError, MaxAttemptsExceededError, } from "./index.js";
+import { DevboxSnapshotViewsDiskSnapshotsCursorIDPage, PagePromise } from "./pagination.js";
+const PAYLOAD = "compat.runloop.snapshot.";
+export function requestOptions(value) {
+    const keys = Object.keys(value);
+    return (keys.length > 0 && keys.every((key) => ["signal", "timeout", "idempotencyKey"].includes(key)));
+}
+export function nativeOptions(options) {
+    return {
+        signal: options.signal,
+        timeoutMs: options.timeout,
+        idempotencyKey: options.idempotencyKey,
+    };
+}
+export function snapshotOptions(body) {
+    only("Runloop snapshot", body, ["name", "metadata", "commit_message"]);
+    if (body.commit_message != null &&
+        (typeof body.commit_message !== "string" || body.commit_message.length > 1000))
+        throw new TypeError("commit_message must be a string of at most 1000 characters");
+    if (body.name != null && typeof body.name !== "string")
+        throw new TypeError("name must be a string");
+    if (body.metadata != null &&
+        (typeof body.metadata !== "object" ||
+            Array.isArray(body.metadata) ||
+            Object.values(body.metadata).some((value) => typeof value !== "string")))
+        throw new TypeError("metadata must contain string values");
+    // Keep the entire public payload durable, including arbitrary names and the
+    // official 1000-character commit message. Native labels have 256-char values.
+    const payload = JSON.stringify({
+        name: body.name ?? null,
+        metadata: body.metadata ?? {},
+        commit_message: body.commit_message ?? null,
+    });
+    const chunks = [];
+    let chunk = "";
+    for (const character of payload) {
+        if (chunk.length + character.length > 256) {
+            chunks.push(chunk);
+            chunk = "";
+        }
+        chunk += character;
+    }
+    if (chunk)
+        chunks.push(chunk);
+    if (chunks.length > 31)
+        throw new CompatibilityError("Runloop", "snapshot metadata exceeding Runtime's 31 label chunks");
+    const labels = {
+        "compat.provider": "runloop",
+        ...Object.fromEntries(chunks.map((chunk, index) => [`${PAYLOAD}${index.toString().padStart(2, "0")}`, chunk])),
+    };
+    // Match the spine's JSONB text bound, including its spaces between entries.
+    // Count UTF-8 bytes and never split surrogate pairs into invalid JSON strings.
+    const stored = `{${Object.entries(labels)
+        .map(([key, value]) => `${JSON.stringify(key)}: ${JSON.stringify(value)}`)
+        .join(", ")}}`;
+    if (new TextEncoder().encode(stored).length > 4096)
+        throw new CompatibilityError("Runloop", "snapshot metadata exceeding Runtime's 4096-byte label bound");
+    return {
+        mode: "disk",
+        labels,
+    };
+}
+function labelsOf(snapshot) {
+    const value = snapshot.labels;
+    return value && typeof value === "object"
+        ? Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"))
+        : {};
+}
+export function snapshotView(snapshot) {
+    if (snapshot.mode !== "disk")
+        throw new CompatibilityError("Runloop", "using a memory snapshot as a disk snapshot");
+    const labels = labelsOf(snapshot);
+    const packed = Object.keys(labels)
+        .filter((key) => key.startsWith(PAYLOAD))
+        .sort()
+        .map((key) => labels[key])
+        .join("");
+    const body = packed
+        ? JSON.parse(packed)
+        : {
+            name: snapshot.name,
+            metadata: Object.fromEntries(Object.entries(labels).filter(([key]) => !key.startsWith("compat."))),
+        };
+    return {
+        id: snapshot.id,
+        create_time_ms: Date.parse(snapshot.createdAt),
+        metadata: body.metadata ?? {},
+        source_devbox_id: snapshot.sourceSandboxId,
+        commit_message: body.commit_message ?? null,
+        name: body.name ?? null,
+        size_bytes: snapshot.meteredBytes,
+        source_blueprint_id: typeof snapshot.sourceImageId === "string" ? snapshot.sourceImageId : null,
+    };
+}
+export class DiskSnapshots {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async update(id, body = {}, options = {}) {
+        if (requestOptions(body))
+            return this.update(id, {}, body);
+        snapshotOptions(body); // Reject invalid input before any request.
+        for (let attempt = 0;; attempt++) {
+            const current = await this.runtime.snapshots.get(id, nativeOptions(options));
+            const previous = snapshotView(current);
+            const merged = {
+                name: body.name === undefined ? previous.name : body.name,
+                metadata: body.metadata === undefined ? previous.metadata : body.metadata,
+                commit_message: body.commit_message === undefined ? previous.commit_message : body.commit_message,
+            };
+            const labels = snapshotOptions(merged).labels;
+            try {
+                return snapshotView(await this.runtime.snapshots.update(id, { labels, ifLabels: labelsOf(current) }, nativeOptions(options)));
+            }
+            catch (error) {
+                if (!(error instanceof RuntimeError) ||
+                    error.code !== "snapshot_metadata_changed" ||
+                    attempt >= 2)
+                    throw error;
+            }
+        }
+    }
+    async awaitCompleted(id, options = {}) {
+        const timeoutMs = options.longPoll?.timeoutMs ?? options.polling?.timeoutMs;
+        const { maxAttempts, initialDelayMs = 0, pollingIntervalMs = 1000 } = options.polling ?? {};
+        if (options.signal?.aborted)
+            throw new LongPollAbortError("Polling aborted", undefined);
+        for (const [name, value] of Object.entries({ initialDelayMs, pollingIntervalMs, maxAttempts }))
+            if (value !== undefined && (!Number.isFinite(value) || value < 0))
+                throw new Error(`${name} must be non-negative`);
+        if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0))
+            throw new Error("timeoutMs must be positive");
+        const controller = new AbortController();
+        const timer = timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(), timeoutMs);
+        const signal = options.signal
+            ? AbortSignal.any([controller.signal, options.signal])
+            : controller.signal;
+        let lastResult;
+        const delay = (ms) => new Promise((resolve, reject) => {
+            signal.throwIfAborted();
+            const onAbort = () => {
+                clearTimeout(wait);
+                reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
+            };
+            const wait = setTimeout(() => {
+                signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+            let attempts = 0;
+            while (true) {
+                lastResult = await this.queryStatus(id, { ...options, signal });
+                if (lastResult.status === "error")
+                    throw new Error(`Snapshot ${id} failed: ${lastResult.error_message || "Unknown error"}`);
+                if (lastResult.status === "complete" || (maxAttempts === 0 && attempts === 0))
+                    return lastResult;
+                if (maxAttempts !== undefined && attempts === maxAttempts)
+                    throw new MaxAttemptsExceededError(`Polling exceeded maximum attempts (${maxAttempts})`, lastResult);
+                await delay(attempts++ === 0 ? initialDelayMs : pollingIntervalMs);
+            }
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw new LongPollAbortError("Polling aborted", lastResult);
+            if (controller.signal.aborted)
+                throw new PollingTimeoutError(`Polling timed out after ${timeoutMs}ms`, lastResult);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async queryStatus(id, options = {}) {
+        const snapshot = await this.runtime.snapshots.get(id, nativeOptions(options));
+        const view = snapshotView(snapshot);
+        return {
+            status: snapshot.state === "ready"
+                ? "complete"
+                : snapshot.state === "failed"
+                    ? "error"
+                    : snapshot.state === "deleted" || snapshot.state === "deleting"
+                        ? "deleted"
+                        : "in_progress",
+            error_message: snapshot.error,
+            snapshot: view,
+        };
+    }
+    async delete(id, options = {}) {
+        snapshotView(await this.runtime.snapshots.get(id, nativeOptions(options)));
+        await this.runtime.snapshots.delete(id, nativeOptions(options));
+        return {};
+    }
+    list(query = {}, options = {}) {
+        if (requestOptions(query))
+            return this.list({}, query);
+        return new PagePromise(this.page(query, options));
+    }
+    async page(query, options) {
+        options.signal?.throwIfAborted();
+        const filters = Object.entries(query).filter(([key]) => /^metadata\[[^\]]+\](\[in\])?$/.test(key));
+        only("Runloop snapshot list", query, [
+            "starting_after",
+            "limit",
+            "devbox_id",
+            "include_total_count",
+            "source_blueprint_id",
+            ...filters.map(([key]) => key),
+        ]);
+        if (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit <= 0))
+            throw new TypeError("limit must be positive");
+        const values = [];
+        const page = await this.runtime.snapshots.list({ sandboxId: query.devbox_id }, nativeOptions(options));
+        for await (const snapshot of page) {
+            options.signal?.throwIfAborted();
+            if (snapshot.mode !== "disk" || labelsOf(snapshot)["compat.provider"] !== "runloop")
+                continue;
+            const value = snapshotView(snapshot);
+            if (query.source_blueprint_id && value.source_blueprint_id !== query.source_blueprint_id)
+                continue;
+            if (!filters.every(([key, expected]) => {
+                const name = key.slice(9, key.indexOf("]"));
+                return key.endsWith("[in]")
+                    ? typeof expected === "string" &&
+                        expected.split(",").includes(value.metadata[name] ?? "")
+                    : value.metadata[name] === expected;
+            }))
+                continue;
+            values.push(value);
+        }
+        const total = values.length;
+        const offset = query.starting_after
+            ? values.findIndex((value) => value.id === query.starting_after) + 1
+            : 0;
+        if (query.starting_after && offset === 0)
+            throw new TypeError("starting_after does not identify a matching snapshot");
+        const data = values.slice(offset, offset + (query.limit ?? 20));
+        return new DevboxSnapshotViewsDiskSnapshotsCursorIDPage(data, offset + data.length < total, query.include_total_count === false ? 0 : total, (after) => this.page({ ...query, starting_after: after }, options));
+    }
+}

package/dist/sandbox.d.ts

@@ -1,10 +1,14 @@
 import { Page } from "./page.js";
 import { type FileEvent, type WatchHandle, type WatchOptions } from "./products/watch.js";
 import { Transport, type RequestOptions } from "./transport.js";
-import type { CommandResult, ExecOptions, FileEntry, OutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
+import type { CommandResult, DeletedSandbox, ExecOptions, FileEntry, OutputEvent, BinaryOutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 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>;
 /** A running (or stopped) sandbox. Every method is one API call or a short
  * sequence of them; `await using sbx = await Sandbox.create()` stops it for
  * you at the end of the block. */
@@ -63,6 +67,9 @@ export declare class Sandbox implements AsyncDisposable {
             cols?: number;
             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. */
@@ -93,6 +100,11 @@ export declare class Sandbox implements AsyncDisposable {
     pause(options?: RequestOptions & {
         wait?: boolean;
     }): Promise<this>;
+    /** 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. */
+    delete(options?: RequestOptions): Promise<DeletedSandbox>;
     /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
     wake(options?: RequestOptions & {
         wait?: boolean;
@@ -104,6 +116,17 @@ export declare class Sandbox implements AsyncDisposable {
      * fields left out stay as they are. `persistent: true` keeps it running
      * while credit lasts (paid only). */
     update(settings: SandboxSettings, options?: RequestOptions): Promise<this>;
+    /** 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. */
+    switchImage(image: string, options: RequestOptions & {
+        keep: "workspace";
+    }): Promise<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
@@ -190,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;
@@ -211,16 +234,23 @@ export declare class Process {
         cursor?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<OutputEvent>;
+    /** Lossless output for a process spawned with outputEncoding: "base64".
+     * Refuses text-only output rather than inventing bytes that were discarded. */
+    outputBytes(options?: {
+        cursor?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<BinaryOutputEvent>;
     /** Waits for the process to end and returns its result. */
     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 {
@@ -262,6 +292,9 @@ export declare class Files {
             lostBytes: number;
             ended: boolean;
         }>;
+        webhook: (path: string, input?: import("./products/watch.js").WebhookWatchOptions) => Promise<import("./products/watch.js").WatchInfo & {
+            cursor: number;
+        }>;
         stop: (id: string, options?: RequestOptions) => Promise<{
             stopped: boolean;
         }>;
@@ -290,38 +323,65 @@ 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;
         glob?: string;
         hidden?: boolean;
         limit?: number;
-    }): Promise<FileEntry[]>;
+    } & RequestOptions): Promise<FileEntry[]>;
     glob(pattern: string, root?: string): Promise<FileEntry[]>;
-    stat(path: string): Promise<(FileEntry & {
+    stat(path: string, options?: RequestOptions): Promise<(FileEntry & {
         exists: true;
     }) | {
         exists: false;
         path: string;
     }>;
-    exists(path: string): Promise<boolean>;
+    exists(path: string, options?: RequestOptions): Promise<boolean>;
     mkdir(path: string, options?: {
         parents?: boolean;
-    }): Promise<void>;
+    } & RequestOptions): Promise<void>;
     remove(path: string, options?: {
         recursive?: boolean;
-    }): Promise<boolean>;
+    } & RequestOptions): Promise<boolean>;
     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 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. */
     upload(localPath: string, remotePath: string): Promise<void>;
     /** Copies a file or directory out of the sandbox. A file streams to disk,
-     * any size, checked against its length. */
-    download(remotePath: string, localPath: string): Promise<void>;
+     * any size, checked against its length; a directory comes as one tar from
+     * the API's folder route. */
+    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>;