@tlockney/cdp-kernel 0.7.2 → 0.9.0

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/comm.d.mts

@@ -1,30 +1,116 @@
 /** A comm message as a handler receives it. */
 export interface CommMessage {
+  /** The message's JSON data. */
   data: { [key: string]: unknown };
+  /** The message's metadata. */
   metadata: { [key: string]: unknown };
+  /** Binary buffers sent with the message. */
   buffers: Uint8Array[];
 }
 
+/** Options for sending, opening or closing a comm. */
 export interface CommSendOptions {
+  /** Metadata for the message. Default `{}`. */
   metadata?: { [key: string]: unknown };
+  /** Binary buffers sent with the message. Default `[]`. */
   buffers?: Uint8Array[];
 }
 
-/** One end of a Jupyter comm channel. */
+/** One end of a Jupyter comm channel, from `jupyter.comm.open` or a target handler. */
 export interface Comm {
+  /** The comm id, shared with the frontend's end. */
   readonly id: string;
+  /** The target the comm was opened on. */
   readonly targetName: string;
+  /** Whether either end has closed the comm. */
   readonly closed: boolean;
+  /**
+   * Send a message to the frontend's end. Does nothing once closed.
+   *
+   * @param data The message's JSON data. Default `{}`.
+   * @param options Metadata and binary buffers.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.send({ ping: true }, { buffers: [new Uint8Array([1, 2, 3])] });
+   * ```
+   */
   send(data?: { [key: string]: unknown }, options?: CommSendOptions): void;
+  /**
+   * Close the comm and tell the frontend. Its `onClose` handlers start
+   * right away, without being awaited. Does nothing once closed.
+   *
+   * @param data Data sent with the close message. Default `{}`.
+   * @param options Metadata and binary buffers.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.close({ reason: "done" });
+   * ```
+   */
   close(data?: { [key: string]: unknown }, options?: CommSendOptions): void;
+  /**
+   * Handle messages from the frontend's end. A handler runs like a cell:
+   * its output goes to the notebook, and an exception shows on stderr.
+   *
+   * @param handler Called with each message; may be async.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.onMsg(({ data, buffers }) => console.log(data, buffers.length));
+   * ```
+   */
   onMsg(handler: (msg: CommMessage) => void | Promise<void>): void;
+  /**
+   * Handle the comm closing, from either end.
+   *
+   * @param handler Called with the close message; may be async.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.onClose(() => console.log("closed"));
+   * ```
+   */
   onClose(handler: (msg: CommMessage) => void | Promise<void>): void;
 }
 
 /** `jupyter.comm`: open comms, and accept comms the frontend opens. */
 export interface CommApi {
+  /**
+   * Open a comm to a target the frontend registered.
+   *
+   * @param targetName The frontend's target name.
+   * @param data Data sent with the open message. Default `{}`.
+   * @param options Metadata and binary buffers.
+   * @returns The kernel's end of the comm.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target", { hello: 1 });
+   * comm.onMsg((m) => console.log(m.data));
+   * ```
+   */
   open(targetName: string, data?: { [key: string]: unknown }, options?: CommSendOptions): Comm;
+  /**
+   * Accept comms the frontend opens on `targetName`. Registering the same
+   * name again replaces the handler.
+   *
+   * @param targetName The target name the frontend opens comms on.
+   * @param handler Called with the new comm and its open message.
+   * @example
+   * ```ts
+   * jupyter.comm.registerTarget("echo", (comm) => comm.onMsg((m) => comm.send(m.data)));
+   * ```
+   */
   registerTarget(targetName: string, handler: (comm: Comm, msg: CommMessage) => void | Promise<void>): void;
+  /**
+   * Stop accepting new comms on `targetName`. Comms already open stay open.
+   *
+   * @param targetName The target to remove.
+   * @example
+   * ```ts
+   * jupyter.comm.unregisterTarget("echo");
+   * ```
+   */
   unregisterTarget(targetName: string): void;
 }
 

package/runtime/display.d.mts

@@ -3,8 +3,18 @@ import type { Widget, WidgetOptions } from "./widget.d.mts";
 
 export type { CommApi, Widget, WidgetOptions };
 
+/**
+ * The symbol a class implements to choose how its instances appear. At
+ * runtime it is `Symbol.for("Jupyter.display")`, so a library can use that
+ * form without the `jupyter` global.
+ */
 export const $display: unique symbol;
 
