@tlockney/cdp-kernel 0.1.1 → 0.3.0

package/README.md

@@ -3,15 +3,19 @@
 A Jupyter kernel extracted from Deno's (`deno jupyter`, v2.9.6) that drives
 any V8 runtime over the Chrome DevTools Protocol. The kernel host runs on
 Node or Deno; the code you type runs in a separate **target** runtime:
-Node or Deno today, and anything else whose inspector speaks CDP in
-principle.
+Node or Deno over CDP. Bun, workerd and celld evaluate cells in-process
+instead (see [Bun](#bun), [workerd](#workerd) and [celld](#celld)). In
+principle, anything else whose inspector speaks CDP works too.
 
 This is early software. It passes a conformance suite derived from Deno's
-own Jupyter integration tests on both targets, and it's packaged for npm and
+own Jupyter integration tests on every target, and it's packaged for npm and
 JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet. The
 feasibility study behind it covers the design,
 the other options considered (workerd, Bun, rusty_v8, FFI), and the
-evidence: [`docs/life-after-deno-jupyter.html`](docs/life-after-deno-jupyter.html).
+evidence: [read it online](https://claude.ai/artifact/S66TnTmhCzPy2EW7jbeeue)
+(also in the repo as
+[`docs/life-after-deno-jupyter.html`](docs/life-after-deno-jupyter.html)). It
+was written before packaging, so it calls the project a spike.
 The scripts that produced its runtime findings are in [`probes/`](probes/).
 
 ## Why this shape
@@ -37,9 +41,9 @@ So the extraction is:
 
 ## Install
 
-Each install writes a Jupyter kernelspec: `cdp-node`, `cdp-deno`, or
-`cdp-node-deno` (Node with the Deno compatibility namespace). Then pick the
-kernel in JupyterLab or VS Code.
+Each install writes a Jupyter kernelspec: `cdp-node`, `cdp-deno`,
+`cdp-node-deno` (Node with the Deno compatibility namespace), `cdp-bun`,
+`cdp-workerd`, or `cdp-celld`. Then pick the kernel in JupyterLab or VS Code.
 
 **From npm** (host runs on Node 24+; Node 26 is what's been tested):
 
@@ -48,6 +52,9 @@ npm install -g @tlockney/cdp-kernel
 cdp-kernel install --runtime node
 cdp-kernel install --runtime deno
 cdp-kernel install --runtime node --deno-compat
+cdp-kernel install --runtime bun
+cdp-kernel install --runtime workerd
+cdp-kernel install --runtime celld
 ```
 
 The kernelspec records the absolute paths of `node` and the installed
@@ -62,7 +69,21 @@ deno run -A jsr:@tlockney/cdp-kernel/cli install --runtime deno
 The kernelspec pins the release it was installed from
 (`jsr:@tlockney/cdp-kernel@<version>/cli`). On first launch the target's
 runtime modules are copied into `~/.cache/cdp-kernel/runtime/`. A Node
-target needs `node` on `PATH`.
+target needs `node` on `PATH`, and a Bun target needs `bun` (1.4 is what's
+been tested). A workerd target uses the `workerd` in the notebook
+directory's `node_modules` (a Workers project has one through wrangler),
+or the one on `PATH` (`npm install -g workerd`; 2026-10-15 is what's been
+tested). A celld target uses `~/.local/bin/celld`, where celld's installer
+puts it, or the one on `PATH` (0.6.2 is what's been tested; celld has no
+Windows build).
+
+Deno 2.9+ refuses package versions less than 24 hours old by default
+([minimum dependency age](https://docs.deno.com/go/minimum-dependency-age)).
+In a release's first day, the install command fails with "blocked by the
+minimum dependency age policy". Wait out the day, or install an earlier
+release. Passing `--min-dep-age=0` gets the install through, but the
+kernelspec doesn't carry the flag, so the kernel still won't launch until
+the release is a day old.
 
 **From a checkout**, for working on the kernel itself:
 
@@ -71,6 +92,9 @@ npm ci
 npm run install:node        # kernelspec cdp-node
 npm run install:deno        # kernelspec cdp-deno
 npm run install:node-deno   # kernelspec cdp-node-deno
+npm run install:bun         # kernelspec cdp-bun
+npm run install:workerd     # kernelspec cdp-workerd
+npm run install:celld       # kernelspec cdp-celld
 ```
 
 These kernelspecs point at the checkout, so don't move it after installing.
@@ -93,11 +117,214 @@ In a cell:
   or `jsr:@scope/pkg@range`.
   - On Node, `npm:` and `jsr:` install on first use into
     `~/.cache/cdp-kernel/npm`.
-  - On Deno they use Deno's global cache. The target runs with
-    `--node-modules-dir=none --no-lock`, so a project-local `node_modules`
-    isn't used.
-- `prompt()` and `confirm()` work over the stdin channel. Interrupt keeps
-  state.
+  - On Deno they use Deno's global cache, unless the notebook is in a Deno
+    project (below).
+  - On Bun they install with `bun add` into `~/.cache/cdp-kernel/bun`. Other
+    bare imports resolve from the notebook's directory, so without a
+    `node_modules` there, Bun auto-installs them.
+  - On workerd, the host bundles every import other than a builtin
+    (`node:`, `cloudflare:`) with esbuild, using Workers' resolution
+    conditions, and sends it with the cell. `npm:` and `jsr:` install into
+    the npm cache first, as on Node.
+- **Deno projects.** If a `deno.json` or `deno.jsonc` sits in the notebook's
+  directory or above it, a Deno target uses it, as `deno jupyter` does:
+  - its import map (`"@/": "./lib/"` aliases, mapped packages);
+  - its `nodeModulesDir` setting, with `package.json` dependencies from the
+    project's `node_modules`;
+  - its JSX and decorator `compilerOptions`: `jsx` (`react-jsx`,
+    `react-jsxdev`, `precompile`, `react`), `jsxImportSource`,
+    `jsxFactory`, `jsxFragmentFactory`, `experimentalDecorators`.
+
+  The import map wins over `node_modules`, as in Deno. The kernel never
+  writes to the project's lockfile. A `deno.json` that doesn't parse is
+  reported in the first cell's output, and the kernel runs as in a plain
+  directory. Outside a project, the target runs with
+  `--node-modules-dir=none --no-lock`.
+- `prompt()` and `confirm()` work over the stdin channel, except on
+  workerd. Interrupt keeps state, except for a busy cell on Bun or workerd
+  (below).
+
+## Bun
+
+Bun's `--inspect` speaks the WebKit Inspector Protocol, which lacks what the
+CDP backend relies on: `replMode`, `Runtime.addBinding`,
+`Runtime.terminateExecution`, and top-level `await` in `Runtime.evaluate`.
+So the Bun target has its own backend (`src/bun-target.ts`,
+`runtime/bun-channel.mjs`):
+
+- **No inspector.** The host and Bun exchange JSON lines over a pipe on
+  fd 3, which only the host holds, so there is no port to discover.
+- **Cells run in-process.** Each cell becomes global code wrapped in an
+  async function (`transformCellForEval` in `src/transform.ts`). Its
+  top-level declarations become properties of `globalThis`, so later
+  cells, and closures from this one, see them. This is the
+  tslab/IJavascript technique.
+- **Same output ordering.** stdout and stderr stay pipes, ordered against
+  display messages by the same barrier markers as the CDP targets.
+- **Interrupt.** A cell that's waiting on a promise is interrupted in place,
+  keeping state. A busy one (`while (true) {}`) can't be reached, so Bun is
+  stopped and restarts on the next cell without the earlier state. The cell
+  output says so.
+
+What differs from the CDP targets is listed under [Known gaps](#known-gaps).
+
+## workerd
+
+workerd's inspector can evaluate code, but outside a request there is no
+I/O context: timers, `fetch` and `crypto.randomUUID()` throw "Disallowed
+operation called within global scope". So the workerd target runs its
+cells inside a driver Worker (`src/workerd-target.ts`,
+`runtime/workerd-worker.mjs`):
+
+- **One session.** The host opens a single WebSocket to the driver, and
+  every cell runs inside that session's request. Cells get Workers'
+  `fetch`, `Request`, `caches`, timers and randomness, and anything one
+  cell makes carries over to the next: globals, a Durable Object stub, a
+  stream, a timer still pending.
+- **A private socket.** Outside a Workers project, the host writes a
+  workerd config into a private temporary directory and serves the driver
+  on a Unix socket there, opened with a per-launch token. There is no TCP
+  port and no inspector.
+- **Cells.** Cells are transformed as for Bun and run by workerd's
+  `UnsafeEval` binding (hence `--experimental`).
+- **Output.** `console` output and display messages come back over the
+  session as they happen, in order.
+- **Interrupt.** A cell that's waiting on something is abandoned in place,
+  keeping state, as on Bun. A busy one gets Bun's treatment too: workerd is
+  stopped and restarts on the next cell.
+
+What workerd's own process prints, such as its warnings, goes to the Jupyter
+server log, not the notebook.
+
+### Workers projects
+
+If a `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` sits in the
+notebook's directory or above it, the driver runs on the project's own
+Miniflare, the simulator `wrangler dev` uses, with the project's bindings
+(`src/workers-project.ts`):
+
+- `env` holds the bindings: whatever wrangler translates for Miniflare.
+  Vars, KV, D1 and Durable Objects are tested; R2, Queues and the others
+  go through the same path but aren't.
+- The project's `main` is bundled into the driver, so its Durable Object
+  classes run, and `worker` is its default export:
+  `await worker.fetch(new Request("https://x/"), env)`.
+- State lives in the project's `.wrangler/state/cdp-kernel`, beside
+  `wrangler dev`'s own, so the two never open the same Durable Object.
+- The first cell's output names the bindings. If the project can't load,
+  for example because wrangler isn't installed in it, the first cell says
+  why and the kernel runs on plain workerd.
+
+wrangler and Miniflare come from the project's `node_modules`, so they match
+its versions. Miniflare 4 and 5 both work. Miniflare listens on a loopback
+TCP port, so there the per-launch token is what keeps other local processes
+out.
+
+## celld
+
+[celld](https://github.com/denoland/celld) runs Workers and Durable Objects
+on your own storage. Like workerd it has no I/O outside a request, so the
+celld target runs the same driver Worker over the same WebSocket session
+(`src/celld-target.ts`). Cells, output, interrupts and host-bundled imports
+all work as on workerd. The differences:
+
+- **No `UnsafeEval` needed.** celld allows a plain global `eval`, so it runs
+  without workerd's `--experimental`.
+- **One module.** The host bundles the driver, and a project's `main`, into
+  a single module, and gives celld the result with `no_bundle`. celld
+  doesn't need its own esbuild.
+- **Loopback TCP.** celld listens only on TCP, so the session is a loopback
+  WebSocket opened with a per-launch token. The kernel picks a free port
+  and runs `celld dev --no-watch` on a generated config.
+- **Projects.** In a celld project (a `wrangler.jsonc` or `wrangler.json`
+  at or above the notebook), the generated config copies the project's
+  compatibility settings and bindings: vars, KV, D1, R2, Durable Objects,
+  Queues, Workflows, services, Worker Loaders. `env` and `worker` then work
+  as on workerd. The generated config is written to the project's
+  `.celld/cdp-kernel` and removed when the kernel stops. The state stays
+  there across kernels, beside `celld dev`'s own `.celld/dev`. celld rejects `wrangler.toml`; a project
+  that can't load is reported in the first cell, and the driver runs alone.
+- **Stopping.** `celld dev` runs its node in a separate process group and
+  waits for it to stop gracefully, which a busy cell never allows. So an
+  interrupt of a busy cell kills the node, then `celld dev`.
+
+## Editor types
+
+Cells run untyped, as in `deno jupyter`. Notebook code your editor
+type-checks can declare the globals.
+
+**Node notebooks.** The npm package ships the declarations. Add it as a dev
+dependency, then reference it once from a cell or a `.d.ts` in the project:
+
+```ts
+/// <reference types="@tlockney/cdp-kernel/globals" />
+await jupyter.display(jupyter.md`typed`);
+const name: string | null = prompt("Name?", "", { password: false });
+```
+
+That declares `jupyter`, `prompt` and `confirm`. With the `cdp-node-deno`
+kernel, use `@tlockney/cdp-kernel/globals/deno-compat` instead: it adds the
+`Deno` namespace the compatibility shim implements. A custom display is a
+class with a `[jupyter.$display]()` method returning a MIME bundle.
+`jupyter.$display` is `Symbol.for("Jupyter.display")` at runtime, but only
+`jupyter.$display` carries the precise type.
+
+**Deno notebooks.** Use `Deno.jupyter`, which Deno already types and which a
+Deno target provides. The JSR package doesn't ship these globals, because
+JSR doesn't allow packages to augment global types.
+
+## Widgets and comms
+
+`deno jupyter` has no comms. Here they're supported in both directions, so
+anywidget-style widgets work in frontends with the `anywidget` extension:
+JupyterLab, Notebook 7 and VS Code. Install it with
+`pip install anywidget`; that's the frontend half, no Python kernel needed.
+
+```ts
+const counter = jupyter.widget({
+  esm: `export default {
+    render({ model, el }) {
+      const btn = document.createElement("button");
+      const update = () => { btn.textContent = \`count is \${model.get("count")}\`; };
+      btn.onclick = () => { model.set("count", model.get("count") + 1); model.save_changes(); };
+      model.on("change:count", update);
+      update();
+      el.append(btn);
+    },
+  };`,
+  state: { count: 0 },
+});
+counter.on("change:count", (value) => console.log("clicked to", value));
+counter; // display it
+```
+
+The model API:
+
+- `get(key)`, and `set(key, value)` or `set({ ... })`, which syncs to every
+  view.
+- `on("change:key" | "change" | "msg:custom", listener)` and `off(...)`.
+- `send(content, buffers)` for custom messages.
+- `close()`.
+
+`Uint8Array`, `ArrayBuffer` and `DataView` values in the state travel as
+binary buffers. JupyterLab restores widget state after a page reload over
+the `jupyter.widget.control` comm.
+
+The comm layer underneath is available directly, for other comm-based
+protocols:
+
+```ts
+const comm = jupyter.comm.open("my.target", { hello: 1 });
+comm.onMsg(({ data, buffers }) => console.log(data, buffers.length));
+comm.send({ ping: true });
+jupyter.comm.registerTarget("echo", (comm) => comm.onMsg((m) => comm.send(m.data)));
+```
+
+Comm handlers run like cells. Their output goes to the notebook as replies
+to the message that triggered them, an exception is shown on stderr, and
+interrupt stops a stuck handler. Messages are processed one at a time with
+cell executions, as in ipykernel, so a widget event that arrives during a
+long cell waits for the cell to finish.
 
 ## How the tricky parts work
 
@@ -114,7 +341,8 @@ In a cell:
 ```sh
 npm run check  # tsc --strict over src/ and test/
 npm test       # unit tests (node:test)
-npm run e2e    # conformance suite via jupyter_client/libzmq, on node, deno, node-deno
+npm run e2e    # conformance suite via jupyter_client/libzmq, on every target variant
+npm run test:lab   # an anywidget counter in real JupyterLab, headless Chromium (node, deno, bun, workerd, celld)
 uv run --with nbclient --with nbformat python examples/run_notebook.py   # Deno-style notebook on deno + node-deno
 ```
 
@@ -151,7 +379,8 @@ that failed.
 
 ## Known gaps
 
-- No comms, so no ipywidgets. Deno has none either.
+- Widgets are anywidget-style (`jupyter.widget`). The classic ipywidgets
+  controls (sliders, dropdowns) are Python classes, so they're not available.
 - No `inspect_request` content and no history. Deno has neither.
 - No debugger.
 - `npm:` on Node:
@@ -162,12 +391,36 @@ that failed.
 - Results are formatted with `util.inspect` on Node, so they look slightly
   different from Deno's `Deno.inspect`.
 - WebGPU texture and buffer display is dropped.
-- Targets:
-  - **Bun** speaks the WebKit inspector protocol: no `replMode`, bindings,
-    `terminateExecution`, or top-level await in `Runtime.evaluate`.
-  - **workerd** forbids timers and I/O outside a request.
-
-  Both need a different backend; see the writeup.
+- On Bun:
+  - Interrupting a busy cell restarts Bun and loses state. An awaiting cell
+    keeps it.
+  - Top-level declarations are properties of `globalThis`. A `const` can be
+    reassigned, and declaring a global's name (`const fetch = ...`) replaces
+    that global rather than shadowing it.
+  - Only a trailing expression statement shows a result: `x` does, but
+    `if (c) { x }` doesn't.
+  - Bun 1.4 can't import a module whose path contains `?`.
+  - No `--deno-compat` namespace.
+- On workerd:
+  - All cells share one request, so it never ends. Unlike production
+    Workers, there is no per-request CPU or duration limit, and
+    `ctx.waitUntil` isn't available in a cell.
+  - No `prompt()` or `confirm()` answers: they return `null`, as without a
+    stdin channel. `jupyter.image(path)` can't read files; pass the bytes.
+  - Each imported module is bundled with its dependencies. Two imports that
+    share a dependency each get their own copy.
+  - Interrupting a busy cell restarts workerd and loses state.
+  - Top-level declarations and results behave as on Bun: declarations are
+    `globalThis` properties, and only a trailing expression shows a result.
+  - In a Workers project, `main` is bundled with esbuild directly, not with
+    wrangler's build. Custom `build` commands, `alias` and module `rules`
+    aren't applied.
+- On celld, as on workerd, except:
+  - Only the binding and compatibility keys of a project's config are
+    copied. `assets`, `triggers` and `containers` aren't, and neither is
+    `.dev.vars`. Relative paths inside the copied keys resolve from
+    `.celld/cdp-kernel`, not from the project.
+  - Interrupting a busy cell restarts celld and loses state.
 
 ## Provenance
 

package/dist/bun-target.d.ts

@@ -0,0 +1,58 @@
+import type { CdpParams, EvaluateResult, RemoteObject } from "./cdp.ts";
+import { transformCellForEval } from "./transform.ts";
+import { type KernelTarget, type TargetEvents } from "./target.ts";
+/**
+ * How long an interrupted target has to answer a ping. A cell waiting on a
+ * promise leaves the event loop free, so the answer is near-instant; a busy
+ * one can't answer at all.
+ */
+export declare const INTERRUPT_GRACE_MS = 500;
+export declare const RESTART_NOTE: string;
+export declare function bunLaunchCommand(bootstrap: string, executable?: string): {
+    cmd: string;
+    args: string[];
+};
+export declare class BunTarget implements KernelTarget {
+    #private;
+    readonly runtime = "bun";
+    readonly versions: {
+        runtime: string;
+        engine: string;
+    };
+    readonly transform: typeof transformCellForEval;
+    private constructor();
+    static launch(events: TargetEvents, options?: {
+        cwd?: string;
+        executable?: string;
+    }): Promise<BunTarget>;
+    evaluate(script: string): Promise<EvaluateResult>;
+    /**
+     * There's no terminateExecution, but a cell that's waiting on a promise
+     * leaves the event loop free: the target answers a ping, and the cell is
+     * abandoned with the session intact, like terminateExecution on an idle
+     * isolate (its pending work still runs). A busy cell can't be reached, so
+     * the process is stopped and restarts on the next cell, losing its state.
+     */
+    interrupt(): Promise<void>;
+    flush(): Promise<void>;
+    broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
+    dispatchComm(msgType: string, content: CdpParams, metadata: CdpParams, buffers: Uint8Array[]): Promise<{
+        handled: boolean;
+    } | {
+        error: {
+            name: string;
+            message: string;
+            stack: string;
+        };
+    }>;
+    describeError(exception: RemoteObject): Promise<{
+        name: string;
+        message: string;
+        stack: string;
+    }>;
+    propertyNames(expression: string): Promise<string[]>;
+    /** None: top-level declarations here are properties of globalThis. */
+    lexicalNames(): Promise<string[]>;
+    replyInput(value: string | null): void;
+    kill(): void;
+}

package/dist/bun-target.js

@@ -0,0 +1,231 @@
+// The Bun target (#7). Bun's --inspect speaks the WebKit Inspector Protocol,
+// which has no replMode, Runtime.addBinding or Runtime.terminateExecution, so
+// Bun isn't driven over an inspector at all. The host sends requests over a
+// private pipe (fd 3) to runtime/bun-channel.mjs, which evaluates cells
+// in-process (transformCellForEval). Output ordering is the CDP targets':
+// stdout and stderr are pipes, ordered against channel messages by the
+// bootstrap's barrier markers.
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { transformCellForEval } from "./transform.js";
+import { runtimeDir } from "./package.js";
+import { Gates, Interrupted, isTargetMessage, PipeDemux } from "./target.js";
+/**
+ * How long an interrupted target has to answer a ping. A cell waiting on a
+ * promise leaves the event loop free, so the answer is near-instant; a busy
+ * one can't answer at all.
+ */
+export const INTERRUPT_GRACE_MS = 500;
+export const RESTART_NOTE = "[cdp-kernel] bun was busy and can't be interrupted in place, so it was stopped; " +
+    "it restarts on the next cell, without the earlier cells' state";
+/** Rejects a request whose reply the host no longer waits for. */
+class Abandoned extends Error {
+}
+function isDuplex(stream) {
+    return typeof stream?.write === "function" && typeof stream?.on === "function";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function bunLaunchCommand(bootstrap, executable) {
+    // No flags: Bun reads the notebook directory's bunfig.toml and package.json
+    // on its own, and auto-installs bare imports when there's no node_modules.
+    return { cmd: executable ?? "bun", args: [bootstrap] };
+}
+export class BunTarget {
+    runtime = "bun";
+    versions = { runtime: "", engine: "" };
+    transform = transformCellForEval;
+    #child;
+    #channel;
+    #stdout;
+    #stderr;
+    #gates = new Gates();
+    #pending = new Map();
+    #nextId = 0;
+    #messages = Promise.resolve();
+    #interrupted = false;
+    #stopNote;
+    constructor(child, channel, events) {
+        this.#child = child;
+        this.#channel = channel;
+        this.#stdout = new PipeDemux((text) => events.stream("stdout", text), (n) => this.#gates.wait(n));
+        this.#stderr = new PipeDemux((text) => events.stream("stderr", text), (n) => this.#gates.wait(n));
+    }
+    static async launch(events, options = {}) {
+        const bootstrap = join(await runtimeDir(new URL("../runtime/", import.meta.url).href), "bootstrap.mjs");
+        const { cmd, args } = bunLaunchCommand(bootstrap, options.executable);
+        const env = { ...process.env, FORCE_COLOR: "1" };
+        delete env.NO_COLOR;
+        const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe", "pipe"], env });
+        const channel = child.stdio[3];
+        if (!child.stdout || !child.stderr || !isDuplex(channel)) {
+            child.kill();
+            throw new Error("could not open the pipes to bun");
+        }
+        const target = new BunTarget(child, channel, events);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => target.#stdout.push(chunk));
+        const ready = new Promise((resolve, reject) => {
+            let early = "";
+            const onEarly = (chunk) => (early += chunk);
+            child.stderr?.on("data", onEarly);
+            target.#onReady = (msg) => {
+                child.stderr?.off("data", onEarly);
+                if (early)
+                    target.#stderr.push(early);
+                child.stderr?.on("data", (chunk) => target.#stderr.push(chunk));
+                resolve(msg);
+            };
+            child.once("error", reject);
+            child.once("exit", (code) => reject(new Error(`${cmd} exited (${code}) before it was ready:\n${early}`)));
+        });
+        target.#readChannel(events);
+        child.once("exit", (code) => target.#exited(code, events));
+        const { versions } = await ready;
+        if (isRecord(versions))
+            Object.assign(target.versions, versions);
+        return target;
+    }
+    #onReady = () => { };
+    #readChannel(events) {
+        let buffer = "";
+        this.#channel.setEncoding("utf8");
+        this.#channel.on("data", (chunk) => {
+            buffer += chunk;
+            for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
+                const msg = JSON.parse(buffer.slice(0, nl));
+                buffer = buffer.slice(nl + 1);
+                if (isTargetMessage(msg))
+                    this.#deliver(msg, events);
+                else if (isRecord(msg) && msg.kind === "reply")
+                    this.#settle(msg);
+                else if (isRecord(msg) && msg.kind === "ready")
+                    this.#onReady(msg);
+            }
+        });
+        // A closed pipe is reported through the child's exit.
+        this.#channel.on("error", () => { });
+    }
+    #settle(reply) {
+        const id = Number(reply.id);
+        const pending = this.#pending.get(id);
+        if (!pending)
+            return; // abandoned
+        this.#pending.delete(id);
+        if (typeof reply.failure === "string")
+            pending.reject(new Error(reply.failure));
+        else
+            pending.resolve(reply);
+    }
+    #exited(code, events) {
+        this.#gates.openAll();
+        this.#stdout.close();
+        this.#stderr.close();
+        events.exit(code, this.#stopNote);
+        this.#abandonPending(`bun exited (${code})`);
+    }
+    #abandonPending(reason) {
+        for (const pending of this.#pending.values())
+            pending.reject(new Abandoned(reason));
+        this.#pending.clear();
+    }
+    // Binding messages wait until both pipes have caught up to their marker,
+    // and are delivered strictly in order (as in Target).
+    #deliver(msg, events) {
+        this.#messages = this.#messages.then(async () => {
+            await Promise.all([this.#stdout.waitFor(msg.barrier), this.#stderr.waitFor(msg.barrier)]);
+            events.message(msg);
+            this.#gates.open(msg.barrier);
+        });
+    }
+    #request(op, params = {}) {
+        const id = ++this.#nextId;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            this.#channel.write(JSON.stringify({ id, op, ...params }) + "\n");
+        });
+    }
+    /** A request that interrupt() may cut short. */
+    async #interruptible(op, params, what) {
+        this.#interrupted = false;
+        try {
+            return await this.#request(op, params);
+        }
+        catch (err) {
+            if (err instanceof Abandoned || this.#interrupted)
+                throw new Interrupted(`${what} interrupted`);
+            throw err;
+        }
+    }
+    async evaluate(script) {
+        return (await this.#interruptible("eval", { code: script }, "Execution"));
+    }
+    /**
+     * There's no terminateExecution, but a cell that's waiting on a promise
+     * leaves the event loop free: the target answers a ping, and the cell is
+     * abandoned with the session intact, like terminateExecution on an idle
+     * isolate (its pending work still runs). A busy cell can't be reached, so
+     * the process is stopped and restarts on the next cell, losing its state.
+     */
+    async interrupt() {
+        this.#interrupted = true;
+        const answered = await Promise.race([
+            this.#request("ping").then(() => true, () => false),
+            new Promise((resolve) => setTimeout(() => resolve(false), INTERRUPT_GRACE_MS)),
+        ]);
+        if (answered) {
+            this.#abandonPending("interrupted");
+            return;
+        }
+        this.#stopNote = RESTART_NOTE;
+        this.#child.kill("SIGKILL");
+    }
+    async flush() {
+        const { value } = await this.#request("barrier");
+        const barrier = Number(value);
+        await Promise.all([this.#stdout.waitFor(barrier), this.#stderr.waitFor(barrier)]);
+        await this.#messages;
+    }
+    async broadcastResult(executionCount, result) {
+        if (result.objectId === undefined)
+            return;
+        await this.#request("broadcast", { count: executionCount, handle: result.objectId });
+    }
+    async dispatchComm(msgType, content, metadata, buffers) {
+        const reply = await this.#interruptible("comm", {
+            msgType,
+            content,
+            metadata,
+            buffers: buffers.map((b) => Buffer.from(b).toString("base64")),
+        }, "Comm handler");
+        if (isRecord(reply.error)) {
+            const { name, message, stack } = reply.error;
+            return { error: { name: String(name), message: String(message), stack: String(stack) } };
+        }
+        return { handled: reply.handled === true };
+    }
+    async describeError(exception) {
+        if (exception.objectId === undefined)
+            return { name: "Error", message: exception.description ?? "", stack: "" };
+        const { value } = await this.#request("describe", { handle: exception.objectId });
+        return JSON.parse(typeof value === "string" ? value : '{"name":"Error","message":"","stack":""}');
+    }
+    async propertyNames(expression) {
+        const reply = await this.#request("props", { expr: expression }).catch(() => null);
+        return Array.isArray(reply?.names) ? reply.names.filter((n) => typeof n === "string") : [];
+    }
+    /** None: top-level declarations here are properties of globalThis. */
+    lexicalNames() {
+        return Promise.resolve([]);
+    }
+    replyInput(value) {
+        this.#child.stdin?.write(JSON.stringify({ value }) + "\n");
+    }
+    kill() {
+        this.#child.kill();
+    }
+}