kern-sandbox 0.2.38 → 0.2.40

package/README.md

@@ -1,17 +1,31 @@
-# kern-sandbox (Node.js / TypeScript)
+<div align="center">
 
-**Run LLM-generated code in a fast, real sandbox, one fresh box per call.**
+<img src="https://raw.githubusercontent.com/getkern/kern/main/assets/brand/kern-logo.png" width="220" alt="kern">
 
-Fast means milliseconds, and it is two numbers rather than one: the box is the cheap part, and an
-interpreter starting inside it costs more than the box does. Both depend on your machine, so they are
-measured under [Prewarming](https://github.com/getkern/kern/blob/main/bindings/node/README.md#prewarming-a-box-ready-before-the-call-arrives) with the machine and the method beside them, and the
-runtime's own are in [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md).
+# Kern Sandbox
 
-`kern-sandbox` is the Node and TypeScript binding for **[kern](https://getkern.dev)**: a rootless,
-kernel-enforced sandbox out of one static binary, with no daemon, no VM and no cloud. An agent's
-tool-call, a model's generated snippet, a CI step: code that runs before anyone reads it gets its own
-box, and the box is thrown away after. A hundred calls are a hundred boxes and 1.4 s in total, with
-nothing left behind, and when state has to carry across them there is
+**Your model writes the code. This runs it where it can't touch your machine.**
+
+<sub>**Works with** Claude Code · Cursor · Claude Desktop · LM Studio · LangChain · pi</sub>
+
+[![npm](https://img.shields.io/npm/v/kern-sandbox?label=npm&color=0b7285)](https://www.npmjs.com/package/kern-sandbox)
+[![PyPI](https://img.shields.io/pypi/v/kern-sandbox?label=PyPI&color=0b7285)](https://pypi.org/project/kern-sandbox/)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/getkern/kern/blob/main/LICENSE)
+
+<sub>rootless · no daemon · no socket · no VM · no cloud · no account</sub>
+
+**[The runtime](https://github.com/getkern/kern)** ·
+**[MCP server](https://github.com/getkern/kern/blob/main/docs/MCP.md)** ·
+**[Security model](https://github.com/getkern/kern/blob/main/SECURITY.md)** ·
+**[Benchmarks](https://github.com/getkern/kern/blob/main/BENCHMARKS.md)**
+
+</div>
+
+An agent's tool-call, a generated snippet, a notebook cell, a CI step: it arrives, you run it, and
+nobody has read it first.
+
+`kern-sandbox` is the Node and TypeScript binding for **[kern](https://getkern.dev)**. Every call
+gets its own box, thrown away after; when state has to carry across calls there is
 [a session](#a-session-files-persist-processes-are-ephemeral) and a warm interpreter.
 
 Network off, memory and PID caps the kernel enforces **where your host delegates them**,
@@ -288,7 +302,7 @@ RUN python3 -m compileall -q -j 0 /usr/local/lib/python3.12
 
 Build it once and pass it: `run_code(..., image="my-python")`. The default stays the stock tag,
 because an SDK that silently required a custom image would be worse than one that costs 29 ms and
-says so. Measured on an Intel i7-14700KF, Linux 7.0.0, idle; [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md) has the method.
+says so. Measured rootless on an idle machine; [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md) has the method.
 
 ## Prewarming: a box ready before the call arrives
 

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.2.38";
+const VERSION = "0.2.40";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -285,9 +285,22 @@ function pycSourceId(image) {
     const root = path.join(cacheHome(), "kern", "images");
     const safe = sanitizeRef(image);
     const h = crypto.createHash("sha256");
-    for (const suffix of [".image", ".ok"]) {
-      h.update(fs.readFileSync(path.join(root, safe + suffix)).subarray(0, 4096));
-      h.update(Buffer.from([0]));
+    // THE CONFIG, which changes when ENTRYPOINT/ENV/WORKDIR/USER do.
+    h.update(fs.readFileSync(path.join(root, `${safe}.image`)).subarray(0, 4096));
+    // THE SENTINEL'S STAMP, NOT ITS BYTES. `.ok` holds the REFERENCE, so its contents are the tag and
+    // never move when the tag does: hashing them missed the commonest case there is, a rebuilt rootfs
+    // under an unchanged config. Its mtime and length are what kern ITSELF uses to decide an image's
+    // content changed, because a re-pull rewrites the sentinel last. Measured: a real re-pull leaves
+    // the config byte-identical and moves this.
+    const st = fs.statSync(path.join(root, `${safe}.ok`), { bigint: true });
+    h.update(`${st.mtimeNs}:${st.size}`);
+    // AND THE LAYER MANIFEST FOR A BUILT IMAGE, which names its layers by content. A pulled image has
+    // none, and that absence is part of the identity: an image that stops being layered is not the
+    // same image.
+    try {
+      h.update(fs.readFileSync(path.join(root, `${safe}.layers`)).subarray(0, 8192));
+    } catch {
+      h.update("\0no-layers");
     }
     return h.digest("hex").slice(0, 32);
   } catch {
@@ -4411,5 +4424,11 @@ module.exports = {
   _ociCanonicalRef: ociCanonicalRef,
   _PYC_BUILD_CODE: PYC_BUILD_CODE,
   _pycStartBuild: pycStartBuild,
+  /** Await every build still in flight. FOR TESTS, and it removes a real race rather than masking
+   *  one: a test that removes its temp cache home while a background build is still writing into it
+   *  fails in `rimraf` with ENOTEMPTY, which is a teardown ordering bug and reads like a product
+   *  defect. Measured under the gate, where the machine is busy enough for the build to outlive the
+   *  test. */
+  _pycSettle: () => Promise.allSettled([...PYC_BUILDS.values()]),
   version: VERSION,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "description": "Your model writes the code. This runs it where it can't touch your machine: a rootless Linux container, no daemon, no VM, no cloud, no account. A kernel boundary, not a microVM: for deliberately hostile code, use one.",
   "keywords": [
     "sandbox",