@tlockney/cdp-kernel 0.7.0 → 0.7.2

package/dist/workerd-target.js

@@ -18,17 +18,18 @@ import { Buffer } from "node:buffer";
 import process from "node:process";
 import { execFileSync, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
-import { builtinModules } from "node:module";
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { builtinModules, createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, delimiter, dirname, isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { build } from "esbuild";
 import { asEvaluateResult } from "./cdp.js";
 import { transformCellForEval } from "./transform.js";
 import { runtimeDir } from "./package.js";
 import { killOnExit } from "./children.js";
-import { Interrupted, isTargetMessage } from "./target.js";
+import { Interrupted, isTargetMessage, parseBundle, parseJson } from "./target.js";
+import { withStartTimeout } from "./target-api.js";
 import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
 import { ensureInstalledAsync, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
@@ -87,6 +88,50 @@ export function findWorkerd(cwd) {
             return "workerd";
     }
 }
+/**
+ * The native workerd binary behind `executable`. npm's workerd package
+ * installs bin/workerd as a Node script that runs the platform package's
+ * binary with execFileSync, and only its postinstall swaps the binary in.
+ * When install scripts don't run (the npm that comes with Node 27 blocks
+ * those not in allowScripts), killing that script leaves the binary running
+ * with the driver socket open, so it's never what the target spawns (#397).
+ * Anything that isn't the workerd package's script is returned as given.
+ */
+export function nativeWorkerd(executable) {
+    const candidates = [];
+    let path = executable;
+    if (!isAbsolute(path) && !path.includes("/") && !path.includes("\\")) {
+        const dir = (process.env.PATH ?? "").split(delimiter).find((d) => d && existsSync(join(d, path)));
+        if (dir === undefined)
+            return executable;
+        path = join(dir, path);
+    }
+    // node_modules/.bin/workerd, a link or (on Windows) a .cmd shim.
+    if (basename(dirname(path)) === ".bin")
+        candidates.push(join(dirname(dirname(path)), "workerd"));
+    try {
+        // A link to <package>/bin/workerd, as a global install makes.
+        candidates.push(dirname(dirname(realpathSync(path))));
+    }
+    catch {
+        return executable;
+    }
+    for (const pkg of candidates) {
+        try {
+            const { name } = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
+            if (name !== "workerd")
+                continue;
+            // The package's main export is the binary's path.
+            const binary = createRequire(join(pkg, "package.json"))(join(pkg, "lib", "main.js")).default;
+            if (typeof binary === "string" && existsSync(binary))
+                return binary;
+        }
+        catch {
+            // Not the npm package, or one this doesn't understand: use it as given.
+        }
+    }
+    return executable;
+}
 /** "workerd 2026-10-15" -> "2026-10-15": the newest date it supports. */
 export function compatibilityDateOf(versionOutput) {
     const m = /\b(\d{4}-\d{2}-\d{2})\b/.exec(versionOutput);
@@ -188,8 +233,30 @@ function isWorkerdIn(pid, dir) {
     try {
         if (process.platform === "linux")
             return readlinkSync(`/proc/${pid}/cwd`) === dir;
-        const args = execFileSync("ps", ["-o", "args=", "-p", String(pid)], { encoding: "utf8" });
-        return /workerd/.test(args) && args.includes("config.capnp");
+        // No cwd to compare elsewhere: the process must at least be ours and
+        // look like a workerd (#335).
+        const [uid, ...args] = execFileSync("ps", ["-o", "uid=,args=", "-p", String(pid)], { encoding: "utf8" }).trim().split(/\s+/);
+        const command = args.join(" ");
+        return Number(uid) === process.getuid?.() && /workerd/.test(command) && command.includes("config.capnp");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `dir` is a directory mkdtemp made for this user: not a symlink,
+ * owned by us, and closed to everyone else. Anyone can create entries in
+ * tmpdir(), so nothing in a directory that fails this is trusted (#335).
+ * Windows has no uids; its tmpdir() is per-user.
+ */
+function isOwnPrivateDir(dir) {
+    try {
+        const stat = lstatSync(dir);
+        if (!stat.isDirectory())
+            return false;
+        if (process.getuid === undefined)
+            return true;
+        return stat.uid === process.getuid() && (stat.mode & 0o077) === 0;
     }
     catch {
         return false;
@@ -210,12 +277,14 @@ export function sweepStaleWorkerdDirs(root = tmpdir()) {
     }
     for (const name of names) {
         const dir = join(root, name);
+        if (!isOwnPrivateDir(dir))
+            continue;
         let owner;
         try {
             owner = JSON.parse(readFileSync(join(dir, OWNER_FILE), "utf8"));
         }
         catch {
-            continue; // Another user's, from before owner files, or being set up.
+            continue; // From before owner files, or being set up.
         }
         if (typeof owner.host !== "number" || pidAlive(owner.host))
             continue;
@@ -227,7 +296,12 @@ export function sweepStaleWorkerdDirs(root = tmpdir()) {
                 // Gone already.
             }
         }
-        rmSync(dir, { recursive: true, force: true });
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Cleanup is best effort; it must not stop this kernel starting.
+        }
     }
 }
 /** The driver on a workerd of its own, behind a Unix socket. */
@@ -241,7 +315,7 @@ export class RawWorkerd {
         this.runtime = runtime;
     }
     static async start(cwd, executable) {
-        const workerd = executable ?? findWorkerd(cwd);
+        const workerd = nativeWorkerd(executable ?? findWorkerd(cwd));
         const compatibilityDate = compatibilityDateOf(execFileSync(workerd, ["--version"], { encoding: "utf8" }));
         const source = await runtimeDir(new URL("../runtime/", import.meta.url).href);
         // mkdtemp makes the directory 0700: only this user reaches the socket,
@@ -295,7 +369,7 @@ export class RawWorkerd {
             }
         })();
         try {
-            const host = new RawWorkerd(child, await Promise.race([ready, exited]), compatibilityDate);
+            const host = new RawWorkerd(child, await withStartTimeout(Promise.race([ready, exited]), "workerd"), compatibilityDate);
             starting = false;
             early = "";
             return host;
@@ -360,7 +434,7 @@ export class WorkerdTarget {
         let notice;
         if (project !== null) {
             try {
-                host = await startMiniflare(project, cwd);
+                host = await startMiniflare(project, cwd, options.startTimeoutMs);
             }
             catch (err) {
                 // Like a broken deno.json (#13): say why in the first cell, and run
@@ -370,16 +444,18 @@ export class WorkerdTarget {
             }
         }
         host ??= await RawWorkerd.start(cwd, options.executable);
-        return await WorkerdTarget.open(host, cwd, events, "workerd", notice);
+        return await WorkerdTarget.open(host, cwd, events, "workerd", { notice, startTimeoutMs: options.startTimeoutMs });
     }
     /**
      * A target over a started host's session. `notice` (a project that
      * failed to load) is replaced by the bindings when the host has a project.
      */
-    static async open(host, cwd, events, runtime, notice) {
+    static async open(host, cwd, events, runtime, options = {}) {
         const target = new WorkerdTarget(host, cwd, events, runtime);
+        let notice = options.notice;
         try {
-            const { v8, bindings, worker } = await target.#request("info");
+            // A driver that never answers is stopped (#336).
+            const { v8, bindings, worker } = await withStartTimeout(target.#request("info"), `the ${runtime} driver`, options.startTimeoutMs);
             if (typeof v8 === "string" && v8)
                 target.versions.engine = `V8 ${v8}`;
             if (host.project !== undefined) {
@@ -396,7 +472,15 @@ export class WorkerdTarget {
         return target;
     }
     #receive(text) {
-        const msg = JSON.parse(text);
+        const msg = parseJson(text);
+        if (msg === undefined) {
+            // The driver only sends JSON; a frame that isn't means the session is
+            // broken, which ends the target rather than the kernel (#337).
+            this.#stopNote = `[cdp-kernel] ${this.runtime} sent a message that isn't JSON, so it was stopped; ` +
+                "it restarts on the next cell, without the earlier cells' state";
+            this.kill();
+            return;
+        }
         if (isRecord(msg) && msg.kind === "stream") {
             this.#events.stream(msg.name === "stderr" ? "stderr" : "stdout", String(msg.text));
         }
@@ -519,6 +603,10 @@ export class WorkerdTarget {
         }
         return { handled: reply.handled === true };
     }
+    async format(value) {
+        const reply = await this.#request("format", { handle: value.objectId });
+        return parseBundle(reply.value);
+    }
     async describeError(exception) {
         if (exception.objectId === undefined)
             return { name: "Error", message: exception.description ?? "", stack: "" };

package/dist/workers-project.d.ts

@@ -24,4 +24,4 @@ export declare function bundleProject(main: string, define?: {
     [name: string]: string;
 }): Promise<string>;
 /** Starts the driver on the project's Miniflare with its bindings. */
-export declare function startMiniflare(configPath: string, cwd: string): Promise<WorkerHost>;
+export declare function startMiniflare(configPath: string, cwd: string, startTimeoutMs?: number): Promise<WorkerHost>;

package/dist/workers-project.js

@@ -17,6 +17,7 @@ import { dirname, join } from "node:path";
 import { build } from "esbuild";
 import { childPids, reap } from "./children.js";
 import { runtimeDir } from "./package.js";
+import { withStartTimeout } from "./target-api.js";
 import { cellMeta, WORKER_MODULES } from "./workerd-target.js";
 export const WRANGLER_CONFIGS = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
 /** The nearest wrangler config at or above `cwd`, or null. */
@@ -157,7 +158,7 @@ class MiniflareHost {
     }
 }
 /** Starts the driver on the project's Miniflare with its bindings. */
-export async function startMiniflare(configPath, cwd) {
+export async function startMiniflare(configPath, cwd, startTimeoutMs) {
     const { wrangler, miniflare, version } = loadTooling(configPath);
     const projectDir = dirname(configPath);
     const { workerOptions, main, define } = wrangler.unstable_getMiniflareWorkerOptions(configPath);
@@ -190,10 +191,10 @@ export async function startMiniflare(configPath, cwd) {
     const before = new Set(childPids(process.pid, "workerd"));
     const mf = new miniflare.Miniflare(v5 && miniflare.convertV4MiniflareOptions ? miniflare.convertV4MiniflareOptions(options) : options);
     try {
-        await mf.ready;
         // Miniflare listens on a loopback TCP port; the token is what keeps
         // other local processes from the driver.
-        const res = await mf.dispatchFetch("http://cdpk/", { headers: { Upgrade: "websocket", "x-cdpk-token": token } });
+        const connect = mf.ready.then(() => mf.dispatchFetch("http://cdpk/", { headers: { Upgrade: "websocket", "x-cdpk-token": token } }));
+        const res = await withStartTimeout(connect, "Miniflare", startTimeoutMs);
         if (res.status !== 101 || res.webSocket === null)
             throw new Error(`the driver answered ${res.status}: ${await res.text()}`);
         const workerd = childPids(process.pid, "workerd").filter((pid) => !before.has(pid));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on Node, Deno, Bun, workerd and celld",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -59,6 +59,7 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:notebooks": "node docs/.vitepress/run-notebooks.ts",
+    "docs:debugger": "uv run --with jupyterlab --with playwright --with nbformat python test/debugger_screenshot.py",
     "docs:widgets": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/widget_screenshots.py",
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
@@ -81,6 +82,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
+    "medium-zoom": "^1.1.0",
     "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",
     "wrangler": "4.151.0"

package/runtime/bootstrap.mjs

@@ -215,6 +215,8 @@ globalThis.__cdpk = {
   inspectPath: (path, detail) => inspectPath(path, { inspect: inspectPlain, detail }),
   resolvePath,
   broadcastResult: jupyter.broadcastResult,
+  // execute_request's user_expressions (#340).
+  formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
   // The debugger's rich variable viewer (#18), synchronously: it runs while
   // the target is paused. A value whose $display is async shows as text.
   richBundle(value) {

package/runtime/browser-worker.mjs

@@ -8,6 +8,9 @@
 //
 // A Worker has no module resolution beyond URLs, so `npm:` and `jsr:`
 // specifiers, and bare package names, load from a CDN (esm.sh by default).
+//
+// The page can also offer cells its own features (#384): `host` requests go
+// to the page's handler, and `preload` modules run before the first cell.
 
 import { createJupyter } from "./display.mjs";
 import { createHandler } from "./evaluator.mjs";
@@ -68,6 +71,82 @@ const jupyter = createJupyter({
 let cdn = DEFAULT_CDN;
 
 
+// --- The host page (#384) -----------------------------------------------------
+// Requests to the page's `host` handler (src/browser/target.ts), and events
+// it sends. Preload modules get this object; cells only through them.
+const hostCalls = new Map();
+const hostListeners = new Set();
+let nextHostId = 0;
+
+function hostError(error) {
+  const err = new Error(String(error?.message ?? "the host request failed"));
+  if (typeof error?.name === "string") err.name = error.name;
+  if (error?.code !== undefined) err.code = error.code;
+  return err;
+}
+
+const host = {
+  /** Resolves with the page's answer; aborting `signal` cancels the call on the page too. */
+  request(method, params, { signal, transfer } = {}) {
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    const id = ++nextHostId;
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        hostCalls.delete(id);
+        post({ kind: "host", id, cancel: true });
+        reject(signal.reason);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      const done = () => signal?.removeEventListener("abort", onAbort);
+      try {
+        globalThis.postMessage({ kind: "host", id, method, params }, transfer ?? []);
+      } catch (err) {
+        done(); // params structured clone can't copy
+        throw err;
+      }
+      hostCalls.set(id, { resolve, reject, done });
+    });
+  },
+  /** Calls `listener(event, value)` for each event the page sends; returns a function that stops it. */
+  onEvent(listener) {
+    hostListeners.add(listener);
+    return () => hostListeners.delete(listener);
+  },
+};
+
+function receiveHost(msg) {
+  if (msg.id === undefined) {
+    for (const listener of hostListeners) {
+      try {
+        listener(msg.event, msg.value);
+      } catch (err) {
+        reportUncaught("Uncaught", err);
+      }
+    }
+    return;
+  }
+  const call = hostCalls.get(msg.id);
+  if (!call) return; // cancelled
+  hostCalls.delete(msg.id);
+  call.done();
+  if (msg.error !== undefined) call.reject(hostError(msg.error));
+  else call.resolve(msg.result);
+}
+
+// Each module is imported in order, and a default export that is a function
+// is called with the host. A module that fails is reported, and the kernel
+// runs without it.
+async function preload(urls, base) {
+  for (const specifier of Array.isArray(urls) ? urls : []) {
+    try {
+      const mod = await import(new URL(specifier, base).href);
+      if (typeof mod.default === "function") await mod.default({ host, jupyter: jupyter.namespace });
+    } catch (err) {
+      reportUncaught(`Preloading ${specifier} failed`, err);
+    }
+  }
+}
+
 // --- The shim cells and the evaluator use -----------------------------------
 let handle = null;
 
@@ -83,6 +162,8 @@ function install({ base, cdn: cdnBase }) {
     resolvePath,
     barrier: () => 0,
     broadcastResult: jupyter.broadcastResult,
+    // execute_request's user_expressions (#340).
+    formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
     async commDispatch(msgType, content, metadata, buffers64) {
       const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
       return await jupyter.commDispatch(msgType, content, metadata, buffers);
@@ -104,6 +185,7 @@ function install({ base, cdn: cdnBase }) {
 async function answer(req) {
   if (req.op === "info") {
     install(req);
+    await preload(req.preload, req.base);
     return { userAgent: globalThis.navigator?.userAgent ?? "" };
   }
   if (handle === null) throw new Error("the driver wasn't sent info first");
@@ -112,6 +194,7 @@ async function answer(req) {
 
 globalThis.addEventListener("message", (event) => {
   const req = event.data;
+  if (req?.op === "host") return receiveHost(req);
   answer(req).then(
     (reply) => post({ kind: "reply", id: req.id, ...reply }),
     (err) => post({ kind: "reply", id: req.id, failure: String(err?.stack ?? err) }),

package/runtime/evaluator.mjs

@@ -56,6 +56,8 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
       case "broadcast":
         await shim.broadcastResult(request.count, take(request.handle));
         return {};
+      case "format":
+        return { value: await shim.formatJson(request.handle === undefined ? undefined : take(request.handle)) };
       case "describe":
         return { value: shim.describeError(take(request.handle)) };
       case "comm":

package/runtime/workerd-worker.mjs

@@ -141,6 +141,8 @@ function install(env) {
     resolvePath,
     barrier: () => 0,
     broadcastResult: jupyter.broadcastResult,
+    // execute_request's user_expressions (#340).
+    formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
     async commDispatch(msgType, content, metadata, buffers64) {
       const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
       return await jupyter.commDispatch(msgType, content, metadata, buffers);