@tlockney/cdp-kernel 0.7.2 → 0.9.0

package/dist/kernel-core.js

@@ -19,6 +19,8 @@ import { buildTraceback, cellName, TRACEBACK_MIME } from "./traceback.js";
  * installed TypeScript's: the major version package.json depends on.
  */
 export const TYPESCRIPT_VERSION = "6";
+/** Errors from launching a target, which `KernelHost.fault` doesn't get. */
+const launchFailures = new WeakSet();
 function fromBase64(text) {
     return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
 }
@@ -28,8 +30,46 @@ function fromBase64(text) {
  */
 const INTERRUPT_REPLY_WAIT_MS = 1_000;
 const NO_INPUT = { value: null, interrupted: false };
+/**
+ * Shell messages handled one at a time, in order: the main shell, or a
+ * kernel subshell (JEP 91, #417), each with its own.
+ */
+class ShellQueue {
+    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 !== undefined)
+                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;
+    }
+}
 /** Cells remembered for tracebacks: a frame can be in a function any earlier cell defined. */
 const MAX_CELLS = 1000;
+/** The error reply for a subshell that doesn't exist (#417). */
+function subshellNotFound(evalue) {
+    return { status: "error", ename: "SubshellNotFound", evalue, traceback: [`SubshellNotFound: ${evalue}`] };
+}
 /** Shell requests other than execute_request, and their reply types. */
 const SHELL_REPLIES = {
     kernel_info_request: "kernel_info_reply",
@@ -84,13 +124,16 @@ export class KernelCore {
     #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 = new Map();
     /** The input_request waiting for its input_reply, if any. */
     #input = null;
     /** An interrupt is waiting on the target. */
@@ -117,7 +160,10 @@ export class KernelCore {
         // Transforms are synchronous, so the stripper loads before any cell.
         if (typeof this.#typeStrip === "string")
             await loadTypeStripper(this.#typeStrip);
-        await Promise.all([this.#loop("shell", (m, p) => this.#handleShell(m, p)),
+        // No shell or control reply until every port is bound: a client that
+        // has kernel_info_reply goes on to the heartbeat port (#438).
+        await this.#channels.ready;
+        await Promise.all([this.#readShell(), this.#runShell(this.#mainShell),
             this.#loop("control", (m, p) => this.#handleControl(m, p)),
             this.#loop("stdin", (m) => this.#handleStdin(m))]);
     }
@@ -141,8 +187,9 @@ export class KernelCore {
             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,
@@ -175,16 +222,21 @@ export class KernelCore {
         const type = msg.header.msg_type;
         const commId = String(msg.content.comm_id ?? "");
         const target = await this.#ensureTarget();
-        // Kernel messages the handlers send are replies to this message.
-        this.#parent = msg.header;
-        this.#allowStdin = false;
-        this.#executing = true;
+        // Kernel messages the handlers send are replies to this message, unless
+        // it came on a subshell while a cell runs (#417): the target's output
+        // doesn't say which it came from, so it stays the cell's.
+        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}`}\n` });
+                this.#publish("stream", { name: "stderr", text: `Error in ${type} handler: ${stack || `${name}: ${message}`}\n` }, { parent });
             }
             else {
                 handled = result.handled;
@@ -193,10 +245,10 @@ export class KernelCore {
         catch (err) {
             if (!(err instanceof Interrupted))
                 throw err;
-            this.#publish("stream", { name: "stderr", text: `${type} handler interrupted\n` });
+            this.#publish("stream", { name: "stderr", text: `${type} handler interrupted\n` }, { parent });
         }
         finally {
-            this.#executing = false;
+            this.#running--;
         }
         await target.flush().catch(() => { });
         if (type === "comm_open") {
@@ -206,7 +258,7 @@ export class KernelCore {
             else {
                 // An unknown target, or a handler that failed: the protocol asks the
                 // kernel to close the comm so the frontend doesn't wait on it.
-                this.#publish("comm_close", { comm_id: commId, data: {} });
+                this.#publish("comm_close", { comm_id: commId, data: {} }, { parent });
             }
         }
         else if (type === "comm_close") {
@@ -228,6 +280,10 @@ export class KernelCore {
             return target;
         }, (err) => {
             this.#targetStarting = null;
+            // Usually the user's environment (a missing runtime, a bad config),
+            // not a kernel fault, and its message quotes the child's stderr.
+            if (typeof err === "object" && err !== null)
+                launchFailures.add(err);
             throw err;
         });
         return this.#targetStarting;
@@ -249,10 +305,19 @@ export class KernelCore {
             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;
                 // What its cells declared died with it.
@@ -302,7 +367,7 @@ export class KernelCore {
             this.#interruptStart();
             return;
         }
-        if (!this.#target || !this.#executing)
+        if (!this.#target || this.#running === 0)
             return;
         this.#interrupting = true;
         try {
@@ -334,27 +399,85 @@ export class KernelCore {
     async #loop(channel, handle) {
         while (!this.#shuttingDown) {
             const received = await this.#channels.recv(channel);
-            // Before the drop below: shellQueued() counted this message too, so
-            // a dropped one takes its own abort slot, not a queued cell's (#340).
-            if (channel === "shell") {
-                this.#aborting = this.#abortQueued > 0;
-                if (this.#aborting)
-                    this.#abortQueued--;
+            // Malformed, or on ZeroMQ unsigned or forged: dropped, as in Deno.
+            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");
             // Malformed, or on ZeroMQ unsigned or forged: dropped, as in Deno.
             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 === undefined) {
+                this.#refuseShell(received, `No subshell with id ${subshellId}`);
+            }
+            else if (received.msg.header.msg_type === "execute_request") {
+                // Cells share one target and one parent header, so a cell sent on
+                // a subshell waits its turn on the main shell.
+                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 !== undefined)
+            this.#reply("shell", peer, msg, replyType, subshellNotFound(evalue));
+        // As for an unknown target: the frontend shouldn't wait on the comm.
+        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")
+                if (main) {
+                    this.#aborting = queued.abort;
                     this.#handling = { msgType: msg.header.msg_type, msgId: msg.header.msg_id, since: Date.now() };
-                await handle(msg, peer);
+                }
+                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")
+                if (main)
                     this.#handling = null;
             }
         }
@@ -369,7 +492,12 @@ export class KernelCore {
             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",
@@ -381,12 +509,22 @@ export class KernelCore {
             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) {
+        // A frontend polls usage, and measuring can take a moment (`ps` on
+        // macOS): answer it beside the queue, so an interrupt or shutdown
+        // never waits behind a poll (#409).
+        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) {
         // 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.)
@@ -412,6 +550,42 @@ export class KernelCore {
                 ]);
                 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 === undefined) {
+                    this.#reply(channel, peer, msg, "delete_subshell_reply", subshellNotFound(`No subshell with id ${subshellId}`));
+                    break;
+                }
+                // A message it is handling finishes; what's queued is refused.
+                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": {
+                // Without starting a target: a frontend polls this (#409). A host
+                // that can't measure anything still answers, so the frontend
+                // doesn't wait out its timeout.
+                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) {
@@ -745,7 +919,8 @@ export class KernelCore {
         let userExpressions = {};
         // nteract's structured traceback, sent as the error message's metadata (#322).
         let structured = null;
-        this.#executing = true;
+        this.#running++;
+        this.#cellRunning = true;
         try {
             const target = await this.#targetForCell();
             if (target.notice !== undefined && this.#noticeShownFor !== target) {
@@ -796,7 +971,8 @@ export class KernelCore {
             }
         }
         finally {
-            this.#executing = false;
+            this.#running--;
+            this.#cellRunning = false;
         }
         // The result and error are shown: nothing refers to them any more (#286).
         await this.#target?.releaseResults?.();
@@ -805,10 +981,14 @@ export class KernelCore {
                 // 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.
+                // Shell messages are queued as they're read, so by then each is.
                 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 } } : {});
+            // With its parent: a subshell's comm handler may have taken #parent
+            // since the cell ended (#417).
+            this.#publish("error", error, { parent, ...(structured ? { metadata: { [TRACEBACK_MIME]: structured } } : {}) });
             this.#reply("shell", peer, msg, "execute_reply", { status: "error", execution_count: count, ...error });
         }
         else {

package/dist/kernel.js

@@ -18,6 +18,8 @@ import { cacheRoot, VERSION } from "./package.js";
 import { watchParent } from "./parent.js";
 import { KernelCore } from "./kernel-core.js";
 import { ZmqChannels } from "./zmq-channels.js";
+import { UsageMeter } from "./usage.js";
+import { crashReporter, reportUncaught } from "./crash-reports.js";
 /** The installed TypeScript's version, for kernel_info's language_info (#340). */
 function typescriptVersion() {
     try {
@@ -141,6 +143,12 @@ export class Kernel {
             }
         }
         const denoCompat = options.denoCompat ?? false;
+        const usage = new UsageMeter();
+        // Opt-in reports of the kernel's own faults (#422): null, and nothing
+        // installed, unless CDP_KERNEL_CRASH_REPORTS=1.
+        const reporter = crashReporter({ target: runtime });
+        if (reporter)
+            reportUncaught(reporter);
         this.#core = new KernelCore({
             runtime,
             version: VERSION,
@@ -164,9 +172,11 @@ export class Kernel {
             createDebugger: runtime === "node" || runtime === "deno"
                 ? (publish, transformOptions) => new Debugger(publish, transformOptions)
                 : undefined,
+            usage: (target) => usage.reply(target),
             readSource,
             kernelFiles: kernelFiles(),
             log,
+            fault: reporter ? (err, where) => void reporter.report(err, where) : undefined,
             exit: () => process.exit(0),
         });
     }

package/dist/main.js

@@ -135,19 +135,36 @@ function uninstall(names, all) {
     if (failed)
         process.exit(1);
 }
-const { positionals, values } = parseArgs({
-    allowPositionals: true,
-    options: {
-        runtime: { type: "string", default: "node" },
-        conn: { type: "string" },
-        name: { type: "string" },
-        display: { type: "string" },
-        all: { type: "boolean", default: false },
-        "deno-compat": { type: "boolean", default: false },
-        "type-strip": { type: "string", default: "esbuild" },
-        "no-language-service": { type: "boolean", default: false },
-    },
-});
+const USAGE = "usage: cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] [--type-strip esbuild|sucrase] [--no-language-service] | list | uninstall [NAME...] [--all] | kernel --runtime node|deno|bun|workerd|celld --conn FILE | version";
+/** The command line, or exit 2 with the usage when it doesn't parse (an unknown option, a missing value). */
+function parseCommandLine() {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            options: {
+                runtime: { type: "string", default: "node" },
+                conn: { type: "string" },
+                name: { type: "string" },
+                display: { type: "string" },
+                all: { type: "boolean", default: false },
+                "deno-compat": { type: "boolean", default: false },
+                "type-strip": { type: "string", default: "esbuild" },
+                "no-language-service": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+            },
+        });
+    }
+    catch (err) {
+        console.error(`cdp-kernel: ${err instanceof Error ? err.message.split(". ")[0] : String(err)}`);
+        console.error(USAGE);
+        process.exit(2);
+    }
+}
+const { positionals, values } = parseCommandLine();
+if (values.help || positionals[0] === "help") {
+    console.log(USAGE);
+    process.exit(0);
+}
 const runtime = values.runtime;
 if (!isRuntime(runtime)) {
     console.error(`unknown runtime ${runtime}; expected node, deno, bun, workerd or celld`);
@@ -186,6 +203,6 @@ switch (positionals[0]) {
         console.log(VERSION);
         break;
     default:
-        console.error("usage: cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] [--type-strip esbuild|sucrase] [--no-language-service] | list | uninstall [NAME...] [--all] | kernel --runtime node|deno|bun|workerd|celld --conn FILE | version");
+        console.error(USAGE);
         process.exit(2);
 }

package/dist/message.d.ts

@@ -1,4 +1,4 @@
-export declare const PROTOCOL_VERSION = "5.3";
+export declare const PROTOCOL_VERSION = "5.5";
 export type JsonObject = {
     [key: string]: unknown;
 };

package/dist/message.js

@@ -1,7 +1,7 @@
 // Jupyter message shapes and headers, without the wire format: what the
 // kernel's message handling (src/kernel-core.ts) builds and reads. The
 // framing and HMAC signing that ZeroMQ peers need are in src/wire.ts.
-export const PROTOCOL_VERSION = "5.3";
+export const PROTOCOL_VERSION = "5.5";
 export function makeHeader(session, msgType) {
     return {
         msg_id: crypto.randomUUID(),

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.7.2";
+export declare const VERSION = "0.9.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-11-02";
+export declare const RELEASE_DATE = "2026-11-09";
 /**
  * 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.7.2";
+export const VERSION = "0.9.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-11-02";
+export const RELEASE_DATE = "2026-11-09";
 /**
  * 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/target-api.d.ts

@@ -52,8 +52,19 @@ export interface KernelTarget {
     diagnose?(): Promise<CdpParams>;
     /** Lets go of the last cell's result and error, once they are shown (#286). */
     releaseResults?(): Promise<void>;
+    /** The target process's memory and CPU time, for usage_request (#409). */
+    usage?(): Promise<TargetUsage>;
     kill(): void;
 }
+/** What a target measured of its own process; a field it can't measure is left out (#409). */
+export interface TargetUsage {
+    /** Resident memory, in bytes. */
+    memory?: number;
+    /** CPU time used since it started, in µs. */
+    cpuTime?: number;
+    /** When it started (ms since the epoch), the start of its first CPU interval. */
+    startedAt?: number;
+}
 /** Messages the bootstrap sends: message records on stdout, or Bun's channel. */
 export type TargetMessage = {
     kind: "iopub";

package/dist/target.d.ts

@@ -1,7 +1,7 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
 import { transformCell } from "./transform.ts";
 import type { DebugChannel } from "./debugger.ts";
-import { type CdpRuntime, Interrupted, isTargetMessage, type KernelTarget, parseBundle, parseJson, type TargetEvents, type TargetMessage } from "./target-api.ts";
+import { type CdpRuntime, Interrupted, isTargetMessage, type KernelTarget, parseBundle, parseJson, type TargetEvents, type TargetMessage, type TargetUsage } from "./target-api.ts";
 export { Interrupted, isTargetMessage, parseBundle, parseJson };
 export type { CdpRuntime, KernelTarget, RuntimeName, TargetEvents, TargetMessage } from "./target-api.ts";
 export interface LaunchOptions {
@@ -89,6 +89,12 @@ export declare class Target implements KernelTarget {
     }): Promise<Target>;
     /** The Debugger domain on this target's session, for src/debugger.ts. */
     get debug(): DebugChannel;
+    /**
+     * The runtime process's resident memory and CPU time, from the OS (#409).
+     * Where the OS can't say, the memory is the V8 heap's size instead,
+     * which leaves out native memory such as Buffers; CDP has no CPU time.
+     */
+    usage(): Promise<TargetUsage>;
     /**
      * What the host is waiting on, whether the runtime still evaluates, runs
      * immediates and runs timers, and where its JavaScript is if it is
@@ -106,7 +112,8 @@ export declare class Target implements KernelTarget {
      * CDP equivalent is Runtime.terminateExecution, sent on a second session
      * because the shell session is the one blocked on the running evaluate.
      * Terminated code never settles the awaited promise, so the pending
-     * evaluate is abandoned here and the session stays usable.
+     * evaluate is abandoned here and the session stays usable; jupyter.signal
+     * tells code still waiting on such a promise to stop (#418).
      */
     interrupt(): Promise<void>;
     /**