sbox-sdk 0.0.2

package/dist/beam/index.js

@@ -0,0 +1,222 @@
+/**
+ * `sbox-sdk/beam` — adapter for Beam Cloud sandboxes (`@beamcloud/beam-js`).
+ * A "sandbox" is a Beam sandboxed container (real Linux + coreutils), with
+ * first-class GPU. exec uses `instance.exec(cmd, { cwd, env })` and buffers the
+ * process streams (`streaming` emulated). The SDK's filesystem helpers are
+ * local-path based, so `readFile`/`writeFile` go through exec + base64 (binary
+ * safe, portable). Ports are public SSL endpoints (`exposePort`). `snapshot()`
+ * maps to `instance.snapshot()` and `fork()` snapshots then boots N sandboxes
+ * from it. `setTimeout()` maps to `updateTtl`. Requires the optional peer
+ * dependency `@beamcloud/beam-js`.
+ */
+import { AsyncQueue, base64ToBytes, bytesToBase64, defineProvider, SandboxError, shellQuote as sq, } from "../adapter/index.js";
+export const BEAM_CAPS = {
+    background: "unsupported",
+    codeInterpreter: "unsupported",
+    egressControl: "unsupported",
+    exposePort: "native",
+    filesUpload: "native",
+    filesWatch: "unsupported",
+    fork: "native",
+    gpu: "native",
+    killProcess: "unsupported",
+    list: "unsupported",
+    metrics: "unsupported",
+    pause: "unsupported",
+    privatePreview: "unsupported",
+    proxiedFetch: "unsupported",
+    pty: "unsupported",
+    region: "unsupported",
+    secretsVault: "unsupported",
+    setTimeout: "native",
+    snapshot: "native",
+    ssh: "unsupported",
+    statefulKernel: "unsupported",
+    stdin: "unsupported",
+    stop: "unsupported",
+    streaming: "emulated",
+    volumes: "unsupported",
+};
+const BEAM_FLAGS = {
+    exitCodeNative: true,
+    perCommandEnvCwd: true, // exec accepts { cwd, env }
+    preservesDiskOnStop: false,
+    preservesMemoryOnPause: false,
+    previewModel: "subdomain",
+};
+let cached = null;
+async function loadBeam() {
+    if (!cached) {
+        cached = (await import("@beamcloud/beam-js"));
+    }
+    return cached;
+}
+async function readAll(stream) {
+    if (!stream) {
+        return "";
+    }
+    if (typeof stream === "string") {
+        return stream;
+    }
+    const decode = (c) => typeof c === "string" ? c : new TextDecoder().decode(c);
+    if (typeof stream[Symbol.asyncIterator] === "function") {
+        let s = "";
+        for await (const c of stream) {
+            s += decode(c);
+        }
+        return s;
+    }
+    if (typeof stream.read === "function") {
+        let s = "";
+        for (;;) {
+            const c = await stream.read();
+            if (c === null || c === undefined) {
+                break;
+            }
+            s += decode(c);
+        }
+        return s;
+    }
+    return "";
+}
+export const beam = defineProvider((opts) => {
+    const configure = async () => {
+        const mod = await loadBeam();
+        if (opts.token) {
+            mod.beamOpts.token = opts.token;
+        }
+        if (opts.workspaceId) {
+            mod.beamOpts.workspaceId = opts.workspaceId;
+        }
+        return mod;
+    };
+    // Buffered exec: run the command, drain stdout/stderr, then resolve the code.
+    const runBuffered = async (inst, cmd, options) => {
+        const proc = await inst.exec(cmd, {
+            cwd: options.cwd,
+            env: options.env,
+        });
+        const [stdout, stderr] = await Promise.all([
+            readAll(proc.stdout),
+            readAll(proc.stderr),
+        ]);
+        const exitCode = await proc.wait();
+        return { stdout, stderr, exitCode: exitCode ?? 0 };
+    };
+    const makeHandle = (inst) => {
+        const id = inst.sandboxId();
+        // base64 fs uses a bare exec (no cwd/env) so it is independent of options.
+        const fsExec = (cmd) => runBuffered(inst, cmd, {});
+        return {
+            id,
+            raw: inst,
+            getInfo() {
+                return {
+                    id,
+                    state: "running",
+                    provider: "beam",
+                    metadata: {},
+                    raw: inst,
+                };
+            },
+            async destroy() {
+                await inst.terminate();
+            },
+            async setTimeout(ttlMs) {
+                await inst.updateTtl(Math.max(1, Math.ceil(ttlMs / 1000)));
+            },
+            exec(cmd, options) {
+                const queue = new AsyncQueue();
+                void runBuffered(inst, cmd, options)
+                    .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.exitCode });
+                    queue.close();
+                })
+                    .catch((error) => queue.fail(error instanceof SandboxError
+                    ? error
+                    : SandboxError.wrap(error, "beam")));
+                return {
+                    pid: Promise.resolve(""),
+                    async kill() {
+                        /* buffered exec; use the native process API for control */
+                    },
+                    [Symbol.asyncIterator]: () => queue.iterator(),
+                };
+            },
+            async readFile(path) {
+                const r = await fsExec(`base64 ${sq(path)}`);
+                if (r.exitCode !== 0) {
+                    throw new SandboxError("NotFound", `no such file: '${path}'`, {
+                        provider: "beam",
+                    });
+                }
+                return base64ToBytes(r.stdout);
+            },
+            async writeFile(path, data) {
+                const b64 = bytesToBase64(data);
+                const r = await fsExec(`mkdir -p "$(dirname ${sq(path)})" && printf %s ${sq(b64)} | base64 -d > ${sq(path)}`);
+                if (r.exitCode !== 0) {
+                    throw new SandboxError("Provider", `write failed: '${path}'`, {
+                        provider: "beam",
+                    });
+                }
+            },
+            async exposePort(port) {
+                return { url: await inst.exposePort(port), port };
+            },
+            async snapshot(snapOpts) {
+                const snapshotId = await inst.snapshot();
+                return {
+                    id: snapshotId,
+                    name: snapOpts.name,
+                    provider: "beam",
+                    raw: snapshotId,
+                };
+            },
+            async fork(count) {
+                const snapshotId = await inst.snapshot();
+                const mod = await configure();
+                const forks = await Promise.all(Array.from({ length: count }, () => mod.Sandbox.createFromSnapshot(snapshotId)));
+                return forks.map((f) => makeHandle(f));
+            },
+        };
+    };
+    const provider = {
+        name: "beam",
+        capabilities: BEAM_CAPS,
+        flags: BEAM_FLAGS,
+        async create(spec) {
+            const mod = await configure();
+            const image = spec.template ?? opts.image;
+            const sandbox = new mod.Sandbox({
+                name: spec.name,
+                cpu: spec.resources?.vcpus ?? opts.cpu ?? 1,
+                memory: (spec.resources?.memoryMB
+                    ? `${spec.resources.memoryMB}Mi`
+                    : undefined) ??
+                    opts.memory ??
+                    "1Gi",
+                gpu: spec.resources?.gpu,
+                ports: spec.ports,
+                keepWarmSeconds: spec.ttlMs
+                    ? Math.ceil(spec.ttlMs / 1000)
+                    : undefined,
+                image: image && mod.Image
+                    ? new mod.Image({ baseImage: image })
+                    : undefined,
+            });
+            return makeHandle(await sandbox.create());
+        },
+        async connect(id) {
+            const mod = await configure();
+            return makeHandle(await mod.Sandbox.connect(id));
+        },
+    };
+    return provider;
+});

