@chengchenccc/sandbox 0.1.1-rc.1

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/** @chengchenccc/sandbox — process-isolated execution of untrusted scripts.
+ *
+ *  A script is a TS/JS module with `export default async (ctx) => output`.
+ *  It runs in a spawned `bun` subprocess with its own temp directory as cwd,
+ *  a minimal environment, a hard timeout (process tree kill), and a JSON
+ *  stdio contract: input on stdin, output on the last stdout line marked
+ *  `__SANDBOX_OUTPUT__`. Callers never share memory, modules, or handles
+ *  with the script.
+ *
+ *  Isolation level: process boundary (crash/resource/timeout isolation,
+ *  no access to host objects). It is NOT a filesystem/network jail — a
+ *  hostile script can still touch the host filesystem like any spawned
+ *  process. Container-level isolation is a deliberate non-goal here. */
+export interface SandboxInput {
+    /** The script source (TS/JS module). Must `export default (ctx) => output`. */
+    code: string;
+    /** JSON-serializable context passed to the script (stdin). */
+    input?: Record<string, unknown>;
+    /** Hard timeout in ms. Default 30_000. Kills the process tree. */
+    timeoutMs?: number;
+    /** Extra env vars merged over the minimal base (PATH/HOME/LANG). */
+    env?: Record<string, string>;
+    /** Persistent dir for the script's files (cwd). Default: a fresh temp dir. */
+    cwd?: string;
+    /** Keep the working dir after the run (default: removed). */
+    keepCwd?: boolean;
+}
+export interface SandboxResult {
+    /** The script's returned value (parsed JSON), or null when it returned nothing. */
+    output: Record<string, unknown> | null;
+    /** Raw stdout (without the output marker line). */
+    stdout: string;
+    /** Raw stderr. */
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+}
+export declare function runInSandbox(input: SandboxInput): Promise<SandboxResult>;
+export declare class SandboxTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+//# 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;;;;;;;;;;;;wEAYwE;AAMxE,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAoCD,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAgD9E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,SAAS,EAAE,MAAM;CAI9B"}

package/dist/index.js

