sbox-sdk 0.0.2

package/dist/internal/errors.js

@@ -0,0 +1,79 @@
+/**
+ * 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()`.
+ */
+const RETRYABLE_CODES = new Set([
+    "Timeout",
+    "QuotaExceeded",
+    "Provider",
+]);
+export class SandboxError extends Error {
+    code;
+    provider;
+    status;
+    retryable;
+    timedOut;
+    aborted;
+    constructor(code, message, init = {}) {
+        super(`[sbox]${init.provider ? ` [${init.provider}]` : ""} ${message}`, {
+            cause: init.cause,
+        });
+        this.name = "SandboxError";
+        this.code = code;
+        this.provider = init.provider;
+        this.status = init.status;
+        this.retryable = init.retryable ?? RETRYABLE_CODES.has(code);
+        this.timedOut = init.timedOut ?? code === "Timeout";
+        this.aborted = init.aborted ?? false;
+        Error.captureStackTrace?.(this, SandboxError);
+    }
+    /** Coerce any thrown value into a SandboxError (pass-through if already one). */
+    static wrap(err, provider, fallback = "Provider") {
+        if (err instanceof SandboxError) {
+            return err;
+        }
+        if (err instanceof Error && err.name === "AbortError") {
+            return new SandboxError("Timeout", err.message, {
+                aborted: true,
+                cause: err,
+                provider,
+            });
+        }
+        return new SandboxError(fallback, err instanceof Error ? err.message : String(err), { cause: err, provider });
+    }
+}
+/** Thrown synchronously by a namespace facade before any network call. */
+export class NotSupportedError extends SandboxError {
+    feature;
+    constructor(provider, feature) {
+        super("NotSupported", `'${feature}' is not supported by provider '${provider}'`, { provider, retryable: false });
+        this.name = "NotSupportedError";
+        this.feature = feature;
+    }
+}
+export class ProviderNotFoundError extends SandboxError {
+    constructor(name, known = []) {
+        super("ProviderNotFound", `Unknown provider "${name}". Registered: ${known.join(", ") || "(none)"}`);
+        this.name = "ProviderNotFoundError";
+    }
+}
+export class AllProvidersFailedError extends SandboxError {
+    attempts;
+    constructor(attempts) {
+        super("AllProvidersFailed", `all providers failed: ${attempts.map((a) => a.provider).join(", ")}`, { cause: attempts });
+        this.name = "AllProvidersFailedError";
+        this.attempts = attempts;
+    }
+}
+/** Centralized HTTP-status retryability classifier. */
+export function isRetryableStatus(status) {
+    return (status === 408 ||
+        status === 409 ||
+        status === 425 ||
+        status === 429 ||
+        (status !== undefined && status >= 500));
+}
+export function isRetryableError(err) {
+    return err instanceof SandboxError && err.retryable;
+}

package/dist/internal/exec.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Adapts a raw adapter `DriverExec` (an AsyncIterable of output events) into the
+ * public `ExecHandle` — which is simultaneously awaitable (buffered ExecResult)
+ * and async-iterable (live OutputEvent stream), and also exposes byte streams.
+ * A single internal pump drives all consumers, so awaiting and streaming the
+ * same handle never double-consumes the source.
+ */
+import { SandboxError } from "./errors.js";
+import type { DriverExec, ExecHandle } from "./types.js";
+export interface ExecHandleOptions {
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    /** Parse `__sbox_rc=N` out of stdout to synthesize the exit code. */
+    parseExitMarker?: boolean;
+    /** Normalize errors thrown while iterating the source. */
+    mapError?: (err: unknown) => SandboxError;
+}
+export declare function createExecHandle(source: DriverExec, opts?: ExecHandleOptions): ExecHandle;
+//# sourceMappingURL=exec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/internal/exec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EAGX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,YAAY,CAAC;CAC3C;AA0OD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE,iBAAiB,GACvB,UAAU,CAEZ"}

package/dist/internal/exec.js

