@tlockney/cdp-kernel 0.2.0 → 0.4.0

package/dist/ws-client.d.ts

@@ -0,0 +1,32 @@
+import { Buffer } from "node:buffer";
+export declare const OP_CONTINUATION = 0;
+export declare const OP_TEXT = 1;
+export declare const OP_CLOSE = 8;
+export declare const OP_PING = 9;
+export declare const OP_PONG = 10;
+export interface Frame {
+    fin: boolean;
+    opcode: number;
+    payload: Buffer;
+}
+/** One frame; clients must mask what they send. */
+export declare function encodeFrame(opcode: number, payload: Buffer, mask?: Buffer | null): Buffer;
+/** Splits a byte stream into frames, holding back a partial one. */
+export declare class FrameDecoder {
+    #private;
+    push(chunk: Buffer): Frame[];
+}
+export declare function acceptKey(key: string): string;
+export interface WsChannel {
+    send(text: string): void;
+    onMessage(listener: (text: string) => void): void;
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/** Opens a WebSocket over the Unix socket at `socketPath`. */
+export declare function connectUnixWebSocket(socketPath: string, { path, headers }?: {
+    path?: string;
+    headers?: {
+        [name: string]: string;
+    };
+}): Promise<WsChannel>;

package/dist/ws-client.js

@@ -0,0 +1,166 @@
+// A minimal WebSocket client (RFC 6455) over a Unix socket, for the workerd
+// target's session with its driver Worker (#26). The WebSocket that Node
+// and Deno provide can't connect to a Unix socket, and a TCP listener would
+// be reachable by every local process. Text messages only: that's all the
+// session carries.
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import { connect } from "node:net";
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+export const OP_CONTINUATION = 0x0;
+export const OP_TEXT = 0x1;
+export const OP_CLOSE = 0x8;
+export const OP_PING = 0x9;
+export const OP_PONG = 0xa;
+/** One frame; clients must mask what they send. */
+export function encodeFrame(opcode, payload, mask = randomBytes(4)) {
+    const len = payload.length;
+    const head = len < 126 ? 2 : len < 0x10000 ? 4 : 10;
+    const out = Buffer.alloc(head + (mask ? 4 : 0) + len);
+    out[0] = 0x80 | opcode;
+    const maskBit = mask ? 0x80 : 0;
+    if (len < 126) {
+        out[1] = maskBit | len;
+    }
+    else if (len < 0x10000) {
+        out[1] = maskBit | 126;
+        out.writeUInt16BE(len, 2);
+    }
+    else {
+        out[1] = maskBit | 127;
+        out.writeBigUInt64BE(BigInt(len), 2);
+    }
+    if (mask) {
+        mask.copy(out, head);
+        for (let i = 0; i < len; i++)
+            out[head + 4 + i] = payload[i] ^ mask[i & 3];
+    }
+    else {
+        payload.copy(out, head);
+    }
+    return out;
+}
+/** Splits a byte stream into frames, holding back a partial one. */
+export class FrameDecoder {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        const frames = [];
+        for (;;) {
+            const b = this.#buffer;
+            if (b.length < 2)
+                break;
+            const masked = (b[1] & 0x80) !== 0;
+            let len = b[1] & 0x7f;
+            let offset = 2;
+            if (len === 126) {
+                if (b.length < 4)
+                    break;
+                len = b.readUInt16BE(2);
+                offset = 4;
+            }
+            else if (len === 127) {
+                if (b.length < 10)
+                    break;
+                len = Number(b.readBigUInt64BE(2));
+                offset = 10;
+            }
+            const maskAt = offset;
+            if (masked)
+                offset += 4;
+            if (b.length < offset + len)
+                break;
+            const payload = Buffer.from(b.subarray(offset, offset + len));
+            if (masked)
+                for (let i = 0; i < len; i++)
+                    payload[i] ^= b[maskAt + (i & 3)];
+            frames.push({ fin: (b[0] & 0x80) !== 0, opcode: b[0] & 0x0f, payload });
+            this.#buffer = b.subarray(offset + len);
+        }
+        return frames;
+    }
+}
+export function acceptKey(key) {
+    return createHash("sha1").update(key + GUID).digest("base64");
+}
+/** Opens a WebSocket over the Unix socket at `socketPath`. */
+export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } = {}) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ path: socketPath });
+        const key = randomBytes(16).toString("base64");
+        const messageListeners = [];
+        const closeListeners = [];
+        let open = false;
+        let closed = false;
+        let head = Buffer.alloc(0);
+        const decoder = new FrameDecoder();
+        let parts = [];
+        const finish = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (!open)
+                reject(new Error("the WebSocket closed before it opened"));
+            for (const listener of closeListeners)
+                listener();
+        };
+        const write = (opcode, payload) => {
+            if (!closed)
+                socket.write(encodeFrame(opcode, payload));
+        };
+        const channel = {
+            send: (text) => write(OP_TEXT, Buffer.from(text)),
+            onMessage: (listener) => void messageListeners.push(listener),
+            onClose: (listener) => void closeListeners.push(listener),
+            close() {
+                write(OP_CLOSE, Buffer.alloc(0));
+                socket.end();
+            },
+        };
+        const onFrames = (frames) => {
+            for (const frame of frames) {
+                if (frame.opcode === OP_TEXT || frame.opcode === OP_CONTINUATION) {
+                    parts.push(frame.payload);
+                    if (frame.fin) {
+                        const text = Buffer.concat(parts).toString("utf8");
+                        parts = [];
+                        for (const listener of messageListeners)
+                            listener(text);
+                    }
+                }
+                else if (frame.opcode === OP_PING) {
+                    write(OP_PONG, frame.payload);
+                }
+                else if (frame.opcode === OP_CLOSE) {
+                    socket.end();
+                }
+            }
+        };
+        socket.on("data", (chunk) => {
+            if (open)
+                return onFrames(decoder.push(chunk));
+            head = Buffer.concat([head, chunk]);
+            const end = head.indexOf("\r\n\r\n");
+            if (end === -1)
+                return;
+            const response = head.subarray(0, end).toString("latin1");
+            const accept = /^sec-websocket-accept:\s*(\S+)/im.exec(response)?.[1];
+            if (!/^HTTP\/1\.1 101 /.test(response) || accept !== acceptKey(key)) {
+                socket.destroy();
+                reject(new Error(`the WebSocket handshake failed: ${response.split("\r\n")[0]}`));
+                return;
+            }
+            open = true;
+            resolve(channel);
+            onFrames(decoder.push(head.subarray(end + 4)));
+        });
+        socket.on("error", (err) => {
+            if (!open)
+                reject(err);
+        });
+        socket.on("close", finish);
+        const extra = Object.entries(headers).map(([name, value]) => `${name}: ${value}\r\n`).join("");
+        socket.write(`GET ${path} HTTP/1.1\r\nHost: cdpk\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n` +
+            `Sec-WebSocket-Key: ${key}\r\nSec-WebSocket-Version: 13\r\n${extra}\r\n`);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on any V8 runtime over the Chrome DevTools Protocol",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -8,7 +8,16 @@
     "type": "git",
     "url": "git+https://github.com/tlockney/cdp-kernel.git"
   },