@@ -0,0 +1,108 @@
+/** @chengchenccc/sandbox — process-isolated execution of untrusted scripts.
+ *
+ *  A script is a TS/JS module with `export default async (ctx) => output`.
+ *  It runs in a spawned `bun` subprocess with its own temp directory as cwd,
+ *  a minimal environment, a hard timeout (process tree kill), and a JSON
+ *  stdio contract: input on stdin, output on the last stdout line marked
+ *  `__SANDBOX_OUTPUT__`. Callers never share memory, modules, or handles
+ *  with the script.
+ *
+ *  Isolation level: process boundary (crash/resource/timeout isolation,
+ *  no access to host objects). It is NOT a filesystem/network jail — a
+ *  hostile script can still touch the host filesystem like any spawned
+ *  process. Container-level isolation is a deliberate non-goal here. */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+const BASE_ENV = {
+    PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+    HOME: tmpdir(),
+    LANG: process.env.LANG ?? "en_US.UTF-8",
+};
+/** The wrapper that runs inside the subprocess. It reads ctx from stdin,
+ *  imports the user module, awaits the default export, and prints the
+ *  result as a marked JSON line for the parent to parse. */
+const WRAPPER = `
+const fs = await import("node:fs");
+const path = await import("node:path");
+const inputRaw = fs.readFileSync(0, "utf8");
+let ctx = {};
+try { ctx = JSON.parse(inputRaw || "{}"); } catch { ctx = {}; }
+const mod = await import(path.resolve("./script.ts") + "?t=" + Date.now());
+const fn = mod.default;
+if (typeof fn !== "function") {
+  console.error("sandbox script must export default a function");
+  process.exit(2);
+}
+try {
+  const out = await fn(ctx);
+  if (out !== undefined && out !== null) {
+    process.stdout.write("__SANDBOX_OUTPUT__:" + JSON.stringify(out) + "\\n");
+  }
+} catch (err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(msg);
+  if (err instanceof Error && err.stack) console.error(err.stack);
+  process.exit(1);
+}
+`;
+export async function runInSandbox(input) {
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    const dir = input.cwd ?? mkTempDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "script.ts"), input.code);
+    writeFileSync(join(dir, "__sandbox_main.ts"), WRAPPER);
+    let timedOut = false;
+    try {
+        const proc = Bun.spawn(["bun", "run", join(dir, "__sandbox_main.ts")], {
+            cwd: dir,
+            env: { ...BASE_ENV, ...(input.env ?? {}) },
+            stdin: "pipe",
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        proc.stdin.write(JSON.stringify(input.input ?? {}));
+        proc.stdin.end();
+        const timer = setTimeout(() => {
+            timedOut = true;
+            proc.kill();
+        }, timeoutMs);
+        const [stdout, stderr, exitCode] = await Promise.all([
+            new Response(proc.stdout).text(),
+            new Response(proc.stderr).text(),
+            proc.exited,
+        ]);
+        clearTimeout(timer);
+        const marker = stdout.lastIndexOf("__SANDBOX_OUTPUT__:");
+        let output = null;
+        let cleanStdout = stdout;
+        if (marker !== -1) {
+            const line = stdout.slice(marker + "__SANDBOX_OUTPUT__:".length).trim();
+            cleanStdout = stdout.slice(0, marker).trimEnd();
+            try {
+                output = JSON.parse(line);
+            }
+            catch {
+                output = null;
+            }
+        }
+        if (timedOut) {
+            throw new SandboxTimeoutError(timeoutMs);
+        }
+        return { output, stdout: cleanStdout, stderr, exitCode, timedOut };
+    }
+    finally {
+        if (!input.keepCwd && !input.cwd) {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+export class SandboxTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`sandbox script timed out after ${timeoutMs}ms`);
+        this.name = "SandboxTimeoutError";
+    }
+}
+function mkTempDir() {
+    return resolve(tmpdir(), `sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

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

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

package/dist/index.test.js

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { runInSandbox } from "./index.js";
+test("runs a script and returns its output", async () => {
+    const r = await runInSandbox({
+        code: `export default async (ctx) => ({ echo: ctx.msg, doubled: ctx.n * 2 });`,
+        input: { msg: "hi", n: 21 },
+        timeoutMs: 15_000,
+    });
+    expect(r.exitCode).toBe(0);
+    expect(r.output).toEqual({ echo: "hi", doubled: 42 });
+});
+test("captures stdout and stderr", async () => {
+    const r = await runInSandbox({
+        code: `export default async () => { console.log("out-line"); console.error("err-line"); return { ok: true }; };`,
+        input: {},
+    });
+    expect(r.stdout).toContain("out-line");
+    expect(r.stderr).toContain("err-line");
+    expect(r.output).toEqual({ ok: true });
+});
+test("script error surfaces on stderr with non-zero exit", async () => {
+    const r = await runInSandbox({
+        code: `export default async () => { throw new Error("boom"); };`,
+        input: {},
+    });
+    expect(r.exitCode).not.toBe(0);
+    expect(r.stderr).toContain("boom");
+    expect(r.output).toBeNull();
+});
+test("timeout kills the process", async () => {
+    await expect(runInSandbox({
+        code: `export default async () => { await new Promise(() => {}); };`,
+        input: {},
+        timeoutMs: 1_000,
+    })).rejects.toThrow(/timed out/);
+});
+test("minimal env — no host env leakage by default", async () => {
+    const r = await runInSandbox({
+        code: `export default async () => ({ hasSecret: typeof process.env.SANDBOX_LEAK_TEST !== "undefined" });`,
+        input: {},
+        env: {},
+    });
+    expect(r.output).toEqual({ hasSecret: false });
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@chengchenccc/sandbox",
+  "version": "0.1.1-rc.1",
+  "description": "Process-isolated sandbox for executing untrusted workflow/eval scripts (Bun subprocess, timeout kill, JSON stdio)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "biome check . && eslint .",
+    "test": "bun test --pass-with-no-tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Chengchcc/my-agent-team.git",
+    "directory": "packages/sandbox"
+  }
+}