@@ -0,0 +1,208 @@
+/**
+ * Adapts a raw adapter `DriverExec` (an AsyncIterable of output events) into the
+ * public `ExecHandle` — which is simultaneously awaitable (buffered ExecResult)
+ * and async-iterable (live OutputEvent stream), and also exposes byte streams.
+ * A single internal pump drives all consumers, so awaiting and streaming the
+ * same handle never double-consumes the source.
+ */
+import { SandboxError } from "./errors.js";
+const MARKER_RE = /__sbox_rc=(-?\d+)/;
+const MARKER_STRIP_RE = /\n?__sbox_rc=-?\d+\s*/g;
+class ExecHandleImpl {
+    #source;
+    #opts;
+    #events = [];
+    #wakers = [];
+    #startedPump = false;
+    #done = false;
+    #error = null;
+    #exitCode = 0;
+    #synthExit = 0;
+    #synthesized = false;
+    #resultPromise;
+    #resolveResult;
+    #rejectResult;
+    constructor(source, opts = {}) {
+        this.#source = source;
+        this.#opts = opts;
+        this.#resultPromise = new Promise((res, rej) => {
+            this.#resolveResult = res;
+            this.#rejectResult = rej;
+        });
+    }
+    #notify() {
+        const wakers = this.#wakers;
+        this.#wakers = [];
+        for (const w of wakers) {
+            w();
+        }
+    }
+    #nextTick() {
+        return new Promise((resolve) => this.#wakers.push(resolve));
+    }
+    #ensureStarted() {
+        if (this.#startedPump) {
+            return;
+        }
+        this.#startedPump = true;
+        void this.#pump();
+    }
+    #start() {
+        this.#ensureStarted();
+        return this.#resultPromise;
+    }
+    async #pump() {
+        try {
+            for await (const ev of this.#source) {
+                this.#handle(ev);
+            }
+            this.#finish(null);
+        }
+        catch (error) {
+            this.#finish(error);
+        }
+    }
+    #handle(ev) {
+        if (ev.type === "exit") {
+            this.#exitCode = ev.exitCode;
+            this.#events.push(ev);
+            this.#notify();
+            return;
+        }
+        let { data } = ev;
+        if (ev.type === "stdout" && this.#opts.parseExitMarker) {
+            const m = MARKER_RE.exec(data);
+            if (m && m[1] !== undefined) {
+                this.#synthExit = Number(m[1]);
+                this.#synthesized = true;
+                data = data.replace(MARKER_STRIP_RE, "");
+            }
+        }
+        if (data.length === 0) {
+            return;
+        }
+        this.#events.push({ data, type: ev.type });
+        if (ev.type === "stdout") {
+            this.#opts.onStdout?.(data);
+        }
+        else {
+            this.#opts.onStderr?.(data);
+        }
+        this.#notify();
+    }
+    #finish(err) {
+        this.#done = true;
+        if (err !== null && err !== undefined) {
+            this.#error = this.#opts.mapError
+                ? this.#opts.mapError(err)
+                : SandboxError.wrap(err);
+            this.#rejectResult(this.#error);
+            this.#notify();
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        for (const ev of this.#events) {
+            if (ev.type === "stdout") {
+                stdout += ev.data;
+            }
+            else if (ev.type === "stderr") {
+                stderr += ev.data;
+            }
+        }
+        const result = {
+            exitCode: this.#synthesized ? this.#synthExit : this.#exitCode,
+            stderr,
+            stdout,
+            ...(this.#synthesized ? { exitCodeSynthesized: true } : {}),
+        };
+        this.#resolveResult(result);
+        this.#notify();
+    }
+    // ---- Promise<ExecResult> ----
+    then(onfulfilled, onrejected) {
+        return this.#start().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.#start().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.#start().finally(onfinally);
+    }
+    [Symbol.toStringTag] = "ExecHandle";
+    // ---- AsyncIterable<OutputEvent> ----
+    async *[Symbol.asyncIterator]() {
+        this.#ensureStarted();
+        let i = 0;
+        for (;;) {
+            while (i < this.#events.length) {
+                const ev = this.#events[i];
+                i++;
+                if (ev) {
+                    yield ev;
+                }
+            }
+            if (this.#done) {
+                if (this.#error) {
+                    throw this.#error;
+                }
+                return;
+            }
+            await this.#nextTick();
+        }
+    }
+    // ---- ExecHandle extras ----
+    get pid() {
+        this.#ensureStarted();
+        return this.#source.pid;
+    }
+    #makeStream(kind) {
+        const enc = new TextEncoder();
+        let i = 0;
+        const self = this;
+        return new ReadableStream({
+            async pull(controller) {
+                for (;;) {
+                    while (i < self.#events.length) {
+                        const ev = self.#events[i];
+                        i++;
+                        if (ev && ev.type === kind) {
+                            controller.enqueue(enc.encode(ev.data));
+                            return;
+                        }
+                    }
+                    if (self.#done) {
+                        if (self.#error) {
+                            controller.error(self.#error);
+                        }
+                        else {
+                            controller.close();
+                        }
+                        return;
+                    }
+                    await self.#nextTick();
+                }
+            },
+            start: () => self.#ensureStarted(),
+        });
+    }
+    get stdout() {
+        return this.#makeStream("stdout");
+    }
+    get stderr() {
+        return this.#makeStream("stderr");
+    }
+    async kill(signal) {
+        await this.#source.kill(signal);
+    }
+    async writeStdin(data) {
+        if (!this.#source.writeStdin) {
+            throw new SandboxError("NotSupported", "stdin is not supported");
+        }
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        await this.#source.writeStdin(bytes);
+    }
+}
+export function createExecHandle(source, opts) {
+    return new ExecHandleImpl(source, opts);
+}

