@tlockney/cdp-kernel 0.7.1 → 0.8.0

package/dist/workerd-target.js

@@ -18,10 +18,10 @@ 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, lstatSync, 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";
@@ -30,6 +30,7 @@ import { runtimeDir } from "./package.js";
 import { killOnExit } from "./children.js";
 import { Interrupted, isTargetMessage, parseBundle, parseJson } from "./target.js";
 import { withStartTimeout } from "./target-api.js";
+import { processesUsage } from "./usage.js";
 import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
 import { ensureInstalledAsync, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
@@ -88,6 +89,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);
@@ -265,13 +310,16 @@ export class RawWorkerd {
     runtime;
     channel;
     #child;
+    get pids() {
+        return this.#child.pid === undefined ? [] : [this.#child.pid];
+    }
     constructor(child, channel, runtime) {
         this.#child = child;
         this.channel = channel;
         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,
@@ -365,9 +413,13 @@ export class WorkerdTarget {
     /** Requests that interrupt() abandons when the driver can still answer. */
     #interruptible = new Set();
     #nextId = 0;
-    #interrupted = false;
+    /** Counts interrupt() calls: a call that saw one start during it was interrupted (#417). */
+    #interrupts = 0;
+    /** Cells running: a comm handler that starts with none gets its own jupyter.signal (#421). */
+    #cells = 0;
     #stopNote;
     #exitedOnce = false;
+    #startedAt = Date.now();
     constructor(host, cwd, events, runtime) {
         this.runtime = runtime;
         this.#host = host;
@@ -486,17 +538,26 @@ export class WorkerdTarget {
         });
     }
     async #interruptibly(op, params, what) {
-        this.#interrupted = false;
+        const interrupts = this.#interrupts;
         try {
             return await this.#request(op, params, true);
         }
         catch (err) {
-            if (err instanceof Abandoned || this.#interrupted)
+            if (err instanceof Abandoned || this.#interrupts !== interrupts)
                 throw new Interrupted(`${what} interrupted`);
             throw err;
         }
     }
     async evaluate(script) {
+        this.#cells++;
+        try {
+            return await this.#evaluate(script);
+        }
+        finally {
+            this.#cells--;
+        }
+    }
+    async #evaluate(script) {
         const modules = {};
         for (const specifier of importSpecifiers(script)) {
             if (BUILTIN.test(specifier) || this.#sent.has(specifier))
@@ -516,11 +577,14 @@ export class WorkerdTarget {
     /**
      * A cell that's waiting on something leaves the driver free: it answers a
      * ping, and the cell is abandoned with the session intact (its pending
-     * work still runs, as on Bun). A busy cell can't be reached, so workerd is
-     * stopped and restarts on the next cell.
+     * work still runs, as on Bun, and jupyter.signal tells it to stop). A busy
+     * cell can't be reached, so workerd is stopped and restarts on the next
+     * cell.
      */
     async interrupt() {
-        this.#interrupted = true;
+        this.#interrupts++;
+        // Before abandoning the cell's request, which ends the count.
+        const cellRunning = this.#cells > 0;
         const running = [...this.#interruptible];
         const answered = await Promise.race([
             this.#request("ping").then(() => true, () => false),
@@ -532,6 +596,10 @@ export class WorkerdTarget {
                 this.#pending.delete(id);
                 this.#interruptible.delete(id);
             }
+            // After the cell is abandoned, so its reply can't end it first
+            // (#418). Not awaited: requests are answered in order, and an abort
+            // listener that never returns mustn't hold up the interrupt.
+            void this.#request("abort", { cell: cellRunning }).catch(() => { });
             return;
         }
         this.#stopNote = restartNote(this.runtime);
@@ -552,6 +620,7 @@ export class WorkerdTarget {
             content,
             metadata,
             buffers: buffers.map((b) => Buffer.from(b).toString("base64")),
+            ownSignal: this.#cells === 0,
         }, "Comm handler");
         if (isRecord(reply.error)) {
             const { name, message, stack } = reply.error;
@@ -584,6 +653,11 @@ export class WorkerdTarget {
     }
     /** Never asked for: prompt() in workerd answers null without asking. */
     replyInput() { }
+    /** The workerd processes' resident memory and CPU time, from the OS (#410). */
+    async usage() {
+        const pids = this.#host.pids ?? [];
+        return { startedAt: this.#startedAt, ...(await processesUsage(pids)) };
+    }
     kill() {
         // workerd's graceful shutdown waits for open connections, the session
         // included, so close it first.

package/dist/workers-project.js

@@ -132,8 +132,10 @@ class MiniflareHost {
     #exitListeners = [];
     #stopped = false;
     #forget;
+    pids;
     constructor(mf, channel, version, project, workerd) {
         this.#mf = mf;
+        this.pids = workerd;
         // Miniflare kills its workerd only on a normal exit; the helper in
         // src/children.ts kills it if this process is SIGKILLed (#241).
         this.#forget = workerd.map(reap);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on Node, Deno, Bun, workerd and celld",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",

package/runtime/bootstrap.mjs

@@ -97,7 +97,9 @@ const jupyter = createJupyter({
     const reply = JSON.parse(line);
     if (reply.interrupted === true) {
       // Interrupted while waiting for the answer: unwind the cell, as
-      // KeyboardInterrupt does in Python's input() (#121).
+      // KeyboardInterrupt does in Python's input() (#121). The host
+      // doesn't interrupt the target then, so abort jupyter.signal here.
+      jupyter.abortSignal(reply.cell !== false);
       const err = new Error("Execution interrupted");
       err.name = "Interrupted";
       throw err;
@@ -217,6 +219,10 @@ globalThis.__cdpk = {
   broadcastResult: jupyter.broadcastResult,
   // execute_request's user_expressions (#340).
   formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
+  // jupyter.signal (#418, #421): a new one as each cell starts; the host
+  // aborts the running ones on interrupt.
+  startCell: jupyter.startCell,
+  abortSignal: jupyter.abortSignal,
   // 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) {
@@ -225,10 +231,10 @@ globalThis.__cdpk = {
   },
   // Frontend comm messages (#9), from the host's shell channel. Handlers
   // run after one macrotask, like cells, so interrupt can reach them.
-  async commDispatch(msgType, content, metadata, buffers64) {
+  async commDispatch(msgType, content, metadata, buffers64, ownSignal) {
     await yieldTask();
     const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
-    return await jupyter.commDispatch(msgType, content, metadata, buffers);
+    return await jupyter.commDispatch(msgType, content, metadata, buffers, ownSignal);
   },
   // The same, for a message the host wrote to stdin (Node and Deno). A
   // value passed as a CDP call argument is compiled as source, and V8's
@@ -236,8 +242,23 @@ globalThis.__cdpk = {
   // each message's data would stay in memory (#287). Read before the first
   // await, so messages are taken in the order the host wrote them.
   commDispatchFromStdin() {
-    const { msgType, content, metadata, buffers } = readCommRecord();
-    return globalThis.__cdpk.commDispatch(msgType, content, metadata, buffers);
+    const dispatch = () => {
+      const { msgType, content, metadata, buffers, ownSignal } = readCommRecord();
+      return globalThis.__cdpk.commDispatch(msgType, content, metadata, buffers, ownSignal === true);
+    };
+    // Node's inspector can run this call in the middle of a blocking stdin
+    // read, e.g. a prompt's, when the message came on a kernel subshell
+    // (#417): reading then would take bytes from the middle of that read.
+    if (stdinReading) {
+      const resumed = new Promise((resolve) => afterStdinRead.push(resolve));
+      // A read is synchronous, so by the next task it has ended. If the flag
+      // is still set, an interrupt terminated the read before its finally.
+      yieldTask().then(() => {
+        if (stdinReading) endStdinRead();
+      });
+      return resumed.then(dispatch);
+    }
+    return dispatch();
   },
   describeError(value) {
     if (value instanceof Error) {
@@ -445,18 +466,55 @@ function readLine() {
   }
 }
 
-/** The next prompt reply's line, past any comm record left unread. */
+/**
+ * Comm records read while waiting for a prompt's reply. A comm message on
+ * a kernel subshell (#417) can be written while a cell waits in input();
+ * its dispatch runs after, and takes it from here.
+ */
+const commRecords = [];
+
+/** Whether a read from stdin is in progress, and what waits for it to end. */
+let stdinReading = false;
+const afterStdinRead = [];
+
+function readingStdin(read) {
+  stdinReading = true;
+  try {
+    return read();
+  } finally {
+    endStdinRead();
+  }
+}
+
+function endStdinRead() {
+  stdinReading = false;
+  // In order, so comm records are taken as the host wrote them.
+  for (const resume of afterStdinRead.splice(0)) resume();
+}
+
+/** The next prompt reply's line; comm records before it are kept. */
 function readInputReply() {
+  return readingStdin(readInputReplyNow);
+}
+
+function readInputReplyNow() {
   for (;;) {
     const line = readLine();
     const comm = line === null ? null : COMM_HEADER.exec(line);
     if (comm === null) return line;
-    readExactly(Number(comm[1]));
+    const body = readExactly(Number(comm[1]));
+    if (body !== null) commRecords.push(body);
   }
 }
 
 /** The next comm message, past any prompt reply left unread. */
 function readCommRecord() {
+  return readingStdin(readCommRecordNow);
+}
+
+function readCommRecordNow() {
+  const kept = commRecords.shift();
+  if (kept !== undefined) return JSON.parse(new TextDecoder().decode(kept));
   for (;;) {
     const line = readLine();
     if (line === null) throw new Error("stdin closed before a comm message arrived");

package/runtime/browser-worker.mjs

@@ -164,9 +164,13 @@ function install({ base, cdn: cdnBase }) {
     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) {
+    // jupyter.signal (#418, #421): a new one as each cell starts; the host
+    // aborts the running ones on interrupt.
+    startCell: jupyter.startCell,
+    abortSignal: jupyter.abortSignal,
+    async commDispatch(msgType, content, metadata, buffers64, ownSignal) {
       const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
-      return await jupyter.commDispatch(msgType, content, metadata, buffers);
+      return await jupyter.commDispatch(msgType, content, metadata, buffers, ownSignal);
     },
     describeError(value) {
       if (value instanceof Error) {

package/runtime/display.d.mts

@@ -42,6 +42,12 @@ export interface JupyterNamespace {
   comm: CommApi;
   /** An anywidget-compatible widget; display the result to show it. */
   widget(options: WidgetOptions): Widget;
+  /**
+   * Aborted when the kernel interrupts this cell. Each cell gets its own,
+   * as does a comm handler that starts while no cell runs. Read it when
+   * the work starts: a later read gets the signal of whatever started last.
+   */
+  readonly signal: AbortSignal;
 }
 
 export interface Jupyter {
@@ -51,8 +57,24 @@ export interface Jupyter {
   formatNow(obj: unknown): unknown;
   confirm(message?: string): boolean;
   prompt(message?: string, defaultValue?: string, options?: { password?: boolean }): string | null;
-  /** Routes a frontend comm message into the kernel's comms. */
-  commDispatch: Comms["dispatch"];
+  /**
+   * Routes a frontend comm message into the kernel's comms. `ownSignal`
+   * (no cell is running) gives its handlers their own jupyter.signal.
+   */
+  commDispatch(
+    msgType: string,
+    content: { [key: string]: unknown },
+    metadata: { [key: string]: unknown },
+    buffers: Uint8Array[],
+    ownSignal?: boolean,
+  ): Promise<boolean>;
+  /** A new jupyter.signal: a cell is starting (#421). */
+  startCell(): void;
+  /**
+   * Aborts the running comm handlers' jupyter.signal, and the last cell's
+   * unless `cellRunning` is false: the kernel was interrupted.
+   */
+  abortSignal(cellRunning?: boolean): void;
 }
 
 export function escapeHTML(str: string): string;

package/runtime/display.mjs

@@ -441,8 +441,47 @@ export function createJupyter(host) {
 
   const comms = createComms((msgType, content, metadata, buffers) => host.send(msgType, content, metadata, buffers));
 
+  // jupyter.signal (#418): aborted when the kernel is interrupted, so cell
+  // code can stop waiting on what the interrupt can't reach, such as a comm
+  // reply. Each cell gets its own, as does a comm handler that starts while
+  // no cell runs; a handler during a cell shares the cell's. An interrupt
+  // aborts only those of the cell and handlers running (#421).
+  /** The last cell's controller. */
+  let cell = new AbortController();
+  /** What jupyter.signal returns: that of whatever started last. */
+  let current = cell;
+  /** Controllers of running comm handlers, with how many handlers use each. */
+  const handlers = new Map();
+  function startCell() {
+    current = cell = new AbortController();
+  }
+  /** `cellRunning`: the host has a cell in flight, so the last cell's signal is aborted too. */
+  function abortSignal(cellRunning = true) {
+    const reason = new DOMException("Execution interrupted", "AbortError");
+    if (cellRunning) cell.abort(reason);
+    for (const controller of handlers.keys()) controller.abort(reason);
+    handlers.clear();
+  }
+  async function commDispatch(msgType, content, metadata, buffers, ownSignal = false) {
+    // A handler during a cell shares the cell's signal, and is tracked
+    // apart from it: it can outlive the cell.
+    const controller = ownSignal ? new AbortController() : cell;
+    if (ownSignal) current = controller;
+    handlers.set(controller, (handlers.get(controller) ?? 0) + 1);
+    try {
+      return await comms.dispatch(msgType, content, metadata, buffers);
+    } finally {
+      const left = (handlers.get(controller) ?? 0) - 1;
+      if (left > 0) handlers.set(controller, left);
+      else handlers.delete(controller);
+    }
+  }
+
   return {
     namespace: {
+      get signal() {
+        return current.signal;
+      },
       broadcast,
       display,
       format,
@@ -458,6 +497,8 @@ export function createJupyter(host) {
     formatNow,
     confirm,
     prompt,
-    commDispatch: comms.dispatch,
+    commDispatch,
+    startCell,
+    abortSignal,
   };
 }

package/runtime/evaluator.d.mts

@@ -2,12 +2,16 @@
 export interface EvaluatorShim {
   broadcastResult(executionCount: number, value: unknown): void | Promise<void>;
   describeError(value: unknown): string;
-  commDispatch(msgType: string, content: object, metadata: object, buffers64: string[]): Promise<unknown>;
+  commDispatch(msgType: string, content: object, metadata: object, buffers64: string[], ownSignal?: boolean): Promise<unknown>;
   barrier(): number;
   /** inspect_request's text for a dotted path, or null (#10). */
   inspectPath(path: string, detail: number): string | null;
   /** Resolves a dotted path without running getters; see introspect.mjs. */
   resolvePath?(path: string): import("./introspect.mjs").Resolved;
+  /** A new jupyter.signal, as a cell starts (#421). */
+  startCell?(): void;
+  /** Aborts the running cell's and comm handlers' jupyter.signal, after an interrupt (#418). */
+  abortSignal?(cellRunning?: boolean): void;
 }
 
 /** A request from the host: an `op` plus its parameters. */

package/runtime/evaluator.mjs

@@ -44,6 +44,7 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
       case "eval": {
         // The host uses a result's handle before its next cell.
         handles.clear();
+        shim.startCell?.();
         try {
           const box = await evaluate(request.code);
           return { result: box === undefined ? { type: "undefined" } : remote(box[0]) };
@@ -62,7 +63,13 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
         return { value: shim.describeError(take(request.handle)) };
       case "comm":
         try {
-          const handled = await shim.commDispatch(request.msgType, request.content, request.metadata, request.buffers);
+          const handled = await shim.commDispatch(
+            request.msgType,
+            request.content,
+            request.metadata,
+            request.buffers,
+            request.ownSignal === true,
+          );
           return { handled: handled === true };
         } catch (err) {
           return { error: JSON.parse(shim.describeError(err)) };
@@ -86,6 +93,10 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
         return { text: shim.inspectPath(request.path, request.detail ?? 0) };
       case "barrier":
         return { value: shim.barrier() };
+      case "abort":
+        // After an interrupt: jupyter.signal (#418).
+        shim.abortSignal?.(request.cell !== false);
+        return {};
       default:
         throw new Error(`unknown request ${JSON.stringify(request.op)}`);
     }

package/runtime/workerd-worker.mjs

@@ -143,9 +143,13 @@ function install(env) {
     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) {
+    // jupyter.signal (#418, #421): a new one as each cell starts; the host
+    // aborts the running ones on interrupt.
+    startCell: jupyter.startCell,
+    abortSignal: jupyter.abortSignal,
+    async commDispatch(msgType, content, metadata, buffers64, ownSignal) {
       const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
-      return await jupyter.commDispatch(msgType, content, metadata, buffers);
+      return await jupyter.commDispatch(msgType, content, metadata, buffers, ownSignal);
     },
     describeError(value) {
       if (value instanceof Error) {