sbox-sdk 0.0.2

package/dist/northflank/index.js

@@ -0,0 +1,265 @@
+/**
+ * `sbox-sdk/northflank` — adapter for Northflank (`@northflank/js-client`).
+ * Northflank is a services platform, so a "sandbox" is a deployment service that
+ * runs a base image with a `sleep infinity` keep-alive command. exec uses
+ * `apiClient.exec.execServiceSession`, which streams stdout/stderr over Node
+ * EventEmitters and resolves an exit code via `waitForCommandResult()`; the
+ * adapter buffers it. There is no per-call cwd/env, so the core folds those into
+ * a `cd … && KEY=v …` wrapper (`perCommandEnvCwd: false`). Filesystem is exec +
+ * base64.
+ *
+ * `pause()` scales the service to zero (volume retained, memory lost),
+ * `resume()` scales it back, `destroy()` deletes the service and its children.
+ * Ports are made public via the service port config and resolved to their public
+ * DNS. Node-only (the SDK uses EventEmitters). Requires the optional peer
+ * dependency `@northflank/js-client`.
+ */
+import { AsyncQueue, base64ToBytes, bytesToBase64, defineProvider, SandboxError, shellQuote as sq, } from "../adapter/index.js";
+export const NORTHFLANK_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: "unsupported",
+    secretsVault: "unsupported",
+    setTimeout: "unsupported",
+    snapshot: "unsupported",
+    ssh: "unsupported",
+    statefulKernel: "unsupported",
+    stdin: "unsupported",
+    stop: "unsupported",
+    streaming: "emulated",
+    volumes: "unsupported",
+};
+const NORTHFLANK_FLAGS = {
+    exitCodeNative: true, // waitForCommandResult() returns the exit code
+    perCommandEnvCwd: false, // execServiceSession has no cwd/env — core wraps it
+    preservesDiskOnStop: false,
+    preservesMemoryOnPause: false, // scale-to-zero loses memory (volume retained)
+    previewModel: "subdomain",
+};
+let cached = null;
+async function loadNorthflank() {
+    if (!cached) {
+        cached = (await import("@northflank/js-client"));
+    }
+    return cached;
+}
+function mapState(state) {
+    switch ((state ?? "").toLowerCase()) {
+        case "running": {
+            return "running";
+        }
+        case "paused": {
+            return "paused";
+        }
+        case "deploying":
+        case "building":
+        case "deploymentongoing": {
+            return "creating";
+        }
+        case "failed":
+        case "unhealthy": {
+            return "error";
+        }
+        default: {
+            return "unknown";
+        }
+    }
+}
+export const northflank = defineProvider((opts) => {
+    const { projectId } = opts;
+    let clientP = null;
+    const getClient = () => {
+        if (!clientP) {
+            clientP = (async () => {
+                const mod = await loadNorthflank();
+                const ctx = new mod.ApiClientInMemoryContextProvider();
+                await ctx.addContext({ name: "sbox", token: opts.token });
+                return new mod.ApiClient(ctx, { throwErrorOnHttpErrorCode: true });
+            })();
+        }
+        return clientP;
+    };
+    const makeHandle = (ref, client) => {
+        const params = { projectId: ref.projectId, serviceId: ref.serviceId };
+        const exec1 = async (cmd) => {
+            const handle = await client.exec.execServiceSession({ parameters: params }, { shell: "sh -c", command: cmd });
+            const out = [];
+            const err = [];
+            handle.stdOut.on("data", (d) => out.push(String(d)));
+            handle.stdErr.on("data", (d) => err.push(String(d)));
+            const result = await handle.waitForCommandResult();
+            return {
+                stdout: out.join(""),
+                stderr: err.join(""),
+                exitCode: result.exitCode ?? 0,
+            };
+        };
+        return {
+            id: ref.serviceId,
+            raw: ref,
+            async getInfo() {
+                const res = await client.get.service({ parameters: params });
+                return {
+                    id: ref.serviceId,
+                    state: mapState(res.data?.status),
+                    provider: "northflank",
+                    metadata: {},
+                    raw: ref,
+                };
+            },
+            async destroy() {
+                await client.delete.service({
+                    parameters: params,
+                    options: { delete_child_objects: true },
+                });
+            },
+            async pause() {
+                await client.pause.service({ parameters: params });
+            },
+            async resume() {
+                await client.resume.service({ parameters: params });
+            },
+            exec(cmd) {
+                const queue = new AsyncQueue();
+                void exec1(cmd)
+                    .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, "northflank")));
+                return {
+                    pid: Promise.resolve(""),
+                    async kill() {
+                        /* execServiceSession is buffered here; no kill handle */
+                    },
+                    [Symbol.asyncIterator]: () => queue.iterator(),
+                };
+            },
+            async readFile(path) {
+                const r = await exec1(`base64 ${sq(path)}`);
+                if (r.exitCode !== 0) {
+                    throw new SandboxError("NotFound", `no such file: '${path}'`, {
+                        provider: "northflank",
+                    });
+                }
+                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.exitCode !== 0) {
+                    throw new SandboxError("Provider", `write failed: '${path}'`, {
+                        provider: "northflank",
+                    });
+                }
+            },
+            async exposePort(port) {
+                await client.update.service.ports({
+                    parameters: params,
+                    data: {
+                        ports: [
+                            {
+                                name: `p${port}`,
+                                internalPort: port,
+                                public: true,
+                                protocol: "HTTP",
+                            },
+                        ],
+                    },
+                });
+                const got = await client.get.service.ports({ parameters: params });
+                const dns = got.data?.ports?.find((p) => p.internalPort === port)?.dns;
+                return { url: dns ? `https://${dns}` : "", port };
+            },
+        };
+    };
+    const provider = {
+        name: "northflank",
+        capabilities: NORTHFLANK_CAPS,
+        flags: NORTHFLANK_FLAGS,
+        async create(spec) {
+            const client = await getClient();
+            const serviceId = spec.name ?? `sandbox-${globalThis.crypto.randomUUID().slice(0, 8)}`;
+            await client.create.service.deployment({
+                parameters: { projectId },
+                data: {
+                    name: serviceId,
+                    billing: { deploymentPlan: opts.deploymentPlan ?? "nf-compute-200" },
+                    deployment: {
+                        instances: 1,
+                        docker: {
+                            configType: "customCommand",
+                            customCommand: "sleep infinity",
+                        },
+                        external: {
+                            imagePath: spec.template ?? opts.image ?? "ubuntu:22.04",
+                        },
+                        storage: {
+                            ephemeralStorage: {
+                                storageSize: opts.ephemeralStorageMB ?? 2048,
+                            },
+                        },
+                    },
+                    runtimeEnvironment: spec.env ?? {},
+                },
+            });
+            const ref = { projectId, serviceId };
+            // Best-effort wait for the service to come up before returning.
+            for (let i = 0; i < 60; i++) {
+                const res = await client.get
+                    .service({ parameters: { projectId, serviceId } })
+                    .catch(() => null);
+                const status = res?.data?.status;
+                if (status === "running") {
+                    break;
+                }
+                if (status === "failed") {
+                    throw new SandboxError("Provider", `service ${serviceId} failed to start`, {
+                        provider: "northflank",
+                    });
+                }
+                await new Promise((r) => setTimeout(r, 2000));
+            }
+            return makeHandle(ref, client);
+        },
+        async connect(id) {
+            const client = await getClient();
+            return makeHandle({ projectId, serviceId: id }, client);
+        },
+        async *list() {
+            const client = await getClient();
+            const res = await client.list.services({ parameters: { projectId } });
+            for (const s of res.data?.services ?? []) {
+                yield {
+                    id: s.id,
+                    state: mapState(s.status),
+                    provider: "northflank",
+                    metadata: {},
+                    raw: { projectId, serviceId: s.id },
+                };
+            }
+        },
+    };
+    return provider;
+});

