@tlockney/cdp-kernel 0.2.0 → 0.4.0

package/README.md

@@ -3,11 +3,12 @@
 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
@@ -40,17 +41,21 @@ 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):
+**From npm** (host runs on Node 24+). CI tests Node 24 and 26 with Deno 2.9
+and the latest 2.x, on Linux and macOS. Windows isn't supported yet.
 
 ```sh
 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
@@ -65,15 +70,28 @@ 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.
+minimum dependency age policy". Pass `--min-dep-age=0` to the install
+command to get it through:
+
+```sh
+deno run -A --min-dep-age=0 jsr:@tlockney/cdp-kernel/cli install --runtime deno
+```
+
+The kernelspec it writes works on release day too. It relaunches the kernel
+with a dependency cutoff of two days after the release
+(`--min-dep-age=<date>`), so it never resolves anything published after
+that.
 
 **From a checkout**, for working on the kernel itself:
 
@@ -82,6 +100,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.
@@ -103,9 +124,29 @@ In a cell:
   from the notebook's `node_modules`, `node:` builtins, and `npm:pkg@range`
   or `jsr:@scope/pkg@range`.
   - On Node, `npm:` and `jsr:` install on first use into
-    `~/.cache/cdp-kernel/npm`.
+    `~/.cache/cdp-kernel/npm`. An exact version (`npm:react@19.0.0`) installs
+    exactly that version. A range (`npm:react@19`) is resolved the first
+    time it's imported and stays at that version, even as other packages
+    are installed later. Caches written by cdp-kernel 0.3.0 or earlier
+    recorded ranges, which later installs could re-resolve. Delete
+    `~/.cache/cdp-kernel/npm` to start fresh. `jsr:` works with npm 12,
+    which otherwise refuses JSR's registry tarballs.
+  - **Lockfile** (cdp-kernel 0.4.0 or later). To pin versions, create a `cdp-kernel.lock.json` in the
+    notebook's directory (or above it) containing `{}`. From then on, each
+    `npm:`/`jsr:` range is recorded with the exact version it resolved to,
+    and installed at that version, so the notebook gets the same packages
+    on another machine. Commit it next to the notebook. Deno targets use
+    Deno's own resolution and lock instead. Installs into the shared cache
+    are serialized, so two kernels installing at once can't corrupt it.
   - 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);
@@ -120,8 +161,149 @@ In a cell:
   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. Interrupt keeps
-  state.
+- `prompt()` and `confirm()` work over the stdin channel, except on
+  workerd. Interrupt keeps state, except for a busy cell on Bun or workerd
+  (below).
+- **Shift-Tab** shows a tooltip for the name at the cursor: its type, a
+  function's signature (and its source at the second press), a preview, and
+  its properties. Nothing is run to get it. On Node and Deno the value is
+  evaluated with V8's side-effect check (`throwOnSideEffect`), which also
+  guards completion. Bun, workerd and celld look the name up by property,
+  without calling getters. Executed cells are kept for `history_request`
+  (tail, range and search).
+
+## 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`.
+
+## Debugger
+
+On Node and Deno targets, JupyterLab's visual debugger works: the bug
+button in the notebook toolbar, breakpoints in the cell gutter, the call
+stack, variables and scopes, stepping, pause on exceptions, the debug
+console, and the rich variable viewer. The kernel translates the Jupyter
+debug protocol (DAP over `debug_request`) to V8's `Debugger` domain on the
+session it already holds (`src/debugger.ts`):
+
+- **Cell paths.** Each cell is named as JupyterLab names it: a temp-dir
+  prefix plus the Murmur2 hash of its code (`src/murmur2.ts`, matched
+  against ipykernel's). It's evaluated with that name as its
+  `//# sourceURL`, so breakpoints bind to the cell and frames point back at
+  it.
+- **Lines.** Breakpoint and frame lines go through the cell's source map
+  (`src/sourcemap.ts`), since esbuild rewrites the TypeScript. A breakpoint
+  on a blank or type-only line moves to the next statement.
+- **Nothing runs on its own.** The variable explorer between cells reads
+  the cells' declarations with V8's side-effect check, so a getter never
+  runs. Frames, scopes and the rich viewer evaluate on the paused frame.
+- **Kernelspec.** `metadata.debugger` is set for Node and Deno kernelspecs,
+  which is what JupyterLab checks. Reinstall older kernelspecs to get it.
+
+`CDPK_DEBUG_TRACE=1` logs every debug request, reply and event to the
+Jupyter server's log.
+
+Bun, workerd and celld don't run over an inspector, so they have no
+debugger.
 
 ## Editor types
 
@@ -216,8 +398,8 @@ long cell waits for the cell to finish.
 ```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 test:lab   # an anywidget counter in real JupyterLab, headless Chromium (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
 ```
 
@@ -232,12 +414,15 @@ CLI: an installed npm bin, or `deno run -A src/main.ts` to test a Deno host.
 One version number lives in three places: `package.json`, `deno.jsonc` and
 `src/package.ts`. `test/package.test.ts` fails if they disagree. To release:
 
-1. Bump all three, commit, and merge to `main`.
+1. Bump all three, and set `RELEASE_DATE` in `src/package.ts` to today
+   (UTC). Commit, and merge to `main`.
 2. Tag and push: `git tag v0.1.1 && git push origin v0.1.1`.
 
 The `publish` workflow then:
 
-1. Checks that the tag matches the version.
+1. Checks that the tag matches the version, and that `RELEASE_DATE` is
+   today or yesterday. A JSR kernelspec's dependency cutoff comes from that
+   date, so a stale one would block the release it ships in.
 2. Runs the type check, the unit tests, and the e2e suite against the packed
    npm tarball and against a Deno host.
 3. Publishes to JSR (`deno publish`).
@@ -256,22 +441,63 @@ that failed.
 
 - 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:
-  - one npm alias per `name@range`;
-  - no lockfile;
-  - peer dependencies resolve by real name from the shared cache.
+- Inspection tooltips show what's found at runtime (type, signature,
+  preview, properties), not TypeScript types or JSDoc. On Bun, workerd and
+  celld, a getter on the path is reported but not called. History is kept
+  for the current kernel session only.
+- The debugger is for Node and Deno targets only. Breakpoints are per line,
+  conditional breakpoints and logpoints aren't supported, variables can't be
+  set from the debugger, and "copy to globals" isn't offered.
+- `npm:` on Node, Bun, workerd and celld:
+  - one npm alias per `name@range` (or exact version, when locked);
+  - the cache is shared by every notebook, so peer dependencies resolve by
+    real name from it;
+  - a project's own `package.json` doesn't decide an `npm:` import's version
+    (bare imports do use its `node_modules`).
 - No type checking. Deno doesn't type-check REPL cells either.
