withruntime 0.3.1 → 0.5.0

package/dist/transport.js

@@ -1,5 +1,6 @@
-import { ConnectionError, errorFor, RuntimeError } from "./errors.js";
-export const VERSION = "0.3.1";
+import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
+import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
+export const VERSION = "0.5.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);
@@ -83,10 +84,14 @@ export class Transport {
     #apiKey;
     #findKey;
     #fetch;
+    /** Whether calls go through envFetch, so a failure can name its proxy. */
+    #routed;
     #timeoutMs;
     #maxRetries;
     #client;
     #slots;
+    /** What `sandboxes.create` waits for room by default. */
+    waitForCapacityMs;
     constructor(options) {
         if (typeof options.apiKey === "function")
             this.#findKey = options.apiKey;
@@ -95,11 +100,15 @@ export class Transport {
         else
             this.#apiKey = options.apiKey;
         this.baseUrl = apiOrigin(options.baseUrl ?? DEFAULT_BASE_URL);
-        this.#fetch = options.fetch ?? fetch;
+        // The environment's proxy (HTTPS_PROXY, NO_PROXY) on Node and Bun alike;
+        // a fetch passed in is used as it is.
+        this.#fetch = options.fetch ?? envFetch;
+        this.#routed = options.fetch === undefined;
         this.#timeoutMs = options.timeoutMs ?? 300_000;
         this.#maxRetries = options.maxRetries ?? 4;
         this.#client = options.client ?? `sdk-js/${VERSION}`;
         this.#slots = slots(Math.max(1, options.maxConnections ?? 32));
+        this.waitForCapacityMs = Math.max(0, options.waitForCapacityMs ?? 120_000);
     }
     /** The key, found once on first use when it was not given. */
     async #key() {
@@ -127,48 +136,83 @@ export class Transport {
     }
     /** Sends a call and returns the raw Response once it succeeded. Retries
      * transport failures, 429, 502, 503 and 504 with backoff and jitter, with
-     * the same key every time. */
+     * the same key every time, and waits out a full house for a call that sets
+     * waitForCapacityMs. */
     async send(call) {
         const apiKey = await this.#key();
         const write = call.method !== "GET";
         const key = write ? (call.idempotencyKey ?? crypto.randomUUID()) : undefined;
-        const deadline = AbortSignal.timeout(call.timeoutMs ?? this.#timeoutMs);
+        // Time spent waiting for room is added to the call's deadline, not taken
+        // from it: once admitted, a create still has its whole timeoutMs.
+        const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
+        const roomUntil = performance.now() + roomMs;
+        let roomAttempt = 0;
+        const deadline = AbortSignal.timeout((call.timeoutMs ?? this.#timeoutMs) + roomMs);
         const signal = call.signal ? AbortSignal.any([call.signal, deadline]) : deadline;
         const url = `${this.baseUrl}${call.path}${encodeQuery(call.query)}`;
         const body = call.bytes ?? (call.body === undefined ? undefined : JSON.stringify(call.body));
         const retry = call.retry ?? true;
         for (let attempt = 0;; attempt++) {
             let response;
+            // Called as a plain function: Cloudflare Workers' fetch throws "Illegal
+            // invocation" when called as a method of another object (this.#fetch()).
+            const send = this.#fetch;
             try {
-                response = await this.#fetch(url, {
+                // "manual", not "error": Workers accept only "follow" and "manual".
+                // The API never redirects, so a redirect is refused here exactly as
+                // "error" refused it: thrown, retried, then a connection_error.
+                response = await send(url, {
                     method: call.method,
                     headers: this.#headers(call, key, apiKey),
-                    redirect: "error",
+                    redirect: "manual",
                     signal,
                     ...(body === undefined ? {} : { body: body }),
                 });
+                if (response.type === "opaqueredirect" ||
+                    (response.status >= 300 && response.status < 400)) {
+                    await response.body?.cancel().catch(() => { });
+                    throw new TypeError(`fetch failed: Runtime answered a redirect (${response.status}).`);
+                }
             }
             catch (cause) {
-                if (signal.aborted || !retry || attempt >= this.#maxRetries)
+                // A proxy variable the SDK cannot use: retrying cannot change it.
+                if (cause instanceof RuntimeError)
+                    throw cause;
+                if (signal.aborted || !retry || attempt >= this.#maxRetries) {
+                    const route = this.#routed && !signal.aborted ? describeRoute(url, cause) : { via: "" };
                     throw new ConnectionError({
                         message: signal.aborted
                             ? "The call was cancelled or ran past its deadline."
                             : write
-                                ? `No answer from Runtime at ${this.baseUrl}. The change may have happened; retrying with the same idempotencyKey is safe.`
-                                : `No answer from Runtime at ${this.baseUrl}.`,
+                                ? `No answer from Runtime at ${this.baseUrl}${route.via}. The change may have happened; retrying with the same idempotencyKey is safe.`
+                                : `No answer from Runtime at ${this.baseUrl}${route.via}.`,
                         hint: signal.aborted
                             ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
-                            : "Check the network, and RUNTIME_API_URL if you set it.",
+                            : (route.hint ?? "Check the network, and RUNTIME_API_URL if you set it."),
                         code: signal.aborted ? "timeout" : "connection_error",
                         status: 0,
                         ...(key ? { idempotencyKey: key } : {}),
                         cause,
                     });
+                }
                 await sleep(backoff(attempt), signal);
                 continue;
             }
             if (response.ok)
                 return response;
+            // Runtime never answers 407: it is a proxy refusing the tunnel, which
+            // Bun's fetch hands back as a response rather than an error.
+            if (response.status === 407 && this.#routed) {
+                await response.body?.cancel();
+                const route = describeRoute(url, 407);
+                throw new ConnectionError({
+                    message: `No answer from Runtime at ${this.baseUrl}${route.via}.`,
+                    code: "connection_error",
+                    status: 0,
+                    ...(route.hint ? { hint: route.hint } : {}),
+                    ...(key ? { idempotencyKey: key } : {}),
+                });
+            }
             const text = await response.text();
             let parsed = null;
             try {
@@ -178,6 +222,19 @@ export class Transport {
                 parsed = { error: { message: text.slice(0, 500) || `HTTP ${response.status}` } };
             }
             const error = errorFor(response.status, parsed, key);
+            // A full house: wait for a slot or for room, then send the same call
+            // again. A request that can never fit (a fork of more copies than the
+            // trial runs) is not waited for.
+            if (retry &&
+                roomMs > 0 &&
+                WAITS_FOR_ROOM.has(error.code) &&
+                error.details?.field !== "count") {
+                const left = roomUntil - performance.now();
+                if (left <= 0)
+                    throw error;
+                await sleep(Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++)), signal);
+                continue;
+            }
             const retryable = [429, 502, 503, 504].includes(response.status) && !DELIBERATE.has(error.code);
             if (!retry || !retryable || attempt >= this.#maxRetries)
                 throw error;
@@ -239,11 +296,9 @@ export class Transport {
     async websocket(path, query) {
         const apiKey = await this.#key();
         const url = `${this.baseUrl.replace(/^http/, "ws")}${path}${encodeQuery(query)}`;
-        const Socket = globalThis.WebSocket;
-        if (!Socket)
-            throw new Error("This runtime has no WebSocket; use Node 22+ or Bun.");
-        return new Socket(url, {
-            headers: { authorization: `Bearer ${apiKey}`, "x-runtime-client": this.#client },
+        return openWebSocket(url, {
+            authorization: `Bearer ${apiKey}`,
+            "x-runtime-client": this.#client,
         });
     }
 }
@@ -259,3 +314,8 @@ export function missingKey() {
 function backoff(attempt) {
     return Math.min(8000, 250 * 2 ** attempt) * (0.5 + Math.random());
 }
+/** Between tries for room: 0.5 s, 1 s, 2 s, 4 s, then every 8 s, jittered, so
+ * a queue of CI jobs spreads out instead of knocking at once. */
+function roomBackoff(attempt) {
+    return Math.min(8000, 500 * 2 ** attempt) * (0.75 + Math.random() * 0.5);
+}

package/dist/tunnel.d.ts

@@ -0,0 +1,67 @@
+/** One TCP connection (or SSH login) inside a tunnel. Set the handlers before
+ * data can arrive, which is as soon as the promise that gave you this resolves. */
+export declare class TunnelStream {
+    #private;
+    private readonly tunnel;
+    readonly id: number;
+    /** Bytes from the sandbox side. */
+    onData?: (data: Uint8Array) => void;
+    /** The sandbox side will send nothing more; you may still write. */
+    onEnd?: () => void;
+    /** The connection is gone. `reason` is "done" after a clean finish. */
+    onClose?: (reason: string) => void;
+    /** sshd's own error output, for an SSH login that fails. */
+    onLog?: (text: string) => void;
+    constructor(tunnel: Tunnel, id: number);
+    /** Sends bytes. Resolves once they are within the tunnel's window, so
+     * awaiting each write is enough backpressure. */
+    write(data: Uint8Array): Promise<void>;
+    /** No more bytes from this side; the sandbox side reads end of input. */
+    end(): void;
+    /** Drops the connection at once. After both sides have ended, the sandbox
+     * finishes it by itself, so a close then would only race the last bytes. */
+    close(): void;
+    /** @internal */
+    receive(kind: number, payload: Uint8Array): void;
+    /** @internal */
+    gone(reason: string): void;
+}
+/** A local port forwarded into the sandbox. */
+export type PortForward = {
+    /** The local address and port that forward (the port the system chose, if you passed 0). */
+    readonly host: string;
+    readonly localPort: number;
+    /** The port inside the sandbox. */
+    readonly port: number;
+    /** Stops listening and closes every forwarded connection. */
+    close(): Promise<void>;
+};
+export declare class Tunnel {
+    #private;
+    private readonly socket;
+    readonly closed: Promise<string>;
+    private constructor();
+    /** Waits for the server's ready message. */
+    static open(socket: WebSocket): Promise<Tunnel>;
+    /** A TCP connection to `port` on the sandbox's loopback (127.0.0.1, then ::1). */
+    connect(port: number): Promise<TunnelStream>;
+    /** An SSH login as the sandbox's user, authorized by this one public key
+     * (the text of an OpenSSH `.pub` file). Speak SSH over the stream. */
+    ssh(publicKey: string): Promise<TunnelStream>;
+    /** Listens on a local port and carries each connection to `port` in the
+     * sandbox. Node and Bun only. */
+    forward(port: number, options?: {
+        localPort?: number;
+        host?: string;
+    }): Promise<PortForward>;
+    /** Closes the tunnel and every connection in it. */
+    close(): void;
+    /** @internal Data for one stream, within the window. */
+    send(id: number, data: Uint8Array): Promise<void>;
+    /** @internal End or close, in order behind any data still waiting. */
+    control(kind: number, id: number): Promise<void>;
+    /** @internal */
+    forget(id: number): void;
+    private receive;
+    private end;
+}

package/dist/tunnel.js

@@ -0,0 +1,311 @@
+import { RuntimeError } from "./errors.js";
+/* A tunnel into a sandbox: one WebSocket carrying many TCP connections to
+   ports on the sandbox's loopback, and SSH logins. The server end and the
+   protocol are documented in packages/cloud/src/api/tunnels.ts. */
+const OPEN = 0x6f;
+const DATA = 0x64;
+const END = 0x65;
+const CLOSE = 0x63;
+const ACK = 0x61;
+const LOG = 0x6c;
+/** Data this side may send past the sandbox's last report of what it took. */
+const WINDOW = 1_048_576;
+const CHUNK = 65_536;
+function frame(kind, stream, payload = new Uint8Array()) {
+    const out = new Uint8Array(5 + payload.length);
+    out[0] = kind;
+    new DataView(out.buffer).setUint32(1, stream);
+    out.set(payload, 5);
+    return out;
+}
+/** One TCP connection (or SSH login) inside a tunnel. Set the handlers before
+ * data can arrive, which is as soon as the promise that gave you this resolves. */
+export class TunnelStream {
+    tunnel;
+    id;
+    /** Bytes from the sandbox side. */
+    onData;
+    /** The sandbox side will send nothing more; you may still write. */
+    onEnd;
+    /** The connection is gone. `reason` is "done" after a clean finish. */
+    onClose;
+    /** sshd's own error output, for an SSH login that fails. */
+    onLog;
+    #ended = false;
+    #remoteEnded = false;
+    #closed = false;
+    constructor(tunnel, id) {
+        this.tunnel = tunnel;
+        this.id = id;
+    }
+    /** Sends bytes. Resolves once they are within the tunnel's window, so
+     * awaiting each write is enough backpressure. */
+    write(data) {
+        if (this.#ended || this.#closed)
+            return Promise.resolve();
+        return this.tunnel.send(this.id, data);
+    }
+    /** No more bytes from this side; the sandbox side reads end of input. */
+    end() {
+        if (this.#ended || this.#closed)
+            return;
+        this.#ended = true;
+        void this.tunnel.control(END, this.id);
+    }
+    /** Drops the connection at once. After both sides have ended, the sandbox
+     * finishes it by itself, so a close then would only race the last bytes. */
+    close() {
+        if (this.#closed)
+            return;
+        const finishing = this.#ended && this.#remoteEnded;
+        this.#closed = true;
+        if (!finishing)
+            void this.tunnel.control(CLOSE, this.id);
+        this.tunnel.forget(this.id);
+    }
+    /** @internal */
+    receive(kind, payload) {
+        if (kind === DATA)
+            this.onData?.(payload);
+        else if (kind === LOG)
+            this.onLog?.(new TextDecoder().decode(payload));
+        else if (kind === END) {
+            this.#remoteEnded = true;
+            this.onEnd?.();
+        }
+        else if (kind === CLOSE)
+            this.gone(new TextDecoder().decode(payload) || "closed");
+    }
+    /** @internal */
+    gone(reason) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.tunnel.forget(this.id);
+        this.onClose?.(reason);
+    }
+}
+export class Tunnel {
+    socket;
+    closed;
+    #streams = new Map();
+    #opening = new Map();
+    #next = 1;
+    #sent = 0;
+    #credited = 0;
+    #waiting = [];
+    #sending = Promise.resolve();
+    #over;
+    constructor(socket, closed) {
+        this.socket = socket;
+        this.closed = closed;
+    }
+    /** Waits for the server's ready message. */
+    static open(socket) {
+        socket.binaryType = "arraybuffer";
+        let settle;
+        const closed = new Promise((resolve) => (settle = resolve));
+        return new Promise((resolve, reject) => {
+            let tunnel;
+            let failure;
+            socket.onmessage = (event) => {
+                if (typeof event.data === "string") {
+                    const message = JSON.parse(event.data);
+                    if (message.type === "ready" && !tunnel) {
+                        tunnel = new Tunnel(socket, closed);
+                        resolve(tunnel);
+                    }
+                    else if (message.type === "error") {
+                        failure = new RuntimeError({
+                            message: message.error?.message ?? "The tunnel failed.",
+                            code: message.error?.code ?? "tunnel_failed",
+                            status: 0,
+                            ...(message.error?.hint ? { hint: message.error.hint } : {}),
+                            ...(message.error?.requestId ? { requestId: message.error.requestId } : {}),
+                        });
+                        if (!tunnel)
+                            reject(failure);
+                    }
+                }
+                else
+                    tunnel?.receive(new Uint8Array(event.data));
+            };
+            socket.onclose = () => {
+                const reason = failure?.message ?? "The tunnel closed.";
+                tunnel?.end(reason);
+                settle(reason);
+                if (!tunnel)
+                    reject(new RuntimeError({
+                        message: "The tunnel could not be opened: check the key, that the sandbox is running, and that your organization has fewer than 16 tunnels open.",
+                        code: "tunnel_refused",
+                        status: 0,
+                    }));
+            };
+            socket.onerror = () => undefined;
+        });
+    }
+    /** A TCP connection to `port` on the sandbox's loopback (127.0.0.1, then ::1). */
+    connect(port) {
+        if (!Number.isSafeInteger(port) || port < 1 || port > 65_535)
+            return Promise.reject(new RuntimeError({
+                message: "port must be 1 to 65535.",
+                code: "invalid_request",
+                status: 0,
+            }));
+        return this.#open(`tcp ${port}`, port);
+    }
+    /** An SSH login as the sandbox's user, authorized by this one public key
+     * (the text of an OpenSSH `.pub` file). Speak SSH over the stream. */
+    ssh(publicKey) {
+        return this.#open(`ssh ${publicKey.trim()}`);
+    }
+    /** Listens on a local port and carries each connection to `port` in the
+     * sandbox. Node and Bun only. */
+    async forward(port, options = {}) {
+        const net = await import("node:net");
+        const host = options.host ?? "127.0.0.1";
+        const sockets = new Set();
+        // Half-open: a client that ends its input still gets the answer.
+        const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+            sockets.add(socket);
+            socket.pause();
+            socket.on("error", () => undefined);
+            socket.on("close", () => sockets.delete(socket));
+            this.connect(port).then((stream) => {
+                stream.onData = (data) => void socket.write(data);
+                stream.onEnd = () => void socket.end();
+                // "done" follows the last data; ending lets the socket flush it.
+                stream.onClose = (reason) => void (reason === "done" ? socket.end() : socket.destroy());
+                socket.on("data", (data) => {
+                    socket.pause();
+                    void stream.write(new Uint8Array(data)).then(() => socket.resume());
+                });
+                socket.on("end", () => stream.end());
+                socket.on("close", () => stream.close());
+                socket.resume();
+            }, () => socket.destroy());
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.localPort ?? port, host, () => resolve());
+        });
+        const address = server.address();
+        return {
+            host,
+            localPort: typeof address === "object" && address ? address.port : (options.localPort ?? port),
+            port,
+            close: () => new Promise((resolve) => {
+                for (const socket of sockets)
+                    socket.destroy();
+                server.close(() => resolve());
+            }),
+        };
+    }
+    /** Closes the tunnel and every connection in it. */
+    close() {
+        this.socket.close(1000);
+    }
+    #open(target, port) {
+        if (this.#over)
+            return Promise.reject(new RuntimeError({ message: this.#over, code: "tunnel_closed", status: 0 }));
+        const id = this.#next++;
+        return new Promise((resolve, reject) => {
+            this.#opening.set(id, {
+                resolve,
+                reject: (error) => reject(port !== undefined && error.message === "closed"
+                    ? new RuntimeError({
+                        message: `Nothing is listening on port ${port} in the sandbox.`,
+                        code: "port_closed",
+                        status: 0,
+                        hint: "Start the server first, and let it listen on 127.0.0.1, ::1 or every address.",
+                    })
+                    : error.message === "reserved"
+                        ? new RuntimeError({
+                            message: `Port ${port} is the sandbox's own outbound proxy, which a tunnel does not reach.`,
+                            code: "port_reserved",
+                            status: 0,
+                        })
+                        : error.message === "no-sshd"
+                            ? new RuntimeError({
+                                message: "The sandbox has no OpenSSH server (sshd).",
+                                code: "sshd_missing",
+                                status: 0,
+                                hint: "Install it once: sudo apt-get install -y openssh-server",
+                            })
+                            : new RuntimeError({
+                                message: `The sandbox refused the connection (${error.message}).`,
+                                code: "tunnel_refused",
+                                status: 0,
+                            })),
+            });
+            this.#write(frame(OPEN, id, new TextEncoder().encode(target)));
+        });
+    }
+    /** @internal Data for one stream, within the window. */
+    send(id, data) {
+        const sending = this.#sending.then(async () => {
+            for (let at = 0; at < data.length && !this.#over; at += CHUNK) {
+                const piece = data.subarray(at, at + CHUNK);
+                while (this.#sent + piece.length - this.#credited > WINDOW && !this.#over)
+                    await new Promise((resolve) => this.#waiting.push(resolve));
+                if (this.#over)
+                    return;
+                this.#sent += piece.length;
+                this.#write(frame(DATA, id, piece));
+            }
+        });
+        this.#sending = sending.catch(() => undefined);
+        return sending;
+    }
+    /** @internal End or close, in order behind any data still waiting. */
+    control(kind, id) {
+        const sending = this.#sending.then(() => this.#write(frame(kind, id)));
+        this.#sending = sending.catch(() => undefined);
+        return sending;
+    }
+    /** @internal */
+    forget(id) {
+        this.#streams.delete(id);
+    }
+    #write(bytes) {
+        if (!this.#over && this.socket.readyState === 1)
+            this.socket.send(bytes);
+    }
+    receive(message) {
+        if (message.length < 5)
+            return;
+        const kind = message[0];
+        const view = new DataView(message.buffer, message.byteOffset, message.length);
+        const id = view.getUint32(1);
+        const payload = message.subarray(5);
+        if (kind === ACK) {
+            this.#credited = Math.max(this.#credited, Number(view.getBigUint64(5)));
+            for (const wake of this.#waiting.splice(0))
+                wake();
+            return;
+        }
+        const opening = this.#opening.get(id);
+        if (opening) {
+            this.#opening.delete(id);
+            if (kind === OPEN) {
+                const stream = new TunnelStream(this, id);
+                this.#streams.set(id, stream);
+                opening.resolve(stream);
+            }
+            else
+                opening.reject(new Error(new TextDecoder().decode(payload) || "closed"));
+            return;
+        }
+        this.#streams.get(id)?.receive(kind, payload);
+    }
+    end(reason) {
+        this.#over = reason;
+        for (const wake of this.#waiting.splice(0))
+            wake();
+        for (const { reject } of this.#opening.values())
+            reject(new Error(reason));
+        this.#opening.clear();
+        for (const stream of [...this.#streams.values()])
+            stream.gone(reason);
+    }
+}

package/dist/types.d.ts

@@ -16,6 +16,16 @@ export type SandboxInfo = {
     cpuFloorMillis: number;
     pausable: boolean;
     timeoutSeconds: number;
+    /** Pauses after this many idle seconds; 0 is never. */
+    idlePauseSeconds?: number;
+    /** True for the default idle pause, which pauses only a sandbox nothing has used yet. */
+    idlePauseUnusedOnly?: boolean;
+    /** A request (exec, files, terminal, a visit to a shared port) wakes it when paused. */
+    autoWake?: boolean;
+    /** Its lease renews itself while credit lasts, and its disk is kept after a stop. */
+    persistent?: boolean;
+    /** The last exec, file, terminal, desktop or preview request, to within a minute. */
+    lastActiveAt?: string | null;
     onLeaseEnd: "pause" | "stop";
     createdAt: string;
     readyAt: string | null;
@@ -28,6 +38,16 @@ export type SandboxInfo = {
     heldMicros: number;
     simulated?: boolean;
     replayed?: boolean;
+    /** On a create from an image with a start command: whether it started,
+     * became ready (readyMs), timed out, or exited first. */
+    start?: {
+        state: "started" | "ready" | "timeout" | "exited" | "not_running";
+        processId?: string;
+        exitCode?: number | null;
+        readyMs?: number;
+    };
+    /** Present and true when getOrCreate answered a sandbox that already held the name. */
+    reused?: boolean;
     [key: string]: unknown;
 };
 export type CreateSandbox = {
@@ -46,6 +66,18 @@ export type CreateSandbox = {
     pausable?: boolean;
     /** What happens when timeoutSeconds runs out: "pause" (default) or "stop". */
     onLeaseEnd?: "pause" | "stop";
+    /** Pause after this many seconds with no exec, file, terminal, desktop or
+     * preview request (60 to 86400; 0 never). A request wakes it again. */
+    idlePauseSeconds?: number;
+    /** A request to a paused sandbox wakes it. Default true. */
+    autoWake?: boolean;
+    /** Keep it running while credit lasts (its lease renews itself) and keep its
+     * disk after a stop, for restart(). Paid only. */
+    persistent?: boolean;
+    /** The most it may cost over its whole life, in microdollars. */
+    maxTotalCostMicros?: number;
+    /** With name: return the sandbox that already has the name, woken if paused. */
+    getOrCreate?: boolean;
     maxCostMicros?: number;
     /** Network rules from the first start; the same shape as sandbox.network.set.
      * Omit for the public web on ports 80 and 443. */
@@ -55,7 +87,9 @@ export type CreateSandbox = {
         deny?: string[];
         connect?: string[];
     };
-    /** A ready image's id (runtime.images.build); the sandbox starts from it. */
+    /** A ready image (runtime.images.build): its id, name (its latest tag),
+     * name:tag or name@version. When the image has a start command, create
+     * answers once its ready check passes and says how in `start`. */
     image?: string;
     /** A ready snapshot's id: the sandbox starts as a copy of it, with its shape. Not with image. */
     snapshot?: string;
@@ -173,3 +207,25 @@ export type Usage = {
     [key: string]: unknown;
 };
 export type FeedbackKind = "bug" | "missing_feature" | "competitor_gap" | "migration_blocker" | "docs" | "pricing" | "praise" | "other";
+/** What `sandbox.update()` changes; fields left out stay as they are. */
+export type SandboxSettings = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** A request to a paused sandbox wakes it. */
+    autoWake?: boolean;
+    /** Pause after this many seconds with no activity, counted from now; 0 never. */
+    idlePauseSeconds?: number;
+    /** Keep it running while credit lasts and keep its disk after a stop. Paid only. */
+    persistent?: boolean;
+    /** Lifetime cap in microdollars; null removes it. */
+    maxTotalCostMicros?: number | null;
+};
+/** How `sandbox.keepAlive()` extends the lease. */
+export type KeepAliveOptions = {
+    /** How often it checks, in seconds. Default 60. */
+    everySeconds?: number;
+    /** How much lease it keeps ahead of now, in seconds (60 to 3600). Default 600. */
+    marginSeconds?: number;
+    /** Called with an error an extension met; the loop carries on. */
+    onError?: (error: unknown) => void;
+};