withruntime 0.11.1 → 0.11.2

package/dist/sandbox.d.ts

@@ -1,27 +1,25 @@
-import { Page } from "./page.js";
+import type { 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, DeletedSandbox, ExecOptions, FileEntry, OutputEvent, BinaryOutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
+import type { CommandResult, DeletedSandbox, ExecOptions, FileEntry, OutputEvent, BinaryOutputEvent, 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>;
+import { Machine, type MachineProduct } from "./machine.js";
+/** Sandboxes, as a product of the machine engine (machine.ts). */
+export declare const SANDBOXES: MachineProduct;
 /** 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. */
 export interface Sandbox extends SandboxExtensions {
 }
-export declare class Sandbox implements AsyncDisposable {
+export declare class Sandbox extends Machine<SandboxInfo, SandboxSettings, DeletedSandbox> {
     #private;
     readonly files: Files;
     readonly processes: Processes;
     /** Short-lived tokens that let a browser reach this sandbox directly. */
     readonly sessions: SandboxSessions;
     constructor(transport: Transport, info: SandboxInfo);
-    get id(): string;
     /** A sandbox reached with a session token instead of an API key, for code in
      * a browser: commands and their streams, processes, files and previews of
      * this one sandbox. Makes no call; `info` holds only the id until
@@ -39,14 +37,6 @@ export declare class Sandbox implements AsyncDisposable {
         apiUrl?: string;
         fetch?: typeof fetch;
     }): Sandbox;
-    /** What the API last said about this sandbox. `refresh()` asks again. */
-    get info(): SandboxInfo;
-    get state(): SandboxInfo["state"];
-    refresh(options?: RequestOptions): Promise<this>;
-    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
-    waitFor(state: "running" | "paused" | "stopped", options?: {
-        timeoutSeconds?: number;
-    } & RequestOptions): Promise<this>;
     /** Runs a command and returns its exit code and output. A string runs under
      * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
      * streams as it happens. A timeout is a result (timedOut: true, the output so
@@ -94,76 +84,6 @@ export declare class Sandbox implements AsyncDisposable {
         localPort?: number;
         host?: string;
     }): Promise<PortForward>;
-    stop(options?: RequestOptions & {
-        wait?: boolean;
-    }): Promise<this>;
-    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; for one with a time limit,
-     * `timeoutSeconds` is its new one. */
-    wake(options?: RequestOptions & {
-        wait?: boolean;
-        timeoutSeconds?: number;
-    }): Promise<this>;
-    /** More time before its time limit ends (at most an hour ahead of now). A
-     * sandbox with no time limit needs none: the call answers at once and
-     * changes nothing. */
-    extend(seconds: number, options?: RequestOptions): Promise<this>;
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * 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; 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. `keep` is optional:
-     * "workspace" is the only value, and it is sent either way, so an API from
-     * before it was optional accepts the call too. */
-    switchImage(image: string, options?: RequestOptions & {
-        keep?: "workspace";
-    }): Promise<this>;
-    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
-     * whole disk, volumes, environment, name and previews stay, and its
-     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
-     * persistent, and comes back running at the new size on the same server; a
-     * paused or stopped one is started. Memory bills on the new size from then.
-     * Refused, with nothing changed, when the server has no room
-     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
-     * while a snapshot or fork of it is being taken. `restart` is optional:
-     * true is the only value, and it is sent either way, so an API from before
-     * it was optional accepts the call too. */
-    resize(size: {
-        vcpu?: number;
-        memoryMiB?: number;
-    }, options?: RequestOptions & {
-        restart?: true;
-    }): Promise<this>;
-    /** Keeps a sandbox with a time limit running past it, in the background,
-     * until stop() or the returned function ends it: every `everySeconds` (60)
-     * it extends the limit so that `marginSeconds` (600) remain, never more
-     * than the hour ahead the API allows. A sandbox with no time limit
-     * (`endsAt` null) needs none, and is only watched. Running time is billed
-     * as it is used. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
-     * Node or Bun process alive by itself. */
-    keepAlive(options?: KeepAliveOptions): () => void;
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
-    setRetention(days: number, options?: RequestOptions): Promise<this>;
-    /** Keeps this sandbox's whole machine (files, memory, running processes) as
-     * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. Past
-     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
-     * the error names the snapshot. */
-    snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
     /** Copies of this sandbox as it is now (files, memory, running processes),
      * each its own sandbox, answered once they run. A running sandbox is paused
      * for the moment its snapshot takes, then woken. One without `count`; an
@@ -182,12 +102,6 @@ export declare class Sandbox implements AsyncDisposable {
         keepSnapshot?: boolean;
         funding?: "trial" | "paid";
     } & RequestOptions): Promise<Sandbox[]>;
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
-    restart(options?: RequestOptions & {
-        wait?: boolean;
-    }): Promise<this>;
-    [Symbol.asyncDispose](): Promise<void>;
-    toJSON(): SandboxInfo;
 }
 /** A sandbox session, as the API answers it. `token` is set only in the
  * answer to `create`. */
@@ -411,6 +325,7 @@ export declare class Files {
      * the API's folder route. */
     download(remotePath: string, localPath: string, options?: RequestOptions): Promise<void>;
 }
+/** One page of `runtime.sandboxes.list()`, and the pages after it. */
 export declare function sandboxPage(t: Transport, body: {
     data: SandboxInfo[];
     nextCursor: string | null;

package/dist/sandbox.js

@@ -1,13 +1,13 @@
-import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
+import { STREAMED_EXEC_TIMEOUT_MS } from "./api-defaults.js";
 import { CommandError, ConnectionError, DELIBERATE, errorFor, NotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "./errors.js";
-import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
 import { Transport } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
 import { pause } from "./wait.js";
-/** How long snapshot() waits, pause and capture together, unless told. */
-const SNAPSHOT_DEADLINE_MS = 10 * 60_000;
+import { Machine, machinePage, requestOnly } from "./machine.js";
+/** Sandboxes, as a product of the machine engine (machine.ts). */
+export const SANDBOXES = { plural: "sandboxes", noun: "Sandbox" };
 const CHUNK = 1_048_576;
 /** Chunks of a large write in flight at once. Each chunk's reply waits on the
  * API and the guest, and the link idles while every chunk in flight waits:
@@ -59,15 +59,6 @@ function requestScope(options) {
     };
     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. */
@@ -97,26 +88,21 @@ function commandBody(command, options) {
     };
 }
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
-export class Sandbox {
-    #info;
-    #keepAlive;
+export class Sandbox extends Machine {
     #t;
     files;
     processes;
     /** Short-lived tokens that let a browser reach this sandbox directly. */
     sessions;
     constructor(transport, info) {
+        super(SANDBOXES, transport, info);
         this.#t = transport;
-        this.#info = info;
         this.files = new Files(transport, info.id);
         this.processes = new Processes(transport, info.id);
         this.sessions = new SandboxSessions(transport, info.id);
         for (const [name, make] of sandboxFactories())
             Object.defineProperty(this, name, { value: make(transport, this), enumerable: false });
     }
-    get id() {
-        return this.#info.id;
-    }
     /** A sandbox reached with a session token instead of an API key, for code in
      * a browser: commands and their streams, processes, files and previews of
      * this one sandbox. Makes no call; `info` holds only the id until
@@ -141,41 +127,6 @@ 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;
-    }
-    get state() {
-        return this.#info.state;
-    }
-    async refresh(options = {}) {
-        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.#keep(await this.#t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${enc(this.id)}`,
-            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
      * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
      * streams as it happens. A timeout is a result (timedOut: true, the output so
@@ -368,275 +319,6 @@ export class Sandbox {
             throw error;
         }
     }
-    async stop(options = {}) {
-        this.#keepAlive?.();
-        return this.#lifecycle("stop", options);
-    }
-    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; for one with a time limit,
-     * `timeoutSeconds` is its new one. */
-    async wake(options = {}) {
-        const { timeoutSeconds, ...rest } = options;
-        try {
-            return await this.#lifecycle("wake", rest, timeoutSeconds === undefined ? {} : { timeoutSeconds });
-        }
-        catch (error) {
-            // Waking one that is already awake is done, not a mistake. With a new
-            // lease asked for, the refusal stands: it was not given.
-            if (!(error instanceof RuntimeError) || error.code !== "not_paused" || timeoutSeconds)
-                throw error;
-            await this.refresh(requestOnly(rest));
-            if (this.state !== "running" && this.state !== "starting")
-                throw error;
-            return this;
-        }
-    }
-    /** More time before its time limit ends (at most an hour ahead of now). A
-     * sandbox with no time limit needs none: the call answers at once and
-     * changes nothing. */
-    async extend(seconds, options = {}) {
-        return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
-    }
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * fields left out stay as they are. `persistent: true` keeps it running
-     * while credit lasts (paid only). */
-    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; 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. `keep` is optional:
-     * "workspace" is the only value, and it is sent either way, so an API from
-     * before it was optional accepts the call too. */
-    async switchImage(image, options = {}) {
-        const { keep = "workspace", ...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,
-            ...requestOnly(rest),
-        }));
-        return this;
-    }
-    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
-     * whole disk, volumes, environment, name and previews stay, and its
-     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
-     * persistent, and comes back running at the new size on the same server; a
-     * paused or stopped one is started. Memory bills on the new size from then.
-     * Refused, with nothing changed, when the server has no room
-     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
-     * while a snapshot or fork of it is being taken. `restart` is optional:
-     * true is the only value, and it is sent either way, so an API from before
-     * it was optional accepts the call too. */
-    async resize(size, options = {}) {
-        const { restart = true, ...rest } = options;
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:resize`,
-            body: { ...size, restart },
-            // A pause or stop and a cold boot.
-            wait: 120,
-            ...requestOnly(rest),
-        }));
-        return this;
-    }
-    /** Keeps a sandbox with a time limit running past it, in the background,
-     * until stop() or the returned function ends it: every `everySeconds` (60)
-     * it extends the limit so that `marginSeconds` (600) remain, never more
-     * than the hour ahead the API allows. A sandbox with no time limit
-     * (`endsAt` null) needs none, and is only watched. Running time is billed
-     * as it is used. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
-     * Node or Bun process alive by itself. */
-    keepAlive(options = {}) {
-        this.#keepAlive?.();
-        const every = Math.max(10, options.everySeconds ?? 60) * 1000;
-        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? KEEP_ALIVE_MARGIN_SECONDS));
-        let ended = false;
-        let timer;
-        const end = () => {
-            ended = true;
-            if (timer)
-                clearTimeout(timer);
-            if (this.#keepAlive === end)
-                this.#keepAlive = undefined;
-        };
-        const tick = async () => {
-            if (ended)
-                return;
-            try {
-                await this.refresh();
-                if (this.state === "stopped" || this.state === "stopping")
-                    return end();
-                // No time limit: nothing to extend (an older server sends no endsAt).
-                if (this.state === "running" && this.info.endsAt !== null) {
-                    const left = (Date.parse(this.info.endsAt ?? this.info.expiresAt) - Date.now()) / 1000;
-                    const need = Math.ceil(margin - left);
-                    if (need >= 1)
-                        await this.extend(Math.min(3600, need));
-                }
-            }
-            catch (error) {
-                options.onError?.(error);
-            }
-            if (ended)
-                return;
-            timer = setTimeout(() => void tick(), every);
-            timer.unref?.();
-        };
-        this.#keepAlive = end;
-        void tick();
-        return end;
-    }
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
-    async setRetention(days, options = {}) {
-        return this.#lifecycle("retention", { ...options, wait: false }, { days });
-    }
-    /** Keeps this sandbox's whole machine (files, memory, running processes) as
-     * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. Past
-     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
-     * the error names the snapshot. */
-    async snapshot(options = {}) {
-        const { idempotencyKey, signal, timeoutMs, ...body } = options;
-        if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
-            throw new TypeError("Snapshot mode must be memory or disk.");
-        signal?.throwIfAborted();
-        // One minute, whatever `timeoutMs` said, was too short: pausing a busy
-        // 16 vCPU, 32 GiB sandbox writes its memory out first (4 October 2026).
-        const until = performance.now() + (timeoutMs && timeoutMs > 0 ? timeoutMs : SNAPSHOT_DEADLINE_MS);
-        let running = false;
-        /** The capture in progress, once the server has one. */
-        let capturing;
-        let late = false;
-        const request = () => {
-            signal?.throwIfAborted();
-            const left = Math.ceil(until - performance.now());
-            if (left <= 0 && capturing) {
-                late = true;
-                throw new RuntimeError({
-                    code: "snapshot_timeout",
-                    status: 0,
-                    message: `Snapshot ${capturing} was still capturing at the deadline.${running ? " The sandbox stays paused until it ends: waking it now would fail the capture." : ""}`,
-                    hint: `Wait until runtime.snapshots.get("${capturing}") is ready${running ? ", then wake the sandbox" : ""}, or pass a longer timeoutMs.`,
-                    details: { snapshotId: capturing, sourceSandboxId: this.id },
-                });
-            }
-            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", request());
-        else if (this.state === "pausing")
-            await this.waitFor("paused", request());
-        running = this.state === "running";
-        // 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 {
-            if (running)
-                await this.pause(pauseOptions);
-            let snapshot = await this.#t.json({
-                method: "POST",
-                path: `/v1/sandboxes/${enc(this.id)}:snapshot`,
-                body,
-                wait: 10,
-                ...(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") {
-                capturing = snapshot.id;
-                request();
-                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;
-        }
-        catch (error) {
-            failed = true;
-            primary = error;
-            // A request cut off by the deadline mid-capture is late all the same.
-            if (capturing && performance.now() >= until)
-                late = true;
-        }
-        // A capture still running needs its source paused: the worker fails one
-        // whose source woke. The timeout says so and leaves the wake to the caller.
-        if (running && !late) {
-            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;
         const reply = await this.#t.json({
@@ -649,29 +331,6 @@ export class Sandbox {
         const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
         return options.count === undefined ? sandboxes[0] : sandboxes;
     }
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
-    async restart(options = {}) {
-        return this.#lifecycle("restart", options);
-    }
-    async #lifecycle(verb, options, body = {}) {
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
-            body,
-            wait: options.wait === false ? 0 : 60,
-            ...requestOnly(options),
-        }));
-        return this;
-    }
-    async [Symbol.asyncDispose]() {
-        this.#keepAlive?.();
-        if (this.#info.state === "stopped")
-            return;
-        await this.stop({ wait: false }).catch(() => undefined);
-    }
-    toJSON() {
-        return this.#info;
-    }
 }
 /** Where a reader of a process's output is, in bytes of stdout and stderr
  * together. Output it did not receive, named by the server or not, becomes a
@@ -747,15 +406,6 @@ function pick(options) {
         ...(options.timeoutMs ? { timeoutMs: options.timeoutMs + 60_000 } : {}),
     };
 }
-/** Any other call's request options, as the caller gave them: `timeoutMs` is
- * the call's whole deadline, and 0 turns it off. */
-function requestOnly(options) {
-    return {
-        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
-        ...(options.signal ? { signal: options.signal } : {}),
-        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
-    };
-}
 /** Sessions: a token your backend makes and hands to your own frontend, which
  * then runs commands, reads and writes files and reaches previews in this one
  * sandbox directly, without proxying through your servers. A session cannot
@@ -1752,11 +1402,7 @@ export class Files {
         }
     }
 }
+/** One page of `runtime.sandboxes.list()`, and the pages after it. */
 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 }),
-        ...options,
-    }), query, options));
+    return machinePage(SANDBOXES, t, (transport, info) => new Sandbox(transport, info), body, query, options);
 }

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.11.1";
+export declare const VERSION = "0.11.2";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -50,7 +50,7 @@ export type Call = RequestOptions & {
     retry?: boolean;
     /** How long to keep retrying, with the same key and input, a refusal that
      * clears when a sandbox stops or a host frees room (WAITS_FOR_ROOM): a
-     * full trial, a full quota, a full region. Then the refusal is thrown as
+     * full slots without credit, a full quota, a full region. Then the refusal is thrown as
      * it came. Only a create sets it; 0 or absent fails at once. */
     waitForCapacityMs?: number;
     /** Called each time a call waits for room, with the refusal it is waiting
@@ -103,6 +103,8 @@ export declare class Transport {
         /** Connections held at once, answers and streams together; the rest
          * wait their turn. Default 48: one address may hold 64 to the API. */
         maxConnections?: number;
+        /** Called each time a call has to wait for one of those connections. */
+        onQueued?: (maxConnections: number) => void;
         /** How long a create waits for room. Default 120 000; 0 fails at once. */
         waitForCapacityMs?: number;
     });

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.11.1";
+export const VERSION = "0.11.2";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -120,7 +120,7 @@ function abortReason(signal) {
 }
 /** At most `maximum` holders at once; the rest wait their turn, first come
  * first served. */
-function slots(maximum) {
+function slots(maximum, onWait) {
     let active = 0;
     const waiting = [];
     return {
@@ -130,6 +130,7 @@ function slots(maximum) {
                 active++;
                 return;
             }
+            onWait?.();
             await new Promise((resolve, reject) => {
                 const ready = () => {
                     signal?.removeEventListener("abort", abort);
@@ -203,8 +204,9 @@ export class Transport {
         this.#maxRetries = options.maxRetries ?? 4;
         this.#client = options.client ?? `sdk-js/${VERSION}`;
         const most = Math.max(1, options.maxConnections ?? DEFAULT_MAX_CONNECTIONS);
-        this.#slots = slots(most);
-        this.#streams = slots(Math.max(1, most - KEPT_FOR_CALLS));
+        const queued = options.onQueued && (() => options.onQueued(most));
+        this.#slots = slots(most, queued);
+        this.#streams = slots(Math.max(1, most - KEPT_FOR_CALLS), queued);
         this.waitForCapacityMs = Math.max(0, options.waitForCapacityMs ?? 120_000);
     }
     /** The key, found once on first use when it was not given. */