+/**
+ * A Jupyter MIME bundle: media type to content, such as
+ * `{ "text/plain": "42", "text/html": "<b>42</b>" }`. Binary images are
+ * base64 strings; JSON types (`application/json`, Vega-Lite) are objects.
+ */
 export type MediaBundle = { [mediaType: string]: unknown };
 
 export interface DisplayHost {
@@ -15,33 +25,264 @@ export interface DisplayHost {
   input: (prompt: string, password: boolean) => string | null;
 }
 
+/** Options for `jupyter.display`. */
 export interface DisplayOptions {
+  /**
+   * Send a plain object as the MIME bundle itself instead of formatting
+   * it. Default `false`.
+   */
   raw?: boolean;
+  /**
+   * Replace every earlier output that has the same `display_id`, including
+   * one shown by an earlier cell, instead of adding an output. Needs
+   * `display_id`. Default `false`.
+   */
   update?: boolean;
+  /** An id that a later display with `update: true` can replace. */
   display_id?: string;
 }
 
+/** A value that renders as rich output: it has a `[jupyter.$display]` method. */
 export interface Displayable {
+  /** Returns the value's MIME bundle, or a promise of one. */
   [$display]: () => MediaBundle | Promise<MediaBundle>;
 }
 
+/**
+ * The `jupyter` global: how values appear in the notebook. The same object
+ * as `Deno.jupyter` in `deno jupyter`.
+ */
 export interface JupyterNamespace {
+  /**
+   * Send a raw Jupyter message on the kernel's output channel (IOPub), as a
+   * reply to the running cell. The other helpers are built on it. It does
+   * not check the message: a wrong field is ignored or mishandled by the
+   * frontend.
+   *
+   * @param msgType An IOPub message type, such as `"clear_output"` or
+   *   `"display_data"`.
+   * @param content The message content, as the messaging spec defines it
+   *   for `msgType`.
+   * @param options `metadata` for the message, and binary `buffers`.
+   * @example
+   * ```ts
+   * // Count down in place: clear_output with wait avoids a flicker.
+   * for (const n of [3, 2, 1]) {
+   *   jupyter.broadcast("clear_output", { wait: true });
+   *   await jupyter.display(jupyter.md`Launching in **${n}**…`);
+   *   await new Promise((resolve) => setTimeout(resolve, 1000));
+   * }
+   * ```
+   * @see jupyter-api.md#raw-messages-with-broadcast
+   */
   broadcast(
     msgType: string,
     content: object,
     options?: { metadata?: object; buffers?: Uint8Array[] },
   ): void;
+  /**
+   * Show a value now, in the middle of a cell, or replace one shown
+   * earlier. The value can be anything a cell could end with: a template
+   * from `md`, `html` or `svg`, an image, a widget, an object with a
+   * `[jupyter.$display]` method, or a plain value, shown as text.
+   *
+   * @param obj The value to show.
+   * @param options `display_id` and `update` to replace an earlier output;
+   *   `raw` to send a plain object as the MIME bundle itself.
+   * @returns Resolves once the output is sent. Without `await` the output
+   *   still appears, but later output in the cell can appear before it.
+   * @example
+   * ```ts
+   * const bar = (pct: number) => jupyter.html`<progress value="${pct}" max="100"></progress>`;
+   * await jupyter.display(bar(0), { display_id: "download" });
+   * for (let pct = 25; pct <= 100; pct += 25) {
+   *   await new Promise((resolve) => setTimeout(resolve, 500));
+   *   await jupyter.display(bar(pct), { display_id: "download", update: true });
+   * }
+   * ```
+   * @example
+   * ```ts
+   * // A MIME bundle sent as is: JupyterLab renders it as a JSON tree.
+   * const user = { name: "Ada", active: true };
+   * await jupyter.display(
+   *   { "application/json": user, "text/plain": JSON.stringify(user) },
+   *   { raw: true },
+   * );
+   * ```
+   * @see jupyter-api.md#showing-output-with-display
+   */
   display(obj: unknown, options?: DisplayOptions): Promise<void>;
+  /**
+   * The MIME bundle that displaying a value would send, without showing
+   * anything. For plain values `text/plain` holds terminal color codes,
+   * as the notebook shows them.
+   *
+   * @param obj The value to format.
+   * @returns The bundle, for example `{ "text/plain": "\x1b[33m42\x1b[39m" }`
+   *   for `42`.
+   * @example
+   * ```ts
+   * const bundle = await jupyter.format(jupyter.md`# Weekly report`);
+   * bundle["text/markdown"]; // "# Weekly report"
+   * ```
+   * @see jupyter-api.md#getting-a-bundle-with-format
+   */
   format(obj: unknown): Promise<MediaBundle>;
+  /**
+   * A tagged template that renders as Markdown. Interpolated values are
+   * inserted as is, without escaping.
+   *
+   * @returns A value that shows as `text/markdown` as a cell's result or
+   *   through `display`.
+   * @example
+   * ```ts
+   * const scores = { Ada: 92, Grace: 88 };
+   * const rows = Object.entries(scores).map(([n, s]) => `| ${n} | ${s} |`).join("\n");
+   * jupyter.md`| Name | Score |
+   * | --- | --- |
+   * ${rows}`;
+   * ```
+   * @see jupyter-api.md#markdown
+   */
   md(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  /**
+   * A tagged template that renders as HTML. Interpolated values are
+   * inserted as is, without escaping: escape text from users, files or
+   * the network yourself.
+   *
+   * @returns A value that shows as `text/html`.
+   * @example
+   * ```ts
+   * const escape = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+   * const comment = "<script>alert(1)</script>";
+   * jupyter.html`<p>${escape(comment)}</p>`;
+   * ```
+   * @see jupyter-api.md#html
+   */
   html(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  /**
+   * A tagged template that renders as SVG. Include the `xmlns` attribute.
+   * Interpolated values are inserted as is, without escaping.
+   *
+   * @returns A value that shows as `image/svg+xml`.
+   * @example
+   * ```ts
+   * const data = [4, 8, 15, 16];
+   * const bars = data.map((v, i) => `<rect x="${i * 20}" y="${40 - v * 2}" width="16" height="${v * 2}"/>`).join("");
+   * jupyter.svg`<svg xmlns="http://www.w3.org/2000/svg" width="80" height="40">${bars}</svg>`;
+   * ```
+   * @see jupyter-api.md#svg
+   */
   svg(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  /**
+   * Show a PNG or JPEG. The format is read from the bytes, not the file
+   * name.
+   *
+   * @param obj A file path, relative to the notebook's directory, or the
+   *   image's bytes.
+   * @returns A value that shows as `image/png` or `image/jpeg`.
+   * @throws {TypeError} The bytes are not PNG or JPEG, or the path can't
+   *   be read.
+   * @availability Paths need a file system: on workerd and celld pass
+   *   bytes.
+   * @example
+   * ```ts
+   * jupyter.image("./chart.png");
+   * ```
+   * @example
+   * ```ts
+   * const response = await fetch("https://www.python.org/static/img/python-logo.png");
+   * jupyter.image(new Uint8Array(await response.arrayBuffer()));
+   * ```
+   * @see jupyter-api.md#images
+   */
   image(obj: string | Uint8Array): Displayable;
+  /**
+   * The symbol a class implements to choose how its instances appear. The
+   * method returns a MIME bundle, or a promise of one. It is used for a
+   * cell's result, `display` and `format`, but not for objects nested in
+   * other values. At runtime it is `Symbol.for("Jupyter.display")`.
+   *
+   * @example
+   * ```ts
+   * class Temperature {
+   *   celsius: number;
+   *   constructor(celsius: number) {
+   *     this.celsius = celsius;
+   *   }
+   *   [jupyter.$display]() {
+   *     return { "text/plain": `${this.celsius}°C`, "text/html": `<b>${this.celsius}°C</b>` };
+   *   }
+   * }
+   * new Temperature(21);
+   * ```
+   * @see jupyter-api.md#custom-display-for-your-own-classes
+   */
   $display: typeof $display;
-  /** Jupyter comms: bidirectional channels to the frontend. */
+  /**
+   * Jupyter comms: message channels to the frontend outside cell
+   * execution. Its methods are in the widgets and comms reference.
+   *
+   * @see widgets.md#comms
+   */
   comm: CommApi;
-  /** An anywidget-compatible widget; display the result to show it. */
+  /**
+   * Create an anywidget-compatible widget model. Display it (or end the
+   * cell with it) to show a view.
+   *
+   * @param options The view module, its CSS, and the initial state.
+   * @returns The model, synced with every view of it.
+   * @throws {TypeError} `options.esm` is not a string.
+   * @availability The frontend needs the anywidget extension.
+   * @example
+   * ```ts
+   * const counter = jupyter.widget({
+   *   esm: `export default {
+   *     render({ model, el }) {
+   *       const button = document.createElement("button");
+   *       const update = () => {
+   *         button.textContent = "count is " + model.get("count");
+   *       };
+   *       button.onclick = () => {
+   *         model.set("count", model.get("count") + 1);
+   *         model.save_changes();
+   *       };
+   *       model.on("change:count", update);
+   *       update();
+   *       el.append(button);
+   *     },
+   *   };`,
+   *   state: { count: 0 },
+   * });
+   * counter; // the cell's result: displays the widget
+   * ```
+   * ![A JupyterLab cell that creates a counter widget with jupyter.widget. Below the code, the output is a button reading "count is 3" after three clicks.](https://cdp-kernel.org/images/widgets/counter.png)
+   * @see widgets.md#a-first-widget-a-counter
+   */
   widget(options: WidgetOptions): Widget;
+  /**
+   * An `AbortSignal` that an interrupt aborts, so code waiting on something
+   * only it can end can stop and clean up. Each cell gets its own, as does
+   * a comm handler that starts while no cell runs. Read it once when the
+   * work starts: a later read gets the signal of whatever started last.
+   * The abort reason is a `DOMException` named `AbortError`.
+   *
+   * @example
+   * ```ts
+   * const response = await fetch("https://example.com/large.csv", { signal: jupyter.signal });
+   * ```
+   * @example
+   * ```ts
+   * const signal = jupyter.signal;
+   * const ask = jupyter.comm.open("my.app", { question: "ready?" });
+   * const answer = await new Promise((resolve, reject) => {
+   *   ask.onMsg((m) => resolve(m.data));
+   *   signal.addEventListener("abort", () => { ask.close(); reject(signal.reason); }, { once: true });
+   * });
+   * ```
+   * @see jupyter-api.md#stopping-on-interrupt-jupyter-signal
+   */
+  readonly signal: AbortSignal;
 }
 
 export interface Jupyter {
@@ -51,8 +292,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)}`);
     }