package/dist/internal/plugin.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The sandbox plugin system. A plugin augments every sandbox the client builds.
+ * The headline kind is an *AI-provider* plugin (`kind: "ai-provider"`), which
+ * contributes a framework-shaped `tools` property to `sandbox.tools` via
+ * `extend`. The shape of `sandbox.tools` follows whichever AI-provider plugin
+ * is installed — the app never imports a projection function.
+ *
+ * This module is intentionally free of any agent-tools dependency: the per-create
+ * overrides reach a plugin as an opaque `createOptions` bag it interprets itself.
+ */
+import type { Sandbox } from "./types.js";
+/** Standard "merge a union of object types into one intersection" helper. */
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** Passed to `extend`/`onCreate`. Carries the 2nd arg of `client.create`. */
+export interface PluginSetupContext {
+    /** Per-sandbox overrides from `client.create(spec, options)`; plugin-defined. */
+    readonly createOptions?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A sandbox plugin. `Ext` is the typed set of properties it grafts onto the
+ * sandbox object (e.g. `{ tools: Record<string, AISDKTool> }`).
+ */
+export interface SandboxPlugin<Ext extends object = object> {
+    readonly name: string;
+    /** Discriminant. The client enforces AT MOST ONE `"ai-provider"` plugin. */
+    readonly kind?: "ai-provider" | "middleware" | "lifecycle" | "mcp";
+    /** Pure, synchronous projection merged onto the sandbox (keeps build sync). */
+    extend?(sandbox: Sandbox, ctx: PluginSetupContext): Ext;
+    /** Async side-effects, awaited by the client after the sandbox is built. */
+    onCreate?(sandbox: Sandbox & Ext, ctx: PluginSetupContext): void | Promise<void>;
+    /** Runs before the underlying destroy(); flush audit logs, stop servers, … */
+    onDestroy?(sandbox: Sandbox): void | Promise<void>;
+}
+/** The contribution type of a single plugin. */
+export type PluginExt<P> = P extends SandboxPlugin<infer E> ? E : object;
+/** The merged contribution of a tuple of plugins (empty tuple -> `{}`). */
+export type MergePlugins<Ps extends readonly SandboxPlugin[]> = Ps extends readonly [] ? object : UnionToIntersection<PluginExt<Ps[number]>>;
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/internal/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CACnC,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAC3C,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,GAC1B,CAAC,GACD,KAAK,CAAC;AAEV,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,KAAK,CAAC;IACnE,+EAA+E;IAC/E,MAAM,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,GAAG,GAAG,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,CACP,OAAO,EAAE,OAAO,GAAG,GAAG,EACtB,GAAG,EAAE,kBAAkB,GACtB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8EAA8E;IAC9E,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,gDAAgD;AAChD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;AAEzE,2EAA2E;AAC3E,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,SAAS,aAAa,EAAE,IAC1D,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC"}

package/dist/internal/plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tiny runtime probe so the (fetch-only) core can adapt without importing any
+ * `node:` module. Providers that genuinely need Node APIs do their own checks.
+ */
+export type Runtime = "node" | "bun" | "deno" | "workerd" | "unknown";
+export declare function detectRuntime(): Runtime;
+export declare function hasFetch(): boolean;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/internal/runtime.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE,wBAAgB,aAAa,IAAI,OAAO,CAmBvC;AAED,wBAAgB,QAAQ,IAAI,OAAO,CAElC"}

package/dist/internal/runtime.js

@@ -0,0 +1,21 @@
+export function detectRuntime() {
+    const g = globalThis;
+    if (g.Deno) {
+        return "deno";
+    }
+    if (g.Bun) {
+        return "bun";
+    }
+    if (typeof navigator !== "undefined" &&
+        navigator.userAgent === "Cloudflare-Workers") {
+        return "workerd";
+    }
+    const proc = g.process;
+    if (proc?.versions?.node) {
+        return "node";
+    }
+    return "unknown";
+}
+export function hasFetch() {
+    return typeof globalThis.fetch === "function";
+}

package/dist/internal/sandbox.d.ts

@@ -0,0 +1,12 @@
+import type { CapabilityMap } from "./capabilities.js";
+import type { PluginSetupContext, SandboxPlugin } from "./plugin.js";
+import type { Sandbox, SandboxProvider } from "./types.js";
+export interface BuildSandboxBase {
+    fetch: typeof fetch;
+    emulate?: (keyof CapabilityMap)[];
+    defaultMetadata?: Record<string, string>;
+    /** Plugins to graft onto every sandbox (applied here so forks inherit them). */
+    plugins?: readonly SandboxPlugin[];
+}
+export declare function buildSandbox<Caps extends CapabilityMap, Raw>(provider: SandboxProvider<Caps, Raw>, handle: import("./types.js").DriverHandle<Raw>, base: BuildSandboxBase, setup?: PluginSetupContext): Sandbox<Caps, Raw>;
+//# sourceMappingURL=sandbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/internal/sandbox.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAQrE,OAAO,KAAK,EAaV,OAAO,EACP,eAAe,EAIhB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,MAAM,aAAa,CAAC,EAAE,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gFAAgF;IAChF,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACpC;AAED,wBAAgB,YAAY,CAAC,IAAI,SAAS,aAAa,EAAE,GAAG,EAC1D,QAAQ,EAAE,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,EACpC,MAAM,EAAE,OAAO,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,EAC9C,IAAI,EAAE,gBAAgB,EACtB,KAAK,GAAE,kBAAuB,GAC7B,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAoYpB"}