sbox-sdk 0.0.2

package/dist/fly/index.js

@@ -0,0 +1,222 @@
+/**
+ * `sbox-sdk/fly` — adapter for the Fly Machines REST API (no SDK; pure fetch, so
+ * it runs anywhere the core does). A "sandbox" is a Fly Machine. exec is the
+ * buffered `/exec` endpoint (no per-command cwd/env — the core folds those into
+ * a `cd … && KEY=v …` wrapper via `perCommandEnvCwd: false`); filesystem is done
+ * via exec + base64. stop() releases compute but the rootfs resets unless a
+ * volume is attached (`preservesDiskOnStop: false` — callers are warned).
+ */
+import { AsyncQueue, base64ToBytes, bytesToBase64, defineProvider, SandboxError, shellQuote as sq, } from "../adapter/index.js";
+export const FLY_CAPS = {
+    background: "unsupported",
+    codeInterpreter: "unsupported",
+    egressControl: "unsupported",
+    exposePort: "native",
+    filesUpload: "native",
+    filesWatch: "unsupported",
+    fork: "unsupported",
+    gpu: "unsupported",
+    killProcess: "unsupported",
+    list: "native",
+    metrics: "unsupported",
+    pause: "native",
+    privatePreview: "unsupported",
+    proxiedFetch: "unsupported",
+    pty: "unsupported",
+    region: "native",
+    secretsVault: "unsupported",
+    setTimeout: "unsupported",
+    snapshot: "unsupported",
+    ssh: "unsupported",
+    statefulKernel: "unsupported",
+    stdin: "unsupported",
+    stop: "native",
+    streaming: "emulated",
+    volumes: "unsupported",
+};
+const FLY_FLAGS = {
+    exitCodeNative: true,
+    perCommandEnvCwd: false, // /exec has no per-call cwd/env — core wraps `cd && KEY=v`
+    preservesDiskOnStop: false, // rootfs resets on stop unless a volume is attached
+    preservesMemoryOnPause: true, // suspend preserves memory
+    previewModel: "subdomain",
+};
+function mapStatus(s) {
+    if (s === 404) {
+        return "NotFound";
+    }
+    if (s === 401 || s === 403) {
+        return "Unauthorized";
+    }
+    if (s === 429) {
+        return "QuotaExceeded";
+    }
+    if (s === 408) {
+        return "Timeout";
+    }
+    return "Provider";
+}
+export const fly = defineProvider((opts) => {
+    const base = opts.apiBaseUrl ?? "https://api.machines.dev/v1";
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const app = opts.appName;
+    async function api(method, path, body) {
+        const res = await fetchImpl(`${base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${opts.apiToken}`,
+                "content-type": "application/json",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new SandboxError(mapStatus(res.status), `fly ${method} ${path} -> ${res.status} ${text}`, {
+                provider: "fly",
+                status: res.status,
+                retryable: res.status === 429 || res.status >= 500,
+            });
+        }
+        const ct = res.headers.get("content-type") ?? "";
+        return (ct.includes("json") ? await res.json() : await res.text());
+    }
+    const makeHandle = (machine) => {
+        const { id } = machine;
+        const exec1 = (cmd, timeoutMs) => api("POST", `/apps/${app}/machines/${id}/exec`, {
+            command: ["sh", "-c", cmd],
+            timeout: timeoutMs ? Math.ceil(timeoutMs / 1000) : undefined,
+        });
+        return {
+            id,
+            raw: machine,
+            getInfo() {
+                return {
+                    id,
+                    state: mapState(machine.state),
+                    provider: "fly",
+                    metadata: {},
+                    raw: machine,
+                };
+            },
+            async destroy() {
+                await api("DELETE", `/apps/${app}/machines/${id}?force=true`);
+            },
+            async stop() {
+                await api("POST", `/apps/${app}/machines/${id}/stop`);
+            },
+            async pause() {
+                await api("POST", `/apps/${app}/machines/${id}/suspend`);
+            },
+            async resume() {
+                await api("POST", `/apps/${app}/machines/${id}/start`);
+            },
+            exec(cmd, options) {
+                const queue = new AsyncQueue();
+                void exec1(cmd, options.timeoutMs)
+                    .then((r) => {
+                    if (r.stdout) {
+                        queue.push({ type: "stdout", data: r.stdout });
+                    }
+                    if (r.stderr) {
+                        queue.push({ type: "stderr", data: r.stderr });
+                    }
+                    queue.push({ type: "exit", exitCode: r.exit_code ?? 0 });
+                    queue.close();
+                })
+                    .catch((error) => queue.fail(error instanceof SandboxError
+                    ? error
+                    : SandboxError.wrap(error, "fly")));
+                return {
+                    pid: Promise.resolve(""),
+                    async kill() {
+                        /* /exec is buffered; no kill handle */
+                    },
+                    [Symbol.asyncIterator]: () => queue.iterator(),
+                };
+            },
+            async readFile(path) {
+                const r = await exec1(`base64 ${sq(path)}`);
+                if ((r.exit_code ?? 1) !== 0) {
+                    throw new SandboxError("NotFound", `no such file: '${path}'`, {
+                        provider: "fly",
+                    });
+                }
+                return base64ToBytes(r.stdout ?? "");
+            },
+            async writeFile(path, data) {
+                const b64 = bytesToBase64(data);
+                const r = await exec1(`mkdir -p "$(dirname ${sq(path)})" && printf %s ${sq(b64)} | base64 -d > ${sq(path)}`);
+                if ((r.exit_code ?? 1) !== 0) {
+                    throw new SandboxError("Provider", `write failed: '${path}'`, {
+                        provider: "fly",
+                    });
+                }
+            },
+            exposePort(port) {
+                return { url: opts.appDomain ?? `https://${app}.fly.dev`, port };
+            },
+        };
+    };
+    const provider = {
+        name: "fly",
+        capabilities: FLY_CAPS,
+        flags: FLY_FLAGS,
+        async create(spec) {
+            const machine = await api("POST", `/apps/${app}/machines`, {
+                region: spec.region ?? opts.region,
+                config: {
+                    image: spec.template ?? opts.image ?? "ubuntu:22.04",
+                    env: spec.env,
+                    auto_destroy: false,
+                    guest: {
+                        cpus: spec.resources?.vcpus ?? 1,
+                        memory_mb: spec.resources?.memoryMB ?? 256,
+                        cpu_kind: "shared",
+                    },
+                },
+            });
+            // Best-effort wait for the machine to reach 'started'.
+            await api("GET", `/apps/${app}/machines/${machine.id}/wait?state=started&timeout=60`).catch(() => { });
+            return makeHandle(machine);
+        },
+        async connect(id) {
+            return makeHandle(await api("GET", `/apps/${app}/machines/${id}`));
+        },
+        async *list() {
+            const machines = await api("GET", `/apps/${app}/machines`);
+            for (const m of machines) {
+                yield {
+                    id: m.id,
+                    state: mapState(m.state),
+                    provider: "fly",
+                    metadata: {},
+                    raw: m,
+                };
+            }
+        },
+    };
+    return provider;
+});
+function mapState(state) {
+    switch (state) {
+        case "started": {
+            return "running";
+        }
+        case "stopped": {
+            return "stopped";
+        }
+        case "suspended": {
+            return "paused";
+        }
+        case "created":
+        case "starting": {
+            return "creating";
+        }
+        case "destroyed": {
+            return "destroyed";
+        }
+        default: {
+            return "unknown";
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * sbox-sdk — one unified SDK for agent sandbox providers.
+ *
+ * Pick a provider by importing its adapter from a subpath and passing it in:
+ *
+ * ```ts
+ * import { createSandboxClient } from "sbox-sdk";
+ * import { e2b } from "sbox-sdk/e2b";
+ *
+ * const client = createSandboxClient({ provider: e2b({ apiKey }) });
+ * const sandbox = await client.create({ template: "python-3.12" });
+ * const { stdout } = await sandbox.commands.run("echo hi");
+ * ```
+ */
+export { createSandboxClient } from "./internal/client.js";
+export { SandboxError, NotSupportedError, ProviderNotFoundError, AllProvidersFailedError, isRetryableError, isRetryableStatus, } from "./internal/errors.js";
+export type { SandboxErrorCode, SandboxErrorInit, ProviderAttempt, } from "./internal/errors.js";
+export type { CapabilityLevel, CapabilityMap, CapabilityName, CapabilityFlags, Capabilities, Gated, PreviewModel, } from "./internal/capabilities.js";
+export type * from "./internal/types.js";
+export type { SandboxPlugin, PluginSetupContext, MergePlugins, } from "./internal/plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,KAAK,EACL,YAAY,GACb,MAAM,4BAA4B,CAAC;AAEpC,mBAAmB,qBAAqB,CAAC;AAEzC,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,GACb,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * sbox-sdk — one unified SDK for agent sandbox providers.
+ *
+ * Pick a provider by importing its adapter from a subpath and passing it in:
+ *
+ * ```ts
+ * import { createSandboxClient } from "sbox-sdk";
+ * import { e2b } from "sbox-sdk/e2b";
+ *
+ * const client = createSandboxClient({ provider: e2b({ apiKey }) });
+ * const sandbox = await client.create({ template: "python-3.12" });
+ * const { stdout } = await sandbox.commands.run("echo hi");
+ * ```
+ */
+export { createSandboxClient } from "./internal/client.js";
+export { SandboxError, NotSupportedError, ProviderNotFoundError, AllProvidersFailedError, isRetryableError, isRetryableStatus, } from "./internal/errors.js";

package/dist/internal/capabilities.d.ts

@@ -0,0 +1,57 @@
+export type CapabilityLevel = "native" | "emulated" | "unsupported";
+/** Static, declarative table per provider. Drives type-level + runtime gating. */
+export interface CapabilityMap {
+    list: CapabilityLevel;
+    stop: CapabilityLevel;
+    pause: CapabilityLevel;
+    setTimeout: CapabilityLevel;
+    background: CapabilityLevel;
+    streaming: CapabilityLevel;
+    killProcess: CapabilityLevel;
+    pty: CapabilityLevel;
+    stdin: CapabilityLevel;
+    filesWatch: CapabilityLevel;
+    filesUpload: CapabilityLevel;
+    codeInterpreter: CapabilityLevel;
+    statefulKernel: CapabilityLevel;
+    exposePort: CapabilityLevel;
+    privatePreview: CapabilityLevel;
+    egressControl: CapabilityLevel;
+    ssh: CapabilityLevel;
+    proxiedFetch: CapabilityLevel;
+    snapshot: CapabilityLevel;
+    fork: CapabilityLevel;
+    volumes: CapabilityLevel;
+    gpu: CapabilityLevel;
+    region: CapabilityLevel;
+    secretsVault: CapabilityLevel;
+    metrics: CapabilityLevel;
+}
+export type CapabilityName = keyof CapabilityMap;
+export type PreviewModel = "subdomain" | "tunnel" | "declaredPorts" | "wildcardDNS" | "ip" | "none";
+/** Behavioral flags that aren't present/absent — they change semantics. */
+export interface CapabilityFlags {
+    preservesMemoryOnPause: boolean;
+    preservesDiskOnStop: boolean;
+    /** false => core wraps exec in `sh -c 'cd <cwd> && KEY=v <cmd>'`. */
+    perCommandEnvCwd: boolean;
+    /** false => core synthesizes exit code via `; echo __sbox_rc=$?`. */
+    exitCodeNative: boolean;
+    previewModel: PreviewModel;
+}
+/** Runtime read-model surfaced on every sandbox + client. */
+export interface Capabilities {
+    readonly map: Readonly<CapabilityMap>;
+    readonly flags: Readonly<CapabilityFlags>;
+}
+/** Gated sub-API: the real interface when supported/emulated, else `undefined`. */
+export type Gated<L extends CapabilityLevel, API> = L extends "unsupported" ? undefined : API;
+/** A baseline map of all-`unsupported`, for providers to spread overrides onto. */
+export declare function baseCapabilities(): CapabilityMap;
+export declare function defaultFlags(overrides?: Partial<CapabilityFlags>): CapabilityFlags;
+/** Build a frozen runtime read-model from a provider's static declaration. */
+export declare function freezeCapabilities(map: CapabilityMap, flags: CapabilityFlags): Capabilities;
+export declare function isCapable(caps: Capabilities, name: CapabilityName): boolean;
+/** Throw NotSupportedError up front if a capability is unsupported. */
+export declare function assertCapability(provider: string, caps: Capabilities, name: CapabilityName, feature?: string): void;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/internal/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/internal/capabilities.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;AAEpE,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAE5B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,eAAe,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAE5B,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,eAAe,CAAC;IAC3B,WAAW,EAAE,eAAe,CAAC;IAC7B,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;IAEvB,UAAU,EAAE,eAAe,CAAC;IAC5B,WAAW,EAAE,eAAe,CAAC;IAE7B,eAAe,EAAE,eAAe,CAAC;IACjC,cAAc,EAAE,eAAe,CAAC;IAEhC,UAAU,EAAE,eAAe,CAAC;IAC5B,cAAc,EAAE,eAAe,CAAC;IAChC,aAAa,EAAE,eAAe,CAAC;IAC/B,GAAG,EAAE,eAAe,CAAC;IACrB,YAAY,EAAE,eAAe,CAAC;IAE9B,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;IAEzB,GAAG,EAAE,eAAe,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;IACxB,YAAY,EAAE,eAAe,CAAC;IAC9B,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,QAAQ,GACR,eAAe,GACf,aAAa,GACb,IAAI,GACJ,MAAM,CAAC;AAEX,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,sBAAsB,EAAE,OAAO,CAAC;IAChC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,qEAAqE;IACrE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;CAC3C;AAED,mFAAmF;AACnF,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,eAAe,EAAE,GAAG,IAAI,CAAC,SAAS,aAAa,GACvE,SAAS,GACT,GAAG,CAAC;AAsCR,mFAAmF;AACnF,wBAAgB,gBAAgB,IAAI,aAAa,CAMhD;AAED,wBAAgB,YAAY,CAC1B,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GACvC,eAAe,CAEjB;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,eAAe,GACrB,YAAY,CAKd;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAE3E;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,MAAa,GACrB,IAAI,CAIN"}

package/dist/internal/capabilities.js

@@ -0,0 +1,68 @@
+/**
+ * The single source of truth for what a provider can do. Each provider declares
+ * a static `CapabilityMap` literal; from it we derive (A) type-level gating via
+ * `Gated<>`, (B) the runtime read-model on `sandbox.capabilities`, and (C)
+ * fail-fast enforcement via `assertCapability`.
+ */
+import { NotSupportedError } from "./errors.js";
+const ALL_CAPABILITY_NAMES = [
+    "list",
+    "stop",
+    "pause",
+    "setTimeout",
+    "background",
+    "streaming",
+    "killProcess",
+    "pty",
+    "stdin",
+    "filesWatch",
+    "filesUpload",
+    "codeInterpreter",
+    "statefulKernel",
+    "exposePort",
+    "privatePreview",
+    "egressControl",
+    "ssh",
+    "proxiedFetch",
+    "snapshot",
+    "fork",
+    "volumes",
+    "gpu",
+    "region",
+    "secretsVault",
+    "metrics",
+];
+const DEFAULT_FLAGS = {
+    exitCodeNative: true,
+    perCommandEnvCwd: true,
+    preservesDiskOnStop: false,
+    preservesMemoryOnPause: false,
+    previewModel: "none",
+};
+/** A baseline map of all-`unsupported`, for providers to spread overrides onto. */
+export function baseCapabilities() {
+    const map = {};
+    for (const name of ALL_CAPABILITY_NAMES) {
+        map[name] = "unsupported";
+    }
+    return map;
+}
+export function defaultFlags(overrides = {}) {
+    return { ...DEFAULT_FLAGS, ...overrides };
+}
+/** Build a frozen runtime read-model from a provider's static declaration. */
+export function freezeCapabilities(map, flags) {
+    return {
+        flags: Object.freeze({ ...flags }),
+        map: Object.freeze({ ...map }),
+    };
+}
+export function isCapable(caps, name) {
+    return caps.map[name] !== "unsupported";
+}
+/** Throw NotSupportedError up front if a capability is unsupported. */
+export function assertCapability(provider, caps, name, feature = name) {
+    if (caps.map[name] === "unsupported") {
+        throw new NotSupportedError(provider, feature);
+    }
+}

package/dist/internal/client.d.ts

@@ -0,0 +1,9 @@
+import type { CapabilityMap } from "./capabilities.js";
+import type { MergePlugins, SandboxPlugin } from "./plugin.js";
+import type { ClientOptions, SandboxClient, SandboxProvider } from "./types.js";
+export declare function createSandboxClient(): SandboxClient;
+export declare function createSandboxClient<Caps extends CapabilityMap, Raw, const Ps extends readonly SandboxPlugin[] = []>(options: ClientOptions<Caps, Raw> & {
+    provider: SandboxProvider<Caps, Raw>;
+    plugins?: Ps;
+}): SandboxClient<Caps, Raw, MergePlugins<Ps>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/internal/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/internal/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,KAAK,EAEV,aAAa,EAIb,aAAa,EAEb,eAAe,EAEhB,MAAM,YAAY,CAAC;AAepB,wBAAgB,mBAAmB,IAAI,aAAa,CAAC;AACrD,wBAAgB,mBAAmB,CACjC,IAAI,SAAS,aAAa,EAC1B,GAAG,EACH,KAAK,CAAC,EAAE,SAAS,SAAS,aAAa,EAAE,GAAG,EAAE,EAE9C,OAAO,EAAE,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG;IAClC,QAAQ,EAAE,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,EAAE,CAAC;CACd,GACA,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/internal/client.js

@@ -0,0 +1,126 @@
+import { memory } from "../memory/index.js";
+/**
+ * `createSandboxClient` — the single entry point. Owns provider selection
+ * (instance, or the in-memory default), idempotency-aware retry + fallback,
+ * lifecycle hooks, and disposal. The router is the only caller of providers.
+ */
+import { freezeCapabilities } from "./capabilities.js";
+import { AllProvidersFailedError, NotSupportedError, SandboxError, } from "./errors.js";
+import { buildSandbox } from "./sandbox.js";
+function defaultShouldRetry(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "retryable" in err &&
+        err.retryable === true);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createSandboxClient(options) {
+    const provider = options?.provider ?? memory();
+    const fetchImpl = options?.fetch ?? globalThis.fetch;
+    const retry = { retries: 2, ...options?.retry };
+    const fallback = options?.fallback ?? [];
+    const hooks = options?.hooks;
+    const plugins = options?.plugins ?? [];
+    const aiProviders = plugins.filter((p) => p.kind === "ai-provider");
+    if (aiProviders.length > 1) {
+        throw new SandboxError("Validation", `a client supports one AI-provider plugin, got ${aiProviders.length} (${aiProviders
+            .map((p) => p.name)
+            .join(", ")}). Use the standalone toXTools(sandbox) helpers for multiple frameworks.`);
+    }
+    const caps = freezeCapabilities(provider.capabilities, provider.flags);
+    const base = {
+        defaultMetadata: options?.defaultMetadata,
+        emulate: options?.emulate,
+        fetch: fetchImpl,
+        plugins,
+    };
+    const mkCtx = (attempt, signal, idempotencyKey) => ({
+        attempt,
+        fetch: fetchImpl,
+        idempotencyKey,
+        metadata: options?.defaultMetadata,
+        signal,
+    });
+    const backoff = (n) => Math.min(100 * 2 ** (n - 1), 2000);
+    const withRetry = async (fn) => {
+        const max = retry.retries ?? 2;
+        let lastErr;
+        for (let attempt = 1; attempt <= max + 1; attempt++) {
+            try {
+                return await fn(attempt);
+            }
+            catch (error) {
+                lastErr = error;
+                await hooks?.onError?.(error, attempt);
+                const should = (retry.shouldRetry ?? defaultShouldRetry)(error, attempt);
+                if (!should || attempt > max) {
+                    throw error;
+                }
+                await sleep((retry.delayMs ?? backoff)(attempt, error));
+            }
+        }
+        throw lastErr instanceof Error
+            ? lastErr
+            : new SandboxError("Provider", String(lastErr));
+    };
+    const client = {
+        get capabilities() {
+            return caps;
+        },
+        async connect(id) {
+            const handle = await withRetry((attempt) => Promise.resolve(provider.connect(id, mkCtx(attempt))));
+            const sandbox = buildSandbox(provider, handle, base);
+            for (const pl of plugins) {
+                await pl.onCreate?.(sandbox, {});
+            }
+            return sandbox;
+        },
+        async create(spec = {}, createOptions) {
+            const idem = spec.idempotencyKey ?? globalThis.crypto.randomUUID();
+            await hooks?.beforeCreate?.(spec);
+            // Only fall back across providers when the caller supplied an idempotency
+            // key — otherwise a retried create could orphan a second VM.
+            const canFallback = !!spec.idempotencyKey && fallback.length > 0;
+            const chain = canFallback
+                ? [provider, ...fallback]
+                : [provider];
+            const attempts = [];
+            for (const p of chain) {
+                try {
+                    const handle = await withRetry((attempt) => Promise.resolve(p.create({
+                        ...spec,
+                        metadata: { ...options?.defaultMetadata, ...spec.metadata },
+                    }, mkCtx(attempt, spec.signal, idem))));
+                    await hooks?.afterCreate?.({ id: handle.id, provider: p.name });
+                    const sandbox = buildSandbox(p, handle, base, { createOptions });
+                    for (const pl of plugins) {
+                        await pl.onCreate?.(sandbox, { createOptions });
+                    }
+                    return sandbox;
+                }
+                catch (error) {
+                    attempts.push({ error, provider: p.name });
+                }
+            }
+            if (attempts.length === 1) {
+                throw attempts[0].error;
+            }
+            throw new AllProvidersFailedError(attempts);
+        },
+        async dispose() {
+            await provider.dispose?.();
+        },
+        async *list(filter) {
+            if (!provider.list) {
+                throw new NotSupportedError(provider.name, "list");
+            }
+            yield* provider.list(filter, mkCtx(1));
+        },
+        get provider() {
+            return provider.name;
+        },
+    };
+    return client;
+}

package/dist/internal/encoding.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Encoding helpers shared by adapters that move bytes over text channels
+ * (exec + base64). Web-standard only (atob/btoa) so they work on Node, Bun,
+ * Deno, and Workers. (For shell quoting, use `shellQuote` from the adapter kit.)
+ */
+export declare function bytesToBase64(b: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/internal/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/internal/encoding.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAMnD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOrD"}

package/dist/internal/encoding.js

@@ -0,0 +1,20 @@
+/**
+ * Encoding helpers shared by adapters that move bytes over text channels
+ * (exec + base64). Web-standard only (atob/btoa) so they work on Node, Bun,
+ * Deno, and Workers. (For shell quoting, use `shellQuote` from the adapter kit.)
+ */
+export function bytesToBase64(b) {
+    let s = "";
+    for (const x of b) {
+        s += String.fromCodePoint(x);
+    }
+    return btoa(s);
+}
+export function base64ToBytes(b64) {
+    const bin = atob(b64.replace(/\s/g, ""));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) {
+        out[i] = bin.codePointAt(i) ?? 0;
+    }
+    return out;
+}

package/dist/internal/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One normalized error taxonomy for every provider. Providers must never leak
+ * their native SDK errors past the adapter boundary — they route through
+ * `mapError` or `SandboxError.wrap()`.
+ */
+export type SandboxErrorCode = "NotFound" | "Unauthorized" | "Timeout" | "QuotaExceeded" | "NotSupported" | "Conflict" | "ProviderNotFound" | "Validation" | "AllProvidersFailed" | "Provider";
+export interface SandboxErrorInit {
+    provider?: string;
+    status?: number;
+    cause?: unknown;
+    retryable?: boolean;
+    timedOut?: boolean;
+    aborted?: boolean;
+}
+export declare class SandboxError extends Error {
+    readonly code: SandboxErrorCode;
+    readonly provider?: string;
+    readonly status?: number;
+    readonly retryable: boolean;
+    readonly timedOut: boolean;
+    readonly aborted: boolean;
+    constructor(code: SandboxErrorCode, message: string, init?: SandboxErrorInit);
+    /** Coerce any thrown value into a SandboxError (pass-through if already one). */
+    static wrap(err: unknown, provider?: string, fallback?: SandboxErrorCode): SandboxError;
+}
+/** Thrown synchronously by a namespace facade before any network call. */
+export declare class NotSupportedError extends SandboxError {
+    readonly feature: string;
+    constructor(provider: string, feature: string);
+}
+export declare class ProviderNotFoundError extends SandboxError {
+    constructor(name: string, known?: string[]);
+}
+export interface ProviderAttempt {
+    provider: string;
+    error: unknown;
+}
+export declare class AllProvidersFailedError extends SandboxError {
+    readonly attempts: ProviderAttempt[];
+    constructor(attempts: ProviderAttempt[]);
+}
+/** Centralized HTTP-status retryability classifier. */
+export declare function isRetryableStatus(status?: number): boolean;
+export declare function isRetryableError(err: unknown): err is SandboxError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/internal/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,cAAc,GACd,SAAS,GACT,eAAe,GACf,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,YAAY,GACZ,oBAAoB,GACpB,UAAU,CAAC;AAQf,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAGxB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,gBAAqB;IAe7B,iFAAiF;IACjF,MAAM,CAAC,IAAI,CACT,GAAG,EAAE,OAAO,EACZ,QAAQ,CAAC,EAAE,MAAM,EACjB,QAAQ,GAAE,gBAA6B,GACtC,YAAY;CAiBhB;AAED,0EAA0E;AAC1E,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAS9C;AAED,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,EAAO;CAO/C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;gBACzB,QAAQ,EAAE,eAAe,EAAE;CASxC;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY,CAElE"}