@sandboxrouter/sdk 0.4.0 → 0.5.0

package/README.md

@@ -30,14 +30,15 @@ Site and docs: [sandboxrouter.vercel.app](https://sandboxrouter.vercel.app) · n
 AI agents need a disposable computer to run code a model wrote: install packages, run tests, do an RL rollout. Dozens of providers sell one, each with its own SDK and auth, and the same 2 vCPU / 4 GB sandbox costs from under a cent to over thirty cents an hour. sandboxrouter is one interface over all of them:
 
 - **Same code everywhere.** `create`, `exec` (streamed), `writeFile`, `readFile`, `pause`, `kill`. Switch providers by changing which keys are set.
-- **Cheapest real cost, then speed, with fallback.** Or `cheapest` for list price alone, `fastest` by start times, `verified` for tested providers first, or a list of providers you name.
+- **Cheapest real cost, then speed, with fallback.** Or `cheapest` for list price alone, `fastest` by start times, `verified` for tested providers first, or a list of providers you name. `requireVerified` limits a router to providers that passed the real-account check.
+- **Errors you can act on.** Every failure has a `code` (`no_provider`, `setup`, `all_failed`, `timeout`, ...), an HTTP status, and the list of providers tried.
 - **Your keys.** Your accounts and your bills; nothing is proxied through anyone else.
 - **Cleanup.** A local ledger of every sandbox started, so `sandboxrouter gc` kills what a crashed script left behind.
 - **TypeScript, Python, HTTP and a CLI.** Plus desktops and phones for computer-use models.
 
 ## Prices
 
-List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups follow. The router tries the ones that passed the real-account check first. "Up to" = CPU billed only while busy, shown with every core busy. "Not run yet" = built from the provider's docs and tested against mocks only. Click a provider for its billing details; more in [Reading the price table](https://sandboxrouter.vercel.app/docs#price-table).
+List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups follow. The router ranks by these, corrected where we measured what a provider really bills, and tries providers whose last real-account check failed last. "Up to" = CPU billed only while busy, shown with every core busy. "Not run yet" = built from the provider's docs and tested against mocks only. Click a provider for its billing details; more in [Reading the price table](https://sandboxrouter.vercel.app/docs#price-table).
 
 | Provider | $/hr | Plan needed | Real-account check | Source |
 |---|---|---|---|---|

package/dist/cli.js

@@ -156,11 +156,13 @@ async function main() {
         let n = 0;
         for (const c of plan) {
             const mark = c.skip ? "  -" : `${++n}.`.padStart(3);
-            const tested = c.failing ? "check failed " : c.verified ? "tested       " : "             ";
-            // The billed column only shows where a measured bill moved it off list price.
-            const real = c.effectiveHourlyUsd !== c.estimatedHourlyUsd ? ` (billed ~$${c.effectiveHourlyUsd.toFixed(4)})` : "";
-            const speed = c.medianCreateMs !== undefined ? `${c.medianCreateMs} ms  ` : "";
-            console.log(`${mark} ${c.provider.padEnd(11)} $${c.estimatedHourlyUsd.toFixed(4)}/hr${real}  ${speed}${tested}${c.skip ? `(skipped: ${c.skip})` : ""}`.trimEnd());
+            const tested = c.failing ? "check failed" : c.verified ? "tested" : "";
+            // The list price only shows where a measured bill moved the estimate off it.
+            const list = c.listHourlyUsd !== c.estimatedHourlyUsd ? ` (list $${c.listHourlyUsd.toFixed(4)})` : "";
+            const size = `${c.size.vcpu} vCPU / ${c.size.memoryGb} GB`;
+            const speed = c.medianCreateMs !== undefined ? `${c.medianCreateMs} ms` : "";
+            const cols = [`$${c.estimatedHourlyUsd.toFixed(4)}/hr${list}`, size, speed, tested].filter(Boolean).join("  ");
+            console.log(`${mark} ${c.provider.padEnd(11)} ${cols}${c.skip ? `  (skipped: ${c.skip})` : ""}`);
         }
         return;
     }

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import type { Attempt, ExecOptions, ExecResult, RouteOptions, SandboxSpec } from "./types.js";
+import type { Candidate, Size } from "./router.js";
+import type { Attempt, ExecOptions, ExecResult, RouteOptions, RouterErrorCode, SandboxSpec } from "./types.js";
 /**
  * Client for the sandboxrouter HTTP API: the hosted service (one key, prepaid credits) or your own
  * `sandboxrouter serve`. Provider keys live on the server; this side only needs the one key.
@@ -20,18 +21,16 @@ export declare class Client {
     /** @internal */
     request(method: string, path: string, body?: unknown, accept?: string): Promise<Response>;
     private json;
-    /** Providers this server can route to, with list prices. */
+    /** Providers this server can route to, with prices at the default size. */
     providers(): Promise<{
         id: string;
         configured: boolean;
         estimatedHourlyUsd: number;
+        listHourlyUsd: number;
+        size: Size;
     }[]>;
-    /** Dry run: which providers would be tried, in order. */
-    route(spec?: SandboxSpec, route?: RouteOptions): Promise<{
-        provider: string;
-        estimatedHourlyUsd: number;
-        skip?: string;
-    }[]>;
+    /** Dry run: which providers would be tried, in order, each with its price, size and any reason it's skipped. */
+    route(spec?: SandboxSpec, route?: RouteOptions): Promise<Candidate[]>;
     /** Start a sandbox on the first provider that works, as the server routes it. */
     create(spec?: SandboxSpec, route?: RouteOptions): Promise<RemoteSandbox>;
     /** A handle on a sandbox you created earlier. */
@@ -40,19 +39,42 @@ export declare class Client {
 export declare class ClientError extends Error {
     readonly status: number;
     readonly attempts: Attempt[];
-    constructor(status: number, message: string, attempts?: Attempt[]);
+    /** The server's RouterErrorCode, when the router refused or failed (e.g. "no_provider", "all_failed"). */
+    readonly code?: RouterErrorCode | undefined;
+    constructor(status: number, message: string, attempts?: Attempt[], 
+    /** The server's RouterErrorCode, when the router refused or failed (e.g. "no_provider", "all_failed"). */
+    code?: RouterErrorCode | undefined);
+}
+/** What POST /v1/sandboxes answers. A hosted service may add fields (e.g. what it charges). */
+export interface CreateResponse {
+    id: string;
+    provider: string;
+    size?: Size;
+    estimatedHourlyUsd?: number;
+    listHourlyUsd?: number;
+    attempts: Attempt[];
+    [field: string]: unknown;
 }
 export declare class RemoteSandbox {
     private readonly client;
     readonly id: string;
     readonly provider: string;
-    readonly estimatedHourlyUsd?: number | undefined;
+    /** The full create response, including any fields the server added. Empty for `client.sandbox(id)`. */
+    readonly details: Partial<CreateResponse>;
+    readonly estimatedHourlyUsd?: number;
+    readonly listHourlyUsd?: number;
+    readonly size?: Size;
     readonly attempts: Attempt[];
-    constructor(client: Client, id: string, provider: string, estimatedHourlyUsd?: number | undefined, attempts?: Attempt[]);
+    constructor(client: Client, id: string, provider: string, 
+    /** The full create response, including any fields the server added. Empty for `client.sandbox(id)`. */
+    details?: Partial<CreateResponse>);
     private path;
     exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     readFile(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
     pause(): Promise<void>;
     kill(): Promise<void>;
+    /** `await using sbx = await client.create()` kills it when the block ends. */
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/client.js

@@ -35,28 +35,25 @@ export class Client {
                 parsed = JSON.parse(text);
             }
             catch { }
-            throw new ClientError(res.status, parsed.error ?? (text || res.statusText), parsed.attempts ?? []);
+            throw new ClientError(res.status, parsed.error ?? (text || res.statusText), parsed.attempts ?? [], parsed.code);
         }
         return res;
     }
     async json(method, path, body) {
         return (await this.request(method, path, body)).json();
     }
-    /** Providers this server can route to, with list prices. */
+    /** Providers this server can route to, with prices at the default size. */
     async providers() {
         return (await this.json("GET", "/v1/providers")).providers;
     }
-    /** Dry run: which providers would be tried, in order. */
+    /** Dry run: which providers would be tried, in order, each with its price, size and any reason it's skipped. */
     async route(spec = {}, route = {}) {
         return (await this.json("POST", "/v1/route", { ...spec, ...route })).candidates;
     }
     /** Start a sandbox on the first provider that works, as the server routes it. */
     async create(spec = {}, route = {}) {
-        const r = await this.json("POST", "/v1/sandboxes", {
-            ...spec,
-            ...route,
-        });
-        return new RemoteSandbox(this, r.id, r.provider, r.estimatedHourlyUsd, r.attempts);
+        const r = await this.json("POST", "/v1/sandboxes", { ...spec, ...route });
+        return new RemoteSandbox(this, r.id, r.provider, r);
     }
     /** A handle on a sandbox you created earlier. */
     sandbox(id) {
@@ -67,10 +64,14 @@ const DEFAULT_URL = "http://127.0.0.1:8787";
 export class ClientError extends Error {
     status;
     attempts;
-    constructor(status, message, attempts = []) {
+    code;
+    constructor(status, message, attempts = [], 
+    /** The server's RouterErrorCode, when the router refused or failed (e.g. "no_provider", "all_failed"). */
+    code) {
         super(`${status}: ${message}`);
         this.status = status;
         this.attempts = attempts;
+        this.code = code;
         this.name = "ClientError";
     }
 }
@@ -78,14 +79,22 @@ export class RemoteSandbox {
     client;
     id;
     provider;
+    details;
     estimatedHourlyUsd;
+    listHourlyUsd;
+    size;
     attempts;
-    constructor(client, id, provider, estimatedHourlyUsd, attempts = []) {
+    constructor(client, id, provider, 
+    /** The full create response, including any fields the server added. Empty for `client.sandbox(id)`. */
+    details = {}) {
         this.client = client;
         this.id = id;
         this.provider = provider;
-        this.estimatedHourlyUsd = estimatedHourlyUsd;
-        this.attempts = attempts;
+        this.details = details;
+        this.estimatedHourlyUsd = details.estimatedHourlyUsd;
+        this.listHourlyUsd = details.listHourlyUsd;
+        this.size = details.size;
+        this.attempts = details.attempts ?? [];
     }
     path(suffix = "") {
         return `/v1/sandboxes/${encodeURIComponent(this.id)}${suffix}`;
@@ -118,7 +127,7 @@ export class RemoteSandbox {
                 else if (event === "result")
                     return payload;
                 else if (event === "error")
-                    throw new ClientError(502, payload.error ?? data);
+                    throw new ClientError(payload.status ?? 502, payload.error ?? data, [], payload.code);
             }
         }
         throw new ClientError(502, "stream ended before the command finished");
@@ -131,10 +140,17 @@ export class RemoteSandbox {
         const res = await this.client.request("GET", this.path(`/files?path=${encodeURIComponent(path)}`), undefined, "application/octet-stream");
         return new Uint8Array(await res.arrayBuffer());
     }
+    async readText(path) {
+        return new TextDecoder().decode(await this.readFile(path));
+    }
     async pause() {
         await this.client.request("POST", this.path("/pause"));
     }
     async kill() {
         await this.client.request("DELETE", this.path());
     }
+    /** `await using sbx = await client.create()` kills it when the block ends. */
+    async [Symbol.asyncDispose]() {
+        await this.kill();
+    }
 }

package/dist/index.d.ts

@@ -2,10 +2,13 @@ export { checkProvider, CHECK_STEPS, type CheckReport, type CheckResult, type Ch
 export { Ledger, defaultLedgerFile, type LedgerEntry } from "./ledger.js";
 export { conformanceTable, loadConformance, type ConformanceRow, type SavedCheck } from "./conformance.js";
 export { gc, listOpen, isGone, type GcResult, type OpenSandbox } from "./gc.js";
-export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId, type Candidate, type RouterOptions } from "./router.js";
+export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId, balanced, sizeOf, PRICE_TIE, DEFAULT_CREATE_TIMEOUT_S, DEFAULT_CREATE_DEADLINE_S, type Candidate, type RouterOptions, type SandboxPrice, type Size, } from "./router.js";
+export { VERIFIED, FAILING } from "./verified.js";
+export { BILLED_VS_LIST } from "./billing.js";
+export { validate, splitRequest, SPEC_KEYS, ROUTE_KEYS, STRATEGIES } from "./validate.js";
 export { CATALOG, hourlyCost, unfit, info, type ProviderInfo } from "./catalog.js";
-export { createApp, HttpError, type ServerHooks } from "./server.js";
-export { Client, ClientError, RemoteSandbox } from "./client.js";
+export { createApp, HttpError, ERROR_STATUS, type ServerHooks } from "./server.js";
+export { Client, ClientError, RemoteSandbox, type CreateResponse } from "./client.js";
 export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, type ComputerCatalogEntry, type ComputerCandidate, type ComputerProviderId, type ActionResult, type ComputerAction, type ComputerActionName, type ComputerInfo, type ComputerOs, type ComputerProvider, type ComputerSpec, type ProviderComputer, } from "./computers.js";
 export { bench, benchMarkdown, type BenchRow } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard, type BenchReport, type LeaderRow } from "./leaderboard.js";

package/dist/index.js

@@ -2,9 +2,12 @@ export { checkProvider, CHECK_STEPS } from "./check.js";
 export { Ledger, defaultLedgerFile } from "./ledger.js";
 export { conformanceTable, loadConformance } from "./conformance.js";
 export { gc, listOpen, isGone } from "./gc.js";
-export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId } from "./router.js";
+export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId, balanced, sizeOf, PRICE_TIE, DEFAULT_CREATE_TIMEOUT_S, DEFAULT_CREATE_DEADLINE_S, } from "./router.js";
+export { VERIFIED, FAILING } from "./verified.js";
+export { BILLED_VS_LIST } from "./billing.js";
+export { validate, splitRequest, SPEC_KEYS, ROUTE_KEYS, STRATEGIES } from "./validate.js";
 export { CATALOG, hourlyCost, unfit, info } from "./catalog.js";
