@sandboxrouter/sdk 0.4.0 → 0.6.0

package/dist/router.d.ts

@@ -1,15 +1,28 @@
-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. */
+export interface Size {
+    vcpu: number;
+    memoryGb: number;
+}
 export interface Candidate {
     provider: ProviderId;
-    /** List price for the spec, USD/hour. What the sandbox is expected to cost at the provider's published rates. */
+    /**
+     * What the sandbox is expected to cost, USD/hour: the provider's list price for this size, times what
+     * it really billed against list price where we measured that (`billedVsList`). The default strategy
+     * ranks by this, and a service reselling sandboxes should charge from it.
+     */
     estimatedHourlyUsd: number;
+    /** The provider's published list price for this size, USD/hour. */
+    listHourlyUsd: number;
+    /** Billed / list-price ratio behind `estimatedHourlyUsd`, when measured (`BILLED_VS_LIST`). */
+    billedVsList?: number;
     /**
-     * List price x what the provider really billed against list price, where that was measured
-     * (`BILLED_VS_LIST`, or `RouterOptions.billedVsList`); the list price otherwise. The default strategy ranks by this.
+     * The size the sandbox gets: the provider's fixed default image size where it has one, else what was
+     * asked for (2 vCPU / 4 GB when nothing was). Some providers round up to their next size.
      */
-    effectiveHourlyUsd: number;
+    size: Size;
     /** Median create time: this router's own recent creates when it has a few, else your `bench` file. */
     medianCreateMs?: number;
     /** Passed the real-account check (as of this release, or `RouterOptions.verified`). */
@@ -48,7 +61,7 @@ export interface RouterOptions {
      * costs money. Default false.
      */
     requireVerified?: boolean;
-    /** Billed / list-price ratio per provider, for the default ranking. Default: `BILLED_VS_LIST` from saved cost runs. */
+    /** Billed / list-price ratio per provider, behind `estimatedHourlyUsd`. Default: the ratios in `BILLED_VS_LIST`, from saved cost runs. */
     billedVsList?: Partial<Record<ProviderId, number>>;
 }
 /** Desktop-only providers. Filled in as adapters are added. */
@@ -92,25 +105,37 @@ 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>;
 }
+/** What a sandbox costs and its size, as the router priced it when it was created. */
+export interface SandboxPrice {
+    /** Expected cost, USD/hour: list price x what the provider really billed against it, where measured. */
+    estimatedHourlyUsd: number;
+    /** The provider's published list price for this size, USD/hour. */
+    listHourlyUsd: number;
+    size: Size;
+}
 export declare class RoutedSandbox {
     readonly provider: ProviderId;
     private box;
     /** Every create attempt, including failed fallbacks. */
     readonly attempts: Attempt[];
-    readonly estimatedHourlyUsd: number;
     private ledger?;
     /** Stable id across processes: `provider:nativeId`. */
     readonly id: string;
+    /** Expected cost, USD/hour (see `Candidate.estimatedHourlyUsd`). Undefined for a handle from `get()` this machine didn't create. */
+    readonly estimatedHourlyUsd?: number;
+    /** The provider's list price for this size, USD/hour. */
+    readonly listHourlyUsd?: number;
+    /** The size it was created at (see `Candidate.size`). */
+    readonly size?: Size;
     constructor(provider: ProviderId, box: ProviderSandbox, 
     /** Every create attempt, including failed fallbacks. */
-    attempts: Attempt[], estimatedHourlyUsd: number, ledger?: Ledger | undefined);
+    attempts: Attempt[], price?: SandboxPrice, ledger?: Ledger | undefined);
     get nativeId(): string;
     /**
      * Run a command. If it outlives `opts.timeoutSeconds` the adapter stops it and this rejects with
@@ -141,5 +166,9 @@ export declare function parseId(id: string): {
 export declare function balanced(list: Candidate[]): Candidate[];
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export declare const DEFAULT_CREATE_TIMEOUT_S = 120;
+/** Seconds a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */
+export declare const DEFAULT_CREATE_DEADLINE_S = 240;
 /** Seconds past a command's timeout before the router stops waiting for the adapter. */
 export declare const EXEC_GRACE_S = 30;
+/** The size a provider gives for a spec: its fixed default image size, else what was asked for. */
+export declare function sizeOf(id: ProviderId, spec?: SandboxSpec): Size;

