@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/dist/providers/sprites.js

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+/**
+ * Fly.io Sprites via `@fly/sprites`. A sprite is a persistent machine named by the caller, so the
+ * name is the native id. Sprites idle on their own and have no lifetime knob: kill() deletes it.
+ */
+export class SpritesProvider {
+    token;
+    id = "sprites";
+    client;
+    constructor(token = process.env.SPRITES_TOKEN) {
+        this.token = token;
+    }
+    configured() {
+        return !!this.token;
+    }
+    async sprites() {
+        if (!this.client) {
+            const { SpritesClient } = await optionalImport("@fly/sprites", "sprites");
+            this.client = new SpritesClient(this.token);
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const client = await this.sprites();
+        const name = `sbr-${randomUUID().slice(0, 12)}`;
+        try {
+            const sprite = await client.createSprite(name, {
+                config: { cpus: spec.vcpu, ramMB: spec.memoryGb ? Math.round(spec.memoryGb * 1024) : undefined },
+                environment: spec.env,
+            });
+            return new SpritesBox(sprite);
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err), err?.statusCode);
+        }
+    }
+    async connect(nativeId) {
+        const client = await this.sprites();
+        try {
+            return new SpritesBox(await client.getSprite(nativeId));
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err), err?.statusCode);
+        }
+    }
+}
+class SpritesBox {
+    sprite;
+    nativeId;
+    constructor(sprite) {
+        this.sprite = sprite;
+        this.nativeId = sprite.name;
+    }
+    /** `sprite.exec` splits on whitespace without a shell, so spawn `sh -c` and stream its output. */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const limit = (opts.timeoutSeconds ?? 60) * 1000;
+        const proc = this.sprite.spawn("sh", ["-c", cmd], { cwd: opts.cwd, env: opts.env });
+        const out = new StringDecoder("utf8");
+        const errd = new StringDecoder("utf8");
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (b) => {
+            const c = out.write(b);
+            stdout += c;
+            if (c)
+                opts.onStdout?.(c);
+        });
+        proc.stderr.on("data", (b) => {
+            const c = errd.write(b);
+            stderr += c;
+            if (c)
+                opts.onStderr?.(c);
+        });
+        try {
+            const exitCode = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    proc.kill("SIGKILL");
+                    proc.close();
+                    reject(new ProviderError("sprites", `command timed out after ${limit / 1000}s`));
+                }, limit);
+                timer.unref();
+                proc.on("exit", (code) => {
+                    clearTimeout(timer);
+                    resolve(code);
+                });
+                proc.on("error", (e) => {
+                    clearTimeout(timer);
+                    proc.close();
+                    reject(e);
+                });
+            });
+            const so = out.end();
+            const se = errd.end();
+            if (so)
+                opts.onStdout?.(so);
+            if (se)
+                opts.onStderr?.(se);
+            return { exitCode, stdout: stdout + so, stderr: stderr + se, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("sprites", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sprite.filesystem().writeFile(path, Buffer.from(toBytes(content)));
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err));
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await this.sprite.filesystem().readFile(path, null));
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err));
+        }
+    }
+    /** Sprites are persistent; delete so the router's disposable sandboxes don't linger. */
+    async kill() {
+        try {
+            await this.sprite.delete();
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err), err?.statusCode);
+        }
+    }
+}

package/dist/providers/tensorlake.d.ts

