@sandboxrouter/sdk 0.1.0 → 0.3.0

package/dist/router.d.ts

@@ -1,4 +1,5 @@
-import { RoutedComputer, type ComputerProvider, type ComputerSpec } from "./computers.js";
+import { RoutedComputer, type ComputerOs, type ComputerProvider, type ComputerProviderId, type ComputerSpec } from "./computers.js";
+import { Ledger } from "./ledger.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;
@@ -12,11 +13,24 @@ export interface RouterOptions {
     providers?: Provider[];
     /** Path of the bench results file used by strategy "fastest". */
     benchFile?: string;
+    /** Desktop-only computer providers (sandbox providers that also sell computers are found automatically). */
+    computers?: ComputerProvider[];
+    /**
+     * Record created sandboxes so leaks can be found and killed (`sandboxrouter ls` / `gc`).
+     * Default: ~/.sandboxrouter/sandboxes.jsonl (or $SANDBOXROUTER_HOME); a path for another file;
+     * false to keep no record. SANDBOXROUTER_LEDGER=off also turns it off.
+     */
+    ledger?: string | false;
 }
+/** Desktop-only providers. Filled in as adapters are added. */
+export declare function defaultComputerProviders(): ComputerProvider[];
 export declare function defaultProviders(): Provider[];
 export declare class Router {
     private providers;
     private benchFile?;
+    private computerOnly;
+    /** The local record of sandboxes this router created, or undefined when turned off. */
+    readonly ledger?: Ledger;
     constructor(opts?: RouterOptions);
     /** Registered and has credentials. False for providers this router doesn't know. */
     isConfigured(id: ProviderId): boolean;
@@ -27,11 +41,17 @@ export declare class Router {
     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). */
+    private record;
+    private discard;
+    /** Every provider that sells computers (desktops/phones): sandbox providers that do, plus desktop-only ones. */
     computerProviders(): ComputerProvider[];
-    /** Get or create a desktop/phone. With `externalUserId`, the same id returns the same computer. */
+    /** The order a computer create would try for this OS. */
+    planComputer(os?: ComputerOs, opts?: {
+        provider?: ComputerProviderId | ComputerProviderId[];
+    }): import("./computers.js").ComputerCandidate[];
+    /** Start a desktop or phone on the cheapest provider for its OS (ties alphabetical), with fallback. */
     computer(spec?: ComputerSpec, opts?: {
-        provider?: ProviderId | ProviderId[];
+        provider?: ComputerProviderId | ComputerProviderId[];
     }): Promise<RoutedComputer>;
     getComputer(id: string): Promise<RoutedComputer>;
     /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
@@ -43,12 +63,19 @@ export declare class RoutedSandbox {
     /** Every create attempt, including failed fallbacks. */
     readonly attempts: Attempt[];
     readonly estimatedHourlyUsd: number;
+    private ledger?;
     /** Stable id across processes: `provider:nativeId`. */
     readonly id: string;
     constructor(provider: ProviderId, box: ProviderSandbox, 
     /** Every create attempt, including failed fallbacks. */
-    attempts: Attempt[], estimatedHourlyUsd: number);
+    attempts: Attempt[], estimatedHourlyUsd: number, ledger?: Ledger | undefined);
     get nativeId(): string;
+    /**
+     * Run a command. If it outlives `opts.timeoutSeconds` the adapter stops it and this rejects with
+     * `ProviderError("<provider>: command timed out after Ns")`. Should an adapter fail to notice its
+     * own deadline, the router gives up `EXEC_GRACE_S` later with the same error, so callers can
+     * always rely on the timeout being bounded and the message being the same on every provider.
+     */
     exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     readFile(path: string): Promise<Uint8Array>;
@@ -63,3 +90,7 @@ export declare function parseId(id: string): {
     provider: ProviderId;
     nativeId: string;
 };
+/** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
+export declare const DEFAULT_CREATE_TIMEOUT_S = 120;
+/** Seconds past a command's timeout before the router stops waiting for the adapter. */
+export declare const EXEC_GRACE_S = 30;

package/dist/router.js

@@ -1,6 +1,8 @@
-import { CATALOG, hourlyCost, unfit } from "./catalog.js";
-import { RoutedComputer, createComputer } from "./computers.js";
+import { CATALOG, accessLabel, hourlyCost, unfit } from "./catalog.js";
+import { RoutedComputer, createComputer, planComputer, } from "./computers.js";
 import { loadBench, median } from "./bench-store.js";
+import { Ledger, defaultLedgerFile } from "./ledger.js";
+import { DEFAULT_EXEC_TIMEOUT_S, timeoutError } from "./util.js";
 import { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -11,7 +13,39 @@ 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 { RouterError, } from "./types.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 { AgentCoreProvider } from "./providers/agentcore.js";
+import { AzureSessionsProvider } from "./providers/azure.js";
+import { LambdaMicrovmProvider } from "./providers/lambda.js";
+import { AlibabaProvider } from "./providers/alibaba.js";
+import { BeamProvider } from "./providers/beam.js";
+import { CodeSandboxProvider } from "./providers/codesandbox.js";
+import { DenoProvider } from "./providers/deno.js";
+import { FreestyleProvider } from "./providers/freestyle.js";
+import { KoyebProvider } from "./providers/koyeb.js";
+import { DedalusProvider } from "./providers/dedalus.js";
+import { Agent37Provider } from "./providers/agent37.js";
+import { OpenScaleProvider } from "./providers/openscale.js";
+import { SuperserveProvider } from "./providers/superserve.js";
+import { SailProvider } from "./providers/sail.js";
+import { InstaboxProvider } from "./providers/instabox.js";
+import { NovitaProvider } from "./providers/novita.js";
+import { LangSmithProvider } from "./providers/langsmith.js";
+import { UpstashProvider } from "./providers/upstash.js";
+import { OrgoProvider } from "./providers/orgo.js";
+import { MobilerunProvider } from "./providers/mobilerun.js";
+import { LimrunProvider } from "./providers/limrun.js";
+import { WorkspacesAgentProvider } from "./providers/workspaces.js";
+import { ProviderError, RouterError, } from "./types.js";
+/** Desktop-only providers. Filled in as adapters are added. */
+export function defaultComputerProviders() {
+    return [new OrgoProvider(), new MobilerunProvider(), new LimrunProvider(), new WorkspacesAgentProvider()];
+}
 export function defaultProviders() {
     return [
         new MaritimeProvider(),
@@ -24,14 +58,45 @@ export function defaultProviders() {
         new BlaxelProvider(),
         new TensorlakeProvider(),
         new RunloopProvider(),
+        new HopxProvider(),
+        new CloudflareProvider(),
+        new NorthflankProvider(),
+        new BoatProvider(),
+        new ExeDevProvider(),
+        new AgentCoreProvider(),
+        new AzureSessionsProvider(),
+        new LambdaMicrovmProvider(),
+        new Agent37Provider(),
+        new AlibabaProvider(),
+        new BeamProvider(),
+        new CodeSandboxProvider(),
+        new DedalusProvider(),
+        new DenoProvider(),
+        new FreestyleProvider(),
+        new InstaboxProvider(),
+        new KoyebProvider(),
+        new NovitaProvider(),
+        new LangSmithProvider(),
+        new OpenScaleProvider(),
+        new SuperserveProvider(),
+        new SailProvider(),
+        new UpstashProvider(),
+        new DockerProvider(),
     ];
 }
 export class Router {
     providers;
     benchFile;
+    computerOnly;
+    /** The local record of sandboxes this router created, or undefined when turned off. */
+    ledger;
     constructor(opts = {}) {
+        const file = opts.ledger === false ? null : (opts.ledger ?? defaultLedgerFile());
+        if (file)
+            this.ledger = new Ledger(file);
         this.providers = new Map((opts.providers ?? defaultProviders()).map((p) => [p.id, p]));
         this.benchFile = opts.benchFile;
+        this.computerOnly = opts.computers ?? (opts.providers ? [] : defaultComputerProviders());
     }
     /** Registered and has credentials. False for providers this router doesn't know. */
     isConfigured(id) {
@@ -50,9 +115,14 @@ export class Router {
     /** 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;
-        const ids = explicit ?? CATALOG.map((c) => c.id).filter((id) => this.providers.has(id));
+        // 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) => {
+            // An id the catalog has never heard of (a typo in an explicit list) has no price to look up.
+            if (!CATALOG.some((c) => c.id === id))
+                return { provider: id, estimatedHourlyUsd: 0, skip: "unknown provider" };
             const p = this.providers.get(id);
             const c = {
                 provider: id,
@@ -60,16 +130,23 @@ export class Router {
                 medianCreateMs: median(bench[id]?.createMs),
             };
             if (!p)
-                c.skip = "unknown provider";
-            else
-                c.skip = unfit(id, spec, route.require) ?? (p.configured() ? undefined : "not configured");
+                c.skip = "no adapter registered";
+            else {
+                const gated = accessLabel(id);
+                c.skip = unfit(id, spec, route.require) ?? (p.configured() ? undefined : gated ? `not configured; ${gated}` : "not configured");
+            }
             return c;
         });
-        if (!explicit && route.strategy === "cheapest") {
-            list.sort((a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd);
-        }
-        else if (!explicit && route.strategy === "fastest") {
-            list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity));
+        // 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;
     }
@@ -83,40 +160,81 @@ export class Router {
         }
         const attempts = [];
         const tries = route.fallback === false ? usable.slice(0, 1) : usable;
+        const limitS = route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S;
         for (const c of tries) {
             const t0 = Date.now();
+            const pending = this.provider(c.provider).create(spec);
+            let timedOut = false;
             try {
-                const box = await this.provider(c.provider).create(spec);
+                const box = await withDeadline(pending, limitS * 1000, () => {
+                    timedOut = true;
+                    return new ProviderError(c.provider, `create timed out after ${limitS}s`);
+                });
                 attempts.push({ provider: c.provider, ok: true, ms: Date.now() - t0 });
-                return new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd);
+                const sbx = new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd, this.ledger);
+                this.record(sbx, c.estimatedHourlyUsd, spec.timeoutMinutes);
+                return sbx;
             }
             catch (err) {
+                // A create that answers after we gave up still made a sandbox: record it, then kill it,
+                // so it can't bill unseen. If the kill fails, the ledger entry is left for `gc`.
+                if (timedOut)
+                    pending.then((late) => this.discard(c.provider, late, c.estimatedHourlyUsd, spec.timeoutMinutes), () => { });
                 attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
+                const status = err instanceof ProviderError ? err.status : undefined;
+                if (route.fallback !== "any" && status !== undefined && SETUP_ERRORS.has(status)) {
+                    throw new RouterError(`${err.message.replace(/[.\s]+$/, "")}. This looks like a setup problem with ${c.provider} (key, billing, image or request), ` +
+                        `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts);
+                }
             }
         }
         throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts);
     }
-    /** Providers that also sell computers (desktops/phones). */
+    record(sbx, usdHour, timeoutMinutes) {
+        const now = Date.now();
+        this.ledger?.open({
+            id: sbx.id,
+            provider: sbx.provider,
+            createdAt: new Date(now).toISOString(),
+            expiresAt: new Date(now + (timeoutMinutes ?? 30) * 60_000).toISOString(),
+            usdHour,
+        });
+    }
+    discard(provider, box, usdHour, timeoutMinutes) {
+        const sbx = new RoutedSandbox(provider, box, [], usdHour, this.ledger);
+        this.record(sbx, usdHour, timeoutMinutes);
+        return sbx.kill().catch(() => { });
+    }
+    /** Every provider that sells computers (desktops/phones): sandbox providers that do, plus desktop-only ones. */
     computerProviders() {
-        return [...this.providers.values()].filter((p) => "createComputer" in p);
+        const fromSandboxes = [...this.providers.values()].filter((p) => "createComputer" in p);
+        return [...fromSandboxes, ...this.computerOnly];
+    }
+    /** The order a computer create would try for this OS. */
+    planComputer(os = "linux", opts = {}) {
+        const prefer = opts.provider ? [].concat(opts.provider) : undefined;
+        return planComputer(this.computerProviders(), os, prefer);
     }
-    /** Get or create a desktop/phone. With `externalUserId`, the same id returns the same computer. */
+    /** Start a desktop or phone on the cheapest provider for its OS (ties alphabetical), with fallback. */
     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 i = id.indexOf(":");
+        if (i <= 0)
+            throw new RouterError(`bad computer id "${id}": expected provider:id`);
+        const provider = id.slice(0, i);
         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));
+        return new RoutedComputer(provider, await p.connectComputer(id.slice(i + 1)));
     }
     /** 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)));
+        return new RoutedSandbox(provider, box, [], round(hourlyCost(provider)), this.ledger);
     }
 }
 export class RoutedSandbox {
@@ -124,22 +242,31 @@ export class RoutedSandbox {
     box;
     attempts;
     estimatedHourlyUsd;
+    ledger;
     /** Stable id across processes: `provider:nativeId`. */
     id;
     constructor(provider, box, 
     /** Every create attempt, including failed fallbacks. */
-    attempts, estimatedHourlyUsd) {
+    attempts, estimatedHourlyUsd, ledger) {
         this.provider = provider;
         this.box = box;
         this.attempts = attempts;
         this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.ledger = ledger;
         this.id = `${provider}:${box.nativeId}`;
     }
     get nativeId() {
         return this.box.nativeId;
     }
-    exec(cmd, opts) {
-        return this.box.exec(cmd, opts);
+    /**
+     * Run a command. If it outlives `opts.timeoutSeconds` the adapter stops it and this rejects with
+     * `ProviderError("<provider>: command timed out after Ns")`. Should an adapter fail to notice its
+     * own deadline, the router gives up `EXEC_GRACE_S` later with the same error, so callers can
+     * always rely on the timeout being bounded and the message being the same on every provider.
+     */
+    exec(cmd, opts = {}) {
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        return withDeadline(this.box.exec(cmd, opts), (seconds + EXEC_GRACE_S) * 1000, () => timeoutError(this.provider, seconds));
     }
     writeFile(path, content) {
         return this.box.writeFile(path, content);
@@ -150,8 +277,9 @@ export class RoutedSandbox {
     async readText(path) {
         return new TextDecoder().decode(await this.box.readFile(path));
     }
-    kill() {
-        return this.box.kill();
+    async kill() {
+        await this.box.kill();
+        this.ledger?.close(this.id);
     }
     /** Pause, keeping the disk. Resume with router.get(id) or, on Maritime, any call. */
     async pause() {
@@ -178,3 +306,24 @@ export function parseId(id) {
 function round(n) {
     return Math.round(n * 10000) / 10000;
 }
+/** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
+export const DEFAULT_CREATE_TIMEOUT_S = 120;
+/** HTTP statuses that mean the request or the account is wrong, not that the provider is down. */
+const SETUP_ERRORS = new Set([400, 401, 402, 403, 404, 422]);
+/** Seconds past a command's timeout before the router stops waiting for the adapter. */
+export const EXEC_GRACE_S = 30;
+/** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */
+async function withDeadline(work, ms, onExpire) {
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(onExpire()), ms);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([work, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+        work.catch(() => { });
+    }
+}

package/dist/server.d.ts

@@ -6,7 +6,7 @@ import { Router } from "./router.js";
  *
  *   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                  { vcpu, memoryGb, ..., provider, strategy, fallback, require, createTimeoutSeconds }
  *   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

package/dist/server.js

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { CATALOG, hourlyCost } from "./catalog.js";
 import { Router } from "./router.js";
@@ -8,7 +9,7 @@ import { ProviderError, RouterError } from "./types.js";
  *
  *   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                  { vcpu, memoryGb, ..., provider, strategy, fallback, require, createTimeoutSeconds }
  *   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
@@ -31,6 +32,19 @@ import { ProviderError, RouterError } from "./types.js";
 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)) {
+    // With CORS on, any page open in a browser on this machine can call the server (Chrome even
+    // lets a public page reach localhost, which the Private-Network header below allows), so it
+    // would start sandboxes on these provider keys. A token is required for that.
+    if (corsOrigins.length && !token) {
+        throw new Error("CORS is on but SANDBOXROUTER_TOKEN is not set: browser pages could start sandboxes on your keys. Set a token, or turn CORS off.");
+    }
+    const expected = token ? Buffer.from(`Bearer ${token}`) : undefined;
+    const authorized = (req) => {
+        if (!expected)
+            return true;
+        const got = Buffer.from(req.headers.authorization ?? "");
+        return got.length === expected.length && timingSafeEqual(got, expected);
+    };
     const live = new Map();
     const cors = (req, res) => {
         const origin = req.headers.origin;
@@ -57,7 +71,7 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         if (url.pathname === "/health")
             return json(res, 200, { ok: true });
-        if (token && req.headers.authorization !== `Bearer ${token}`)
+        if (!authorized(req))
             return json(res, 401, { error: "unauthorized" });
         if (parts[0] !== "v1")
             return json(res, 404, { error: "not found" });
@@ -220,12 +234,17 @@ class HttpError extends Error {
         this.status = status;
     }
 }
-const ROUTE_KEYS = ["provider", "strategy", "fallback", "require"];
+const ROUTE_KEYS = ["provider", "strategy", "fallback", "require", "createTimeoutSeconds"];
 function splitBody(body) {
     const route = {};
     const spec = {};
     for (const [k, v] of Object.entries(body))
         (ROUTE_KEYS.includes(k) ? route : spec)[k] = v;
+    // A provider id the catalog does not know is the client's mistake, not a routing failure.
+    const ids = route.provider === undefined ? [] : [].concat(route.provider);
+    const unknown = ids.filter((id) => !CATALOG.some((c) => c.id === id));
+    if (unknown.length)
+        throw new HttpError(400, `unknown provider: ${unknown.join(", ")}`);
     return { spec: spec, route: route };
 }
 const MAX_BODY = 100 * 1024 * 1024;

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "morph" | "sprites" | "blaxel" | "tensorlake" | "runloop";
+export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "morph" | "sprites" | "blaxel" | "tensorlake" | "runloop" | "hopx" | "cloudflare" | "northflank" | "boat" | "exedev" | "docker" | "novita" | "langsmith" | "alibaba" | "upstash" | "koyeb" | "freestyle" | "deno" | "beam" | "codesandbox" | "azure" | "agentcore" | "lambda" | "dedalus" | "agent37" | "superserve" | "instabox" | "openscale" | "sail";
 /** 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. */
@@ -21,14 +21,26 @@ export interface SandboxSpec {
     /** 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: "default" (catalog order). */
+    /** 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;
+    /**
+     * What to do when a create fails. `true` (default): try the next candidate when the provider
+     * looks unavailable (timeout, network error, 429, 5xx, or an error without a status), but stop on
+     * a setup error (400, 401, 402, 403, 404, 422: a bad key, no billing, a bad image or request), so
+     * a mistake isn't hidden by quietly moving the work to another, maybe pricier, provider.
+     * `"any"`: try the next candidate on every error. `false`: only the first candidate.
+     */
+    fallback?: boolean | "any";
+    /** Seconds to wait for each provider's create before moving on (default 120). */
+    createTimeoutSeconds?: number;
     /** Capabilities every candidate must have. */
     require?: Capability[];
 }
@@ -77,7 +89,7 @@ export declare class RouterError extends Error {
 }
 /** Thrown by adapters for HTTP failures so the router can report status codes. */
 export declare class ProviderError extends Error {
-    readonly provider: ProviderId;
+    readonly provider: ProviderId | (string & {});
     readonly status?: number | undefined;
-    constructor(provider: ProviderId, message: string, status?: number | undefined);
+    constructor(provider: ProviderId | (string & {}), message: string, status?: number | undefined);
 }

package/dist/util.d.ts

@@ -1,10 +1,37 @@
+import { ProviderError, type ProviderId } from "./types.js";
+/** Per-command timeout when ExecOptions.timeoutSeconds is not given. */
+export declare const DEFAULT_EXEC_TIMEOUT_S = 60;
 /** 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. */
+/**
+ * Build `cd dir && export VAR=x && { cmd }` for providers whose exec API lacks cwd/env.
+ *
+ * Every step is chained with `&&`, so a missing cwd stops the command from running somewhere
+ * else, and the shell exits with cd's status instead. The command itself is grouped so its own
+ * `;` or `||` can't escape the chain; the newline before `}` keeps a trailing `#` comment in the
+ * command from swallowing the brace.
+ */
 export declare function wrapCommand(cmd: string, opts?: {
     cwd?: string;
     env?: Record<string, string>;
 }): string;
+/** The one error every adapter throws when a command outlives ExecOptions.timeoutSeconds. */
+export declare function timeoutError(provider: ProviderId | (string & {}), seconds: number): ProviderError;
+/**
+ * True when an exit code is the one left behind by a timeout kill and the command really ran
+ * for the whole timeout: 124 from coreutils `timeout`, 137 after SIGKILL, 143 after SIGTERM, or a
+ * negative code (how some SDKs report a signal death, and what adapters use for "no exit code").
+ * The elapsed check keeps a command that itself exits 124 quickly from being reported as a timeout.
+ */
+export declare function killedByTimeout(exitCode: number, elapsedMs: number, seconds: number): boolean;
+/**
+ * Shell text that runs `cmd` and kills it after `seconds`, for exec APIs that cannot stop a
+ * running command themselves. Prefers coreutils `timeout`, which stops the whole process group
+ * (exit 124, then SIGKILL 5 s later, exit 137). When the image has none, a plain-sh watchdog
+ * kills the command's shell and, where `pkill` exists, its children (exit 137). Callers detect
+ * the kill with `killedByTimeout`.
+ */
+export declare function guardTimeout(cmd: string, seconds: number): 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. */

package/dist/util.js

@@ -1,19 +1,66 @@
+import { ProviderError } from "./types.js";
+/** Per-command timeout when ExecOptions.timeoutSeconds is not given. */
+export const DEFAULT_EXEC_TIMEOUT_S = 60;
 /** Single-quote a string for POSIX sh. */
 export function shq(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-/** Build `cd dir && VAR=x cmd` for providers whose exec API lacks cwd/env. */
+/**
+ * Build `cd dir && export VAR=x && { cmd }` for providers whose exec API lacks cwd/env.
+ *
+ * Every step is chained with `&&`, so a missing cwd stops the command from running somewhere
+ * else, and the shell exits with cd's status instead. The command itself is grouped so its own
+ * `;` or `||` can't escape the chain; the newline before `}` keeps a trailing `#` comment in the
+ * command from swallowing the brace.
+ */
 export function wrapCommand(cmd, opts = {}) {
-    const parts = [];
+    const prelude = [];
     if (opts.cwd)
-        parts.push(`cd ${shq(opts.cwd)} &&`);
+        prelude.push(`cd ${shq(opts.cwd)}`);
     for (const [k, v] of Object.entries(opts.env ?? {})) {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
             throw new Error(`invalid env var name: ${k}`);
-        parts.push(`export ${k}=${shq(v)};`);
+        prelude.push(`export ${k}=${shq(v)}`);
     }
-    parts.push(cmd);
-    return parts.join(" ");
+    if (prelude.length === 0)
+        return cmd;
+    return `${prelude.join(" && ")} && {\n${cmd}\n}`;
+}
+/** The one error every adapter throws when a command outlives ExecOptions.timeoutSeconds. */
+export function timeoutError(provider, seconds) {
+    return new ProviderError(provider, `command timed out after ${seconds}s`);
+}
+/**
+ * True when an exit code is the one left behind by a timeout kill and the command really ran
+ * for the whole timeout: 124 from coreutils `timeout`, 137 after SIGKILL, 143 after SIGTERM, or a
+ * negative code (how some SDKs report a signal death, and what adapters use for "no exit code").
+ * The elapsed check keeps a command that itself exits 124 quickly from being reported as a timeout.
+ */
+export function killedByTimeout(exitCode, elapsedMs, seconds) {
+    const killed = exitCode === 124 || exitCode === 137 || exitCode === 143 || exitCode < 0;
+    return killed && elapsedMs >= seconds * 1000 - TIMEOUT_SLACK_MS;
+}
+/** Clocks on the two sides of an exec call differ by a little; a kill this close to the deadline still counts. */
+const TIMEOUT_SLACK_MS = 250;
+/**
+ * Shell text that runs `cmd` and kills it after `seconds`, for exec APIs that cannot stop a
+ * running command themselves. Prefers coreutils `timeout`, which stops the whole process group
+ * (exit 124, then SIGKILL 5 s later, exit 137). When the image has none, a plain-sh watchdog
+ * kills the command's shell and, where `pkill` exists, its children (exit 137). Callers detect
+ * the kill with `killedByTimeout`.
+ */
+export function guardTimeout(cmd, seconds) {
+    const n = Math.max(1, Math.ceil(seconds));
+    const inner = shq(cmd);
+    return [
+        `if command -v timeout >/dev/null 2>&1; then exec timeout -k 5 ${n} sh -c ${inner}; fi`,
+        `sh -c ${inner} & p=$!`,
+        // Freeze the shell first so it can't run its next command while its children are being killed.
+        `( sleep ${n}; kill -STOP $p; command -v pkill >/dev/null 2>&1 && pkill -KILL -P $p .; kill -9 $p ) >/dev/null 2>&1 & w=$!`,
+        `wait $p; c=$?`,
+        `kill $w >/dev/null 2>&1`,
+        `exit $c`,
+    ].join("\n");
 }
 export function toBytes(content) {
     return typeof content === "string" ? new TextEncoder().encode(content) : content;
@@ -29,7 +76,9 @@ export async function optionalImport(pkg, provider) {
     }
     catch (err) {
         const code = err.code;
-        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+        // Bundlers and test runners (Vite, esbuild) report a missing package without Node's error code.
+        const missing = /Cannot find (module|package)|Could not resolve|Failed to (resolve|load url)/.test(String(err?.message));
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || missing) {
             throw new Error(`${provider} needs the "${pkg}" package: npm i ${pkg}`);
         }
         throw err;