@sandboxrouter/sdk 0.2.0 → 0.3.0

package/dist/providers/e2b.js

@@ -1,9 +1,16 @@
 import { ProviderError } from "../types.js";
-import { optionalImport, toBytes } from "../util.js";
-/** E2B via the official `e2b` SDK. vCPU and memory come from the template, not the create call. */
+import { DEFAULT_EXEC_TIMEOUT_S, optionalImport, timeoutError, toBytes } from "../util.js";
+/** How long a desktop lives without activity. 1 hour is the Hobby tier's cap (Pro allows 24 h). */
+const DESKTOP_TIMEOUT_MS = 60 * 60_000;
+/**
+ * E2B via the official `e2b` SDK. vCPU and memory come from the template, not the create call.
+ * Computers (Linux desktops) via `@e2b/desktop`: the public `desktop` template (Xvfb + XFCE),
+ * driven with xdotool and scrot inside the sandbox.
+ */
 export class E2BProvider {
     apiKey;
     id = "e2b";
+    computerOs = ["linux"];
     constructor(apiKey = process.env.E2B_API_KEY) {
         this.apiKey = apiKey;
     }
@@ -25,32 +32,96 @@ export class E2BProvider {
         const { Sandbox } = await optionalImport("e2b", "e2b");
         return new E2BBox(await Sandbox.connect(nativeId, { apiKey: this.apiKey }));
     }
+    /**
+     * A fresh desktop every call. E2B has no get-or-create by user, so `externalUserId` (and `name`)
+     * are only stored as sandbox metadata; keep the returned id to come back to the same desktop.
+     */
+    async createComputer(spec) {
+        const os = spec.os ?? "linux";
+        if (os !== "linux")
+            throw new ProviderError(this.id, `E2B only offers linux desktops, not ${os}`);
+        const { Sandbox } = await optionalImport("@e2b/desktop", "e2b computers");
+        const metadata = {};
+        if (spec.externalUserId !== undefined)
+            metadata.externalUserId = spec.externalUserId;
+        if (spec.name !== undefined)
+            metadata.name = spec.name;
+        try {
+            const sbx = await Sandbox.create({
+                apiKey: this.apiKey,
+                timeoutMs: DESKTOP_TIMEOUT_MS,
+                metadata,
+                ...(spec.screen ? { resolution: [Math.round(spec.screen.width), Math.round(spec.screen.height)] } : {}),
+            });
+            return new E2BComputer(sbx);
+        }
+        catch (err) {
+            throw new ProviderError(this.id, err?.message ?? String(err));
+        }
+    }
+    /** Reattach by sandbox id. A paused (slept) desktop is resumed. */
+    async connectComputer(nativeId) {
+        const { Sandbox } = await optionalImport("@e2b/desktop", "e2b computers");
+        try {
+            return new E2BComputer(await Sandbox.connect(nativeId, { apiKey: this.apiKey, timeoutMs: DESKTOP_TIMEOUT_MS }));
+        }
+        catch (err) {
+            throw new ProviderError(this.id, err?.message ?? String(err));
+        }
+    }
 }
