@sandboxrouter/sdk 0.5.0 → 0.6.0

package/dist/client.d.ts

@@ -19,7 +19,7 @@ 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 prices at the default size. */
     providers(): Promise<{
@@ -31,8 +31,14 @@ export declare class Client {
     }[]>;
     /** Dry run: which providers would be tried, in order, each with its price, size and any reason it's skipped. */
     route(spec?: SandboxSpec, route?: RouteOptions): Promise<Candidate[]>;
-    /** Start a sandbox on the first provider that works, as the server routes it. */
-    create(spec?: SandboxSpec, route?: RouteOptions): Promise<RemoteSandbox>;
+    /**
+     * 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;
 }

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),
         });
@@ -50,10 +51,16 @@ export class Client {
     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);
+    /**
+     * 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) {

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

@@ -7,9 +7,9 @@ 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, ERROR_STATUS, type ServerHooks } from "./server.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, 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 { 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

@@ -7,9 +7,9 @@ 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, ERROR_STATUS } 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,7 +3,9 @@ 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. */

package/dist/router.d.ts

@@ -1,4 +1,4 @@
-import { RoutedComputer, type ComputerOs, type ComputerProvider, type ComputerProviderId, type ComputerSpec } from "./computers.js";
+import { type ComputerRoute, RoutedComputer, type ComputerOs, type ComputerProvider, type ComputerProviderId, type ComputerSpec } from "./computers.js";
 import { Ledger } from "./ledger.js";
 import { type Attempt, type ExecOptions, type ExecResult, type Provider, type ProviderId, type ProviderSandbox, type RouteOptions, type SandboxSpec } from "./types.js";
 /** vCPUs and memory a sandbox gets. */
@@ -105,9 +105,8 @@ export declare class Router {
         provider?: ComputerProviderId | ComputerProviderId[];
     }): import("./computers.js").ComputerCandidate[];
     /** Start a desktop or phone on the cheapest provider for its OS (ties alphabetical), with fallback. */
-    computer(spec?: ComputerSpec, opts?: {
-        provider?: ComputerProviderId | ComputerProviderId[];
-    }): Promise<RoutedComputer>;
+    /** Start a desktop or phone, routed like a sandbox (see createComputer). */
+    computer(spec?: ComputerSpec, route?: ComputerRoute): Promise<RoutedComputer>;
     getComputer(id: string): Promise<RoutedComputer>;
     /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
     get(id: string): Promise<RoutedSandbox>;

package/dist/router.js

