@sandboxrouter/sdk 0.3.5 → 0.5.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,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.
-- **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. `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/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,13 @@ 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 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;
     }
@@ -214,6 +219,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 +232,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/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/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/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,19 +1,43 @@
 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    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`). */
     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 +48,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, 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. */
 export declare function defaultComputerProviders(): ComputerProvider[];
@@ -36,6 +71,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 +94,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. */
@@ -70,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
@@ -103,7 +158,18 @@ 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 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;