@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/dist/router.js

@@ -0,0 +1,199 @@
+import { CATALOG, hourlyCost, unfit } from "./catalog.js";
+import { RoutedComputer, createComputer } from "./computers.js";
+import { loadBench, median } from "./bench-store.js";
+import { DaytonaProvider } from "./providers/daytona.js";
+import { E2BProvider } from "./providers/e2b.js";
+import { MaritimeProvider } from "./providers/maritime.js";
+import { ModalProvider } from "./providers/modal.js";
+import { VercelProvider } from "./providers/vercel.js";
+import { MorphProvider } from "./providers/morph.js";
+import { SpritesProvider } from "./providers/sprites.js";
+import { BlaxelProvider } from "./providers/blaxel.js";
+import { TensorlakeProvider } from "./providers/tensorlake.js";
+import { RunloopProvider } from "./providers/runloop.js";
+import { DockerProvider } from "./providers/docker.js";
+import { HopxProvider } from "./providers/hopx.js";
+import { CloudflareProvider } from "./providers/cloudflare.js";
+import { NorthflankProvider } from "./providers/northflank.js";
+import { BoatProvider } from "./providers/boat.js";
+import { ExeDevProvider } from "./providers/exedev.js";
+import { RouterError, } from "./types.js";
+export function defaultProviders() {
+    return [
+        new MaritimeProvider(),
+        new E2BProvider(),
+        new DaytonaProvider(),
+        new ModalProvider(),
+        new VercelProvider(),
+        new MorphProvider(),
+        new SpritesProvider(),
+        new BlaxelProvider(),
+        new TensorlakeProvider(),
+        new RunloopProvider(),
+        new HopxProvider(),
+        new CloudflareProvider(),
+        new NorthflankProvider(),
+        new BoatProvider(),
+        new ExeDevProvider(),
+        new DockerProvider(),
+    ];
+}
+export class Router {
+    providers;
+    benchFile;
+    constructor(opts = {}) {
+        this.providers = new Map((opts.providers ?? defaultProviders()).map((p) => [p.id, p]));
+        this.benchFile = opts.benchFile;
+    }
+    /** Registered and has credentials. False for providers this router doesn't know. */
+    isConfigured(id) {
+        return this.providers.get(id)?.configured() ?? false;
+    }
+    /** Catalog ids this router has an adapter for, in catalog order. */
+    registered() {
+        return CATALOG.map((c) => c.id).filter((id) => this.providers.has(id));
+    }
+    provider(id) {
+        const p = this.providers.get(id);
+        if (!p)
+            throw new RouterError(`unknown provider: ${id}`);
+        return p;
+    }
+    /** The ordered list of providers a create would try, with the reason any are skipped. */
+    plan(spec = {}, route = {}) {
+        const explicit = route.provider ? [].concat(route.provider) : null;
+        // Local providers (Docker) are never picked automatically: they always "cost" $0 and isolate
+        // less than a cloud micro-VM. Name them explicitly to use them.
+        const ids = explicit ?? CATALOG.filter((c) => !c.local && this.providers.has(c.id)).map((c) => c.id);
+        const bench = route.strategy === "fastest" ? loadBench(this.benchFile) : {};
+        const list = ids.map((id) => {
+            const p = this.providers.get(id);
+            const c = {
+                provider: id,
+                estimatedHourlyUsd: round(hourlyCost(id, spec)),
+                medianCreateMs: median(bench[id]?.createMs),
+            };
+            if (!p)
+                c.skip = "unknown provider";
+            else
+                c.skip = unfit(id, spec, route.require) ?? (p.configured() ? undefined : "not configured");
+            return c;
+        });
+        // Neutral by construction: price (or measured speed) decides, ties break alphabetically by id.
+        // An explicit provider list keeps the caller's order.
+        if (!explicit) {
+            const byPrice = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
+            if (route.strategy === "fastest") {
+                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
+            }
+            else {
+                list.sort(byPrice);
+            }
+        }
+        return list;
+    }
+    /** Start a sandbox on the best available provider, falling back down the list on failure. */
+    async create(spec = {}, route = {}) {
+        const plan = this.plan(spec, route);
+        const usable = plan.filter((c) => !c.skip);
+        if (usable.length === 0) {
+            const why = plan.map((c) => `${c.provider} (${c.skip})`).join(", ");
+            throw new RouterError(`no provider can take this sandbox: ${why || "none registered"}`);
+        }
+        const attempts = [];
+        const tries = route.fallback === false ? usable.slice(0, 1) : usable;
+        for (const c of tries) {
+            const t0 = Date.now();
+            try {
+                const box = await this.provider(c.provider).create(spec);
+                attempts.push({ provider: c.provider, ok: true, ms: Date.now() - t0 });
+                return new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd);
+            }
+            catch (err) {
+                attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
+            }
+        }
+        throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts);
+    }
+    /** Providers that also sell computers (desktops/phones). */
+    computerProviders() {
+        return [...this.providers.values()].filter((p) => "createComputer" in p);
+    }
+    /** Get or create a desktop/phone. With `externalUserId`, the same id returns the same computer. */
+    computer(spec = {}, opts = {}) {
+        const prefer = opts.provider ? [].concat(opts.provider) : undefined;
+        return createComputer(this.computerProviders(), spec, prefer);
+    }
+    async getComputer(id) {
+        const { provider, nativeId } = parseId(id);
+        const p = this.computerProviders().find((c) => c.id === provider);
+        if (!p)
+            throw new RouterError(`${provider} does not offer computers`);
+        return new RoutedComputer(provider, await p.connectComputer(nativeId));
+    }
+    /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
+    async get(id) {
+        const { provider, nativeId } = parseId(id);
+        const box = await this.provider(provider).connect(nativeId);
+        return new RoutedSandbox(provider, box, [], round(hourlyCost(provider)));
+    }
+}
+export class RoutedSandbox {
+    provider;
+    box;
+    attempts;
+    estimatedHourlyUsd;
+    /** Stable id across processes: `provider:nativeId`. */
+    id;
+    constructor(provider, box, 
+    /** Every create attempt, including failed fallbacks. */
+    attempts, estimatedHourlyUsd) {
+        this.provider = provider;
+        this.box = box;
+        this.attempts = attempts;
+        this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.id = `${provider}:${box.nativeId}`;
+    }
+    get nativeId() {
+        return this.box.nativeId;
+    }
+    exec(cmd, opts) {
+        return this.box.exec(cmd, opts);
+    }
+    writeFile(path, content) {
+        return this.box.writeFile(path, content);
+    }
+    readFile(path) {
+        return this.box.readFile(path);
+    }
+    async readText(path) {
+        return new TextDecoder().decode(await this.box.readFile(path));
+    }
+    kill() {
+        return this.box.kill();
+    }
+    /** Pause, keeping the disk. Resume with router.get(id) or, on Maritime, any call. */
+    async pause() {
+        if (!this.box.pause)
+            throw new RouterError(`${this.provider} does not support pause; create with require: ["pause"]`);
+        await this.box.pause();
+    }
+    get canPause() {
+        return typeof this.box.pause === "function";
+    }
+    async [Symbol.asyncDispose]() {
+        await this.kill();
+    }
+}
+export function parseId(id) {
+    const i = id.indexOf(":");
+    if (i <= 0)
+        throw new RouterError(`bad sandbox id "${id}": expected provider:id`);
+    const provider = id.slice(0, i);
+    if (!CATALOG.some((c) => c.id === provider))
+        throw new RouterError(`unknown provider in id: ${provider}`);
+    return { provider, nativeId: id.slice(i + 1) };
+}
+function round(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { Router } from "./router.js";
+/**
+ * OpenRouter-style HTTP API in front of every provider. One token for your clients; provider keys
+ * stay on this host.
+ *
+ *   GET    /v1/providers
+ *   POST   /v1/route                      dry run: which providers would be tried, in order
+ *   POST   /v1/sandboxes                  { vcpu, memoryGb, ..., provider, strategy, fallback, require }
+ *   POST   /v1/sandboxes/:id/exec         { cmd, cwd, env, timeoutSeconds, stream }
+ *          stream: true answers text/event-stream: `stdout`/`stderr` events (JSON string chunks),
+ *          then one `result` event (the ExecResult), or an `error` event
+ *   POST   /v1/sandboxes/:id/pause        keeps the disk; the next call resumes it
+ *   PUT    /v1/sandboxes/:id/files?path=  raw body
+ *   GET    /v1/sandboxes/:id/files?path=  raw body
+ *   DELETE /v1/sandboxes/:id
+ *
+ *   POST   /v1/computers                  { os, externalUserId, name, screen, arch, provider }
+ *   GET    /v1/computers/:id
+ *   POST   /v1/computers/:id/actions      one action, or { actions: [...] }
+ *   GET    /v1/computers/:id/screenshot   image bytes
+ *   POST   /v1/computers/:id/exec         { command, timeoutSeconds }
+ *   PUT    /v1/computers/:id/files?path=  raw body
+ *   GET    /v1/computers/:id/files?path=  raw body
+ *   POST   /v1/computers/:id/viewer       { mode: "watch" | "control", ttlSeconds, reason }
+ *   POST   /v1/computers/:id/sleep
+ *   DELETE /v1/computers/:id
+ */
+export declare function createApp(router?: Router, token?: string | undefined, 
+/** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
+corsOrigins?: string[]): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;

package/dist/server.js

@@ -0,0 +1,257 @@
+import { createServer } from "node:http";
+import { CATALOG, hourlyCost } from "./catalog.js";
+import { Router } from "./router.js";
+import { ProviderError, RouterError } from "./types.js";
+/**
+ * OpenRouter-style HTTP API in front of every provider. One token for your clients; provider keys
+ * stay on this host.
+ *
+ *   GET    /v1/providers
+ *   POST   /v1/route                      dry run: which providers would be tried, in order
+ *   POST   /v1/sandboxes                  { vcpu, memoryGb, ..., provider, strategy, fallback, require }
+ *   POST   /v1/sandboxes/:id/exec         { cmd, cwd, env, timeoutSeconds, stream }
+ *          stream: true answers text/event-stream: `stdout`/`stderr` events (JSON string chunks),
+ *          then one `result` event (the ExecResult), or an `error` event
+ *   POST   /v1/sandboxes/:id/pause        keeps the disk; the next call resumes it
+ *   PUT    /v1/sandboxes/:id/files?path=  raw body
+ *   GET    /v1/sandboxes/:id/files?path=  raw body
+ *   DELETE /v1/sandboxes/:id
+ *
+ *   POST   /v1/computers                  { os, externalUserId, name, screen, arch, provider }
+ *   GET    /v1/computers/:id
+ *   POST   /v1/computers/:id/actions      one action, or { actions: [...] }
+ *   GET    /v1/computers/:id/screenshot   image bytes
+ *   POST   /v1/computers/:id/exec         { command, timeoutSeconds }
+ *   PUT    /v1/computers/:id/files?path=  raw body
+ *   GET    /v1/computers/:id/files?path=  raw body
+ *   POST   /v1/computers/:id/viewer       { mode: "watch" | "control", ttlSeconds, reason }
+ *   POST   /v1/computers/:id/sleep
+ *   DELETE /v1/computers/:id
+ */
+export function createApp(router = new Router(), token = process.env.SANDBOXROUTER_TOKEN, 
+/** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
+corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.trim()).filter(Boolean)) {
+    const live = new Map();
+    const cors = (req, res) => {
+        const origin = req.headers.origin;
+        if (!origin || !(corsOrigins.includes("*") || corsOrigins.includes(origin)))
+            return false;
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+        res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, Accept");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Max-Age", "600");
+        // Chrome asks before a public HTTPS page (the hosted Playground) may call a server on localhost.
+        if (req.headers["access-control-request-private-network"] === "true") {
+            res.setHeader("Access-Control-Allow-Private-Network", "true");
+        }
+        return true;
+    };
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const parts = url.pathname.split("/").filter(Boolean);
+        const allowed = cors(req, res);
+        if (req.method === "OPTIONS") {
+            res.writeHead(allowed ? 204 : 403);
+            return res.end();
+        }
+        if (url.pathname === "/health")
+            return json(res, 200, { ok: true });
+        if (token && req.headers.authorization !== `Bearer ${token}`)
+            return json(res, 401, { error: "unauthorized" });
+        if (parts[0] !== "v1")
+            return json(res, 404, { error: "not found" });
+        const box = async (id) => live.get(id) ?? router.get(id);
+        // GET /v1/providers
+        if (req.method === "GET" && parts[1] === "providers" && parts.length === 2) {
+            return json(res, 200, {
+                providers: CATALOG.filter((c) => router.registered().includes(c.id)).map((c) => ({
+                    ...c,
+                    configured: router.isConfigured(c.id),
+                    estimatedHourlyUsd: hourlyCost(c.id),
+                })),
+            });
+        }
+        // POST /v1/route
+        if (req.method === "POST" && parts[1] === "route" && parts.length === 2) {
+            const { spec, route } = splitBody(await readJson(req));
+            return json(res, 200, { candidates: router.plan(spec, route) });
+        }
+        if (parts[1] === "computers")
+            return computers(req, res, url, parts);
+        if (parts[1] !== "sandboxes")
+            return json(res, 404, { error: "not found" });
+        // POST /v1/sandboxes
+        if (req.method === "POST" && parts.length === 2) {
+            const { spec, route } = splitBody(await readJson(req));
+            const sbx = await router.create(spec, route);
+            live.set(sbx.id, sbx);
+            return json(res, 201, {
+                id: sbx.id,
+                provider: sbx.provider,
+                estimatedHourlyUsd: sbx.estimatedHourlyUsd,
+                attempts: sbx.attempts,
+            });
+        }
+        const id = parts[2] ? decodeURIComponent(parts[2]) : "";
+        if (!id)
+            return json(res, 404, { error: "not found" });
+        // POST /v1/sandboxes/:id/exec
+        if (req.method === "POST" && parts[3] === "exec") {
+            const body = await readJson(req);
+            if (typeof body.cmd !== "string" || !body.cmd)
+                return json(res, 400, { error: "cmd (string) is required" });
+            const sbx = await box(id);
+            const opts = { cwd: body.cwd, env: body.env, timeoutSeconds: body.timeoutSeconds };
+            if (body.stream !== true)
+                return json(res, 200, await sbx.exec(body.cmd, opts));
+            res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" });
+            const emit = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            try {
+                const r = await sbx.exec(body.cmd, { ...opts, onStdout: (c) => emit("stdout", c), onStderr: (c) => emit("stderr", c) });
+                emit("result", r);
+            }
+            catch (err) {
+                emit("error", { error: err.message });
+            }
+            return res.end();
+        }
+        // POST /v1/sandboxes/:id/pause
+        if (req.method === "POST" && parts[3] === "pause" && parts.length === 4) {
+            await (await box(id)).pause();
+            // Drop the cached handle so the next call reattaches through router.get(), which resumes.
+            live.delete(id);
+            return json(res, 200, { id, paused: true });
+        }
+        // /v1/sandboxes/:id/files?path=
+        if (parts[3] === "files") {
+            const path = url.searchParams.get("path");
+            if (!path)
+                return json(res, 400, { error: "path query parameter is required" });
+            if (req.method === "PUT") {
+                await (await box(id)).writeFile(path, await readRaw(req));
+                return json(res, 200, { ok: true, path });
+            }
+            if (req.method === "GET") {
+                const data = await (await box(id)).readFile(path);
+                res.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Length": data.byteLength });
+                return res.end(Buffer.from(data));
+            }
+        }
+        // DELETE /v1/sandboxes/:id
+        if (req.method === "DELETE" && parts.length === 3) {
+            await (await box(id)).kill();
+            live.delete(id);
+            return json(res, 200, { id, killed: true });
+        }
+        return json(res, 404, { error: "not found" });
+    };
+    const computers = async (req, res, url, parts) => {
+        if (req.method === "POST" && parts.length === 2) {
+            const { provider, ...spec } = await readJson(req);
+            const c = await router.computer(spec, { provider });
+            return json(res, 201, { ...(await c.info()), id: c.id, nativeId: c.nativeId, provider: c.provider });
+        }
+        const id = parts[2] ? decodeURIComponent(parts[2]) : "";
+        if (!id)
+            return json(res, 404, { error: "not found" });
+        const c = await router.getComputer(id);
+        const sub = parts[3];
+        if (req.method === "GET" && !sub)
+            return json(res, 200, { ...(await c.info()), id, nativeId: c.nativeId });
+        if (req.method === "DELETE" && !sub) {
+            await c.delete();
+            return json(res, 200, { id, deleted: true });
+        }
+        if (req.method === "POST" && sub === "actions") {
+            const body = await readJson(req);
+            return json(res, 200, Array.isArray(body.actions) ? { results: await c.actBatch(body.actions) } : await c.act(body));
+        }
+        if (req.method === "GET" && sub === "screenshot") {
+            const format = url.searchParams.get("format") === "jpeg" ? "jpeg" : "png";
+            const img = await c.screenshot({ format, quality: Number(url.searchParams.get("quality")) || undefined });
+            res.writeHead(200, { "Content-Type": `image/${format}`, "Content-Length": img.byteLength });
+            return res.end(Buffer.from(img));
+        }
+        if (req.method === "POST" && sub === "exec") {
+            const body = await readJson(req);
+            if (typeof body.command !== "string" || !body.command)
+                return json(res, 400, { error: "command (string) is required" });
+            return json(res, 200, await c.exec(body.command, body.timeoutSeconds));
+        }
+        if (sub === "files") {
+            const path = url.searchParams.get("path");
+            if (!path)
+                return json(res, 400, { error: "path query parameter is required" });
+            if (req.method === "PUT") {
+                await c.writeFile(path, await readRaw(req));
+                return json(res, 200, { ok: true, path });
+            }
+            if (req.method === "GET") {
+                const data = await c.readFile(path);
+                res.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Length": data.byteLength });
+                return res.end(Buffer.from(data));
+            }
+        }
+        if (req.method === "POST" && sub === "viewer") {
+            const body = await readJson(req);
+            return json(res, 200, await c.viewer(body.mode, { ttlSeconds: body.ttlSeconds, reason: body.reason }));
+        }
+        if (req.method === "POST" && sub === "sleep") {
+            await c.sleep();
+            return json(res, 200, { id, sleeping: true });
+        }
+        return json(res, 404, { error: "not found" });
+    };
+    return createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            const status = err instanceof HttpError ? err.status
+                : err instanceof RouterError ? 502
+                    : err instanceof ProviderError && err.status ? err.status
+                        : 500;
+            json(res, status, { error: err.message, attempts: err.attempts });
+        });
+    });
+}
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const ROUTE_KEYS = ["provider", "strategy", "fallback", "require"];
+function splitBody(body) {
+    const route = {};
+    const spec = {};
+    for (const [k, v] of Object.entries(body))
+        (ROUTE_KEYS.includes(k) ? route : spec)[k] = v;
+    return { spec: spec, route: route };
+}
+const MAX_BODY = 100 * 1024 * 1024;
+async function readRaw(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > MAX_BODY)
+            throw new HttpError(413, "request body too large");
+        chunks.push(c);
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+async function readJson(req) {
+    const raw = Buffer.from(await readRaw(req)).toString("utf8");
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new HttpError(400, "invalid JSON body");
+    }
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}

package/dist/sse.d.ts

@@ -0,0 +1,6 @@
+export interface SSEEvent {
+    event: string;
+    data: string;
+}
+/** Minimal text/event-stream reader for a fetch Response. */
+export declare function readSSE(res: Response): AsyncGenerator<SSEEvent>;

package/dist/sse.js

@@ -0,0 +1,33 @@
+/** Minimal text/event-stream reader for a fetch Response. */
+export async function* readSSE(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let event = "message";
+    let data = [];
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        if (done)
+            buffer += "\n\n";
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).replace(/\r$/, "");
+            buffer = buffer.slice(nl + 1);
+            if (line === "") {
+                if (data.length)
+                    yield { event, data: data.join("\n") };
+                event = "message";
+                data = [];
+            }
+            else if (line.startsWith("event:"))
+                event = line.slice(6).trim();
+            else if (line.startsWith("data:"))
+                data.push(line.slice(5).replace(/^ /, ""));
+        }
+        if (done)
+            return;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "morph" | "sprites" | "blaxel" | "tensorlake" | "runloop" | "hopx" | "cloudflare" | "northflank" | "boat" | "exedev" | "docker";
+/** Things a caller can require of a provider. The router skips providers that lack one. */
+export type Capability = "gpu" | "pause" | "custom-image";
+/** What the caller wants. Every field is optional; providers map it to their own knobs. */
+export interface SandboxSpec {
+    /** vCPUs (default 2). */
+    vcpu?: number;
+    /** Memory in GB (default 4). */
+    memoryGb?: number;
+    /** GPU type, e.g. "T4", "A100". Only providers with the "gpu" capability accept it. */
+    gpu?: string;
+    /** Env vars set for every command. */
+    env?: Record<string, string>;
+    /** Hard lifetime in minutes (default 30). */
+    timeoutMinutes?: number;
+    /**
+     * Provider-specific image/template, keyed by provider, e.g.
+     * { maritime: "python", e2b: "code-interpreter-v1", modal: "python:3.13-slim" }.
+     */
+    image?: Partial<Record<ProviderId, string>>;
+    /** Free-form tags stored on the sandbox where the provider supports it. */
+    metadata?: Record<string, string>;
+}
+/**
+ * "cheapest" (and "default", the same thing): lowest list price for the spec, ties alphabetical.
+ * "fastest": lowest median cold start you measured with `bench`, then cheapest.
+ */
+export type Strategy = "default" | "cheapest" | "fastest";
+export interface RouteOptions {
+    /** Pin to one provider, or give an ordered list to try. Omit to let the router choose. */
+    provider?: ProviderId | ProviderId[];
+    /** How to order candidates when no explicit list is given. Default: cheapest. */
+    strategy?: Strategy;
+    /** Try the next candidate if a create fails (default true). */
+    fallback?: boolean;
+    /** Capabilities every candidate must have. */
+    require?: Capability[];
+}
+export interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Per-command timeout in seconds (default 60). */
+    timeoutSeconds?: number;
+    /** Called with each chunk of stdout as it arrives. The full output is still returned. */
+    onStdout?: (chunk: string) => void;
+    /** Called with each chunk of stderr as it arrives. */
+    onStderr?: (chunk: string) => void;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+}
+/** A live sandbox as one provider sees it. Adapters implement this. */
+export interface ProviderSandbox {
+    readonly nativeId: string;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    kill(): Promise<void>;
+    /** Present only on adapters with the "pause" capability. */
+    pause?(): Promise<void>;
+}
+export interface Provider {
+    readonly id: ProviderId;
+    /** True when the credentials this adapter needs are present. */
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}
+export interface Attempt {
+    provider: ProviderId;
+    ok: boolean;
+    ms: number;
+    error?: string;
+}
+export declare class RouterError extends Error {
+    readonly attempts: Attempt[];
+    constructor(message: string, attempts?: Attempt[]);
+}
+/** Thrown by adapters for HTTP failures so the router can report status codes. */
+export declare class ProviderError extends Error {
+    readonly provider: ProviderId;
+    readonly status?: number | undefined;
+    constructor(provider: ProviderId, message: string, status?: number | undefined);
+}

package/dist/types.js

@@ -0,0 +1,19 @@
+export class RouterError extends Error {
+    attempts;
+    constructor(message, attempts = []) {
+        super(message);
+        this.attempts = attempts;
+        this.name = "RouterError";
+    }
+}
+/** Thrown by adapters for HTTP failures so the router can report status codes. */
+export class ProviderError extends Error {
+    provider;
+    status;
+    constructor(provider, message, status) {
+        super(`${provider}: ${message}`);
+        this.provider = provider;
+        this.status = status;
+        this.name = "ProviderError";
+    }
+}

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+/** Single-quote a string for POSIX sh. */
+export declare function shq(s: string): string;
+/** Build `cd dir && VAR=x cmd` for providers whose exec API lacks cwd/env. */
+export declare function wrapCommand(cmd: string, opts?: {
+    cwd?: string;
+    env?: Record<string, string>;
+}): string;
+export declare function toBytes(content: string | Uint8Array): Uint8Array;
+export declare function dirname(path: string): string;
+/** Load an optional peer dependency with a helpful error. */
+export declare function optionalImport<T>(pkg: string, provider: string): Promise<T>;