@tlockney/cdp-kernel 0.3.0 → 0.5.0

package/dist/text.js

@@ -2,7 +2,53 @@
 //
 // Ported from Deno's cli/js/jupyter_kernel.js (v2.9.6), which is
 // Copyright 2018-2026 the Deno authors, MIT license.
-/** Bracket/quote/comment scanner deciding whether a cell is finished. */
+// Keywords after which a `/` starts a regex literal rather than dividing.
+const REGEX_AFTER_WORD = new Set([
+    "return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw",
+    "case", "do", "else", "yield", "await",
+]);
+/**
+ * Whether a `/` at `i` (not starting a comment) begins a regex literal: the
+ * usual heuristic, true unless the previous token can end an operand (a
+ * name, number, closing bracket or string). It can't tell `a++ / b` or a
+ * block's `} /re/` apart; those are rare enough in a console.
+ */
+function startsRegex(code, i) {
+    let j = i - 1;
+    while (j >= 0 && /\s/.test(code[j]))
+        j--;
+    if (j < 0)
+        return true;
+    const prev = code[j];
+    if (/[\w$]/.test(prev)) {
+        const word = /[\w$]+$/.exec(code.slice(0, j + 1))?.[0] ?? "";
+        return REGEX_AFTER_WORD.has(word);
+    }
+    return !/[)\]}'"`]/.test(prev);
+}
+/** The index just past a regex literal starting at `i`, or -1 if it doesn't end on its line. */
+function regexEnd(code, i) {
+    let inClass = false;
+    for (let j = i + 1; j < code.length; j++) {
+        const c = code[j];
+        if (c === "\n")
+            return -1;
+        if (c === "\\")
+            j++;
+        else if (c === "[")
+            inClass = true;
+        else if (c === "]")
+            inClass = false;
+        else if (c === "/" && !inClass)
+            return j + 1;
+    }
+    return -1;
+}
+/**
+ * Bracket/quote/comment scanner deciding whether a cell is finished. Regex
+ * literals are recognised heuristically (see startsRegex), and a template's
+ * `${...}` is skipped like the rest of the template.
+ */
 export function checkIsComplete(code) {
     const stack = [];
     const closers = { ")": "(", "]": "[", "}": "{" };
@@ -21,11 +67,18 @@ export function checkIsComplete(code) {
             i = end + 2;
             continue;
         }
+        if (ch === "/" && startsRegex(code, i)) {
+            const end = regexEnd(code, i);
+            if (end !== -1) {
+                i = end;
+                continue;
+            }
+        }
         if (ch === "'" || ch === '"' || ch === "`") {
             i++;
             let closed = false;
             while (i < code.length) {
-                if (code[i] === "\\" && ch !== "`") {
+                if (code[i] === "\\") {
                     i += 2;
                     continue;
                 }
@@ -51,6 +104,23 @@ export function exprAtCursor(code, cursor) {
     const m = /[\w$.]+$/.exec(code.slice(0, cursor));
     return m ? m[0] : "";
 }
+/**
+ * The dotted name an inspect_request means (#10): the one the cursor is in
+ * or just after, or, right after "name(" while typing a call, that callee.
+ * Null when it isn't a plain path; nothing else is evaluated.
+ */
+export function inspectTarget(code, cursor) {
+    let end = cursor;
+    // Inside a call's parentheses with nothing typed yet: "add(|".
+    const before = code.slice(0, cursor);
+    const call = /([\w$.]+)\(\s*$/.exec(before);
+    if (call)
+        end = cursor - (before.length - before.lastIndexOf("(", cursor));
+    const head = /[\w$.]*$/.exec(code.slice(0, end))?.[0] ?? "";
+    const tail = call ? "" : (/^[\w$]*/.exec(code.slice(end))?.[0] ?? "");
+    const path = (head + tail).replace(/\.$/, "");
+    return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(path) ? path : null;
+}
 // Jupyter measures cursor_pos in Unicode codepoints; JS strings index UTF-16
 // code units (denoland/deno#22771).
 export function codePointToUtf16Index(str, cpOffset) {

package/dist/transform.d.ts

@@ -1,4 +1,14 @@
+import { LineMap } from "./sourcemap.ts";
 export declare const SHIM = "__cdpk";
+/**
+ * Each replMode cell also ends by yielding one macrotask, so the script
+ * settles with no other microtasks queued ahead of the inspector's
+ * then-callback. Until that callback runs, the inspector holds the result
+ * promise only weakly, and a GC in between fails the evaluate with "Promise
+ * was collected" (#55). A declaration has no completion value, so the
+ * cell's value is unchanged; replMode lets `let` be declared again.
+ */
+export declare const SETTLE = "\n;let __cdpk_settled = await __cdpk.tick();";
 export declare class CellSyntaxError extends Error {
     name: string;
 }
@@ -23,6 +33,15 @@ export interface CellTransformOptions {
 /** Rewrites module-only syntax in plain JavaScript into script syntax. */
 export declare function rewriteModuleSyntax(js: string): string;
 export declare function transformCell(code: string, options?: CellTransformOptions): string;
+/**
+ * transformCell, plus the map between the cell's lines and the script's,
+ * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
+ * script's lines are esbuild's, after the prelude's one.
+ */
+export declare function transformCellWithLines(code: string, options?: CellTransformOptions): {
+    script: string;
+    lines: LineMap;
+};
 /**
  * Like transformCell, for a target that evaluates cells itself, as global
  * code (an indirect eval), instead of through the inspector's replMode: see

package/dist/transform.js

@@ -6,7 +6,7 @@
 // TypeScript/JSX part and acorn finds the module syntax that a script can't
 // contain:
 //   import x, { y as z } from "m"  ->  var __cdpk_m0 = await __cdpk.import("m");
-//                                     var x = __cdpk_m0.default, z = __cdpk_m0.y;
+//                                     var x = __cdpk_m0["default"], z = __cdpk_m0["y"];
 //   import("m")                    ->  __cdpk.import("m")
 //   import.meta                    ->  __cdpk.meta
 //   export const a = 1             ->  const a = 1
@@ -17,6 +17,7 @@
 import { transformSync } from "esbuild";
 import { parse } from "acorn";
 import { full, recursive } from "acorn-walk";
+import { LineMap } from "./sourcemap.js";
 export const SHIM = "__cdpk";
 // Each cell first yields one macrotask. User code then runs as an ordinary
 // task instead of nested inside the inspector's dispatch of Runtime.evaluate,
@@ -24,6 +25,15 @@ export const SHIM = "__cdpk";
 // interrupt a busy loop. (Within that dispatch the inspector processes no
 // other messages, so an interrupt would never be seen.)
 const PRELUDE = `'use strict'; await ${SHIM}.tick();\n`;
+/**
+ * Each replMode cell also ends by yielding one macrotask, so the script
+ * settles with no other microtasks queued ahead of the inspector's
+ * then-callback. Until that callback runs, the inspector holds the result
+ * promise only weakly, and a GC in between fails the evaluate with "Promise
+ * was collected" (#55). A declaration has no completion value, so the
+ * cell's value is unchanged; replMode lets `let` be declared again.
+ */
+export const SETTLE = `\n;let ${SHIM}_settled = await ${SHIM}.tick();`;
 export class CellSyntaxError extends Error {
     name = "SyntaxError";
 }
@@ -33,7 +43,14 @@ function jsxSettings(jsx) {
     }
     return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
 }
-function stripTypes(code, options) {
+// esbuild compiles `import x = require("m")` to a `require` call, which a
+// cell doesn't have (#143); `import type x = require("m")` is erased.
+const IMPORT_REQUIRE = /^\s*(?:export\s+)?import\s+(?!type\s)[\w$]+\s*=\s*require\s*\(/m;
+/** esbuild's output, with its source map's `mappings` when asked for. */
+function stripTypesMapped(code, options, sourcemap) {
+    if (IMPORT_REQUIRE.test(code)) {
+        throw new CellSyntaxError('import x = require("m") is not supported in a cell; use import x from "m"');
+    }
     const compilerOptions = {
         verbatimModuleSyntax: true,
         ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
@@ -42,13 +59,22 @@ function stripTypes(code, options) {
     let firstError;
     for (const loader of ["tsx", "ts"]) {
         try {
-            return transformSync(code, {
+            const result = transformSync(code, {
                 loader,
                 target: "esnext",
+                // Neither acorn nor V8 parses standard (TC39) decorators or
+                // `accessor` yet, so esbuild lowers them (#142).
+                supported: { decorators: false },
                 ...jsxSettings(options.jsx),
                 tsconfigRaw: { compilerOptions },
                 logLevel: "silent",
-            }).code;
+                ...(sourcemap ? { sourcemap: "external" } : {}),
+            });
+            const map = sourcemap ? JSON.parse(result.map) : null;
+            const mappings = typeof map?.mappings === "string"
+                ? map.mappings
+                : "";
+            return { code: result.code, mappings };
         }
         catch (err) {
             firstError ??= err;
@@ -57,6 +83,9 @@ function stripTypes(code, options) {
     const message = firstError instanceof Error ? firstError.message : String(firstError);
     throw new CellSyntaxError(message.replace(/^Transform failed with \d+ errors?:\n/, ""));
 }
+function stripTypes(code, options) {
+    return stripTypesMapped(code, options, false).code;
+}
 function importedName(spec) {
     const imported = spec.imported;
     if (!imported)
@@ -69,8 +98,9 @@ function rewriteImport(code, node, index) {
         ? `, { with: { ${node.attributes.map((a) => code.slice(a.start, a.end)).join(", ")} } }`
         : "";
     const load = `await ${SHIM}.import(${source}${attrs})`;
+    // `void`: as a cell's last statement, the import isn't its result (#139).
     if (node.specifiers.length === 0)
-        return `${load};`;
+        return `void ${load};`;
     const ns = `${SHIM}_m${index}`;
     const bindings = node.specifiers.map((spec) => {
         const local = String(spec.local.name);
@@ -129,7 +159,13 @@ export function rewriteModuleSyntax(js) {
             }
             case "ExportDefaultDeclaration": {
                 const decl = node;
-                edits.push({ start: decl.start, end: decl.declaration.start, text: "" });
+                const anonymous = (decl.declaration.type === "FunctionDeclaration" || decl.declaration.type === "ClassDeclaration") &&
+                    decl.declaration.id === null;
+                // An anonymous `function () {}` or `class {}` isn't a statement on
+                // its own; parenthesized, it's an expression and the cell's result (#143).
+                edits.push({ start: decl.start, end: decl.declaration.start, text: anonymous ? "(" : "" });
+                if (anonymous)
+                    edits.push({ start: decl.declaration.end, end: decl.declaration.end, text: ");" });
                 break;
             }
             case "ExportAllDeclaration":
@@ -140,12 +176,25 @@ export function rewriteModuleSyntax(js) {
     // keyword edit doesn't overlap its arguments), so apply back to front.
     return applyEdits(js, edits);
 }
+function newlines(text) {
+    let count = 0;
+    for (const char of text)
+        if (char === "\n")
+            count++;
+    return count;
+}
 function applyEdits(js, edits) {
     // Back to front; at a shared start, a replacement goes before an insertion.
     edits.sort((a, b) => b.start - a.start || b.end - a.end);
     let out = js;
-    for (const edit of edits)
-        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    for (const edit of edits) {
+        // Keep every later line where it was, so a cell's lines still map to
+        // esbuild's (the debugger relies on it, #18): a multi-line import
+        // rewritten to one line is padded with the newlines it replaced.
+        const lost = newlines(js.slice(edit.start, edit.end)) - newlines(edit.text);
+        const text = lost > 0 ? edit.text + "\n".repeat(lost) : edit.text;
+        out = out.slice(0, edit.start) + text + out.slice(edit.end);
+    }
     return out;
 }
 /** Adds the names a binding pattern declares. */
@@ -178,8 +227,8 @@ function patternNames(pattern, names) {
  * surrounding script, which a global-code eval turns into a property of
  * globalThis. Inside the function the declarations become assignments to
  * those globals:
- *   const { a } = o; class K {}  ->  var a, K;
- *                                    (async () => { ({ a } = o); K = class K {}; })()
+ *   const { a } = o; class K {}  ->  var a, K; (async () => {
+ *                                    ({ a } = o); K = class K {}; })()
  * So later cells, and closures from this one, all see one binding. A `var`
  * in a top-level block or loop head is global too, as in a script; block
  * scoped and function-local declarations stay where they are. Functions
@@ -253,18 +302,30 @@ function hoistForEval(js) {
             edits.push({ start: stmt.end, end: stmt.end, text: ";" });
         }
         else if (stmt.type === "ExpressionStatement" && i === program.body.length - 1) {
-            replace(stmt, `return [${src(stmt.expression)}];`);
+            // Parenthesized, so `1, 2` returns [2] rather than [1, 2] (#140).
+            replace(stmt, `return [(${src(stmt.expression)})];`);
         }
         else {
             nestedVars(stmt);
         }
     });
-    const declare = names.size > 0 ? `var ${[...names].join(", ")};\n` : "";
+    // All on the first line, so the cell always starts on line 2, as after
+    // transformCell's one-line prelude (#150).
+    const declare = names.size > 0 ? `var ${[...names].join(", ")}; ` : "";
     const publish = functions.map((name) => ` globalThis.${name} = ${name};`).join("");
     return `${declare}(async () => { 'use strict';${publish}\n${applyEdits(js, edits)}\n})()`;
 }
 export function transformCell(code, options = {}) {
-    return PRELUDE + rewriteModuleSyntax(stripTypes(code, options));
+    return PRELUDE + rewriteModuleSyntax(stripTypes(code, options)) + SETTLE;
+}
+/**
+ * transformCell, plus the map between the cell's lines and the script's,
+ * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
+ * script's lines are esbuild's, after the prelude's one.
+ */
+export function transformCellWithLines(code, options = {}) {
+    const stripped = stripTypesMapped(code, options, true);
+    return { script: PRELUDE + rewriteModuleSyntax(stripped.code) + SETTLE, lines: new LineMap(stripped.mappings, newlines(PRELUDE)) };
 }
 /**
  * Like transformCell, for a target that evaluates cells itself, as global

package/dist/wire.d.ts

@@ -11,12 +11,17 @@ export interface Header extends JsonObject {
     msg_type: string;
     version: string;
 }
+/** A header as received: the fields the kernel relies on, plus whatever else came. */
+export interface ReceivedHeader extends JsonObject {
+    msg_id: string;
+    msg_type: string;
+}
 export interface Message {
     identities: Uint8Array[];
     sig: string;
     /** Raw bytes of header, parent_header, metadata, content as received. */
     signedParts: Uint8Array[];
-    header: Header;
+    header: ReceivedHeader;
     parentHeader: JsonObject;
     metadata: JsonObject;
     content: JsonObject;
@@ -26,6 +31,8 @@ export declare function sign(key: string, parts: Uint8Array[]): string;
 export declare function verify(key: string, parts: Uint8Array[], sig: string): boolean;
 export declare function makeHeader(session: string, msgType: string): Header;
 export interface EncodeOptions {
+    /** Defaults to a fresh header; pass one to know its msg_id. */
+    header?: Header;
     identities?: Uint8Array[];
     parentHeader?: JsonObject;
     metadata?: JsonObject;

package/dist/wire.js

@@ -41,7 +41,7 @@ export function makeHeader(session, msgType) {
 }
 export function encodeMessage(session, key, msgType, content, options = {}) {
     const parts = [
-        makeHeader(session, msgType),
+        options.header ?? makeHeader(session, msgType),
         options.parentHeader ?? {},
         options.metadata ?? {},
         content,
@@ -70,6 +70,8 @@ function parseObject(frame) {
     }
     return value;
 }
+// Only msg_id and msg_type are required of a received header; nothing
+// reads the rest, so a client that leaves them out still works.
 function isHeader(value) {
     return typeof value.msg_id === "string" && typeof value.msg_type === "string";
 }

package/dist/workerd-target.d.ts

@@ -1,4 +1,4 @@
-import type { CdpParams, EvaluateResult, RemoteObject } from "./cdp.ts";
+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 WsChannel } from "./ws-client.ts";
@@ -53,6 +53,12 @@ export interface WorkerHost {
     stop(now: boolean): void;
     onExit(listener: (code: number | null) => void): void;
 }
+/**
+ * Removes workerd directories under `root` whose kernel has died without
+ * cleaning up (SIGKILL runs no exit hook), killing their workerd if it's
+ * still running (#220).
+ */
+export declare function sweepStaleWorkerdDirs(root?: string): void;
 /** The driver on a workerd of its own, behind a Unix socket. */
 export declare class RawWorkerd implements WorkerHost {
     #private;
@@ -115,6 +121,8 @@ export declare class WorkerdTarget implements KernelTarget {
         stack: string;
     }>;
     propertyNames(expression: string): Promise<string[]>;
+    /** Resolved by property descriptor in the driver, so nothing runs (#10). */
+    inspect(path: string, detail: number): Promise<string | null>;
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames(): Promise<string[]>;
     /** Never asked for: prompt() in workerd answers null without asking. */

package/dist/workerd-target.js

@@ -18,20 +18,22 @@ import { Buffer } from "node:buffer";
 import process from "node:process";
 import { execFileSync, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { copyFileSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
 import { builtinModules } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { build } from "esbuild";
+import { asEvaluateResult } from "./cdp.js";
 import { transformCellForEval } from "./transform.js";
 import { runtimeDir } from "./package.js";
+import { killOnExit } from "./children.js";
 import { Interrupted, isTargetMessage } from "./target.js";
 import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
-import { ensureInstalled, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
+import { ensureInstalledAsync, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
 /** The driver Worker's modules; the first is its main module. */
-export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs"];
+export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs", "introspect.mjs"];
 /** See BunTarget: how long an interrupted cell has to show it isn't busy. */
 export const INTERRUPT_GRACE_MS = 500;
 export function restartNote(runtime) {
@@ -121,7 +123,8 @@ export async function bundleModule(specifier, cwd) {
                 ? jsrToNpm(specifier.slice(4))
                 : null;
         if (pkg) {
-            const { dir, alias } = ensureInstalled(pkg);
+            // Async: a sync install would stall the heartbeat and interrupts (#149).
+            const { dir, alias } = await ensureInstalledAsync(pkg, "npm", { lockFile: findLockFile(cwd) });
             entry = alias + pkg.subpath;
             resolveDir = dir;
         }
@@ -168,6 +171,65 @@ export function cellMeta(cwd) {
     const replUrl = new URL("$cdpk$repl.mjs", pathToFileURL(cwd.endsWith("/") ? cwd : cwd + "/"));
     return { url: replUrl.href, dirname: cwd, filename: join(cwd, "$cdpk$repl.mjs") };
 }
+const WORKERD_DIR_PREFIX = "cdpk-workerd-";
+/** In each workerd directory: `{ host, workerd }` pids. */
+const OWNER_FILE = "owner.json";
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Whether `pid` is still the workerd serving `dir`, not a reused pid. */
+function isWorkerdIn(pid, dir) {
+    try {
+        if (process.platform === "linux")
+            return readlinkSync(`/proc/${pid}/cwd`) === dir;
+        const args = execFileSync("ps", ["-o", "args=", "-p", String(pid)], { encoding: "utf8" });
+        return /workerd/.test(args) && args.includes("config.capnp");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes workerd directories under `root` whose kernel has died without
+ * cleaning up (SIGKILL runs no exit hook), killing their workerd if it's
+ * still running (#220).
+ */
+export function sweepStaleWorkerdDirs(root = tmpdir()) {
+    let names;
+    try {
+        names = readdirSync(root).filter((name) => name.startsWith(WORKERD_DIR_PREFIX));
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const dir = join(root, name);
+        let owner;
+        try {
+            owner = JSON.parse(readFileSync(join(dir, OWNER_FILE), "utf8"));
+        }
+        catch {
+            continue; // Another user's, from before owner files, or being set up.
+        }
+        if (typeof owner.host !== "number" || pidAlive(owner.host))
+            continue;
+        if (typeof owner.workerd === "number" && isWorkerdIn(owner.workerd, dir)) {
+            try {
+                process.kill(owner.workerd, "SIGKILL");
+            }
+            catch {
+                // Gone already.
+            }
+        }
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
 /** The driver on a workerd of its own, behind a Unix socket. */
 export class RawWorkerd {
     runtime;
@@ -184,7 +246,9 @@ export class RawWorkerd {
         const source = await runtimeDir(new URL("../runtime/", import.meta.url).href);
         // mkdtemp makes the directory 0700: only this user reaches the socket,
         // and the token stops anything else running as them by accident.
-        const dir = mkdtempSync(join(tmpdir(), "cdpk-workerd-"));
+        sweepStaleWorkerdDirs();
+        const dir = mkdtempSync(join(tmpdir(), WORKERD_DIR_PREFIX));
+        writeFileSync(join(dir, OWNER_FILE), JSON.stringify({ host: process.pid }));
         const socket = join(dir, "sock");
         for (const name of WORKER_MODULES)
             copyFileSync(join(source, name), join(dir, name));
@@ -194,11 +258,21 @@ export class RawWorkerd {
         // --experimental: the UnsafeEval binding.
         const child = spawn(workerd, ["serve", "config.capnp", "--experimental"], { cwd: dir, stdio: ["ignore", "pipe", "pipe"], env });
         child.once("exit", () => rmSync(dir, { recursive: true, force: true }));
+        if (child.pid !== undefined)
+            writeFileSync(join(dir, OWNER_FILE), JSON.stringify({ host: process.pid, workerd: child.pid }));
+        killOnExit(child, () => {
+            child.kill("SIGKILL");
+            rmSync(dir, { recursive: true, force: true });
+        });
         // Cell output is captured inside the Worker; what workerd itself prints
         // (its own warnings, errors from background work) goes to the server log.
+        // `early` keeps that output for a startup error only, and stops growing
+        // once the session is open.
         let early = "";
+        let starting = true;
         const log = (chunk) => {
-            early += chunk.toString();
+            if (starting)
+                early += chunk.toString();
             process.stderr.write(`[cdp-kernel workerd] ${chunk}`);
         };
         child.stdout?.on("data", log);
@@ -221,7 +295,10 @@ export class RawWorkerd {
             }
         })();
         try {
-            return new RawWorkerd(child, await Promise.race([ready, exited]), compatibilityDate);
+            const host = new RawWorkerd(child, await Promise.race([ready, exited]), compatibilityDate);
+            starting = false;
+            early = "";
+            return host;
         }
         catch (err) {
             child.kill();
@@ -229,7 +306,16 @@ export class RawWorkerd {
         }
     }
     stop(now) {
-        this.#child.kill(now ? "SIGKILL" : "SIGTERM");
+        if (now) {
+            this.#child.kill("SIGKILL");
+            return;
+        }
+        this.#child.kill("SIGTERM");
+        // A busy isolate keeps workerd's event loop from ever seeing SIGTERM (#128).
+        setTimeout(() => {
+            if (this.#child.exitCode === null && this.#child.signalCode === null)
+                this.#child.kill("SIGKILL");
+        }, 3000).unref();
     }
     onExit(listener) {
         this.#child.once("exit", listener);
@@ -342,6 +428,9 @@ export class WorkerdTarget {
         this.#pending.clear();
     }
     #request(op, params = {}, interruptible = false) {
+        // The channel drops writes after it closes, so nothing would answer.
+        if (this.#exitedOnce)
+            return Promise.reject(new Abandoned("the workerd session is closed"));
         const id = ++this.#nextId;
         return new Promise((resolve, reject) => {
             this.#pending.set(id, { resolve, reject });
@@ -377,7 +466,12 @@ export class WorkerdTarget {
             if (!modules[specifier].startsWith("Promise.reject("))
                 this.#sent.add(specifier);
         }
-        return (await this.#interruptibly("eval", { code: script, modules }, "Execution"));
+        const { failedModules, ...reply } = await this.#interruptibly("eval", { code: script, modules }, "Execution");
+        // A module that threw while loading is rebuilt for its next import (#147).
+        if (Array.isArray(failedModules))
+            for (const specifier of failedModules)
+                this.#sent.delete(specifier);
+        return asEvaluateResult(reply);
     }
     /**
      * A cell that's waiting on something leaves the driver free: it answers a
@@ -435,6 +529,11 @@ export class WorkerdTarget {
         const reply = await this.#request("props", { expr: expression }).catch(() => null);
         return Array.isArray(reply?.names) ? reply.names.filter((n) => typeof n === "string") : [];
     }
+    /** Resolved by property descriptor in the driver, so nothing runs (#10). */
+    async inspect(path, detail) {
+        const reply = await this.#request("inspect", { path, detail }).catch(() => null);
+        return typeof reply?.text === "string" ? reply.text : null;
+    }
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames() {
         return Promise.resolve([]);

package/dist/ws-client.d.ts

@@ -1,6 +1,7 @@
 import { Buffer } from "node:buffer";
 export declare const OP_CONTINUATION = 0;
 export declare const OP_TEXT = 1;
+export declare const OP_BINARY = 2;
 export declare const OP_CLOSE = 8;
 export declare const OP_PING = 9;
 export declare const OP_PONG = 10;
@@ -11,7 +12,10 @@ export interface Frame {
 }
 /** One frame; clients must mask what they send. */
 export declare function encodeFrame(opcode: number, payload: Buffer, mask?: Buffer | null): Buffer;
-/** Splits a byte stream into frames, holding back a partial one. */
+/**
+ * Splits a byte stream into frames, holding back a partial one. Chunks of a
+ * large frame are only joined once the whole frame has arrived.
+ */
 export declare class FrameDecoder {
     #private;
     push(chunk: Buffer): Frame[];