@sandboxrouter/sdk 0.4.0 → 0.6.0

package/README.md

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

package/dist/cli.js

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

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import type { Attempt, ExecOptions, ExecResult, RouteOptions, SandboxSpec } from "./types.js";
+import type { Candidate, Size } from "./router.js";
+import type { Attempt, ExecOptions, ExecResult, RouteOptions, RouterErrorCode, SandboxSpec } from "./types.js";
 /**
  * Client for the sandboxrouter HTTP API: the hosted service (one key, prepaid credits) or your own
  * `sandboxrouter serve`. Provider keys live on the server; this side only needs the one key.
@@ -18,41 +19,68 @@ export declare class Client {
         fetch?: typeof fetch;
     });
     /** @internal */
-    request(method: string, path: string, body?: unknown, accept?: string): Promise<Response>;
+    request(method: string, path: string, body?: unknown, accept?: string, headers?: Record<string, 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;
-    }[]>;
-    /** Start a sandbox on the first provider that works, as the server routes it. */
-    create(spec?: SandboxSpec, route?: RouteOptions): Promise<RemoteSandbox>;
+    /** 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. With `idempotencyKey`,
+     * sending the same create again (say, after a timeout) returns the same sandbox instead of starting
+     * a second one; use a new key for each sandbox you mean to start.
+     */
+    create(spec?: SandboxSpec, route?: RouteOptions, opts?: {
+        idempotencyKey?: string;
+    }): Promise<RemoteSandbox>;
     /** A handle on a sandbox you created earlier. */
     sandbox(id: string): RemoteSandbox;
 }
 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

@@ -17,7 +17,7 @@ export class Client {
         this.fetch = opts.fetch ?? globalThis.fetch;
     }
     /** @internal */
