withruntime 0.3.0 → 0.4.0

package/dist/e2b/code-interpreter.js

@@ -0,0 +1,244 @@
+import { guard, NotSupportedError, SandboxError, TimeoutError } from "./errors.js";
+import { bind } from "./index.js";
+import { Sandbox as BaseSandbox } from "./sandbox.js";
+export * from "./index.js";
+/** A line of output, as E2B's callbacks receive it. */
+export class OutputMessage {
+    line;
+    timestamp;
+    error;
+    constructor(line, 
+    /** Unix epoch in nanoseconds (from the client's clock). */
+    timestamp, error) {
+        this.line = line;
+        this.timestamp = timestamp;
+        this.error = error;
+    }
+    toString() {
+        return this.line;
+    }
+}
+export class ExecutionError {
+    name;
+    value;
+    traceback;
+    constructor(name, value, traceback) {
+        this.name = name;
+        this.value = value;
+        this.traceback = traceback;
+    }
+}
+const FORMATS = {
+    "text/plain": "text",
+    "text/html": "html",
+    "text/markdown": "markdown",
+    "image/svg+xml": "svg",
+    "image/png": "png",
+    "image/jpeg": "jpeg",
+    "application/pdf": "pdf",
+    "text/latex": "latex",
+    "application/json": "json",
+    "application/javascript": "javascript",
+};
+/** One rich result, as E2B's: text, html, png (base64) and the rest. `chart`
+ * and E2B's `data` (its own DataFrame format) are never set on Runtime; a
+ * DataFrame arrives in `extra` under application/vnd.runtime.table+json. */
+export class Result {
+    isMainResult;
+    text;
+    html;
+    markdown;
+    svg;
+    png;
+    jpeg;
+    pdf;
+    latex;
+    json;
+    javascript;
+    data;
+    chart;
+    extra;
+    raw;
+    constructor(rawData, isMainResult) {
+        this.raw = rawData;
+        this.isMainResult = isMainResult;
+        const extra = {};
+        const fields = {};
+        for (const [mime, value] of Object.entries(rawData)) {
+            const field = FORMATS[mime];
+            if (field)
+                fields[field] = value;
+            else
+                extra[mime] = value;
+        }
+        Object.assign(this, fields);
+        if (Object.keys(extra).length)
+            this.extra = extra;
+    }
+    formats() {
+        return [
+            ...Object.values(FORMATS).filter((field) => this[field] !== undefined),
+            ...Object.keys(this.extra ?? {}),
+        ];
+    }
+    toJSON() {
+        return {
+            text: this.text,
+            html: this.html,
+            markdown: this.markdown,
+            svg: this.svg,
+            png: this.png,
+            jpeg: this.jpeg,
+            pdf: this.pdf,
+            latex: this.latex,
+            json: this.json,
+            javascript: this.javascript,
+            ...(this.extra ? { extra: this.extra } : {}),
+        };
+    }
+}
+export class Execution {
+    results;
+    logs;
+    error;
+    executionCount;
+    constructor(results = [], logs = { stdout: [], stderr: [] }, error, executionCount) {
+        this.results = results;
+        this.logs = logs;
+        this.error = error;
+        this.executionCount = executionCount;
+    }
+    /** The main result's text. */
+    get text() {
+        return this.results.find((result) => result.isMainResult)?.text;
+    }
+    toJSON() {
+        return { results: this.results, logs: this.logs, error: this.error };
+    }
+}
+const TEXT_MIME = /^text\/|json|javascript|svg|latex/;
+/** Output as E2B's logs: one entry per line, each keeping its newline. */
+function lines(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+function language(requested) {
+    if (requested === undefined || requested === "python")
+        return "python";
+    if (requested === "javascript" || requested === "js")
+        return "javascript";
+    throw new NotSupportedError(`Running ${requested} code in the interpreter`, requested === "bash"
+        ? "Use sandbox.commands.run(code)."
+        : "Runtime's interpreter runs Python and JavaScript; install the language and run it with sandbox.commands.run(...).");
+}
+/** The code interpreter sandbox: everything the base Sandbox has, plus runCode
+ * and code contexts. */
+export class Sandbox extends BaseSandbox {
+    static defaultTemplate = "code-interpreter-v1";
+    /** Contexts made to carry the sandbox's envs, one per language. */
+    #envContexts = new Map();
+    get #interpreter() {
+        return this.runtime.interpreter;
+    }
+    /** The context a run goes to: the one asked for; else, when the sandbox has
+     * envs, a context made once with them; else Runtime's default one. */
+    async #contextFor(lang, context) {
+        if (context)
+            return context.id;
+        if (!Object.keys(this.envs).length)
+            return undefined;
+        let id = this.#envContexts.get(lang);
+        if (!id) {
+            id = guard("sandbox", async () => {
+                const made = await this.#interpreter.contexts.create({
+                    id: `e2b-${lang}`,
+                    language: lang,
+                    env: this.envs,
+                });
+                return made.id;
+            }).catch(async (error) => {
+                // Made already, by another object connected to this sandbox.
+                const existing = (await this.#interpreter.contexts.list()).find((one) => one.id === `e2b-${lang}`);
+                if (existing)
+                    return existing.id;
+                throw error;
+            });
+            this.#envContexts.set(lang, id);
+        }
+        return id;
+    }
+    async #inline(result) {
+        const data = { ...result.data };
+        for (const [mime, ref] of Object.entries(result.refs ?? {})) {
+            if (data[mime] !== undefined)
+                continue;
+            const bytes = await guard("sandbox", () => this.#interpreter.result(ref));
+            data[mime] = TEXT_MIME.test(mime)
+                ? new TextDecoder().decode(bytes)
+                : Buffer.from(bytes).toString("base64");
+        }
+        return data;
+    }
+    /** Runs code in a stateful context. Errors in the code come back in
+     * `execution.error`, as in E2B; a run past `timeoutMs` throws TimeoutError. */
+    async runCode(code, opts = {}) {
+        if (opts.language !== undefined && opts.context !== undefined)
+            throw new SandboxError("Pass language or context, not both.");
+        if (opts.envs && Object.keys(opts.envs).length)
+            throw new NotSupportedError("Environment variables for one run (runCode envs)", "Make a context with them: sandbox.runtime.interpreter.contexts.create({ env }), then runCode(code, { context: { id } }).");
+        const lang = language(opts.context?.language ?? opts.language);
+        const context = await this.#contextFor(lang, opts.context);
+        const now = () => Date.now() * 1_000_000;
+        const streaming = opts.onStdout || opts.onStderr || opts.onResult || opts.onError;
+        const execution = await guard("sandbox", () => this.#interpreter.run(code, {
+            ...(context ? { context } : { language: lang }),
+            timeoutMs: opts.timeoutMs ?? 60_000,
+            ...(streaming
+                ? {
+                    onStdout: (text) => void opts.onStdout?.(new OutputMessage(text, now(), false)),
+                    onStderr: (text) => void opts.onStderr?.(new OutputMessage(text, now(), true)),
+                    onError: (error) => void opts.onError?.(new ExecutionError(error.name, error.value, error.traceback)),
+                }
+                : {}),
+        }));
+        if (execution.status === "timeout")
+            throw new TimeoutError(`Execution timed out after ${opts.timeoutMs ?? 60_000} ms: pass a larger 'timeoutMs'.`);
+        if (execution.status === "lost")
+            throw new SandboxError("The interpreter lost this run (its context stopped); run it again.");
+        const results = await Promise.all(execution.results.map(async (result) => new Result(await this.#inline(result), result.main)));
+        if (opts.onResult)
+            for (const result of results)
+                await opts.onResult(result);
+        return new Execution(results, { stdout: lines(execution.stdout), stderr: lines(execution.stderr) }, execution.error
+            ? new ExecutionError(execution.error.name, execution.error.value, execution.error.traceback)
+            : undefined, execution.executionCount ?? undefined);
+    }
+    async createCodeContext(opts = {}) {
+        const lang = language(opts.language);
+        const made = await guard("sandbox", () => this.#interpreter.contexts.create({
+            language: lang,
+            ...(opts.cwd ? { cwd: opts.cwd } : {}),
+            ...(Object.keys(this.envs).length ? { env: this.envs } : {}),
+        }));
+        return { id: made.id, language: made.language, cwd: made.cwd };
+    }
+    async removeCodeContext(context) {
+        const id = typeof context === "string" ? context : context.id;
+        await guard("sandbox", () => this.#interpreter.contexts.remove(id));
+    }
+    async listCodeContexts() {
+        const contexts = await guard("sandbox", () => this.#interpreter.contexts.list());
+        return contexts.map((one) => ({ id: one.id, language: one.language, cwd: one.cwd }));
+    }
+    async restartCodeContext(context) {
+        const id = typeof context === "string" ? context : context.id;
+        await guard("sandbox", () => this.#interpreter.contexts.restart(id));
+    }
+}
+export default Sandbox;
+/** E2B's client with bound options, for the code interpreter. */
+export class E2B {
+    Sandbox;
+    constructor(opts = {}) {
+        this.Sandbox = bind(Sandbox, opts);
+    }
+}

package/dist/e2b/commands.d.ts

@@ -0,0 +1,100 @@
+import type { Process } from "../sandbox.js";
+import type { RuntimeSandbox } from "./client.js";
+import { type CommandResult } from "./errors.js";
+export type { CommandResult };
+export type Username = "user" | "root" | (string & {});
+export interface CommandRequestOpts {
+    requestTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface CommandStartOpts extends CommandRequestOpts {
+    background?: boolean;
+    cwd?: string;
+    /** Only the default user. Runtime runs commands as `runtime`, the sandbox's
+     * owner, with passwordless sudo; E2B's `root` is refused rather than
+     * silently run as someone else. */
+    user?: Username;
+    envs?: Record<string, string>;
+    onStdout?: (data: string) => void | Promise<void>;
+    onStderr?: (data: string) => void | Promise<void>;
+    stdin?: boolean;
+    /** Default 60 000, as in E2B. 0 is no limit (Runtime's longest, 24 hours). */
+    timeoutMs?: number;
+}
+export type CommandConnectOpts = Pick<CommandStartOpts, "onStderr" | "onStdout" | "timeoutMs"> & CommandRequestOpts;
+/** A command as E2B lists it. `pid` is a number derived from Runtime's process
+ * id (stable for the life of the process), not the Linux pid. */
+export interface ProcessInfo {
+    pid: number;
+    tag?: string;
+    cmd: string;
+    args: string[];
+    envs: Record<string, string>;
+    cwd?: string;
+}
+/** The shared state a sandbox's modules need: the Runtime sandbox, the
+ * environment given at create, and the one-time /home/user link. */
+export interface SandboxContext {
+    readonly runtime: RuntimeSandbox;
+    readonly envs: Record<string, string>;
+    /** Makes /home/user (E2B's home) lead to /workspace (Runtime's), once, when
+     * something names it. */
+    ensureHome(text: string | undefined): Promise<void>;
+}
+/** E2B's pids are numbers; Runtime's process ids are strings. The number is a
+ * 31-bit FNV-1a hash of the id, so every client derives the same one. */
+export declare function pidOf(processId: string): number;
+/** `sandbox.commands`: E2B's command module over Runtime's exec and processes. */
+export declare class Commands {
+    #private;
+    constructor(ctx: SandboxContext);
+    /** Runs a command. In the foreground it resolves with the result and throws
+     * CommandExitError on a non-zero exit and TimeoutError past `timeoutMs`; with
+     * `background: true` it resolves at once with a CommandHandle. */
+    run(cmd: string, opts?: CommandStartOpts & {
+        background?: false;
+    }): Promise<CommandResult>;
+    run(cmd: string, opts: CommandStartOpts & {
+        background: true;
+    }): Promise<CommandHandle>;
+    run(cmd: string, opts?: CommandStartOpts & {
+        background?: boolean;
+    }): Promise<CommandHandle | CommandResult>;
+    /** Running commands. */
+    list(_opts?: CommandRequestOpts): Promise<ProcessInfo[]>;
+    /** Kills a command with SIGKILL, as E2B does. False when there is none. */
+    kill(pid: number, _opts?: CommandRequestOpts): Promise<boolean>;
+    /** Sends input to a command started with `stdin: true`. */
+    sendStdin(pid: number, data: string | Uint8Array, _opts?: CommandRequestOpts): Promise<void>;
+    closeStdin(pid: number, _opts?: CommandRequestOpts): Promise<void>;
+    /** Attaches to a running command; output from now on reaches the handle. */
+    connect(pid: number, opts?: CommandConnectOpts): Promise<CommandHandle>;
+}
+/** A command started in the background: E2B's CommandHandle over a Runtime
+ * process. Output streams into `stdout`/`stderr` and the callbacks as it
+ * arrives. */
+export declare class CommandHandle {
+    #private;
+    readonly pid: number;
+    constructor(process: Process, options: {
+        stdin: boolean;
+        timeoutMs: number;
+        cursor?: number;
+        onStdout?: (data: string) => void | Promise<void>;
+        onStderr?: (data: string) => void | Promise<void>;
+    });
+    /** The exit code, or undefined while the command runs. */
+    get exitCode(): number | undefined;
+    get error(): string | undefined;
+    get stdout(): string;
+    get stderr(): string;
+    /** Waits for the command to end. Throws CommandExitError on a non-zero exit,
+     * as E2B does. */
+    wait(): Promise<CommandResult>;
+    /** Stops receiving output; the command keeps running. */
+    disconnect(): Promise<void>;
+    /** Kills the command with SIGKILL. False when it had already ended. */
+    kill(): Promise<boolean>;
+    sendStdin(data: string | Uint8Array, _opts?: CommandRequestOpts): Promise<void>;
+    closeStdin(_opts?: CommandRequestOpts): Promise<void>;
+}

package/dist/e2b/commands.js

@@ -0,0 +1,268 @@
+import { request } from "./client.js";
+import { CommandExitError, guard, InvalidArgumentError, NotSupportedError, SandboxError, TimeoutError, translate, } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const LONGEST_MS = 86_400_000;
+/** E2B's pids are numbers; Runtime's process ids are strings. The number is a
+ * 31-bit FNV-1a hash of the id, so every client derives the same one. */
+export function pidOf(processId) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < processId.length; i++) {
+        hash ^= processId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 1 || 1;
+}
+function refuseUser(user) {
+    if (user !== undefined && user !== "user")
+        throw new NotSupportedError(`Running as the user "${user}"`, 'Runtime runs commands as its sandbox owner, with passwordless sudo: prefix the command with "sudo" to run it as root.');
+}
+function timeoutFor(timeoutMs) {
+    if (timeoutMs === undefined)
+        return DEFAULT_TIMEOUT_MS;
+    if (timeoutMs === 0)
+        return LONGEST_MS;
+    return Math.min(timeoutMs, LONGEST_MS);
+}
+function timedOut(timeoutMs) {
+    return new TimeoutError(`Command timed out after ${timeoutMs} ms: this error is likely due to exceeding 'timeoutMs'. ` +
+        "Pass a larger 'timeoutMs', or 0 for no limit.");
+}
+/** A Runtime result as E2B's: a command killed by a signal has no exit code on
+ * Runtime; E2B reports -1. */
+function toResult(result) {
+    const exitCode = result.exitCode ?? -1;
+    return {
+        exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        ...(exitCode === 0
+            ? {}
+            : {
+                error: result.exitCode === null ? "terminated by a signal" : `exit status ${exitCode}`,
+            }),
+    };
+}
+function settle(result, timeoutMs) {
+    if (result.timedOut)
+        throw timedOut(timeoutMs);
+    const out = toResult(result);
+    if (out.exitCode !== 0)
+        throw new CommandExitError(out);
+    return out;
+}
+/** `sandbox.commands`: E2B's command module over Runtime's exec and processes. */
+export class Commands {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    #env(envs) {
+        const merged = { ...this.#ctx.envs, ...envs };
+        return Object.keys(merged).length ? { env: merged } : {};
+    }
+    async run(cmd, opts = {}) {
+        refuseUser(opts.user);
+        await this.#ctx.ensureHome(`${cmd}\n${opts.cwd ?? ""}`);
+        const timeoutMs = timeoutFor(opts.timeoutMs);
+        if (opts.background || opts.stdin) {
+            const handle = await this.#start(cmd, opts, timeoutMs);
+            return opts.background ? handle : handle.wait();
+        }
+        const result = await guard("sandbox", () => this.#ctx.runtime.exec(cmd, {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...this.#env(opts.envs),
+            timeoutMs,
+            ...(opts.onStdout ? { onStdout: (text) => void opts.onStdout(text) } : {}),
+            ...(opts.onStderr ? { onStderr: (text) => void opts.onStderr(text) } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        }));
+        return settle(result, timeoutMs);
+    }
+    async #start(cmd, opts, timeoutMs) {
+        const process = await guard("sandbox", () => this.#ctx.runtime.spawn(cmd, {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...this.#env(opts.envs),
+            timeoutMs,
+            ...(opts.stdin ? { stdin: "pipe" } : {}),
+            ...request(opts),
+        }));
+        return new CommandHandle(process, {
+            stdin: opts.stdin === true,
+            timeoutMs,
+            ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+            ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+        });
+    }
+    /** Running commands. */
+    async list(_opts = {}) {
+        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list());
+        return processes.filter((info) => info.state === "running").map(describe);
+    }
+    async #find(pid) {
+        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list());
+        return processes.find((info) => pidOf(info.id) === pid && info.state === "running");
+    }
+    async #process(pid) {
+        const info = await this.#find(pid);
+        if (!info)
+            throw new SandboxError(`No running command with pid ${pid}.`);
+        return guard("sandbox", () => this.#ctx.runtime.processes.get(info.id));
+    }
+    /** Kills a command with SIGKILL, as E2B does. False when there is none. */
+    async kill(pid, _opts = {}) {
+        const info = await this.#find(pid);
+        if (!info)
+            return false;
+        const process = await guard("sandbox", () => this.#ctx.runtime.processes.get(info.id));
+        await guard("sandbox", () => process.kill("SIGKILL"));
+        return true;
+    }
+    /** Sends input to a command started with `stdin: true`. */
+    async sendStdin(pid, data, _opts = {}) {
+        const process = await this.#process(pid);
+        if (!process.info.stdinOpen)
+            throw new InvalidArgumentError(`The command with pid ${pid} was not started with stdin: true, so its input is closed.`);
+        await guard("sandbox", () => process.write(data));
+    }
+    async closeStdin(pid, _opts = {}) {
+        const process = await this.#process(pid);
+        await guard("sandbox", () => process.write("", { eof: true }));
+    }
+    /** Attaches to a running command; output from now on reaches the handle. */
+    async connect(pid, opts = {}) {
+        const process = await this.#process(pid);
+        return new CommandHandle(process, {
+            stdin: process.info.stdinOpen,
+            timeoutMs: timeoutFor(opts.timeoutMs),
+            cursor: process.info.outputBytes,
+            ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+            ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+        });
+    }
+}
+function describe(info) {
+    return {
+        pid: pidOf(info.id),
+        cmd: "/bin/bash",
+        args: ["-c", info.command],
+        envs: {},
+        cwd: info.cwd,
+    };
+}
+/** A command started in the background: E2B's CommandHandle over a Runtime
+ * process. Output streams into `stdout`/`stderr` and the callbacks as it
+ * arrives. */
+export class CommandHandle {
+    pid;
+    #process;
+    #stdin;
+    #timeoutMs;
+    #abort = new AbortController();
+    #done;
+    #stdout = "";
+    #stderr = "";
+    #exit;
+    #failure;
+    #disconnected = false;
+    constructor(process, options) {
+        this.#process = process;
+        this.pid = pidOf(process.id);
+        this.#stdin = options.stdin;
+        this.#timeoutMs = options.timeoutMs;
+        this.#done = this.#follow(options);
+    }
+    async #follow(options) {
+        try {
+            for await (const event of this.#process.output({
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+                signal: this.#abort.signal,
+            })) {
+                if (event.type === "stdout") {
+                    this.#stdout += event.data;
+                    await options.onStdout?.(event.data);
+                }
+                else if (event.type === "stderr") {
+                    this.#stderr += event.data;
+                    await options.onStderr?.(event.data);
+                }
+                else if (event.type === "exit") {
+                    this.#exit = { exitCode: event.exitCode, timedOut: event.timedOut };
+                }
+            }
+        }
+        catch (error) {
+            if (!this.#disconnected) {
+                const translated = translate(error, "sandbox");
+                this.#failure =
+                    translated instanceof Error ? translated : new SandboxError(String(translated));
+            }
+        }
+    }
+    /** The exit code, or undefined while the command runs. */
+    get exitCode() {
+        return this.#exit ? (this.#exit.exitCode ?? -1) : undefined;
+    }
+    get error() {
+        return this.#exit ? this.#result().error : undefined;
+    }
+    get stdout() {
+        return this.#stdout;
+    }
+    get stderr() {
+        return this.#stderr;
+    }
+    #result() {
+        return toResult({
+            exitCode: this.#exit?.exitCode ?? null,
+            stdout: this.#stdout,
+            stderr: this.#stderr,
+        });
+    }
+    /** Waits for the command to end. Throws CommandExitError on a non-zero exit,
+     * as E2B does. */
+    async wait() {
+        await this.#done;
+        if (this.#failure)
+            throw this.#failure;
+        if (!this.#exit)
+            throw new SandboxError(this.#disconnected
+                ? "Disconnected from the command before it ended; reconnect with commands.connect(pid)."
+                : "The command's output ended without an exit.");
+        return settle({
+            exitCode: this.#exit.exitCode,
+            stdout: this.#stdout,
+            stderr: this.#stderr,
+            timedOut: this.#exit.timedOut,
+        }, this.#timeoutMs);
+    }
+    /** Stops receiving output; the command keeps running. */
+    async disconnect() {
+        this.#disconnected = true;
+        this.#abort.abort();
+        await Promise.resolve();
+    }
+    /** Kills the command with SIGKILL. False when it had already ended. */
+    async kill() {
+        if (this.#exit)
+            return false;
+        try {
+            await guard("sandbox", () => this.#process.kill("SIGKILL"));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof SandboxError && error.statusCode === 404)
+                return false;
+            throw error;
+        }
+    }
+    async sendStdin(data, _opts = {}) {
+        if (!this.#stdin)
+            throw new InvalidArgumentError("The command was not started with stdin: true, so its input is closed.");
+        await guard("sandbox", () => this.#process.write(data));
+    }
+    async closeStdin(_opts = {}) {
+        if (!this.#stdin)
+            throw new InvalidArgumentError("The command was not started with stdin: true.");
+        await guard("sandbox", () => this.#process.write("", { eof: true }));
+    }
+}

package/dist/e2b/errors.d.ts

@@ -0,0 +1,72 @@
+/** Base class for E2B's sandbox errors. */
+export declare class SandboxError extends Error {
+    statusCode?: number;
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(message?: string);
+}
+export declare class TimeoutError extends SandboxError {
+}
+export declare class InvalidArgumentError extends SandboxError {
+}
+export declare class NotEnoughSpaceError extends SandboxError {
+}
+export declare class NotFoundError extends SandboxError {
+}
+export declare class FileNotFoundError extends NotFoundError {
+}
+export declare class SandboxNotFoundError extends NotFoundError {
+}
+export declare class TemplateError extends SandboxError {
+}
+export declare class RateLimitError extends SandboxError {
+}
+/** E2B's AuthenticationError extends Error, not SandboxError. */
+export declare class AuthenticationError extends Error {
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(message: string);
+}
+/** E2B's ServiceBusyError extends Error, not SandboxError. */
+export declare class ServiceBusyError extends Error {
+    readonly statusCode = 503;
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(message: string);
+}
+/** A call that E2B supports and Runtime does not, or not in the same way.
+ * Thrown before anything is done, never after doing something different.
+ * `feature` names what was asked for; `alternative` says what to use on
+ * Runtime instead. */
+export declare class NotSupportedError extends SandboxError {
+    readonly feature: string;
+    readonly alternative: string;
+    constructor(feature: string, alternative: string, message?: string);
+}
+/** What `commands.run` resolves with, as in E2B. */
+export interface CommandResult {
+    exitCode: number;
+    error?: string;
+    stdout: string;
+    stderr: string;
+}
+/** Thrown by `commands.run` and `CommandHandle.wait` when the command exits
+ * with a code other than 0. It carries the result, as in E2B. */
+export declare class CommandExitError extends SandboxError implements CommandResult {
+    #private;
+    constructor(result: CommandResult);
+    get exitCode(): number;
+    get error(): string | undefined;
+    get stdout(): string;
+    get stderr(): string;
+}
+/** Which object a call was about, to name a 404 the way E2B would. */
+export type Subject = "sandbox" | "file" | "other";
+/** Turns a Runtime SDK error into the E2B error a caller written for E2B
+ * expects. Anything that is not a Runtime error passes through unchanged. */
+export declare function translate(error: unknown, subject?: Subject): unknown;
+/** Runs `work`, turning any Runtime error into its E2B counterpart. */
+export declare function guard<T>(subject: Subject, work: () => Promise<T>): Promise<T>;