@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/dist/providers/hopx.js

@@ -0,0 +1,168 @@
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+/** Public template used when spec.image.hopx is not set. */
+const DEFAULT_TEMPLATE = "code-interpreter";
+/**
+ * HOPX via `@hopx-ai/sdk`. Auth: HOPX_API_KEY. vCPU and memory come from the template, not the
+ * create call (HOPX does not take custom resources at create). Set image.hopx to a template name
+ * (or a numeric template id) to start from your own; default is the public "code-interpreter".
+ */
+export class HopxProvider {
+    apiKey;
+    id = "hopx";
+    constructor(apiKey = process.env.HOPX_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("@hopx-ai/sdk", "hopx");
+        const image = spec.image?.hopx ?? DEFAULT_TEMPLATE;
+        try {
+            const sbx = await Sandbox.create({
+                ...(/^\d+$/.test(image) ? { templateId: image } : { template: image }),
+                apiKey: this.apiKey,
+                timeoutSeconds: Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)),
+                envVars: spec.env,
+            });
+            return new HopxBox(sbx);
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /** Reattach; the SDK resumes a paused sandbox. */
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("@hopx-ai/sdk", "hopx");
+        try {
+            return new HopxBox(await Sandbox.connect(nativeId, this.apiKey));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+}
+class HopxBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.sandboxId;
+    }
+    async exec(cmd, opts = {}) {
+        if (opts.onStdout || opts.onStderr)
+            return this.execStreaming(cmd, opts);
+        const t0 = Date.now();
+        try {
+            const r = await this.sbx.commands.run(cmd, {
+                timeout: opts.timeoutSeconds ?? 60,
+                workingDir: opts.cwd,
+                env: opts.env,
+            });
+            // A nonzero exit comes back as a normal response with exit_code set.
+            return { exitCode: r.exit_code ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "", durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /** Streams over the agent's WebSocket (/execute/stream) with the code run as bash. */
+    async execStreaming(cmd, opts) {
+        const t0 = Date.now();
+        const seconds = opts.timeoutSeconds ?? 60;
+        let stdout = "";
+        let stderr = "";
+        let exitCode;
+        const run = async () => {
+            const stream = this.sbx.runCodeStream(cmd, {
+                language: "bash",
+                timeout: seconds,
+                workingDir: opts.cwd,
+                env: opts.env,
+            });
+            for await (const m of stream) {
+                if (m.type === "stdout") {
+                    stdout += m.data;
+                    opts.onStdout?.(m.data);
+                }
+                else if (m.type === "stderr") {
+                    stderr += m.data;
+                    opts.onStderr?.(m.data);
+                }
+                else if (m.type === "result") {
+                    exitCode = m.exit_code;
+                }
+                else if (m.type === "error") {
+                    const msg = m.code === "EXECUTION_TIMEOUT" ? `command timed out after ${seconds}s` : m.error;
+                    throw new ProviderError("hopx", msg);
+                }
+            }
+        };
+        try {
+            // The agent enforces the timeout; the extra grace covers a stream that never closes.
+            const graceMs = (seconds + 30) * 1000;
+            const timedOut = await Promise.race([run().then(() => false), sleep(graceMs).then(() => true)]);
+            if (timedOut)
+                throw new ProviderError("hopx", `command timed out after ${seconds}s`);
+            if (exitCode === undefined)
+                throw new ProviderError("hopx", "stream closed before the command finished");
+            return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sbx.files.writeBytes(path, Buffer.from(toBytes(content)));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await this.sbx.files.readBytes(path));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /** Pause with memory and disk kept. router.get() (Sandbox.connect) resumes it. */
+    async pause() {
+        try {
+            await this.sbx.pause();
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.sbx.kill();
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+}
+/** HTTP status for SDK errors that drop it (only APIError keeps statusCode). */
+const STATUS_BY_NAME = {
+    AuthenticationError: 401,
+    TokenExpiredError: 401,
+    RateLimitError: 429,
+    NotFoundError: 404,
+    TemplateNotFoundError: 404,
+    FileNotFoundError: 404,
+    SandboxExpiredError: 410,
+};
+function fail(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = err?.statusCode ?? err?.response?.status ?? STATUS_BY_NAME[err?.name];
+    return new ProviderError("hopx", err?.message ?? String(err), status);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/maritime.d.ts

@@ -0,0 +1,38 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+import type { ComputerOs, ComputerProvider, ComputerSpec, ProviderComputer } from "../computers.js";
+/**
+ * Maritime over plain REST (no SDK needed).
+ * Control plane: https://api.maritime.sh  (Bearer mk_ key)
+ * Data plane:    sandbox.dataPlaneUrl      (X-Maritime-Token: sandbox.secret)
+ *   POST /commands         run; with Accept: text/event-stream it streams stdout/stderr events
+ *   GET|PUT /files?path=   raw bytes
+ * Any data plane call resumes a paused sandbox.
+ * Docs: https://maritime.sh/docs/ephemeral-sandboxes
+ */
+export declare class MaritimeProvider implements Provider, ComputerProvider {
+    private apiKey;
+    private baseUrl;
+    readonly id: "maritime";
+    readonly computerOs: ComputerOs[];
+    constructor(apiKey?: string | undefined, baseUrl?: string);
+    configured(): boolean;
+    /** @internal */
+    request(method: string, url: string, init?: {
+        json?: unknown;
+        bytes?: Uint8Array;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    /** @internal */
+    json<T>(method: string, url: string, init?: {
+        json?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /** @internal */
+    control<T>(method: string, path: string, json?: unknown): Promise<T>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** @internal Control-plane call that returns the raw Response (binary bodies). */
+    controlRaw(method: string, path: string, bytes?: Uint8Array): Promise<Response>;
+    createComputer(spec: ComputerSpec): Promise<ProviderComputer>;
+    connectComputer(nativeId: string): Promise<ProviderComputer>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/maritime.js

@@ -0,0 +1,240 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { toBytes } from "../util.js";
+import { readSSE } from "../sse.js";
+/**
+ * Maritime over plain REST (no SDK needed).
+ * Control plane: https://api.maritime.sh  (Bearer mk_ key)
+ * Data plane:    sandbox.dataPlaneUrl      (X-Maritime-Token: sandbox.secret)
+ *   POST /commands         run; with Accept: text/event-stream it streams stdout/stderr events
+ *   GET|PUT /files?path=   raw bytes
+ * Any data plane call resumes a paused sandbox.
+ * Docs: https://maritime.sh/docs/ephemeral-sandboxes
+ */
+export class MaritimeProvider {
+    apiKey;
+    baseUrl;
+    id = "maritime";
+    computerOs = ["linux", "windows", "android"];
+    constructor(apiKey = process.env.MARITIME_API_KEY, baseUrl = process.env.MARITIME_API_URL ?? "https://api.maritime.sh") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /** @internal */
+    async request(method, url, init = {}) {
+        const headers = { ...init.headers };
+        let body;
+        if (init.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        else if (init.bytes) {
+            headers["Content-Type"] = "application/octet-stream";
+            body = init.bytes;
+        }
+        const res = await fetch(url, { method, headers, body });
+        if (!res.ok) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                // Sandboxes: {code, message}. Computers: {error, message, retryAfterS}. Agents: {detail}.
+                const code = j?.code ?? (typeof j?.error === "string" ? j.error : undefined);
+                detail = code ? `${code}: ${j.message ?? ""}` : j?.detail ? JSON.stringify(j.detail) : detail;
+            }
+            catch {
+                /* non-JSON body */
+            }
+            throw new ProviderError(this.id, `${method} ${new URL(url).pathname} -> ${res.status} ${detail}`, res.status);
+        }
+        return res;
+    }
+    /** @internal */
+    async json(method, url, init = {}) {
+        const text = await (await this.request(method, url, init)).text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /** @internal */
+    control(method, path, json) {
+        if (!this.apiKey)
+            throw new ProviderError(this.id, "MARITIME_API_KEY is not set");
+        return this.json(method, `${this.baseUrl}${path}`, { json, headers: { Authorization: `Bearer ${this.apiKey}` } });
+    }
+    async create(spec) {
+        const timeLimit = clamp(Math.round(spec.timeoutMinutes ?? 30), 5, 1440);
+        const body = {
+            from: spec.image?.maritime ?? "base",
+            vcpu: clamp(Math.round(spec.vcpu ?? DEFAULT_VCPU), 1, 16),
+            memoryMib: clamp(Math.ceil(spec.memoryGb ?? DEFAULT_MEMORY_GB), 1, 64) * 1024,
+            timeLimitMinutes: timeLimit,
+            // The router promises a hard lifetime, so don't let the idle timer end it much earlier.
+            idleMinutes: clamp(timeLimit, 1, 60),
+        };
+        if (spec.env)
+            body.env = spec.env;
+        if (spec.metadata)
+            body.metadata = spec.metadata;
+        return new MaritimeSandbox(this, await this.control("POST", "/api/sandboxes/ephemeral", body));
+    }
+    /** @internal Control-plane call that returns the raw Response (binary bodies). */
+    controlRaw(method, path, bytes) {
+        if (!this.apiKey)
+            throw new ProviderError(this.id, "MARITIME_API_KEY is not set");
+        return this.request(method, `${this.baseUrl}${path}`, { bytes, headers: { Authorization: `Bearer ${this.apiKey}` } });
+    }
+    async createComputer(spec) {
+        const body = { os: spec.os ?? "linux" };
+        for (const k of ["externalUserId", "name", "screen", "arch"])
+            if (spec[k] !== undefined)
+                body[k] = spec[k];
+        const c = await this.control("POST", "/api/v1/computers", body);
+        return new MaritimeComputer(this, c.id);
+    }
+    async connectComputer(nativeId) {
+        const c = await this.control("GET", `/api/v1/computers/${encodeURIComponent(nativeId)}`);
+        return new MaritimeComputer(this, c.id);
+    }
+    async connect(nativeId) {
+        const sbx = await this.control("GET", `/v1/sandboxes/${encodeURIComponent(nativeId)}`);
+        if (!sbx.dataPlaneUrl || !sbx.secret)
+            throw new ProviderError(this.id, `sandbox ${nativeId} has no data plane (state: ${sbx.state})`);
+        return new MaritimeSandbox(this, sbx);
+    }
+}
+class MaritimeSandbox {
+    p;
+    sbx;
+    nativeId;
+    constructor(p, sbx) {
+        this.p = p;
+        this.sbx = sbx;
+        this.nativeId = sbx.id;
+    }
+    /** Data plane call; on 401 re-reads the sandbox once in case the secret was rotated. */
+    async data(method, path, init = {}) {
+        const go = () => this.p.request(method, `${this.sbx.dataPlaneUrl}${path}`, {
+            ...init,
+            headers: { ...init.headers, "X-Maritime-Token": this.sbx.secret ?? "" },
+        });
+        try {
+            return await go();
+        }
+        catch (err) {
+            if (!(err instanceof ProviderError && err.status === 401))
+                throw err;
+            this.sbx = await this.p.control("GET", `/v1/sandboxes/${encodeURIComponent(this.nativeId)}`);
+            return go();
+        }
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const body = { cmd, cwd: opts.cwd, env: opts.env, timeoutSeconds: opts.timeoutSeconds ?? 60 };
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        const res = await this.data("POST", "/commands", {
+            json: body,
+            headers: streaming ? { Accept: "text/event-stream" } : {},
+        });
+        let result;
+        if (streaming && res.headers.get("content-type")?.includes("text/event-stream")) {
+            for await (const ev of readSSE(res)) {
+                const payload = JSON.parse(ev.data);
+                if (ev.event === "stdout")
+                    opts.onStdout?.(payload);
+                else if (ev.event === "stderr")
+                    opts.onStderr?.(payload);
+                else if (ev.event === "result")
+                    result = payload;
+                else if (ev.event === "error")
+                    throw new ProviderError("maritime", `${payload?.code ?? "error"}: ${payload?.message ?? ev.data}`);
+            }
+            if (!result)
+                throw new ProviderError("maritime", "output stream closed before the command finished");
+        }
+        else {
+            result = JSON.parse(await res.text());
+            // Server answered without streaming: deliver the output in one chunk.
+            if (result.stdout)
+                opts.onStdout?.(result.stdout);
+            if (result.stderr)
+                opts.onStderr?.(result.stderr);
+        }
+        return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", durationMs: Date.now() - t0 };
+    }
+    async writeFile(path, content) {
+        await this.data("PUT", `/files?path=${encodeURIComponent(path)}`, { bytes: toBytes(content) });
+    }
+    async readFile(path) {
+        const res = await this.data("GET", `/files?path=${encodeURIComponent(path)}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async pause() {
+        await this.p.control("POST", `/v1/sandboxes/${encodeURIComponent(this.nativeId)}/pause`);
+    }
+    async kill() {
+        await this.p.control("DELETE", `/api/sandboxes/ephemeral/${encodeURIComponent(this.nativeId)}`);
+    }
+}
+/** A Maritime desktop or phone. REST: /api/v1/computers/{id}/... (camelCase fields). */
+class MaritimeComputer {
+    p;
+    nativeId;
+    base;
+    constructor(p, nativeId) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.base = `/api/v1/computers/${encodeURIComponent(nativeId)}`;
+    }
+    info() {
+        return this.p.control("GET", this.base);
+    }
+    act(action) {
+        return this.p.control("POST", `${this.base}/actions`, action);
+    }
+    async actBatch(actions) {
+        const r = await this.p.control("POST", `${this.base}/actions`, { actions });
+        return r.results;
+    }
+    async screenshot(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.format)
+            q.set("format", opts.format);
+        if (opts.quality)
+            q.set("quality", String(opts.quality));
+        const res = await this.p.controlRaw("GET", `${this.base}/screenshot${q.size ? `?${q}` : ""}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async exec(command, timeoutSeconds = 30) {
+        const r = await this.p.control("POST", `${this.base}/exec`, {
+            command,
+            timeoutS: Math.min(30, timeoutSeconds),
+        });
+        return { exitCode: r.exitCode ?? -1, stdout: r.stdout, stderr: r.stderr };
+    }
+    async readFile(path) {
+        const res = await this.p.controlRaw("GET", `${this.base}/files?path=${encodeURIComponent(path)}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async writeFile(path, content) {
+        await this.p.controlRaw("PUT", `${this.base}/files?path=${encodeURIComponent(path)}`, toBytes(content));
+    }
+    viewer(mode = "watch", opts = {}) {
+        const body = { mode };
+        if (opts.ttlSeconds !== undefined)
+            body.ttlS = opts.ttlSeconds;
+        if (opts.reason !== undefined)
+            body.reason = opts.reason;
+        return this.p.control("POST", `${this.base}/viewer`, body);
+    }
+    async sleep() {
+        await this.p.control("POST", `${this.base}/sleep`);
+    }
+    async delete() {
+        await this.p.control("DELETE", this.base);
+    }
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}

package/dist/providers/modal.d.ts

@@ -0,0 +1,10 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** Modal via the `modal` JS SDK. The only adapter here that takes `gpu`. */
+export declare class ModalProvider implements Provider {
+    readonly id: "modal";
+    private client?;
+    configured(): boolean;
+    private modal;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/modal.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+const APP_NAME = process.env.SANDBOXROUTER_MODAL_APP ?? "sandboxrouter";
+/** Modal via the `modal` JS SDK. The only adapter here that takes `gpu`. */
+export class ModalProvider {
+    id = "modal";
+    client;
+    configured() {
+        return (!!process.env.MODAL_TOKEN_ID && !!process.env.MODAL_TOKEN_SECRET) || existsSync(join(homedir(), ".modal.toml"));
+    }
+    async modal() {
+        if (!this.client) {
+            const { ModalClient } = await optionalImport("modal", "modal");
+            this.client = new ModalClient();
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const modal = await this.modal();
+        const app = await modal.apps.fromName(APP_NAME, { createIfMissing: true });
+        const image = modal.images.fromRegistry(spec.image?.modal ?? "python:3.13-slim");
+        const sb = await modal.sandboxes.create(app, image, {
+            cpu: spec.vcpu ?? DEFAULT_VCPU,
+            memoryMiB: Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024),
+            gpu: spec.gpu,
+            timeoutMs: (spec.timeoutMinutes ?? 30) * 60_000,
+            env: spec.env,
+        });
+        return new ModalBox(sb);
+    }
+    async connect(nativeId) {
+        return new ModalBox(await (await this.modal()).sandboxes.fromId(nativeId));
+    }
+}
+/** Read a text stream to the end, passing each chunk to `on`. */
+async function drain(stream, on) {
+    const reader = stream.getReader();
+    let out = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return out;
+        out += value;
+        on?.(value);
+    }
+}
+class ModalBox {
+    sb;
+    nativeId;
+    constructor(sb) {
+        this.sb = sb;
+        this.nativeId = sb.sandboxId;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        try {
+            const p = await this.sb.exec(["sh", "-c", cmd], {
+                workdir: opts.cwd,
+                env: opts.env,
+                timeoutMs: (opts.timeoutSeconds ?? 60) * 1000,
+            });
+            const [stdout, stderr, exitCode] = await Promise.all([drain(p.stdout, opts.onStdout), drain(p.stderr, opts.onStderr), p.wait()]);
+            return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw new ProviderError("modal", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        await this.sb.filesystem.writeBytes(toBytes(content), path);
+    }
+    async readFile(path) {
+        return await this.sb.filesystem.readBytes(path);
+    }
+    async kill() {
+        await this.sb.terminate();
+    }
+}

package/dist/providers/morph.d.ts

@@ -0,0 +1,19 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Morph Cloud via `morphcloud`. Instances start from snapshots: by default a cached snapshot of
+ * morphvm-minimal sized to spec.vcpu / spec.memoryGb; set image.morph to a snapshot id to start
+ * from your own (its resources come from the snapshot).
+ */
+export declare class MorphProvider implements Provider {
+    private apiKey;
+    readonly id: "morph";
+    private client?;
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    private morph;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a paused instance is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+    /** Reuse (or create once) a morphvm-minimal snapshot with this shape, keyed by digest. */
+    private baseSnapshot;
+}