@sandboxrouter/sdk 0.0.0-stage → 0.1.0

package/dist/providers/blaxel.js

@@ -0,0 +1,152 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+/** Blaxel's public base image (the SDK's own default). Set image.blaxel for another image or a `bl deploy` template. */
+const DEFAULT_IMAGE = "blaxel/base-image:latest";
+/** Blaxel rejects a max-age ttl under 5 minutes. */
+const MIN_TTL_MINUTES = 5;
+/**
+ * Blaxel sandboxes via `@blaxel/core`. Auth: BL_API_KEY + BL_WORKSPACE (or `bl login`).
+ * Region: BL_REGION, else us-pdx-1. Blaxel sizes by memory only and gives 1 vCPU per 2 GB,
+ * so memory is max(memoryGb, 2 × vcpu) GB. Idle sandboxes drop to standby on their own and
+ * wake on the next call; pause() archives explicitly.
+ */
+export class BlaxelProvider {
+    apiKey;
+    workspace;
+    region;
+    id = "blaxel";
+    ready;
+    constructor(apiKey = process.env.BL_API_KEY, workspace = process.env.BL_WORKSPACE, region = process.env.BL_REGION ?? "us-pdx-1") {
+        this.apiKey = apiKey;
+        this.workspace = workspace;
+        this.region = region;
+    }
+    configured() {
+        return !!this.apiKey && !!this.workspace;
+    }
+    /** Load the SDK once and point its (global) settings at our credentials. */
+    sdk() {
+        this.ready ??= optionalImport("@blaxel/core", "blaxel").then((m) => {
+            if (this.apiKey && this.workspace)
+                m.initialize({ apiKey: this.apiKey, workspace: this.workspace });
+            return m;
+        });
+        return this.ready;
+    }
+    async create(spec) {
+        const { SandboxInstance } = await this.sdk();
+        const memoryGb = Math.max(spec.memoryGb ?? DEFAULT_MEMORY_GB, (spec.vcpu ?? DEFAULT_VCPU) * 2);
+        const ttlMinutes = Math.max(MIN_TTL_MINUTES, Math.round(spec.timeoutMinutes ?? 30));
+        try {
+            const sbx = await SandboxInstance.create({
+                image: spec.image?.blaxel ?? DEFAULT_IMAGE,
+                memory: Math.round(memoryGb * 1024),
+                region: this.region,
+                envs: Object.entries(spec.env ?? {}).map(([name, value]) => ({ name, value })),
+                labels: spec.metadata,
+                // Max-age from creation, not an idle timeout.
+                ttl: `${ttlMinutes}m`,
+            });
+            return new BlaxelBox(sbx);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reattach by sandbox name; an archived (paused) sandbox is unarchived first. */
+    async connect(nativeId) {
+        const { SandboxInstance } = await this.sdk();
+        try {
+            let sbx = await SandboxInstance.get(nativeId);
+            if (sbx.status === "ARCHIVED" || sbx.status === "ARCHIVING")
+                sbx = await SandboxInstance.unarchive(nativeId);
+            return new BlaxelBox(sbx);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+}
+class BlaxelBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        const name = sbx.metadata.name;
+        if (!name)
+            throw new ProviderError("blaxel", "sandbox has no name");
+        this.nativeId = name;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const timeoutSeconds = opts.timeoutSeconds ?? 60;
+        let r;
+        try {
+            // With onStdout/onStderr the SDK streams logs from the same request as the command runs.
+            r = await this.sbx.process.exec({
+                command: cmd,
+                workingDir: opts.cwd,
+                env: opts.env,
+                timeout: timeoutSeconds,
+                waitForCompletion: true,
+                onStdout: opts.onStdout,
+                onStderr: opts.onStderr,
+            });
+            if (r.status === "running")
+                r = await this.sbx.process.wait(r.pid, { maxWait: timeoutSeconds * 1000 });
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+        if (r.status === "killed" || r.status === "stopped") {
+            throw new ProviderError("blaxel", `command ${r.status} (timeout ${timeoutSeconds}s?)`);
+        }
+        // A nonzero exit is a result (status "failed"), not an error.
+        return { exitCode: r.exitCode, stdout: r.stdout ?? "", stderr: r.stderr ?? "", durationMs: Date.now() - t0 };
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sbx.fs.writeBinary(path, toBytes(content));
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await (await this.sbx.fs.readBinary(path)).arrayBuffer());
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /**
+     * Archive: the filesystem is kept, memory and processes are lost. The max-age ttl is cleared
+     * first so the archive survives until kill(). router.get() unarchives it.
+     */
+    async pause() {
+        const { SandboxInstance } = await optionalImport("@blaxel/core", "blaxel");
+        try {
+            await SandboxInstance.updateTtl(this.nativeId, null);
+            await this.sbx.archive();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.sbx.delete();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+}
+function wrap(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = typeof err?.status === "number" ? err.status : err?.response?.status;
+    return new ProviderError("blaxel", err?.message ?? String(err), status);
+}

package/dist/providers/daytona.d.ts

@@ -0,0 +1,13 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** Daytona via `@daytonaio/sdk`. Default snapshot; set image.daytona to start from an image. */
+export declare class DaytonaProvider implements Provider {
+    private apiKey;
+    readonly id: "daytona";
+    private client?;
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    private daytona;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a paused (stopped) sandbox is started again. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/daytona.js

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes, wrapCommand } from "../util.js";
+/** Daytona via `@daytonaio/sdk`. Default snapshot; set image.daytona to start from an image. */
+export class DaytonaProvider {
+    apiKey;
+    id = "daytona";
+    client;
+    constructor(apiKey = process.env.DAYTONA_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async daytona() {
+        if (!this.client) {
+            const { Daytona } = await optionalImport("@daytonaio/sdk", "daytona");
+            this.client = new Daytona({ apiKey: this.apiKey });
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const d = await this.daytona();
+        const base = {
+            envVars: spec.env,
+            labels: spec.metadata,
+            // Minutes of inactivity before Daytona stops it; delete right after stop.
+            autoStopInterval: Math.max(1, Math.round(spec.timeoutMinutes ?? 30)),
+            autoDeleteInterval: 0,
+        };
+        const sbx = spec.image?.daytona
+            ? await d.create({
+                ...base,
+                image: spec.image.daytona,
+                resources: { cpu: spec.vcpu, memory: spec.memoryGb },
+            })
+            : await d.create(base);
+        return new DaytonaBox(sbx);
+    }
+    /** Reattach; a paused (stopped) sandbox is started again. */
+    async connect(nativeId) {
+        const sbx = await (await this.daytona()).get(nativeId);
+        if (sbx.state === "stopped")
+            await sbx.start();
+        return new DaytonaBox(sbx);
+    }
+}
+class DaytonaBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.id;
+    }
+    async exec(cmd, opts = {}) {
+        if (opts.onStdout || opts.onStderr)
+            return this.execStreaming(cmd, opts);
+        const t0 = Date.now();
+        try {
+            const r = await this.sbx.process.executeCommand(cmd, opts.cwd, opts.env, opts.timeoutSeconds ?? 60);
+            // Daytona merges stdout and stderr into `result` here.
+            return { exitCode: r.exitCode, stdout: r.result, stderr: "", durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw new ProviderError("daytona", err?.message ?? String(err));
+        }
+    }
+    /** Streaming goes through a throwaway session, which also keeps stdout and stderr apart. */
+    async execStreaming(cmd, opts) {
+        const t0 = Date.now();
+        const session = `sbr-${randomUUID()}`;
+        const proc = this.sbx.process;
+        let stdout = "";
+        let stderr = "";
+        try {
+            await proc.createSession(session);
+            const { cmdId } = await proc.executeSessionCommand(session, {
+                command: wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }),
+                runAsync: true,
+            });
+            const logs = proc.getSessionCommandLogs(session, cmdId, (c) => {
+                stdout += c;
+                opts.onStdout?.(c);
+            }, (c) => {
+                stderr += c;
+                opts.onStderr?.(c);
+            });
+            const limit = (opts.timeoutSeconds ?? 60) * 1000;
+            const timedOut = await Promise.race([logs.then(() => false), sleep(limit).then(() => true)]);
+            if (timedOut)
+                throw new ProviderError("daytona", `command timed out after ${limit / 1000}s`);
+            const done = await proc.getSessionCommand(session, cmdId);
+            return { exitCode: done.exitCode ?? -1, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("daytona", err?.message ?? String(err));
+        }
+        finally {
+            await proc.deleteSession(session).catch(() => { });
+        }
+    }
+    async writeFile(path, content) {
+        await this.sbx.fs.uploadFile(Buffer.from(toBytes(content)), path);
+    }
+    async readFile(path) {
+        return new Uint8Array(await this.sbx.fs.downloadFile(path));
+    }
+    /** Stop and keep the disk until kill(). router.get() starts it again. */
+    async pause() {
+        await this.sbx.setAutoDeleteInterval(-1);
+        await this.sbx.stop();
+    }
+    async kill() {
+        await this.sbx.delete();
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/e2b.d.ts

@@ -0,0 +1,10 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** E2B via the official `e2b` SDK. vCPU and memory come from the template, not the create call. */
+export declare class E2BProvider implements Provider {
+    private apiKey;
+    readonly id: "e2b";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/e2b.js

@@ -0,0 +1,69 @@
+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. */
+export class E2BProvider {
+    apiKey;
+    id = "e2b";
+    constructor(apiKey = process.env.E2B_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("e2b", "e2b");
+        const opts = {
+            apiKey: this.apiKey,
+            timeoutMs: (spec.timeoutMinutes ?? 30) * 60_000,
+            envs: spec.env,
+            metadata: spec.metadata,
+        };
+        const sbx = spec.image?.e2b ? await Sandbox.create(spec.image.e2b, opts) : await Sandbox.create(opts);
+        return new E2BBox(sbx);
+    }
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("e2b", "e2b");
+        return new E2BBox(await Sandbox.connect(nativeId, { apiKey: this.apiKey }));
+    }
+}
+class E2BBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.sandboxId;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        try {
+            const r = await this.sbx.commands.run(cmd, {
+                cwd: opts.cwd,
+                envs: opts.env,
+                timeoutMs: (opts.timeoutSeconds ?? 60) * 1000,
+                onStdout: opts.onStdout,
+                onStderr: opts.onStderr,
+            });
+            return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, durationMs: Date.now() - t0 };
+        }
+        catch (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));
+        }
+    }
+    async writeFile(path, content) {
+        await this.sbx.files.write(path, toBytes(content));
+    }
+    async readFile(path) {
+        return await this.sbx.files.read(path, { format: "bytes" });
+    }
+    /** Snapshot memory and disk. Sandbox.connect (router.get) resumes it. */
+    async pause() {
+        await this.sbx.pause();
+    }
+    async kill() {
+        await this.sbx.kill();
+    }
+}

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>;
+}