@@ -2,7 +2,7 @@ import { CATALOG, DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, fixedSize, hourl
 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 { DEFAULT_EXEC_TIMEOUT_S, SETUP_ERRORS, errorStatus, timeoutError, withDeadline } from "./util.js";
 import { BILLED_VS_LIST } from "./billing.js";
 import { FAILING, VERIFIED } from "./verified.js";
 import { validate } from "./validate.js";
@@ -309,19 +309,21 @@ export class Router {
         return planComputer(this.computerProviders(), os, prefer);
     }
     /** Start a desktop or phone on the cheapest provider for its OS (ties alphabetical), with fallback. */
-    computer(spec = {}, opts = {}) {
-        const prefer = opts.provider ? [].concat(opts.provider) : undefined;
-        return createComputer(this.computerProviders(), spec, prefer);
+    /** Start a desktop or phone, routed like a sandbox (see createComputer). */
+    computer(spec = {}, route = {}) {
+        const prefer = route.provider ? [].concat(route.provider) : undefined;
+        return createComputer(this.computerProviders(), spec, prefer, { ...route, ledger: this.ledger });
     }
     async getComputer(id) {
         const i = id.indexOf(":");
         if (i <= 0)
-            throw new RouterError(`bad computer id "${id}": expected provider:id`);
+            throw new RouterError(`bad computer id "${id}": expected provider:id`, [], "bad_request");
         const provider = id.slice(0, i);
         const p = this.computerProviders().find((c) => c.id === provider);
         if (!p)
-            throw new RouterError(`${provider} does not offer computers`);
-        return new RoutedComputer(provider, await p.connectComputer(id.slice(i + 1)));
+            throw new RouterError(`${provider} does not offer computers`, [], "bad_request");
+        const e = this.ledger?.list().find((x) => x.id === id);
+        return new RoutedComputer(provider, await p.connectComputer(id.slice(i + 1)), [], e?.usdHour, this.ledger);
     }
     /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
     async get(id) {
@@ -437,29 +439,8 @@ export function balanced(list) {
 export const DEFAULT_CREATE_TIMEOUT_S = 120;
 /** Seconds a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */
 export const DEFAULT_CREATE_DEADLINE_S = 240;
-/**
- * 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. */
-async function withDeadline(work, ms, onExpire) {
-    let timer;
-    const expired = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(onExpire()), ms);
-        timer.unref();
-    });
-    try {
-        return await Promise.race([work, expired]);
-    }
-    finally {
-        clearTimeout(timer);
-        work.catch(() => { });
-    }
-}
 /** The size a provider gives for a spec: its fixed default image size, else what was asked for. */
 export function sizeOf(id, spec = {}) {
     return fixedSize(id, spec) ?? { vcpu: spec.vcpu ?? DEFAULT_VCPU, memoryGb: spec.memoryGb ?? DEFAULT_MEMORY_GB };

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { Router, type RoutedSandbox } from "./router.js";
+import { type ComputerSpec, type RoutedComputer } from "./computers.js";
 import { type RouteOptions, type RouterErrorCode, type SandboxSpec } from "./types.js";
 /**
  * Hooks for running this API for many users (accounts, billing, per-user sandboxes). With none set,
@@ -30,8 +31,21 @@ export interface ServerHooks {
     afterKill?(caller: unknown, id: string, outcome?: {
         error?: Error;
     }): Promise<void>;
-    /** /v1/computers. Default: on for a single-user server, off when `authorize` is set (computers don't go through these hooks). */
+    /**
+     * /v1/computers. Default: on for a single-user server, off when `authorize` is set. When on with
+     * `authorize`, `owns` guards computer ids too, and the computer hooks below run.
+     */
     computers?: boolean;
+    /** Before a computer starts. Throw HttpError to refuse; may edit spec. */
+    beforeCreateComputer?(caller: unknown, spec: ComputerSpec): Promise<void>;
+    /** After a computer started. Return fields to add to the answer. If this throws, the computer is deleted. */
+    afterCreateComputer?(caller: unknown, computer: RoutedComputer): Promise<Record<string, unknown> | void>;
+    /** After DELETE /v1/computers/:id; `error` is set when the provider's delete failed. */
+    afterDeleteComputer?(caller: unknown, id: string, outcome?: {
+        error?: Error;
+    }): Promise<void>;
+    /** Milliseconds a sandbox whose caller hung up (having sent an Idempotency-Key) waits for a retry to collect it. Default 120000. */
+    orphanGraceMs?: number;
     /** false turns off pause. */
     pause?: boolean;
 }
@@ -68,5 +82,7 @@ export declare class HttpError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** How long a sandbox whose caller hung up (with an Idempotency-Key) waits for a retry to collect it. */
+export declare const ORPHAN_GRACE_MS = 120000;
 /** The HTTP status for each RouterError code (see RouterErrorCode). */
 export declare const ERROR_STATUS: Record<RouterErrorCode, number>;

package/dist/server.js

@@ -1,7 +1,8 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { CATALOG } from "./catalog.js";
 import { Router } from "./router.js";
+import { splitComputerRequest } from "./computers.js";
 import { ProviderError, RouterError } from "./types.js";
 import { errorStatus } from "./util.js";
 import { splitRequest } from "./validate.js";
@@ -49,6 +50,63 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
     };
     const live = new Map();
     const computersOn = hooks.computers ?? !hooks.authorize;