package/dist/blaxel/index.d.ts

@@ -0,0 +1,125 @@
+import type { SandboxProvider } from "../adapter/index.js";
+export interface BlaxelOptions {
+    /** Blaxel API key (falls back to BL_API_KEY in the environment). */
+    apiKey?: string;
+    /** Blaxel workspace (falls back to BL_WORKSPACE in the environment). */
+    workspace?: string;
+    /** Default sandbox image when a spec omits `template`. */
+    image?: string;
+    /** Default memory (MB) for new sandboxes. */
+    memory?: number;
+    region?: string;
+}
+export declare const BLAXEL_CAPS: {
+    readonly background: "unsupported";
+    readonly codeInterpreter: "unsupported";
+    readonly egressControl: "unsupported";
+    readonly exposePort: "native";
+    readonly filesUpload: "native";
+    readonly filesWatch: "unsupported";
+    readonly fork: "unsupported";
+    readonly gpu: "unsupported";
+    readonly killProcess: "unsupported";
+    readonly list: "native";
+    readonly metrics: "unsupported";
+    readonly pause: "unsupported";
+    readonly privatePreview: "native";
+    readonly proxiedFetch: "unsupported";
+    readonly pty: "unsupported";
+    readonly region: "native";
+    readonly secretsVault: "unsupported";
+    readonly setTimeout: "unsupported";
+    readonly snapshot: "unsupported";
+    readonly ssh: "unsupported";
+    readonly statefulKernel: "unsupported";
+    readonly stdin: "unsupported";
+    readonly stop: "unsupported";
+    readonly streaming: "emulated";
+    readonly volumes: "native";
+};
+export type BlaxelCaps = typeof BLAXEL_CAPS;
+interface BlaxelProcessResult {
+    pid?: string;
+    exitCode?: number;
+    status?: string;
+    logs?: string;
+    stdout?: string;
+}
+interface BlaxelLs {
+    subdirectories?: ({
+        path?: string;
+        name?: string;
+    } | string)[];
+    files?: ({
+        path?: string;
+        name?: string;
+    } | string)[];
+}
+interface BlaxelInstance {
+    metadata?: {
+        name?: string;
+        status?: string;
+    };
+    status?: string;
+    process: {
+        exec(opts: {
+            command: string;
+            workingDir?: string;
+            waitForCompletion?: boolean;
+            timeout?: number;
+        }): Promise<BlaxelProcessResult>;
+        kill(name: string): Promise<void>;
+    };
+    fs: {
+        readBinary(path: string): Promise<Blob | Uint8Array | ArrayBuffer>;
+        writeBinary(path: string, data: Uint8Array): Promise<void>;
+        mkdir(path: string): Promise<void>;
+        ls(path: string): Promise<BlaxelLs>;
+    };
+    previews: {
+        createIfNotExists(opts: {
+            metadata: {
+                name: string;
+            };
+            spec: {
+                port: number;
+                public: boolean;
+                prefixUrl?: string;
+            };
+        }): Promise<{
+            spec?: {
+                url?: string;
+            };
+        }>;
+    };
+    delete(): Promise<void>;
+}
+export declare const blaxel: (opts: BlaxelOptions) => SandboxProvider<{
+    readonly background: "unsupported";
+    readonly codeInterpreter: "unsupported";
+    readonly egressControl: "unsupported";
+    readonly exposePort: "native";
+    readonly filesUpload: "native";
+    readonly filesWatch: "unsupported";
+    readonly fork: "unsupported";
+    readonly gpu: "unsupported";
+    readonly killProcess: "unsupported";
+    readonly list: "native";
+    readonly metrics: "unsupported";
+    readonly pause: "unsupported";
+    readonly privatePreview: "native";
+    readonly proxiedFetch: "unsupported";
+    readonly pty: "unsupported";
+    readonly region: "native";
+    readonly secretsVault: "unsupported";
+    readonly setTimeout: "unsupported";
+    readonly snapshot: "unsupported";
+    readonly ssh: "unsupported";
+    readonly statefulKernel: "unsupported";
+    readonly stdin: "unsupported";
+    readonly stop: "unsupported";
+    readonly streaming: "emulated";
+    readonly volumes: "native";
+}, BlaxelInstance>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/blaxel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blaxel/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EASV,eAAe,EAGhB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BU,CAAC;AAEnC,MAAM,MAAM,UAAU,GAAG,OAAO,WAAW,CAAC;AAW5C,UAAU,mBAAmB;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,UAAU,QAAQ;IAChB,cAAc,CAAC,EAAE,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,EAAE,CAAC;IAC/D,KAAK,CAAC,EAAE,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,EAAE,CAAC;CACvD;AACD,UAAU,cAAc;IACtB,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACP,IAAI,CAAC,IAAI,EAAE;YACT,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;YAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnC,CAAC;IACF,EAAE,EAAE;QACF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,UAAU,GAAG,WAAW,CAAC,CAAC;QACnE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;KACrC,CAAC;IACF,QAAQ,EAAE;QACR,iBAAiB,CAAC,IAAI,EAAE;YACtB,QAAQ,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC;YAC3B,IAAI,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,MAAM,EAAE,OAAO,CAAC;gBAAC,SAAS,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;SAC7D,GAAG,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE;gBAAE,GAAG,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAC,CAAC;KAC1C,CAAC;IACF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AA6DD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoJlB,CAAC"}

