kern-sandbox 0.1.2 → 0.1.4

package/README.md

@@ -77,6 +77,7 @@ const r = await kern.runCode("console.log([1,2,3].map(x => x * x))", {
 | `success` | `true` iff `exitCode === 0` **and** no sandbox fault |
 | `fault` | a sandbox event, or `null`. `{ type, message }` |
 | `files` | files created/modified in the workspace this call |
+| `results` | rich mime-typed values (`Result[]`): last expression, `display()`, matplotlib figures |
 | `truncated` | output hit the cap and overflow was discarded |
 
 A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it is a normal result.
@@ -134,19 +135,28 @@ new Sandbox({
 });
 ```
 
-## Charts, live output, and checkpoints
+## Charts, rich results, live output, and checkpoints
 
-**Charts / artifacts (the "code interpreter" pattern).** No Jupyter kernel: have the code WRITE the
-artifact to the workspace, then read it back with `readFile`.
+**Rich results (the "code interpreter" pattern).** `runCode` runs Python by default, and like a
+Jupyter/E2B cell it captures rich, mime-typed values into `result.results` (a list of `Result`) with
+**no Jupyter kernel**: the value of the code's **last bare expression**, every **`display(obj)`** call,
+and **every open matplotlib figure automatically** (no `savefig`). Accessors: `.png`/`.jpeg` (Buffer),
+`.html`, `.svg`, `.markdown`, `.json`, `.text`.
 
 ```js
-await kern.withSandbox({ setup: "pip install matplotlib" }, async (sbx) => {
-  await sbx.runCode("import matplotlib; matplotlib.use('Agg')\n" +
-    "import matplotlib.pyplot as plt; plt.plot([1,4,9]); plt.savefig('chart.png')");
-  const png = await sbx.readFile("chart.png"); // Buffer, ready to return to the model / user
+await kern.withSandbox({ setup: "pip install matplotlib pandas" }, async (sbx) => {
+  let r = await sbx.runCode("import matplotlib; matplotlib.use('Agg')\n" +
+    "import matplotlib.pyplot as plt; plt.plot([1,4,9])");
+  const png = r.results[0].png;                 // Buffer of the figure, auto-captured
+
+  r = await sbx.runCode("import pandas as pd; pd.DataFrame({'a':[1,2]})");
+  r.results[0].html;                            // the DataFrame as an HTML table (also .text)
 });
 ```
 
+Capture never touches `stdout`/`stderr`/`exitCode`; a statement returning `None` yields no result. You
+can still WRITE an artifact to the workspace and `readFile` it if you prefer.
+
 **Live output.** Pass `onStdout` / `onStderr` to stream each chunk as it arrives. The callback is
 best-effort, not lossless: a SLOW callback drops chunks rather than applying backpressure to the box
 (the full capped output is always in `result.stdout`).

package/index.d.ts

@@ -17,6 +17,29 @@ export interface FileInfo {
   change: "created" | "modified";
 }
 
+/** A rich, mime-typed value captured from a Python `runCode` (Jupyter/E2B-style): the code's last bare
+ * expression, every `display(obj)` call, and every open matplotlib figure. `data` maps a MIME type to
+ * its payload (text/* and application/json are strings; image/* are base64). One value, several forms. */
+export class Result {
+  data: Record<string, string>;
+  /** text/plain */
+  readonly text?: string;
+  /** text/html */
+  readonly html?: string;
+  /** text/markdown */
+  readonly markdown?: string;
+  /** image/svg+xml */
+  readonly svg?: string;
+  /** application/json */
+  readonly json?: string;
+  /** image/png decoded to a Buffer, or null */
+  readonly png: Buffer | null;
+  /** image/jpeg decoded to a Buffer, or null */
+  readonly jpeg: Buffer | null;
+  /** The MIME types this value was captured as. */
+  formats(): string[];
+}
+
 /** The outcome of one runCode()/run(). `fault` is the source of truth for "did the sandbox act";
  * `exitCode`/`stdout` are what the user's code did. `success` requires both clean. */
 export class ExecutionResult {
@@ -29,6 +52,8 @@ export class ExecutionResult {
   files: FileInfo[];
   /** stdout/stderr hit the capture cap and overflow was discarded. */
   truncated: boolean;
+  /** Rich mime-typed values (Python runCode): last expression, display(), matplotlib figures. */
+  results: Result[];
   /** True iff the code exited 0 AND no sandbox fault fired. */
   readonly success: boolean;
 }

package/index.js

@@ -36,13 +36,141 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.2";
+const VERSION = "0.1.4";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
 const DEPS_DIR = ".deps"; // pip --target dir inside the workspace (added to PYTHONPATH for python)
 const ENV_FILE = ".kern-env"; // host-side 0600 env file (kept out of argv so values don't show in `ps`)
 const INLINE_CODE_MAX = 128 * 1024; // above this, pass code via a file instead of argv (ARG_MAX guard)
+// Cap the results file the (untrusted) box writes before the binding reads it into host RAM: a malicious
+// cell could stream a multi-GB `.res` to disk (past its own memory cap) and OOM the host.
+const RESULTS_MAX = 64 * 1024 * 1024; // 64 MiB: generous for charts/tables, bounds the attacker read
+
+// Python cell runner (P1: rich mime-typed results, Jupyter/E2B-style, no Jupyter kernel). Runs INSIDE
+// the box (it is Python, regardless of which binding drove it): execs the user cell, then captures the
+// trailing bare expression's value, every display(obj) call, and every open matplotlib figure, writing
+// them as a JSON mime-bundle list the binding reads back. stdout/stderr/exit are UNTOUCHED. On the hot
+// path it imports only C builtins (no .py to recompile in the read-only slim box); base64/io/traceback/
+// json are lazy. Mirrors the Python binding's runner. __KERN_CELL__/__KERN_RES__ are substituted per call.
+const PY_RUNNER = `
+import sys, builtins  # C builtins: no .py to recompile in the read-only slim box (the P1 hot path).
+_CELL = "__KERN_CELL__"
+_RES = "__KERN_RES__"
+_out = []
+def _js(s):  # minimal JSON string encoder, so the box needs no \`import json\` (~80ms in a pyc-less slim box)
+    r = ['"']
+    for ch in s:
+        o = ord(ch)
+        if ch == '"':
+            r.append('\\\\"')
+        elif ch == '\\\\':
+            r.append('\\\\\\\\')
+        elif o == 10:
+            r.append('\\\\n')
+        elif o == 13:
+            r.append('\\\\r')
+        elif o == 9:
+            r.append('\\\\t')
+        elif o < 32:
+            r.append('\\\\u%04x' % o)
+        else:
+            r.append(ch)
+    r.append('"')
+    return "".join(r)
+def _bundle(o):
+    d = {}
+    for meth, key in (("_repr_html_", "text/html"), ("_repr_markdown_", "text/markdown"),
+                      ("_repr_svg_", "image/svg+xml"), ("_repr_latex_", "text/latex")):
+        try:
+            fn = getattr(o, meth, None)
+            if callable(fn):
+                v = fn()
+                if isinstance(v, str) and v:
+                    d[key] = v
+        except Exception:
+            pass
+    try:
+        fn = getattr(o, "_repr_json_", None)
+        if callable(fn):
+            v = fn()
+            if v is not None:
+                if isinstance(v, str):
+                    d["application/json"] = v
+                else:
+                    import json
+                    d["application/json"] = json.dumps(v)
+    except Exception:
+        pass
+    for meth, key in (("_repr_png_", "image/png"), ("_repr_jpeg_", "image/jpeg")):
+        try:
+            fn = getattr(o, meth, None)
+            if callable(fn):
+                v = fn()
+                if v:
+                    import base64
+                    raw = v if isinstance(v, (bytes, bytearray)) else str(v).encode()
+                    d[key] = base64.b64encode(raw).decode()
+        except Exception:
+            pass
+    if "text/plain" not in d:
+        try:
+            d["text/plain"] = repr(o)
+        except Exception:
+            d["text/plain"] = "<unrepresentable>"
+    return d
+def display(o=None, **kw):
+    if o is not None:
+        _out.append(_bundle(o))
+builtins.display = display
+sys.argv = [_CELL]
+_g = {"__name__": "__main__", "__file__": _CELL, "display": display}
+_rc = 0
+try:
+    _src = open(_CELL, "r", encoding="utf-8").read()
+    _tree = compile(_src, _CELL, "exec", 0x400)
+    _tail = None
+    if _tree.body and type(_tree.body[-1]).__name__ == "Expr":
+        _n = _tree.body.pop()
+        _lines = _src.split("\\n")
+        if _n.lineno == _n.end_lineno:
+            _tail = _lines[_n.lineno - 1].encode()[_n.col_offset:_n.end_col_offset].decode("utf-8", "replace")
+        else:
+            _seg = [_lines[_n.lineno - 1].encode()[_n.col_offset:].decode("utf-8", "replace")]
+            _seg += _lines[_n.lineno:_n.end_lineno - 1]
+            _seg.append(_lines[_n.end_lineno - 1].encode()[:_n.end_col_offset].decode("utf-8", "replace"))
+            _tail = "\\n".join(_seg)
+    exec(compile(_tree, _CELL, "exec"), _g)
+    if _tail is not None:
+        _val = eval(compile(_tail, _CELL, "eval"), _g)
+        if _val is not None:
+            _out.append(_bundle(_val))
+except SystemExit as _e:
+    _rc = _e.code if isinstance(_e.code, int) else (0 if _e.code is None else 1)
+except BaseException as _e:
+    import traceback
+    _tb = _e.__traceback__
+    while _tb is not None and _tb.tb_frame.f_code.co_filename != _CELL:
+        _tb = _tb.tb_next
+    sys.stderr.write("".join(traceback.format_exception(type(_e), _e, _tb)))
+    _rc = 1
+try:
+    if "matplotlib.pyplot" in sys.modules:
+        import base64, io
+        _plt = sys.modules["matplotlib.pyplot"]
+        for _fig in _plt.get_fignums():
+            _buf = io.BytesIO()
+            _plt.figure(_fig).savefig(_buf, format="png")
+            _out.append({"image/png": base64.b64encode(_buf.getvalue()).decode()})
+except Exception:
+    pass
+try:
+    _parts = ["{" + ",".join(_js(str(_k)) + ":" + _js(str(_v)) for _k, _v in _d.items()) + "}" for _d in _out]
+    open(_RES, "w", encoding="utf-8").write("[" + ",".join(_parts) + "]")
+except Exception:
+    pass
+sys.exit(_rc)
+`;
 
 // Signal-derived exit codes (128 + signum) we classify.
 const EXIT_SIGKILL = 137; // SIGKILL: timeout backstop or OOM (indistinguishable without cgroup)
@@ -80,10 +208,47 @@ class MountRefused extends SandboxError {
   }
 }
 
+/** A rich, mime-typed value captured from a Python `runCode` (the way a Jupyter/E2B cell captures
+ * output): the value of the code's last bare expression, every `display(obj)` call, and every open
+ * matplotlib figure. `data` maps a MIME type to its payload; text/* and application/json are strings,
+ * image/* are base64 strings (use `.png`/`.jpeg` for Buffers). One value can carry several forms. */
+class Result {
+  constructor(data) {
+    this.data = data || {};
+  }
+  get text() {
+    return this.data["text/plain"];
+  }
+  get html() {
+    return this.data["text/html"];
+  }
+  get markdown() {
+    return this.data["text/markdown"];
+  }
+  get svg() {
+    return this.data["image/svg+xml"];
+  }
+  get json() {
+    return this.data["application/json"];
+  }
+  get png() {
+    const v = this.data["image/png"];
+    return v ? Buffer.from(v, "base64") : null;
+  }
+  get jpeg() {
+    const v = this.data["image/jpeg"];
+    return v ? Buffer.from(v, "base64") : null;
+  }
+  /** The MIME types this value was captured as. */
+  formats() {
+    return Object.keys(this.data);
+  }
+}
+
 /** The outcome of one runCode()/run(). `fault` is the source of truth for "did the SANDBOX act";
  * `exitCode`/`stdout` are what the user's code did. `success` requires both clean. */
 class ExecutionResult {
-  constructor({ stdout, stderr, exitCode, durationMs, fault, files, truncated }) {
+  constructor({ stdout, stderr, exitCode, durationMs, fault, files, truncated, results }) {
     this.stdout = stdout;
     this.stderr = stderr;
     this.exitCode = exitCode;
@@ -92,6 +257,8 @@ class ExecutionResult {
     this.fault = fault || null;
     this.files = files || [];
     this.truncated = !!truncated;
+    /** @type {Result[]} rich mime-typed values (Python runCode) */
+    this.results = results || [];
   }
   /** True iff the code exited 0 AND no sandbox fault fired. */
   get success() {
@@ -723,7 +890,7 @@ class Sandbox {
   }
 
   /** Read `path` (workspace-relative) from the workspace - host-direct. Final component O_NOFOLLOW. */
-  async readFile(rel) {
+  async readFile(rel, { maxBytes = null } = {}) {
     this._requireEntered();
     const full = this._wsPath(rel);
     let fd;
@@ -733,6 +900,10 @@ class Sandbox {
       throw new SandboxError(`cannot read ${JSON.stringify(rel)}: ${e.message}`);
     }
     try {
+      // maxBytes caps the read so a file a not-fully-trusted box wrote can't OOM the host; the box has
+      // already exited by the time we read, so fstat -> read is race-free.
+      if (maxBytes !== null && fs.fstatSync(fd).size > maxBytes)
+        throw new SandboxError(`${JSON.stringify(rel)} exceeds maxBytes=${maxBytes}`);
       return fs.readFileSync(fd);
     } finally {
       fs.closeSync(fd);
@@ -918,6 +1089,7 @@ class Sandbox {
     if (!spec)
       throw new SandboxError(`unsupported language ${JSON.stringify(language)} (v1: 'python' | 'bash' | 'node')`);
     const [runner, evalFlag, ext] = spec;
+    if (language === "python") return this._runPythonCell(code);
     let command;
     if (Buffer.byteLength(code, "utf8") > INLINE_CODE_MAX) {
       const cell = `.cell-${crypto.randomBytes(4).toString("hex")}.${ext}`;
@@ -929,6 +1101,44 @@ class Sandbox {
     return this._spawn(command, { network: this.network, timeoutS: this.timeoutS });
   }
 
+  /** Run Python through the cell runner so a trailing expression, display() calls and matplotlib
+   * figures are captured as rich mime-typed `result.results` (Jupyter/E2B-style). stdout/stderr/exit
+   * are identical to a plain run; capture is best-effort. Internal cell/runner/results files are
+   * removed and hidden from `result.files`. */
+  async _runPythonCell(code) {
+    const uid = crypto.randomBytes(4).toString("hex");
+    const cell = `.cell-${uid}.py`;
+    const resf = `.res-${uid}.json`;
+    const runf = `.run-${uid}.py`;
+    await this.writeFile(cell, code);
+    const shim = PY_RUNNER.replace("__KERN_CELL__", `${WORKSPACE}/${cell}`).replace(
+      "__KERN_RES__",
+      `${WORKSPACE}/${resf}`,
+    );
+    await this.writeFile(runf, shim);
+    const result = await this._spawn(["python3", `${WORKSPACE}/${runf}`], {
+      network: this.network,
+      timeoutS: this.timeoutS,
+    });
+    try {
+      const parsed = JSON.parse(await this.readFile(resf, { maxBytes: RESULTS_MAX }));
+      if (Array.isArray(parsed))
+        result.results = parsed.filter((r) => r && typeof r === "object").map((r) => new Result(r));
+    } catch {
+      /* missing / too-large / unreadable / bad JSON: leave results empty, run otherwise intact */
+    }
+    const internal = new Set([cell, resf, runf]);
+    for (const name of internal) {
+      try {
+        fs.unlinkSync(path.join(this._ws, name));
+      } catch {
+        /* ignore */
+      }
+    }
+    result.files = result.files.filter((fi) => !internal.has(fi.path));
+    return result;
+  }
+
   /** Run an arbitrary `command` (an argv ARRAY, never a shell string) in a fresh box. */
   async run(command) {
     this._requireEntered();
@@ -968,6 +1178,7 @@ module.exports = {
   withSandbox,
   runCode,
   ExecutionResult,
+  Result,
   SandboxError,
   MountRefused,
   version: VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Run LLM/agent-generated code in a fast, local, daemonless kernel sandbox. A thin, dependency-free wrapper around the kern binary.",
   "keywords": [
     "sandbox",