@@ -0,0 +1,14 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Tensorlake sandboxes via `@tensorlakeai/tensorlake`. Auth: TENSORLAKE_API_KEY.
+ * Set image.tensorlake to start from your own sandbox image; spec.gpu maps to a GPU model.
+ */
+export declare class TensorlakeProvider implements Provider {
+    private apiKey;
+    readonly id: "tensorlake";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a suspended sandbox is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/tensorlake.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, shq, toBytes, wrapCommand } from "../util.js";
+/** Tensorlake has no sandbox-level env, so spec.env lives in this file and every exec sources it. */
+const ENV_FILE = "/tmp/.sandboxrouter.env";
+/**
+ * Tensorlake sandboxes via `@tensorlakeai/tensorlake`. Auth: TENSORLAKE_API_KEY.
+ * Set image.tensorlake to start from your own sandbox image; spec.gpu maps to a GPU model.
+ */
+export class TensorlakeProvider {
+    apiKey;
+    id = "tensorlake";
+    constructor(apiKey = process.env.TENSORLAKE_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("@tensorlakeai/tensorlake", "tensorlake");
+        const image = spec.image?.tensorlake;
+        let sbx;
+        try {
+            sbx = await Sandbox.create({
+                apiKey: this.apiKey,
+                image,
+                cpus: spec.vcpu ?? DEFAULT_VCPU,
+                memoryMb: Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024),
+                timeoutSecs: Math.round((spec.timeoutMinutes ?? 30) * 60),
+                ...(spec.gpu ? { gpuModel: spec.gpu } : {}),
+            });
+        }
+        catch (err) {
+            throw fail(err);
+        }
+        const box = new TensorlakeBox(sbx);
+        if (spec.env && Object.keys(spec.env).length > 0) {
+            try {
+                await box.writeFile(ENV_FILE, wrapCommand(":", { env: spec.env }) + "\n");
+            }
+            catch (err) {
+                await sbx.terminate().catch(() => { });
+                throw err;
+            }
+        }
+        return box;
+    }
+    /** Reattach; a suspended sandbox is resumed. */
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("@tensorlakeai/tensorlake", "tensorlake");
+        try {
+            const sbx = await Sandbox.connect({ sandboxId: nativeId, apiKey: this.apiKey });
+            let status = await sbx.status();
+            // resume() is rejected while a suspend is still in flight.
+            for (let i = 0; status === "suspending" && i < 300; i++) {
+                await sleep(1000);
+                status = await sbx.status();
+            }
+            if (status === "suspended")
+                await sbx.resume();
+            return new TensorlakeBox(sbx);
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+}
+class TensorlakeBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.sandboxId;
+    }
+    /** `sh -c` so cmd is a shell line; spec.env is sourced first so per-call env wins. */
+    shellLine(cmd, opts) {
+        return `[ -f ${shq(ENV_FILE)} ] && . ${shq(ENV_FILE)}; ${wrapCommand(cmd, { cwd: opts.cwd, env: opts.env })}`;
+    }
+    async exec(cmd, opts = {}) {
+        if (opts.onStdout || opts.onStderr)
+            return this.execStreaming(cmd, opts);
+        const t0 = Date.now();
+        const limit = opts.timeoutSeconds ?? 60;
+        try {
+            const r = await this.sbx.run("/bin/sh", { args: ["-c", this.shellLine(cmd, opts)], timeout: limit });
+            if (r.timedOut)
+                throw new ProviderError("tensorlake", `command timed out after ${limit}s`);
+            // A nonzero exit is a result; the SDK only throws for transport/API failures.
+            return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /** Start the process, then follow its combined output stream until it exits. */
+    async execStreaming(cmd, opts) {
+        const t0 = Date.now();
+        const limit = (opts.timeoutSeconds ?? 60) * 1000;
+        const abort = new AbortController();
+        const stdout = [];
+        const stderr = [];
+        let pid;
+        const timer = setTimeout(() => abort.abort(), limit);
+        timer.unref();
+        try {
+            ({ pid } = await this.sbx.startProcess("/bin/sh", { args: ["-c", this.shellLine(cmd, opts)] }));
+            try {
+                for await (const ev of this.sbx.followOutput(pid, { signal: abort.signal })) {
+                    if (ev.stream === "stderr") {
+                        stderr.push(ev.line);
+                        opts.onStderr?.(ev.line + "\n");
+                    }
+                    else {
+                        stdout.push(ev.line);
+                        opts.onStdout?.(ev.line + "\n");
+                    }
+                }
+            }
+            catch (err) {
+                if (!abort.signal.aborted)
+                    throw err;
+            }
+            if (abort.signal.aborted) {
+                await this.sbx.killProcess(pid).catch(() => { });
+                throw new ProviderError("tensorlake", `command timed out after ${limit / 1000}s`);
+            }
+            // The stream can close a moment before the daemon records the exit.
+            let info = await this.sbx.getProcess(pid);
+            for (let i = 0; info.status === "running" && i < 20; i++) {
+                await sleep(250);
+                info = await this.sbx.getProcess(pid);
+            }
+            const exitCode = info.exitCode ?? (info.signal != null ? -info.signal : -1);
+            return { exitCode, stdout: stdout.join("\n"), stderr: stderr.join("\n"), durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sbx.writeFile(path, toBytes(content));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await this.sbx.readFile(path));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /**
+     * Suspend, keeping memory and disk. Only named sandboxes can suspend, so an unnamed one is
+     * named first. router.get() resumes it.
+     */
+    async pause() {
+        try {
+            const info = await this.sbx.info();
+            if (!info.name)
+                await this.sbx.update({ name: `sbr-${randomUUID()}` });
+            await this.sbx.suspend();
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.sbx.terminate();
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+}
+function fail(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = typeof err?.statusCode === "number" ? err.statusCode : undefined;
+    return new ProviderError("tensorlake", err?.message ?? String(err), status);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/vercel.d.ts

@@ -0,0 +1,12 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Vercel Sandbox via `@vercel/sandbox`. Auth: VERCEL_OIDC_TOKEN (from `vercel env pull`), or
+ * VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID. Memory is fixed at 2 GB per vCPU.
+ */
+export declare class VercelProvider implements Provider {
+    readonly id: "vercel";
+    configured(): boolean;
+    private creds;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/vercel.js

@@ -0,0 +1,87 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes, wrapCommand } from "../util.js";
+/**
+ * Vercel Sandbox via `@vercel/sandbox`. Auth: VERCEL_OIDC_TOKEN (from `vercel env pull`), or
+ * VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID. Memory is fixed at 2 GB per vCPU.
+ */
+export class VercelProvider {
+    id = "vercel";
+    configured() {
+        const e = process.env;
+        return !!e.VERCEL_OIDC_TOKEN || (!!e.VERCEL_TOKEN && !!e.VERCEL_TEAM_ID && !!e.VERCEL_PROJECT_ID);
+    }
+    creds() {
+        const e = process.env;
+        return e.VERCEL_TOKEN && e.VERCEL_TEAM_ID && e.VERCEL_PROJECT_ID
+            ? { token: e.VERCEL_TOKEN, teamId: e.VERCEL_TEAM_ID, projectId: e.VERCEL_PROJECT_ID }
+            : {};
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("@vercel/sandbox", "vercel");
+        const vcpus = Math.min(8, Math.max(spec.vcpu ?? DEFAULT_VCPU, Math.ceil((spec.memoryGb ?? DEFAULT_MEMORY_GB) / 2)));
+        const sbx = await Sandbox.create({
+            ...this.creds(),
+            runtime: spec.image?.vercel ?? "node22",
+            timeout: (spec.timeoutMinutes ?? 30) * 60_000,
+            resources: { vcpus },
+            env: spec.env,
+            tags: spec.metadata,
+        });
+        return new VercelBox(sbx);
+    }
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("@vercel/sandbox", "vercel");
+        return new VercelBox(await Sandbox.get({ ...this.creds(), name: nativeId }));
+    }
+}
+class VercelBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.name;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const signal = AbortSignal.timeout((opts.timeoutSeconds ?? 60) * 1000);
+        try {
+            const params = { cmd: "sh", args: ["-c", wrapCommand(cmd)], cwd: opts.cwd, env: opts.env, signal };
+            if (opts.onStdout || opts.onStderr) {
+                const running = await this.sbx.runCommand({ ...params, detached: true });
+                let stdout = "";
+                let stderr = "";
+                for await (const line of running.logs({ signal })) {
+                    if (line.stream === "stdout") {
+                        stdout += line.data;
+                        opts.onStdout?.(line.data);
+                    }
+                    else {
+                        stderr += line.data;
+                        opts.onStderr?.(line.data);
+                    }
+                }
+                const done = await running.wait({ signal });
+                return { exitCode: done.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+            }
+            const r = await this.sbx.runCommand(params);
+            const [stdout, stderr] = await Promise.all([r.stdout(), r.stderr()]);
+            return { exitCode: r.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw new ProviderError("vercel", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        await this.sbx.writeFiles([{ path, content: Buffer.from(toBytes(content)) }]);
+    }
+    async readFile(path) {
+        const buf = await this.sbx.readFileToBuffer({ path });
+        if (!buf)
+            throw new ProviderError("vercel", `no such file: ${path}`);
+        return new Uint8Array(buf);
+    }
+    async kill() {
+        await this.sbx.stop();
+    }
+}

package/dist/router.d.ts

@@ -0,0 +1,65 @@
+import { RoutedComputer, type ComputerProvider, type ComputerSpec } from "./computers.js";
+import { type Attempt, type ExecOptions, type ExecResult, type Provider, type ProviderId, type ProviderSandbox, type RouteOptions, type SandboxSpec } from "./types.js";
+export interface Candidate {
+    provider: ProviderId;
+    estimatedHourlyUsd: number;
+    medianCreateMs?: number;
+    /** Why this provider won't be tried, if it won't. */
+    skip?: string;
+}
+export interface RouterOptions {
+    /** Replace the built-in adapters (tests, custom providers). */
+    providers?: Provider[];
+    /** Path of the bench results file used by strategy "fastest". */
+    benchFile?: string;
+}
+export declare function defaultProviders(): Provider[];
+export declare class Router {
+    private providers;
+    private benchFile?;
+    constructor(opts?: RouterOptions);
+    /** Registered and has credentials. False for providers this router doesn't know. */
+    isConfigured(id: ProviderId): boolean;
+    /** Catalog ids this router has an adapter for, in catalog order. */
+    registered(): ProviderId[];
+    provider(id: ProviderId): Provider;
+    /** The ordered list of providers a create would try, with the reason any are skipped. */
+    plan(spec?: SandboxSpec, route?: RouteOptions): Candidate[];
+    /** Start a sandbox on the best available provider, falling back down the list on failure. */
+    create(spec?: SandboxSpec, route?: RouteOptions): Promise<RoutedSandbox>;
+    /** Providers that also sell computers (desktops/phones). */
+    computerProviders(): ComputerProvider[];
+    /** Get or create a desktop/phone. With `externalUserId`, the same id returns the same computer. */
+    computer(spec?: ComputerSpec, opts?: {
+        provider?: ProviderId | ProviderId[];
+    }): Promise<RoutedComputer>;
+    getComputer(id: string): Promise<RoutedComputer>;
+    /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
+    get(id: string): Promise<RoutedSandbox>;
+}
+export declare class RoutedSandbox {
+    readonly provider: ProviderId;
+    private box;
+    /** Every create attempt, including failed fallbacks. */
+    readonly attempts: Attempt[];
+    readonly estimatedHourlyUsd: number;
+    /** Stable id across processes: `provider:nativeId`. */
+    readonly id: string;
+    constructor(provider: ProviderId, box: ProviderSandbox, 
+    /** Every create attempt, including failed fallbacks. */
+    attempts: Attempt[], estimatedHourlyUsd: number);
+    get nativeId(): string;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    kill(): Promise<void>;
+    /** Pause, keeping the disk. Resume with router.get(id) or, on Maritime, any call. */
+    pause(): Promise<void>;
+    get canPause(): boolean;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare function parseId(id: string): {
+    provider: ProviderId;
+    nativeId: string;
+};