-- Results are formatted with `util.inspect` on Node, so they look slightly
-  different from Deno's `Deno.inspect`.
+- Results are formatted by each runtime's own inspector: `util.inspect` on
+  Node, Bun, workerd and celld, and `Deno.inspect` on Deno. On a fixture of
+  30 typical values, 23 format identically on Node and Deno. The rest
+  differ in two ways:
+  - strings are quoted `'…'` on Node and `"…"` on Deno, wherever they
+    appear;
+  - a displayed `Error`'s stack also lists Node's own module-loader frames.
+
+  That's deliberate: each runtime's users see the format they expect, and
+  Node's inspector has no quote-style option, short of porting Deno's
+  formatter. `test/formatting.test.ts` runs both runtimes on the fixture
+  and fails if a new kind of difference appears (#17).
 - 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,60 @@
+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[]>;
+    /** Resolved by property descriptor in the target, so nothing runs (#10). */
+    inspect(path: string, detail: number): Promise<string | null>;
+    /** 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,236 @@
+// 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") : [];
+    }
+    /** Resolved by property descriptor in the target, 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([]);
+    }
+    replyInput(value) {
+        this.#child.stdin?.write(JSON.stringify({ value }) + "\n");
+    }
+    kill() {
+        this.#child.kill();
+    }
+}