withruntime 0.3.1 → 0.5.0

package/dist/ssh.js

@@ -0,0 +1,312 @@
+import { spawn, spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { RuntimeError } from "./errors.js";
+import { VERSION } from "./transport.js";
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+export const SSH_HELP = (me) => `${me} sandbox ssh <id|name> [-- <command...>]   Log in over SSH (an interactive shell, or run the command)
+${me} sandbox ssh config [--install]          The ssh config for \`ssh <id|name>.runtime\`, also from
+                                      VS Code Remote-SSH and JetBrains Gateway; --install adds
+                                      it to ~/.ssh/config
+${me} sandbox ssh proxy <id|name>[.runtime]   ProxyCommand mode: SSH on stdin and stdout
+${me} sandbox port-forward <id|name> <port|local:remote>... [--address 127.0.0.1]
+                                      Forward local ports to ports in the sandbox, until Ctrl-C
+
+SSH and port forwarding go through Runtime's API with your key: the sandbox opens
+no port to the internet. The login is the sandbox's user, runtime, with sudo.
+A paused sandbox wakes when you connect, like any command.
+`;
+function configDirectory(env) {
+    const root = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    if (!isAbsolute(root))
+        throw new Error("XDG_CONFIG_HOME must be an absolute path.");
+    return join(root, "runtime-cloud");
+}
+/** This machine's key for Runtime SSH logins, made on first use. Only its
+ * public half ever leaves the machine, and only into the one login it opens. */
+export async function sshKey(env) {
+    const dir = join(configDirectory(env), "ssh");
+    const path = join(dir, "id_ed25519");
+    try {
+        return { path, publicKey: (await readFile(`${path}.pub`, "utf8")).trim() };
+    }
+    catch {
+        // Made below.
+    }
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    const made = spawnSync("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-C", "runtime-cloud", "-f", path], {
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (made.error || made.status !== 0)
+        throw new RuntimeError({
+            message: `Could not make an SSH key with ssh-keygen${made.error ? `: ${made.error.message}` : `: ${made.stderr.toString().trim()}`}.`,
+            code: "ssh_keygen_failed",
+            status: 0,
+            hint: "Install OpenSSH (it has ssh and ssh-keygen), or pass --key with a public key file.",
+        });
+    return { path, publicKey: (await readFile(`${path}.pub`, "utf8")).trim() };
+}
+/** A sandbox by id or by its name, as `ssh` hands it over (`<id>.runtime`). */
+export async function resolveSandbox(runtime, target) {
+    const name = target.replace(/\.runtime$/, "");
+    if (UUID.test(name))
+        return runtime.sandboxes.get(name);
+    const page = await runtime.sandboxes.list({ name, limit: 2 });
+    if (page.data.length === 1)
+        return page.data[0];
+    throw new RuntimeError({
+        message: page.data.length
+            ? `More than one live sandbox is named ${name}.`
+            : `No live sandbox is named ${name}.`,
+        code: page.data.length ? "ambiguous_name" : "sandbox_not_found",
+        status: 0,
+        hint: "Use its id: runtime sandbox ls",
+    });
+}
+const quote = (text) => /^[A-Za-z0-9_./:@=-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
+/** How ssh should start this CLI again: the same program and script, or npx
+ * at this version when it ran from npx's temporary cache. */
+function selfCommand(env) {
+    const script = process.argv[1];
+    const program = script && !/[\\/]_npx[\\/]/.test(script)
+        ? [process.execPath, realpathSync(script)]
+        : ["npx", "--yes", `withruntime@${VERSION}`];
+    const origin = env.RUNTIME_API_URL ? [`RUNTIME_API_URL=${env.RUNTIME_API_URL}`] : [];
+    return [...(origin.length ? ["env", ...origin] : []), ...program].map(quote).join(" ");
+}
+export async function sshConfig(env) {
+    const { path } = await sshKey(env);
+    return `# Runtime Cloud: \`ssh <sandbox id or name>.runtime\`, and the same host in
+# VS Code Remote-SSH or JetBrains Gateway. The connection is Runtime's
+# authenticated tunnel, which already proves which sandbox answers; each login
+# gets a fresh host key, so there is nothing to pin in known_hosts.
+Host *.runtime
+  User runtime
+  ProxyCommand ${selfCommand(env)} sandbox ssh proxy %h
+  IdentityFile "${path}"
+  IdentitiesOnly yes
+  StrictHostKeyChecking no
+  UserKnownHostsFile /dev/null
+  LogLevel ERROR
+  ServerAliveInterval 30
+`;
+}
+/** Writes the block to its own file and includes it from ~/.ssh/config once. */
+async function installConfig(env) {
+    const file = join(configDirectory(env), "ssh", "config");
+    await writeFile(file, await sshConfig(env), { mode: 0o600 });
+    const sshDir = join(homedir(), ".ssh");
+    await mkdir(sshDir, { recursive: true, mode: 0o700 });
+    const main = join(sshDir, "config");
+    const current = await readFile(main, "utf8").catch(() => "");
+    const include = `Include "${file}"`;
+    if (!current.split("\n").some((line) => line.trim() === include))
+        // First, because ssh reads an Include inside a Host block as part of it.
+        await writeFile(main, `${include}\n${current ? `\n${current}` : ""}`, { mode: 0o600 });
+    return file;
+}
+/** ProxyCommand mode: ssh speaks on this process's stdin and stdout. */
+async function proxy(runtime, target, publicKey) {
+    const sbx = await resolveSandbox(runtime, target);
+    const tunnel = await sbx.tunnel();
+    const stream = await tunnel.ssh(publicKey).catch((error) => {
+        tunnel.close();
+        throw error;
+    });
+    return new Promise(() => {
+        // When the sandbox side ends, the session is over: flush what ssh has not
+        // read yet, then exit, which is what closes the pipe ssh is reading (an
+        // ended process.stdout does not close it on every runtime).
+        let leaving = false;
+        const leave = (code) => {
+            if (leaving)
+                return;
+            leaving = true;
+            tunnel.close();
+            process.stdout.write("", () => process.exit(code));
+        };
+        stream.onData = (data) => void process.stdout.write(data);
+        stream.onEnd = () => leave(0);
+        stream.onLog = (text) => process.stderr.write(`sandbox sshd: ${text}`);
+        stream.onClose = (reason) => {
+            if (reason !== "done")
+                process.stderr.write(`Runtime: the SSH connection ended (${reason}).\n`);
+            leave(reason === "done" ? 0 : 1);
+        };
+        // Async iteration reads the next chunk only after this one is inside the
+        // window: backpressure that behaves the same on Node and Bun.
+        void (async () => {
+            for await (const data of process.stdin)
+                await stream.write(new Uint8Array(data));
+            stream.end();
+        })().catch(() => stream.close());
+    });
+}
+/** Installs the OpenSSH server in a sandbox that lacks it (an image made
+ * before it was in the base image, or a custom one), saying so first. */
+async function ensureSshd(sbx, out) {
+    const probe = await sbx.exec(["sh", "-c", "command -v sshd || test -x /usr/sbin/sshd"], {
+        timeoutMs: 30_000,
+    });
+    if (probe.exitCode === 0)
+        return;
+    out.error("This sandbox has no OpenSSH server yet; installing it once...");
+    const installed = await sbx.exec([
+        "sh",
+        "-c",
+        "sudo -n apt-get update -qq && sudo -n env DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends openssh-server",
+    ], { timeoutMs: 300_000 });
+    if (installed.exitCode !== 0)
+        throw new RuntimeError({
+            message: `Installing openssh-server in the sandbox failed: ${(installed.stderr || installed.stdout).trim().slice(-400)}`,
+            code: "sshd_missing",
+            status: 0,
+            hint: "Install an SSH server in the sandbox yourself, or build an image that has one.",
+        });
+}
+export async function sshCommand(argv, env, out, connect, me) {
+    const dash = argv.indexOf("--");
+    const words = dash === -1 ? argv : argv.slice(0, dash);
+    const remote = dash === -1 ? [] : argv.slice(dash + 1);
+    const keyAt = words.indexOf("--key");
+    const keyFile = keyAt === -1 ? undefined : words[keyAt + 1];
+    const positional = words.filter((word, i) => !word.startsWith("--") && (keyAt === -1 || i !== keyAt + 1));
+    const [first, second] = positional;
+    if (!first || first === "help") {
+        out.write(SSH_HELP(me));
+        return first ? 0 : 64;
+    }
+    const publicKey = async () => keyFile ? (await readFile(keyFile, "utf8")).trim() : (await sshKey(env)).publicKey;
+    if (first === "config") {
+        if (words.includes("--install")) {
+            const file = await installConfig(env);
+            out.write(out.json
+                ? JSON.stringify({ installed: file })
+                : `Added Include "${file}" to ~/.ssh/config. Connect with: ssh <sandbox id or name>.runtime`);
+        }
+        else
+            out.write(out.json ? JSON.stringify({ config: await sshConfig(env) }) : await sshConfig(env));
+        return 0;
+    }
+    if (first === "proxy") {
+        if (!second)
+            throw usageError(`Give the host: ${me} sandbox ssh proxy <id>.runtime`, me);
+        return proxy(await connect(), second, await publicKey());
+    }
+    const runtime = await connect();
+    const sbx = await resolveSandbox(runtime, first);
+    await ensureSshd(sbx, out);
+    const key = keyFile ? undefined : await sshKey(env);
+    const args = [
+        "-o",
+        `ProxyCommand=${selfCommand(env)} sandbox ssh proxy${keyFile ? ` --key ${quote(keyFile)}` : ""} %h`,
+        ...(key ? ["-i", key.path, "-o", "IdentitiesOnly=yes"] : []),
+        "-o",
+        "StrictHostKeyChecking=no",
+        "-o",
+        "UserKnownHostsFile=/dev/null",
+        "-o",
+        "LogLevel=ERROR",
+        "-o",
+        "ServerAliveInterval=30",
+        ...(remote.length ? [] : ["-t"]),
+        `runtime@${sbx.id}.runtime`,
+        // ssh joins what follows the host into one remote command line.
+        ...remote,
+    ];
+    return new Promise((resolve, reject) => {
+        const child = spawn("ssh", args, { stdio: "inherit" });
+        child.on("error", (error) => reject(new RuntimeError({
+            message: `Could not run ssh: ${error.message}`,
+            code: "ssh_missing",
+            status: 0,
+            hint: "Install OpenSSH, or use `runtime sandbox shell <id>`, which needs nothing.",
+        })));
+        child.on("exit", (code) => resolve(code ?? 255));
+    });
+}
+function usageError(message, me) {
+    return new RuntimeError({
+        message,
+        code: "usage",
+        status: 0,
+        hint: `Run \`${me} sandbox ssh help\`.`,
+    });
+}
+/** `runtime sandbox port-forward <id> 5432 8080:3000 ...` */
+export async function portForwardCommand(argv, out, connect, me) {
+    const at = argv.indexOf("--address");
+    const address = at === -1 ? "127.0.0.1" : argv[at + 1];
+    const positional = argv.filter((word, i) => !word.startsWith("--") && (at === -1 || i !== at + 1));
+    const [target, ...specs] = positional;
+    if (!target || !specs.length || !address)
+        throw new RuntimeError({
+            message: `Give a sandbox and at least one port: ${me} sandbox port-forward <id> 5432 8080:3000`,
+            code: "usage",
+            status: 0,
+            hint: `Run \`${me} sandbox ssh help\`.`,
+        });
+    const ports = specs.map((spec) => {
+        const match = /^(?:(\d{1,5}):)?(\d{1,5})$/.exec(spec);
+        const remote = Number(match?.[2]);
+        const local = match?.[1] === undefined ? remote : Number(match[1]);
+        if (!match || remote < 1 || remote > 65_535 || local > 65_535)
+            throw new RuntimeError({
+                message: `${spec} is not a port or local:remote pair.`,
+                code: "usage",
+                status: 0,
+                hint: "For example 5432, or 15432:5432 to listen on 15432 here.",
+            });
+        return { local, remote };
+    });
+    const sbx = await resolveSandbox(await connect(), target);
+    const tunnel = await sbx.tunnel();
+    const forwards = [];
+    try {
+        for (const { local, remote } of ports)
+            forwards.push(await tunnel.forward(remote, { localPort: local, host: address }));
+    }
+    catch (error) {
+        tunnel.close();
+        throw new RuntimeError({
+            message: `Could not listen here: ${error instanceof Error ? error.message : String(error)}`,
+            code: "listen_failed",
+            status: 0,
+            hint: "Pick another local port with local:remote, for example 15432:5432.",
+        });
+    }
+    out.write(out.json
+        ? JSON.stringify({
+            sandboxId: sbx.id,
+            forwarding: forwards.map((f) => ({
+                address: f.host,
+                localPort: f.localPort,
+                port: f.port,
+            })),
+        })
+        : forwards
+            .map((f) => `Forwarding ${f.host}:${f.localPort} -> sandbox ${sbx.id} port ${f.port}`)
+            .join("\n") + "\nPress Ctrl-C to stop.");
+    return new Promise((resolve) => {
+        let stopping = false;
+        const stop = () => {
+            stopping = true;
+            process.off("SIGINT", stop);
+            void Promise.all(forwards.map((f) => f.close())).then(() => {
+                tunnel.close();
+                resolve(0);
+            });
+        };
+        process.once("SIGINT", stop);
+        void tunnel.closed.then((reason) => {
+            if (stopping)
+                return;
+            process.off("SIGINT", stop);
+            out.error(`The tunnel closed: ${reason}`);
+            void Promise.all(forwards.map((f) => f.close())).then(() => resolve(1));
+        });
+    });
+}

package/dist/tar.d.ts

@@ -1,3 +1,4 @@
+export declare function tarHeader(name: string, size: number, mode: number, type: "0" | "5" | "2", link?: string, mtime?: number): Uint8Array;
 export declare function packDirectory(root: string): Promise<Uint8Array>;
 /** Unpacks into `target`, refusing any entry that would land outside it. */
 export declare function unpackArchive(archive: Uint8Array, target: string): Promise<void>;

package/dist/tar.js

@@ -4,7 +4,7 @@ import { gunzipSync, gzipSync } from "node:zlib";
 /* A small ustar writer and reader for directory uploads and downloads, so the
    SDK needs no dependency. Regular files, directories and symbolic links;
    names up to 255 bytes through the ustar prefix field. */
-function header(name, size, mode, type, link = "", mtime = 0) {
+export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
     const block = new Uint8Array(512);
     const bytes = new TextEncoder().encode(name);
     let prefix = new Uint8Array();
@@ -48,16 +48,16 @@ export async function packDirectory(root) {
             const info = await lstat(full);
             const mtime = Math.floor(info.mtimeMs / 1000);
             if (info.isDirectory()) {
-                parts.push(header(`${path}/`, 0, info.mode, "5", "", mtime));
+                parts.push(tarHeader(`${path}/`, 0, info.mode, "5", "", mtime));
                 await walk(full);
             }
             else if (info.isSymbolicLink()) {
                 const { readlink } = await import("node:fs/promises");
-                parts.push(header(path, 0, info.mode, "2", await readlink(full), mtime));
+                parts.push(tarHeader(path, 0, info.mode, "2", await readlink(full), mtime));
             }
             else if (info.isFile()) {
                 const data = await readFile(full);
-                parts.push(header(path, data.length, info.mode, "0", "", mtime), data);
+                parts.push(tarHeader(path, data.length, info.mode, "0", "", mtime), data);
                 const pad = (512 - (data.length % 512)) % 512;
                 if (pad)
                     parts.push(new Uint8Array(pad));

package/dist/tools/index.d.ts

@@ -0,0 +1,62 @@
+import type { Sandbox } from "../sandbox.js";
+export type ToolInputSchema = {
+    type: "object";
+    properties: Record<string, {
+        type: "string" | "integer";
+        description: string;
+        minimum?: number;
+    }>;
+    required: string[];
+    additionalProperties: false;
+};
+export type SandboxTool<Input, Output> = {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+    execute(input: Input): Promise<Output>;
+};
+export type ExecInput = {
+    command: string;
+    cwd?: string;
+    timeoutSeconds?: number;
+};
+export type ExecOutput = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+};
+export type ListEntry = {
+    path: string;
+    type: "file" | "directory" | "symlink" | "other";
+    size: number;
+};
+export type SandboxToolOptions = {
+    /** Where relative paths resolve. Default /workspace. */
+    root?: string;
+    /** For a command that names no timeout. Default 300. */
+    timeoutSeconds?: number;
+    /** Characters kept from each of stdout, stderr and a file read; the rest is cut from the front. Default 20 000. */
+    maxOutputChars?: number;
+};
+export type SandboxTools = [
+    SandboxTool<ExecInput, ExecOutput>,
+    SandboxTool<{
+        path: string;
+    }, string>,
+    SandboxTool<{
+        path: string;
+        content: string;
+    }, string>,
+    SandboxTool<{
+        path?: string;
+        depth?: number;
+    }, ListEntry[] | {
+        error: string;
+    }>
+];
+/** A POSIX path joined and normalized: `..` cannot climb past `/`. */
+export declare function resolvePath(root: string, path: string | undefined): string;
+export declare function clip(text: string, limit: number): string;
+/** runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files, bound to `sandbox`. */
+export declare function sandboxTools(sandbox: Sandbox, options?: SandboxToolOptions): SandboxTools;

package/dist/tools/index.js

@@ -0,0 +1,180 @@
+/** Four tools bound to one Runtime sandbox, in no framework's format: a name,
+ * a description, a JSON Schema and a function. The adapters for the Vercel AI
+ * SDK (and Mastra), the Claude Agent SDK and the OpenAI Agents SDK wrap these,
+ * and any other framework can too:
+ *
+ *   import { sandboxTools } from "withruntime/tools";
+ *   for (const t of sandboxTools(sbx)) register(t.name, t.description, t.inputSchema, t.execute);
+ *
+ * The application creates the sandbox and binds the tools to it: the model
+ * chooses commands and paths, never the sandbox, the account or the key.
+ * Relative paths are under /workspace, and output is capped so one noisy
+ * command cannot flood the model's context. */
+import { NotFoundError } from "../errors.js";
+const WORKSPACE = "/workspace";
+/** A POSIX path joined and normalized: `..` cannot climb past `/`. */
+export function resolvePath(root, path) {
+    const joined = (path ?? ".").startsWith("/") ? path : `${root}/${path ?? "."}`;
+    const parts = [];
+    for (const part of joined.split("/")) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..")
+            parts.pop();
+        else
+            parts.push(part);
+    }
+    return `/${parts.join("/")}`;
+}
+export function clip(text, limit) {
+    return text.length <= limit
+        ? text
+        : `[${text.length - limit} earlier characters omitted]\n${text.slice(-limit)}`;
+}
+/** runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files, bound to `sandbox`. */
+export function sandboxTools(sandbox, options = {}) {
+    const root = resolvePath("/", options.root ?? WORKSPACE);
+    const timeoutSeconds = options.timeoutSeconds ?? 300;
+    const limit = options.maxOutputChars ?? 20_000;
+    const inFilesApi = (path) => path.startsWith(`${WORKSPACE}/`);
+    return [
+        {
+            name: "runtime_exec",
+            description: "Run a shell command (bash) in the sandbox and return its exit code, stdout and stderr.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    command: {
+                        type: "string",
+                        description: "The command line, run under `bash -c`, for example `pytest -q`.",
+                    },
+                    cwd: {
+                        type: "string",
+                        description: "Directory to run in. Relative paths are under /workspace, the default.",
+                    },
+                    timeoutSeconds: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Seconds before the command is stopped and reported as timed out.",
+                    },
+                },
+                required: ["command"],
+                additionalProperties: false,
+            },
+            async execute({ command, cwd, timeoutSeconds: seconds }) {
+                const result = await sandbox.exec(command, {
+                    cwd: resolvePath(root, cwd),
+                    timeoutMs: (seconds ?? timeoutSeconds) * 1000,
+                });
+                return {
+                    exitCode: result.exitCode,
+                    stdout: clip(result.stdout, limit),
+                    stderr: clip(result.stderr, limit),
+                    timedOut: result.timedOut,
+                };
+            },
+        },
+        {
+            name: "runtime_read_file",
+            description: "Read a text file from the sandbox.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "The file's path. Relative paths are under /workspace.",
+                    },
+                },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            async execute({ path }) {
+                const target = resolvePath(root, path);
+                if (inFilesApi(target)) {
+                    try {
+                        return clip(await sandbox.files.readText(target), limit);
+                    }
+                    catch (error) {
+                        if (error instanceof NotFoundError)
+                            return `No such file: ${target}`;
+                        throw error;
+                    }
+                }
+                const result = await sandbox.exec(["cat", "--", target]);
+                return clip(result.exitCode === 0 ? result.stdout : result.stderr, limit);
+            },
+        },
+        {
+            name: "runtime_write_file",
+            description: "Create or replace a text file in the sandbox, making parent directories.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "The file's path. Relative paths are under /workspace.",
+                    },
+                    content: { type: "string", description: "The file's full new content." },
+                },
+                required: ["path", "content"],
+                additionalProperties: false,
+            },
+            async execute({ path, content }) {
+                const target = resolvePath(root, path);
+                if (inFilesApi(target))
+                    await sandbox.files.write(target, content);
+                else {
+                    const result = await sandbox.exec(["sh", "-c", 'mkdir -p -- "$(dirname -- "$1")" && cat > "$1"', "sh", target], { stdin: content });
+                    if (result.exitCode !== 0)
+                        return `Could not write ${target}: ${result.stderr.trim()}`;
+                }
+                return `Wrote ${new TextEncoder().encode(content).length} bytes to ${target}`;
+            },
+        },
+        {
+            name: "runtime_list_files",
+            description: "List a directory in the sandbox: each entry's path, type and size.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "The directory. Relative paths are under /workspace, the default.",
+                    },
+                    depth: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "How many levels below it to include; 1 lists only its children.",
+                    },
+                },
+                required: [],
+                additionalProperties: false,
+            },
+            async execute({ path, depth }) {
+                const levels = String(Math.max(1, Math.min(depth ?? 1, 10)));
+                const result = await sandbox.exec([
+                    "sh",
+                    "-c",
+                    'find "$1" -mindepth 1 -maxdepth "$2" -printf "%y\\t%s\\t%p\\n" | sort -k3 | head -n 1000',
+                    "sh",
+                    resolvePath(root, path),
+                    levels,
+                ]);
+                if (result.exitCode !== 0 && !result.stdout)
+                    return { error: result.stderr.trim() || `find exited with ${result.exitCode}` };
+                const kinds = {
+                    f: "file",
+                    d: "directory",
+                    l: "symlink",
+                };
+                return result.stdout
+                    .split("\n")
+                    .filter(Boolean)
+                    .map((line) => {
+                    const [kind = "", size = "0", ...rest] = line.split("\t");
+                    return { path: rest.join("\t"), type: kinds[kind] ?? "other", size: Number(size) || 0 };
+                });
+            },
+        },
+    ];
+}

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.5.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps
@@ -25,6 +25,11 @@ export type Call = RequestOptions & {
      * reads and for writes (the key makes them safe); false only for calls
      * the server cannot deduplicate. */
     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
+     * it came. Only a create sets it; 0 or absent fails at once. */
+    waitForCapacityMs?: number;
 };
 export declare function apiOrigin(value: string): string;
 export declare function encodeQuery(query: Query | undefined): string;
@@ -39,6 +44,8 @@ export declare function encodeQuery(query: Query | undefined): string;
 export declare class Transport {
     #private;
     readonly baseUrl: string;
+    /** What `sandboxes.create` waits for room by default. */
+    readonly waitForCapacityMs: number;
     constructor(options: {
         /** A key, or where to find one when the first call is made. */
         apiKey: string | (() => Promise<string>);
@@ -49,10 +56,13 @@ export declare class Transport {
         client?: string;
         /** Calls read whole that may be in flight at once. Default 32. */
         maxConnections?: number;
+        /** How long a create waits for room. Default 120 000; 0 fails at once. */
+        waitForCapacityMs?: number;
     });
     /** 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. */
     send(call: Call): Promise<Response>;
     json<T>(call: Call): Promise<T>;
     bytes(call: Call): Promise<Uint8Array>;