@sandboxrouter/sdk 0.3.1 → 0.3.2

package/dist/cli.js

@@ -6,6 +6,7 @@ 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 { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
 import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
 import { Router } from "./router.js";
@@ -17,15 +18,15 @@ Usage:
   sandboxrouter providers [--vcpu N] [--memory GB]   price table + which keys are set
   sandboxrouter route     [spec flags] [route flags] dry run: the order providers would be tried
   sandboxrouter run "<cmd>" [spec flags] [route flags] [--keep]
-  sandboxrouter check     --provider ID[,ID] | --all [--json] [--save [dir]]
+  sandboxrouter check     --provider ID[,ID] | --all [--json] [--save [dir]] [--by GITHUB_USER]
                           test providers for real: exec, env, UTF-8, streaming, files, timeout, pause,
                           kill; exits 1 if any step fails. --all = every configured provider;
                           --save writes results/conformance/<id>.json for the compatibility table
   sandboxrouter ls        [--json]                       sandboxes this machine started that weren't killed
   sandboxrouter gc        [--all | --older-than MIN] [--dry-run]
                           kill leaked sandboxes: by default those past their lifetime
-  sandboxrouter bench     [--runs 3] [--provider a,b] [--json] [--share [--label "where you ran it"]]
-  sandboxrouter cost run  [--provider a,b] [--minutes 10] [--vcpu 2 --memory 4] [--no-load] [--out FILE]
+  sandboxrouter bench     [--runs 3] [--provider a,b] [--json] [--share [--label "where you ran it"] [--by GITHUB_USER]]
+  sandboxrouter cost run  [--provider a,b] [--minutes 10] [--vcpu 2 --memory 4] [--no-load] [--out FILE] [--by GITHUB_USER]
                           start one sandbox per provider for a fixed time with every core busy, record
                           the size it really got and the list-price prediction
   sandboxrouter cost settle FILE
@@ -42,7 +43,8 @@ Route flags:  --provider e2b[,modal,...]  --strategy cheapest|fastest
               --no-fallback  --fallback-any (also on setup errors like a bad key)
               --create-timeout SEC (per provider, default 120)  --require gpu,custom-image
 
-Keys: one env var group per provider; "sandboxrouter providers" lists them and shows which are set.`;
+Keys: one env var group per provider; "sandboxrouter providers" lists them and shows which are set.
+--by puts your GitHub username on a saved result, so the website can credit it.`;
 const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
@@ -75,6 +77,7 @@ const { values, positionals } = parseArgs({
         "dry-run": { type: "boolean" },
         minutes: { type: "string" },
         "no-load": { type: "boolean" },
+        by: { type: "string" },
     },
 });
 const list = (s) => (s ? s.split(",").map((x) => x.trim()).filter(Boolean) : undefined);
@@ -92,6 +95,15 @@ const spec = {
     timeoutMinutes: num(values.timeout),
 };
 const providers = list(values.provider);
+const by = (() => {
+    try {
+        return contributor(values.by);
+    }
+    catch (e) {
+        console.error(`error: ${e.message}`);
+        process.exit(2);
+    }
+})();
 const route = {
     provider: providers,
     strategy: values.strategy,
@@ -203,7 +215,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()}`, ...report };
+                const saved = { tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report };
                 writeFileSync(`${saveDir}/${p}.json`, JSON.stringify(saved, null, 2) + "\n");
             }
         }
@@ -264,7 +276,7 @@ async function main() {
             console.error(`\n${r.provider} last error: ${r.lastError}`);
         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 });
+            const report = makeReport(rows, { version, runs: rows[0].runs, spec, label: values.label, by });
             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.`);
@@ -284,6 +296,7 @@ async function main() {
                 spec,
                 load: !values["no-load"],
                 version,
+                by,
                 onProgress: (m) => console.error(m),
             });
             const file = values.out ?? `results/cost/cost-${run.date.slice(0, 16).replace(/[:T]/g, "-")}.json`;

package/dist/conformance.d.ts

