@tlockney/cdp-kernel 0.7.0 → 0.7.2

package/dist/debugger.js

@@ -8,7 +8,7 @@
 // as their //# sourceURL, so breakpoints bind and frames point at the cell.
 // Lines go through the cell's source map (src/sourcemap.ts), since esbuild
 // rewrites TypeScript.
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import process from "node:process";
@@ -23,6 +23,9 @@ const EXCEPTION_FILTERS = [
     { filter: "caught", label: "Caught Exceptions", default: false },
     { filter: "uncaught", label: "Uncaught Exceptions", default: false },
 ];
+/** URLs of the runtime's built-in modules: Deno's `ext:`, Node's `node:`. */
+const RUNTIME_SCRIPTS = ["^ext:", "^node:"];
+const RUNTIME_SCRIPT = /^(ext|node):/;
 /** Bindings the kernel itself installs, hidden from the variable views. */
 const KERNEL_GLOBALS = new Set(["__cdpk", "__cdpk_send", "jupyter", "prompt", "confirm"]);
 const SCOPE_NAMES = {
@@ -52,6 +55,18 @@ function isCallFrame(value) {
         typeof value.location.lineNumber === "number" && Array.isArray(value.scopeChain) &&
         value.scopeChain.every((scope) => isRecord(scope) && typeof scope.type === "string" && isRemoteObject(scope.object));
 }
+/**
+ * Whether `dir` is a directory, not a symlink, owned by this user and
+ * closed to others. Windows has no uids; its tmpdir() is per-user.
+ */
+function isOwnPrivateDir(dir) {
+    const stat = lstatSync(dir);
+    if (!stat.isDirectory())
+        return false;
+    if (process.getuid === undefined)
+        return true;
+    return stat.uid === process.getuid() && (stat.mode & 0o077) === 0;
+}
 /** A DAP value string for a CDP RemoteObject. */
 export function describeRemote(object) {
     if (object.type === "string")
@@ -256,6 +271,8 @@ export class Debugger {
         if (!channel)
             return;
         await channel.send("Debugger.enable");
+        // Stepping doesn't enter the runtime's own code (#380).
+        await channel.send("Debugger.setBlackboxPatterns", { patterns: RUNTIME_SCRIPTS });
         await channel.send("Debugger.setPauseOnExceptions", { state: this.#pauseOnExceptions });
         this.#cdpBreakpoints.clear();
         for (const path of this.#breakpoints.keys())
@@ -332,21 +349,38 @@ export class Debugger {
     }
     // --- stopped state ----------------------------------------------------------
     #onPaused(params) {
+        const hit = Array.isArray(params.hitBreakpoints) && params.hitBreakpoints.length > 0;
+        const exception = params.reason === "exception" || params.reason === "promiseRejection";
+        if (exception && !hit && this.#inRuntime(params.callFrames)) {
+            // Thrown in the runtime's own code, as Chrome's ignore list treats it.
+            // Deno's lazy node:process setup throws and catches one there, which
+            // blackboxing doesn't always skip, and it held the cell (#380). The
+            // cell still sees an error that reaches it.
+            void this.#channel?.send("Debugger.resume").catch(() => { });
+            return;
+        }
         this.#frames = Array.isArray(params.callFrames) ? params.callFrames.filter(isCallFrame) : [];
         this.#stopped = true;
         for (const notify of this.#pauseWaiters.splice(0))
             notify();
         this.#refs.clear();
-        const hit = Array.isArray(params.hitBreakpoints) && params.hitBreakpoints.length > 0;
         const reason = hit
             ? "breakpoint"
-            : params.reason === "exception" || params.reason === "promiseRejection"
+            : exception
                 ? "exception"
                 : params.reason === "other"
                     ? "step"
                     : String(params.reason ?? "pause");
         this.#event("stopped", { reason, threadId: THREAD_ID, allThreadsStopped: true });
     }
+    /** Whether the top frame is the runtime's own code. */
+    #inRuntime(callFrames) {
+        const top = Array.isArray(callFrames) ? callFrames[0] : undefined;
+        if (!isRecord(top) || !isRecord(top.location))
+            return false;
+        const url = this.#scripts.get(String(top.location.scriptId)) ?? (typeof top.url === "string" ? top.url : "");
+        return RUNTIME_SCRIPT.test(url);
+    }
     #resetStop() {
         this.#stopped = false;
         this.#frames = [];
@@ -526,12 +560,24 @@ export class Debugger {
     }
     #writeCell(path, code) {
         try {
+            mkdirSync(this.prefix, { recursive: true, mode: 0o700 });
+            // The path is predictable (the frontend computes it too), so another
+            // user could have made the directory first and planted symlinks in it:
+            // write only into a directory that is ours and closed to others (#339).
+            if (!isOwnPrivateDir(this.prefix))
+                return;
             if (!this.#cleanupRegistered) {
                 // The files only serve this kernel's frontend: remove them with it.
-                process.once("exit", () => rmSync(this.prefix, { recursive: true, force: true }));
+                process.once("exit", () => {
+                    try {
+                        rmSync(this.prefix, { recursive: true, force: true });
+                    }
+                    catch {
+                        // Best effort; exiting matters more.
+                    }
+                });
                 this.#cleanupRegistered = true;
             }
-            mkdirSync(this.prefix, { recursive: true });
             writeFileSync(path, code);
         }
         catch {

package/dist/kernel-core.d.ts

@@ -37,6 +37,8 @@ export interface KernelHost {
     /** The target's name, for the banner and messages. */
     readonly runtime: string;
     readonly version: string;
+    /** The TypeScript version cells are checked against; TYPESCRIPT_VERSION if not given. */
+    readonly languageVersion?: string;
     readonly channels: KernelChannels;
     launchTarget(events: TargetEvents): Promise<KernelTarget>;
     /** What strips cells' types; esbuild by default (#238). */
@@ -46,6 +48,8 @@ export interface KernelHost {
     /** Shown once, in the first cell: e.g. why a project config wasn't used. */
     readonly warning?: string | null;
     readonly types?: TypeService | null;
+    /** Returned as `capabilities` in kernel_info_reply, when set: what the host offers cells (#384). */
+    readonly capabilities?: JsonObject;
     /** JupyterLab's visual debugger, for targets driven over CDP (#18). */
     createDebugger?(publish: (event: JsonObject) => void, transformOptions: () => CellTransformOptions): Debugger;
     /** A file's source, for the lines around a traceback frame (#322). */
@@ -56,6 +60,11 @@ export interface KernelHost {
     /** After shutdown_reply has gone out. */
     exit(): void;
 }
+/**
+ * kernel_info's language_info.version when the host doesn't know the
+ * installed TypeScript's: the major version package.json depends on.
+ */
+export declare const TYPESCRIPT_VERSION = "6";
 export declare class KernelCore {
     #private;
     constructor(host: KernelHost);

package/dist/kernel-core.js

@@ -14,6 +14,11 @@ import { CellSyntaxError, loadTypeStripper, objectLiteralCandidate, transformCel
 import { checkIsComplete, codePointToUtf16Index, exprAtCursor, inspectTarget, utf16ToCodePointIndex } from "./text.js";
 import { queryHistory } from "./history.js";
 import { buildTraceback, cellName, TRACEBACK_MIME } from "./traceback.js";
+/**
+ * kernel_info's language_info.version when the host doesn't know the
+ * installed TypeScript's: the major version package.json depends on.
+ */
+export const TYPESCRIPT_VERSION = "6";
 function fromBase64(text) {
     return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
 }
@@ -90,6 +95,8 @@ export class KernelCore {
     #input = null;
     /** An interrupt is waiting on the target. */
     #interrupting = false;
+    /** Ends the cell waiting for the target to start, while one is (#336). */
+    #interruptStart = null;
     /** The shell message being handled, and since when. */
     #handling = null;
     // Open comms, for comm_info_request: comm_id -> target_name (#9).
@@ -225,6 +232,23 @@ export class KernelCore {
         });
         return this.#targetStarting;
     }
+    /**
+     * The target for a cell. An interrupt while it starts ends the cell; the
+     * start goes on, bounded by the target's own deadline, for the next one (#336).
+     */
+    async #targetForCell() {
+        if (this.#target)
+            return this.#target;
+        const interrupted = new Promise((_, reject) => {
+            this.#interruptStart = () => reject(new Interrupted("Execution interrupted"));
+        });
+        try {
+            return await Promise.race([this.#ensureTarget(), interrupted]);
+        }
+        finally {
+            this.#interruptStart = null;
+        }
+    }
     #targetEvents() {
         return {
             stream: (name, text) => this.#publish("stream", { name, text }),
@@ -274,6 +298,10 @@ export class KernelCore {
             input.settle({ value: null, interrupted: true });
             return;
         }
+        if (this.#interruptStart !== null) {
+            this.#interruptStart();
+            return;
+        }
         if (!this.#target || !this.#executing)
             return;
         this.#interrupting = true;
@@ -306,6 +334,8 @@ export class KernelCore {
     async #loop(channel, handle) {
         while (!this.#shuttingDown) {
             const received = await this.#channels.recv(channel);
+            // Before the drop below: shellQueued() counted this message too, so
+            // a dropped one takes its own abort slot, not a queued cell's (#340).
             if (channel === "shell") {
                 this.#aborting = this.#abortQueued > 0;
                 if (this.#aborting)
@@ -338,7 +368,7 @@ export class KernelCore {
             implementation_version: this.#host.version,
             language_info: {
                 name: "typescript",
-                version: "5",
+                version: this.#host.languageVersion ?? TYPESCRIPT_VERSION,
                 mimetype: "text/x.typescript",
                 file_extension: ".ts",
                 pygments_lexer: "typescript",
@@ -352,6 +382,7 @@ export class KernelCore {
             // What current ipykernel advertises; JupyterLab itself goes by the
             // kernelspec's metadata.debugger.
             supported_features: this.#debugger !== null ? ["debugger"] : [],
+            ...(this.#host.capabilities ? { capabilities: this.#host.capabilities } : {}),
         };
     }
     // --- control channel ------------------------------------------------------
@@ -648,6 +679,41 @@ export class KernelCore {
         }
         return target.evaluate(transform(code));
     }
+    /** execute_request's user_expressions, each as its value's MIME bundle or the error it threw (#340). */
+    async #userExpressions(target, expressions) {
+        const results = {};
+        if (typeof expressions !== "object" || expressions === null)
+            return results;
+        for (const [name, expression] of Object.entries(expressions)) {
+            results[name] = await this.#userExpression(target, String(expression));
+        }
+        return results;
+    }
+    async #userExpression(target, expression) {
+        try {
+            // On their own lines, so a trailing line comment can't swallow the paren.
+            const source = `(\n${expression}\n)`;
+            const result = await target.evaluate(`${target.transform(source, this.#transformOptions())}\n//# sourceURL=$cdpk$user-expression.ts`);
+            if (result.exceptionDetails) {
+                const exception = result.exceptionDetails.exception;
+                const described = exception
+                    ? await target.describeError(exception)
+                    : { name: "Error", message: result.exceptionDetails.text, stack: "" };
+                return {
+                    status: "error",
+                    ename: described.name || "Error",
+                    evalue: described.message,
+                    traceback: (described.stack || `${described.name}: ${described.message}`).split("\n"),
+                };
+            }
+            return { status: "ok", data: await target.format(result.result), metadata: {} };
+        }
+        catch (err) {
+            const ename = err instanceof CellSyntaxError ? "SyntaxError" : err instanceof Interrupted ? "Interrupted" : "Error";
+            const evalue = err instanceof Error ? err.message : String(err);
+            return { status: "error", ename, evalue, traceback: [`${ename}: ${evalue}`] };
+        }
+    }
     async #execute(msg, peer) {
         const parent = msg.header;
         if (this.#aborting) {
@@ -676,11 +742,12 @@ export class KernelCore {
             this.#projectWarning = null;
         }
         let error = null;
+        let userExpressions = {};
         // nteract's structured traceback, sent as the error message's metadata (#322).
         let structured = null;
         this.#executing = true;
         try {
-            const target = await this.#ensureTarget();
+            const target = await this.#targetForCell();
             if (target.notice !== undefined && this.#noticeShownFor !== target) {
                 // Once per target, in the first cell it runs.
                 this.#noticeShownFor = target;
@@ -709,6 +776,9 @@ export class KernelCore {
             else if (!silent && result.result.type !== "undefined") {
                 await target.broadcastResult(count, result.result);
             }
+            // As in ipykernel: only after a cell that succeeded (#340).
+            if (!result.exceptionDetails)
+                userExpressions = await this.#userExpressions(target, msg.content.user_expressions);
             await target.flush();
         }
         catch (err) {
@@ -746,7 +816,7 @@ export class KernelCore {
                 status: "ok",
                 execution_count: count,
                 payload: [],
-                user_expressions: {},
+                user_expressions: userExpressions,
             });
         }
         this.#status("idle", parent);

package/dist/kernel.js

@@ -2,6 +2,7 @@
 // file's ZeroMQ ports, with a target runtime launched as a child process,
 // the language service in a worker thread, and the visual debugger.
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
@@ -17,6 +18,16 @@ import { cacheRoot, VERSION } from "./package.js";
 import { watchParent } from "./parent.js";
 import { KernelCore } from "./kernel-core.js";
 import { ZmqChannels } from "./zmq-channels.js";
+/** The installed TypeScript's version, for kernel_info's language_info (#340). */
+function typescriptVersion() {
+    try {
+        const { version } = createRequire(import.meta.url)("typescript/package.json");
+        return typeof version === "string" ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Larger files get no source lines in a traceback. */
 const MAX_SOURCE_BYTES = 1 << 20;
 /** A traceback frame's file, read from disk when it is a local one (#322). */
@@ -133,6 +144,7 @@ export class Kernel {
         this.#core = new KernelCore({
             runtime,
             version: VERSION,
+            languageVersion: typescriptVersion(),
             channels: new ZmqChannels(conn, log),
             launchTarget(events) {
                 if (runtime === "bun")

package/dist/main.js

@@ -31,7 +31,17 @@ function kernelsDir() {
         return join(process.env.APPDATA ?? homedir(), "jupyter", "kernels");
     return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "jupyter", "kernels");
 }
+// Jupyter's kernel names; anything else could point outside the kernels
+// directory.
+const KERNEL_NAME = /^[A-Za-z0-9._-]+$/;
+function isKernelName(name) {
+    return KERNEL_NAME.test(name) && name !== "." && name !== "..";
+}
 function install(runtime, denoCompat, typeStrip, languageService, name, display) {
+    if (!isKernelName(name)) {
+        console.error(`install: invalid kernelspec name ${JSON.stringify(name)}; use letters, digits, '.', '_' and '-'`);
+        process.exit(2);
+    }
     const dir = join(kernelsDir(), name);
     mkdirSync(dir, { recursive: true });
     const spec = {
@@ -97,9 +107,6 @@ function list() {
         console.log(`${s.name.padEnd(width)}  ${s.runtime.padEnd(7)}  ${(s.version ?? "-").padEnd(7)}  ${s.dir}`);
     }
 }
-// Jupyter's kernel names; anything else could point outside the kernels
-// directory.
-const KERNEL_NAME = /^[A-Za-z0-9._-]+$/;
 function uninstall(names, all) {
     if (all)
         names = installedSpecs().map((s) => s.name);
@@ -110,7 +117,7 @@ function uninstall(names, all) {
     }
     let failed = false;
     for (const name of names) {
-        const valid = KERNEL_NAME.test(name) && name !== "." && name !== "..";
+        const valid = isKernelName(name);
         const spec = valid ? readOwnSpec(name) : undefined;
         if (!spec) {
             const exists = valid && existsSync(join(kernelsDir(), name));

package/dist/package.d.ts

@@ -1,11 +1,11 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.7.2";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export declare const RELEASE_DATE = "2026-10-19";
+export declare const RELEASE_DATE = "2026-11-02";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It

package/dist/package.js

@@ -14,13 +14,13 @@ import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export const VERSION = "0.7.0";
+export const VERSION = "0.7.2";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export const RELEASE_DATE = "2026-10-19";
+export const RELEASE_DATE = "2026-11-02";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It

package/dist/target-api.d.ts

@@ -24,6 +24,8 @@ export interface KernelTarget {
     /** Resolves once all output and messages sent so far have been delivered. */
     flush(): Promise<void>;
     broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
+    /** A value's MIME bundle, as a cell's result would show it: for user_expressions (#340). */
+    format(value: RemoteObject): Promise<CdpParams>;
     dispatchComm(msgType: string, content: CdpParams, metadata: CdpParams, buffers: Uint8Array[]): Promise<{
         handled: boolean;
     } | {
@@ -66,6 +68,16 @@ export type TargetMessage = {
     password: boolean;
     barrier: number;
 };
+/** A MIME bundle the target sent as JSON text; empty if it isn't one. */
+export declare function parseBundle(text: unknown): CdpParams;
+/** How long a target may take from launch to a usable session. */
+export declare const START_TIMEOUT_MS = 60000;
+/**
+ * `start`, or a rejection once `ms` pass without it settling. The caller
+ * stops whatever was starting: a runtime that never becomes ready would
+ * otherwise wedge the first cell (#52, #336).
+ */
+export declare function withStartTimeout<T>(start: Promise<T>, what: string, ms?: number): Promise<T>;
 /** The parsed value, or undefined for text that isn't JSON. */
 export declare function parseJson(text: string): unknown;
 export declare function isTargetMessage(value: unknown): value is TargetMessage;

package/dist/target-api.js

@@ -1,6 +1,32 @@
 // What the kernel needs from a target runtime, and what a target sends
 // back: the part of src/target.ts with no Node imports, so the kernel's
 // message handling (src/kernel-core.ts) also loads in a browser.
+/** A MIME bundle the target sent as JSON text; empty if it isn't one. */
+export function parseBundle(text) {
+    const bundle = typeof text === "string" ? parseJson(text) : undefined;
+    return typeof bundle === "object" && bundle !== null && !Array.isArray(bundle) ? bundle : {};
+}
+/** How long a target may take from launch to a usable session. */
+export const START_TIMEOUT_MS = 60_000;
+/**
+ * `start`, or a rejection once `ms` pass without it settling. The caller
+ * stops whatever was starting: a runtime that never becomes ready would
+ * otherwise wedge the first cell (#52, #336).
+ */
+export async function withStartTimeout(start, what, ms = START_TIMEOUT_MS) {
+    // Its own rejection, once the deadline has passed, is the caller's to ignore.
+    start.catch(() => { });
+    let timer;
+    const stalled = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} did not start within ${ms / 1000}s`)), ms);
+    });
+    try {
+        return await Promise.race([start, stalled]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** The parsed value, or undefined for text that isn't JSON. */
 export function parseJson(text) {
     try {

package/dist/target.d.ts

@@ -1,8 +1,8 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
 import { transformCell } from "./transform.ts";
 import type { DebugChannel } from "./debugger.ts";
-import { type CdpRuntime, Interrupted, isTargetMessage, type KernelTarget, parseJson, type TargetEvents, type TargetMessage } from "./target-api.ts";
-export { Interrupted, isTargetMessage, parseJson };
+import { type CdpRuntime, Interrupted, isTargetMessage, type KernelTarget, parseBundle, parseJson, type TargetEvents, type TargetMessage } from "./target-api.ts";
+export { Interrupted, isTargetMessage, parseBundle, parseJson };
 export type { CdpRuntime, KernelTarget, RuntimeName, TargetEvents, TargetMessage } from "./target-api.ts";
 export interface LaunchOptions {
     /** Runtime binary; defaults to `deno`, or `node` (this one when hosted by Node). */
@@ -116,6 +116,7 @@ export declare class Target implements KernelTarget {
     callFunctionOn(functionDeclaration: string, args: CdpParams[]): Promise<CdpParams>;
     /** The broadcastResult step of Deno's execute flow (jupyter/mod.rs). */
     broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
+    format(value: RemoteObject): Promise<CdpParams>;
     /**
      * Hands a frontend comm message to the target's comms. Resolves to
      * whether a comm or registered target took it, or to the error a handler

package/dist/target.js

@@ -11,8 +11,8 @@ import { asEvaluateResult, CdpAbandoned, CdpError, CdpSession } from "./cdp.js";
 import { SHIM, transformCell } from "./transform.js";
 import { hostRuntime, isInsideNodeModules, runtimeDir } from "./package.js";
 import { killOnExit } from "./children.js";
-import { Interrupted, isTargetMessage, parseJson } from "./target-api.js";
-export { Interrupted, isTargetMessage, parseJson };
+import { Interrupted, isTargetMessage, parseBundle, parseJson, withStartTimeout, } from "./target-api.js";
+export { Interrupted, isTargetMessage, parseBundle, parseJson };
 /**
  * The inspector keeps every object it returns a remote reference to alive
  * until it is released, so a cell's result would never be collected (#286).
@@ -21,8 +21,6 @@ export { Interrupted, isTargetMessage, parseJson };
  */
 const CELL_GROUP = "cdpk-cell";
 const LOOKUP_GROUP = "cdpk-lookup";
-/** How long a target may take from spawn to a usable session. */
-const START_TIMEOUT_MS = 60_000;
 const MARKER_RE = /\x1b\[cdpk:(\d+)(m?)\]\x1b/;
 const MAX_MARKER_LEN = 24;
 // Lines the runtimes print to stderr on their own: inspector notices, and
@@ -386,13 +384,8 @@ export class Target {
         // A start that fails or stalls must not leave the runtime running: its
         // pipes and inspector sockets would keep this process alive (#52).
         const sessions = [];
-        const timeoutMs = options.startTimeoutMs ?? START_TIMEOUT_MS;
-        let timer;
-        const stalled = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`${cmd} did not start within ${timeoutMs / 1000}s`)), timeoutMs);
-        });
         try {
-            return await Promise.race([Target.#start(runtime, events, cmd, child, sessions), stalled]);
+            return await withStartTimeout(Target.#start(runtime, events, cmd, child, sessions), cmd, options.startTimeoutMs);
         }
         catch (error) {
             for (const session of sessions)
@@ -400,9 +393,6 @@ export class Target {
             child.kill();
             throw error;
         }
-        finally {
-            clearTimeout(timer);
-        }
     }
     static async #start(runtime, events, cmd, child, sessions) {
         child.stdout.setEncoding("utf8");
@@ -470,6 +460,15 @@ export class Target {
             if (params.executionContextId === contextId && target)
                 target.#onExit();
         });
+        // A session that closes on its own (e.g. a frame that isn't JSON, #337)
+        // leaves a target nothing can drive: stop it, so the next cell starts
+        // a fresh one.
+        for (const session of [shell, control]) {
+            session.onClose(() => {
+                if (target)
+                    target.#onExit();
+            });
+        }
         // Wait for the bootstrap's top-level await to finish installing the
         // shim. There is no cap here: launch's start timeout bounds the wait and
         // kills the child, so a slow bootstrap never yields a target without
@@ -716,6 +715,19 @@ export class Target {
             arg,
         ]).catch(interrupted("Execution"));
     }
+    async format(value) {
+        const arg = value.objectId
+            ? { objectId: value.objectId }
+            : value.unserializableValue !== undefined
+                ? { unserializableValue: value.unserializableValue }
+                : { value: value.value };
+        const res = await this.#callAsyncFunctionOn(`function (v) { return globalThis.${SHIM}.formatJson(v); }`, [arg])
+            .catch(interrupted("Execution"));
+        const thrown = res.exceptionDetails;
+        if (thrown)
+            throw new Error(thrown.exception?.description ?? thrown.text ?? "the value could not be formatted");
+        return parseBundle(res.result?.value);
+    }
     /**
      * Hands a frontend comm message to the target's comms. Resolves to
      * whether a comm or registered target took it, or to the error a handler

package/dist/workerd-target.d.ts

@@ -18,6 +18,16 @@ export declare function workerdConfig({ socket, compatibilityDate }: {
  * otherwise use the one on PATH.
  */
 export declare function findWorkerd(cwd: string): string;
+/**
+ * The native workerd binary behind `executable`. npm's workerd package
+ * installs bin/workerd as a Node script that runs the platform package's
+ * binary with execFileSync, and only its postinstall swaps the binary in.
+ * When install scripts don't run (the npm that comes with Node 27 blocks
+ * those not in allowScripts), killing that script leaves the binary running
+ * with the driver socket open, so it's never what the target spawns (#397).
+ * Anything that isn't the workerd package's script is returned as given.
+ */
+export declare function nativeWorkerd(executable: string): string;
 /** "workerd 2026-10-15" -> "2026-10-15": the newest date it supports. */
 export declare function compatibilityDateOf(versionOutput: string): string;
 /** The literal specifiers a transformed cell imports, in order. */
@@ -89,12 +99,16 @@ export declare class WorkerdTarget implements KernelTarget {
     static launch(events: TargetEvents, options?: {
         cwd?: string;
         executable?: string;
+        startTimeoutMs?: number;
     }): Promise<WorkerdTarget>;
     /**
      * A target over a started host's session. `notice` (a project that
      * failed to load) is replaced by the bindings when the host has a project.
      */
-    static open(host: WorkerHost, cwd: string, events: TargetEvents, runtime: WorkersRuntime, notice?: string): Promise<WorkerdTarget>;
+    static open(host: WorkerHost, cwd: string, events: TargetEvents, runtime: WorkersRuntime, options?: {
+        notice?: string;
+        startTimeoutMs?: number;
+    }): Promise<WorkerdTarget>;
     evaluate(script: string): Promise<EvaluateResult>;
     /**
      * A cell that's waiting on something leaves the driver free: it answers a
@@ -115,6 +129,7 @@ export declare class WorkerdTarget implements KernelTarget {
             stack: string;
         };
     }>;
+    format(value: RemoteObject): Promise<CdpParams>;
     describeError(exception: RemoteObject): Promise<{
         name: string;
         message: string;