package/dist/blaxel/index.js

@@ -0,0 +1,220 @@
+/**
+ * `sbox-sdk/blaxel` — adapter for Blaxel (`@blaxel/core`, `SandboxInstance`).
+ * Blaxel is the "perpetual sandbox" platform: a sandbox stays in standby
+ * indefinitely and resumes in sub-25ms on the next request, so there is no
+ * explicit pause/resume — `destroy()` deletes it. exec is the buffered
+ * `process.exec({ command, waitForCompletion: true })`; it has no per-command env
+ * (only `workingDir`), so the core folds cwd+env into a `cd … && KEY=v …` wrapper
+ * (`perCommandEnvCwd: false`). Filesystem uses the binary-safe `fs.readBinary` /
+ * `fs.writeBinary`; directory ops the core can't get from those are polyfilled via
+ * exec. Ports are preview URLs (`previews.createIfNotExists`, public or private).
+ * Requires the optional peer dependency `@blaxel/core`.
+ */
+import { AsyncQueue, defineProvider, SandboxError } from "../adapter/index.js";
+export const BLAXEL_CAPS = {
+    background: "unsupported",
+    codeInterpreter: "unsupported",
+    egressControl: "unsupported",
+    exposePort: "native",
+    filesUpload: "native",
+    filesWatch: "unsupported",
+    fork: "unsupported",
+    gpu: "unsupported",
+    killProcess: "unsupported",
+    list: "native",
+    metrics: "unsupported",
+    pause: "unsupported",
+    privatePreview: "native",
+    proxiedFetch: "unsupported",
+    pty: "unsupported",
+    region: "native",
+    secretsVault: "unsupported",
+    setTimeout: "unsupported",
+    snapshot: "unsupported",
+    ssh: "unsupported",
+    statefulKernel: "unsupported",
+    stdin: "unsupported",
+    stop: "unsupported",
+    streaming: "emulated",
+    volumes: "native",
+};
+const BLAXEL_FLAGS = {
+    exitCodeNative: true,
+    perCommandEnvCwd: false, // process.exec has no per-call env — core wraps it
+    preservesDiskOnStop: true, // standby preserves disk + memory automatically
+    preservesMemoryOnPause: true,
+    previewModel: "subdomain",
+};
+let cached = null;
+async function loadBlaxel() {
+    if (!cached) {
+        cached = (await import("@blaxel/core"));
+    }
+    return cached;
+}
+function mapState(state) {
+    switch ((state ?? "").toUpperCase()) {
+        case "DEPLOYED":
+        case "RUNNING": {
+            return "running";
+        }
+        case "STANDBY":
+        case "SUSPENDED": {
+            return "paused";
+        }
+        case "DEPLOYING":
+        case "PENDING": {
+            return "creating";
+        }
+        case "DELETED": {
+            return "destroyed";
+        }
+        default: {
+            return "unknown";
+        }
+    }
+}
+async function toBytes(data) {
+    if (data instanceof Uint8Array) {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    return new Uint8Array(await data.arrayBuffer());
+}
+function entryName(e) {
+    if (typeof e === "string") {
+        return e;
+    }
+    return e.name ?? (e.path ? (e.path.split("/").pop() ?? e.path) : "");
+}
+export const blaxel = defineProvider((opts) => {
+    const ensureAuth = () => {
+        if (opts.apiKey) {
+            process.env.BL_API_KEY ??= opts.apiKey;
+        }
+        if (opts.workspace) {
+            process.env.BL_WORKSPACE ??= opts.workspace;
+        }
+    };
+    const makeHandle = (inst) => {
+        const name = inst.metadata?.name ?? "";
+        return {
+            id: name,
+            name,
+            raw: inst,
+            getInfo() {
+                return {
+                    id: name,
+                    name,
+                    state: mapState(inst.metadata?.status ?? inst.status),
+                    provider: "blaxel",
+                    metadata: {},
+                    raw: inst,
+                };
+            },
+            async destroy() {
+                await inst.delete();
+            },
+            exec(cmd) {
+                const queue = new AsyncQueue();
+                void inst.process
+                    .exec({ command: cmd, waitForCompletion: true })
+                    .then((r) => {
+                    const out = r.logs ?? r.stdout ?? "";
+                    if (out) {
+                        queue.push({ type: "stdout", data: out });
+                    }
+                    queue.push({ type: "exit", exitCode: r.exitCode ?? 0 });
+                    queue.close();
+                })
+                    .catch((error) => queue.fail(error instanceof SandboxError
+                    ? error
+                    : SandboxError.wrap(error, "blaxel")));
+                return {
+                    pid: Promise.resolve(""),
+                    async kill() {
+                        /* exec runs with waitForCompletion; no kill handle */
+                    },
+                    [Symbol.asyncIterator]: () => queue.iterator(),
+                };
+            },
+            async readFile(path) {
+                return toBytes(await inst.fs.readBinary(path));
+            },
+            async writeFile(path, data) {
+                await inst.fs.writeBinary(path, data);
+            },
+            async mkdir(path) {
+                await inst.fs.mkdir(path);
+            },
+            async listDir(path) {
+                const ls = await inst.fs.ls(path);
+                const base = path.replace(/\/$/, "");
+                const dirs = (ls.subdirectories ?? []).map((d) => {
+                    const nm = entryName(d);
+                    return { name: nm, path: `${base}/${nm}`, type: "dir" };
+                });
+                const files = (ls.files ?? []).map((f) => {
+                    const nm = entryName(f);
+                    return { name: nm, path: `${base}/${nm}`, type: "file" };
+                });
+                return [...dirs, ...files];
+            },
+            async exposePort(port, portOpts) {
+                const preview = await inst.previews.createIfNotExists({
+                    metadata: { name: `sbox-${port}` },
+                    spec: { port, public: !portOpts.private },
+                });
+                return { url: preview.spec?.url ?? "", port };
+            },
+        };
+    };
+    const provider = {
+        name: "blaxel",
+        capabilities: BLAXEL_CAPS,
+        flags: BLAXEL_FLAGS,
+        async create(spec) {
+            ensureAuth();
+            const mod = await loadBlaxel();
+            const name = spec.name ?? `sbox-${globalThis.crypto.randomUUID().slice(0, 8)}`;
+            const inst = await mod.SandboxInstance.createIfNotExists({
+                name,
+                image: spec.template ?? opts.image ?? "blaxel/prod-base:latest",
+                memory: spec.resources?.memoryMB ?? opts.memory ?? 2048,
+                region: spec.region ?? opts.region,
+                ports: spec.ports?.map((p) => ({ target: p, protocol: "HTTP" })),
+                labels: spec.metadata,
+                ttl: spec.ttlMs ? `${Math.ceil(spec.ttlMs / 1000)}s` : undefined,
+                volumes: spec.volumes?.map((v) => ({
+                    name: v.id,
+                    mountPath: v.mountPath,
+                    readOnly: v.readOnly ?? false,
+                })),
+            });
+            return makeHandle(inst);
+        },
+        async connect(id) {
+            ensureAuth();
+            const mod = await loadBlaxel();
+            return makeHandle(await mod.SandboxInstance.get(id));
+        },
+        async *list() {
+            ensureAuth();
+            const mod = await loadBlaxel();
+            for (const inst of await mod.SandboxInstance.list()) {
+                const name = inst.metadata?.name ?? "";
+                yield {
+                    id: name,
+                    name,
+                    state: mapState(inst.metadata?.status ?? inst.status),
+                    provider: "blaxel",
+                    metadata: {},
+                    raw: inst,
+                };
+            }
+        },
+    };
+    return provider;
+});

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}