-    async request(method, path, body, accept = "application/json") {
+    async request(method, path, body, accept = "application/json", headers = {}) {
         const raw = body instanceof Uint8Array;
         const res = await this.fetch(this.baseUrl + path, {
             method,
@@ -25,6 +25,7 @@ export class Client {
                 Accept: accept,
                 ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
                 ...(body === undefined ? {} : { "Content-Type": raw ? "application/octet-stream" : "application/json" }),
+                ...headers,
             },
             body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
         });
@@ -35,28 +36,31 @@ 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);
+    /**
+     * Start a sandbox on the first provider that works, as the server routes it. With `idempotencyKey`,
+     * sending the same create again (say, after a timeout) returns the same sandbox instead of starting
+     * a second one; use a new key for each sandbox you mean to start.
+     */
+    async create(spec = {}, route = {}, opts = {}) {
+        const headers = opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {};
+        const res = await this.request("POST", "/v1/sandboxes", { ...spec, ...route }, "application/json", headers);
+        const r = (await res.json());
+        return new RemoteSandbox(this, r.id, r.provider, { ...r, replayed: res.headers.get("idempotent-replayed") === "true" });
     }
     /** A handle on a sandbox you created earlier. */
     sandbox(id) {
@@ -67,10 +71,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 +86,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 +134,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 +147,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/computers.d.ts

@@ -1,3 +1,5 @@
+import type { Ledger } from "./ledger.js";
+import { type Attempt } from "./types.js";
 /**
  * Computers: machines with a screen that a model drives with clicks and keys (computer use).
  * Linux and Windows desktops, Android phones. Routed like sandboxes: cheapest published price for
@@ -99,8 +101,17 @@ export interface ComputerProvider {
 export declare class RoutedComputer {
     readonly provider: ComputerProviderId;
     private c;
+    /** Every create attempt, including failed fallbacks (empty for a handle from getComputer). */
+    readonly attempts: Attempt[];
+    /** List price per hour for this OS, where the provider publishes one. */
+    readonly estimatedHourlyUsd?: number | undefined;
+    private ledger?;
     readonly id: string;
-    constructor(provider: ComputerProviderId, c: ProviderComputer);
+    constructor(provider: ComputerProviderId, c: ProviderComputer, 
+    /** Every create attempt, including failed fallbacks (empty for a handle from getComputer). */
+    attempts?: Attempt[], 
+    /** List price per hour for this OS, where the provider publishes one. */
+    estimatedHourlyUsd?: number | undefined, ledger?: Ledger | undefined);
     get nativeId(): string;
     info(): Promise<ComputerInfo>;
     act(action: ComputerAction): Promise<ActionResult>;
@@ -109,7 +120,10 @@ export declare class RoutedComputer {
         format?: "png" | "jpeg";
         quality?: number;
     }): Promise<Uint8Array<ArrayBufferLike>>;
-    exec(command: string, timeoutSeconds?: number): Promise<{
+    /** Run a shell command (max 30 s). The second argument is `{ timeoutSeconds }`, or the number alone. */
+    exec(command: string, opts?: number | {
+        timeoutSeconds?: number;
+    }): Promise<{
         exitCode: number;
         stdout: string;
         stderr: string;
@@ -129,7 +143,12 @@ export declare class RoutedComputer {
         expiresAt: string | null;
     }>;
     sleep(): Promise<void>;
+    /** Delete the computer and everything on it (its files and logins). */
     delete(): Promise<void>;
+    /** Same as delete(), named like a sandbox's. */
+    kill(): Promise<void>;
+    /** `await using pc = await router.computer(...)` deletes it when the block ends. */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /** Published prices per OS for every computer provider. Same rules as the sandbox catalog. */
 export interface ComputerCatalogEntry {
@@ -159,8 +178,32 @@ export interface ComputerCandidate {
 }
 /** The order a computer create would try, with the reason any provider is skipped. */
 export declare function planComputer(providers: ComputerProvider[], os?: ComputerOs, prefer?: ComputerProviderId[]): ComputerCandidate[];
+/** How a computer create is routed: the same knobs and rules as a sandbox's (see RouteOptions). */
+export interface ComputerRoute {
+    provider?: ComputerProviderId | ComputerProviderId[];
+    /** true (default): move on when a provider is down or can't bill, stop on a setup error. "any": move on always. false: first only. */
+    fallback?: boolean | "any";
+    /** Seconds to wait for one provider before trying the next (default 120). */
+    createTimeoutSeconds?: number;
+    /** Seconds the whole create may take (default 240). */
+    deadlineSeconds?: number;
+}
+/** Split and check a POST /v1/computers body, like splitRequest does for sandboxes. */
+export declare function splitComputerRequest(body: Record<string, unknown>): {
+    spec: ComputerSpec;
+    route: ComputerRoute;
+};
 /**
  * Start a computer on the cheapest provider that offers this OS and has credentials (ties
- * alphabetical), falling back down the list. An explicit `prefer` list keeps its order.
+ * alphabetical), falling back down the list like a sandbox create: on to the next when a provider is
+ * down, slow or can't bill, but stopping on a setup error (a bad key or request). An explicit
+ * provider list keeps its order. Each computer goes in the ledger, so `ls` and `gc --all` find it;
+ * computers have no lifetime of their own, so plain `gc` leaves them.
  */
-export declare function createComputer(providers: ComputerProvider[], spec?: ComputerSpec, prefer?: ComputerProviderId[]): Promise<RoutedComputer>;
+export declare function createComputer(providers: ComputerProvider[], spec?: ComputerSpec, prefer?: ComputerProviderId[], route?: ComputerRoute & {
+    ledger?: Ledger;
+}): Promise<RoutedComputer>;
+/** Seconds to wait for one provider's computer before trying the next. */
+export declare const DEFAULT_COMPUTER_TIMEOUT_S = 120;
+/** Seconds a whole computer create may take. */
+export declare const DEFAULT_COMPUTER_DEADLINE_S = 240;

package/dist/computers.js

@@ -1,11 +1,22 @@
-import { RouterError } from "./types.js";
+import { ProviderError, RouterError, SetupError } from "./types.js";
+import { SETUP_ERRORS, errorStatus, withDeadline } from "./util.js";
 export class RoutedComputer {
     provider;
     c;
+    attempts;
+    estimatedHourlyUsd;
+    ledger;
     id;
-    constructor(provider, c) {
+    constructor(provider, c, 
+    /** Every create attempt, including failed fallbacks (empty for a handle from getComputer). */
+    attempts = [], 
+    /** List price per hour for this OS, where the provider publishes one. */
+    estimatedHourlyUsd, ledger) {
         this.provider = provider;
         this.c = c;
+        this.attempts = attempts;
+        this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.ledger = ledger;
         this.id = `${provider}:${c.nativeId}`;
     }
     get nativeId() {
@@ -25,8 +36,9 @@ export class RoutedComputer {
     screenshot(opts) {
         return this.c.screenshot(opts);
     }
-    exec(command, timeoutSeconds) {
-        return this.c.exec(command, timeoutSeconds);
+    /** Run a shell command (max 30 s). The second argument is `{ timeoutSeconds }`, or the number alone. */
+    exec(command, opts) {
+        return this.c.exec(command, typeof opts === "number" ? opts : opts?.timeoutSeconds);
     }
     readFile(path) {
         return this.c.readFile(path);
@@ -48,8 +60,18 @@ export class RoutedComputer {
             throw new RouterError(`${this.provider} can't sleep a computer; delete it instead`);
         await this.c.sleep();
     }
-    delete() {
-        return this.c.delete();
+    /** Delete the computer and everything on it (its files and logins). */
+    async delete() {
+        await this.c.delete();
+        this.ledger?.close(this.id, "deleted");
+    }
+    /** Same as delete(), named like a sandbox's. */
+    kill() {
+        return this.delete();
+    }
+    /** `await using pc = await router.computer(...)` deletes it when the block ends. */
+    async [Symbol.asyncDispose]() {
+        await this.delete();
     }
 }
 export const COMPUTER_ENTRIES = [
@@ -166,27 +188,118 @@ export function planComputer(providers, os = "linux", prefer) {
     }
     return list;
 }
+const OS_LIST = ["linux", "windows", "android", "ios"];
+const SPEC_FIELDS = ["os", "externalUserId", "name", "screen", "arch"];
+const ROUTE_FIELDS = ["provider", "fallback", "createTimeoutSeconds", "deadlineSeconds"];
+/** Split and check a POST /v1/computers body, like splitRequest does for sandboxes. */
+export function splitComputerRequest(body) {
+    const bad = (msg) => new RouterError(msg, [], "bad_request");
+    const spec = {};
+    const route = {};
+    const unknown = [];
+    for (const [k, v] of Object.entries(body ?? {})) {
+        if (SPEC_FIELDS.includes(k))
+            spec[k] = v;
+        else if (ROUTE_FIELDS.includes(k))
+            route[k] = v;
+        else
+            unknown.push(k);
+    }
+    if (unknown.length)
+        throw bad(`unknown field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: a computer takes ${[...SPEC_FIELDS, ...ROUTE_FIELDS].join(", ")}`);
+    if (spec.os !== undefined && !OS_LIST.includes(spec.os))
+        throw bad(`os must be one of ${OS_LIST.join(", ")}`);
+    for (const k of ["externalUserId", "name"])
+        if (spec[k] !== undefined && typeof spec[k] !== "string")
+            throw bad(`${k} must be a string`);
+    const screen = spec.screen;
+    if (screen !== undefined && !(typeof screen === "object" && [screen.width, screen.height].every((n) => typeof n === "number" && Number.isFinite(n) && n > 0))) {
+        throw bad("screen must be { width, height } in pixels");
+    }
+    if (spec.arch !== undefined && spec.arch !== "x86_64" && spec.arch !== "arm64")
+        throw bad('arch must be "x86_64" or "arm64"');
+    for (const k of ["createTimeoutSeconds", "deadlineSeconds"]) {
+        const v = route[k];
+        if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0))
+            throw bad(`${k} must be a positive number`);
+    }
+    if (route.fallback !== undefined && route.fallback !== true && route.fallback !== false && route.fallback !== "any")
+        throw bad('fallback must be true, false or "any"');
+    return { spec: spec, route: route };
+}
 /**
  * Start a computer on the cheapest provider that offers this OS and has credentials (ties
- * alphabetical), falling back down the list. An explicit `prefer` list keeps its order.
+ * alphabetical), falling back down the list like a sandbox create: on to the next when a provider is
+ * down, slow or can't bill, but stopping on a setup error (a bad key or request). An explicit
+ * provider list keeps its order. Each computer goes in the ledger, so `ls` and `gc --all` find it;
+ * computers have no lifetime of their own, so plain `gc` leaves them.
  */
-export async function createComputer(providers, spec = {}, prefer) {
+export async function createComputer(providers, spec = {}, prefer, route = {}) {
     const os = spec.os ?? "linux";
-    const usable = planComputer(providers, os, prefer)
-        .filter((c) => !c.skip)
-        .map((c) => providers.find((p) => p.id === c.provider));
+    const plan = planComputer(providers, os, prefer);
+    const usable = plan.filter((c) => !c.skip);
     if (usable.length === 0) {
         const offering = providers.filter((p) => p.computerOs.includes(os)).map((p) => p.id);
-        throw new RouterError(offering.length ? `no configured provider for a ${os} computer (offered by: ${offering.join(", ")})` : `no provider offers a ${os} computer`);
+        throw new RouterError(offering.length ? `no configured provider for a ${os} computer (offered by: ${offering.join(", ")})` : `no provider offers a ${os} computer`, [], "no_provider");
+    }
+    if (prefer && route.fallback === false && plan[0].skip) {
+        throw new RouterError(`${plan[0].provider} can't start this computer: ${plan[0].skip}`, [], "no_provider");
     }
-    const errors = [];
-    for (const p of usable) {
+    const tries = route.fallback === false ? usable.slice(0, 1) : usable;
+    const limitS = route.createTimeoutSeconds ?? DEFAULT_COMPUTER_TIMEOUT_S;
+    const deadline = Date.now() + (route.deadlineSeconds ?? DEFAULT_COMPUTER_DEADLINE_S) * 1000;
+    const attempts = [];
+    for (const c of tries) {
+        const left = deadline - Date.now();
+        if (left <= 0)
+            throw new RouterError(`computer create ran out of time: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "timeout");
+        const p = providers.find((x) => x.id === c.provider);
+        const t0 = Date.now();
+        const pending = p.createComputer({ ...spec, os });
+        const waitS = Math.min(limitS, left / 1000);
+        let timedOut = false;
         try {
-            return new RoutedComputer(p.id, await p.createComputer({ ...spec, os }));
+            const made = await withDeadline(pending, waitS * 1000, () => {
+                timedOut = true;
+                return new ProviderError(p.id, `create timed out after ${Number(waitS.toFixed(1))}s`);
+            });
+            attempts.push({ provider: p.id, ok: true, ms: Date.now() - t0 });
+            const pc = new RoutedComputer(p.id, made, attempts, c.estimatedHourlyUsd, route.ledger);
+            record(route.ledger, pc);
+            return pc;
         }
         catch (err) {
-            errors.push(`${p.id}: ${err.message}`);
+            // One that turns up after we gave up is deleted, so it can't bill unseen (or left in the ledger for gc).
+            if (timedOut) {
+                pending.then((late) => {
+                    const pc = new RoutedComputer(p.id, late, [], c.estimatedHourlyUsd, route.ledger);
+                    record(route.ledger, pc);
+                    return pc.delete();
+                }).catch(() => { });
+            }
+            const status = errorStatus(err);
+            attempts.push({ provider: p.id, 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) {
+                throw new RouterError(`${err.message.replace(/[.\s]+$/, "")}. This looks like a setup problem with ${p.id} (key or request), so the router stopped instead of moving to another provider; pass fallback: "any" to fall back on every error`, attempts, "setup");
+            }
         }
     }
-    throw new RouterError(`all computer providers failed: ${errors.join(" | ")}`);
+    throw new RouterError(`all computer providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "all_failed");
+}
+/** Computers keep running until deleted: the ledger gives them no lifetime, so only `gc --all` takes them. */
+const NO_LIFETIME = "9999-12-31T00:00:00.000Z";
+function record(ledger, pc) {
+    ledger?.open({
+        id: pc.id,
+        provider: pc.provider,
+        kind: "computer",
+        createdAt: new Date().toISOString(),
+        expiresAt: NO_LIFETIME,
+        usdHour: pc.estimatedHourlyUsd ?? 0,
+    });
 }
+/** Seconds to wait for one provider's computer before trying the next. */
+export const DEFAULT_COMPUTER_TIMEOUT_S = 120;
+/** Seconds a whole computer create may take. */
+export const DEFAULT_COMPUTER_DEADLINE_S = 240;

package/dist/gc.js

@@ -34,8 +34,11 @@ export async function gc(router, opts = {}) {
             continue;
         }
         try {
-            const box = await router.get(s.id);
-            await box.kill(); // closes the ledger entry
+            // Both close the ledger entry.
+            if (s.kind === "computer")
+                await (await router.getComputer(s.id)).delete();
+            else
+                await (await router.get(s.id)).kill();
             results.push({ id: s.id, action: "killed" });
         }
         catch (err) {

package/dist/index.d.ts

@@ -2,11 +2,14 @@ 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 { 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 { createApp, HttpError, ERROR_STATUS, ORPHAN_GRACE_MS, type ServerHooks } from "./server.js";
+export { Client, ClientError, RemoteSandbox, type CreateResponse } from "./client.js";
+export { RoutedComputer, createComputer, splitComputerRequest, DEFAULT_COMPUTER_TIMEOUT_S, DEFAULT_COMPUTER_DEADLINE_S, type ComputerRoute, 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";
 export { MaritimeProvider } from "./providers/maritime.js";

package/dist/index.js

@@ -2,11 +2,14 @@ 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, ORPHAN_GRACE_MS } from "./server.js";
 export { Client, ClientError, RemoteSandbox } from "./client.js";
-export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
+export { RoutedComputer, createComputer, splitComputerRequest, DEFAULT_COMPUTER_TIMEOUT_S, DEFAULT_COMPUTER_DEADLINE_S, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
 export { bench, benchMarkdown } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
 export { MaritimeProvider } from "./providers/maritime.js";

package/dist/ledger.d.ts

@@ -3,13 +3,22 @@ import type { ProviderId } from "./types.js";
 export interface LedgerEntry {
     /** Routed id, `provider:nativeId`. */
     id: string;
-    provider: ProviderId;
+    provider: ProviderId | (string & {});
+    /** "computer" for desktops and phones (deleted with getComputer); sandboxes leave it out. */
+    kind?: "computer";
     /** ISO time the create returned. */
     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/.