package/dist/openai/index.d.ts

@@ -0,0 +1,25 @@
+import type { Tool } from "@openai/agents";
+import type { FrameworkAdapter, ToolSetOptions, ToolSpec } from "../agent-tools/types.js";
+import type { Sandbox } from "../internal/types.js";
+export type OpenAIToolOptions = ToolSetOptions;
+/** OpenAI Agents takes tools as an array. */
+export type OpenAIToolSet = Tool[];
+/**
+ * Build OpenAI Agents tools from a live sandbox (capability-gated) or a
+ * pre-built `ToolSpec[]`. Pass the result to `new Agent({ tools })`.
+ */
+export declare function toOpenAITools(source: Sandbox | ToolSpec[], opts?: OpenAIToolOptions): OpenAIToolSet;
+/**
+ * The OpenAI Agents framework adapter for the `ai()` plugin:
+ *
+ * ```ts
+ * import { ai } from "sbox-sdk/ai";
+ * import { openaiAgents } from "sbox-sdk/openai";
+ *
+ * const client = createSandboxClient({ provider: e2b(), plugins: [ai({ framework: openaiAgents() })] });
+ * const sandbox = await client.create();
+ * const agent = new Agent({ name: "coder", tools: sandbox.tools });
+ * ```
+ */
+export declare function openaiAgents(): FrameworkAdapter<OpenAIToolSet>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openai/index.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAI3C,OAAO,KAAK,EACV,gBAAgB,EAEhB,cAAc,EACd,QAAQ,EACT,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAE/C,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,IAAI,EAAE,CAAC;AAanC;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,EAC5B,IAAI,GAAE,iBAAsB,GAC3B,aAAa,CAyBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,gBAAgB,CAAC,aAAa,CAAC,CAK9D"}

