kern-sandbox 0.1.39 → 0.1.41

package/README.md

@@ -12,9 +12,9 @@ allowlist, and a wall-clock deadline the binding applies from **outside** the bo
 cannot outlive it. Dependency-free: it shells out to the `kern` binary and does not re-implement
 isolation in JavaScript.
 
-**The failure comes back as data, not as an exception.** A timeout, an OOM-kill, a blocked syscall or
-a missing interpreter is a typed `fault` on the result, beside stdout and the exit code, so an agent
-loop reads a field instead of parsing a stack trace to learn that the sandbox ended the run.
+**Your loop reads a field, not a stack trace.** A timeout, an OOM-kill, a blocked syscall or a missing
+interpreter each arrive as a typed `fault` on the result, beside stdout and the exit code, so the
+agent branches on a value instead of parsing text to work out who ended the run.
 
 On npm: [`npm install kern-sandbox`](https://www.npmjs.com/package/kern-sandbox). Python gets the same
 package on PyPI: [`kern-sandbox`](https://pypi.org/project/kern-sandbox/), which also ships an **MCP
@@ -109,6 +109,8 @@ const r = await kern.runCode("console.log([1,2,3].map(x => x * x))", {
 | field | meaning |
 |---|---|
 | `stdout`, `stderr` | captured output (each capped at `maxOutputBytes`) |
+| `codeStderr` | `stderr` with kern's own `note:`/`warning:` lines removed: what the code wrote. Feed THIS to a model |
+| `runtimeNotes` | the complement: the lines kern wrote about itself. `stderr` still holds both, in order |
 | `exitCode` | the process exit code |
 | `durationMs` | wall-clock duration of the call, in ms |
 | `success` | `true` iff `exitCode === 0` **and** no sandbox fault |
@@ -118,6 +120,13 @@ const r = await kern.runCode("console.log([1,2,3].map(x => x * x))", {
 | `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.
+
+`stderr` is one stream shared by kern and your code, so a note about overlayfs or an undelegated
+cgroup arrives interleaved with the program's own output. That is right for a human reading a
+terminal and wrong for anything that puts `stderr` into a prompt, where it spends context on the
+runtime's housekeeping and reads like an error the code produced. `codeStderr` is the same string
+without those lines, and nothing is hidden: `runtimeNotes` holds exactly what was taken out. The
+LangChain tool and the MCP server already use it.
 `fault` is only set when the **sandbox** acted:
 
 | `fault.type` | when |
@@ -202,52 +211,10 @@ new Sandbox({
 });
 ```
 
-**Writable paths: `/workspace`, `/tmp` and `/dev/shm`.** The box root is read-only, so `/tmp` is a
-64 MiB tmpfs this binding mounts for you. Without it a write naming `/tmp` fails with `EROFS` and
-temp-file helpers fall back to the current directory, quietly putting scratch into your persistent
-workspace where `listFiles` then reports it. The bytes are charged to the box's own memory cgroup, so
-filling `/tmp` OOM-kills the box and never fills the host disk. Resize with `tmpfs: { "/tmp": "512m" }`,
-remove with `tmpfs: {}`, or bind your own directory at `/tmp` through `mounts` and the default steps
-aside (a `:ro` bind included, which leaves `/tmp` read-only: your call, not an accident). **The unit is
-required and the target may not contain a `:`.** kern's CLI takes both spellings and means the
-opposite of what you do: a bare `"64"` is 64 BYTES, `"0"` is UNLIMITED, and `["/scratch:9g"]` mounts
-`/scratch` at 9 GiB rather than a directory by that name. All three measured, all three refused here. A size larger than `memoryMb` is refused for the same family
-of reason: `df` would report it to a program that preflights. The binding's own default is clamped to
-half the cap instead.
-
-**`memoryMb` bounds the cgroup, not the workload's usable memory.** The cap is shared with
-memory-backed filesystems in the same box, and `/dev/shm` is one of them with **no size at all** (the
-kernel's tmpfs default, half of host RAM, so it scales with the machine and not with your config).
-Measured: 200 MiB written there under `memoryMb: 128` OOM-kills the box whatever `/tmp` is set to.
-`tmpfs: { "/dev/shm": ... }` is refused by kern; `mounts` at the same target IS accepted and stacks over
-kern's own mount; measured through it, `multiprocessing.shared_memory` and POSIX semaphores still
-work. Two costs: a plain directory is unbounded on DISK instead of in RAM, so bounding it means
-binding a host directory that is itself a sized tmpfs, and it has no tmpfs lifetime, so what the box
-writes to `/dev/shm` is still on the host after the box dies.
-
-**Scratch does not survive a call.** Each `runCode` is a fresh box, so `/tmp` is fresh too while the
-workspace persists. Put anything a later call must find in the workspace. The `setup` box is the exception: an install needs unbounded scratch, so the default is not
-applied there (an explicit `tmpfs` still is).
-
-**Toolchains in the box** need two writable places, and the error names neither. Go reports `failed to
-initialize build cache at /root/.cache`, which says nothing about `HOME`; npm renders a failed
-`mkdir /root/.npm` as `Invalid response body while trying to fetch https://registry.npmjs.org/...`,
-which reads as a network fault and is not one. Measured on `node:22`: neither -> exit 2, `HOME` alone
-with a read-only `/tmp` -> still exit 2, both -> exit 0. Pass both:
-
-```js
-new Sandbox({
-  image: "golang:1.23-alpine",
-  env: { HOME: "/workspace" },   // npm's ~/.npm, Go's ~/.cache, Rust's CARGO_HOME, .NET's NuGet
-  tmpfs: { "/tmp": "512m" },     // scratch; 64 MiB fits a small install, a real one needs more
-});
-```
-
-`runCode`/`run` also take `timeoutS`/`onStdout`/`onStderr` as **per-call** options that override the
-session defaults for that one call. A `vcpu:` profile can carry `cpus`+`memory`; `memoryMb`/`cpus` are
-explicit flags that **override** a profile's values (and the `memoryMb` default `512` shadows a profile's
-`memory`, so pass `memoryMb: null` to let the profile apply). The **MCP server** (`kern-mcp`, for Claude
-Desktop / Cursor) ships in the Python package `kern-sandbox` (`pip install kern-sandbox`).
+**The sharp edges are in [SANDBOX-NOTES.md](https://github.com/getkern/kern/blob/main/bindings/node/SANDBOX-NOTES.md):**
+the writable paths and why `/tmp` is a tmpfs, `memoryMb` bounding the cgroup rather than usable
+memory, scratch that does not survive a call, and the two writable places a toolchain needs before
+`npm install` stops reporting a network error that is not one. Each is a measured surprise.
 
 ## Egress: the setting between no network and the host's
 
@@ -308,60 +275,24 @@ package manager imports `globSync` from `node:fs`, which landed in 22.
 
 ## Charts, rich results, live output, and checkpoints
 
-**Rich results (the "code interpreter" pattern).** `runCode` runs Python by default, and like a
-Jupyter 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`.
+`runCode` captures mime-typed values into `result.results` the way a notebook cell does: the **last
+bare expression**, every **`display(obj)`**, and **every open matplotlib figure automatically**, with
+no `savefig`. Accessors: `.png`, `.jpeg`, `.html`, `.svg`, `.markdown`, `.json`, `.text`.
 
 ```js
-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.map((x) => x.png).find(Boolean) ?? null;  // figure Buffer, 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)
+await withSandbox({ setup: "pip install pandas matplotlib" }, async (sbx) => {
+  await sbx.writeFile("data.csv", "a,b\n1,2\n3,4\n");
+  const r = await sbx.runCode("import pandas as pd; pd.read_csv('data.csv').describe()");
+  r.results[0].html;                       // the DataFrame as an HTML table
 });
 ```
 
-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.
-
-**Warm kernel (kill the interpreter boot).** Each `runCode` starts a **fresh** interpreter, paying the
-CPython boot (~12 ms) every call. When you run many cells that share state (a REPL, a notebook, an
-agent's tool loop), open a `kernel()`: ONE warm interpreter in a long-lived box, fed cells over a pipe.
-In-memory state persists across cells and the per-cell cost drops from ~14 ms to **sub-millisecond**
-(~300x). Same rich `results` capture as `runCode`.
-
-```js
-await kern.withSandbox(async (sbx) => {
-  const k = await sbx.kernel();
-  try {
-    await k.runCode("import numpy as np; a = np.arange(1_000_000)");  // imports paid once
-    const r = await k.runCode("a.sum()");                            // 'a' is still here; ~sub-ms
-    console.log(r.results[0].text);                                  // 499999500000
-  } finally {
-    await k.close();                                                 // tears the box down
-  }
-});
-```
+Capture never touches `stdout`, `stderr` or `exitCode`. Pass `onStdout` / `onStderr` to stream output
+as it arrives (best-effort: a slow callback drops chunks rather than stalling the box).
 
-The trade vs `runCode`: cells in a kernel share one process and one box, so it is call-fast but not
-call-isolated (still network-off and resource-capped; a fresh session or kernel is clean). An uncaught
-error is confined (`exitCode` 1, traceback on `stderr`, the kernel keeps serving); a per-cell `timeoutS`
-tears the kernel down (a running cell cannot be interrupted), after which it refuses further cells.
-
-**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`).
-
-**Checkpoints.** `sbx.snapshot(dest)` writes a portable `.tar.gz` of the workspace (a FILESYSTEM
-checkpoint, not memory); `sbx.restore(src)` extracts it back, refusing absolute / `..` / symlink
-members. Interoperable with `tar` and the Python binding (both write plain USTAR, so a workspace path
-must be under 100 bytes). The Node path uses a hand-rolled tar reader,
-so while it is new it is **opt-in**: set `KERN_SANDBOX_SNAPSHOT=1` to enable it (it fails closed with a
-clear error otherwise). The Python binding uses the stdlib `tarfile` and has no such gate.
+`snapshot(dest)` and `restore(src)` write a portable `.tar.gz` checkpoint of the **workspace**;
+`restore` refuses absolute, `..` and symlink members. Nothing in `/tmp` is on it, because a tmpfs is
+on no layer.
 
 ## Honest threat model
 

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.39";
+const VERSION = "0.1.41";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -510,6 +510,47 @@ class ExecutionResult {
   get success() {
     return this.exitCode === 0 && this.fault === null;
   }
+  /** `stderr` with kern's own `note:`/`warning:`/posture lines removed: what the code actually wrote.
+   *
+   * This is what belongs in a model's context. A workload CAN forge one of kern's prefixes, and the
+   * consequence is its own line moving to {@link runtimeNotes}: the trick removes its text from this
+   * field, it cannot inject text into it.
+   *
+   * The guarantee is LINE-ALIGNED, not absolute: a workload that leaves a line unterminated and is
+   * then interleaved with a `kern: warning:` on the shared stderr produces one line starting with the
+   * workload's text, which no prefix matches, so kern's warning lands here framed by bytes the
+   * workload chose. Racy rather than reliable, and in the less harmful direction, but real. Mirrors
+   * `ExecutionResult.code_stderr` in Python. */
+  get codeStderr() {
+    return this._splitStderr()[0];
+  }
+  /** Partition `stderr` ONCE into [what the code wrote, the lines kern wrote].
+   *
+   * One pass and one cache, mirroring `_split_stderr` in Python. The two public halves are a single
+   * partition, so computing them separately left two filters that had to agree by inspection rather
+   * than by construction; and each was O(n) on every read, measured at 13.9 ms on a 200k-line stderr
+   * in the Python binding before this. Keyed on the string it partitioned, so reassigning `stderr`
+   * recomputes rather than serving a stale answer. Non-enumerable, so it stays out of JSON and out of
+   * anything that walks the result's own keys. */
+  _splitStderr() {
+    const raw = String(this.stderr || "");
+    if (this._stderrSplit && this._stderrSplit[0] === raw) {
+      return [this._stderrSplit[1], this._stderrSplit[2]];
+    }
+    const kept = [];
+    const notes = [];
+    for (const line of raw.split("\n")) (isKernDiagnostic(line) ? notes : kept).push(line);
+    const joined = kept.join("\n");
+    Object.defineProperty(this, "_stderrSplit", {
+      value: [raw, joined, notes], writable: true, enumerable: false, configurable: true,
+    });
+    return [joined, notes];
+  }
+  /** The lines on `stderr` that KERN wrote, the complement of {@link codeStderr}. Reported rather
+   * than removed: `stderr` still holds every byte in its original order. */
+  get runtimeNotes() {
+    return this._splitStderr()[1].slice();
+  }
 }
 
 /** A sandbox event `{type, message}` for `result.fault`. NB: `startup_failed` is decided from an
@@ -821,6 +862,21 @@ function execFailureBinary(stderr) {
   return m ? { what: m[1], reason: (m[2] || "").trim() } : null;
 }
 
+/** The prefixes of stderr lines KERN writes about itself, as opposed to lines the workload wrote: the
+ * `--security-profile` posture banner and any `warning:`/`note:` diagnostic.
+ *
+ * ONE definition, used for two purposes that must agree by construction: `codeStderr` subtracts these
+ * to build what a model should read, and `looksLikeStartupFailure` skips them so a benign note is not
+ * read as a box that failed to start. Mirrors `_KERN_DIAGNOSTICS` in the Python binding. */
+const KERN_DIAGNOSTICS = ["kern: security-profile=", "kern: warning:", "kern: note:"];
+
+function isKernDiagnostic(line) {
+  const s = line.replace(/^\s+/, "");
+  return KERN_DIAGNOSTICS.some((p) => s.startsWith(p));
+}
+
+
+
 function looksLikeStartupFailure(stderr) {
   const markers = [
     "kern:",
@@ -833,14 +889,9 @@ function looksLikeStartupFailure(stderr) {
     "error: oci:",
     "error: image:",
   ];
-  // kern also writes BENIGN `kern:` diagnostics that are NOT a box-start failure: the
-  // `--security-profile` posture banner, and `warning:`/`note:` lines. They start with `kern:` too, so
-  // without this skip a workload that merely exits non-zero WHILE one is on stderr (e.g. code run under
-  // securityProfile: "untrusted" that hits a network error) would be mislabeled `startup_failed`.
-  const benign = ["kern: security-profile=", "kern: warning:", "kern: note:"];
   for (const line of stderr.split("\n")) {
     const s = line.replace(/^\s+/, "");
-    if (benign.some((b) => s.startsWith(b))) continue;
+    if (isKernDiagnostic(s)) continue;
     if (s.includes("sandbox setup failed") || markers.some((m) => s.startsWith(m))) return true;
   }
   return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and AI-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box in single-digit milliseconds, with no cloud, no account and no VM.",
   "keywords": [
     "sandbox",