@tlockney/cdp-kernel 0.7.2 → 0.9.0

package/README.md

@@ -7,7 +7,7 @@ runtime: Node or Deno over the Chrome DevTools Protocol, or Bun, workerd and
 celld, which evaluate cells in-process. In principle, anything else whose
 inspector speaks CDP works too. The kernel can also run inside a web page,
 with cells in a Web Worker and no server
-([The browser](https://cdp-kernel.org/docs/integration-browser), experimental).
+([The browser](https://cdp-kernel.org/docs/integration-browser)).
 
 **Website:** <https://cdp-kernel.org/> ·
 **Docs:** [cdp-kernel.org/docs](https://cdp-kernel.org/docs/)
@@ -87,7 +87,9 @@ New to Jupyter? Start with
   [Choosing a runtime](https://cdp-kernel.org/docs/runtimes),
   [Widgets and comms](https://cdp-kernel.org/docs/widgets),
   [Debugger](https://cdp-kernel.org/docs/debugger)
-- Reference: [Editor types](https://cdp-kernel.org/docs/editor-types),
+- Reference: [`jupyter` reference](https://cdp-kernel.org/docs/jupyter-reference),
+  [Widgets and comms reference](https://cdp-kernel.org/docs/widgets-reference),
+  [Editor types](https://cdp-kernel.org/docs/editor-types),
   [Known gaps](https://cdp-kernel.org/docs/known-gaps),
   [Support policy](https://cdp-kernel.org/docs/support)
 - Internals: [Architecture](https://cdp-kernel.org/docs/architecture),

package/dist/browser/kernel.js

@@ -28199,7 +28199,7 @@ function rewriteImport(code, node, index) {
     if (spec.type === "ImportNamespaceSpecifier") return `${local} = ${ns}`;
     return `${local} = ${ns}[${JSON.stringify(importedName(spec))}]`;
   });
-  return `var ${ns} = ${load}; var ${bindings.join(", ")};`;
+  return `var ${ns} = ${load}; let ${bindings.join(", ")};`;
 }
 function parseCell(js) {
   try {
@@ -28216,6 +28216,12 @@ function parseCell(js) {
 function rewriteModuleSyntax(js) {
   const program = parseCell(js);
   const edits = [];
+  for (const statement of program.body) {
+    const decl = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    if (decl?.type === "VariableDeclaration" && decl.kind === "const") {
+      edits.push({ start: decl.start, end: decl.start + "const".length, text: "let  " });
+    }
+  }
   let importIndex = 0;
   full(program, (node) => {
     switch (node.type) {
@@ -28376,7 +28382,7 @@ var init_transform = __esm({
     SHIM = "__cdpk";
     YIELD = `await ${SHIM}.tick();
 `;
-    PRELUDE = `'use strict'; ${YIELD}`;
+    PRELUDE = `'use strict'; ${SHIM}.startCell(); ${YIELD}`;
     SETTLE = `
 ;let ${SHIM}_settled = await ${SHIM}.tick();`;
     CellSyntaxError = class extends Error {
@@ -28388,7 +28394,7 @@ var init_transform = __esm({
 });
 
 // src/message.ts
-var PROTOCOL_VERSION = "5.3";
+var PROTOCOL_VERSION = "5.5";
 function makeHeader(session, msgType) {
   return {
     msg_id: crypto.randomUUID(),
@@ -28758,12 +28764,43 @@ function clip(frames) {
 
 // src/kernel-core.ts
 var TYPESCRIPT_VERSION = "6";
+var launchFailures = /* @__PURE__ */ new WeakSet();
 function fromBase64(text) {
   return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
 }
 var INTERRUPT_REPLY_WAIT_MS = 1e3;
 var NO_INPUT = { value: null, interrupted: false };
+var ShellQueue = class {
+  items = [];
+  #wake = null;
+  #closed = false;
+  push(item) {
+    if (this.#closed) return;
+    this.items.push(item);
+    this.#wake?.();
+  }
+  /** The next message; null once closed. */
+  async next() {
+    for (; ; ) {
+      if (this.#closed) return null;
+      const item = this.items.shift();
+      if (item !== void 0) return item;
+      await new Promise((resolve) => this.#wake = resolve);
+      this.#wake = null;
+    }
+  }
+  /** Stops taking messages; returns those still queued. */
+  close() {
+    this.#closed = true;
+    const dropped = this.items.splice(0);
+    this.#wake?.();
+    return dropped;
+  }
+};
 var MAX_CELLS = 1e3;
+function subshellNotFound(evalue) {
+  return { status: "error", ename: "SubshellNotFound", evalue, traceback: [`SubshellNotFound: ${evalue}`] };
+}
 var SHELL_REPLIES = {
   kernel_info_request: "kernel_info_reply",
   complete_request: "complete_reply",
@@ -28815,13 +28852,16 @@ var KernelCore = class {
   #executionCount = 0;
   #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;
+  /** Cells and comm handlers running in the target. */
+  #running = 0;
+  /** A cell is running: its parent header and allow_stdin hold until it ends (#417). */
+  #cellRunning = false;
+  /** stop_on_error (#123): the message being handled was queued behind a failed cell. */
   #aborting = false;
+  /** Messages without a subshell_id, in the order they came. */
+  #mainShell = new ShellQueue();
+  /** Kernel subshells (JEP 91, #417): subshell_id -> its queue. */
+  #subshells = /* @__PURE__ */ new Map();
   /** The input_request waiting for its input_reply, if any. */
   #input = null;
   /** An interrupt is waiting on the target. */
@@ -28845,8 +28885,10 @@ var KernelCore = class {
   async run() {
     this.#ensureTarget().catch((err) => this.#log(`target failed to start: ${err}`));
     if (typeof this.#typeStrip === "string") await loadTypeStripper(this.#typeStrip);
+    await this.#channels.ready;
     await Promise.all([
-      this.#loop("shell", (m, p) => this.#handleShell(m, p)),
+      this.#readShell(),
+      this.#runShell(this.#mainShell),
       this.#loop("control", (m, p) => this.#handleControl(m, p)),
       this.#loop("stdin", (m) => this.#handleStdin(m))
     ]);
@@ -28870,8 +28912,9 @@ var KernelCore = class {
     if (target?.diagnose) targetState = await target.diagnose().catch((err) => `diagnose failed: ${err}`);
     this.#log(`state: ${JSON.stringify({
       shell: handling && { msgType: handling.msgType, msgId: handling.msgId, ms: Date.now() - handling.since },
-      queued: this.#channels.shellQueued(),
-      executing: this.#executing,
+      queued: this.#mainShell.items.length + this.#channels.shellQueued(),
+      subshells: this.#subshells.size,
+      running: this.#running,
       interrupting: this.#interrupting,
       awaitingInput: this.#input !== null,
       target: targetState
@@ -28900,25 +28943,28 @@ var KernelCore = class {
     const type = msg.header.msg_type;
     const commId = String(msg.content.comm_id ?? "");
     const target = await this.#ensureTarget();
-    this.#parent = msg.header;
-    this.#allowStdin = false;
-    this.#executing = true;
+    if (!this.#cellRunning) {
+      this.#parent = msg.header;
+      this.#allowStdin = false;
+    }
+    const parent = msg.header;
     let handled = false;
+    this.#running++;
     try {
       const result = await target.dispatchComm(type, msg.content, msg.metadata, msg.buffers);
       if ("error" in result) {
         const { name, message, stack } = result.error;
         this.#publish("stream", { name: "stderr", text: `Error in ${type} handler: ${stack || `${name}: ${message}`}
-` });
+` }, { parent });
       } else {
         handled = result.handled;
       }
     } catch (err) {
       if (!(err instanceof Interrupted)) throw err;
       this.#publish("stream", { name: "stderr", text: `${type} handler interrupted
-` });
+` }, { parent });
     } finally {
-      this.#executing = false;
+      this.#running--;
     }
     await target.flush().catch(() => {
     });
@@ -28926,7 +28972,7 @@ var KernelCore = class {
       if (handled) {
         this.#comms.set(commId, String(msg.content.target_name ?? ""));
       } else {
-        this.#publish("comm_close", { comm_id: commId, data: {} });
+        this.#publish("comm_close", { comm_id: commId, data: {} }, { parent });
       }
     } else if (type === "comm_close") {
       this.#comms.delete(commId);
@@ -28942,6 +28988,7 @@ var KernelCore = class {
       return target;
     }, (err) => {
       this.#targetStarting = null;
+      if (typeof err === "object" && err !== null) launchFailures.add(err);
       throw err;
     });
     return this.#targetStarting;
@@ -28961,10 +29008,18 @@ var KernelCore = class {
       this.#interruptStart = null;
     }
   }
+  /** Tells the host of a fault in the kernel's own code; a target that failed to launch isn't one (#422). */
+  #fault(err, where) {
+    if (typeof err === "object" && err !== null && launchFailures.has(err)) return;
+    this.#host.fault?.(err, where);
+  }
   #targetEvents() {
     return {
       stream: (name, text) => this.#publish("stream", { name, text }),
-      message: (msg) => void this.#onTargetMessage(msg).catch((err) => this.#log(`error handling target message: ${err}`)),
+      message: (msg) => void this.#onTargetMessage(msg).catch((err) => {
+        this.#log(`error handling target message: ${err}`);
+        this.#fault(err, "target message");
+      }),
       exit: (code, note) => {
         this.#target = null;
         this.#types?.reset();
@@ -29007,7 +29062,7 @@ ${text}
       this.#interruptStart();
       return;
     }
-    if (!this.#target || !this.#executing) return;
+    if (!this.#target || this.#running === 0) return;
     this.#interrupting = true;
     try {
       await this.#target.interrupt();
@@ -29037,19 +29092,70 @@ ${text}
   async #loop(channel, handle) {
     while (!this.#shuttingDown) {
       const received = await this.#channels.recv(channel);
-      if (channel === "shell") {
-        this.#aborting = this.#abortQueued > 0;
-        if (this.#aborting) this.#abortQueued--;
+      if (received === null) continue;
+      try {
+        await handle(received.msg, received.peer);
+      } catch (err) {
+        this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
+        this.#fault(err, `${channel} handler`);
       }
+    }
+  }
+  /**
+   * Takes every shell message as it comes and queues it for the main shell
+   * or its subshell, so a subshell's message isn't stuck behind a running
+   * cell (#417).
+   */
+  async #readShell() {
+    while (!this.#shuttingDown) {
+      const received = await this.#channels.recv("shell");
       if (received === null) continue;
-      const { peer, msg } = received;
+      const subshellId = received.msg.header.subshell_id;
+      if (typeof subshellId !== "string") {
+        this.#mainShell.push({ ...received, abort: false });
+        continue;
+      }
+      const queue = this.#subshells.get(subshellId);
+      if (queue === void 0) {
+        this.#refuseShell(received, `No subshell with id ${subshellId}`);
+      } else if (received.msg.header.msg_type === "execute_request") {
+        this.#mainShell.push({ ...received, abort: false });
+      } else {
+        queue.push({ ...received, abort: false });
+      }
+    }
+  }
+  /**
+   * Answers a shell message for a subshell that doesn't exist, or was
+   * deleted with the message queued, so the frontend doesn't wait on it.
+   */
+  #refuseShell({ peer, msg }, evalue) {
+    const type = msg.header.msg_type;
+    this.#log(`refusing ${type}: ${evalue}`);
+    this.#status("busy", msg.header);
+    const replyType = type === "execute_request" ? "execute_reply" : SHELL_REPLIES[type];
+    if (replyType !== void 0) this.#reply("shell", peer, msg, replyType, subshellNotFound(evalue));
+    if (type === "comm_open") this.#publish("comm_close", { comm_id: String(msg.content.comm_id ?? ""), data: {} }, { parent: msg.header });
+    this.#status("idle", msg.header);
+  }
+  /** Handles one queue's messages in turn. */
+  async #runShell(queue) {
+    const main = queue === this.#mainShell;
+    while (!this.#shuttingDown) {
+      const queued = await queue.next();
+      if (queued === null) return;
+      const { peer, msg } = queued;
       try {
-        if (channel === "shell") this.#handling = { msgType: msg.header.msg_type, msgId: msg.header.msg_id, since: Date.now() };
-        await handle(msg, peer);
+        if (main) {
+          this.#aborting = queued.abort;
+          this.#handling = { msgType: msg.header.msg_type, msgId: msg.header.msg_id, since: Date.now() };
+        }
+        await this.#handleShell(msg, peer);
       } catch (err) {
         this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
+        this.#fault(err, "shell handler");
       } finally {
-        if (channel === "shell") this.#handling = null;
+        if (main) this.#handling = null;
       }
     }
   }
@@ -29063,7 +29169,12 @@ ${text}
       language_info: {
         name: "typescript",
         version: this.#host.languageVersion ?? TYPESCRIPT_VERSION,
-        mimetype: "text/x.typescript",
+        // JupyterLab's LSP adapter picks the language server by a language
+        // it derives from this MIME type, not from name: it drops the type
+        // and an "x-" prefix, so "text/x.typescript" became "x.typescript"
+        // and matched no server (#400). This is CodeMirror's MIME type for
+        // TypeScript and in jupyter-lsp's typescript-language-server spec.
+        mimetype: "application/typescript",
         file_extension: ".ts",
         pygments_lexer: "typescript",
         codemirror_mode: "typescript",
@@ -29075,12 +29186,19 @@ ${text}
       debugger: this.#debugger !== null,
       // What current ipykernel advertises; JupyterLab itself goes by the
       // kernelspec's metadata.debugger.
-      supported_features: this.#debugger !== null ? ["debugger"] : [],
+      supported_features: [...this.#debugger !== null ? ["debugger"] : [], "kernel subshells"],
       ...this.#host.capabilities ? { capabilities: this.#host.capabilities } : {}
     };
   }
   // --- control channel ------------------------------------------------------
   async #handleControl(msg, peer) {
+    if (msg.header.msg_type === "usage_request") {
+      void this.#handleControlRequest(msg, peer).catch((err) => this.#log(`usage_request failed: ${err}`));
+      return;
+    }
+    return this.#handleControlRequest(msg, peer);
+  }
+  async #handleControlRequest(msg, peer) {
     this.#status("busy", msg.header);
     try {
       await this.#controlRequest("control", msg, peer);
@@ -29101,6 +29219,37 @@ ${text}
         ]);
         this.#reply(channel, peer, msg, "interrupt_reply", { status: "ok" });
         break;
+      case "create_subshell_request": {
+        const subshellId = crypto.randomUUID();
+        const queue = new ShellQueue();
+        this.#subshells.set(subshellId, queue);
+        void this.#runShell(queue);
+        this.#reply(channel, peer, msg, "create_subshell_reply", { status: "ok", subshell_id: subshellId });
+        break;
+      }
+      case "delete_subshell_request": {
+        const subshellId = String(msg.content.subshell_id ?? "");
+        const queue = this.#subshells.get(subshellId);
+        if (queue === void 0) {
+          this.#reply(channel, peer, msg, "delete_subshell_reply", subshellNotFound(`No subshell with id ${subshellId}`));
+          break;
+        }
+        this.#subshells.delete(subshellId);
+        for (const dropped of queue.close()) this.#refuseShell(dropped, `Subshell ${subshellId} was deleted`);
+        this.#reply(channel, peer, msg, "delete_subshell_reply", { status: "ok" });
+        break;
+      }
+      case "list_subshell_request":
+        this.#reply(channel, peer, msg, "list_subshell_reply", { status: "ok", subshell_id: [...this.#subshells.keys()] });
+        break;
+      case "usage_request": {
+        const usage = this.#host.usage?.(this.#target).catch((err) => {
+          this.#log(`usage_request failed: ${err}`);
+          return {};
+        });
+        this.#reply(channel, peer, msg, "usage_reply", await usage ?? {});
+        break;
+      }
       case "debug_request": {
         let reply;
         if (this.#debugger === null) {
@@ -29375,7 +29524,8 @@ ${expression}
     let error = null;
     let userExpressions = {};
     let structured = null;
-    this.#executing = true;
+    this.#running++;
+    this.#cellRunning = true;
     try {
       const target = await this.#targetForCell();
       if (target.notice !== void 0 && this.#noticeShownFor !== target) {
@@ -29416,15 +29566,16 @@ ${expression}
         error = { ename: "KernelError", evalue: message, traceback: [message] };
       }
     } finally {
-      this.#executing = false;
+      this.#running--;
+      this.#cellRunning = false;
     }
     await this.#target?.releaseResults?.();
     if (error) {
       if (!silent && msg.content.stop_on_error !== false) {
         await new Promise((r) => setTimeout(r, 0));
-        this.#abortQueued = this.#channels.shellQueued();
+        for (const queued of this.#mainShell.items) queued.abort = true;
       }
-      this.#publish("error", error, structured ? { metadata: { [TRACEBACK_MIME]: structured } } : {});
+      this.#publish("error", error, { parent, ...structured ? { metadata: { [TRACEBACK_MIME]: structured } } : {} });
       this.#reply("shell", peer, msg, "execute_reply", { status: "error", execution_count: count, ...error });
     } else {
       this.#reply("shell", peer, msg, "execute_reply", {
@@ -29439,7 +29590,7 @@ ${expression}
 };
 
 // stub:package
-var VERSION = "0.7.2";
+var VERSION = "0.9.0";
 
 // src/browser/channels.ts
 var PEER = "page";
@@ -29558,7 +29709,10 @@ var BrowserTarget = class _BrowserTarget {
   #hostCalls = /* @__PURE__ */ new Map();
   #host;
   #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;
   #exited = false;
   constructor(worker, events, host) {
@@ -29662,26 +29816,33 @@ var BrowserTarget = class _BrowserTarget {
     });
   }
   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) throw new Interrupted(`${what} interrupted`);
+      if (err instanceof Abandoned || this.#interrupts !== interrupts) throw new Interrupted(`${what} interrupted`);
       throw err;
     }
   }
   async evaluate(script) {
-    return asEvaluateResult(await this.#interruptibly("eval", { code: script }, "Execution"));
+    this.#cells++;
+    try {
+      return asEvaluateResult(await this.#interruptibly("eval", { code: script }, "Execution"));
+    } finally {
+      this.#cells--;
+    }
   }
   /**
    * A cell that's waiting on something leaves the Worker free: it answers a
    * ping, and the cell is abandoned with its state intact; host requests
    * in flight are cancelled on the page, and reject in the Worker with an
-   * AbortError (#388). A busy cell can't be reached, so the Worker is
+   * AbortError (#388), and jupyter.signal is aborted (#418). A busy cell
+   * can't be reached, so the Worker is
    * terminated, and a new one starts on the next cell.
    */
   async interrupt() {
-    this.#interrupted = true;
+    this.#interrupts++;
+    const cellRunning = this.#cells > 0;
     const running = [...this.#interruptible];
     const answered = await Promise.race([
       this.#request("ping").then(() => true, () => false),
@@ -29694,6 +29855,8 @@ var BrowserTarget = class _BrowserTarget {
         this.#interruptible.delete(id);
       }
       this.#cancelHostCalls();
+      void this.#request("abort", { cell: cellRunning }).catch(() => {
+      });
       return;
     }
     this.#stopNote = RESTART_NOTE;
@@ -29708,7 +29871,13 @@ var BrowserTarget = class _BrowserTarget {
     await this.#request("broadcast", { count: executionCount, handle: result.objectId });
   }
   async dispatchComm(msgType, content, metadata, buffers) {
-    const reply = await this.#interruptibly("comm", { msgType, content, metadata, buffers: buffers.map(toBase64) }, "Comm handler");
+    const reply = await this.#interruptibly("comm", {
+      msgType,
+      content,
+      metadata,
+      buffers: buffers.map(toBase64),
+      ownSignal: this.#cells === 0
+    }, "Comm handler");
     if (isRecord(reply.error)) {
       const { name, message, stack } = reply.error;
       return { error: { name: String(name), message: String(message), stack: String(stack) } };