withruntime 0.3.1 → 0.5.0

package/dist/e2b/filesystem.js

@@ -0,0 +1,143 @@
+import { request } from "./client.js";
+import { FileNotFoundError, guard, NotSupportedError } from "./errors.js";
+export var FileType;
+(function (FileType) {
+    FileType["FILE"] = "file";
+    FileType["DIR"] = "dir";
+    FileType["SYMLINK"] = "symlink";
+})(FileType || (FileType = {}));
+/** Runtime's home, where E2B's relative paths land. */
+const HOME = "/workspace";
+function absolute(path) {
+    return path.startsWith("/") ? path : `${HOME}/${path.replace(/^\.\//, "")}`;
+}
+function refuse(opts) {
+    if (opts.user !== undefined && opts.user !== "user")
+        throw new NotSupportedError(`File access as the user "${opts.user}"`, "Runtime's file calls act as the sandbox owner; use commands.run('sudo ...') for root-owned paths.");
+    if (opts.metadata && Object.keys(opts.metadata).length)
+        throw new NotSupportedError("File metadata (user.e2b.* extended attributes)", "Keep the metadata beside the file, for example in a JSON file.");
+}
+const PERMISSIONS = ["---", "--x", "-w-", "-wx", "r--", "r-x", "rw-", "rwx"];
+function entryInfo(entry) {
+    const mode = parseInt(entry.mode, 8) || 0;
+    const bits = mode & 0o777;
+    return {
+        name: entry.name,
+        path: entry.path,
+        ...(entry.type === "file"
+            ? { type: FileType.FILE }
+            : entry.type === "directory"
+                ? { type: FileType.DIR }
+                : entry.type === "symlink"
+                    ? { type: FileType.SYMLINK }
+                    : {}),
+        size: entry.size,
+        mode,
+        permissions: PERMISSIONS[(bits >> 6) & 7] + PERMISSIONS[(bits >> 3) & 7] + PERMISSIONS[bits & 7],
+        owner: "",
+        group: "",
+        modifiedTime: new Date(entry.modifiedAt),
+    };
+}
+async function bytesOf(data) {
+    if (typeof data === "string")
+        return new TextEncoder().encode(data);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        const view = data;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    }
+    if (typeof Blob !== "undefined" && data instanceof Blob)
+        return new Uint8Array(await data.arrayBuffer());
+    return new Uint8Array(await new Response(data).arrayBuffer());
+}
+const basename = (path) => path.split("/").filter(Boolean).pop() ?? path;
+/** `sandbox.files`: E2B's filesystem module over Runtime's files API. Relative
+ * paths resolve against the home directory, as in E2B (Runtime's is
+ * /workspace). */
+export class Filesystem {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get #files() {
+        return this.#ctx.runtime.files;
+    }
+    async #path(path, opts) {
+        refuse(opts);
+        await this.#ctx.ensureHome(path);
+        return absolute(path);
+    }
+    async read(path, opts = {}) {
+        const file = await this.#path(path, opts);
+        const bytes = await guard("file", () => this.#files.read(file, request(opts)));
+        switch (opts.format) {
+            case "bytes":
+                return bytes;
+            case "blob":
+                return new Blob([bytes]);
+            case "stream":
+                return new Blob([bytes]).stream();
+            default:
+                return new TextDecoder().decode(bytes);
+        }
+    }
+    async write(pathOrFiles, dataOrOpts, maybeOpts) {
+        if (Array.isArray(pathOrFiles))
+            return this.writeFiles(pathOrFiles, (dataOrOpts ?? {}));
+        return this.#writeOne(pathOrFiles, dataOrOpts, maybeOpts ?? {});
+    }
+    async writeFiles(files, opts = {}) {
+        const written = [];
+        for (const file of files)
+            written.push(await this.#writeOne(file.path, file.data, opts));
+        return written;
+    }
+    async #writeOne(path, data, opts) {
+        const file = await this.#path(path, opts);
+        const bytes = await bytesOf(data);
+        await guard("file", () => this.#files.write(file, bytes, request(opts)));
+        return { name: basename(file), type: FileType.FILE, path: file };
+    }
+    /** A directory's entries, hidden ones included; `depth` goes deeper. */
+    async list(path, opts = {}) {
+        const dir = await this.#path(path, opts);
+        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true }));
+        return entries.map(entryInfo);
+    }
+    /** Makes a directory and its parents. False when it already existed. */
+    async makeDir(path, opts = {}) {
+        const dir = await this.#path(path, opts);
+        if (await guard("file", () => this.#files.exists(dir)))
+            return false;
+        await guard("file", () => this.#files.mkdir(dir, { parents: true }));
+        return true;
+    }
+    /** Moves a file or directory, replacing a file at the new path, as E2B does. */
+    async rename(oldPath, newPath, opts = {}) {
+        const from = await this.#path(oldPath, opts);
+        const to = await this.#path(newPath, opts);
+        await guard("file", () => this.#files.rename(from, to, { overwrite: true }));
+        return this.getInfo(to, opts);
+    }
+    /** Removes a file, or a directory with everything in it. */
+    async remove(path, opts = {}) {
+        const target = await this.#path(path, opts);
+        await guard("file", () => this.#files.remove(target, { recursive: true }));
+    }
+    async exists(path, opts = {}) {
+        const target = await this.#path(path, opts);
+        return guard("file", () => this.#files.exists(target));
+    }
+    async getInfo(path, opts = {}) {
+        const target = await this.#path(path, opts);
+        const stat = await guard("file", () => this.#files.stat(target));
+        if (!stat.exists)
+            throw new FileNotFoundError(`${target} does not exist.`);
+        return entryInfo(stat);
+    }
+    watchDir() {
+        return Promise.reject(new NotSupportedError("Watching a directory (files.watchDir)", "Poll with files.list(path), or run your own watcher with commands.run(..., { background: true })."));
+    }
+}

package/dist/e2b/index.d.ts

@@ -0,0 +1,28 @@
+/** Code written for E2B's SDK, on Runtime Cloud. Change the import:
+ *
+ *   import { Sandbox } from "withruntime/e2b"; // was: from "e2b"
+ *
+ * and set RUNTIME_API_KEY (or put a Runtime key in E2B_API_KEY). What Runtime
+ * cannot do the way E2B does throws NotSupportedError, naming what to use. */
+import type { Runtime } from "../client.js";
+import { type ConnectionOpts } from "./client.js";
+import { Sandbox } from "./sandbox.js";
+export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SnapshotInfo, } from "./sandbox.js";
+export { Commands, CommandHandle, pidOf, type CommandStartOpts, type CommandConnectOpts, type CommandRequestOpts, type ProcessInfo, type Username, } from "./commands.js";
+export { Filesystem, FileType, type EntryInfo, type WriteInfo, type WriteEntry, type FilesystemRequestOpts, type FilesystemReadOpts, type FilesystemWriteOpts, type FilesystemListOpts, } from "./filesystem.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, type CommandResult, } from "./errors.js";
+export type { ConnectionOpts, RuntimeOpts } from "./client.js";
+export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
+export default Sandbox;
+/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
+export declare class E2B {
+    readonly Sandbox: typeof Sandbox;
+    constructor(opts?: Omit<ConnectionOpts, "signal"> & {
+        client?: Runtime;
+    });
+}
+/** A subclass whose static calls use `opts`'s key or client unless a call
+ * names its own. */
+export declare function bind<S extends typeof Sandbox>(Base: S, opts: Omit<ConnectionOpts, "signal"> & {
+    client?: Runtime;
+}): S;

package/dist/e2b/index.js

@@ -0,0 +1,61 @@
+import { clientFor } from "./client.js";
+import { Sandbox } from "./sandbox.js";
+export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from "./sandbox.js";
+export { Commands, CommandHandle, pidOf, } from "./commands.js";
+export { Filesystem, FileType, } from "./filesystem.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, } from "./errors.js";
+export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
+export default Sandbox;
+/** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
+export class E2B {
+    Sandbox;
+    constructor(opts = {}) {
+        this.Sandbox = bind(Sandbox, opts);
+    }
+}
+/** A subclass whose static calls use `opts`'s key or client unless a call
+ * names its own. */
+export function bind(Base, opts) {
+    const client = clientFor({
+        ...opts,
+        ...(opts.client ? { runtime: { client: opts.client } } : {}),
+    });
+    const withClient = (given) => ({
+        ...given,
+        runtime: { ...given?.runtime, client: given?.runtime?.client ?? client },
+    });
+    const Bound = class extends Base {
+    };
+    const create = Reflect.get(Base, "create");
+    const statics = {
+        create(first, second) {
+            return typeof first === "string"
+                ? create.call(this, first, withClient(second))
+                : create.call(this, withClient(first));
+        },
+    };
+    // The calls that take (id, opts) or (id, x, opts): the options come last.
+    for (const name of [
+        "connect",
+        "list",
+        "kill",
+        "getInfo",
+        "setTimeout",
+        "pause",
+        "betaPause",
+        "fork",
+        "createSnapshot",
+        "deleteSnapshot",
+    ]) {
+        const original = Reflect.get(Base, name);
+        const arity = name === "list" ? 1 : name === "setTimeout" ? 3 : 2;
+        statics[name] = function (...args) {
+            const padded = [...args];
+            padded[arity - 1] = withClient(padded[arity - 1]);
+            return original.apply(this, padded);
+        };
+    }
+    for (const [name, value] of Object.entries(statics))
+        Object.defineProperty(Bound, name, { value, writable: true, configurable: true });
+    return Bound;
+}

package/dist/e2b/sandbox.d.ts

@@ -0,0 +1,203 @@
+import type { Runtime } from "../client.js";
+import { type ConnectionOpts, type RuntimeOpts, type RuntimeSandbox } from "./client.js";
+import { Commands } from "./commands.js";
+import { Filesystem } from "./filesystem.js";
+/** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
+ * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
+export declare const DEFAULT_SHAPE: {
+    readonly vcpu: 2;
+    readonly memoryMiB: 512;
+};
+/** E2B's default sandbox timeout, 300 s. */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+export type SandboxState = "running" | "paused";
+export type SandboxOnTimeout = "pause" | "kill" | {
+    action: "pause" | "kill";
+    keepMemory?: boolean;
+};
+export type SandboxLifecycle = {
+    onTimeout: SandboxOnTimeout;
+    autoResume?: boolean;
+};
+export interface SandboxOpts extends ConnectionOpts {
+    /** An E2B template name. "base" (the default) is Runtime's stock image; any
+     * other name must be a ready Runtime image of that name, and a UUID a
+     * Runtime image or snapshot id. */
+    template?: string;
+    /** Stored as the sandbox's labels (at most 32, values up to 256 characters). */
+    metadata?: Record<string, string>;
+    /** Given to every command and code run through this object. */
+    envs?: Record<string, string>;
+    /** Default 300 000. Runtime's leases run 60 s to 1 hour; shorter rounds up
+     * to 60 s (with a warning), longer is refused. */
+    timeoutMs?: number;
+    /** Accepted and ignored, as E2B ignores it. */
+    secure?: boolean;
+    /** false: no network at all. */
+    allowInternetAccess?: boolean;
+    /** What happens when the timeout ends: "kill" (E2B's default, Runtime stops
+     * the sandbox) or "pause". */
+    lifecycle?: SandboxLifecycle;
+    mcp?: unknown;
+    network?: unknown;
+    iam?: unknown;
+    volumeMounts?: unknown;
+    /** Runtime-only: an explicit client, or fields for the create. */
+    runtime?: RuntimeOpts;
+}
+export type SandboxConnectOpts = ConnectionOpts & {
+    timeoutMs?: number;
+    onResume?: "restore" | "reboot";
+    runtime?: RuntimeOpts;
+};
+export type SandboxApiOpts = Pick<ConnectionOpts, "apiKey" | "requestTimeoutMs" | "signal"> & {
+    runtime?: RuntimeOpts;
+};
+export interface SandboxInfo {
+    sandboxId: string;
+    /** "base" for Runtime's stock image, else the image or snapshot id. */
+    templateId: string;
+    name?: string;
+    metadata: Record<string, string>;
+    startedAt: Date;
+    endAt: Date;
+    state: SandboxState;
+    cpuCount: number;
+    memoryMB: number;
+    /** Runtime has no envd: "runtime". */
+    envdVersion: string;
+    lifecycle?: {
+        onTimeout: "pause" | "kill";
+        autoResume: boolean;
+    };
+}
+export interface SnapshotInfo {
+    snapshotId: string;
+    names: string[];
+}
+export type SandboxListOpts = SandboxApiOpts & {
+    query?: {
+        metadata?: Record<string, string>;
+        state?: SandboxState[];
+        startedAfter?: Date;
+        template?: string;
+    };
+    order?: "asc" | "desc";
+    limit?: number;
+    nextToken?: string;
+};
+/** A sandbox, with E2B's methods. `sandbox.runtime` is the Runtime sandbox
+ * underneath, for anything E2B has no name for. */
+export declare class Sandbox {
+    #private;
+    protected static readonly defaultTemplate: string;
+    readonly files: Filesystem;
+    readonly commands: Commands;
+    /** Use Sandbox.create or Sandbox.connect. */
+    constructor(runtime: RuntimeSandbox, client: Runtime, envs?: Record<string, string>);
+    get sandboxId(): string;
+    /** The Runtime sandbox underneath: previews, network, desktop, interpreter,
+     * processes, terminal and the rest of Runtime's SDK. */
+    get runtime(): RuntimeSandbox;
+    protected get client(): Runtime;
+    protected get envs(): Record<string, string>;
+    /** Creates a sandbox from `template` (default "base", Runtime's stock image)
+     * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
+     * Funding is left to Runtime: the free trial while the account has trial
+     * time, then prepaid credit, exactly as withruntime's own create. */
+    static create<S extends typeof Sandbox>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>;
+    static create<S extends typeof Sandbox>(this: S, template: string, opts?: SandboxOpts): Promise<InstanceType<S>>;
+    /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
+     * `timeoutMs` moves a running sandbox's end later, never earlier. */
+    static connect<S extends typeof Sandbox>(this: S, sandboxId: string, opts?: SandboxConnectOpts): Promise<InstanceType<S>>;
+    /** Wakes this sandbox if it is paused. */
+    connect(opts?: SandboxConnectOpts): Promise<this>;
+    /** Running and paused sandboxes, a page at a time, as E2B's paginator. */
+    static list(opts?: SandboxListOpts): SandboxPaginator;
+    /** Stops the sandbox. False when it was not found or had already ended. */
+    static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>;
+    kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
+    /** Sets the sandbox to end `timeoutMs` from now. Runtime leases only move
+     * later: a shorter timeout than the one it has is refused. */
+    static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
+    setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
+    static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;
+    getInfo(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<SandboxInfo>;
+    isRunning(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
+    /** Pauses the sandbox, keeping memory and files. False when it was paused. */
+    static pause(sandboxId: string, opts?: SandboxApiOpts & {
+        keepMemory?: boolean;
+    }): Promise<boolean>;
+    static betaPause(sandboxId: string, opts?: SandboxApiOpts & {
+        keepMemory?: boolean;
+    }): Promise<boolean>;
+    pause(opts?: SandboxApiOpts & {
+        keepMemory?: boolean;
+    }): Promise<boolean>;
+    betaPause(opts?: SandboxApiOpts & {
+        keepMemory?: boolean;
+    }): Promise<boolean>;
+    /** Copies of this sandbox, memory and all. While Runtime's forks are
+     * switched off this throws NotSupportedError with Runtime's own words. */
+    static fork<S extends typeof Sandbox>(this: S, sandboxId: string, opts?: SandboxApiOpts & {
+        count?: number;
+        timeoutMs?: number;
+    }): Promise<Array<InstanceType<S> | Error>>;
+    fork(opts?: SandboxApiOpts & {
+        count?: number;
+        timeoutMs?: number;
+    }): Promise<Array<this | Error>>;
+    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
+     * with Sandbox.create(snapshotId). */
+    createSnapshot(opts?: SandboxApiOpts & {
+        name?: string;
+    }): Promise<SnapshotInfo>;
+    static createSnapshot(sandboxId: string, opts?: SandboxApiOpts & {
+        name?: string;
+    }): Promise<SnapshotInfo>;
+    static deleteSnapshot(snapshotId: string, opts?: SandboxApiOpts): Promise<boolean>;
+    /** Refused: E2B answers getHost without a call, and a Runtime port becomes
+     * reachable only once it is shared. Use getPublicHost. */
+    getHost(port: number): string;
+    /** Shares `port` at a public HTTPS address (a Runtime preview) and returns
+     * its host, `<port>-<id>.<domain>`, like E2B's getHost. Anyone with the
+     * address can reach it; a browser sees a one-time page naming Runtime. */
+    getPublicHost(port: number): Promise<string>;
+    get pty(): never;
+    get git(): never;
+    /** E2B's metrics, from Runtime's measured readings (`sbx.metrics()`): CPU
+     * as a percent of the sandbox's vCPUs and resident memory, one entry per
+     * host reading (every minute by default) between `start` and `end`, kept
+     * 24 hours at that resolution. Disk use inside the sandbox is not measured:
+     * `diskUsed` is null and `diskTotal` is the disk's size. */
+    getMetrics(opts?: MetricsOpts): Promise<E2BSandboxMetrics[]>;
+    static getMetrics(sandboxId: string, opts?: MetricsOpts & SandboxApiOpts): Promise<E2BSandboxMetrics[]>;
+    updateNetwork(): Promise<never>;
+    uploadUrl(): Promise<never>;
+    downloadUrl(): Promise<never>;
+    getMcpUrl(): never;
+    getMcpToken(): Promise<never>;
+}
+/** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`. */
+export declare class SandboxPaginator {
+    #private;
+    constructor(client: Runtime, opts: SandboxListOpts);
+    get hasNext(): boolean;
+    get nextToken(): string | undefined;
+    nextItems(): Promise<SandboxInfo[]>;
+}
+type MetricsOpts = {
+    start?: Date | number;
+    end?: Date | number;
+};
+export type E2BSandboxMetrics = {
+    timestamp: Date;
+    cpuUsedPct: number;
+    cpuCount: number;
+    memUsed: number;
+    memTotal: number;
+    /** Not measured by Runtime: null. */
+    diskUsed: number | null;
+    diskTotal: number;
+};
+export {};