@tlockney/cdp-kernel 0.4.0 → 0.5.0

package/dist/kernel.js

@@ -7,7 +7,7 @@
 import { Buffer } from "node:buffer";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
-import { decodeMessage, encodeMessage, PROTOCOL_VERSION, verify } from "./wire.js";
+import { decodeMessage, encodeMessage, makeHeader, PROTOCOL_VERSION, verify } from "./wire.js";
 import { PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
 import { Interrupted, Target } from "./target.js";
 import { BunTarget } from "./bun-target.js";
@@ -28,6 +28,10 @@ export function parseConnectionInfo(json) {
         if (typeof info[port] !== "number")
             throw new Error(`connection file: missing ${port}`);
     }
+    for (const field of ["ip", "key"]) {
+        if (info[field] !== undefined && typeof info[field] !== "string")
+            throw new Error(`connection file: ${field} is not a string`);
+    }
     if (info.transport !== undefined && info.transport !== "tcp") {
         throw new Error(`unsupported transport ${info.transport}; only tcp is implemented`);
     }
@@ -46,6 +50,18 @@ export function parseConnectionInfo(json) {
         hb_port: info.hb_port,
     };
 }
+/** How long interrupt_request may wait on the target before it's answered anyway (#121). */
+const INTERRUPT_REPLY_WAIT_MS = 5_000;
+const NO_INPUT = { value: null, interrupted: false };
+/** Shell requests other than execute_request, and their reply types. */
+const SHELL_REPLIES = {
+    kernel_info_request: "kernel_info_reply",
+    complete_request: "complete_reply",
+    is_complete_request: "is_complete_reply",
+    inspect_request: "inspect_reply",
+    history_request: "history_reply",
+    comm_info_request: "comm_info_reply",
+};
 export class Kernel {
     #conn;
     #runtime;
@@ -69,6 +85,16 @@ export class Kernel {
     #parent = {};
     #allowStdin = false;
     #executing = false;
+    /**
+     * stop_on_error (#123): how many of the shell messages queued when a cell
+     * failed are still to come, and whether the one being handled is one.
+     */
+    #abortQueued = 0;
+    #aborting = false;
+    /** The input_request waiting for its input_reply, if any. */
+    #input = null;
+    /** An interrupt is waiting on the target. */
+    #interrupting = false;
     // Open comms, for comm_info_request: comm_id -> target_name (#9).
     #comms = new Map();
     #shuttingDown = false;
@@ -90,8 +116,17 @@ export class Kernel {
         // Start the runtime eagerly so the first cell doesn't pay for it.
         this.#ensureTarget().catch((err) => this.#log(`target failed to start: ${err}`));
         process.on("SIGINT", () => void this.#interrupt());
+        // Exiting runs the exit hook that kills the runtime (src/children.ts);
+        // these signals' default action would skip it (#218).
+        for (const [signal, code] of [["SIGTERM", 143], ["SIGHUP", 129]]) {
+            process.on(signal, () => {
+                this.#shuttingDown = true;
+                process.exit(code);
+            });
+        }
         await Promise.all([this.#loop(this.#shell, (m, p) => this.#handleShell(m, p)),
-            this.#loop(this.#control, (m, p) => this.#handleControl(m, p))]);
+            this.#loop(this.#control, (m, p) => this.#handleControl(m, p)),
+            this.#loop(this.#stdin, (m) => this.#handleStdin(m))]);
     }
     #log(text) {
         process.stderr.write(`[cdp-kernel] ${text}\n`);
@@ -205,9 +240,11 @@ export class Kernel {
     #targetEvents() {
         return {
             stream: (name, text) => this.#publish("stream", { name, text }),
-            message: (msg) => void this.#onTargetMessage(msg),
+            message: (msg) => void this.#onTargetMessage(msg).catch((err) => this.#log(`error handling target message: ${err}`)),
             exit: (code, note) => {
                 this.#target = null;
+                // Its prompt, if any, died with it; a late reply is dropped.
+                this.#input = null;
                 void this.#debugger?.attachTarget(null);
                 if (!this.#shuttingDown) {
                     const text = note ?? `[cdp-kernel] ${this.#runtime} exited (${code}); restarting on next cell`;
@@ -225,18 +262,37 @@ export class Kernel {
             });
             return;
         }
-        let value = null;
+        // The answer goes to the target that asked, not one started since.
+        const target = this.#target;
+        let answer = NO_INPUT;
         try {
-            value = await this.#requestInput(msg.prompt, msg.password);
+            answer = await this.#requestInput(msg.prompt, msg.password);
         }
         finally {
             // Always answer exactly once so the target's blocking read returns.
-            this.#target?.replyInput(value);
+            if (target !== null && target === this.#target)
+                target.replyInput(answer.value, answer.interrupted);
         }
     }
     async #interrupt() {
-        if (this.#target && this.#executing)
+        // A target blocked reading its prompt's answer can't run
+        // terminateExecution, and would never answer it. Make the prompt throw
+        // instead, which ends the cell (#121).
+        const input = this.#input;
+        if (input !== null) {
+            this.#input = null;
+            input.settle({ value: null, interrupted: true });
+            return;
+        }
+        if (!this.#target || !this.#executing)
+            return;
+        this.#interrupting = true;
+        try {
             await this.#target.interrupt();
+        }
+        finally {
+            this.#interrupting = false;
+        }
     }
     // --- messaging --------------------------------------------------------------
     #encode(msgType, content, parentHeader, extra = {}) {
@@ -254,6 +310,11 @@ export class Kernel {
     async #loop(socket, handle) {
         while (!this.#shuttingDown) {
             const { peer, frames } = await socket.recv();
+            if (socket === this.#shell) {
+                this.#aborting = this.#abortQueued > 0;
+                if (this.#aborting)
+                    this.#abortQueued--;
+            }
             try {
                 const msg = decodeMessage(frames);
                 // Unsigned or forged messages are dropped, as in Deno.
@@ -292,40 +353,48 @@ export class Kernel {
     }
     // --- control channel ------------------------------------------------------
     async #handleControl(msg, peer) {
+        // Every request is wrapped in busy/idle, as on shell (#124). JupyterLab
+        // treats a debug request as done only once the kernel reports idle for
+        // it. (Jupyter Server leaves debug_request out of the kernel's status.)
+        this.#status("busy", msg.header);
+        try {
+            await this.#controlRequest(this.#control, msg, peer);
+        }
+        finally {
+            this.#status("idle", msg.header);
+        }
+    }
+    /** Control requests; shutdown and interrupt may also arrive on shell (#124). */
+    async #controlRequest(socket, msg, peer) {
         switch (msg.header.msg_type) {
             case "kernel_info_request":
-                this.#reply(this.#control, peer, msg, "kernel_info_reply", this.#kernelInfo());
+                this.#reply(socket, peer, msg, "kernel_info_reply", this.#kernelInfo());
                 break;
             case "interrupt_request":
-                await this.#interrupt();
-                this.#reply(this.#control, peer, msg, "interrupt_reply", { status: "ok" });
+                // Answer even if the target doesn't (#121); the interrupt goes on.
+                await Promise.race([
+                    this.#interrupt().catch((err) => this.#log(`interrupt failed: ${err}`)),
+                    new Promise((r) => setTimeout(r, INTERRUPT_REPLY_WAIT_MS)),
+                ]);
+                this.#reply(socket, peer, msg, "interrupt_reply", { status: "ok" });
                 break;
             case "debug_request": {
-                // JupyterLab treats a debug request as done only once the kernel
-                // reports idle for it, as ipykernel does for control messages.
-                // (Jupyter Server leaves debug_request out of the kernel's status.)
-                this.#status("busy", msg.header);
                 let reply;
-                try {
-                    if (this.#debugger === null) {
-                        reply = { type: "response", request_seq: msg.content.seq, command: msg.content.command, success: false, message: `${this.#runtime} targets have no debugger`, body: {} };
-                    }
-                    else {
-                        // Everything but debugInfo talks to the target, so make sure there is one.
-                        if (msg.content.command !== "debugInfo")
-                            await this.#ensureTarget().catch(() => null);
-                        reply = await this.#debugger.handle(msg.content);
-                    }
-                    this.#reply(this.#control, peer, msg, "debug_reply", reply);
+                if (this.#debugger === null) {
+                    reply = { type: "response", request_seq: msg.content.seq, command: msg.content.command, success: false, message: `${this.#runtime} targets have no debugger`, body: {} };
                 }
-                finally {
-                    this.#status("idle", msg.header);
+                else {
+                    // Everything but debugInfo talks to the target, so make sure there is one.
+                    if (msg.content.command !== "debugInfo")
+                        await this.#ensureTarget().catch(() => null);
+                    reply = await this.#debugger.handle(msg.content);
                 }
+                this.#reply(socket, peer, msg, "debug_reply", reply);
                 break;
             }
             case "shutdown_request": {
                 const restart = msg.content.restart === true;
-                this.#reply(this.#control, peer, msg, "shutdown_reply", { status: "ok", restart });
+                this.#reply(socket, peer, msg, "shutdown_reply", { status: "ok", restart });
                 this.#shuttingDown = true;
                 this.#target?.kill();
                 // Frontends spawn a fresh kernel even on restart; exit after the
@@ -367,8 +436,27 @@ export class Kernel {
                 case "comm_close":
                     await this.#handleComm(msg);
                     break;
+                case "shutdown_request":
+                case "interrupt_request":
+                    // Deprecated on shell, but still allowed, and ipykernel takes them.
+                    await this.#controlRequest(this.#shell, msg, peer);
+                    break;
+                default:
+                    this.#log(`ignoring unknown shell message ${type}`);
             }
         }
+        catch (err) {
+            // E.g. the runtime failed to launch. Answer anyway, so the frontend
+            // doesn't wait on the request forever (#125).
+            const replyType = SHELL_REPLIES[type];
+            if (replyType !== undefined) {
+                const name = err instanceof Error ? err.name : "Error";
+                const message = err instanceof Error ? err.message : String(err);
+                const error = { ename: name, evalue: message, traceback: [`${name}: ${message}`] };
+                this.#reply(this.#shell, peer, msg, replyType, { status: "error", ...error });
+            }
+            throw err;
+        }
         finally {
             this.#status("idle", msg.header);
         }
@@ -417,23 +505,41 @@ export class Kernel {
         };
     }
     async #requestInput(prompt, password) {
+        // The target asked while an interrupt was already waiting on it.
+        if (this.#interrupting)
+            return { value: null, interrupted: true };
         const parent = this.#parent;
         if (!this.#allowStdin || typeof parent.msg_id !== "string")
-            return null;
+            return NO_INPUT;
         if (this.#stdin.peers.size === 0)
             await new Promise((r) => setTimeout(r, 100));
         if (this.#stdin.peers.size === 0)
-            return null;
-        this.#stdin.sendAll(this.#encode("input_request", { prompt, password }, parent));
-        for (;;) {
-            const { frames } = await this.#stdin.recv();
-            const reply = decodeMessage(frames);
-            if (!verify(this.#conn.key, reply.signedParts, reply.sig))
-                continue;
-            if (reply.header.msg_type === "input_reply") {
-                return typeof reply.content.value === "string" ? reply.content.value : null;
-            }
-        }
+            return NO_INPUT;
+        const header = makeHeader(this.#session, "input_request");
+        const answer = new Promise((settle) => (this.#input = { msgId: header.msg_id, settle }));
+        this.#stdin.sendAll(encodeMessage(this.#session, this.#conn.key, "input_request", { prompt, password }, {
+            header,
+            parentHeader: parent,
+        }));
+        return answer;
+    }
+    /** stdin carries only input_replys. */
+    async #handleStdin(reply) {
+        if (reply.header.msg_type !== "input_reply")
+            return;
+        const input = this.#input;
+        // A reply with nothing waiting is late (its prompt was interrupted), and
+        // one naming another request is for an earlier prompt: drop both rather
+        // than answer the next prompt with them (#121). Some clients
+        // (jupyter_client's input()) send no parent header, so only a present
+        // one is checked.
+        if (input === null)
+            return;
+        const parentId = reply.parentHeader.msg_id;
+        if (typeof parentId === "string" && parentId !== "" && parentId !== input.msgId)
+            return;
+        this.#input = null;
+        input.settle({ value: typeof reply.content.value === "string" ? reply.content.value : null, interrupted: false });
     }
     async #evaluateCell(target, code) {
         // Object-literal wrapping (Deno's evaluate_line_with_object_wrapping):
@@ -458,6 +564,13 @@ export class Kernel {
     }
     async #execute(msg, peer) {
         const parent = msg.header;
+        if (this.#aborting) {
+            // Queued behind a failed cell: not run, not counted (#123).
+            this.#status("busy", parent);
+            this.#reply(this.#shell, peer, msg, "execute_reply", { status: "aborted" });
+            this.#status("idle", parent);
+            return;
+        }
         const code = String(msg.content.code ?? "");
         const silent = msg.content.silent === true;
         if (!silent && msg.content.store_history !== false) {
@@ -468,7 +581,9 @@ export class Kernel {
         this.#parent = parent;
         this.#allowStdin = msg.content.allow_stdin === true;
         this.#status("busy", parent);
-        this.#publish("execute_input", { code, execution_count: count });
+        // Silent requests broadcast nothing on iopub but status (#124).
+        if (!silent)
+            this.#publish("execute_input", { code, execution_count: count });
         if (this.#projectWarning !== null) {
             // Shown once, in the first cell, where the user will see it.
             this.#publish("stream", { name: "stderr", text: `[cdp-kernel] ${this.#projectWarning}\n` });
@@ -518,6 +633,13 @@ export class Kernel {
             this.#executing = false;
         }
         if (error) {
+            if (!silent && msg.content.stop_on_error !== false) {
+                // Abort what was queued behind this cell (JupyterLab's Run All sends
+                // every cell at once), but nothing sent after the client sees the
+                // error. A macrotask first lets bytes already received be parsed.
+                await new Promise((r) => setTimeout(r, 0));
+                this.#abortQueued = this.#shell.incoming.size;
+            }
             this.#publish("error", error);
             this.#reply(this.#shell, peer, msg, "execute_reply", { status: "error", execution_count: count, ...error });
         }

package/dist/mod.d.ts

@@ -1,7 +1,9 @@
 /**
- * cdp-kernel: Deno's Jupyter kernel, extracted to run notebook cells in any
- * runtime whose inspector speaks the Chrome DevTools Protocol (Node and
- * Deno today).
+ * cdp-kernel: a Jupyter kernel for TypeScript and JavaScript, extracted from
+ * Deno's, that runs notebooks on several JavaScript runtimes. The kernel host
+ * runs on Node or Deno; cells run in a separate target runtime: Node or Deno
+ * over the Chrome DevTools Protocol, or Bun, workerd and celld, which
+ * evaluate cells in-process.
  *
  * Most people want the CLI (`cdp-kernel install`). This module exposes
  * the kernel for embedding: give it a parsed connection file and a target

package/dist/mod.js

@@ -1,7 +1,9 @@
 /**
- * cdp-kernel: Deno's Jupyter kernel, extracted to run notebook cells in any
- * runtime whose inspector speaks the Chrome DevTools Protocol (Node and
- * Deno today).
+ * cdp-kernel: a Jupyter kernel for TypeScript and JavaScript, extracted from
+ * Deno's, that runs notebooks on several JavaScript runtimes. The kernel host
+ * runs on Node or Deno; cells run in a separate target runtime: Node or Deno
+ * over the Chrome DevTools Protocol, or Bun, workerd and celld, which
+ * evaluate cells in-process.
  *
  * Most people want the CLI (`cdp-kernel install`). This module exposes
  * the kernel for embedding: give it a parsed connection file and a target

package/dist/package.d.ts

@@ -1,11 +1,11 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export declare const RELEASE_DATE = "2026-10-15";
+export declare const RELEASE_DATE = "2026-10-16";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It

package/dist/package.js

@@ -14,13 +14,13 @@ import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export const RELEASE_DATE = "2026-10-15";
+export const RELEASE_DATE = "2026-10-16";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It
@@ -82,7 +82,7 @@ export function kernelArgv(host, execPath, origin, args) {
     return [execPath, "run", "--allow-all", ...flags, entry, ...args];
 }
 export function cacheRoot() {
-    const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    const base = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
     return join(base, "cdp-kernel");
 }
 async function fetchText(url) {

package/dist/target.d.ts

@@ -3,7 +3,7 @@ import { type CellTransformOptions, transformCell } from "./transform.ts";
 import type { DebugChannel } from "./debugger.ts";
 /** Targets driven over CDP. */
 export type CdpRuntime = "node" | "deno";
-/** Bun and workerd have their own backends: src/bun-target.ts, src/workerd-target.ts. */
+/** Bun, workerd and celld have their own backends: src/bun-target.ts, src/workerd-target.ts, src/celld-target.ts. */
 export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
 /** What the kernel needs from a target runtime. */
 export interface KernelTarget {
@@ -42,7 +42,8 @@ export interface KernelTarget {
     inspect(path: string, detail: number): Promise<string | null>;
     /** The Debugger domain, on targets driven over CDP (#18). */
     readonly debug?: DebugChannel;
-    replyInput(value: string | null): void;
+    /** Answers the target's pending prompt; `interrupted` makes it throw instead (#121). */
+    replyInput(value: string | null, interrupted?: boolean): void;
     kill(): void;
 }
 export interface LaunchOptions {
@@ -56,6 +57,13 @@ export declare function launchCommand(runtime: CdpRuntime, bootstrap: string, {
     cmd: string;
     args: string[];
 };
+/**
+ * The esbuild binary this host's esbuild runs, for a Node target to compile
+ * imported TypeScript Node can't strip (#73); null when it can't be found.
+ * Resolved from esbuild's own location, so it's found in a node_modules
+ * install and in Deno's npm cache alike.
+ */
+export declare function esbuildBinary(resolve?: (specifier: string) => string, platform?: string, arch?: string): string | null;
 /** Messages the bootstrap sends through the CDP binding. */
 export type TargetMessage = {
     kind: "iopub";
@@ -70,6 +78,8 @@ export type TargetMessage = {
     password: boolean;
     barrier: number;
 };
+/** The parsed value, or undefined for text that isn't JSON. */
+export declare function parseJson(text: string): unknown;
 export declare function isTargetMessage(value: unknown): value is TargetMessage;
 /**
  * Splits one output pipe into text and barrier markers, and releases them
@@ -88,6 +98,19 @@ export declare class PipeDemux {
     /** Release everything (the process died). */
     close(): void;
 }
+/**
+ * Removes the runtime's own stderr lines (see INSPECTOR_CHATTER) and passes
+ * everything else on. A chatter line can arrive split across chunks, so a
+ * trailing partial line that could still turn out to be one is held back
+ * until its newline arrives; any other partial line passes straight through.
+ */
+export declare class StderrFilter {
+    #private;
+    constructor(runtime: CdpRuntime, emit: (text: string) => void);
+    push(chunk: string): void;
+    /** Releases a held partial line (the process died). */
+    flush(): void;
+}
 /** Promises keyed by barrier number, resolvable before or after first use. */
 export declare class Gates {
     #private;
@@ -118,6 +141,7 @@ export declare class Target implements KernelTarget {
         executable?: string;
         denoCompat?: boolean;
         denoConfig?: string;
+        startTimeoutMs?: number;
     }): Promise<Target>;
     /** The Debugger domain on this target's session, for src/debugger.ts. */
     get debug(): DebugChannel;
@@ -133,6 +157,10 @@ export declare class Target implements KernelTarget {
      * evaluate is abandoned here and the session stays usable.
      */
     interrupt(): Promise<void>;
+    /**
+     * For synchronous functions. With awaitPromise the inspector would wrap
+     * even a plain return value in a promise it holds only weakly (#55).
+     */
     callFunctionOn(functionDeclaration: string, args: CdpParams[]): Promise<CdpParams>;
     /** The broadcastResult step of Deno's execute flow (jupyter/mod.rs). */
     broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
@@ -158,6 +186,6 @@ export declare class Target implements KernelTarget {
     propertyNames(expression: string): Promise<string[]>;
     inspect(path: string, detail: number): Promise<string | null>;
     lexicalNames(): Promise<string[]>;
-    replyInput(value: string | null): void;
+    replyInput(value: string | null, interrupted?: boolean): void;
     kill(): void;
 }