package/dist/openai/index.js

@@ -0,0 +1,71 @@
+/**
+ * `sbox-sdk/openai` — OpenAI Agents SDK adapter. Projects the provider-neutral
+ * sandbox tool registry into `tool()` objects, returned as an **array** for
+ * `new Agent({ tools })`.
+ *
+ * Approval: the OpenAI Agents SDK has native human-in-the-loop, so this adapter
+ * wires the policy into `needsApproval` — `"ask"` → the agent surfaces a
+ * `tool_approval_requested` interruption on the `RunResult` (the host resolves
+ * it via `result.state.approve()/reject()` + re-run). `"deny"` is enforced
+ * inside `execute` (returns a message the model reads).
+ *
+ * Schema: our zod schemas are passed directly with `strict: true`; the SDK
+ * converts optional fields to nullable+required (OpenAI strict-mode valid).
+ *
+ * Peer dependency: `@openai/agents` (optional).
+ */
+import { tool } from "@openai/agents";
+import { decide } from "../agent-tools/policy.js";
+import { createSandboxTools } from "../agent-tools/registry.js";
+function resolve(source, opts) {
+    return Array.isArray(source)
+        ? { specs: source }
+        : { sandbox: source, specs: createSandboxTools(source, opts) };
+}
+/**
+ * Build OpenAI Agents tools from a live sandbox (capability-gated) or a
+ * pre-built `ToolSpec[]`. Pass the result to `new Agent({ tools })`.
+ */
+export function toOpenAITools(source, opts = {}) {
+    const { specs, sandbox } = resolve(source, opts);
+    const { policy } = opts;
+    return specs.map((spec) => {
+        const ctx = { sandbox };
+        return tool({
+            name: spec.name,
+            description: spec.description,
+            // `inputSchema` is erased to z.ZodType but is a z.object() at runtime, which
+            // the SDK accepts and converts to a strict JSON schema (verified by the
+            // round-trip test). The SDK's ZodObjectLike param type is modeled on zod 3,
+            // so this type-only cast bridges the boundary; the runtime value is unchanged.
+            parameters: spec.inputSchema,
+            strict: true,
+            // Native HITL: "ask" -> the SDK raises a tool-approval interruption.
+            needsApproval: async (_runContext, input) => decide(spec, input, ctx, policy) === "ask",
+            execute: async (input) => {
+                if (decide(spec, input, ctx, policy) === "deny") {
+                    return `Denied by policy: ${spec.name} is not permitted.`;
+                }
+                return (await spec.execute(input, ctx)).text;
+            },
+        });
+    });
+}
+/**
+ * The OpenAI Agents framework adapter for the `ai()` plugin:
+ *
+ * ```ts
+ * import { ai } from "sbox-sdk/ai";
+ * import { openaiAgents } from "sbox-sdk/openai";
+ *
+ * const client = createSandboxClient({ provider: e2b(), plugins: [ai({ framework: openaiAgents() })] });
+ * const sandbox = await client.create();
+ * const agent = new Agent({ name: "coder", tools: sandbox.tools });
+ * ```
+ */
+export function openaiAgents() {
+    return {
+        build: (sandbox, opts) => toOpenAITools(sandbox, opts),
+        name: "openai",
+    };
+}

package/dist/railway/index.d.ts

