@sandboxrouter/sdk 0.3.5 → 0.4.0

package/README.md

@@ -21,7 +21,7 @@ try {
 
 Runs as plain JavaScript on Node 20+. (In TypeScript 5.2+, or Node 24+, `await using sbx = ...` kills the sandbox for you.)
 
-Set the keys of the providers you use. `create()` starts the sandbox on the cheapest one that fits among those that passed the real-account check, then the untested ones, by public list price (ties alphabetical, and no provider pays for placement). If that provider is down, busy or out of credit, the next one takes it, and every attempt is on `sbx.attempts`. The sandbox stays on that provider until you `kill()` it.
+Set the keys of the providers you use. `create()` starts the sandbox on the cheapest one that fits: list price for the size you asked for, corrected where we measured what a provider really bills. Providers within 10% of each other on price go fastest first, by start times measured where you run the router. Providers that failed their last real-account check go last. Ties are alphabetical, and no provider pays for placement. If that provider is down, busy or out of credit, the next one takes it, and every attempt is on `sbx.attempts`. The sandbox stays on that provider until you `kill()` it.
 
 Site and docs: [sandboxrouter.vercel.app](https://sandboxrouter.vercel.app) · npm: [`@sandboxrouter/sdk`](https://www.npmjs.com/package/@sandboxrouter/sdk)
 
@@ -30,7 +30,7 @@ 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.
-- **Tested first, then cheapest, with fallback.** Or `cheapest` for price alone, `fastest` by cold starts you measured, 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.
 - **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.

package/dist/bench-store.d.ts

@@ -6,7 +6,8 @@ export interface BenchSample {
     at: string;
 }
 export type BenchData = Partial<Record<ProviderId, BenchSample>>;
-export declare const DEFAULT_BENCH_FILE: string;
+/** $SANDBOXROUTER_BENCH_FILE, else bench.json next to the ledger: $SANDBOXROUTER_HOME, else ~/.sandboxrouter/. */
+export declare function defaultBenchFile(): string;
 export declare function loadBench(file?: string): BenchData;
 export declare function saveBench(data: BenchData, file?: string): void;
 export declare function median(xs?: number[]): number | undefined;

package/dist/bench-store.js

@@ -1,8 +1,11 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-export const DEFAULT_BENCH_FILE = process.env.SANDBOXROUTER_BENCH_FILE ?? join(homedir(), ".sandboxrouter", "bench.json");
-export function loadBench(file = DEFAULT_BENCH_FILE) {
+/** $SANDBOXROUTER_BENCH_FILE, else bench.json next to the ledger: $SANDBOXROUTER_HOME, else ~/.sandboxrouter/. */
+export function defaultBenchFile() {
+    return process.env.SANDBOXROUTER_BENCH_FILE || join(process.env.SANDBOXROUTER_HOME || join(homedir(), ".sandboxrouter"), "bench.json");
+}
+export function loadBench(file = defaultBenchFile()) {
     try {
         return JSON.parse(readFileSync(file, "utf8"));
     }
@@ -10,7 +13,7 @@ export function loadBench(file = DEFAULT_BENCH_FILE) {
         return {};
     }
 }
-export function saveBench(data, file = DEFAULT_BENCH_FILE) {
+export function saveBench(data, file = defaultBenchFile()) {
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(data, null, 2));
 }

package/dist/billing.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderId } from "./types.js";
+export declare const BILLED_VS_LIST: Partial<Record<ProviderId, {
+    ratio: number;
+    date: string;
+}>>;

package/dist/billing.js

@@ -0,0 +1,3 @@
+export const BILLED_VS_LIST = {
+    sail: { ratio: 1.458, date: "2026-11-06" },
+};

package/dist/check.d.ts

@@ -15,6 +15,11 @@ export interface CheckReport {
     results: CheckResult[];
     /** True when no step failed. */
     ok: boolean;
+    /**
+     * Set when the run says nothing about the provider: the account running it couldn't pay (402: no
+     * balance, plan not started). Such a run isn't saved, so the provider keeps its last real result.
+     */
+    inconclusive?: string;
 }
 /**
  * One real pass over a provider: create, exec (stdout, stderr, exit code, env, cwd), streaming,

package/dist/check.js

@@ -42,10 +42,21 @@ export async function checkProvider(router, provider, opts = {}) {
         }
     };
     let sbx;
+    let unpaid;
     await step("create", async () => {
-        sbx = await router.create({ timeoutMinutes: 10, ...fixedSize(provider), ...opts.spec }, { provider, fallback: false });
+        try {
+            sbx = await router.create({ timeoutMinutes: 10, ...fixedSize(provider), ...opts.spec }, { provider, fallback: false });
+        }
+        catch (err) {
+            if (err.attempts?.at(-1)?.status !== 402)
+                throw err;
+            unpaid = err.message;
+            return { status: "skip", detail: `the account can't pay (402), so this run says nothing about ${provider}: ${unpaid}` };
+        }
         return `${sbx.id}, ~$${sbx.estimatedHourlyUsd}/hr`;
     });
+    if (unpaid)
+        return { provider, results, ok: false, inconclusive: "the account running the check can't pay (402)" };
     if (!sbx)
         return { provider, results, ok: false };
     const box = sbx;

package/dist/cli.js

@@ -39,7 +39,7 @@ Usage:
   sandboxrouter serve     [--port 8787] [--host 127.0.0.1] [--cors https://site.example,http://localhost:3000]
 
 Spec flags:   --vcpu N  --memory GB  --gpu T4  --timeout MIN
-Route flags:  --provider e2b[,modal,...]  --strategy verified|cheapest|fastest (default verified: tested providers first)
+Route flags:  --provider e2b[,modal,...]  --strategy balanced|verified|cheapest|fastest (default balanced: cheapest real cost, speed breaks near-ties)
               --no-fallback  --fallback-any (also on setup errors like a bad key)
               --create-timeout SEC (per provider, default 120)  --require gpu,custom-image
 
@@ -156,8 +156,11 @@ async function main() {
         let n = 0;
         for (const c of plan) {
             const mark = c.skip ? "  -" : `${++n}.`.padStart(3);
-            const tested = c.verified ? "tested  " : "        ";
-            console.log(`${mark} ${c.provider.padEnd(11)} $${c.estimatedHourlyUsd.toFixed(4)}/hr  ${tested}${c.skip ? `(skipped: ${c.skip})` : ""}`.trimEnd());
+            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());
         }
         return;
     }
@@ -214,6 +217,11 @@ async function main() {
                 },
             });
             reports.push(report);
+            if (report.inconclusive) {
+                if (!values.json)
+                    console.log(`  not saved: ${report.inconclusive}; ${p} keeps its last saved result`);
+                continue;
+            }
             if (saveDir) {
                 mkdirSync(saveDir, { recursive: true });
                 const saved = publishableCheck({ tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report });
@@ -222,9 +230,12 @@ async function main() {
         }
         if (values.json)
             console.log(JSON.stringify(reports, null, 2));
-        else
-            console.log(`\n${reports.filter((r) => r.ok).length}/${reports.length} passed`);
-        if (reports.some((r) => !r.ok))
+        else {
+            const unpaid = reports.filter((r) => r.inconclusive).length;
+            const ran = reports.length - unpaid;
+            console.log(`\n${reports.filter((r) => r.ok).length}/${ran} passed${unpaid ? `; ${unpaid} not run (the account can't pay)` : ""}`);
+        }
+        if (reports.some((r) => !r.ok && !r.inconclusive))
             process.exitCode = 1;
         return;
     }

package/dist/cost.d.ts

@@ -74,4 +74,15 @@ type Reader = (e: CostEntry) => Promise<Omit<Bill, "at">>;
 export declare const BILL_READERS: Partial<Record<ProviderId, Reader>>;
 export declare function settle(run: CostRun): Promise<CostRun>;
 export declare function costMarkdown(run: CostRun): string;
+/**
+ * Billed / predicted per provider, from the saved cost runs in `dir` (default results/cost): the latest
+ * entry whose bill is precise enough to compare. A bill rounded to whole cents only counts when the
+ * prediction is at least $1, so rounding can't move the ratio by more than 1%. Providers whose terms
+ * forbid publishing benchmarks are left out, like everywhere else results are published.
+ */
+export declare function billedVsList(dir?: string): {
+    provider: ProviderId;
+    ratio: number;
+    date: string;
+}[];
 export {};

package/dist/cost.js

@@ -1,4 +1,6 @@
-import { fittingSpec, hourlyCost } from "./catalog.js";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { benchmarksPublishable, fittingSpec, hourlyCost } from "./catalog.js";
 import { Router } from "./router.js";
 /**
  * The size the sandbox really has, as "<vcpus> <memoryMb>". nproc and MemTotal can show the whole host
@@ -163,3 +165,43 @@ export function costMarkdown(run) {
     }
     return lines.join("\n");
 }
+/**
+ * Billed / predicted per provider, from the saved cost runs in `dir` (default results/cost): the latest
+ * entry whose bill is precise enough to compare. A bill rounded to whole cents only counts when the
+ * prediction is at least $1, so rounding can't move the ratio by more than 1%. Providers whose terms
+ * forbid publishing benchmarks are left out, like everywhere else results are published.
+ */
+export function billedVsList(dir = "results/cost") {
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const latest = new Map();
+    for (const f of files) {
+        let run;
+        try {
+            run = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (run?.tool !== "sandboxrouter-cost" || !Array.isArray(run.entries))
+            continue;
+        for (const e of run.entries) {
+            const usd = e.bill?.usd;
+            const predicted = e.predictedUsd;
+            if (!usd || !predicted || usd <= 0 || predicted <= 0 || !benchmarksPublishable(e.provider))
+                continue;
+            if (/integer cents/i.test(e.bill.source) && predicted < 1)
+                continue;
+            const date = run.date.slice(0, 10);
+            const prev = latest.get(e.provider);
+            if (!prev || date >= prev.date)
+                latest.set(e.provider, { ratio: Math.round((usd / predicted) * 1000) / 1000, date });
+        }
+    }
+    return [...latest].map(([provider, v]) => ({ provider, ...v })).sort((a, b) => a.provider.localeCompare(b.provider));
+}

package/dist/router.d.ts

@@ -3,17 +3,28 @@ import { Ledger } from "./ledger.js";
 import { type Attempt, type ExecOptions, type ExecResult, type Provider, type ProviderId, type ProviderSandbox, type RouteOptions, type SandboxSpec } from "./types.js";
 export interface Candidate {
     provider: ProviderId;
+    /** List price for the spec, USD/hour. What the sandbox is expected to cost at the provider's published rates. */
     estimatedHourlyUsd: 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.
+     */
+    effectiveHourlyUsd: number;
+    /** 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`). */
     verified: boolean;
+    /** Failed a step of its last real-account check (as of this release, or `RouterOptions.failing`). */
+    failing: boolean;
     /** Why this provider won't be tried, if it won't. */
     skip?: string;
 }
+/** Providers within this share of the cheapest remaining price count as a tie, broken by speed. */
+export declare const PRICE_TIE = 0.1;
 export interface RouterOptions {
     /** Replace the built-in adapters (tests, custom providers). */
     providers?: Provider[];
-    /** Path of the bench results file used by strategy "fastest". */
+    /** Path of the bench results file: start times for the speed tie-break and strategy "fastest". */
     benchFile?: string;
     /** Desktop-only computer providers (sandbox providers that also sell computers are found automatically). */
     computers?: ComputerProvider[];
@@ -24,10 +35,21 @@ export interface RouterOptions {
      */
     ledger?: string | false;
     /**
-     * Providers the default "verified" strategy tries first. Default: those whose last real-account check
-     * passed as of this release (`VERIFIED`). Pass your own list, e.g. after running `check` yourself.
+     * Providers that passed the real-account check: tried first by strategy "verified", and the only ones
+     * used with `requireVerified`. Default: those that passed as of this release (`VERIFIED`). Pass your own
+     * list, e.g. after running `check` yourself.
      */
     verified?: ProviderId[];
+    /** Providers whose last real-account check failed. The default strategy tries them last. Default: `FAILING`. */
+    failing?: ProviderId[];
+    /**
+     * Only route to providers in `verified`; the rest are skipped. For services that run sandboxes on their own
+     * accounts, where a provider that misbehaves without failing (keeps billing after kill, garbles output)
+     * costs money. Default false.
+     */
+    requireVerified?: boolean;
+    /** Billed / list-price ratio per provider, for the default ranking. Default: `BILLED_VS_LIST` from saved cost runs. */
+    billedVsList?: Partial<Record<ProviderId, number>>;
 }
 /** Desktop-only providers. Filled in as adapters are added. */
 export declare function defaultComputerProviders(): ComputerProvider[];
@@ -36,6 +58,11 @@ export declare class Router {
     private providers;
     private benchFile?;
     private readonly verified;
+    private readonly failing;
+    private readonly requireVerified;
+    private readonly billed;
+    /** Create times this router measured, most recent last. */
+    private readonly live;
     private computerOnly;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     readonly ledger?: Ledger;
@@ -54,6 +81,8 @@ export declare class Router {
     private whyNone;
     /** Start a sandbox on the best available provider, falling back down the list on failure. */
     create(spec?: SandboxSpec, route?: RouteOptions): Promise<RoutedSandbox>;
+    /** Remember a successful create's time, for the speed tie-break and strategy "fastest". */
+    private observe;
     private record;
     private discard;
     /** Every provider that sells computers (desktops/phones): sandbox providers that do, plus desktop-only ones. */
@@ -103,6 +132,13 @@ export declare function parseId(id: string): {
     provider: ProviderId;
     nativeId: string;
 };
+/**
+ * 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 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 past a command's timeout before the router stops waiting for the adapter. */

package/dist/router.js

@@ -3,7 +3,8 @@ 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 { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -43,6 +44,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 +96,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 +111,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. */
@@ -121,40 +137,52 @@ export class Router {
         // 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" };
+                return { provider: id, estimatedHourlyUsd: 0, effectiveHourlyUsd: 0, verified: false, failing: false, skip: "unknown provider" };
             const p = this.providers.get(id);
+            const list = round(hourlyCost(id, spec));
+            const live = this.live.get(id);
             const c = {
                 provider: id,
-                estimatedHourlyUsd: round(hourlyCost(id, spec)),
-                medianCreateMs: median(bench[id]?.createMs),
+                estimatedHourlyUsd: list,
+                effectiveHourlyUsd: round(list * (this.billed[id] ?? 1)),
+                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") {
+            if (strategy === "fastest") {
                 list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
             }
-            else if (route.strategy === "cheapest") {
+            else if (strategy === "cheapest") {
                 list.sort(byPrice);
             }
-            else {
+            else if (strategy === "verified") {
                 list.sort((a, b) => Number(b.verified) - Number(a.verified) || byPrice(a, b));
             }
+            else {
+                return balanced(list);
+            }
         }
         return list;
     }
@@ -205,6 +233,7 @@ export class Router {
                     return new ProviderError(c.provider, `create timed out after ${limitS}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);
                 return sbx;
@@ -214,8 +243,8 @@ export class Router {
                 // so it can't bill unseen. If the kill fails, the ledger entry is left for `gc`.
                 if (timedOut)
                     pending.then((late) => this.discard(c.provider, late, c.estimatedHourlyUsd, spec.timeoutMinutes), () => { });
-                attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
                 const status = 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]+$/, "");
@@ -226,6 +255,14 @@ export class Router {
         }
         throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts);
     }
+    /** 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) {
         const now = Date.now();
         this.ledger?.open({
@@ -342,6 +379,28 @@ export function parseId(id) {
 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.effectiveHourlyUsd - b.effectiveHourlyUsd || 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);
+            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;
 /**

package/dist/types.d.ts

@@ -22,17 +22,20 @@ 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;
     /**
      * What to do when a create fails. `true` (default): try the next candidate when the provider
@@ -86,6 +89,8 @@ 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;
 }
 export declare class RouterError extends Error {
     readonly attempts: Attempt[];

package/dist/verified.d.ts

@@ -1,2 +1,4 @@
 import type { ProviderId } from "./types.js";
 export declare const VERIFIED: Partial<Record<ProviderId, string>>;
+/** Providers whose last saved real-account check failed a step. The default strategy tries them last. */
+export declare const FAILING: Partial<Record<ProviderId, string>>;

package/dist/verified.js

@@ -16,3 +16,5 @@ export const VERIFIED = {
     superserve: "2026-11-11",
     vercel: "2026-11-11",
 };
+/** Providers whose last saved real-account check failed a step. The default strategy tries them last. */
+export const FAILING = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.3.5",
+  "version": "0.4.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",