@tlockney/cdp-kernel 0.5.0 → 0.6.0

package/dist/kernel.js

@@ -5,20 +5,25 @@
 // The thirteen op_jupyter_* calls into Deno's REPL isolate are replaced by
 // a Target driven over CDP (src/target.ts).
 import { Buffer } from "node:buffer";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
 import { decodeMessage, encodeMessage, makeHeader, PROTOCOL_VERSION, verify } from "./wire.js";
-import { PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
+import { listening, PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
 import { Interrupted, Target } from "./target.js";
 import { BunTarget } from "./bun-target.js";
 import { Debugger } from "./debugger.js";
 import { WorkerdTarget } from "./workerd-target.js";
 import { launchCelld } from "./celld-target.js";
-import { CellSyntaxError, objectLiteralCandidate } from "./transform.js";
+import { CellSyntaxError, loadTypeStripper, objectLiteralCandidate, } from "./transform.js";
 import { loadDenoProject } from "./deno-config.js";
 import { checkIsComplete, codePointToUtf16Index, exprAtCursor, inspectTarget, utf16ToCodePointIndex } from "./text.js";
 import { queryHistory } from "./history.js";
+import { LanguageService } from "./language-service.js";
+import { findWranglerConfig } from "./workers-project.js";
 import { VERSION } from "./package.js";
+import { watchParent } from "./parent.js";
 export function parseConnectionInfo(json) {
     const raw = JSON.parse(json);
     if (typeof raw !== "object" || raw === null)
@@ -50,8 +55,11 @@ export function parseConnectionInfo(json) {
         hb_port: info.hb_port,
     };
 }
-/** How long interrupt_request may wait on the target before it's answered anyway (#121). */
-const INTERRUPT_REPLY_WAIT_MS = 5_000;
+/**
+ * How long interrupt_request may wait on the target before it's answered
+ * anyway (#121). Under the 5 s clients allow control requests (#253).
+ */
+const INTERRUPT_REPLY_WAIT_MS = 1_000;
 const NO_INPUT = { value: null, interrupted: false };
 /** Shell requests other than execute_request, and their reply types. */
 const SHELL_REPLIES = {
@@ -62,16 +70,73 @@ const SHELL_REPLIES = {
     history_request: "history_reply",
     comm_info_request: "comm_info_reply",
 };
+/** The target Node's major version, for @types/node: the host's, which is usually the same binary. */
+function nodeMajor() {
+    return process.versions.node?.split(".")[0] ?? "*";
+}
+/**
+ * Where the language service gets each target's globals and imports from
+ * (#273, #275). A `--deno-compat` Node target gets Node's types only: its
+ * `Deno` namespace is partial, and Deno's declarations would promise
+ * members it doesn't have.
+ */
+function languageServiceOptions(runtime, notebookDir, project) {
+    const base = { notebookDir, npmCache: "npm", deno: null, denoTypes: false, typeFiles: [], typePackages: [] };
+    switch (runtime) {
+        case "node":
+            return { ...base, typePackages: [{ name: "@types/node", range: nodeMajor() }] };
+        case "deno":
+            return { ...base, npmCache: null, deno: { config: project?.configPath ?? null }, denoTypes: true };
+        case "bun":
+            return { ...base, npmCache: "bun", typePackages: [{ name: "@types/bun", range: "1" }] };
+        case "workerd":
+        case "celld": {
+            // A Workers project's own types (`wrangler types`) know its bindings.
+            const config = findWranglerConfig(notebookDir);
+            const generated = config === null ? null : join(dirname(config), "worker-configuration.d.ts");
+            return generated !== null && existsSync(generated)
+                ? { ...base, typeFiles: [generated] }
+                : { ...base, typePackages: [{ name: "@cloudflare/workers-types", range: "*" }] };
+        }
+    }
+}
+/** Runtime inspection text without its Type and Signature lines, which the declared type replaces. */
+function withoutSignature(text) {
+    return text.split("\n").filter((line) => !/^(?:Type|Signature): /.test(line)).join("\n");
+}
+/** A TypeScript completion kind as a Jupyter completion type (JupyterLab picks its icon by these). */
+function jupyterType(kind) {
+    switch (kind) {
+        case undefined:
+            return "<unknown>";
+        case "var":
+        case "let":
+        case "const":
+        case "local var":
+        case "parameter":
+            return "variable";
+        case "local function":
+            return "function";
+        case "type":
+        case "alias":
+            return "type";
+        default:
+            return kind;
+    }
+}
 export class Kernel {
     #conn;
     #runtime;
     #denoCompat;
+    #typeStrip;
     // A Deno target in a Deno project uses its config (#13).
     #project;
     #projectWarning = null;
     #noticeShownFor = null;
     /** JupyterLab's visual debugger, for targets driven over CDP (#18). */
     #debugger;
+    /** Typed completion from TypeScript's language service (#273). */
+    #types;
     /** Cells run with store_history, for history_request (#10). */
     #history = [];
     #session = randomUUID();
@@ -79,6 +144,8 @@ export class Kernel {
     #control;
     #stdin;
     #iopub;
+    /** Settles once all five ports are bound (#257). */
+    #bound;
     #target = null;
     #targetStarting = null;
     #executionCount = 0;
@@ -95,6 +162,8 @@ export class Kernel {
     #input = null;
     /** An interrupt is waiting on the target. */
     #interrupting = false;
+    /** The shell message being handled, and since when. */
+    #handling = null;
     // Open comms, for comm_info_request: comm_id -> target_name (#9).
     #comms = new Map();
     #shuttingDown = false;
@@ -102,15 +171,21 @@ export class Kernel {
         this.#conn = conn;
         this.#runtime = runtime;
         this.#denoCompat = options.denoCompat ?? false;
-        this.#project = runtime === "deno" ? this.#loadProject(options.notebookDir ?? process.cwd()) : null;
+        this.#typeStrip = options.typeStrip ?? "esbuild";
+        const notebookDir = options.notebookDir ?? process.cwd();
+        this.#project = runtime === "deno" ? this.#loadProject(notebookDir) : null;
+        this.#types = options.languageService === false
+            ? null
+            : new LanguageService(languageServiceOptions(runtime, notebookDir, this.#project), { log: (text) => this.#log(text) });
         this.#debugger = runtime === "node" || runtime === "deno"
             ? new Debugger((event) => this.#publish("debug_event", event), () => this.#transformOptions())
             : null;
-        startHeartbeat(conn.hb_port, conn.ip);
+        const heartbeat = startHeartbeat(conn.hb_port, conn.ip);
         this.#shell = new RouterSocket(conn.shell_port, conn.ip);
         this.#control = new RouterSocket(conn.control_port, conn.ip);
         this.#stdin = new RouterSocket(conn.stdin_port, conn.ip);
         this.#iopub = new PubSocket(conn.iopub_port, conn.ip);
+        this.#bound = Promise.all([heartbeat, this.#shell.server, this.#control.server, this.#stdin.server, this.#iopub.server].map(listening));
     }
     async run() {
         // Start the runtime eagerly so the first cell doesn't pay for it.
@@ -124,6 +199,18 @@ export class Kernel {
                 process.exit(code);
             });
         }
+        // A server killed before it could shut the kernel down (#254).
+        watchParent(() => {
+            this.#log(`parent ${process.env.JPY_PARENT_PID} exited; shutting down`);
+            this.#shuttingDown = true;
+            process.exit(1);
+        });
+        // A state dump on stderr, for a kernel that has stopped answering (#237).
+        if (process.platform !== "win32")
+            process.on("SIGUSR2", () => void this.#logState());
+        // Transforms are synchronous, so the stripper loads before any cell.
+        if (typeof this.#typeStrip === "string")
+            await loadTypeStripper(this.#typeStrip);
         await Promise.all([this.#loop(this.#shell, (m, p) => this.#handleShell(m, p)),
             this.#loop(this.#control, (m, p) => this.#handleControl(m, p)),
             this.#loop(this.#stdin, (m) => this.#handleStdin(m))]);
@@ -131,6 +218,21 @@ export class Kernel {
     #log(text) {
         process.stderr.write(`[cdp-kernel] ${text}\n`);
     }
+    async #logState() {
+        const handling = this.#handling;
+        const target = this.#target;
+        let targetState = target === null ? (this.#targetStarting === null ? null : "starting") : target.runtime;
+        if (target?.diagnose)
+            targetState = await target.diagnose().catch((err) => `diagnose failed: ${err}`);
+        this.#log(`state: ${JSON.stringify({
+            shell: handling && { msgType: handling.msgType, msgId: handling.msgId, ms: Date.now() - handling.since },
+            queued: this.#shell.incoming.size,
+            executing: this.#executing,
+            interrupting: this.#interrupting,
+            awaitingInput: this.#input !== null,
+            target: targetState,
+        })}`);
+    }
     #loadProject(notebookDir) {
         try {
             return loadDenoProject(notebookDir);
@@ -145,7 +247,7 @@ export class Kernel {
         }
     }
     #transformOptions() {
-        return this.#project?.transform ?? {};
+        return { ...this.#project?.transform, typeStrip: this.#typeStrip };
     }
     // --- comms (#9) ------------------------------------------------------------
     #trackComm(msgType, content) {
@@ -225,7 +327,10 @@ export class Kernel {
     #ensureTarget() {
         if (this.#target)
             return Promise.resolve(this.#target);
-        this.#targetStarting ??= this.#launchTarget().then(async (target) => {
+        // Not before the kernel's own ports are bound: a Deno runtime binds its
+        // inspector to port 0 within milliseconds of starting and can take a
+        // connection-file port the kernel is still binding (#257).
+        this.#targetStarting ??= this.#bound.then(() => this.#launchTarget()).then(async (target) => {
             // Before any cell runs on it, so breakpoints already apply.
             await this.#debugger?.attachTarget(target.debug ?? null);
             this.#target = target;
@@ -243,6 +348,8 @@ export class Kernel {
             message: (msg) => void this.#onTargetMessage(msg).catch((err) => this.#log(`error handling target message: ${err}`)),
             exit: (code, note) => {
                 this.#target = null;
+                // What its cells declared died with it.
+                this.#types?.reset();
                 // Its prompt, if any, died with it; a late reply is dropped.
                 this.#input = null;
                 void this.#debugger?.attachTarget(null);
@@ -320,11 +427,17 @@ export class Kernel {
                 // Unsigned or forged messages are dropped, as in Deno.
                 if (!verify(this.#conn.key, msg.signedParts, msg.sig))
                     continue;
+                if (socket === this.#shell)
+                    this.#handling = { msgType: msg.header.msg_type, msgId: msg.header.msg_id, since: Date.now() };
                 await handle(msg, peer);
             }
             catch (err) {
                 this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
             }
+            finally {
+                if (socket === this.#shell)
+                    this.#handling = null;
+            }
         }
     }
     #kernelInfo() {
@@ -343,7 +456,8 @@ export class Kernel {
                 codemirror_mode: "typescript",
                 nbconvert_exporter: "script",
             },
-            banner: `cdp-kernel on ${this.#runtime} ${versions?.runtime ?? ""} (${versions?.engine || "?"})`,
+            // The runtime's versions are known once it is up.
+            banner: versions ? `cdp-kernel on ${this.#runtime} ${versions.runtime} (${versions.engine || "?"})` : `cdp-kernel on ${this.#runtime}`,
             help_links: [],
             debugger: this.#debugger !== null,
             // What current ipykernel advertises; JupyterLab itself goes by the
@@ -413,7 +527,8 @@ export class Kernel {
         try {
             switch (type) {
                 case "kernel_info_request":
-                    await this.#ensureTarget().catch(() => null);
+                    // Without waiting for the runtime: clients probe with kernel_info
+                    // while it starts, and re-send until answered (#253).
                     this.#reply(this.#shell, peer, msg, "kernel_info_reply", this.#kernelInfo());
                     break;
                 case "complete_request":
@@ -461,15 +576,24 @@ export class Kernel {
             this.#status("idle", msg.header);
         }
     }
-    /** The tooltip (Shift-Tab) for the name at the cursor (#10). */
+    /**
+     * The tooltip (Shift-Tab) for the name at the cursor (#10): its declared
+     * type, signature and JSDoc when the language service knows them (#274),
+     * then what the runtime finds.
+     */
     async #inspect(msg) {
         const code = String(msg.content.code ?? "");
         const cursorCp = typeof msg.content.cursor_pos === "number"
             ? msg.content.cursor_pos
             : utf16ToCodePointIndex(code, code.length);
-        const path = inspectTarget(code, codePointToUtf16Index(code, cursorCp));
+        const cursor = codePointToUtf16Index(code, cursorCp);
+        const path = inspectTarget(code, cursor);
         const detail = msg.content.detail_level === 1 ? 1 : 0;
-        const text = path === null ? null : await (await this.#ensureTarget()).inspect(path, detail);
+        const [runtime, typed] = await Promise.all([
+            path === null ? null : (async () => (await this.#ensureTarget()).inspect(path, detail))(),
+            this.#types?.quickInfo(code, cursor) ?? null,
+        ]);
+        const text = typed === null ? runtime : runtime === null ? typed : `${typed}\n\n${withoutSignature(runtime)}`;
         return text === null
             ? { status: "ok", found: false, data: {}, metadata: {} }
             : { status: "ok", found: true, data: { "text/plain": text }, metadata: {} };
@@ -480,29 +604,59 @@ export class Kernel {
             ? msg.content.cursor_pos
             : utf16ToCodePointIndex(code, code.length);
         const cursor = codePointToUtf16Index(code, cursorCp);
+        // Both at once: the language service may not answer within its budget.
+        const [runtime, typed] = await Promise.all([
+            this.#runtimeCompletions(code, cursor),
+            this.#types?.complete(code, cursor) ?? null,
+        ]);
+        // Declared types first, then what only the runtime knows (a property
+        // added at runtime, a global defined by a library).
+        let matches = runtime.matches;
+        let start = runtime.start;
+        const kinds = new Map();
+        if (typed !== null && typed.start === runtime.start) {
+            for (const entry of typed.entries)
+                kinds.set(entry.name, entry.kind);
+            matches = [...kinds.keys(), ...runtime.matches.filter((name) => !kinds.has(name))];
+        }
+        else if (typed !== null && typed.entries.length > 0 && runtime.matches.length === 0) {
+            // An expression the runtime can't complete, e.g. inside a call.
+            for (const entry of typed.entries)
+                kinds.set(entry.name, entry.kind);
+            matches = [...kinds.keys()];
+            start = typed.start;
+        }
+        const cursorStart = utf16ToCodePointIndex(code, start);
+        return {
+            status: "ok",
+            matches,
+            cursor_start: cursorStart,
+            cursor_end: cursorCp,
+            metadata: kinds.size === 0 ? {} : {
+                // JupyterLab shows each match's type as an icon.
+                _jupyter_types_experimental: matches.map((text) => ({
+                    start: cursorStart,
+                    end: cursorCp,
+                    text,
+                    type: jupyterType(kinds.get(text)),
+                })),
+            },
+        };
+    }
+    /** Completion from the runtime's values: property names, globals, lexical names. */
+    async #runtimeCompletions(code, cursor) {
         const expr = exprAtCursor(code, cursor);
         const target = await this.#ensureTarget();
-        let matches;
-        let start;
         const dot = expr.lastIndexOf(".");
         if (dot !== -1) {
             const prefix = expr.slice(dot + 1);
-            matches = (await target.propertyNames(expr.slice(0, dot)))
+            const matches = (await target.propertyNames(expr.slice(0, dot)))
                 .filter((name) => name.startsWith(prefix) && !name.startsWith("Symbol("));
-            start = cursor - prefix.length;
+            return { matches, start: cursor - prefix.length };
         }
-        else {
-            const names = new Set([...(await target.propertyNames("globalThis")), ...(await target.lexicalNames())]);
-            matches = [...names].filter((name) => name.startsWith(expr) && !name.startsWith("__cdpk")).sort();
-            start = cursor - expr.length;
-        }
-        return {
-            status: "ok",
-            matches,
-            cursor_start: utf16ToCodePointIndex(code, start),
-            cursor_end: cursorCp,
-            metadata: {},
-        };
+        const names = new Set([...(await target.propertyNames("globalThis")), ...(await target.lexicalNames())]);
+        const matches = [...names].filter((name) => name.startsWith(expr) && !name.startsWith("__cdpk")).sort();
+        return { matches, start: cursor - expr.length };
     }
     async #requestInput(prompt, password) {
         // The target asked while an interrupt was already waiting on it.
@@ -599,6 +753,8 @@ export class Kernel {
                 this.#publish("stream", { name: "stderr", text: `${target.notice}\n` });
             }
             const result = await this.#evaluateCell(target, code);
+            // It ran, so its declarations exist, even if it threw part way.
+            this.#types?.addCell(code);
             if (result.exceptionDetails) {
                 const exception = result.exceptionDetails.exception;
                 const described = exception
@@ -632,6 +788,8 @@ export class Kernel {
         finally {
             this.#executing = false;
         }
+        // The result and error are shown: nothing refers to them any more (#286).
+        await this.#target?.releaseResults?.();
         if (error) {
             if (!silent && msg.content.stop_on_error !== false) {
                 // Abort what was queued behind this cell (JupyterLab's Run All sends

package/dist/language-service-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/language-service-worker.js

@@ -0,0 +1,88 @@
+// The worker thread that runs TypeScript's language service for the kernel
+// (#273). It owns a NotebookTypes (src/notebook-types.ts) and answers the
+// host's requests (src/language-service.ts) in order. Loading TypeScript
+// and the first program take most of a second, which here doesn't hold up
+// heartbeats, shell or control messages.
+import { parentPort, workerData } from "node:worker_threads";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+import { ensureInstalledAsync } from "../runtime/node-hooks.mjs";
+import { kernelGlobals, NotebookTypes } from "./notebook-types.js";
+import { DenoResolver, denoTypes } from "./deno-types.js";
+const options = workerData;
+const types = new NotebookTypes(ts, {
+    notebookDir: options.notebookDir,
+    npmCache: options.npmCache,
+    deno: options.deno === null
+        ? undefined
+        : new DenoResolver({ config: options.deno.config, root: join(options.notebookDir, "__cdpk_remote__") }),
+    types: [],
+    typeFiles: options.typeFiles,
+    globals: kernelGlobals(options.display),
+});
+if (options.denoTypes) {
+    const declarations = denoTypes();
+    if (declarations !== null)
+        types.addVirtualTypeFile("__cdpk_deno__.d.ts", declarations);
+    else
+        process.stderr.write("[cdp-kernel] no Deno types for completion: `deno types` failed\n");
+}
+/** A package's declaration entry point: package.json "types"/"typings", else index.d.ts. */
+function typesEntry(dir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        const entry = manifest.types ?? manifest.typings;
+        if (typeof entry === "string")
+            return join(dir, entry);
+    }
+    catch {
+        // No readable package.json: fall back to the convention.
+    }
+    return join(dir, "index.d.ts");
+}
+/**
+ * A type package for the target's globals (@types/node on Node, @types/bun,
+ * @cloudflare/workers-types): the
+ * notebook project's own when it has one, else installed once into the
+ * kernel's npm cache, in the background. Completion goes on without it
+ * meanwhile, and without it at all if the install fails (offline).
+ */
+async function addTypePackage({ name, range }) {
+    const short = name.replace(/^@types\//, "");
+    if (types.resolvesTypes(short)) {
+        types.addTypeNames([short]);
+        return;
+    }
+    try {
+        const { dir, alias } = await ensureInstalledAsync({ name, range });
+        types.addTypeFiles([typesEntry(join(dir, "node_modules", alias))]);
+    }
+    catch (err) {
+        process.stderr.write(`[cdp-kernel] no ${name} for completion: ${err instanceof Error ? err.message : err}\n`);
+    }
+}
+for (const pkg of options.typePackages)
+    void addTypePackage(pkg);
+parentPort?.on("message", (request) => {
+    let response;
+    switch (request.type) {
+        case "cell":
+            types.addCell(request.code);
+            return;
+        case "reset":
+            types.reset();
+            return;
+        case "complete":
+        case "quickInfo":
+            try {
+                response = request.type === "complete"
+                    ? { id: request.id, result: types.complete(request.code, request.cursor) }
+                    : { id: request.id, result: types.quickInfo(request.code, request.cursor) };
+            }
+            catch (err) {
+                response = { id: request.id, error: err instanceof Error ? err.stack ?? err.message : String(err) };
+            }
+            parentPort?.postMessage(response);
+    }
+});

package/dist/language-service.d.ts

@@ -0,0 +1,64 @@
+import type { CompletionResult } from "./notebook-types.ts";
+export type { CompletionEntry, CompletionResult } from "./notebook-types.ts";
+/** What the worker is started with. */
+export interface WorkerOptions {
+    notebookDir: string;
+    /** See NotebookTypesOptions.npmCache. */
+    npmCache: "npm" | "bun" | null;
+    /** A Deno target: resolve imports with `deno info`, under this project config if any. */
+    deno: {
+        config: string | null;
+    } | null;
+    /** Add `deno types` (the Deno namespace) to the globals. */
+    denoTypes: boolean;
+    /** Declaration files for the target's globals, e.g. a Workers project's worker-configuration.d.ts. */
+    typeFiles: string[];
+    /** runtime/display.mjs, which types `jupyter`; null if not a local file. */
+    display: string | null;
+    /** Type packages for the target's globals, e.g. @types/node. */
+    typePackages: {
+        name: string;
+        range: string;
+    }[];
+}
+export type WorkerRequest = {
+    type: "cell";
+    code: string;
+} | {
+    type: "reset";
+} | {
+    type: "complete" | "quickInfo";
+    id: number;
+    code: string;
+    cursor: number;
+};
+export type WorkerResponse = {
+    id: number;
+    result: CompletionResult | string | null;
+} | {
+    id: number;
+    error: string;
+};
+/**
+ * What to start the worker from. Deno's node:worker_threads takes only
+ * file: and data: URLs, so a kernel run from JSR (https:) starts a data:
+ * module that imports the worker.
+ */
+export declare function workerEntry(url?: URL): URL;
+export declare class LanguageService {
+    #private;
+    constructor(options: Omit<WorkerOptions, "display">, { budgetMs, log }?: {
+        budgetMs?: number;
+        log?: (text: string) => void;
+    });
+    /** A cell that ran (even if it threw): its declarations exist now. */
+    addCell(code: string): void;
+    /** The target restarted, so what the cells declared is gone. */
+    reset(): void;
+    /** Typed completions, or null if the service isn't ready within the budget. */
+    complete(code: string, cursor: number): Promise<CompletionResult | null>;
+    /** Type, signature and JSDoc for the name at the cursor, or null. */
+    quickInfo(code: string, cursor: number): Promise<string | null>;
+    /** Ends the worker; the next request starts another. */
+    close(): void;
+}

package/dist/language-service.js

@@ -0,0 +1,128 @@
+// The kernel's side of typed completion and inspection (#273, #274): starts the language-service
+// worker (src/language-service-worker.ts) on the first request, keeps it fed
+// with executed cells, and gives each request a time budget, after which
+// the kernel answers from the runtime alone. The worker is ended after a
+// while without requests, which gives its memory back (about 150 MB).
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+/**
+ * How long a request waits for the worker. JupyterLab gives a kernel's
+ * completions a second, and the runtime's half runs alongside.
+ */
+const BUDGET_MS = 500;
+const IDLE_MS = 10 * 60 * 1000;
+// Compiled to dist/*.js for the npm package, run as .ts from a checkout.
+const WORKER_URL = new URL(import.meta.url.endsWith(".ts") ? "./language-service-worker.ts" : "./language-service-worker.js", import.meta.url);
+const DISPLAY_URL = new URL("../runtime/display.mjs", import.meta.url);
+/**
+ * What to start the worker from. Deno's node:worker_threads takes only
+ * file: and data: URLs, so a kernel run from JSR (https:) starts a data:
+ * module that imports the worker.
+ */
+export function workerEntry(url = WORKER_URL) {
+    if (url.protocol === "file:")
+        return url;
+    return new URL(`data:text/javascript,${encodeURIComponent(`import ${JSON.stringify(url.href)};`)}`);
+}
+export class LanguageService {
+    #options;
+    #budgetMs;
+    #log;
+    /** Executed cells, replayed to a new worker. */
+    #cells = [];
+    #pending = new Map();
+    #worker = null;
+    #nextId = 1;
+    #idle = null;
+    /** The worker couldn't start: don't keep trying. */
+    #broken = false;
+    constructor(options, { budgetMs = BUDGET_MS, log = () => { } } = {}) {
+        this.#options = { ...options, display: DISPLAY_URL.protocol === "file:" ? fileURLToPath(DISPLAY_URL) : null };
+        this.#budgetMs = budgetMs;
+        this.#log = log;
+    }
+    /** A cell that ran (even if it threw): its declarations exist now. */
+    addCell(code) {
+        this.#cells.push(code);
+        this.#worker?.postMessage({ type: "cell", code });
+    }
+    /** The target restarted, so what the cells declared is gone. */
+    reset() {
+        this.#cells.length = 0;
+        this.#worker?.postMessage({ type: "reset" });
+    }
+    /** Typed completions, or null if the service isn't ready within the budget. */
+    async complete(code, cursor) {
+        return (await this.#request("complete", code, cursor));
+    }
+    /** Type, signature and JSDoc for the name at the cursor, or null. */
+    async quickInfo(code, cursor) {
+        return (await this.#request("quickInfo", code, cursor));
+    }
+    #request(type, code, cursor) {
+        const worker = this.#ensureWorker();
+        if (worker === null)
+            return Promise.resolve(null);
+        const id = this.#nextId++;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => settle(null), this.#budgetMs);
+            const settle = (response) => {
+                clearTimeout(timer);
+                this.#pending.delete(id);
+                if (response !== null && "error" in response)
+                    this.#log(`${type} failed: ${response.error}`);
+                resolve(response !== null && "result" in response ? response.result : null);
+            };
+            this.#pending.set(id, settle);
+            worker.postMessage({ type, id, code, cursor });
+        });
+    }
+    /** Ends the worker; the next request starts another. */
+    close() {
+        if (this.#idle !== null)
+            clearTimeout(this.#idle);
+        this.#idle = null;
+        const worker = this.#worker;
+        this.#worker = null;
+        for (const settle of this.#pending.values())
+            settle(null);
+        void worker?.terminate();
+    }
+    #ensureWorker() {
+        if (this.#broken)
+            return null;
+        if (this.#idle !== null)
+            clearTimeout(this.#idle);
+        this.#idle = setTimeout(() => this.close(), IDLE_MS);
+        this.#idle.unref();
+        if (this.#worker !== null)
+            return this.#worker;
+        let worker;
+        try {
+            worker = new Worker(workerEntry(), { workerData: this.#options });
+        }
+        catch (err) {
+            this.#broken = true;
+            this.#log(`typed completion unavailable: ${err instanceof Error ? err.message : err}`);
+            return null;
+        }
+        // An idle worker mustn't keep the kernel alive.
+        worker.unref();
+        worker.on("message", (response) => this.#pending.get(response.id)?.(response));
+        worker.on("error", (err) => {
+            // E.g. typescript failed to load. Completion goes on from the runtime.
+            this.#broken = true;
+            this.#log(`typed completion unavailable: ${err instanceof Error ? err.message : err}`);
+            if (this.#worker === worker)
+                this.close();
+        });
+        worker.on("exit", () => {
+            if (this.#worker === worker)
+                this.close();
+        });
+        for (const code of this.#cells)
+            worker.postMessage({ type: "cell", code });
+        this.#worker = worker;
+        return worker;
+    }
+}