-  "keywords": ["jupyter", "kernel", "typescript", "notebook", "deno", "node", "cdp", "devtools-protocol"],
+  "keywords": [
+    "jupyter",
+    "kernel",
+    "typescript",
+    "notebook",
+    "deno",
+    "node",
+    "cdp",
+    "devtools-protocol"
+  ],
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -44,8 +53,11 @@
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
     "install:node-deno": "node src/main.ts install --runtime node --deno-compat",
+    "install:bun": "node src/main.ts install --runtime bun",
+    "install:workerd": "node src/main.ts install --runtime workerd",
+    "install:celld": "node src/main.ts install --runtime celld",
     "prepack": "npm run build",
-    "test": "node --test test/*.test.ts",
+    "test": "node --test --test-timeout=300000 test/*.test.ts",
     "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py",
     "test:lab": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/lab_widgets.py"
   },
@@ -56,6 +68,8 @@
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "workerd": "1.20261015.1",
+    "wrangler": "4.151.0"
   }
 }

package/runtime/bootstrap.mjs

@@ -4,14 +4,18 @@
 // then drives it over CDP. Everything the host needs from inside the
 // runtime lives on globalThis.__cdpk; output to the host goes through the
 // `__cdpk_send` CDP binding (Runtime.addBinding) plus plain stdout/stderr.