-export { createApp, HttpError } from "./server.js";
+export { createApp, HttpError, ERROR_STATUS } from "./server.js";
 export { Client, ClientError, RemoteSandbox } from "./client.js";
 export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
 export { bench, benchMarkdown } from "./bench.js";

package/dist/ledger.d.ts

@@ -8,8 +8,15 @@ export interface LedgerEntry {
     createdAt: string;
     /** ISO time its requested lifetime (spec.timeoutMinutes) runs out. */
     expiresAt: string;
-    /** Estimated list price per hour while it runs. */
+    /** Expected cost per hour while it runs (list price x measured billed ratio). */
     usdHour: number;
+    /** List price per hour. Missing in entries written before 0.5.0. */
+    listUsdHour?: number;
+    /** Size it was created at. Missing in entries written before 0.5.0. */
+    size?: {
+        vcpu: number;
+        memoryGb: number;
+    };
 }
 /**
  * Where the default ledger lives: $SANDBOXROUTER_HOME/sandboxes.jsonl, else ~/.sandboxrouter/.

package/dist/router.d.ts

@@ -1,15 +1,28 @@
 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";
+/** vCPUs and memory a sandbox gets. */
+export interface Size {
+    vcpu: number;
+    memoryGb: number;
+}
 export interface Candidate {
     provider: ProviderId;
-    /** List price for the spec, USD/hour. What the sandbox is expected to cost at the provider's published rates. */
+    /**
+     * What the sandbox is expected to cost, USD/hour: the provider's list price for this size, times what
+     * it really billed against list price where we measured that (`billedVsList`). The default strategy
+     * ranks by this, and a service reselling sandboxes should charge from it.
+     */
     estimatedHourlyUsd: number;
+    /** The provider's published list price for this size, USD/hour. */
+    listHourlyUsd: number;
+    /** Billed / list-price ratio behind `estimatedHourlyUsd`, when measured (`BILLED_VS_LIST`). */
+    billedVsList?: number;
     /**
-     * List price x what the provider really billed against list price, where that was measured
-     * (`BILLED_VS_LIST`, or `RouterOptions.billedVsList`); the list price otherwise. The default strategy ranks by this.
+     * The size the sandbox gets: the provider's fixed default image size where it has one, else what was
+     * asked for (2 vCPU / 4 GB when nothing was). Some providers round up to their next size.
      */
-    effectiveHourlyUsd: number;
+    size: Size;
     /** Median create time: this router's own recent creates when it has a few, else your `bench` file. */
     medianCreateMs?: number;
     /** Passed the real-account check (as of this release, or `RouterOptions.verified`). */
@@ -48,7 +61,7 @@ export interface RouterOptions {
      * costs money. Default false.
      */
     requireVerified?: boolean;
-    /** Billed / list-price ratio per provider, for the default ranking. Default: `BILLED_VS_LIST` from saved cost runs. */
+    /** Billed / list-price ratio per provider, behind `estimatedHourlyUsd`. Default: the ratios in `BILLED_VS_LIST`, from saved cost runs. */
     billedVsList?: Partial<Record<ProviderId, number>>;
 }
 /** Desktop-only providers. Filled in as adapters are added. */
@@ -99,18 +112,31 @@ export declare class Router {
     /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
     get(id: string): Promise<RoutedSandbox>;
 }
+/** What a sandbox costs and its size, as the router priced it when it was created. */
+export interface SandboxPrice {
+    /** Expected cost, USD/hour: list price x what the provider really billed against it, where measured. */
+    estimatedHourlyUsd: number;
+    /** The provider's published list price for this size, USD/hour. */
+    listHourlyUsd: number;
+    size: Size;
+}
 export declare class RoutedSandbox {
     readonly provider: ProviderId;
     private box;
     /** Every create attempt, including failed fallbacks. */
     readonly attempts: Attempt[];
-    readonly estimatedHourlyUsd: number;
     private ledger?;
     /** Stable id across processes: `provider:nativeId`. */
     readonly id: string;
+    /** Expected cost, USD/hour (see `Candidate.estimatedHourlyUsd`). Undefined for a handle from `get()` this machine didn't create. */
+    readonly estimatedHourlyUsd?: number;
+    /** The provider's list price for this size, USD/hour. */
+    readonly listHourlyUsd?: number;
+    /** The size it was created at (see `Candidate.size`). */
+    readonly size?: Size;
     constructor(provider: ProviderId, box: ProviderSandbox, 
     /** Every create attempt, including failed fallbacks. */
-    attempts: Attempt[], estimatedHourlyUsd: number, ledger?: Ledger | undefined);
+    attempts: Attempt[], price?: SandboxPrice, ledger?: Ledger | undefined);
     get nativeId(): string;
     /**
      * Run a command. If it outlives `opts.timeoutSeconds` the adapter stops it and this rejects with
@@ -141,5 +167,9 @@ export declare function parseId(id: string): {
 export declare function balanced(list: Candidate[]): Candidate[];
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export declare const DEFAULT_CREATE_TIMEOUT_S = 120;
+/** Seconds a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */
+export declare const DEFAULT_CREATE_DEADLINE_S = 240;
 /** Seconds past a command's timeout before the router stops waiting for the adapter. */
 export declare const EXEC_GRACE_S = 30;
+/** The size a provider gives for a spec: its fixed default image size, else what was asked for. */
+export declare function sizeOf(id: ProviderId, spec?: SandboxSpec): Size;

package/dist/router.js

@@ -1,10 +1,11 @@
-import { CATALOG, accessLabel, hourlyCost, unfit } from "./catalog.js";
+import { CATALOG, DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, fixedSize, 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, errorStatus, timeoutError } from "./util.js";
 import { BILLED_VS_LIST } from "./billing.js";
 import { FAILING, VERIFIED } from "./verified.js";
+import { validate } from "./validate.js";
 import { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -128,11 +129,12 @@ export class Router {
     provider(id) {
         const p = this.providers.get(id);
         if (!p)
-            throw new RouterError(`unknown provider: ${id}`);
+            throw new RouterError(`unknown provider: ${id}`, [], "bad_request");
         return p;
     }
     /** The ordered list of providers a create would try, with the reason any are skipped. */
     plan(spec = {}, route = {}) {
+        validate(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.
@@ -142,15 +144,19 @@ export class Router {
         const bench = speed ? 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, effectiveHourlyUsd: 0, verified: false, failing: false, skip: "unknown provider" };
+            if (!CATALOG.some((c) => c.id === id)) {
+                return { provider: id, estimatedHourlyUsd: 0, listHourlyUsd: 0, size: { vcpu: 0, memoryGb: 0 }, verified: false, failing: false, skip: "unknown provider" };
+            }
             const p = this.providers.get(id);
             const list = round(hourlyCost(id, spec));
+            const ratio = this.billed[id];
             const live = this.live.get(id);
             const c = {
                 provider: id,
-                estimatedHourlyUsd: list,
-                effectiveHourlyUsd: round(list * (this.billed[id] ?? 1)),
+                estimatedHourlyUsd: round(list * (ratio ?? 1)),
+                listHourlyUsd: list,
+                ...(ratio !== undefined ? { billedVsList: ratio } : {}),
+                size: sizeOf(id, spec),
                 medianCreateMs: speed ? (live && live.length >= LIVE_MIN_SAMPLES ? median(live) : median(bench[id]?.createMs)) : undefined,
                 verified: this.verified.has(id),
                 failing: this.failing.has(id),
@@ -170,15 +176,16 @@ export class Router {
         // depends on who the provider is, only on its price, what it really billed, how fast it started for
         // this router and whether its last real-account check failed. An explicit list keeps the caller's order.
         if (!explicit) {
-            const byPrice = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
+            const byCost = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
+            const byList = (a, b) => a.listHourlyUsd - b.listHourlyUsd || a.provider.localeCompare(b.provider);
             if (strategy === "fastest") {
-                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
+                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byCost(a, b));
             }
             else if (strategy === "cheapest") {
-                list.sort(byPrice);
+                list.sort(byList);
             }
             else if (strategy === "verified") {
-                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byPrice(a, b));
+                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byCost(a, b));
             }
             else {
                 return balanced(list);
@@ -219,41 +226,52 @@ export class Router {
         const plan = this.plan(spec, route);
         const usable = plan.filter((c) => !c.skip);
         if (usable.length === 0)
-            throw new RouterError(this.whyNone(plan, !!route.provider));
+            throw new RouterError(this.whyNone(plan, !!route.provider), [], "no_provider");
+        // Pinned with no fallback: the first provider named, or nothing. Never a different one.
+        if (route.provider && route.fallback === false && plan[0].skip) {
+            throw new RouterError(`${plan[0].provider} can't take this sandbox: ${plan[0].skip}`, [], "no_provider");
+        }
         const attempts = [];
         const tries = route.fallback === false ? usable.slice(0, 1) : usable;
         const limitS = route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S;
+        const deadline = Date.now() + (route.deadlineSeconds ?? DEFAULT_CREATE_DEADLINE_S) * 1000;
         for (const c of tries) {
+            const left = deadline - Date.now();
+            if (left <= 0) {
+                throw new RouterError(`create ran out of time (deadlineSeconds) after trying ${attempts.map((a) => a.provider).join(", ")}: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "timeout");
+            }
             const t0 = Date.now();
             const pending = this.provider(c.provider).create(spec);
+            const waitS = Math.min(limitS, left / 1000);
+            const price = { estimatedHourlyUsd: c.estimatedHourlyUsd, listHourlyUsd: c.listHourlyUsd, size: c.size };
             let timedOut = false;
             try {
-                const box = await withDeadline(pending, limitS * 1000, () => {
+                const box = await withDeadline(pending, waitS * 1000, () => {
                     timedOut = true;
-                    return new ProviderError(c.provider, `create timed out after ${limitS}s`);
+                    return new ProviderError(c.provider, `create timed out after ${Number(waitS.toFixed(1))}s`);
                 });
                 attempts.push({ provider: c.provider, ok: true, ms: Date.now() - t0 });
                 this.observe(c.provider, Date.now() - t0);
-                const sbx = new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd, this.ledger);
-                this.record(sbx, c.estimatedHourlyUsd, spec.timeoutMinutes);
+                const sbx = new RoutedSandbox(c.provider, box, attempts, price, this.ledger);
+                this.record(sbx, price, 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), () => { });
+                    pending.then((late) => this.discard(c.provider, late, price, spec.timeoutMinutes), () => { });
                 const status = errorStatus(err);
                 attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message, ...(status ? { status } : {}) });
                 const setup = err instanceof SetupError || (status !== undefined && SETUP_ERRORS.has(status));
                 if (route.fallback !== "any" && setup) {
                     const msg = err.message.replace(/[.\s]+$/, "");
                     throw new RouterError(`${msg.startsWith(c.provider) ? msg : `${c.provider}: ${msg}`}. This looks like a setup problem with ${c.provider} (key, image, request or a missing package), ` +
-                        `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts);
+                        `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts, "setup");
                 }
             }
         }
-        throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts);
+        throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "all_failed");
     }
     /** Remember a successful create's time, for the speed tie-break and strategy "fastest". */
     observe(id, ms) {
@@ -263,19 +281,21 @@ export class Router {
             xs.shift();
         this.live.set(id, xs);
     }
-    record(sbx, usdHour, timeoutMinutes) {
+    record(sbx, price, 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,
+            usdHour: price.estimatedHourlyUsd,
+            listUsdHour: price.listHourlyUsd,
+            size: price.size,
         });
     }
-    discard(provider, box, usdHour, timeoutMinutes) {
-        const sbx = new RoutedSandbox(provider, box, [], usdHour, this.ledger);
-        this.record(sbx, usdHour, timeoutMinutes);
+    discard(provider, box, price, timeoutMinutes) {
+        const sbx = new RoutedSandbox(provider, box, [], price, this.ledger);
+        this.record(sbx, price, timeoutMinutes);
         return sbx.kill().catch(() => { });
     }
     /** Every provider that sells computers (desktops/phones): sandbox providers that do, plus desktop-only ones. */
@@ -307,26 +327,37 @@ export class Router {
     async get(id) {
         const { provider, nativeId } = parseId(id);
         const box = await this.provider(provider).connect(nativeId);
-        return new RoutedSandbox(provider, box, [], round(hourlyCost(provider)), this.ledger);
+        // The price and size come from this machine's ledger when it started the sandbox; otherwise
+        // they're unknown (a guess at the default size would be wrong for anything bigger).
+        const e = this.ledger?.list().find((x) => x.id === id);
+        const price = e && e.listUsdHour !== undefined && e.size ? { estimatedHourlyUsd: e.usdHour, listHourlyUsd: e.listUsdHour, size: e.size } : undefined;
+        return new RoutedSandbox(provider, box, [], price, this.ledger);
     }
 }
 export class RoutedSandbox {
     provider;
     box;
     attempts;
-    estimatedHourlyUsd;
     ledger;
     /** Stable id across processes: `provider:nativeId`. */
     id;
+    /** Expected cost, USD/hour (see `Candidate.estimatedHourlyUsd`). Undefined for a handle from `get()` this machine didn't create. */
+    estimatedHourlyUsd;
+    /** The provider's list price for this size, USD/hour. */
+    listHourlyUsd;
+    /** The size it was created at (see `Candidate.size`). */
+    size;
     constructor(provider, box, 
     /** Every create attempt, including failed fallbacks. */
-    attempts, estimatedHourlyUsd, ledger) {
+    attempts, price, ledger) {
         this.provider = provider;
         this.box = box;
         this.attempts = attempts;
-        this.estimatedHourlyUsd = estimatedHourlyUsd;
         this.ledger = ledger;
         this.id = `${provider}:${box.nativeId}`;
+        this.estimatedHourlyUsd = price?.estimatedHourlyUsd;
+        this.listHourlyUsd = price?.listHourlyUsd;
+        this.size = price?.size;
     }
     get nativeId() {
         return this.box.nativeId;
@@ -357,7 +388,7 @@ export class RoutedSandbox {
     /** 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"]`);
+            throw new RouterError(`${this.provider} does not support pause; create with require: ["pause"]`, [], "unsupported");
         await this.box.pause();
     }
     get canPause() {
@@ -370,10 +401,10 @@ export class RoutedSandbox {
 export function parseId(id) {
     const i = id.indexOf(":");
     if (i <= 0)
-        throw new RouterError(`bad sandbox id "${id}": expected provider:id`);
+        throw new RouterError(`bad sandbox id "${id}": expected provider:id`, [], "bad_request");
     const provider = id.slice(0, i);
     if (!CATALOG.some((c) => c.id === provider))
-        throw new RouterError(`unknown provider in id: ${provider}`);
+        throw new RouterError(`unknown provider in id: ${provider}`, [], "bad_request");
     return { provider, nativeId: id.slice(i + 1) };
 }
 function round(n) {
@@ -386,14 +417,15 @@ function round(n) {
  * median create time; unknown speed after known), then cheapest, then alphabetical.
  */
 export function balanced(list) {
-    const byCost = (a, b) => a.effectiveHourlyUsd - b.effectiveHourlyUsd || a.provider.localeCompare(b.provider);
+    const byCost = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
     const bySpeed = (a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byCost(a, b);
     const order = (group) => {
         const rest = [...group].sort(byCost);
         const out = [];
         while (rest.length) {
-            const limit = rest[0].effectiveHourlyUsd * (1 + PRICE_TIE);
-            const tie = rest.filter((c) => c.effectiveHourlyUsd <= limit);
+            const limit = rest[0].estimatedHourlyUsd * (1 + PRICE_TIE);
+            // Always take at least the cheapest, so the loop ends whatever the prices are.
+            const tie = rest.filter((c, i) => i === 0 || c.estimatedHourlyUsd <= limit);
             out.push(...tie.sort(bySpeed));
             rest.splice(0, tie.length);
         }
@@ -403,6 +435,8 @@ export function balanced(list) {
 }
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export const DEFAULT_CREATE_TIMEOUT_S = 120;
+/** Seconds a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */
+export const DEFAULT_CREATE_DEADLINE_S = 240;
 /**
  * HTTP statuses that mean the request or the key is wrong, not that the provider is down. 402 (out of
  * balance, plan needed) isn't one: an unfunded account is exactly when the next provider should take the
@@ -426,3 +460,7 @@ async function withDeadline(work, ms, onExpire) {
         work.catch(() => { });
     }
 }
+/** The size a provider gives for a spec: its fixed default image size, else what was asked for. */
+export function sizeOf(id, spec = {}) {
+    return fixedSize(id, spec) ?? { vcpu: spec.vcpu ?? DEFAULT_VCPU, memoryGb: spec.memoryGb ?? DEFAULT_MEMORY_GB };
+}

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { Router, type RoutedSandbox } from "./router.js";
-import { type RouteOptions, type SandboxSpec } from "./types.js";
+import { type RouteOptions, type RouterErrorCode, type SandboxSpec } from "./types.js";
 /**
  * Hooks for running this API for many users (accounts, billing, per-user sandboxes). With none set,
  * the server is single-user: one SANDBOXROUTER_TOKEN, every sandbox reachable by anyone holding it.
@@ -10,15 +10,27 @@ export interface ServerHooks {
     authorize?(req: IncomingMessage): Promise<unknown | null>;
     /** Routes outside /v1 (sign-in, billing webhooks, pages), checked before auth. Return true if handled. */
     extra?(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
-    /** Before a sandbox starts. Throw HttpError to refuse (402 out of credit, 429 too many); may edit spec. */
+    /** Before a sandbox starts. Throw HttpError to refuse (402 out of credit, 429 too many); may edit spec and route. */
     beforeCreate?(caller: unknown, spec: SandboxSpec, route: RouteOptions): Promise<void>;
-    /** After it started. If this throws, the sandbox is killed and the error returned. */
-    afterCreate?(caller: unknown, sbx: RoutedSandbox, spec: SandboxSpec): Promise<void>;
+    /**
+     * After it started. Return fields to add to the create response (e.g. what the caller is charged). If
+     * this throws, the sandbox is killed and the error returned. Not called when the caller hung up before
+     * the sandbox was ready: that sandbox is killed instead.
+     */
+    afterCreate?(caller: unknown, sbx: RoutedSandbox, spec: SandboxSpec): Promise<Record<string, unknown> | void>;
+    /** A create that passed beforeCreate ended without a sandbox for the caller. Release whatever beforeCreate held. */
+    createFailed?(caller: unknown): Promise<void> | void;
     /** May this caller use this sandbox? No means 404. */
     owns?(caller: unknown, id: string): Promise<boolean>;
-    /** After DELETE killed it. */
-    afterKill?(caller: unknown, id: string): Promise<void>;
-    /** false turns off /v1/computers. */
+    /**
+     * After DELETE. `error` is set when the provider's kill failed (the sandbox may still be running): the
+     * server answers with the error, but the caller asked for it gone, so stop charging them for it. A kill
+     * of a sandbox the provider no longer has counts as done.
+     */
+    afterKill?(caller: unknown, id: string, outcome?: {
+        error?: Error;
+    }): Promise<void>;
+    /** /v1/computers. Default: on for a single-user server, off when `authorize` is set (computers don't go through these hooks). */
     computers?: boolean;
     /** false turns off pause. */
     pause?: boolean;
@@ -56,3 +68,5 @@ export declare class HttpError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** The HTTP status for each RouterError code (see RouterErrorCode). */
+export declare const ERROR_STATUS: Record<RouterErrorCode, number>;

package/dist/server.js

@@ -1,8 +1,10 @@
 import { timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
-import { CATALOG, hourlyCost } from "./catalog.js";
+import { CATALOG } from "./catalog.js";
 import { Router } from "./router.js";
 import { ProviderError, RouterError } from "./types.js";
+import { errorStatus } from "./util.js";
+import { splitRequest } from "./validate.js";
 /**
  * OpenRouter-style HTTP API in front of every provider. One token for your clients; provider keys
  * stay on this host.
@@ -46,6 +48,7 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         return got.length === expected.length && timingSafeEqual(got, expected);
     };
     const live = new Map();
+    const computersOn = hooks.computers ?? !hooks.authorize;
     const cors = (req, res) => {
         const origin = req.headers.origin;
         if (!origin || !(corsOrigins.includes("*") || corsOrigins.includes(origin)))
@@ -91,20 +94,19 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         // 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),
-                })),
+                providers: CATALOG.filter((c) => router.registered().includes(c.id)).map((c) => {
+                    const p = router.plan({}, { provider: c.id })[0];
+                    return { ...c, configured: router.isConfigured(c.id), estimatedHourlyUsd: p.estimatedHourlyUsd, listHourlyUsd: p.listHourlyUsd, size: p.size };
+                }),
             });
         }
         // POST /v1/route
         if (req.method === "POST" && parts[1] === "route" && parts.length === 2) {
-            const { spec, route } = splitBody(await readJson(req));
+            const { spec, route } = splitRequest(await readJson(req));
             return json(res, 200, { candidates: router.plan(spec, route) });
         }
         if (parts[1] === "computers") {
-            if (hooks.computers === false)
+            if (!computersOn)
                 return json(res, 404, { error: "computers aren't available on this server" });
             return computers(req, res, url, parts);
         }
@@ -112,22 +114,40 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
             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 { spec, route } = splitRequest(await readJson(req));
             await hooks.beforeCreate?.(caller, spec, route);
-            const sbx = await router.create(spec, route);
+            // A caller that gives up (client timeout, closed connection) never learns the id: kill what
+            // starts after that rather than leave it running, and billing, unseen.
+            let hungUp = false;
+            res.on("close", () => (hungUp = !res.writableFinished));
+            let sbx;
+            let extra;
             try {
-                await hooks.afterCreate?.(caller, sbx, spec);
+                sbx = await router.create(spec, route);
+            }
+            catch (err) {
+                await hooks.createFailed?.(caller);
+                throw err;
+            }
+            try {
+                if (hungUp)
+                    throw new HttpError(499, "the client closed the connection before the sandbox was ready; it was killed");
+                extra = await hooks.afterCreate?.(caller, sbx, spec);
             }
             catch (err) {
                 await sbx.kill().catch(() => { });
+                await hooks.createFailed?.(caller);
                 throw err;
             }
             live.set(sbx.id, sbx);
             return json(res, 201, {
                 id: sbx.id,
                 provider: sbx.provider,
+                size: sbx.size,
                 estimatedHourlyUsd: sbx.estimatedHourlyUsd,
+                listHourlyUsd: sbx.listHourlyUsd,
                 attempts: sbx.attempts,
+                ...(extra ?? {}),
             });
         }
         const id = parts[2] ? decodeURIComponent(parts[2]) : "";
@@ -149,7 +169,8 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
                 emit("result", r);
             }
             catch (err) {
-                emit("error", { error: err.message });
+                const e = describeError(err);
+                emit("error", { ...e.body, status: e.status });
             }
             return res.end();
         }
@@ -179,7 +200,20 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         // DELETE /v1/sandboxes/:id
         if (req.method === "DELETE" && parts.length === 3) {
-            await (await box(id)).kill();
+            try {
+                await (await box(id)).kill();
+            }
+            catch (err) {
+                // Already gone at the provider: that's what the caller wanted.
+                if (!(err instanceof HttpError) && errorStatus(err) === 404) {
+                    live.delete(id);
+                    await hooks.afterKill?.(caller, id);
+                    return json(res, 200, { id, killed: true });
+                }
+                if (!(err instanceof HttpError))
+                    await hooks.afterKill?.(caller, id, { error: err });
+                throw err;
+            }
             live.delete(id);
             await hooks.afterKill?.(caller, id);
             return json(res, 200, { id, killed: true });
@@ -245,11 +279,11 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
     };
     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 });
+            // A closed connection can't be answered.
+            if (res.writableEnded || res.destroyed)
+                return;
+            const e = describeError(err);
+            json(res, e.status, e.body);
         });
     });
 }
@@ -260,19 +294,27 @@ export class HttpError extends Error {
         this.status = status;
     }
 }
-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 };
+/**
+ * The HTTP status and JSON body for an error: `{ error, code?, attempts? }`. RouterErrors carry a code
+ * (see RouterErrorCode) that maps to one status; a ProviderError with an HTTP status passes it on.
+ */
+function describeError(err) {
+    const status = err instanceof HttpError ? err.status
+        : err instanceof RouterError ? ERROR_STATUS[err.code]
+            : err instanceof ProviderError && err.status ? err.status
+                : 500;
+    const code = err instanceof RouterError ? err.code : undefined;
+    return { status, body: { error: err?.message ?? String(err), ...(code ? { code } : {}), ...(err?.attempts?.length ? { attempts: err.attempts } : {}) } };
 }
+/** The HTTP status for each RouterError code (see RouterErrorCode). */
+export const ERROR_STATUS = {
+    bad_request: 400,
+    unsupported: 400,
+    no_provider: 422,
+    setup: 502,
+    all_failed: 503,
+    timeout: 504,
+};
 const MAX_BODY = 100 * 1024 * 1024;
 async function readRaw(req) {
     const chunks = [];

package/dist/types.d.ts

@@ -3,9 +3,14 @@ export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "
 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). */
+    /**
+     * vCPUs. Leave vcpu and memoryGb out to take any provider at the size it starts by default: most give
+     * 2 vCPU / 4 GB, but some only run a fixed, smaller image (E2B 2 vCPU / 0.5 GB, Daytona 1 / 1). Set
+     * either one and only providers that can give that size are tried. `Candidate.size` and
+     * `RoutedSandbox.size` say what you get.
+     */
     vcpu?: number;
-    /** Memory in GB (default 4). */
+    /** Memory in GB. See `vcpu`. */
     memoryGb?: number;
     /** GPU type, e.g. "T4", "A100". Only providers with the "gpu" capability accept it. */
     gpu?: string;
@@ -37,6 +42,12 @@ export interface RouteOptions {
     provider?: ProviderId | ProviderId[];
     /** How to order candidates when no explicit list is given. Default: "balanced" (cheapest real cost, speed breaks near-ties). */
     strategy?: Strategy;
+    /**
+     * Seconds the whole create may take, over every provider it tries (default 240, under the 300 s an
+     * HTTP client usually waits). When it runs out, create stops trying and throws a RouterError with
+     * code "timeout"; a provider still starting is killed when it answers.
+     */
+    deadlineSeconds?: number;
     /**
      * 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) or can't bill
@@ -92,9 +103,21 @@ export interface Attempt {
     /** HTTP status of the failure, when the provider gave one (402: the account can't pay). */
     status?: number;
 }
+/**
+ * Why the router couldn't do what was asked. Each maps to one HTTP status in the server.
+ * - bad_request (400): an invalid spec, route option or sandbox id
+ * - unsupported (400): the sandbox's provider can't do this (e.g. pause)
+ * - no_provider (422): no provider you have keys for can take this sandbox (`plan()` says why for each)
+ * - setup (502): a provider refused the request or the key (400/401/403/404/422 from it); fix the key,
+ *   image or request rather than retrying
+ * - all_failed (503): every provider tried was down, busy or out of credit; retrying later can work
+ * - timeout (504): the create ran out of `deadlineSeconds`
+ */
+export type RouterErrorCode = "bad_request" | "unsupported" | "no_provider" | "setup" | "all_failed" | "timeout";
 export declare class RouterError extends Error {
     readonly attempts: Attempt[];
-    constructor(message: string, attempts?: Attempt[]);
+    readonly code: RouterErrorCode;
+    constructor(message: string, attempts?: Attempt[], code?: RouterErrorCode);
 }
 /** Thrown by adapters for HTTP failures so the router can report status codes. */
 export declare class ProviderError extends Error {

package/dist/types.js

@@ -1,8 +1,10 @@
 export class RouterError extends Error {
     attempts;
-    constructor(message, attempts = []) {
+    code;
+    constructor(message, attempts = [], code = "all_failed") {
         super(message);
         this.attempts = attempts;
+        this.code = code;
         this.name = "RouterError";
     }
 }

package/dist/util.js

@@ -28,7 +28,8 @@ export function wrapCommand(cmd, opts = {}) {
 }
 /** 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`);
+    // 504 for the HTTP API: the command ran out of time, not the server.
+    return new ProviderError(provider, `command timed out after ${seconds}s`, 504);
 }
 /**
  * True when an exit code is the one left behind by a timeout kill and the command really ran

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import { type RouteOptions, type SandboxSpec, type Strategy } from "./types.js";
+/** Every key a SandboxSpec can have. Anything else in a request is a mistake (e.g. "memory" for "memoryGb"). */
+export declare const SPEC_KEYS: readonly ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "image", "metadata"];
+/** Every key RouteOptions can have. */
+export declare const ROUTE_KEYS: readonly ["provider", "strategy", "fallback", "require", "createTimeoutSeconds", "deadlineSeconds"];
+export declare const STRATEGIES: readonly Strategy[];
+/**
+ * Throws RouterError("bad_request") for a spec or route a provider couldn't make sense of: sizes and
+ * times that aren't positive numbers, an unknown strategy or fallback, maps that aren't string maps.
+ * Called by `plan()`, so every create, route and CLI command goes through it.
+ */
+export declare function validate(spec?: SandboxSpec, route?: RouteOptions): void;
+/** Split a flat request body into spec and route options, refusing keys that are neither. */
+export declare function splitRequest(body: Record<string, unknown>): {
+    spec: SandboxSpec;
+    route: RouteOptions;
+};

package/dist/validate.js

@@ -0,0 +1,66 @@
+import { CATALOG } from "./catalog.js";
+import { RouterError } from "./types.js";
+/** Every key a SandboxSpec can have. Anything else in a request is a mistake (e.g. "memory" for "memoryGb"). */
+export const SPEC_KEYS = ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "image", "metadata"];
+/** Every key RouteOptions can have. */
+export const ROUTE_KEYS = ["provider", "strategy", "fallback", "require", "createTimeoutSeconds", "deadlineSeconds"];
+export const STRATEGIES = ["default", "balanced", "verified", "cheapest", "fastest"];
+const bad = (msg) => new RouterError(msg, [], "bad_request");
+const positive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+/** How a bad value is shown: numbers as-is (NaN, Infinity), anything else as JSON. */
+const show = (v) => (typeof v === "number" ? String(v) : JSON.stringify(v));
+const stringMap = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+/**
+ * Throws RouterError("bad_request") for a spec or route a provider couldn't make sense of: sizes and
+ * times that aren't positive numbers, an unknown strategy or fallback, maps that aren't string maps.
+ * Called by `plan()`, so every create, route and CLI command goes through it.
+ */
+export function validate(spec = {}, route = {}) {
+    for (const k of ["vcpu", "memoryGb", "timeoutMinutes"]) {
+        if (spec[k] !== undefined && !positive(spec[k]))
+            throw bad(`${k} must be a positive number, got ${show(spec[k])}`);
+    }
+    if (spec.gpu !== undefined && (typeof spec.gpu !== "string" || !spec.gpu))
+        throw bad(`gpu must be a GPU type such as "T4", got ${JSON.stringify(spec.gpu)}`);
+    for (const k of ["env", "image", "metadata"]) {
+        if (spec[k] !== undefined && !stringMap(spec[k]))
+            throw bad(`${k} must be an object of strings`);
+    }
+    if (route.strategy !== undefined && !STRATEGIES.includes(route.strategy)) {
+        throw bad(`unknown strategy ${JSON.stringify(route.strategy)}: use one of ${STRATEGIES.filter((s) => s !== "default").join(", ")}`);
+    }
+    if (route.fallback !== undefined && route.fallback !== true && route.fallback !== false && route.fallback !== "any") {
+        throw bad(`fallback must be true, false or "any", got ${JSON.stringify(route.fallback)}`);
+    }
+    for (const k of ["createTimeoutSeconds", "deadlineSeconds"]) {
+        if (route[k] !== undefined && !positive(route[k]))
+            throw bad(`${k} must be a positive number, got ${show(route[k])}`);
+    }
+    if (route.require !== undefined && (!Array.isArray(route.require) || !route.require.every((r) => typeof r === "string"))) {
+        throw bad("require must be a list of capabilities, e.g. [\"pause\"]");
+    }
+    if (route.provider !== undefined) {
+        const ids = [].concat(route.provider);
+        const unknown = ids.filter((id) => typeof id !== "string" || !CATALOG.some((c) => c.id === id));
+        if (unknown.length || ids.length === 0)
+            throw bad(`unknown provider: ${unknown.map((u) => JSON.stringify(u)).join(", ") || "(empty list)"}`);
+    }
+}
+/** Split a flat request body into spec and route options, refusing keys that are neither. */
+export function splitRequest(body) {
+    const spec = {};
+    const route = {};
+    const unknown = [];
+    for (const [k, v] of Object.entries(body ?? {})) {
+        if (ROUTE_KEYS.includes(k))
+            route[k] = v;
+        else if (SPEC_KEYS.includes(k))
+            spec[k] = v;
+        else
+            unknown.push(k);
+    }
+    if (unknown.length)
+        throw bad(`unknown field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: a sandbox takes ${SPEC_KEYS.join(", ")}; routing takes ${ROUTE_KEYS.join(", ")}`);
+    validate(spec, route);
+    return { spec: spec, route: route };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One API for every sandbox provider: route AI agents' code by price, speed or capability, with automatic fallback. Free and open source.",
   "type": "module",
   "main": "dist/index.js",