package/dist/router.js

@@ -1,10 +1,11 @@
-import { CATALOG, accessLabel, hourlyCost, unfit } from "./catalog.js";
+import { CATALOG, DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, fixedSize, 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, 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";
 import { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -128,11 +129,12 @@ export class Router {
     provider(id) {
         const p = this.providers.get(id);
         if (!p)
-            throw new RouterError(`unknown provider: ${id}`);
+            throw new RouterError(`unknown provider: ${id}`, [], "bad_request");
         return p;
     }
     /** The ordered list of providers a create would try, with the reason any are skipped. */
     plan(spec = {}, route = {}) {
+        validate(spec, route);
         const explicit = route.provider ? [].concat(route.provider) : null;
         // Local providers (Docker) are never picked automatically: they always "cost" $0 and isolate
         // less than a cloud micro-VM. Name them explicitly to use them.
@@ -142,15 +144,19 @@ export class Router {
         const bench = speed ? loadBench(this.benchFile) : {};
         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, effectiveHourlyUsd: 0, verified: false, failing: false, skip: "unknown provider" };
+            if (!CATALOG.some((c) => c.id === id)) {
+                return { provider: id, estimatedHourlyUsd: 0, listHourlyUsd: 0, size: { vcpu: 0, memoryGb: 0 }, verified: false, failing: false, skip: "unknown provider" };
+            }
             const p = this.providers.get(id);
             const list = round(hourlyCost(id, spec));
+            const ratio = this.billed[id];
             const live = this.live.get(id);
             const c = {
                 provider: id,
-                estimatedHourlyUsd: list,
-                effectiveHourlyUsd: round(list * (this.billed[id] ?? 1)),
+                estimatedHourlyUsd: round(list * (ratio ?? 1)),
+                listHourlyUsd: list,
+                ...(ratio !== undefined ? { billedVsList: ratio } : {}),
+                size: sizeOf(id, spec),
                 medianCreateMs: speed ? (live && live.length >= LIVE_MIN_SAMPLES ? median(live) : median(bench[id]?.createMs)) : undefined,
                 verified: this.verified.has(id),
                 failing: this.failing.has(id),
@@ -170,15 +176,16 @@ export class Router {
         // depends on who the provider is, only on its price, what it really billed, how fast it started for
         // this router and whether its last real-account check failed. An explicit list keeps the caller's order.
         if (!explicit) {
-            const byPrice = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
+            const byCost = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
+            const byList = (a, b) => a.listHourlyUsd - b.listHourlyUsd || a.provider.localeCompare(b.provider);
             if (strategy === "fastest") {
-                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
+                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byCost(a, b));
             }
             else if (strategy === "cheapest") {
-                list.sort(byPrice);
+                list.sort(byList);
             }
             else if (strategy === "verified") {
-                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byPrice(a, b));
+                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byCost(a, b));
             }
             else {
                 return balanced(list);
@@ -219,41 +226,52 @@ export class Router {
         const plan = this.plan(spec, route);
         const usable = plan.filter((c) => !c.skip);
         if (usable.length === 0)
-            throw new RouterError(this.whyNone(plan, !!route.provider));
+            throw new RouterError(this.whyNone(plan, !!route.provider), [], "no_provider");
+        // Pinned with no fallback: the first provider named, or nothing. Never a different one.
+        if (route.provider && route.fallback === false && plan[0].skip) {
+            throw new RouterError(`${plan[0].provider} can't take this sandbox: ${plan[0].skip}`, [], "no_provider");
+        }
         const attempts = [];
         const tries = route.fallback === false ? usable.slice(0, 1) : usable;
         const limitS = route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S;
+        const deadline = Date.now() + (route.deadlineSeconds ?? DEFAULT_CREATE_DEADLINE_S) * 1000;
         for (const c of tries) {
+            const left = deadline - Date.now();
+            if (left <= 0) {
+                throw new RouterError(`create ran out of time (deadlineSeconds) after trying ${attempts.map((a) => a.provider).join(", ")}: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "timeout");
+            }
             const t0 = Date.now();
             const pending = this.provider(c.provider).create(spec);
+            const waitS = Math.min(limitS, left / 1000);
+            const price = { estimatedHourlyUsd: c.estimatedHourlyUsd, listHourlyUsd: c.listHourlyUsd, size: c.size };
             let timedOut = false;
             try {
-                const box = await withDeadline(pending, limitS * 1000, () => {
+                const box = await withDeadline(pending, waitS * 1000, () => {
                     timedOut = true;
-                    return new ProviderError(c.provider, `create timed out after ${limitS}s`);
+                    return new ProviderError(c.provider, `create timed out after ${Number(waitS.toFixed(1))}s`);
                 });
                 attempts.push({ provider: c.provider, ok: true, ms: Date.now() - t0 });
                 this.observe(c.provider, Date.now() - t0);
-                const sbx = new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd, this.ledger);
-                this.record(sbx, c.estimatedHourlyUsd, spec.timeoutMinutes);
+                const sbx = new RoutedSandbox(c.provider, box, attempts, price, this.ledger);
+                this.record(sbx, price, spec.timeoutMinutes);
                 return sbx;
             }
             catch (err) {
                 // A create that answers after we gave up still made a sandbox: record it, then kill it,
                 // so it can't bill unseen. If the kill fails, the ledger entry is left for `gc`.
                 if (timedOut)
-                    pending.then((late) => this.discard(c.provider, late, c.estimatedHourlyUsd, spec.timeoutMinutes), () => { });
+                    pending.then((late) => this.discard(c.provider, late, price, spec.timeoutMinutes), () => { });
                 const status = errorStatus(err);
                 attempts.push({ provider: c.provider, 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) {
                     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, 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);
+                        `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts, "setup");
                 }
             }
         }
-        throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts);
+        throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "all_failed");
     }
     /** Remember a successful create's time, for the speed tie-break and strategy "fastest". */
     observe(id, ms) {
@@ -263,19 +281,21 @@ export class Router {
             xs.shift();
         this.live.set(id, xs);
     }
-    record(sbx, usdHour, timeoutMinutes) {
+    record(sbx, price, timeoutMinutes) {
         const now = Date.now();
         this.ledger?.open({
             id: sbx.id,
             provider: sbx.provider,
             createdAt: new Date(now).toISOString(),
             expiresAt: new Date(now + (timeoutMinutes ?? 30) * 60_000).toISOString(),
-            usdHour,
+            usdHour: price.estimatedHourlyUsd,
+            listUsdHour: price.listHourlyUsd,
+            size: price.size,
         });
     }
-    discard(provider, box, usdHour, timeoutMinutes) {
-        const sbx = new RoutedSandbox(provider, box, [], usdHour, this.ledger);
-        this.record(sbx, usdHour, timeoutMinutes);
+    discard(provider, box, price, timeoutMinutes) {
+        const sbx = new RoutedSandbox(provider, box, [], price, this.ledger);
+        this.record(sbx, price, timeoutMinutes);
         return sbx.kill().catch(() => { });
     }
     /** Every provider that sells computers (desktops/phones): sandbox providers that do, plus desktop-only ones. */
@@ -289,44 +309,57 @@ 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) {
         const { provider, nativeId } = parseId(id);
         const box = await this.provider(provider).connect(nativeId);
-        return new RoutedSandbox(provider, box, [], round(hourlyCost(provider)), this.ledger);
+        // The price and size come from this machine's ledger when it started the sandbox; otherwise
+        // they're unknown (a guess at the default size would be wrong for anything bigger).
+        const e = this.ledger?.list().find((x) => x.id === id);
+        const price = e && e.listUsdHour !== undefined && e.size ? { estimatedHourlyUsd: e.usdHour, listHourlyUsd: e.listUsdHour, size: e.size } : undefined;
+        return new RoutedSandbox(provider, box, [], price, this.ledger);
     }
 }
 export class RoutedSandbox {
     provider;
     box;
     attempts;
-    estimatedHourlyUsd;
     ledger;
     /** Stable id across processes: `provider:nativeId`. */
     id;
+    /** Expected cost, USD/hour (see `Candidate.estimatedHourlyUsd`). Undefined for a handle from `get()` this machine didn't create. */
+    estimatedHourlyUsd;
+    /** The provider's list price for this size, USD/hour. */
+    listHourlyUsd;
+    /** The size it was created at (see `Candidate.size`). */
+    size;
     constructor(provider, box, 
     /** Every create attempt, including failed fallbacks. */
-    attempts, estimatedHourlyUsd, ledger) {
+    attempts, price, ledger) {
         this.provider = provider;
         this.box = box;
         this.attempts = attempts;
-        this.estimatedHourlyUsd = estimatedHourlyUsd;
         this.ledger = ledger;
         this.id = `${provider}:${box.nativeId}`;
+        this.estimatedHourlyUsd = price?.estimatedHourlyUsd;
+        this.listHourlyUsd = price?.listHourlyUsd;
+        this.size = price?.size;
     }
     get nativeId() {
         return this.box.nativeId;
@@ -357,7 +390,7 @@ export class RoutedSandbox {
     /** Pause, keeping the disk. Resume with router.get(id) or, on Maritime, any call. */
     async pause() {
         if (!this.box.pause)
-            throw new RouterError(`${this.provider} does not support pause; create with require: ["pause"]`);
+            throw new RouterError(`${this.provider} does not support pause; create with require: ["pause"]`, [], "unsupported");
         await this.box.pause();
     }
     get canPause() {
@@ -370,10 +403,10 @@ export class RoutedSandbox {
 export function parseId(id) {
     const i = id.indexOf(":");
     if (i <= 0)
-        throw new RouterError(`bad sandbox id "${id}": expected provider:id`);
+        throw new RouterError(`bad sandbox id "${id}": expected provider:id`, [], "bad_request");
     const provider = id.slice(0, i);
     if (!CATALOG.some((c) => c.id === provider))
-        throw new RouterError(`unknown provider in id: ${provider}`);
+        throw new RouterError(`unknown provider in id: ${provider}`, [], "bad_request");
     return { provider, nativeId: id.slice(i + 1) };
 }
 function round(n) {
@@ -386,14 +419,15 @@ function round(n) {
  * median create time; unknown speed after known), then cheapest, then alphabetical.
  */
 export function balanced(list) {
-    const byCost = (a, b) => a.effectiveHourlyUsd - b.effectiveHourlyUsd || a.provider.localeCompare(b.provider);
+    const byCost = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
     const bySpeed = (a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byCost(a, b);
     const order = (group) => {
         const rest = [...group].sort(byCost);
         const out = [];
         while (rest.length) {
-            const limit = rest[0].effectiveHourlyUsd * (1 + PRICE_TIE);
-            const tie = rest.filter((c) => c.effectiveHourlyUsd <= limit);
+            const limit = rest[0].estimatedHourlyUsd * (1 + PRICE_TIE);
+            // Always take at least the cheapest, so the loop ends whatever the prices are.
+            const tie = rest.filter((c, i) => i === 0 || c.estimatedHourlyUsd <= limit);
             out.push(...tie.sort(bySpeed));
             rest.splice(0, tie.length);
         }
@@ -403,26 +437,11 @@ export function balanced(list) {
 }
 /** 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 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 a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */
+export const DEFAULT_CREATE_DEADLINE_S = 240;
 /** 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,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { Router, type RoutedSandbox } from "./router.js";
-import { type RouteOptions, type SandboxSpec } from "./types.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,
  * the server is single-user: one SANDBOXROUTER_TOKEN, every sandbox reachable by anyone holding it.
@@ -10,16 +11,41 @@ export interface ServerHooks {
     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. */
+    /** Before a sandbox starts. Throw HttpError to refuse (402 out of credit, 429 too many); may edit spec and route. */
     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>;
+    /**
+     * After it started. Return fields to add to the create response (e.g. what the caller is charged). If
+     * this throws, the sandbox is killed and the error returned. Not called when the caller hung up before
+     * the sandbox was ready: that sandbox is killed instead.
+     */
+    afterCreate?(caller: unknown, sbx: RoutedSandbox, spec: SandboxSpec): Promise<Record<string, unknown> | void>;
+    /** A create that passed beforeCreate ended without a sandbox for the caller. Release whatever beforeCreate held. */
+    createFailed?(caller: unknown): Promise<void> | 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. */
+    /**
+     * After DELETE. `error` is set when the provider's kill failed (the sandbox may still be running): the
+     * server answers with the error, but the caller asked for it gone, so stop charging them for it. A kill
+     * of a sandbox the provider no longer has counts as done.
+     */
+    afterKill?(caller: unknown, id: string, outcome?: {
+        error?: Error;
+    }): Promise<void>;
+    /**
+     * /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;
 }
@@ -56,3 +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>;