kern-sandbox 0.1.38 → 0.1.40

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 |

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.38";
+const VERSION = "0.1.40";
 
 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.38",
+  "version": "0.1.40",
   "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",