@sandboxrouter/sdk 0.3.5 → 0.5.0

package/dist/router.js

@@ -1,9 +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 { VERIFIED } from "./verified.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";
@@ -43,6 +45,12 @@ import { MobilerunProvider } from "./providers/mobilerun.js";
 import { LimrunProvider } from "./providers/limrun.js";
 import { WorkspacesAgentProvider } from "./providers/workspaces.js";
 import { ProviderError, SetupError, RouterError, } from "./types.js";
+/** Providers within this share of the cheapest remaining price count as a tie, broken by speed. */
+export const PRICE_TIE = 0.1;
+/** Creates this router must have seen for a provider before its own timings replace the bench file's. */
+const LIVE_MIN_SAMPLES = 3;
+/** Recent creates kept per provider for the live median. */
+const LIVE_SAMPLES = 20;
 /** Desktop-only providers. Filled in as adapters are added. */
 export function defaultComputerProviders() {
     return [new OrgoProvider(), new MobilerunProvider(), new LimrunProvider(), new WorkspacesAgentProvider()];
@@ -89,6 +97,11 @@ export class Router {
     providers;
     benchFile;
     verified;
+    failing;
+    requireVerified;
+    billed;
+    /** Create times this router measured, most recent last. */
+    live = new Map();
     computerOnly;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     ledger;
@@ -99,6 +112,10 @@ export class Router {
         this.providers = new Map((opts.providers ?? defaultProviders()).map((p) => [p.id, p]));
         this.benchFile = opts.benchFile;
         this.verified = new Set(opts.verified ?? Object.keys(VERIFIED));
+        this.failing = new Set(opts.failing ?? Object.keys(FAILING));
+        this.requireVerified = opts.requireVerified ?? false;
+        this.billed =
+            opts.billedVsList ?? Object.fromEntries(Object.entries(BILLED_VS_LIST).map(([id, b]) => [id, b.ratio]));
         this.computerOnly = opts.computers ?? (opts.providers ? [] : defaultComputerProviders());
     }
     /** Registered and has credentials. False for providers this router doesn't know. */
@@ -112,48 +129,66 @@ 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.
         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 strategy = route.strategy ?? "default";
+        const speed = strategy === "default" || strategy === "balanced" || strategy === "fastest";
+        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, verified: 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: round(hourlyCost(id, spec)),
-                medianCreateMs: median(bench[id]?.createMs),
+                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),
             };
             if (!p)
                 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");
+                c.skip =
+                    unfit(id, spec, route.require) ??
+                        (p.configured() ? undefined : gated ? `not configured; ${gated}` : "not configured") ??
+                        (this.requireVerified && !c.verified ? "not tested (this router only uses providers that passed the real-account check)" : undefined);
             }
             return c;
         });
-        // Neutral by construction: the same rule for every provider, ties alphabetical by id. The default
-        // puts providers that passed the real-account check first; any provider gets there by passing it.
-        // An explicit provider list keeps the caller's order.
+        // Neutral by construction: the same rule for every provider, ties alphabetical by id. Nothing here
+        // 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);
-            if (route.strategy === "fastest") {
-                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
+            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) || byCost(a, b));
+            }
+            else if (strategy === "cheapest") {
+                list.sort(byList);
             }
-            else if (route.strategy === "cheapest") {
-                list.sort(byPrice);
+            else if (strategy === "verified") {
+                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byCost(a, b));
             }
             else {
-                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byPrice(a, b));
+                return balanced(list);
             }
         }
         return list;
@@ -191,54 +226,76 @@ 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 });
-                const sbx = new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd, this.ledger);
-                this.record(sbx, c.estimatedHourlyUsd, spec.timeoutMinutes);
+                this.observe(c.provider, Date.now() - t0);
+                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), () => { });
-                attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
+                    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) {
+        const xs = this.live.get(id) ?? [];
+        xs.push(ms);
+        if (xs.length > LIVE_SAMPLES)
+            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. */
@@ -270,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;
@@ -320,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() {
@@ -333,17 +401,42 @@ 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) {
     return Math.round(n * 10000) / 10000;
 }
+/**
+ * The default order. Providers whose last real-account check failed go last. The rest go cheapest
+ * first by effective price (list price x what the provider really billed, where measured), except that
+ * providers within PRICE_TIE of the cheapest remaining one count as a tie and go fastest first (by
+ * median create time; unknown speed after known), then cheapest, then alphabetical.
+ */
+export function balanced(list) {
+    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].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);
+        }
+        return out;
+    };
+    return [...order(list.filter((c) => !c.failing)), ...order(list.filter((c) => c.failing))];
+}
 /** 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
@@ -367,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;
@@ -22,18 +27,27 @@ export interface SandboxSpec {
     metadata?: Record<string, string>;
 }
 /**
- * "verified" (and "default", the same thing): providers that passed the real-account check first
- * (as of this release; `VERIFIED` in src/verified.ts), then the rest; cheapest first within each,
- * ties alphabetical.
+ * "balanced" (and "default", the same thing): cheapest first by effective price (list price x what the
+ * provider really billed, where measured; `BILLED_VS_LIST`), with providers within 10% of each other on
+ * price ordered by speed (this router's own recent create times, else your `bench` file). Providers
+ * whose last real-account check failed (`FAILING`) go last.
+ * "verified": providers that passed the real-account check first (`VERIFIED`), then the rest; cheapest
+ * list price first within each.
  * "cheapest": lowest list price for the spec, tested or not, ties alphabetical.
- * "fastest": lowest median cold start you measured with `bench`, then cheapest.
+ * "fastest": lowest median create time (this router's own, else your `bench` file), then cheapest.
  */
-export type Strategy = "default" | "verified" | "cheapest" | "fastest";
+export type Strategy = "default" | "balanced" | "verified" | "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: "verified" (tested providers first, then cheapest). */
+    /** 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
@@ -86,10 +100,24 @@ export interface Attempt {
     ok: boolean;
     ms: number;
     error?: string;
+    /** 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";
     }
 }