@tlockney/cdp-kernel 0.3.0 → 0.5.0

package/dist/kernel.js

@@ -7,15 +7,17 @@
 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";
+import { Debugger } from "./debugger.js";
 import { WorkerdTarget } from "./workerd-target.js";
 import { launchCelld } from "./celld-target.js";
 import { CellSyntaxError, objectLiteralCandidate } from "./transform.js";
 import { loadDenoProject } from "./deno-config.js";
-import { checkIsComplete, codePointToUtf16Index, exprAtCursor, utf16ToCodePointIndex } from "./text.js";
+import { checkIsComplete, codePointToUtf16Index, exprAtCursor, inspectTarget, utf16ToCodePointIndex } from "./text.js";
+import { queryHistory } from "./history.js";
 import { VERSION } from "./package.js";
 export function parseConnectionInfo(json) {
     const raw = JSON.parse(json);
@@ -26,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`);
     }
@@ -44,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;
@@ -52,6 +70,10 @@ export class Kernel {
     #project;
     #projectWarning = null;
     #noticeShownFor = null;
+    /** JupyterLab's visual debugger, for targets driven over CDP (#18). */
+    #debugger;
+    /** Cells run with store_history, for history_request (#10). */
+    #history = [];
     #session = randomUUID();
     #shell;
     #control;
@@ -63,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;
@@ -71,6 +103,9 @@ export class Kernel {
         this.#runtime = runtime;
         this.#denoCompat = options.denoCompat ?? false;
         this.#project = runtime === "deno" ? this.#loadProject(options.notebookDir ?? process.cwd()) : null;
+        this.#debugger = runtime === "node" || runtime === "deno"
+            ? new Debugger((event) => this.#publish("debug_event", event), () => this.#transformOptions())
+            : null;
         startHeartbeat(conn.hb_port, conn.ip);
         this.#shell = new RouterSocket(conn.shell_port, conn.ip);
         this.#control = new RouterSocket(conn.control_port, conn.ip);
@@ -81,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`);
@@ -181,7 +225,9 @@ export class Kernel {
     #ensureTarget() {
         if (this.#target)
             return Promise.resolve(this.#target);
-        this.#targetStarting ??= this.#launchTarget().then((target) => {
+        this.#targetStarting ??= this.#launchTarget().then(async (target) => {
+            // Before any cell runs on it, so breakpoints already apply.
+            await this.#debugger?.attachTarget(target.debug ?? null);
             this.#target = target;
             this.#targetStarting = null;
             return target;
@@ -194,9 +240,12 @@ 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`;
                     this.#publish("stream", { name: "stderr", text: `\n${text}\n` });
@@ -213,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 = {}) {
@@ -242,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.
@@ -272,22 +345,56 @@ export class Kernel {
             },
             banner: `cdp-kernel on ${this.#runtime} ${versions?.runtime ?? ""} (${versions?.engine || "?"})`,
             help_links: [],
-            debugger: false,
+            debugger: this.#debugger !== null,
+            // What current ipykernel advertises; JupyterLab itself goes by the
+            // kernelspec's metadata.debugger.
+            supported_features: this.#debugger !== null ? ["debugger"] : [],
         };
     }
     // --- 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": {
+                let 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: {} };
+                }
+                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
@@ -316,10 +423,10 @@ export class Kernel {
                     this.#reply(this.#shell, peer, msg, "is_complete_reply", checkIsComplete(String(msg.content.code ?? "")));
                     break;
                 case "inspect_request":
-                    this.#reply(this.#shell, peer, msg, "inspect_reply", { status: "ok", found: false, data: {}, metadata: {} });
+                    this.#reply(this.#shell, peer, msg, "inspect_reply", await this.#inspect(msg));
                     break;
                 case "history_request":
-                    this.#reply(this.#shell, peer, msg, "history_reply", { status: "ok", history: [] });
+                    this.#reply(this.#shell, peer, msg, "history_reply", { status: "ok", history: queryHistory(this.#history, msg.content) });
                     break;
                 case "comm_info_request":
                     this.#reply(this.#shell, peer, msg, "comm_info_reply", { status: "ok", comms: this.#commInfo(msg.content) });
@@ -329,12 +436,44 @@ 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);
         }
     }
