@tlockney/cdp-kernel 0.7.1 → 0.8.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.1";
+export declare const VERSION = "0.8.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-19";
+export declare const RELEASE_DATE = "2026-11-06";
 /**
  * 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.1";
+export const VERSION = "0.8.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-19";
+export const RELEASE_DATE = "2026-11-06";
 /**
  * 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>;
     /**

package/dist/target.js

@@ -12,6 +12,7 @@ import { SHIM, transformCell } from "./transform.js";
 import { hostRuntime, isInsideNodeModules, runtimeDir } from "./package.js";
 import { killOnExit } from "./children.js";
 import { Interrupted, isTargetMessage, parseBundle, parseJson, withStartTimeout, } from "./target-api.js";
+import { processUsage } from "./usage.js";
 export { Interrupted, isTargetMessage, parseBundle, parseJson };
 /**
  * The inspector keeps every object it returns a remote reference to alive
@@ -330,7 +331,10 @@ export class Target {
     #messages = Promise.resolve();
     /** Messages received but not yet delivered. */
     #undelivered = 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;
     #paused = false;
     /** What the debugger asked to pause on (#307), and how many kernel calls hold it off. */
     #pauseOnExceptions = "none";
@@ -338,11 +342,14 @@ export class Target {
     /** Set once the main context is gone: the runtime is exiting (#130). */
     #exiting = false;
     #exited;
+    /** When the runtime was spawned: the OS counts its CPU time from then (#409). */
+    #startedAt;
     #baselineGlobals = new Set();
     versions;
-    constructor(runtime, child, shell, control, stdout, stderr, gates, contextId, versions) {
+    constructor(runtime, child, shell, control, stdout, stderr, gates, contextId, versions, startedAt) {
         this.runtime = runtime;
         this.#child = child;
+        this.#startedAt = startedAt;
         this.#exited = new Promise((resolve) => {
             if (child.exitCode !== null || child.signalCode !== null)
                 resolve();
@@ -376,6 +383,7 @@ export class Target {
         if (esbuild !== null)
             env.CDPK_ESBUILD_BINARY = esbuild;
         delete env.NO_COLOR;
+        const startedAt = Date.now();
         const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe"], env });
         killOnExit(child);
         // Prompt replies and comm messages go to stdin; one written as the
@@ -385,7 +393,7 @@ export class Target {
         // pipes and inspector sockets would keep this process alive (#52).
         const sessions = [];
         try {
-            return await withStartTimeout(Target.#start(runtime, events, cmd, child, sessions), cmd, options.startTimeoutMs);
+            return await withStartTimeout(Target.#start(runtime, events, cmd, child, startedAt, sessions), cmd, options.startTimeoutMs);
         }
         catch (error) {
             for (const session of sessions)
@@ -394,7 +402,7 @@ export class Target {
             throw error;
         }
     }
-    static async #start(runtime, events, cmd, child, sessions) {
+    static async #start(runtime, events, cmd, child, startedAt, sessions) {
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         const gates = new Gates();
@@ -452,7 +460,7 @@ export class Target {
         // messages come over stdout. The control session watches for exit.
         await shell.send("Runtime.disable");
         await control.send("Runtime.enable");
-        target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", engine: "" });
+        target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", engine: "" }, startedAt);
         // process.exit() or Deno.exit() destroys the context, then the runtime
         // waits for its inspector clients to disconnect before it exits. Let go,
         // so it exits and the kernel starts a fresh one (#130).
@@ -544,6 +552,26 @@ export class Target {
             this.#gates.open(msg.barrier);
         });
     }
+    /**
+     * 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.
+     */
+    async usage() {
+        const pid = this.#child.pid;
+        const usage = { startedAt: this.#startedAt, ...(pid === undefined ? {} : await processUsage(pid)) };
+        if (usage.memory === undefined) {
+            // Over the control session, which no cell holds; a runtime that
+            // doesn't answer within a second leaves the memory out.
+            const heap = await Promise.race([
+                this.#control.send("Runtime.getHeapUsage").catch(() => null),
+                new Promise((resolve) => setTimeout(() => resolve(null), 1000).unref()),
+            ]);
+            if (typeof heap?.totalSize === "number")
+                usage.memory = heap.totalSize;
+        }
+        return usage;
+    }
     /**
      * What the host is waiting on, whether the runtime still evaluates, runs
      * immediates and runs timers, and where its JavaScript is if it is
@@ -624,12 +652,13 @@ export class Target {
     }
     /** Runs transformed cell code. Rejects with Interrupted after interrupt(). */
     async evaluate(script) {
-        this.#interrupted = false;
+        const interrupts = this.#interrupts;
+        this.#cells++;
         try {
             return await this.#evaluateRaw(script);
         }
         catch (err) {
-            if (err instanceof CdpAbandoned || this.#interrupted)
+            if (err instanceof CdpAbandoned || this.#interrupts !== interrupts)
                 throw new Interrupted("Execution interrupted");
             // The control session's executionContextDestroyed event can arrive
             // after the shell session's error reply (#271 moved it there).
@@ -643,6 +672,9 @@ export class Target {
             }
             throw err;
         }
+        finally {
+            this.#cells--;
+        }
     }
     async releaseResults() {
         if (this.#exiting)
@@ -666,15 +698,35 @@ export class Target {
      * 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).
      */
     async interrupt() {
-        this.#interrupted = true;
+        this.#interrupts++;
+        // Before abandoning the evaluate, which ends the count.
+        const cellRunning = this.#cells > 0;
         // A paused isolate runs nothing to terminate: let it go first (#18).
         if (this.#paused)
             await this.#shell.send("Debugger.resume").catch(() => { });
         await this.#control.send("Runtime.terminateExecution");
         this.#shell.abandonPending();
+        await this.#abortSignal(cellRunning);
+    }
+    /**
+     * Aborts jupyter.signal (#418), once the cell is terminated: cell code
+     * waiting on a promise that only it can settle, such as a comm reply,
+     * can then stop. A termination still pending would end the first call,
+     * so it gets a second.
+     */
+    async #abortSignal(cellRunning) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const res = await this.callFunctionOn(`function (cell) { globalThis.${SHIM}.abortSignal(cell); return true; }`, [
+                { value: cellRunning },
+            ])
+                .catch(() => ({}));
+            if (res.result?.value === true)
+                return;
+        }
     }
     /**
      * For synchronous functions. With awaitPromise the inspector would wrap
@@ -734,7 +786,7 @@ export class Target {
      * threw. Rejects with Interrupted after interrupt().
      */
     async dispatchComm(msgType, content, metadata, buffers) {
-        this.#interrupted = false;
+        const interrupts = this.#interrupts;
         // Over stdin, not as call arguments: V8 caches an argument's source,
         // so the data would stay in the target's memory (#287).
         const record = Buffer.from(JSON.stringify({
@@ -742,6 +794,7 @@ export class Target {
             content,
             metadata,
             buffers: buffers.map((b) => Buffer.from(b).toString("base64")),
+            ownSignal: this.#cells === 0,
         }));
         this.#child.stdin.write(`comm ${record.length}\n`);
         this.#child.stdin.write(record);
@@ -750,7 +803,7 @@ export class Target {
             res = await this.#callAsyncFunctionOn(`function () { return globalThis.${SHIM}.commDispatchFromStdin(); }`, []);
         }
         catch (err) {
-            if (err instanceof CdpAbandoned || this.#interrupted)
+            if (err instanceof CdpAbandoned || this.#interrupts !== interrupts)
                 throw new Interrupted("Comm handler interrupted");
             throw err;
         }
@@ -832,7 +885,8 @@ export class Target {
         return res.names ?? [];
     }
     replyInput(value, interrupted = false) {
-        this.#child.stdin.write(JSON.stringify({ value, interrupted }) + "\n");
+        // `cell`: an interrupted prompt aborts a cell's jupyter.signal only if one runs (#421).
+        this.#child.stdin.write(JSON.stringify({ value, interrupted, cell: this.#cells > 0 }) + "\n");
     }
     kill() {
         this.#shell.close();

package/dist/transform.js

@@ -30,7 +30,9 @@ export const SHIM = "__cdpk";
 // collected" (#329). Yielding first moves the throw into a task, where
 // SETTLE's reasoning applies. The debug console uses YIELD for this.
 export const YIELD = `await ${SHIM}.tick();\n`;
-const PRELUDE = `'use strict'; ${YIELD}`;
+// startCell gives the cell its own jupyter.signal (#421) before any of its
+// code runs.
+const PRELUDE = `'use strict'; ${SHIM}.startCell(); ${YIELD}`;
 /**
  * Each replMode cell also ends by yielding one macrotask, so the script
  * settles with no other microtasks queued ahead of the inspector's

package/dist/usage.d.ts

@@ -0,0 +1,25 @@
+import type { JsonObject } from "./message.ts";
+import type { KernelTarget } from "./target-api.ts";
+/** A process's resident memory in bytes and its CPU time so far in µs, from the OS. */
+export interface ProcessUsage {
+    memory?: number;
+    cpuTime?: number;
+}
+/** A process's usage on Linux (/proc) or macOS (`ps`); empty elsewhere or if it can't be read. */
+export declare function processUsage(pid: number): Promise<ProcessUsage>;
+/**
+ * Several processes' usage added up, for a target that runs in more than
+ * one (Miniflare's workerd). A figure any of them can't report is left out.
+ */
+export declare function processesUsage(pids: readonly number[]): Promise<ProcessUsage>;
+/** `ps`'s `time`: [[dd-]hh:]mm:ss[.cc], in seconds; null if it isn't one. */
+export declare function parseCpuTime(text: string): number | null;
+/**
+ * Builds usage_reply content. CPU percentages cover the time since the
+ * previous request: since the process started, for the first one.
+ */
+export declare class UsageMeter {
+    #private;
+    /** `target` is the running target, or null while none runs. */
+    reply(target: KernelTarget | null): Promise<JsonObject>;
+}

package/dist/usage.js

@@ -0,0 +1,197 @@
+// usage_request (#409): the kernel's memory and CPU, and the host's, in
+// the shape ipykernel replies with. Cells run in the target, a separate
+// process, so the kernel's figures are the host process's plus the
+// target's. A field this platform or target can't measure is left out.
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import process from "node:process";
+/**
+ * Linux reports CPU times in clock ticks of USER_HZ, which the kernel's
+ * ABI fixes at 100 on the architectures Node and Deno run on.
+ */
+const USER_HZ = 100;
+/** How long `ps` may take: Ganymede waits 2 s for a first usage_reply (tlockney/ganymede#364). */
+const PS_TIMEOUT_MS = 1_000;
+/** A process's usage on Linux (/proc) or macOS (`ps`); empty elsewhere or if it can't be read. */
+export async function processUsage(pid) {
+    try {
+        if (process.platform === "linux")
+            return await procUsage(pid);
+        if (process.platform === "darwin")
+            return await psUsage(pid);
+    }
+    catch {
+        // Gone, or not ours to read.
+    }
+    return {};
+}
+async function procUsage(pid) {
+    const [stat, status] = await Promise.all([
+        readFile(`/proc/${pid}/stat`, "utf8"),
+        readFile(`/proc/${pid}/status`, "utf8"),
+    ]);
+    const usage = {};
+    // Fields after the command name, which may itself hold spaces and ")":
+    // the third field (state) is fields[0], so utime and stime (14, 15) are 11, 12.
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    const ticks = Number(fields[11]) + Number(fields[12]);
+    if (Number.isFinite(ticks))
+        usage.cpuTime = ticks * (1_000_000 / USER_HZ);
+    const rss = /^VmRSS:\s+(\d+) kB$/m.exec(status);
+    if (rss !== null)
+        usage.memory = Number(rss[1]) * 1024;
+    return usage;
+}
+async function psUsage(pid) {
+    const out = await new Promise((resolve, reject) => {
+        execFile("ps", ["-o", "rss=,time=", "-p", String(pid)], { timeout: PS_TIMEOUT_MS }, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolve(stdout);
+        });
+    });
+    const [rss, time] = out.trim().split(/\s+/);
+    const usage = {};
+    if (rss !== undefined && /^\d+$/.test(rss))
+        usage.memory = Number(rss) * 1024;
+    const seconds = time === undefined ? null : parseCpuTime(time);
+    if (seconds !== null)
+        usage.cpuTime = Math.round(seconds * 1_000_000);
+    return usage;
+}
+/**
+ * Several processes' usage added up, for a target that runs in more than
+ * one (Miniflare's workerd). A figure any of them can't report is left out.
+ */
+export async function processesUsage(pids) {
+    const each = await Promise.all(pids.map((pid) => processUsage(pid)));
+    const sum = (key) => each.length > 0 && each.every((u) => u[key] !== undefined) ? each.reduce((n, u) => n + u[key], 0) : undefined;
+    const usage = {};
+    const memory = sum("memory");
+    const cpuTime = sum("cpuTime");
+    if (memory !== undefined)
+        usage.memory = memory;
+    if (cpuTime !== undefined)
+        usage.cpuTime = cpuTime;
+    return usage;
+}
+/** `ps`'s `time`: [[dd-]hh:]mm:ss[.cc], in seconds; null if it isn't one. */
+export function parseCpuTime(text) {
+    const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.\d+)?)$/.exec(text);
+    if (match === null)
+        return null;
+    const [, days, hours, minutes, seconds] = match;
+    return Number(days ?? 0) * 86_400 + Number(hours ?? 0) * 3_600 + Number(minutes) * 60 + Number(seconds);
+}
+/** All CPUs' idle and total time so far, in ms; null if the OS lists none. */
+function hostCpuTimes() {
+    const cpus = os.cpus();
+    if (cpus.length === 0)
+        return null;
+    let idle = 0;
+    let total = 0;
+    for (const { times } of cpus) {
+        idle += times.idle;
+        total += times.user + times.nice + times.sys + times.idle + times.irq;
+    }
+    return { idle, total };
+}
+/** psutil.virtual_memory()'s fields that can be read here. */
+async function hostMemory() {
+    const total = os.totalmem();
+    const memory = { total };
+    if (process.platform === "linux") {
+        try {
+            // MemAvailable is what psutil reports as available; os.freemem()
+            // reads the same field, so it is read here alongside MemFree.
+            const meminfo = await readFile("/proc/meminfo", "utf8");
+            const kib = (name) => {
+                const match = new RegExp(`^${name}:\\s+(\\d+) kB$`, "m").exec(meminfo);
+                return match === null ? undefined : Number(match[1]) * 1024;
+            };
+            const available = kib("MemAvailable");
+            const free = kib("MemFree");
+            if (available !== undefined) {
+                memory.available = available;
+                memory.percent = Math.round((total - available) / total * 1000) / 10;
+            }
+            if (free !== undefined)
+                memory.free = free;
+        }
+        catch {
+            // No /proc: total alone.
+        }
+    }
+    else {
+        // macOS's free pages; psutil's "available" also counts inactive ones,
+        // which Node doesn't report, so that is left out.
+        memory.free = os.freemem();
+    }
+    return memory;
+}
+/**
+ * Builds usage_reply content. CPU percentages cover the time since the
+ * previous request: since the process started, for the first one.
+ */
+export class UsageMeter {
+    /** The host process's CPU time when last asked, and when that was (ms). */
+    #host = { cpuTime: 0, at: Date.now() - process.uptime() * 1000 };
+    /** The target's CPU time when last measured, keyed by when it started (not the target, which may be gone). */
+    #target = null;
+    #hostCpu = hostCpuTimes();
+    /** `target` is the running target, or null while none runs. */
+    async reply(target) {
+        const [targetUsage, virtualMemory] = await Promise.all([
+            target?.usage ? target.usage().catch(() => ({})) : null,
+            hostMemory(),
+        ]);
+        const now = Date.now();
+        const content = { hostname: os.hostname(), pid: process.pid };
+        // The host process, then the target's process: no target running
+        // means the kernel is only the host. A target that can't be measured
+        // leaves the figure out rather than reporting the host's alone.
+        const { user, system } = process.cpuUsage();
+        const hostCpu = user + system;
+        let cpu = percentOf(hostCpu - this.#host.cpuTime, now - this.#host.at);
+        this.#host = { cpuTime: hostCpu, at: now };
+        let memory = process.memoryUsage().rss;
+        if (target !== null) {
+            if (targetUsage?.cpuTime === undefined) {
+                // The previous sample stays the baseline, so one missed sample
+                // doesn't make the next reply average over the target's life.
+                cpu = null;
+            }
+            else {
+                const { startedAt } = targetUsage;
+                const last = startedAt !== undefined && this.#target?.startedAt === startedAt
+                    ? this.#target
+                    : { cpuTime: 0, at: startedAt ?? now };
+                cpu += percentOf(targetUsage.cpuTime - last.cpuTime, now - last.at);
+                this.#target = { startedAt, cpuTime: targetUsage.cpuTime, at: now };
+            }
+            memory = targetUsage?.memory === undefined ? null : memory + targetUsage.memory;
+        }
+        if (cpu !== null)
+            content.kernel_cpu = Math.round(cpu * 10) / 10;
+        if (memory !== null)
+            content.kernel_memory = memory;
+        const times = hostCpuTimes();
+        if (times !== null && this.#hostCpu !== null) {
+            const total = times.total - this.#hostCpu.total;
+            if (total > 0)
+                content.host_cpu_percent = Math.round((1 - (times.idle - this.#hostCpu.idle) / total) * 1000) / 10;
+        }
+        this.#hostCpu = times;
+        const cpuCount = os.cpus().length;
+        if (cpuCount > 0)
+            content.cpu_count = cpuCount;
+        content.host_virtual_memory = virtualMemory;
+        return content;
+    }
+}
+/** CPU time (µs) over wall time (ms), as a percentage of one CPU. */
+function percentOf(cpuMicros, wallMs) {
+    return wallMs > 0 ? Math.max(0, cpuMicros / (wallMs * 1000) * 100) : 0;
+}

package/dist/workerd-target.d.ts

@@ -1,6 +1,7 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
 import { transformCellForEval } from "./transform.ts";
 import { type KernelTarget, type TargetEvents } from "./target.ts";
+import { type TargetUsage } from "./target-api.ts";
 import { type WsChannel } from "./ws-client.ts";
 /** The driver Worker's modules; the first is its main module. */
 export declare const WORKER_MODULES: string[];
@@ -18,6 +19,16 @@ export declare function workerdConfig({ socket, compatibilityDate }: {
  * otherwise use the one on PATH.
  */
 export declare function findWorkerd(cwd: string): string;
+/**
+ * The native workerd binary behind `executable`. npm's workerd package
+ * installs bin/workerd as a Node script that runs the platform package's
+ * binary with execFileSync, and only its postinstall swaps the binary in.
+ * When install scripts don't run (the npm that comes with Node 27 blocks
+ * those not in allowScripts), killing that script leaves the binary running
+ * with the driver socket open, so it's never what the target spawns (#397).
+ * Anything that isn't the workerd package's script is returned as given.
+ */
+export declare function nativeWorkerd(executable: string): string;
 /** "workerd 2026-10-15" -> "2026-10-15": the newest date it supports. */
 export declare function compatibilityDateOf(versionOutput: string): string;
 /** The literal specifiers a transformed cell imports, in order. */
@@ -49,6 +60,12 @@ export interface WorkerHost {
     readonly project?: string;
     /** The open session with the driver. */
     readonly channel: WsChannel;
+    /**
+     * The workerd processes that run the driver, for usage_request (#410).
+     * Left out where they aren't ours to measure (celld), and the reply
+     * then leaves the kernel's memory and CPU out.
+     */
+    readonly pids?: readonly number[];
     /** Stops the runtime; `now` even while a cell is busy. */
     stop(now: boolean): void;
     onExit(listener: (code: number | null) => void): void;
@@ -64,6 +81,7 @@ export declare class RawWorkerd implements WorkerHost {
     #private;
     readonly runtime: string;
     readonly channel: WsChannel;
+    get pids(): readonly number[];
     private constructor();
     static start(cwd: string, executable?: string): Promise<RawWorkerd>;
     stop(now: boolean): void;
@@ -103,8 +121,9 @@ export declare class WorkerdTarget implements KernelTarget {
     /**
      * A cell that's waiting on something leaves the driver free: it answers a
      * ping, and the cell is abandoned with the session intact (its pending
-     * work still runs, as on Bun). A busy cell can't be reached, so workerd is
-     * stopped and restarts on the next cell.
+     * work still runs, as on Bun, and jupyter.signal tells it to stop). A busy
+     * cell can't be reached, so workerd is stopped and restarts on the next
+     * cell.
      */
     interrupt(): Promise<void>;
     /** Output arrives on the session before the reply it precedes. */
@@ -132,5 +151,7 @@ export declare class WorkerdTarget implements KernelTarget {
     lexicalNames(): Promise<string[]>;
     /** Never asked for: prompt() in workerd answers null without asking. */
     replyInput(): void;
+    /** The workerd processes' resident memory and CPU time, from the OS (#410). */
+    usage(): Promise<TargetUsage>;
     kill(): void;
 }