@@ -6,6 +6,8 @@ export interface SavedCheck extends CheckReport {
     version: string;
     date: string;
     platform: string;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
 }
 export interface ConformanceRow {
     provider: ProviderId;
@@ -14,6 +16,8 @@ export interface ConformanceRow {
     run: null | {
         date: string;
         version: string;
+        /** GitHub username of whoever ran it, when they gave one. */
+        by: string | null;
         passed: number;
         /** Steps that ran and failed, with why. */
         failed: {

package/dist/conformance.js

@@ -52,6 +52,7 @@ export function conformanceTable(saved = loadConformance()) {
             run: {
                 date: r.date,
                 version: r.version,
+                by: r.by ?? null,
                 passed: pick("pass").length + pick("info").length,
                 failed: pick("fail").map((x) => ({ step: x.step, detail: x.detail })),
                 skipped: pick("skip").map((x) => x.step),

package/dist/cost.d.ts

@@ -48,6 +48,8 @@ export interface CostRun {
     date: string;
     minutes: number;
     load: boolean;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
     entries: CostEntry[];
 }
 export declare function costRun(opts: {
@@ -57,6 +59,7 @@ export declare function costRun(opts: {
     load?: boolean;
     router?: Router;
     version: string;
+    by?: string;
     onProgress?: (msg: string) => void;
 }): Promise<CostRun>;
 type Reader = (e: CostEntry) => Promise<Omit<Bill, "at">>;

package/dist/cost.js

@@ -46,7 +46,7 @@ export async function costRun(opts) {
         return entry;
     };
     const entries = await Promise.all(opts.providers.map(one));
-    return { tool: "sandboxrouter-cost", version: opts.version, date: new Date().toISOString(), minutes: opts.minutes, load, entries };
+    return { tool: "sandboxrouter-cost", version: opts.version, date: new Date().toISOString(), minutes: opts.minutes, load, ...(opts.by ? { by: opts.by } : {}), entries };
 }
 async function getJson(url, headers) {
     const r = await fetch(url, { headers, signal: AbortSignal.timeout(30_000) });

package/dist/leaderboard.d.ts

@@ -11,6 +11,8 @@ export interface BenchReport {
     date: string;
     /** Free text from the submitter, e.g. "us-east-1 c7g.large" or "Berlin, home fiber". */
     label?: string;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
     runs: number;
     spec: SandboxSpec;
     node: string;
@@ -22,6 +24,7 @@ export declare function makeReport(rows: BenchRow[], opts: {
     runs: number;
     spec: SandboxSpec;
     label?: string;
+    by?: string;
 }): BenchReport;
 export declare function loadReports(dir: string): BenchReport[];
 export interface LeaderRow {

package/dist/leaderboard.js

@@ -8,6 +8,7 @@ export function makeReport(rows, opts) {
         version: opts.version,
         date: new Date().toISOString(),
         label: opts.label,
+        ...(opts.by ? { by: opts.by } : {}),
         runs: opts.runs,
         // Only the shape matters for comparison; never ship env or metadata.
         spec: { vcpu: opts.spec.vcpu, memoryGb: opts.spec.memoryGb },

package/dist/providers/blaxel.js

@@ -1,6 +1,6 @@
 import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
 import { ProviderError } from "../types.js";
-import { DEFAULT_EXEC_TIMEOUT_S, optionalImport, timeoutError, toBytes } from "../util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, errorStatus, optionalImport, timeoutError, toBytes } from "../util.js";
 /** Blaxel's public base image (the SDK's own default). Set image.blaxel for another image or a `bl deploy` template. */
 const DEFAULT_IMAGE = "blaxel/base-image:latest";
 /** Blaxel rejects a max-age ttl under 5 minutes. */
@@ -155,7 +155,7 @@ class BlaxelBox {
 function wrap(err) {
     if (err instanceof ProviderError)
         return err;
-    const status = typeof err?.status === "number" ? err.status : typeof err?.code === "number" ? err.code : err?.response?.status;
+    const status = errorStatus(err) ?? (typeof err?.code === "number" ? err.code : undefined);
     // The SDK sometimes throws the plain API body ({ code, error }), not an Error.
     const message = err?.message ?? err?.error ?? (typeof err === "object" ? JSON.stringify(err) : String(err));
     return new ProviderError("blaxel", message, status);

package/dist/providers/deno.js

@@ -1,4 +1,4 @@
-import { ProviderError } from "../types.js";
+import { ProviderError, SetupError } from "../types.js";
 import { dirname, optionalImport, toBytes } from "../util.js";
 /**
  * Deno Sandbox (Linux microVMs on Deno Deploy) via the official `@deno/sandbox` SDK. The SDK is
@@ -43,7 +43,7 @@ export class DenoProvider {
         if (!this.token)
             throw new ProviderError(ID, "DENO_DEPLOY_TOKEN is not set");
         if (!this.token.startsWith("ddo_") && !this.org)
-            throw new ProviderError(ID, "a personal DENO_DEPLOY_TOKEN needs DENO_DEPLOY_ORG");
+            throw new SetupError(`${ID}: a personal DENO_DEPLOY_TOKEN needs DENO_DEPLOY_ORG`);
         return { token: this.token, ...(this.org ? { org: this.org } : {}) };
     }
     async create(spec) {

package/dist/results.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Checks for the files people submit to results/: bench reports, saved `check` runs and `cost` runs.
+ *
+ * Submissions are self-reported, so nothing here can prove a number is real. What it can do is keep
+ * the obvious problems out before a maintainer reviews the PR: files that aren't one of the three
+ * formats, unknown providers, impossible numbers, anything that looks like a key, and labels that
+ * look like a home address or an email. CI runs it on every push and pull request
+ * (`npm run results:check`), and on a pull request it also refuses edits to someone else's bench
+ * report: a new run is a new file.
+ */
+export interface Issue {
+    file: string;
+    problem: string;
+}
+/** A GitHub handle, without the "@": what `--by` accepts and what reports store. */
+export declare function contributor(by?: string): string | undefined;
+/** 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. */
+export declare function scanText(text: string): string[];
+/**
+ * Every problem in a results directory. `changed` is the PR's `git diff --name-status` against its
+ * base, when there is one: a modified bench report means someone edited a run, which is refused.
+ * Saved checks (one per provider, replaced by each new run) and cost runs (`cost settle` fills in the
+ * bill later) may change.
+ */
+export declare function validateResults(dir?: string, opts?: {
+    changed?: {
+        status: string;
+        path: string;
+    }[];
+    now?: number;
+}): Issue[];

package/dist/results.js

@@ -0,0 +1,215 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { 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) {
+    if (by === undefined)
+        return undefined;
+    const h = by.trim().replace(/^@/, "");
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/.test(h)) {
+        throw new Error(`--by takes a GitHub username, e.g. --by octocat (got "${by}")`);
+    }
+    return h;
+}
+const IDS = new Set(CATALOG.map((c) => c.id));
+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,}/],
+    ["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,}/],
+    ["AWS access key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+    ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,})/],
+    ["Slack token", /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
+    ["JWT", /\beyJ[A-Za-z0-9_-]{15,}\.eyJ[A-Za-z0-9_-]{15,}\./],
+    ["bearer token", /\bBearer\s+[A-Za-z0-9._~+/-]{20,}/],
+    ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+    ["key=value secret", /\b[A-Z][A-Z0-9_]*(?:API_KEY|TOKEN|SECRET)["']?\s*[:=]\s*["']?[A-Za-z0-9_\-./+]{16,}/],
+];
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/;
+const IPV4 = /\b(?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}\b/;
+/** "12 Main Street", "Calle Mayor 5", "Apt 4B": a street or a flat, which a label never needs. */
+const ADDRESS = /\b\d+[A-Za-z]?\s+(?:[A-Za-zÀ-ÿ'.-]+\s+){0,3}(?:street|st|road|rd|avenue|ave|lane|ln|drive|dr|way|court|ct|place|pl|boulevard|blvd|terrace|close)\b\.?|\b(?:calle|carrer|rue|via|avenida|straße|strasse|str)\.?\s+[A-Za-zÀ-ÿ'.-]+(?:\s+[A-Za-zÀ-ÿ'.-]+){0,3}\s+\d+|\b(?:apt|apartment|flat|suite|unit|piso|puerta)\.?\s*#?\d+/i;
+const isNum = (n, min = 0, max = Infinity) => typeof n === "number" && Number.isFinite(n) && n >= min && n <= max;
+function checkDate(iso, now) {
+    if (typeof iso !== "string" || Number.isNaN(Date.parse(iso)))
+        return "date is missing or not an ISO date";
+    if (Date.parse(iso) > now + 86_400_000)
+        return "date is in the future";
+    if (Date.parse(iso) < Date.parse("2026-01-01"))
+        return "date is before sandboxrouter existed";
+}
+function checkLabel(label) {
+    if (label === undefined || label === null)
+        return;
+    if (typeof label !== "string")
+        return "label must be text";
+    if (label.length > 80)
+        return "label is longer than 80 characters";
+    if (EMAIL.test(label))
+        return "label contains an email address";
+    if (IPV4.test(label))
+        return "label contains an IP address";
+    if (ADDRESS.test(label))
+        return 'label looks like a street address; use a city or cloud region, e.g. "Berlin" or "us-east-1"';
+}
+function checkBy(by) {
+    if (by === undefined)
+        return;
+    try {
+        if (typeof by !== "string" || contributor(by) !== by)
+            return 'by must be a GitHub username without the "@"';
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+/** Problems with one parsed result file. `now` is injectable for tests. */
+export function validateResult(j, now = Date.now()) {
+    const out = [];
+    const add = (p) => p && out.push(p);
+    const provider = (id, where = "provider") => {
+        if (typeof id !== "string" || !IDS.has(id))
+            out.push(`${where} "${String(id)}" is not in the catalog`);
+    };
+    if (!j || typeof j !== "object" || Array.isArray(j))
+        return ["not a result file: expected a JSON object with a \"tool\" field"];
+    if (j.tool === "sandboxrouter") {
+        add(checkDate(j.date, now));
+        add(checkLabel(j.label));
+        add(checkBy(j.by));
+        if (!isNum(j.runs, 3, 1000))
+            out.push("runs must be at least 3");
+        if (!Array.isArray(j.rows) || !j.rows.length)
+            out.push("rows is empty");
+        for (const r of Array.isArray(j.rows) ? j.rows : []) {
+            provider(r?.provider, "row provider");
+            if (!isNum(r?.runs, 1, 1000))
+                out.push(`${r?.provider}: runs is not a positive number`);
+            if (!isNum(r?.failures, 0, r?.runs ?? 0))
+                out.push(`${r?.provider}: failures must be between 0 and runs`);
+            for (const k of ["medianCreateMs", "medianExecMs"]) {
+                if (r?.[k] !== undefined && !isNum(r[k], 1, MAX_MS))
+                    out.push(`${r?.provider}: ${k} must be between 1 ms and 15 min`);
+            }
+            if (r?.failures < r?.runs && r?.medianCreateMs === undefined)
+                out.push(`${r?.provider}: successful runs but no medianCreateMs`);
+            if ("lastError" in (r ?? {}))
+                out.push(`${r?.provider}: lastError must not be shared (it can hold account details)`);
+        }
+    }
+    else if (j.tool === "sandboxrouter-check") {
+        add(checkDate(j.date, now));
+        add(checkBy(j.by));
+        provider(j.provider);
+        if (!Array.isArray(j.results) || !j.results.length)
+            out.push("results is empty");
+        for (const r of Array.isArray(j.results) ? j.results : []) {
+            if (!STEPS.has(r?.step))
+                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))
+                out.push(`${r?.step}: ms must be between 0 and 15 min`);
+        }
+    }
+    else if (j.tool === "sandboxrouter-cost") {
+        add(checkDate(j.date, now));
+        add(checkBy(j.by));
+        if (!isNum(j.minutes, 1, 24 * 60))
+            out.push("minutes must be between 1 and 1440");
+        if (!Array.isArray(j.entries) || !j.entries.length)
+            out.push("entries is empty");
+        for (const e of Array.isArray(j.entries) ? j.entries : []) {
+            provider(e?.provider, "entry provider");
+            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))
+                out.push(`${e?.provider}: predictedUsd is out of range`);
+            if (e?.bill?.usd !== undefined && !isNum(e.bill.usd, 0, 1000))
+                out.push(`${e?.provider}: bill.usd is out of range`);
+            if (e?.delivered && !(isNum(e.delivered.vcpu, 0.1, 1024) && isNum(e.delivered.memoryMb, 64, 4_194_304))) {
+                out.push(`${e?.provider}: delivered size is out of range`);
+            }
+        }
+    }
+    else {
+        out.push(`unknown tool "${String(j.tool)}": expected a bench report, a saved check or a cost run`);
+    }
+    return out;
+}
+/** Problems found anywhere in a file's raw text: secrets, emails, IP addresses. */
+export function scanText(text) {
+    const out = [];
+    for (const [what, re] of SECRET_SHAPES) {
+        const m = text.match(re);
+        if (m)
+            out.push(`looks like a ${what} ("${m[0].slice(0, 6)}…"); never commit keys`);
+    }
+    const email = text.match(EMAIL);
+    if (email)
+        out.push(`contains an email address ("${email[0].replace(/^(.).*@/, "$1…@")}")`);
+    const ip = text.match(IPV4);
+    if (ip && !/^0\.|^127\./.test(ip[0]))
+        out.push(`contains an IP address ("${ip[0]}")`);
+    return out;
+}
+/** Files in results/ that aren't submissions: notes and the maintainers' price audits. */
+const NOT_A_SUBMISSION = (rel) => /(^|\/)README\.md$/.test(rel) || /(^|\/)price-audit-[^/]+$/.test(rel);
+function walk(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).flatMap((f) => {
+        const p = join(dir, f);
+        return statSync(p).isDirectory() ? walk(p) : [p];
+    });
+}
+/**
+ * Every problem in a results directory. `changed` is the PR's `git diff --name-status` against its
+ * base, when there is one: a modified bench report means someone edited a run, which is refused.
+ * Saved checks (one per provider, replaced by each new run) and cost runs (`cost settle` fills in the
+ * bill later) may change.
+ */
+export function validateResults(dir = "results", opts = {}) {
+    const issues = [];
+    for (const path of walk(dir)) {
+        const rel = relative(".", path);
+        if (NOT_A_SUBMISSION(relative(dir, path)))
+            continue;
+        if (path.endsWith(".DS_Store"))
+            continue;
+        if (!path.endsWith(".json")) {
+            issues.push({ file: rel, problem: "only .json result files belong here" });
+            continue;
+        }
+        const text = readFileSync(path, "utf8");
+        for (const problem of scanText(text))
+            issues.push({ file: rel, problem });
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            issues.push({ file: rel, problem: "is not valid JSON" });
+            continue;
+        }
+        for (const problem of validateResult(j, opts.now))
+            issues.push({ file: rel, problem });
+    }
+    for (const c of opts.changed ?? []) {
+        const p = c.path;
+        if (!p.startsWith(`${dir}/`) || NOT_A_SUBMISSION(p.slice(dir.length + 1)))
+            continue;
+        if (p.startsWith(`${dir}/conformance/`) || p.startsWith(`${dir}/cost/`))
+            continue;
+        if (/^[MR]/.test(c.status))
+            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;
+}

package/dist/router.js

@@ -2,7 +2,7 @@ import { CATALOG, accessLabel, hourlyCost, unfit } from "./catalog.js";
 import { RoutedComputer, createComputer, planComputer, } from "./computers.js";
 import { loadBench, median } from "./bench-store.js";
 import { Ledger, defaultLedgerFile } from "./ledger.js";
-import { DEFAULT_EXEC_TIMEOUT_S, timeoutError } from "./util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, errorStatus, timeoutError } from "./util.js";
 import { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -41,7 +41,7 @@ import { OrgoProvider } from "./providers/orgo.js";
 import { MobilerunProvider } from "./providers/mobilerun.js";
 import { LimrunProvider } from "./providers/limrun.js";
 import { WorkspacesAgentProvider } from "./providers/workspaces.js";
-import { ProviderError, RouterError, } from "./types.js";
+import { ProviderError, SetupError, RouterError, } from "./types.js";
 /** Desktop-only providers. Filled in as adapters are added. */
 export function defaultComputerProviders() {
     return [new OrgoProvider(), new MobilerunProvider(), new LimrunProvider(), new WorkspacesAgentProvider()];
@@ -207,9 +207,11 @@ export class Router {
                 if (timedOut)
                     pending.then((late) => this.discard(c.provider, late, c.estimatedHourlyUsd, spec.timeoutMinutes), () => { });
                 attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
-                const status = err instanceof ProviderError ? err.status : undefined;
-                if (route.fallback !== "any" && status !== undefined && SETUP_ERRORS.has(status)) {
-                    throw new RouterError(`${err.message.replace(/[.\s]+$/, "")}. This looks like a setup problem with ${c.provider} (key, billing, image or request), ` +
+                const status = errorStatus(err);
+                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), ` +
                         `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts);
                 }
             }

package/dist/types.d.ts

@@ -93,3 +93,10 @@ export declare class ProviderError extends Error {
     readonly status?: number | undefined;
     constructor(provider: ProviderId | (string & {}), message: string, status?: number | undefined);
 }
+/**
+ * A problem with local setup, such as a provider SDK that isn't installed or a missing setting:
+ * something to fix here, not a provider being down. The router stops on it instead of falling back.
+ */
+export declare class SetupError extends Error {
+    constructor(message: string);
+}

package/dist/types.js

@@ -17,3 +17,13 @@ export class ProviderError extends Error {
         this.name = "ProviderError";
     }
 }
+/**
+ * A problem with local setup, such as a provider SDK that isn't installed or a missing setting:
+ * something to fix here, not a provider being down. The router stops on it instead of falling back.
+ */
+export class SetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SetupError";
+    }
+}

package/dist/util.d.ts

@@ -36,3 +36,10 @@ export declare function toBytes(content: string | Uint8Array): Uint8Array;
 export declare function dirname(path: string): string;
 /** Load an optional peer dependency with a helpful error. */
 export declare function optionalImport<T>(pkg: string, provider: string): Promise<T>;
+/**
+ * The HTTP status an error stands for, read from the shapes provider SDKs use: `status`,
+ * `statusCode` (Daytona), `status_code` (Blaxel), `response.status` (Vercel), AWS's
+ * `$metadata.httpStatusCode`, gRPC codes (Modal), and error classes that only say it by name
+ * (E2B's AuthenticationError, AWS's CredentialsProviderError). Undefined when there's none.
+ */
+export declare function errorStatus(err: unknown, depth?: number): number | undefined;

package/dist/util.js

@@ -1,4 +1,4 @@
-import { ProviderError } from "./types.js";
+import { ProviderError, SetupError } from "./types.js";
 /** Per-command timeout when ExecOptions.timeoutSeconds is not given. */
 export const DEFAULT_EXEC_TIMEOUT_S = 60;
 /** Single-quote a string for POSIX sh. */
@@ -79,8 +79,34 @@ export async function optionalImport(pkg, provider) {
         // Bundlers and test runners (Vite, esbuild) report a missing package without Node's error code.
         const missing = /Cannot find (module|package)|Could not resolve|Failed to (resolve|load url)/.test(String(err?.message));
         if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || missing) {
-            throw new Error(`${provider} needs the "${pkg}" package: npm i ${pkg}`);
+            throw new SetupError(`${provider} needs the "${pkg}" package: npm i ${pkg}`);
         }
         throw err;
     }
 }
+/** gRPC status codes (Modal's SDK) as the HTTP status they correspond to. */
+const GRPC_TO_HTTP = { 3: 400, 5: 404, 7: 403, 8: 429, 14: 503, 16: 401 };
+/**
+ * The HTTP status an error stands for, read from the shapes provider SDKs use: `status`,
+ * `statusCode` (Daytona), `status_code` (Blaxel), `response.status` (Vercel), AWS's
+ * `$metadata.httpStatusCode`, gRPC codes (Modal), and error classes that only say it by name
+ * (E2B's AuthenticationError, AWS's CredentialsProviderError). Undefined when there's none.
+ */
+export function errorStatus(err, depth = 0) {
+    if (!err || typeof err !== "object" || depth > 3)
+        return undefined;
+    const e = err;
+    for (const v of [e.status, e.statusCode, e.status_code, e.response?.status, e.$metadata?.httpStatusCode])
+        if (typeof v === "number" && v >= 100 && v < 600)
+            return v;
+    if (e.name === "ClientError" && typeof e.code === "number" && GRPC_TO_HTTP[e.code])
+        return GRPC_TO_HTTP[e.code];
+    const name = String(e.name && e.name !== "Error" ? e.name : (e.constructor?.name ?? ""));
+    if (/AuthenticationError$/.test(name) || name === "CredentialsProviderError")
+        return 401;
+    if (/PermissionDenied|ForbiddenError$/.test(name))
+        return 403;
+    if (/RateLimitError$/.test(name))
+        return 429;
+    return errorStatus(e.cause, depth + 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "One API for every sandbox provider: route AI agents' code by price, speed or capability, with automatic fallback. Free and open source.",
   "type": "module",
   "main": "dist/index.js",