+    /** The tooltip (Shift-Tab) for the name at the cursor (#10). */
+    async #inspect(msg) {
+        const code = String(msg.content.code ?? "");
+        const cursorCp = typeof msg.content.cursor_pos === "number"
+            ? msg.content.cursor_pos
+            : utf16ToCodePointIndex(code, code.length);
+        const path = inspectTarget(code, codePointToUtf16Index(code, cursorCp));
+        const detail = msg.content.detail_level === 1 ? 1 : 0;
+        const text = path === null ? null : await (await this.#ensureTarget()).inspect(path, detail);
+        return text === null
+            ? { status: "ok", found: false, data: {}, metadata: {} }
+            : { status: "ok", found: true, data: { "text/plain": text }, metadata: {} };
+    }
     async #complete(msg) {
         const code = String(msg.content.code ?? "");
         const cursorCp = typeof msg.content.cursor_pos === "number"
@@ -366,31 +505,53 @@ 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):
         // try `({ ... })` first and fall back to the code as written.
+        // While debugging, cells carry the path JupyterLab gave them and keep a
+        // line map, so breakpoints bind and frames point at the cell (#18).
+        const debugging = this.#debugger?.started === true && target.debug !== undefined;
+        const transform = (source) => debugging && this.#debugger ? this.#debugger.cellScript(code, source) : target.transform(source, this.#transformOptions());
         const wrapped = objectLiteralCandidate(code);
         if (wrapped !== null) {
             try {
-                const result = await target.evaluate(target.transform(wrapped, this.#transformOptions()));
+                const result = await target.evaluate(transform(wrapped));
                 if (!result.exceptionDetails)
                     return result;
             }
@@ -399,19 +560,30 @@ export class Kernel {
                     throw err;
             }
         }
-        return target.evaluate(target.transform(code, this.#transformOptions()));
+        return target.evaluate(transform(code));
     }
     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)
+        if (!silent && msg.content.store_history !== false) {
             this.#executionCount++;
+            this.#history.push({ line: this.#executionCount, input: code });
+        }
         const count = this.#executionCount;
         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` });
@@ -461,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/main.js

@@ -42,7 +42,9 @@ function install(runtime, denoCompat, name, display) {
         // Interrupts arrive as interrupt_request on the control channel rather
         // than as SIGINT to this process.
         interrupt_mode: "message",
-        metadata: { runtime, denoCompat, version: VERSION },
+        // JupyterLab enables its visual debugger from metadata.debugger (#18);
+        // only the targets driven over CDP have one.
+        metadata: { runtime, denoCompat, version: VERSION, debugger: runtime === "node" || runtime === "deno" },
     };
     writeFileSync(join(dir, "kernel.json"), JSON.stringify(spec, null, 2) + "\n");
     console.log(`installed kernelspec ${name} -> ${dir}`);

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/murmur2.d.ts

@@ -0,0 +1,2 @@
+/** The hash of a string's UTF-8 bytes. */
+export declare function murmur2(str: string, seed: number): number;

package/dist/murmur2.js

@@ -0,0 +1,41 @@
+// MurmurHash2 (32-bit), as the Jupyter debugger uses it to name a cell's
+// source (#18). JupyterLab computes a cell's path itself, as tmpFilePrefix +
+// murmur2(code, hashSeed) + tmpFileSuffix, and the kernel must name the
+// cell's script the same way, so this follows JupyterLab's
+// packages/debugger/src/hash.ts (Modified BSD License, Copyright (c) Jupyter
+// Development Team), itself adapted from Gary Court's murmurhash2_gc.js
+// (MIT License, Copyright (c) 2011 Gary Court).
+const M = 0x5bd1e995;
+const ENCODER = new TextEncoder();
+/** 32-bit multiply by M, without leaving the safe-integer range. */
+function mul(x) {
+    return (x & 0xffff) * M + ((((x >>> 16) * M) & 0xffff) << 16);
+}
+/** The hash of a string's UTF-8 bytes. */
+export function murmur2(str, seed) {
+    const data = ENCODER.encode(str);
+    let len = data.length;
+    let h = seed ^ len;
+    let i = 0;
+    while (len >= 4) {
+        let k = data[i] | (data[i + 1] << 8) | (data[i + 2] << 16) | (data[i + 3] << 24);
+        k = mul(k);
+        k ^= k >>> 24;
+        k = mul(k);
+        h = mul(h) ^ k;
+        len -= 4;
+        i += 4;
+    }
+    if (len === 3)
+        h ^= data[i + 2] << 16;
+    if (len >= 2)
+        h ^= data[i + 1] << 8;
+    if (len >= 1) {
+        h ^= data[i];
+        h = mul(h);
+    }
+    h ^= h >>> 13;
+    h = mul(h);
+    h ^= h >>> 15;
+    return h >>> 0;
+}

package/dist/package.d.ts

@@ -1,6 +1,20 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.3.0";
-export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "node-hooks.mjs", "deno-compat.mjs", "node-modules-resolve.mjs"];
+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-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
+ * relaunches with this cutoff instead (#12): anything published up to two
+ * days after the release is allowed (the release itself included, however
+ * late in the day its tag was pushed), and nothing newer ever is.
+ */
+export declare function dependencyCutoff(releaseDate?: string): string;
+export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "introspect.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "node-hooks.mjs", "deno-compat.mjs", "node-modules-resolve.mjs"];
 export type HostRuntime = "node" | "deno";
 export declare function hostRuntime(): HostRuntime;
 /** Where the CLI module was loaded from. */

package/dist/package.js

@@ -14,11 +14,32 @@ 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.3.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-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
+ * relaunches with this cutoff instead (#12): anything published up to two
+ * days after the release is allowed (the release itself included, however
+ * late in the day its tag was pushed), and nothing newer ever is.
+ */
+export function dependencyCutoff(releaseDate = RELEASE_DATE) {
+    const day = new Date(`${releaseDate}T00:00:00Z`);
+    if (Number.isNaN(day.getTime()))
+        throw new Error(`not a date: ${releaseDate}`);
+    day.setUTCDate(day.getUTCDate() + 2);
+    return day.toISOString().slice(0, 10);
+}
 export const RUNTIME_FILES = [
     "bootstrap.mjs",
     "bun-channel.mjs",
     "evaluator.mjs",
+    "introspect.mjs",
     "workerd-worker.mjs",
     "display.mjs",
     "comm.mjs",
@@ -54,12 +75,14 @@ export function kernelArgv(host, execPath, origin, args) {
     }
     // Deno: a checkout needs its deno.jsonc import map; a JSR package brings
     // its own, so skip whatever config the notebook's directory has.
-    const flags = origin.kind === "jsr" ? ["--no-config", "--no-lock"] : ["--no-lock"];
+    const flags = origin.kind === "jsr"
+        ? ["--no-config", "--no-lock", `--min-dep-age=${dependencyCutoff()}`]
+        : ["--no-lock"];
     const entry = origin.kind === "jsr" ? origin.specifier : origin.path;
     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/sourcemap.d.ts

@@ -0,0 +1,22 @@
+/** One segment's VLQ fields: generated column, source, line, column, name. */
+export declare function decodeVlq(segment: string): number[];
+/**
+ * For each generated line (0-based), the first original line (0-based) a
+ * segment on it maps to, or -1. Source-map fields are relative to the
+ * previous segment's; only the original line is tracked.
+ */
+export declare function generatedToOriginalLines(mappings: string): number[];
+/** Both directions between the lines of a cell and of its script (0-based). */
+export declare class LineMap {
+    #private;
+    /** `offset`: lines the script adds before esbuild's output (the prelude). */
+    constructor(mappings: string, offset?: number);
+    /** The cell line a script line came from: its own mapping, or the nearest one above. */
+    toOriginal(generated: number): number;
+    /**
+     * The script line for a cell line, or for the next cell line that has
+     * code (a breakpoint on a blank or comment line moves down, as debuggers
+     * do), or null past the end.
+     */
+    toGenerated(original: number): number | null;
+}