@@ -0,0 +1,109 @@
+import type { SandboxProvider } from "../adapter/index.js";
+export interface RailwayOptions {
+    /** Railway API token (falls back to RAILWAY_API_TOKEN in the environment). */
+    token?: string;
+    /** Target environment id (falls back to RAILWAY_ENVIRONMENT_ID). */
+    environmentId?: string;
+    /** Network isolation for new sandboxes (default "ISOLATED"). */
+    networkIsolation?: "ISOLATED" | "PRIVATE";
+}
+export declare const RAILWAY_CAPS: {
+    readonly background: "unsupported";
+    readonly codeInterpreter: "unsupported";
+    readonly egressControl: "unsupported";
+    readonly exposePort: "unsupported";
+    readonly filesUpload: "native";
+    readonly filesWatch: "unsupported";
+    readonly fork: "native";
+    readonly gpu: "unsupported";
+    readonly killProcess: "unsupported";
+    readonly list: "native";
+    readonly metrics: "unsupported";
+    readonly pause: "unsupported";
+    readonly privatePreview: "unsupported";
+    readonly proxiedFetch: "unsupported";
+    readonly pty: "unsupported";
+    readonly region: "unsupported";
+    readonly secretsVault: "unsupported";
+    readonly setTimeout: "unsupported";
+    readonly snapshot: "native";
+    readonly ssh: "unsupported";
+    readonly statefulKernel: "unsupported";
+    readonly stdin: "unsupported";
+    readonly stop: "unsupported";
+    readonly streaming: "native";
+    readonly volumes: "unsupported";
+};
+export type RailwayCaps = typeof RAILWAY_CAPS;
+interface RailwayExecResult {
+    exitCode?: number | null;
+    stdout?: string;
+    stderr?: string;
+}
+interface RailwayFiles {
+    read(path: string, opts?: {
+        format?: "text" | "bytes" | "stream";
+    }): Promise<Uint8Array | string>;
+    write(path: string, content: Uint8Array | string): Promise<void>;
+    list(dir: string): Promise<{
+        name: string;
+        type?: string;
+        isDir?: boolean;
+    }[]>;
+    stat(path: string): Promise<{
+        size?: number;
+        isDir?: boolean;
+        type?: string;
+        mtime?: number;
+    }>;
+    mkdir(dir: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    remove(path: string): Promise<void>;
+}
+interface RailwaySandbox {
+    id?: string;
+    sandboxId?: string;
+    exec(command: string, opts?: {
+        timeoutSec?: number;
+        cwd?: string;
+        env?: Record<string, string>;
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    }): Promise<RailwayExecResult>;
+    files: RailwayFiles;
+    fork(opts?: Record<string, unknown>): Promise<RailwaySandbox>;
+    checkpoint(name: string): Promise<{
+        name?: string;
+        id?: string;
+    } | string>;
+    destroy(): Promise<void>;
+}
+export declare const railway: (opts: RailwayOptions) => SandboxProvider<{
+    readonly background: "unsupported";
+    readonly codeInterpreter: "unsupported";
+    readonly egressControl: "unsupported";
+    readonly exposePort: "unsupported";
+    readonly filesUpload: "native";
+    readonly filesWatch: "unsupported";
+    readonly fork: "native";
+    readonly gpu: "unsupported";
+    readonly killProcess: "unsupported";
+    readonly list: "native";
+    readonly metrics: "unsupported";
+    readonly pause: "unsupported";
+    readonly privatePreview: "unsupported";
+    readonly proxiedFetch: "unsupported";
+    readonly pty: "unsupported";
+    readonly region: "unsupported";
+    readonly secretsVault: "unsupported";
+    readonly setTimeout: "unsupported";
+    readonly snapshot: "native";
+    readonly ssh: "unsupported";
+    readonly statefulKernel: "unsupported";
+    readonly stdin: "unsupported";
+    readonly stop: "unsupported";
+    readonly streaming: "native";
+    readonly volumes: "unsupported";
+}, RailwaySandbox>;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/railway/index.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAUV,eAAe,EAIhB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BS,CAAC;AAEnC,MAAM,MAAM,WAAW,GAAG,OAAO,YAAY,CAAC;AAW9C,UAAU,iBAAiB;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,UAAU,YAAY;IACpB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;KAAE,GAC9C,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAChC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,IAAI,CACF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,CACF,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AACD,UAAU,cAAc;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CACF,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KACpC,GACA,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAC3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA6DD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;kBA6JlB,CAAC"}