-class E2BBox {
+/** exec/files/kill over an E2B-style SDK sandbox. `provider` labels errors. No pause. */
+export class E2BCompatBox {
     sbx;
+    provider;
     nativeId;
-    constructor(sbx) {
+    constructor(sbx, provider = "e2b") {
         this.sbx = sbx;
+        this.provider = provider;
         this.nativeId = sbx.sandboxId;
     }
     async exec(cmd, opts = {}) {
         const t0 = Date.now();
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timeout"), seconds * 1000);
+            timer.unref();
+        });
         try {
-            const r = await this.sbx.commands.run(cmd, {
+            // The command runs in the background so the deadline can kill it: the SDK's own `timeoutMs`
+            // only stops listening, and the process would keep running (and billing) in the sandbox.
+            // That stream deadline is set past ours so it never ends a command we still want.
+            const handle = await this.sbx.commands.run(cmd, {
                 cwd: opts.cwd,
                 envs: opts.env,
-                timeoutMs: (opts.timeoutSeconds ?? 60) * 1000,
+                background: true,
+                timeoutMs: (seconds + 15) * 1000,
                 onStdout: opts.onStdout,
                 onStderr: opts.onStderr,
             });
+            const finished = handle.wait();
+            const r = await Promise.race([finished, expired]);
+            if (r === "timeout") {
+                finished.catch(() => { });
+                await handle.kill().catch(() => { });
+                throw timeoutError(this.provider, seconds);
+            }
             return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, durationMs: Date.now() - t0 };
         }
         catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
             // The SDK throws CommandExitError for a nonzero exit; that's a result, not a failure.
             if (err?.name === "CommandExitError" || typeof err?.exitCode === "number") {
                 return { exitCode: err.exitCode, stdout: err.stdout ?? "", stderr: err.stderr ?? "", durationMs: Date.now() - t0 };
             }
-            throw new ProviderError("e2b", err?.message ?? String(err));
+            if (err?.name === "TimeoutError")
+                throw timeoutError(this.provider, seconds);
+            throw new ProviderError(this.provider, err?.message ?? String(err));
+        }
+        finally {
+            clearTimeout(timer);
         }
     }
     async writeFile(path, content) {
@@ -59,11 +130,308 @@ class E2BBox {
     async readFile(path) {
         return await this.sbx.files.read(path, { format: "bytes" });
     }
+    async kill() {
+        await this.sbx.kill();
+    }
+}
+/** E2BCompatBox plus pause, for services where pause/resume is generally available. */
+export class E2BBox extends E2BCompatBox {
     /** Snapshot memory and disk. Sandbox.connect (router.get) resumes it. */
     async pause() {
         await this.sbx.pause();
     }
-    async kill() {
+}
+/** Friendly names models send that xdotool doesn't know; anything else passes through verbatim. */
+const KEY_ALIASES = {
+    enter: "Return",
+    return: "Return",
+    esc: "Escape",
+    escape: "Escape",
+    backspace: "BackSpace",
+    del: "Delete",
+    delete: "Delete",
+    tab: "Tab",
+    space: "space",
+    up: "Up",
+    down: "Down",
+    left: "Left",
+    right: "Right",
+    home: "Home",
+    end: "End",
+    pageup: "Page_Up",
+    page_up: "Page_Up",
+    pagedown: "Page_Down",
+    page_down: "Page_Down",
+    cmd: "super",
+    command: "super",
+    win: "super",
+    windows: "super",
+    meta: "super",
+    control: "ctrl",
+    option: "alt",
+};
+/** "ctrl+Return" -> "ctrl+Return"; "Enter" -> "Return". Space-separated combos stay separate. */
+function xdoKeys(text) {
+    return text
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((combo) => combo
+        .split("+")
+        .map((k) => KEY_ALIASES[k.toLowerCase()] ?? k)
+        .join("+"));
+}
+function sh(s) {
+    return `'${s.replace(/'/g, `'"'"'`)}'`;
+}
+/** Width and height from a PNG's IHDR chunk. */
+function pngSize(png) {
+    if (png.length < 24 || png[0] !== 0x89 || png[1] !== 0x50)
+        return {};
+    const v = new DataView(png.buffer, png.byteOffset, png.byteLength);
+    return { width: v.getUint32(16), height: v.getUint32(20) };
+}
+function errMessage(err) {
+    return err?.stderr?.trim() || err?.message || String(err);
+}
+class ActionError extends Error {
+}
+/**
+ * An E2B desktop sandbox. Canonical actions map to `@e2b/desktop` calls where the SDK has one, and
+ * to xdotool/scrot commands where it doesn't (triple click, horizontal scroll, hold_key, zoom).
+ */
+class E2BComputer {
+    sbx;
+    nativeId;
+    frame = 0;
+    streamKey;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.sandboxId;
+    }
+    async info() {
+        const i = await this.sbx.getInfo();
+        const running = i.state === "running";
+        return {
+            id: this.nativeId,
+            os: "linux",
+            status: running ? "ready" : "sleeping",
+            screen: running ? await this.sbx.getScreenSize().catch(() => undefined) : undefined,
+            externalUserId: i.metadata?.externalUserId ?? null,
+        };
+    }
+    async act(action) {
+        try {
+            const extra = await this.perform(action);
+            if (action.action === "screenshot" || action.action === "zoom" || !action.noScreenshot) {
+                const shot = extra.image ?? (await this.sbx.screenshot());
+                delete extra.image;
+                return { action: action.action, ok: true, ...extra, ...this.frameOf(shot) };
+            }
+            delete extra.image;
+            return { action: action.action, ok: true, ...extra };
+        }
+        catch (err) {
+            return { action: action.action, ok: false, error: errMessage(err) };
+        }
+    }
+    /** Runs in order and stops at the first failed action (later coordinates may no longer apply). */
+    async actBatch(actions) {
+        const out = [];
+        for (const a of actions) {
+            const r = await this.act(a);
+            out.push(r);
+            if (!r.ok)
+                break;
+        }
+        return out;
+    }
+    frameOf(png) {
+        return { frameId: ++this.frame, imageB64: Buffer.from(png).toString("base64"), mime: "image/png", ...pngSize(png) };
+    }
+    /** Run a desktop command, with an explicit timeout rather than the SDK's 60 s default. */
+    run(cmd, timeoutSeconds = 60) {
+        return this.sbx.commands.run(cmd, { timeoutMs: timeoutSeconds * 1000 });
+    }
+    async withModifier(modifier, fn) {
+        if (!modifier)
+            return fn();
+        const keys = xdoKeys(modifier.replace(/\s+/g, "+"))[0]?.split("+") ?? [];
+        await this.run(`xdotool keydown ${keys.map(sh).join(" ")}`);
+        try {
+            return await fn();
+        }
+        finally {
+            await this.run(`xdotool keyup ${[...keys].reverse().map(sh).join(" ")}`).catch(() => { });
+        }
+    }
+    async moveTo(a, required) {
+        if (!a.coordinate) {
+            if (required)
+                throw new ActionError(`${a.action} needs a coordinate`);
+            return;
+        }
+        const [x, y] = a.coordinate;
+        // The SDK's click helpers skip the move when x or y is 0, so always move explicitly.
+        await this.sbx.moveMouse(Math.round(x), Math.round(y));
+    }
+    /** Does the action; returns extra result fields (and `image` for actions that produce their own). */
+    async perform(a) {
+        const click = async (fn) => {
+            await this.moveTo(a, false);
+            await this.withModifier(a.modifier, async () => {
+                for (let i = 0; i < Math.max(1, a.repeat ?? 1); i++)
+                    await fn();
+            });
+            return {};
+        };
+        switch (a.action) {
+            case "screenshot":
+                return {};
+            case "left_click":
+                return click(() => this.sbx.leftClick());
+            case "right_click":
+                return click(() => this.sbx.rightClick());
+            case "middle_click":
+                return click(() => this.sbx.middleClick());
+            case "double_click":
+                return click(() => this.sbx.doubleClick());
+            case "triple_click":
+                return click(() => this.run("xdotool click --repeat 3 1"));
+            case "mouse_move":
+                await this.moveTo(a, true);
+                return {};
+            case "left_click_drag": {
+                const to = a.coordinate;
+                if (!to)
+                    throw new ActionError("left_click_drag needs a coordinate");
+                let from = a.startCoordinate;
+                if (!from) {
+                    const p = await this.sbx.getCursorPosition();
+                    from = [p.x, p.y];
+                }
+                const start = [Math.round(from[0]), Math.round(from[1])];
+                const end = [Math.round(to[0]), Math.round(to[1])];
+                await this.withModifier(a.modifier, () => this.sbx.drag(start, end));
+                return {};
+            }
+            case "left_mouse_down":
+                await this.moveTo(a, false);
+                await this.sbx.mousePress("left");
+                return {};
+            case "left_mouse_up":
+                await this.moveTo(a, false);
+                await this.sbx.mouseRelease("left");
+                return {};
+            case "scroll": {
+                const dir = a.scrollDirection ?? "down";
+                const amount = Math.max(1, Math.round(a.scrollAmount ?? 3));
+                await this.moveTo(a, false);
+                await this.withModifier(a.modifier, async () => {
+                    if (dir === "up" || dir === "down")
+                        await this.sbx.scroll(dir, amount);
+                    else
+                        await this.run(`xdotool click --repeat ${amount} ${dir === "left" ? 6 : 7}`);
+                });
+                return {};
+            }
+            case "type":
+                if (a.text === undefined)
+                    throw new ActionError("type needs text");
+                await this.sbx.write(a.text);
+                return {};
+            case "key": {
+                if (!a.text)
+                    throw new ActionError("key needs text, e.g. \"Return\" or \"ctrl+s\"");
+                const repeat = Math.max(1, Math.round(a.repeat ?? 1));
+                await this.run(`xdotool key${repeat > 1 ? ` --repeat ${repeat}` : ""} -- ${xdoKeys(a.text).map(sh).join(" ")}`);
+                return {};
+            }
+            case "hold_key": {
+                if (!a.text)
+                    throw new ActionError("hold_key needs text");
+                const keys = xdoKeys(a.text).map(sh).join(" ");
+                const secs = a.duration ?? 1;
+                if (!(secs >= 0 && secs <= 100))
+                    throw new ActionError("duration must be 0 to 100 seconds");
+                // The SDK's default command timeout is 60 s and would end a longer hold with the key still down.
+                await this.run(`xdotool keydown ${keys}; sleep ${secs}; xdotool keyup ${keys}`, secs + 30);
+                return {};
+            }
+            case "wait":
+                await new Promise((r) => setTimeout(r, Math.max(0, a.duration ?? 1) * 1000));
+                return {};
+            case "zoom": {
+                if (!a.region)
+                    throw new ActionError("zoom needs a region [x0, y0, x1, y1]");
+                const [x0, y0, x1, y1] = a.region.map((n) => Math.round(n));
+                if (x1 <= x0 || y1 <= y0 || x0 < 0 || y0 < 0)
+                    throw new ActionError(`bad zoom region ${JSON.stringify(a.region)}`);
+                return { image: await this.capture(`-a ${x0},${y0},${x1 - x0},${y1 - y0}`, "png"), region: [x0, y0, x1, y1] };
+            }
+            case "cursor_position": {
+                const p = await this.sbx.getCursorPosition();
+                return { x: p.x, y: p.y, coordinate: [p.x, p.y] };
+            }
+            default:
+                throw new ActionError(`e2b does not support the "${a.action}" action`);
+        }
+    }
+    /** scrot straight to a temp file (format from the extension), read it back, clean up. */
+    async capture(flags, ext) {
+        const path = `/tmp/sbr-${Date.now()}-${Math.random().toString(36).slice(2)}.${ext}`;
+        await this.run(`scrot ${flags} ${path}`);
+        const bytes = await this.sbx.files.read(path, { format: "bytes" });
+        this.sbx.files.remove(path).catch(() => { });
+        return bytes;
+    }
+    async screenshot(opts = {}) {
+        if (opts.format === "jpeg")
+            return this.capture(`--pointer -q ${Math.round(opts.quality ?? 75)}`, "jpg");
+        return await this.sbx.screenshot();
+    }
+    async exec(command, timeoutSeconds = 60) {
+        try {
+            const r = await this.sbx.commands.run(command, { timeoutMs: timeoutSeconds * 1000 });
+            return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+        }
+        catch (err) {
+            // CommandExitError for a nonzero exit is a result, not a failure.
+            if (err?.name === "CommandExitError" || typeof err?.exitCode === "number") {
+                return { exitCode: err.exitCode, stdout: err.stdout ?? "", stderr: err.stderr ?? "" };
+            }
+            throw new ProviderError("e2b", err?.message ?? String(err));
+        }
+    }
+    async readFile(path) {
+        return await this.sbx.files.read(path, { format: "bytes" });
+    }
+    async writeFile(path, content) {
+        await this.sbx.files.write(path, toBytes(content));
+    }
+    /**
+     * A noVNC link to the desktop, password in the URL, valid while the sandbox lives (`ttlSeconds`
+     * is not supported, so `expiresAt` is null). `watch` sets noVNC's view_only flag, which is
+     * enforced by the client page only: whoever holds a watch link can edit it into a control link.
+     * The first call from a fresh connection restarts the VNC server with a new password, which
+     * invalidates links handed out earlier.
+     */
+    async viewer(mode = "watch", _opts = {}) {
+        if (!this.streamKey) {
+            // After connect/resume the SDK has lost the stream state; restart x11vnc so we know the key.
+            await this.sbx.stream.stop().catch(() => { });
+            await this.sbx.stream.start({ requireAuth: true });
+            this.streamKey = this.sbx.stream.getAuthKey();
+        }
+        const url = this.sbx.stream.getUrl({ autoConnect: true, viewOnly: mode === "watch", resize: "scale", authKey: this.streamKey });
+        return { url, expiresAt: null };
+    }
+    /** E2B pause: memory and disk are snapshotted. connectComputer resumes it; open viewers drop. */
+    async sleep() {
+        await this.sbx.pause();
+        this.streamKey = undefined;
+    }
+    async delete() {
         await this.sbx.kill();
     }
 }

package/dist/providers/exedev.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { ProviderError } from "../types.js";
-import { dirname, shq, toBytes, wrapCommand } from "../util.js";
+import { dirname, killedByTimeout, shq, timeoutError, toBytes, wrapCommand } from "../util.js";
 /**
  * exe.dev standalone VMs over the HTTPS API (no SDK needed).
  * Everything is one endpoint: POST https://exe.dev/exec, Authorization: Bearer exe1..., body = the
@@ -110,7 +110,8 @@ export class ExeDevProvider {
             flags.push(`--image=${image}`);
         }
         const vm = await this.lobby(`new ${flags.join(" ")}`);
-        const box = new ExeDevSandbox(this, vm.vm_name ?? name, spec.env);
+        const vmName = vm.vm_name ?? name;
+        const box = new ExeDevSandbox(this, vmName, spec.env);
         try {
             await box.waitForSsh();
         }
@@ -118,6 +119,11 @@ export class ExeDevProvider {
             await box.kill().catch(() => { });
             throw err;
         }
+        // exe.dev has no lifetime setting, so the VM powers itself off when spec.timeoutMinutes runs out
+        // (a stopped VM bills disk only; kill() or `sandboxrouter gc` deletes it). Best effort: it needs
+        // root or passwordless sudo in the image (not yet confirmed on a real exe.dev VM).
+        const secs = Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60));
+        await this.ssh(vmName, `setsid nohup sh -c 'sleep ${secs}; sudo -n poweroff || poweroff' > /dev/null 2>&1 < /dev/null &`).catch(() => { });
         return box;
     }
     async connect(nativeId) {
@@ -214,11 +220,17 @@ class ExeDevSandbox {
                 stderr += e;
                 opts.onStderr?.(e);
             }
-            if (!running)
-                return { exitCode: r.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+            if (!running) {
+                const durationMs = Date.now() - t0;
+                // `timeout -k 5` on the VM leaves exit 124 (or 137 after SIGKILL) when it had to stop the command.
+                if (killedByTimeout(r.exitCode, durationMs, timeout))
+                    throw timeoutError(ID, timeout);
+                return { exitCode: r.exitCode, stdout, stderr, durationMs };
+            }
             if (Date.now() > deadline) {
+                // The VM's own `timeout` should have ended it a minute ago: stop it from here as a last resort.
                 await this.p.ssh(this.nativeId, `pkill -f ${shq(`${dir}/cmd`)}; rm -rf ${dir}`).catch(() => { });
-                throw new ProviderError(ID, `command still running ${timeout + 60}s after it started`);
+                throw timeoutError(ID, timeout);
             }
             script = report(outOff, errOff);
         }

package/dist/providers/freestyle.d.ts

@@ -0,0 +1,49 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Freestyle's Ubuntu base snapshots (hardware is baked into each), from
+ * https://www.freestyle.sh/docs/vms/base-snapshots, priced at the list rates on
+ * https://www.freestyle.sh/docs/vms/pricing-and-limits ($0.04032/vCPU-h, $0.0129/GiB-h memory,
+ * $0.000086/GiB-h disk), checked 2026-11-04. Free tops out at `ubuntu`, Hobby at `ubuntu-lg`,
+ * Pro at `ubuntu-2xl`.
+ */
+export declare const FREESTYLE_SIZES: {
+    snapshot: string;
+    vcpu: number;
+    memoryGb: number;
+    diskGb: number;
+    usdHour: number;
+}[];
+/** Smallest Ubuntu base snapshot with at least the requested vCPU and memory, or undefined. */
+export declare function freestyleSize(vcpu: number, memoryGb: number): (typeof FREESTYLE_SIZES)[number] | undefined;
+export declare class FreestyleProvider implements Provider {
+    private apiKey;
+    private baseUrl;
+    /** How often to poll a backgrounded request or a booting VM. */
+    private pollMs;
+    readonly id: "freestyle";
+    constructor(apiKey?: string | undefined, baseUrl?: string, 
+    /** How often to poll a backgrounded request or a booting VM. */
+    pollMs?: number);
+    configured(): boolean;
+    /**
+     * @internal One API call. With `background`, a call still running after 5 s comes back as 202
+     * and is polled at /v5/background-requests/:id until its own response is ready.
+     */
+    request(method: string, path: string, init?: {
+        json?: unknown;
+        bytes?: Uint8Array;
+        background?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** @internal JSON call. */
+    json<T>(method: string, path: string, init?: {
+        json?: unknown;
+        background?: boolean;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by VM id (or slug); a paused or stopped VM is started again. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+    /** @internal */
+    get poll(): number;
+}