+    /**
+     * Idempotency-Key: a create retried with the same key (by the same caller, to the same path) gets the
+     * first create's answer instead of starting another sandbox, for 24 hours. A retry that arrives while
+     * the first is still starting waits for it. The same key with a different body is refused (422).
+     * Failed creates aren't remembered, so retrying one runs it again.
+     */
+    const replays = new Map();
+    const once = async (req, res, body, run) => {
+        const raw = req.headers["idempotency-key"];
+        if (raw === undefined) {
+            const r = await run(false);
+            return json(res, r.status, r.body);
+        }
+        const key = Array.isArray(raw) ? raw[0] : raw;
+        if (!key || key.length > 255)
+            throw new HttpError(400, "Idempotency-Key must be 1 to 255 characters");
+        const now = Date.now();
+        for (const [k, v] of replays)
+            if (now - v.at > IDEMPOTENCY_TTL_MS)
+                replays.delete(k);
+        while (replays.size >= IDEMPOTENCY_MAX)
+            replays.delete(replays.keys().next().value);
+        const scope = sha256(`${req.headers.authorization ?? ""}\n${req.url}\n${key}`);
+        const bodyHash = sha256(JSON.stringify(body ?? {}));
+        const hit = replays.get(scope);
+        if (hit) {
+            if (hit.bodyHash !== bodyHash)
+                throw new HttpError(422, "this Idempotency-Key was already used with a different request");
+            const r = await hit.result;
+            hit.claimed = true;
+            res.setHeader("Idempotent-Replayed", "true");
+            return json(res, r.status, r.body);
+        }
+        const entry = { bodyHash, result: run(true), at: now, claimed: false };
+        replays.set(scope, entry);
+        let r;
+        try {
+            r = await entry.result;
+        }
+        catch (err) {
+            replays.delete(scope);
+            throw err;
+        }
+        // The caller hung up but sent a key, so it means to retry: keep the sandbox for a retry to
+        // collect, and only then give up on it.
+        if (!res.writableEnded && (res.destroyed || !res.writable) && r.discard) {
+            setTimeout(() => {
+                if (!entry.claimed) {
+                    replays.delete(scope);
+                    r.discard().catch(() => { });
+                }
+            }, hooks.orphanGraceMs ?? ORPHAN_GRACE_MS).unref();
+        }
+        else
+            entry.claimed = true;
+        return json(res, r.status, r.body);
+    };
     const cors = (req, res) => {
         const origin = req.headers.origin;
         if (!origin || !(corsOrigins.includes("*") || corsOrigins.includes(origin)))
@@ -108,46 +166,59 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         if (parts[1] === "computers") {
             if (!computersOn)
                 return json(res, 404, { error: "computers aren't available on this server" });
-            return computers(req, res, url, parts);
+            return computers(req, res, url, parts, caller);
         }
         if (parts[1] !== "sandboxes")
             return json(res, 404, { error: "not found" });
         // POST /v1/sandboxes
         if (req.method === "POST" && parts.length === 2) {
-            const { spec, route } = splitRequest(await readJson(req));
-            await hooks.beforeCreate?.(caller, spec, route);
+            const body = await readJson(req);
+            const { spec, route } = splitRequest(body);
             // A caller that gives up (client timeout, closed connection) never learns the id: kill what
-            // starts after that rather than leave it running, and billing, unseen.
+            // starts after that rather than leave it running, and billing, unseen. With an Idempotency-Key
+            // it's kept for a retry instead (see once).
             let hungUp = false;
             res.on("close", () => (hungUp = !res.writableFinished));
-            let sbx;
-            let extra;
-            try {
-                sbx = await router.create(spec, route);
-            }
-            catch (err) {
-                await hooks.createFailed?.(caller);
-                throw err;
-            }
-            try {
-                if (hungUp)
-                    throw new HttpError(499, "the client closed the connection before the sandbox was ready; it was killed");
-                extra = await hooks.afterCreate?.(caller, sbx, spec);
-            }
-            catch (err) {
-                await sbx.kill().catch(() => { });
-                await hooks.createFailed?.(caller);
-                throw err;
-            }
-            live.set(sbx.id, sbx);
-            return json(res, 201, {
-                id: sbx.id,
-                provider: sbx.provider,
-                size: sbx.size,
-                estimatedHourlyUsd: sbx.estimatedHourlyUsd,
-                listHourlyUsd: sbx.listHourlyUsd,
-                attempts: sbx.attempts,
-                ...(extra ?? {}),
+            return once(req, res, body, async (keepIfHungUp) => {
+                await hooks.beforeCreate?.(caller, spec, route);
+                let sbx;
+                let extra;
+                try {
+                    sbx = await router.create(spec, route);
+                }
+                catch (err) {
+                    await hooks.createFailed?.(caller);
+                    throw err;
+                }
+                try {
+                    if (hungUp && !keepIfHungUp)
+                        throw new HttpError(499, "the client closed the connection before the sandbox was ready; it was killed");
+                    extra = await hooks.afterCreate?.(caller, sbx, spec);
+                }
+                catch (err) {
+                    await sbx.kill().catch(() => { });
+                    await hooks.createFailed?.(caller);
+                    throw err;
+                }
+                live.set(sbx.id, sbx);
+                const made = sbx;
+                return {
+                    status: 201,
+                    body: {
+                        id: sbx.id,
+                        provider: sbx.provider,
+                        size: sbx.size,
+                        estimatedHourlyUsd: sbx.estimatedHourlyUsd,
+                        listHourlyUsd: sbx.listHourlyUsd,
+                        attempts: sbx.attempts,
+                        ...(extra ?? {}),
+                    },
+                    discard: async () => {
+                        live.delete(made.id);
+                        await made.kill().catch(() => { });
+                        await hooks.afterKill?.(caller, made.id);
+                    },
+                };
             });
         }
         const id = parts[2] ? decodeURIComponent(parts[2]) : "";
@@ -220,21 +291,47 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         return json(res, 404, { error: "not found" });
     };
-    const computers = async (req, res, url, parts) => {
+    const computers = async (req, res, url, parts, caller) => {
         if (req.method === "POST" && parts.length === 2) {
-            const { provider, ...spec } = await readJson(req);
-            const c = await router.computer(spec, { provider });
-            return json(res, 201, { ...(await c.info()), id: c.id, nativeId: c.nativeId, provider: c.provider });
+            const body = await readJson(req);
+            const { spec, route } = splitComputerRequest(body);
+            return once(req, res, body, async () => {
+                await hooks.beforeCreateComputer?.(caller, spec);
+                const c = await router.computer(spec, route);
+                let extra;
+                try {
+                    extra = await hooks.afterCreateComputer?.(caller, c);
+                }
+                catch (err) {
+                    await c.delete().catch(() => { });
+                    throw err;
+                }
+                return {
+                    status: 201,
+                    body: { ...(await c.info()), id: c.id, nativeId: c.nativeId, provider: c.provider, estimatedHourlyUsd: c.estimatedHourlyUsd, attempts: c.attempts, ...(extra ?? {}) },
+                };
+            });
         }
         const id = parts[2] ? decodeURIComponent(parts[2]) : "";
         if (!id)
             return json(res, 404, { error: "not found" });
+        if (hooks.owns && !(await hooks.owns(caller, id)))
+            throw new HttpError(404, "no such computer");
         const c = await router.getComputer(id);
         const sub = parts[3];
         if (req.method === "GET" && !sub)
             return json(res, 200, { ...(await c.info()), id, nativeId: c.nativeId });
         if (req.method === "DELETE" && !sub) {
-            await c.delete();
+            try {
+                await c.delete();
+            }
+            catch (err) {
+                if (errorStatus(err) !== 404) {
+                    await hooks.afterDeleteComputer?.(caller, id, { error: err });
+                    throw err;
+                }
+            }
+            await hooks.afterDeleteComputer?.(caller, id);
             return json(res, 200, { id, deleted: true });
         }
         if (req.method === "POST" && sub === "actions") {
@@ -306,6 +403,12 @@ function describeError(err) {
     const code = err instanceof RouterError ? err.code : undefined;
     return { status, body: { error: err?.message ?? String(err), ...(code ? { code } : {}), ...(err?.attempts?.length ? { attempts: err.attempts } : {}) } };
 }
+/** How long an Idempotency-Key is remembered, and how many at most. */
+const IDEMPOTENCY_TTL_MS = 24 * 3600_000;
+const IDEMPOTENCY_MAX = 10_000;
+/** How long a sandbox whose caller hung up (with an Idempotency-Key) waits for a retry to collect it. */
+export const ORPHAN_GRACE_MS = 120_000;
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
 /** The HTTP status for each RouterError code (see RouterErrorCode). */
 export const ERROR_STATUS = {
     bad_request: 400,

package/dist/types.d.ts

@@ -96,7 +96,8 @@ export interface Provider {
     connect(nativeId: string): Promise<ProviderSandbox>;
 }
 export interface Attempt {
-    provider: ProviderId;
+    /** A sandbox provider, or a computer provider (some sell only computers). */
+    provider: ProviderId | (string & {});
     ok: boolean;
     ms: number;
     error?: string;

package/dist/util.d.ts

@@ -43,3 +43,11 @@ export declare function optionalImport<T>(pkg: string, provider: string): Promis
  * (E2B's AuthenticationError, AWS's CredentialsProviderError). Undefined when there's none.
  */
 export declare function errorStatus(err: unknown, depth?: number): number | undefined;
+/**
+ * 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.
+ */
+export declare const SETUP_ERRORS: Set<number>;
+/** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */
+export declare function withDeadline<T>(work: Promise<T>, ms: number, onExpire: () => Error): Promise<T>;

package/dist/util.js

@@ -111,3 +111,24 @@ export function errorStatus(err, depth = 0) {
         return 429;
     return errorStatus(e.cause, depth + 1);
 }
+/**
+ * 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.
+ */
+export const SETUP_ERRORS = new Set([400, 401, 403, 404, 422]);
+/** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */
+export async function withDeadline(work, ms, onExpire) {
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(onExpire()), ms);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([work, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+        work.catch(() => { });
+    }
+}

package/package.json

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