+// Bun is launched as `bun runtime/bootstrap.mjs` and driven over a pipe
+// instead; see bun-channel.mjs.
 //
-// Plain JavaScript on purpose: the same file must load unmodified in Node
-// and in Deno.
+// Plain JavaScript on purpose: the same file must load unmodified in Node,
+// Deno and Bun.
 
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJupyter } from "./display.mjs";
+import { describeValue, inspectPath, resolvePath } from "./introspect.mjs";
 
 const isDeno = typeof globalThis.Deno?.version?.deno === "string";
+const isBun = typeof globalThis.Bun?.version === "string";
 const ENC = new TextEncoder();
 
 const cwd = isDeno ? Deno.cwd() : process.cwd();
@@ -23,7 +27,7 @@ const cwdUrl = pathToFileURL(cwd.endsWith("/") ? cwd : cwd + "/");
 // Stand-in referrer for cell code, like Deno's ./$deno$jupyter_repl.mts.
 const replUrl = new URL("$cdpk$repl.mjs", cwdUrl);
 
-const { inspect, readFile, writeOut, writeErr, readStdinLine } = await platform();
+const { inspect, inspectPlain, readFile, writeOut, writeErr, readStdinLine } = await platform();
 
 function base64(bytes) {
   let binary = "";
@@ -77,7 +81,7 @@ function resolveRelative(specifier) {
   return /^\.{0,2}\//.test(specifier) ? new URL(specifier, replUrl).href : specifier;
 }
 
-if (!isDeno) {
+if (!isDeno && !isBun) {
   // Deno resolves npm:/jsr: natively; Node gets a resolve hook that adds
   // them and re-parents cell imports to the notebook's directory.
   const { installNodeResolveHooks } = await import("./node-hooks.mjs");
@@ -108,12 +112,36 @@ async function denoImport(specifier, options) {
   }
 }
 
+// Bun has neither npm: nor jsr:, and would resolve a bare name from this
+// file's directory. npm:/jsr: install into a per-user cache as on Node
+// (with `bun add`); anything else bare resolves from the notebook's
+// directory, so its node_modules, or Bun's auto-install, supplies it.
+const packages = isBun ? await import("./node-hooks.mjs") : null;
+
+function bunResolve(specifier) {
+  let pkg = null;
+  if (specifier.startsWith("npm:")) pkg = packages.parsePackageSpecifier(specifier.slice(4));
+  else if (specifier.startsWith("jsr:")) pkg = packages.jsrToNpm(specifier.slice(4));
+  if (pkg) {
+    const { dir, alias } = packages.ensureInstalled(pkg, "bun", { lockFile: packages.findLockFile(cwd) });
+    return Bun.resolveSync(alias + pkg.subpath, dir);
+  }
+  // Relative, absolute, or a URL scheme such as node:, bun: or file:.
+  if (/^(?:\.{0,2}\/|[a-z][a-z0-9+.-]*:)/i.test(specifier)) return resolveRelative(specifier);
+  return Bun.resolveSync(specifier, cwd);
+}
+
 globalThis.__cdpk = {
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
   tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
   // Node: the resolve hook re-parents these imports. Deno would resolve
   // relative paths against this file, so denoImport does it here.
-  import: (specifier, options) => (isDeno ? denoImport(specifier, options) : import(specifier, options)),
+  import: (specifier, options) =>
+    isDeno
+      ? denoImport(specifier, options)
+      : isBun
+      ? import(bunResolve(specifier), options)
+      : import(specifier, options),
   meta: {
     url: replUrl.href,
     dirname: cwd,
@@ -121,7 +149,19 @@ globalThis.__cdpk = {
     resolve: (specifier) => new URL(specifier, replUrl).href,
   },
   barrier,
+  // inspect_request (#10). CDP targets find the value with
+  // throwOnSideEffect and describe it here; Bun resolves the path here
+  // too, by descriptor, so nothing runs.
+  describeForInspect: (value, detail) => describeValue(value, { inspect: inspectPlain, detail }),
+  inspectPath: (path, detail) => inspectPath(path, { inspect: inspectPlain, detail }),
+  resolvePath,
   broadcastResult: jupyter.broadcastResult,
+  // The debugger's rich variable viewer (#18), synchronously: it runs while
+  // the target is paused. A value whose $display is async shows as text.
+  richBundle(value) {
+    const bundle = jupyter.formatNow(value);
+    return JSON.stringify(typeof bundle?.then === "function" ? { "text/plain": inspectPlain(value) } : bundle);
+  },
   // Frontend comm messages (#9), from the host's shell channel. Handlers
   // run after one macrotask, like cells, so interrupt can reach them.
   async commDispatch(msgType, content, metadata, buffers64) {
@@ -182,11 +222,20 @@ if (isDeno) {
 // Keep the event loop alive between cells.
 setInterval(() => {}, 1 << 30);
 
+if (isBun) {
+  const { startChannel } = await import("./bun-channel.mjs");
+  const { createHandler } = await import("./evaluator.mjs");
+  startChannel(createHandler(globalThis.__cdpk), {
+    versions: { runtime: Bun.version, engine: `JavaScriptCore (WebKit ${process.versions.webkit.slice(0, 12)})` },
+  });
+}
+
 async function platform() {
   if (isDeno) {
     const stdinBuf = new Uint8Array(1);
     return {
       inspect: (v) => Deno.inspect(v, { colors: true, depth: 4 }),
+      inspectPlain: (v) => Deno.inspect(v, { colors: false, depth: 2 }),
       readFile: (p) => Deno.readFileSync(p),
       writeOut: (s) => Deno.stdout.writeSync(ENC.encode(s)),
       writeErr: (s) => Deno.stderr.writeSync(ENC.encode(s)),
@@ -198,6 +247,7 @@ async function platform() {
   const buf = Buffer.alloc(1);
   return {
     inspect: (v) => util.inspect(v, { colors: true, depth: 4 }),
+    inspectPlain: (v) => util.inspect(v, { colors: false, depth: 2 }),
     readFile: (p) => fs.readFileSync(p),
     writeOut: (s) => process.stdout.write(s),
     writeErr: (s) => process.stderr.write(s),

package/runtime/bun-channel.d.mts

@@ -0,0 +1,3 @@
+import type { Handler } from "./evaluator.mjs";
+
+export function startChannel(handle: Handler, ready: { [key: string]: unknown }, fd?: number): void;

package/runtime/bun-channel.mjs

@@ -0,0 +1,58 @@
+// The Bun target's side of the host connection (#7), in place of CDP.
+//
+// Bun's --inspect speaks the WebKit Inspector Protocol, which has no
+// replMode, Runtime.addBinding or Runtime.terminateExecution, so the host
+// doesn't drive Bun over an inspector. It sends requests as JSON lines over
+// fd 3, a pipe only the host holds (there is no port to discover), and the
+// cells are evaluated here, in-process, by evaluator.mjs. Replies, and the
+// iopub messages that the CDP binding carries for other targets, go back the
+// same way. stdout and stderr stay ordinary pipes, ordered against those
+// messages by bootstrap.mjs's barrier markers.
+
+import fs from "node:fs";
+
+const CHANNEL_FD = 3;
+
+/** Synchronous, like a CDP binding call, so output order is kept. */
+function writeAll(fd, text) {
+  const bytes = Buffer.from(text);
+  for (let offset = 0; offset < bytes.length;) {
+    try {
+      offset += fs.writeSync(fd, bytes, offset);
+    } catch (err) {
+      // The reader's side of the pipe is full; the fd may be non-blocking.
+      if (err.code !== "EAGAIN") throw err;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+    }
+  }
+}
+
+/**
+ * Serves `handle` (see evaluator.mjs) over fd 3 and installs
+ * globalThis.__cdpk_send, the function bootstrap.mjs sends iopub messages
+ * through. `ready` is sent first, once the target can take requests.
+ */
+export function startChannel(handle, ready, fd = CHANNEL_FD) {
+  const send = (message) => writeAll(fd, JSON.stringify(message) + "\n");
+  Object.defineProperty(globalThis, "__cdpk_send", {
+    value: (payload) => writeAll(fd, payload + "\n"),
+    enumerable: false,
+  });
+
+  let buffer = "";
+  const input = fs.createReadStream(null, { fd, autoClose: false, encoding: "utf8" });
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
+      const request = JSON.parse(buffer.slice(0, nl));
+      buffer = buffer.slice(nl + 1);
+      handle(request).then(
+        (reply) => send({ kind: "reply", id: request.id, ...reply }),
+        (err) => send({ kind: "reply", id: request.id, failure: String(err?.stack ?? err) }),
+      );
+    }
+  });
+  // The host is gone; don't linger as an orphan.
+  input.on("end", () => process.exit(0));
+  send({ kind: "ready", ...ready });
+}

package/runtime/deno-compat.mjs

@@ -161,7 +161,9 @@ export function createDenoShim({ jupyter }) {
     rename: async((from, to) => fsp.rename(toPath(from), toPath(to))),
     renameSync: sync((from, to) => fs.renameSync(toPath(from), toPath(to))),
     realPath: async((p) => fsp.realpath(toPath(p))),
-    realPathSync: sync((p) => fs.realpathSync(toPath(p))),
+    // The native call, like fsp.realpath above: the JavaScript one leaves
+    // Windows 8.3 names (RUNNER~1) unexpanded, so the two disagreed (#32).
+    realPathSync: sync((p) => fs.realpathSync.native(toPath(p))),
     makeTempDir: async((options) =>
       fsp.mkdtemp(path.join(options?.dir ?? os.tmpdir(), options?.prefix ?? "deno-"))
     ),

package/runtime/display.d.mts

@@ -47,6 +47,8 @@ export interface JupyterNamespace {
 export interface Jupyter {
   namespace: JupyterNamespace;
   broadcastResult(executionCount: number, result: unknown): Promise<void>;
+  /** format without awaiting; a $display method's promise is returned as is. */
+  formatNow(obj: unknown): unknown;
   confirm(message?: string): boolean;
   prompt(message?: string, defaultValue?: string, options?: { password?: boolean }): string | null;
   /** Routes a frontend comm message into the kernel's comms. */

package/runtime/display.mjs

@@ -146,7 +146,14 @@ function isMediaBundle(obj) {
  */
 export function createJupyter(host) {
   async function format(obj) {
-    if (hasDisplaySymbol(obj)) return await obj[$display]();
+    return await formatNow(obj);
+  }
+
+  // format without awaiting: the debugger's variable viewer formats values
+  // while the target is paused, when no promise settles (#18). A $display
+  // method's promise is the caller's to handle.
+  function formatNow(obj) {
+    if (hasDisplaySymbol(obj)) return obj[$display]();
     if (typeof obj !== "object" || obj === null) return { "text/plain": host.inspect(obj) };
     if (isCanvasLike(obj)) {
       const [prefix, data] = obj.toDataURL().split(",");
@@ -240,6 +247,7 @@ export function createJupyter(host) {
       widget: createWidgetFactory(comms.api, $display),
     },
     broadcastResult,
+    formatNow,
     confirm,
     prompt,
     commDispatch: comms.dispatch,

package/runtime/evaluator.d.mts

@@ -0,0 +1,22 @@
+/** The parts of globalThis.__cdpk the evaluator calls. */
+export interface EvaluatorShim {
+  broadcastResult(executionCount: number, value: unknown): void | Promise<void>;
+  describeError(value: unknown): string;
+  commDispatch(msgType: string, content: object, metadata: object, buffers64: string[]): Promise<unknown>;
+  barrier(): number;
+  /** inspect_request's text for a dotted path, or null (#10). */
+  inspectPath(path: string, detail: number): string | null;
+  /** Resolves a dotted path without running getters; see introspect.mjs. */
+  resolvePath?(path: string): import("./introspect.mjs").Resolved;
+}
+
+/** A request from the host: an `op` plus its parameters. */
+export interface EvaluatorRequest {
+  op: string;
+  [key: string]: unknown;
+}
+
+export type Handler = (request: EvaluatorRequest) => Promise<{ [key: string]: unknown }>;
+
+export function propertyNames(value: unknown): string[];
+export function createHandler(shim: EvaluatorShim, evaluate?: (code: string) => unknown): Handler;

package/runtime/evaluator.mjs

@@ -0,0 +1,91 @@
+// The in-process evaluator behind the targets that don't use CDP: Bun (#7),
+// over a pipe (bun-channel.mjs), and workerd (#8), inside a request
+// (workerd-worker.mjs). Cells arrive as global code from
+// src/transform.ts's transformCellForEval, whose value is a promise of the
+// boxed result. Requests and replies mirror the CDP calls the kernel makes
+// of the other targets.
+//
+// No imports: this file must load in every target.
+
+/** Own and inherited property names, as Runtime.getProperties lists them. */
+export function propertyNames(value) {
+  if (value === null || value === undefined) return [];
+  const names = new Set();
+  for (let o = Object(value); o !== null; o = Object.getPrototypeOf(o)) {
+    for (const name of Object.getOwnPropertyNames(o)) names.add(name);
+  }
+  return [...names];
+}
+
+/**
+ * Answers the host's requests. `shim` is globalThis.__cdpk; `evaluate` runs
+ * global code. Values the host refers to later (a result to display, an
+ * error to describe) stay here under a handle, the stand-in for a CDP
+ * objectId.
+ */
+export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
+  const handles = new Map();
+  let nextHandle = 0;
+  const remote = (value) => {
+    const objectId = `h${++nextHandle}`;
+    handles.set(objectId, value);
+    return { type: value === null ? "object" : typeof value, objectId };
+  };
+  const take = (objectId) => {
+    const value = handles.get(objectId);
+    handles.delete(objectId);
+    return value;
+  };
+
+  return async function handle(request) {
+    switch (request.op) {
+      case "ping":
+        return {};
+      case "eval": {
+        // The host uses a result's handle before its next cell.
+        handles.clear();
+        try {
+          const box = await evaluate(request.code);
+          return { result: box === undefined ? { type: "undefined" } : remote(box[0]) };
+        } catch (err) {
+          return {
+            exceptionDetails: { text: "Uncaught", lineNumber: 0, columnNumber: 0, exception: remote(err) },
+          };
+        }
+      }
+      case "broadcast":
+        await shim.broadcastResult(request.count, take(request.handle));
+        return {};
+      case "describe":
+        return { value: shim.describeError(take(request.handle)) };
+      case "comm":
+        try {
+          const handled = await shim.commDispatch(request.msgType, request.content, request.metadata, request.buffers);
+          return { handled: handled === true };
+        } catch (err) {
+          return { error: JSON.parse(shim.describeError(err)) };
+        }
+      case "props": {
+        // Completion's expression is a dotted path; resolved by descriptor
+        // where the shim can, so completing `obj.` never runs a getter (#10).
+        if (typeof shim.resolvePath === "function") {
+          const resolved = shim.resolvePath(request.expr);
+          return { names: resolved.found && !resolved.accessor ? propertyNames(resolved.value) : [] };
+        }
+        let value;
+        try {
+          value = evaluate(`(${request.expr})`);
+        } catch {
+          return { names: [] };
+        }
+        return { names: propertyNames(value) };
+      }
+      case "inspect":
+        return { text: shim.inspectPath(request.path, request.detail ?? 0) };
+      case "barrier":
+        return { value: shim.barrier() };
+      default:
+        throw new Error(`unknown request ${JSON.stringify(request.op)}`);
+    }
+  };
+}

package/runtime/introspect.d.mts

@@ -0,0 +1,13 @@
+export type Resolved =
+  | { found: false }
+  | { found: true; accessor: true; name: string }
+  | { found: true; value: unknown; accessor?: undefined };
+
+export function resolvePath(path: string, root?: object): Resolved;
+// deno-lint-ignore ban-types -- classes and functions alike
+export function signatureOf(fn: Function): string;
+export function describeValue(value: unknown, options: { inspect: (value: unknown) => string; detail?: number }): string;
+export function inspectPath(
+  path: string,
+  options: { inspect: (value: unknown) => string; detail?: number; root?: object },
+): string | null;