@sandboxrouter/sdk 0.3.2 → 0.3.4

package/dist/cli.js

@@ -6,9 +6,9 @@ import { bench, benchMarkdown } from "./bench.js";
 import { costMarkdown, costRun, settle } from "./cost.js";
 import { checkProvider } from "./check.js";
 import { gc, listOpen } from "./gc.js";
-import { contributor } from "./results.js";
+import { contributor, publishableCheck } from "./results.js";
 import { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
-import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, benchmarksPublishable, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
 import { Router } from "./router.js";
 import { createApp } from "./server.js";
 import { RouterError } from "./types.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 cheapest|fastest
+Route flags:  --provider e2b[,modal,...]  --strategy verified|cheapest|fastest (default verified: tested providers first)
               --no-fallback  --fallback-any (also on setup errors like a bad key)
               --create-timeout SEC (per provider, default 120)  --require gpu,custom-image
 
@@ -156,7 +156,8 @@ async function main() {
         let n = 0;
         for (const c of plan) {
             const mark = c.skip ? "  -" : `${++n}.`.padStart(3);
-            console.log(`${mark} ${c.provider.padEnd(11)} $${c.estimatedHourlyUsd.toFixed(4)}/hr${c.skip ? `  (skipped: ${c.skip})` : ""}`);
+            const tested = c.verified ? "tested  " : "        ";
+            console.log(`${mark} ${c.provider.padEnd(11)} $${c.estimatedHourlyUsd.toFixed(4)}/hr  ${tested}${c.skip ? `(skipped: ${c.skip})` : ""}`.trimEnd());
         }
         return;
     }
@@ -215,7 +216,7 @@ async function main() {
             reports.push(report);
             if (saveDir) {
                 mkdirSync(saveDir, { recursive: true });
-                const saved = { tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report };
+                const saved = publishableCheck({ tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report });
                 writeFileSync(`${saveDir}/${p}.json`, JSON.stringify(saved, null, 2) + "\n");
             }
         }
@@ -277,6 +278,9 @@ async function main() {
         if (values.share) {
             const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
             const report = makeReport(rows, { version, runs: rows[0].runs, spec, label: values.label, by });
+            const left = rows.filter((r) => !benchmarksPublishable(r.provider)).map((r) => r.provider);
+            if (left.length)
+                console.log(`\nleft out of the shared report: ${left.join(", ")} (their terms don't allow publishing benchmarks)`);
             const file = values.out ?? `sandboxrouter-bench-${report.date.slice(0, 10)}-${Math.random().toString(36).slice(2, 8)}.json`;
             writeFileSync(file, JSON.stringify(report, null, 2) + "\n");
             console.log(`\nwrote ${file}. Add it to results/ in a PR to github.com/gigialc/sandboxrouter to put it on the leaderboard.`);
@@ -301,7 +305,11 @@ async function main() {
             });
             const file = values.out ?? `results/cost/cost-${run.date.slice(0, 16).replace(/[:T]/g, "-")}.json`;
             mkdirSync(file.replace(/\/[^/]*$/, "") || ".", { recursive: true });
-            writeFileSync(file, JSON.stringify(await settle(run), null, 2) + "\n");
+            const settled = await settle(run);
+            const left = settled.entries.filter((e) => !benchmarksPublishable(e.provider)).map((e) => e.provider);
+            writeFileSync(file, JSON.stringify({ ...settled, entries: settled.entries.filter((e) => benchmarksPublishable(e.provider)) }, null, 2) + "\n");
+            if (left.length)
+                console.log(`left out of ${file}: ${left.join(", ")} (their terms don't allow publishing benchmarks; the table above is the only copy)`);
             console.log(costMarkdown(run));
             console.log(`\nwrote ${file}. Bills post late on some providers: run "sandboxrouter cost settle ${file}" again later.`);
             return;

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+import type { Attempt, ExecOptions, ExecResult, RouteOptions, 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.
+ *
+ *   const sr = new Client({ apiKey: process.env.SANDBOXROUTER_API_KEY });
+ *   const sbx = await sr.create({ vcpu: 2, memoryGb: 4 });
+ *   console.log(sbx.provider, (await sbx.exec("python3 -c 'print(6*7)'")).stdout);
+ *   await sbx.kill();
+ */
+export declare class Client {
+    readonly baseUrl: string;
+    private readonly apiKey?;
+    private readonly fetch;
+    constructor(opts?: {
+        apiKey?: string;
+        baseUrl?: string;
+        fetch?: typeof fetch;
+    });
+    /** @internal */
+    request(method: string, path: string, body?: unknown, accept?: string): Promise<Response>;
+    private json;
+    /** Providers this server can route to, with list prices. */
+    providers(): Promise<{
+        id: string;
+        configured: boolean;
+        estimatedHourlyUsd: number;
+    }[]>;
+    /** 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>;
+    /** 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[]);
+}
+export declare class RemoteSandbox {
+    private readonly client;
+    readonly id: string;
+    readonly provider: string;
+    readonly estimatedHourlyUsd?: number | undefined;
+    readonly attempts: Attempt[];
+    constructor(client: Client, id: string, provider: string, estimatedHourlyUsd?: number | undefined, attempts?: Attempt[]);
+    private path;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    pause(): Promise<void>;
+    kill(): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,140 @@
+/**
+ * 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.
+ *
+ *   const sr = new Client({ apiKey: process.env.SANDBOXROUTER_API_KEY });
+ *   const sbx = await sr.create({ vcpu: 2, memoryGb: 4 });
+ *   console.log(sbx.provider, (await sbx.exec("python3 -c 'print(6*7)'")).stdout);
+ *   await sbx.kill();
+ */
+export class Client {
+    baseUrl;
+    apiKey;
+    fetch;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? process.env.SANDBOXROUTER_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+        this.apiKey = opts.apiKey ?? process.env.SANDBOXROUTER_API_KEY ?? process.env.SANDBOXROUTER_TOKEN;
+        this.fetch = opts.fetch ?? globalThis.fetch;
+    }
+    /** @internal */
+    async request(method, path, body, accept = "application/json") {
+        const raw = body instanceof Uint8Array;
+        const res = await this.fetch(this.baseUrl + path, {
+            method,
+            headers: {
+                Accept: accept,
+                ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+                ...(body === undefined ? {} : { "Content-Type": raw ? "application/octet-stream" : "application/json" }),
+            },
+            body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            let parsed = {};
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch { }
+            throw new ClientError(res.status, parsed.error ?? (text || res.statusText), parsed.attempts ?? []);
+        }
+        return res;
+    }
+    async json(method, path, body) {
+        return (await this.request(method, path, body)).json();
+    }
+    /** Providers this server can route to, with list prices. */
+    async providers() {
+        return (await this.json("GET", "/v1/providers")).providers;
+    }
+    /** Dry run: which providers would be tried, in order. */
+    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);
+    }
+    /** A handle on a sandbox you created earlier. */
+    sandbox(id) {
+        return new RemoteSandbox(this, id, id.split(":")[0]);
+    }
+}
+const DEFAULT_URL = "http://127.0.0.1:8787";
+export class ClientError extends Error {
+    status;
+    attempts;
+    constructor(status, message, attempts = []) {
+        super(`${status}: ${message}`);
+        this.status = status;
+        this.attempts = attempts;
+        this.name = "ClientError";
+    }
+}
+export class RemoteSandbox {
+    client;
+    id;
+    provider;
+    estimatedHourlyUsd;
+    attempts;
+    constructor(client, id, provider, estimatedHourlyUsd, attempts = []) {
+        this.client = client;
+        this.id = id;
+        this.provider = provider;
+        this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.attempts = attempts;
+    }
+    path(suffix = "") {
+        return `/v1/sandboxes/${encodeURIComponent(this.id)}${suffix}`;
+    }
+    async exec(cmd, opts = {}) {
+        const { onStdout, onStderr, ...rest } = opts;
+        const body = { cmd, ...rest };
+        if (!onStdout && !onStderr)
+            return (await this.client.request("POST", this.path("/exec"), body)).json();
+        const res = await this.client.request("POST", this.path("/exec"), { ...body, stream: true }, "text/event-stream");
+        const decoder = new TextDecoder();
+        let buf = "";
+        for await (const chunk of res.body) {
+            buf += decoder.decode(chunk, { stream: true });
+            let end;
+            while ((end = buf.indexOf("\n\n")) >= 0) {
+                const block = buf.slice(0, end);
+                buf = buf.slice(end + 2);
+                const event = /^event: ?(.*)$/m.exec(block)?.[1] ?? "message";
+                const data = block
+                    .split("\n")
+                    .filter((l) => l.startsWith("data:"))
+                    .map((l) => l.slice(l[5] === " " ? 6 : 5))
+                    .join("\n");
+                const payload = JSON.parse(data);
+                if (event === "stdout")
+                    onStdout?.(payload);
+                else if (event === "stderr")
+                    onStderr?.(payload);
+                else if (event === "result")
+                    return payload;
+                else if (event === "error")
+                    throw new ClientError(502, payload.error ?? data);
+            }
+        }
+        throw new ClientError(502, "stream ended before the command finished");
+    }
+    async writeFile(path, content) {
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        await this.client.request("PUT", this.path(`/files?path=${encodeURIComponent(path)}`), data);
+    }
+    async readFile(path) {
+        const res = await this.client.request("GET", this.path(`/files?path=${encodeURIComponent(path)}`), undefined, "application/octet-stream");
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async pause() {
+        await this.client.request("POST", this.path("/pause"));
+    }
+    async kill() {
+        await this.client.request("DELETE", this.path());
+    }
+}

package/dist/cost.d.ts

@@ -52,6 +52,13 @@ export interface CostRun {
     by?: string;
     entries: CostEntry[];
 }
+/**
+ * The size the sandbox really has, as "<vcpus> <memoryMb>". nproc and MemTotal can show the whole host
+ * (Daytona's containers report 64 CPUs and 755 GB while limited to 1 vCPU and 1 GB), so the cgroup limits
+ * win when they're set: cgroup v2 cpu.max / memory.max, or v1 cfs quota / memory limit. vCPUs can be
+ * fractional (a 50% quota is 0.5).
+ */
+export declare const PROBE: string;
 export declare function costRun(opts: {
     providers: ProviderId[];
     minutes: number;

package/dist/cost.js

@@ -1,6 +1,18 @@
 import { fittingSpec, hourlyCost } from "./catalog.js";
 import { Router } from "./router.js";
-const PROBE = `echo "$(nproc) $(awk '/MemTotal/{printf "%d", $2/1024}' /proc/meminfo)"`;
+/**
+ * The size the sandbox really has, as "<vcpus> <memoryMb>". nproc and MemTotal can show the whole host
+ * (Daytona's containers report 64 CPUs and 755 GB while limited to 1 vCPU and 1 GB), so the cgroup limits
+ * win when they're set: cgroup v2 cpu.max / memory.max, or v1 cfs quota / memory limit. vCPUs can be
+ * fractional (a 50% quota is 0.5).
+ */
+export const PROBE = [
+    `n=$(nproc); m=$(awk '/MemTotal/{printf "%d", $2/1024}' /proc/meminfo)`,
+    `q=; p=; l=`,
+    `if [ -r /sys/fs/cgroup/cpu.max ]; then read q p < /sys/fs/cgroup/cpu.max; elif [ -r /sys/fs/cgroup/cpu/cpu.cfs_quota_us ]; then q=$(cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us); p=$(cat /sys/fs/cgroup/cpu/cpu.cfs_period_us); fi`,
+    `if [ -r /sys/fs/cgroup/memory.max ]; then l=$(cat /sys/fs/cgroup/memory.max); elif [ -r /sys/fs/cgroup/memory/memory.limit_in_bytes ]; then l=$(cat /sys/fs/cgroup/memory/memory.limit_in_bytes); fi`,
+    `awk -v n="$n" -v m="$m" -v q="$q" -v p="$p" -v l="$l" 'BEGIN { c = n; if (q ~ /^[0-9]+$/ && p ~ /^[0-9]+$/ && p > 0 && q / p < c) c = q / p; if (l ~ /^[0-9]+$/ && l / 1048576 < m) m = int(l / 1048576); printf "%s %d\\n", (c == int(c) ? c : sprintf("%.2f", c)), m }'`,
+].join("; ");
 // One `yes` per core, detached so the exec returns; they die with the sandbox.
 const LOAD = `nohup sh -c 'for i in $(seq $(nproc)); do yes > /dev/null & done; wait' > /dev/null 2>&1 &`;
 const round = (n, d = 6) => Math.round(n * 10 ** d) / 10 ** d;

package/dist/index.d.ts

@@ -4,7 +4,8 @@ export { conformanceTable, loadConformance, type ConformanceRow, type SavedCheck
 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 { CATALOG, hourlyCost, unfit, info, type ProviderInfo } from "./catalog.js";
-export { createApp } from "./server.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 { bench, benchMarkdown, type BenchRow } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard, type BenchReport, type LeaderRow } from "./leaderboard.js";

package/dist/index.js

@@ -4,7 +4,8 @@ export { conformanceTable, loadConformance } from "./conformance.js";
 export { gc, listOpen, isGone } from "./gc.js";
 export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId } from "./router.js";
 export { CATALOG, hourlyCost, unfit, info } from "./catalog.js";
-export { createApp } from "./server.js";
+export { createApp, HttpError } 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";
 export { aggregate, loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";

package/dist/leaderboard.js

@@ -1,6 +1,6 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { CATALOG, fittingSpec, hourlyCost } from "./catalog.js";
+import { benchmarksPublishable, CATALOG, fittingSpec, hourlyCost } from "./catalog.js";
 import { median } from "./bench-store.js";
 export function makeReport(rows, opts) {
     return {
@@ -14,7 +14,8 @@ export function makeReport(rows, opts) {
         spec: { vcpu: opts.spec.vcpu, memoryGb: opts.spec.memoryGb },
         node: process.version,
         platform: `${process.platform}-${process.arch}`,
-        rows: rows.map(({ lastError: _drop, ...r }) => r),
+        // Providers whose terms forbid publishing benchmarks stay out of anything meant to be shared.
+        rows: rows.filter((r) => benchmarksPublishable(r.provider)).map(({ lastError: _drop, ...r }) => r),
     };
 }
 export function loadReports(dir) {

package/dist/results.d.ts

@@ -14,6 +14,17 @@ export interface Issue {
 }
 /** A GitHub handle, without the "@": what `--by` accepts and what reports store. */
 export declare function contributor(by?: string): string | undefined;
+/**
+ * A saved check as it may be published: for a provider whose terms forbid publishing benchmarks,
+ * pass/fail stays and every timing goes (the per-step `ms`, and notes that quote a duration).
+ */
+export declare function publishableCheck<T extends {
+    provider: string;
+    results: {
+        ms?: number;
+        detail?: string;
+    }[];
+}>(saved: T): T;
 /** Problems with one parsed result file. `now` is injectable for tests. */
 export declare function validateResult(j: any, now?: number): string[];
 /** Problems found anywhere in a file's raw text: secrets, emails, IP addresses. */
@@ -29,5 +40,6 @@ export declare function validateResults(dir?: string, opts?: {
         status: string;
         path: string;
     }[];
+    previous?: (path: string) => string | undefined;
     now?: number;
 }): Issue[];

package/dist/results.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { CATALOG } from "./catalog.js";
+import { benchmarksPublishable, CATALOG } from "./catalog.js";
 import { CHECK_STEPS } from "./check.js";
 /** A GitHub handle, without the "@": what `--by` accepts and what reports store. */
 export function contributor(by) {
@@ -13,12 +13,29 @@ export function contributor(by) {
     return h;
 }
 const IDS = new Set(CATALOG.map((c) => c.id));
+/** A timing in a check step's note, e.g. "first output after 100 ms" or "threw after 3.0 s". */
+const TIMING = /\d[\d,.]*\s?(?:ms|s|sec|seconds?)\b/i;
+/**
+ * A saved check as it may be published: for a provider whose terms forbid publishing benchmarks,
+ * pass/fail stays and every timing goes (the per-step `ms`, and notes that quote a duration).
+ */
+export function publishableCheck(saved) {
+    if (benchmarksPublishable(saved.provider))
+        return saved;
+    return {
+        ...saved,
+        results: saved.results.map(({ ms: _ms, detail, ...r }) => ({ ...r, ...(detail && !TIMING.test(detail) ? { detail } : {}) })),
+    };
+}
+const noBench = (id) => typeof id === "string" && IDS.has(id) && !benchmarksPublishable(id);
+const NO_BENCH = "its terms don't allow publishing benchmarks (noBenchmarks in src/catalog.ts); leave it out of shared results";
 const STEPS = new Set(CHECK_STEPS);
 const MAX_MS = 15 * 60_000;
 /** Key and token shapes from the providers here and the usual suspects. Matches print as a prefix only. */
 const SECRET_SHAPES = [
     ["Stripe-style or Sail key", /\bsk_(?:live_|test_)?[A-Za-z0-9]{16,}/],
     ["OpenAI-style key", /\bsk-[A-Za-z0-9_-]{20,}/],
+    ["sandboxrouter key", /\bsr_live_[A-Za-z0-9_-]{20,}/],
     ["E2B key", /\be2b_[A-Za-z0-9]{20,}/],
     ["Daytona key", /\bdtn_[A-Za-z0-9]{20,}/],
     ["LangSmith key", /\blsv2_(?:sk|pt)_[A-Za-z0-9_]{20,}/],
@@ -88,6 +105,8 @@ export function validateResult(j, now = Date.now()) {
             out.push("rows is empty");
         for (const r of Array.isArray(j.rows) ? j.rows : []) {
             provider(r?.provider, "row provider");
+            if (noBench(r?.provider))
+                out.push(`${r.provider}: ${NO_BENCH}`);
             if (!isNum(r?.runs, 1, 1000))
                 out.push(`${r?.provider}: runs is not a positive number`);
             if (!isNum(r?.failures, 0, r?.runs ?? 0))
@@ -113,8 +132,11 @@ export function validateResult(j, now = Date.now()) {
                 out.push(`unknown check step "${r?.step}"`);
             if (!["pass", "fail", "skip", "info"].includes(r?.status))
                 out.push(`${r?.step}: unknown status "${r?.status}"`);
-            if (!isNum(r?.ms, 0, MAX_MS))
+            if (r?.ms !== undefined && !isNum(r.ms, 0, MAX_MS))
                 out.push(`${r?.step}: ms must be between 0 and 15 min`);
+            if (noBench(j.provider) && (r?.ms !== undefined || (typeof r?.detail === "string" && TIMING.test(r.detail)))) {
+                out.push(`${r?.step}: has timings, but ${j.provider}'s terms don't allow publishing performance information; save with check --save`);
+            }
         }
     }
     else if (j.tool === "sandboxrouter-cost") {
@@ -126,6 +148,8 @@ export function validateResult(j, now = Date.now()) {
             out.push("entries is empty");
         for (const e of Array.isArray(j.entries) ? j.entries : []) {
             provider(e?.provider, "entry provider");
+            if (noBench(e?.provider))
+                out.push(`${e.provider}: ${NO_BENCH}`);
             if (e?.seconds !== undefined && !isNum(e.seconds, 0, 2 * 24 * 3600))
                 out.push(`${e?.provider}: seconds is out of range`);
             if (e?.predictedUsd !== undefined && !isNum(e.predictedUsd, 0, 1000))
@@ -206,10 +230,32 @@ export function validateResults(dir = "results", opts = {}) {
             continue;
         if (p.startsWith(`${dir}/conformance/`) || p.startsWith(`${dir}/cost/`))
             continue;
-        if (/^[MR]/.test(c.status))
+        if (/^[MR]/.test(c.status) && !onlyDropsUnpublishable(opts.previous?.(p), p)) {
             issues.push({ file: p, problem: "edits an existing bench report; add your run as a new file instead" });
+        }
         if (c.status.startsWith("D"))
             issues.push({ file: p, problem: "deletes a bench report; reports are only removed by a maintainer" });
     }
     return issues;
 }
+/**
+ * True when a bench report's only change is removing rows for providers whose terms forbid publishing
+ * benchmarks: the one edit to someone's report that's allowed, so those numbers can be taken down.
+ */
+function onlyDropsUnpublishable(before, path) {
+    if (before === undefined || !existsSync(path))
+        return false;
+    try {
+        const a = JSON.parse(before);
+        const b = JSON.parse(readFileSync(path, "utf8"));
+        const { rows: ra, ...restA } = a;
+        const { rows: rb, ...restB } = b;
+        if (JSON.stringify(restA) !== JSON.stringify(restB))
+            return false;
+        const kept = ra.filter((r) => benchmarksPublishable(r.provider));
+        return JSON.stringify(kept) === JSON.stringify(rb);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/router.d.ts

@@ -5,6 +5,8 @@ export interface Candidate {
     provider: ProviderId;
     estimatedHourlyUsd: number;
     medianCreateMs?: number;
+    /** Passed the real-account check (as of this release, or `RouterOptions.verified`). */
+    verified: boolean;
     /** Why this provider won't be tried, if it won't. */
     skip?: string;
 }
@@ -21,6 +23,11 @@ export interface RouterOptions {
      * false to keep no record. SANDBOXROUTER_LEDGER=off also turns it off.
      */
     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.
+     */
+    verified?: ProviderId[];
 }
 /** Desktop-only providers. Filled in as adapters are added. */
 export declare function defaultComputerProviders(): ComputerProvider[];
@@ -28,6 +35,7 @@ export declare function defaultProviders(): Provider[];
 export declare class Router {
     private providers;
     private benchFile?;
+    private readonly verified;
     private computerOnly;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     readonly ledger?: Ledger;

package/dist/router.js

@@ -3,6 +3,7 @@ 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 { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -87,6 +88,7 @@ export function defaultProviders() {
 export class Router {
     providers;
     benchFile;
+    verified;
     computerOnly;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     ledger;
@@ -96,6 +98,7 @@ export class Router {
             this.ledger = new Ledger(file);
         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.computerOnly = opts.computers ?? (opts.providers ? [] : defaultComputerProviders());
     }
     /** Registered and has credentials. False for providers this router doesn't know. */
@@ -122,12 +125,13 @@ export class Router {
         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, skip: "unknown provider" };
+                return { provider: id, estimatedHourlyUsd: 0, verified: false, skip: "unknown provider" };
             const p = this.providers.get(id);
             const c = {
                 provider: id,
                 estimatedHourlyUsd: round(hourlyCost(id, spec)),
                 medianCreateMs: median(bench[id]?.createMs),
+                verified: this.verified.has(id),
             };
             if (!p)
                 c.skip = "no adapter registered";
@@ -137,16 +141,20 @@ export class Router {
             }
             return c;
         });
-        // Neutral by construction: price (or measured speed) decides, ties break alphabetically by id.
+        // 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.
         if (!explicit) {
             const byPrice = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
             if (route.strategy === "fastest") {
                 list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
             }
-            else {
+            else if (route.strategy === "cheapest") {
                 list.sort(byPrice);
             }
+            else {
+                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byPrice(a, b));
+            }
         }
         return list;
     }
@@ -211,7 +219,7 @@ export class Router {
                 const setup = err instanceof SetupError || (status !== undefined && SETUP_ERRORS.has(status));
                 if (route.fallback !== "any" && setup) {
                     const msg = err.message.replace(/[.\s]+$/, "");
-                    throw new RouterError(`${msg.startsWith(c.provider) ? msg : `${c.provider}: ${msg}`}. This looks like a setup problem with ${c.provider} (key, billing, image, request or a missing package), ` +
+                    throw new RouterError(`${msg.startsWith(c.provider) ? msg : `${c.provider}: ${msg}`}. This looks like a setup problem with ${c.provider} (key, image, request or a missing package), ` +
                         `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts);
                 }
             }
@@ -336,8 +344,12 @@ function round(n) {
 }
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export const DEFAULT_CREATE_TIMEOUT_S = 120;
-/** HTTP statuses that mean the request or the account is wrong, not that the provider is down. */
-const SETUP_ERRORS = new Set([400, 401, 402, 403, 404, 422]);
+/**
+ * HTTP statuses that mean the request or the key is wrong, not that the provider is down. 402 (out of
+ * balance, plan needed) isn't one: an unfunded account is exactly when the next provider should take the
+ * sandbox, and the failed attempt stays on `attempts` (the CLI prints it), so it isn't hidden.
+ */
+const SETUP_ERRORS = new Set([400, 401, 403, 404, 422]);
 /** Seconds past a command's timeout before the router stops waiting for the adapter. */
 export const EXEC_GRACE_S = 30;
 /** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */

package/dist/server.d.ts

@@ -1,5 +1,28 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
-import { Router } from "./router.js";
+import { Router, type RoutedSandbox } from "./router.js";
+import { type RouteOptions, type SandboxSpec } from "./types.js";
+/**
+ * Hooks for running this API for many users, as the hosted service does (hosted/). With none set,
+ * the server is single-user: one SANDBOXROUTER_TOKEN, every sandbox reachable by anyone holding it.
+ */
+export interface ServerHooks {
+    /** Who is calling, or null for 401. Replaces the single-token check. */
+    authorize?(req: IncomingMessage): Promise<unknown | null>;
+    /** Routes outside /v1 (sign-in, billing webhooks, pages), checked before auth. Return true if handled. */
+    extra?(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
+    /** Before a sandbox starts. Throw HttpError to refuse (402 out of credit, 429 too many); may edit spec. */
+    beforeCreate?(caller: unknown, spec: SandboxSpec, route: RouteOptions): Promise<void>;
+    /** After it started. If this throws, the sandbox is killed and the error returned. */
+    afterCreate?(caller: unknown, sbx: RoutedSandbox, spec: SandboxSpec): Promise<void>;
+    /** May this caller use this sandbox? No means 404. */
+    owns?(caller: unknown, id: string): Promise<boolean>;
+    /** After DELETE killed it. */
+    afterKill?(caller: unknown, id: string): Promise<void>;
+    /** false turns off /v1/computers. */
+    computers?: boolean;
+    /** false turns off pause. */
+    pause?: boolean;
+}
 /**
  * OpenRouter-style HTTP API in front of every provider. One token for your clients; provider keys
  * stay on this host.
@@ -28,4 +51,8 @@ import { Router } from "./router.js";
  */
 export declare function createApp(router?: Router, token?: string | undefined, 
 /** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
-corsOrigins?: string[]): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+corsOrigins?: string[], hooks?: ServerHooks): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}