@tlockney/cdp-kernel 0.6.0 → 0.7.1

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/message.d.ts

@@ -0,0 +1,34 @@
+export declare const PROTOCOL_VERSION = "5.3";
+export type JsonObject = {
+    [key: string]: unknown;
+};
+export interface Header extends JsonObject {
+    msg_id: string;
+    session: string;
+    date: string;
+    username: string;
+    msg_type: string;
+    version: string;
+}
+/** A header as received: the fields the kernel relies on, plus whatever else came. */
+export interface ReceivedHeader extends JsonObject {
+    msg_id: string;
+    msg_type: string;
+}
+/** A message from a frontend, decoded (and on ZeroMQ, verified). */
+export interface KernelMessage {
+    header: ReceivedHeader;
+    parentHeader: JsonObject;
+    metadata: JsonObject;
+    content: JsonObject;
+    buffers: Uint8Array[];
+}
+/** A message the kernel sends. */
+export interface OutgoingMessage {
+    header: Header;
+    parentHeader: JsonObject;
+    metadata: JsonObject;
+    content: JsonObject;
+    buffers: Uint8Array[];
+}
+export declare function makeHeader(session: string, msgType: string): Header;

package/dist/message.js

@@ -0,0 +1,14 @@
+// Jupyter message shapes and headers, without the wire format: what the
+// kernel's message handling (src/kernel-core.ts) builds and reads. The
+// framing and HMAC signing that ZeroMQ peers need are in src/wire.ts.
+export const PROTOCOL_VERSION = "5.3";
+export function makeHeader(session, msgType) {
+    return {
+        msg_id: crypto.randomUUID(),
+        session,
+        date: new Date().toISOString(),
+        username: "kernel",
+        msg_type: msgType,
+        version: PROTOCOL_VERSION,
+    };
+}

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.6.0";
+export declare const VERSION = "0.7.1";
 /**
  * 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-18";
+export declare const RELEASE_DATE = "2026-10-19";
 /**
  * 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.6.0";
+export const VERSION = "0.7.1";
 /**
  * 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-18";
+export const RELEASE_DATE = "2026-10-19";
 /**
  * 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

@@ -0,0 +1,92 @@
+import type { CdpParams, EvaluateResult, RemoteObject } from "./cdp.ts";
+import type { DebugChannel } from "./debugger.ts";
+import type { CellTransformOptions } from "./transform.ts";
+/** Targets driven over CDP. */
+export type CdpRuntime = "node" | "deno";
+/** Bun, workerd and celld have their own backends: src/bun-target.ts, src/workerd-target.ts, src/celld-target.ts. */
+export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
+/** Every target: the runtimes a kernelspec names, and the browser's Worker (src/browser/). */
+export type TargetRuntime = RuntimeName | "browser";
+/** What the kernel needs from a target runtime. */
+export interface KernelTarget {
+    readonly runtime: TargetRuntime;
+    readonly versions: {
+        runtime: string;
+        engine: string;
+    };
+    /** Shown once, in the first cell: e.g. which project's bindings loaded. */
+    readonly notice?: string;
+    /** Turns a cell into the script evaluate() takes. */
+    transform(code: string, options: CellTransformOptions): string;
+    /** Runs a transformed cell. Rejects with Interrupted after interrupt(). */
+    evaluate(script: string): Promise<EvaluateResult>;
+    interrupt(): Promise<void>;
+    /** 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;
+    } | {
+        error: {
+            name: string;
+            message: string;
+            stack: string;
+        };
+    }>;
+    describeError(exception: RemoteObject): Promise<{
+        name: string;
+        message: string;
+        stack: string;
+    }>;
+    propertyNames(expression: string): Promise<string[]>;
+    lexicalNames(): Promise<string[]>;
+    /** inspect_request (#10): text describing a dotted path's value, without running anything. */
+    inspect(path: string, detail: number): Promise<string | null>;
+    /** The Debugger domain, on targets driven over CDP (#18). */
+    readonly debug?: DebugChannel;
+    /** Answers the target's pending prompt; `interrupted` makes it throw instead (#121). */
+    replyInput(value: string | null, interrupted?: boolean): void;
+    /** What the host waits on, for a kernel that has stopped answering (#237). */
+    diagnose?(): Promise<CdpParams>;
+    /** Lets go of the last cell's result and error, once they are shown (#286). */
+    releaseResults?(): Promise<void>;
+    kill(): void;
+}
+/** Messages the bootstrap sends: message records on stdout, or Bun's channel. */
+export type TargetMessage = {
+    kind: "iopub";
+    msg_type: string;
+    content: CdpParams;
+    metadata: CdpParams;
+    buffers: string[];
+    barrier: number;
+} | {
+    kind: "input_request";
+    prompt: string;
+    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;
+export interface TargetEvents {
+    stream(name: "stdout" | "stderr", text: string): void;
+    message(msg: TargetMessage): void;
+    /** `note` says why, when the target was stopped on purpose. */
+    exit(code: number | null, note?: string): void;
+}
+export declare class Interrupted extends Error {
+    name: string;
+}

package/dist/target-api.js

@@ -0,0 +1,48 @@
+// 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 {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isTargetMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = value.kind;
+    return (kind === "iopub" || kind === "input_request") &&
+        typeof value.barrier === "number";
+}
+export class Interrupted extends Error {
+    name = "Interrupted";
+}

package/dist/target.d.ts

@@ -1,55 +1,9 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
-import { type CellTransformOptions, transformCell } from "./transform.ts";
+import { transformCell } from "./transform.ts";
 import type { DebugChannel } from "./debugger.ts";
-/** Targets driven over CDP. */
-export type CdpRuntime = "node" | "deno";
-/** Bun, workerd and celld have their own backends: src/bun-target.ts, src/workerd-target.ts, src/celld-target.ts. */
-export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
-/** What the kernel needs from a target runtime. */
-export interface KernelTarget {
-    readonly runtime: RuntimeName;
-    readonly versions: {
-        runtime: string;
-        engine: string;
-    };
-    /** Shown once, in the first cell: e.g. which project's bindings loaded. */
-    readonly notice?: string;
-    /** Turns a cell into the script evaluate() takes. */
-    transform(code: string, options: CellTransformOptions): string;
-    /** Runs a transformed cell. Rejects with Interrupted after interrupt(). */
-    evaluate(script: string): Promise<EvaluateResult>;
-    interrupt(): Promise<void>;
-    /** Resolves once all output and messages sent so far have been delivered. */
-    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[]>;
-    lexicalNames(): Promise<string[]>;
-    /** inspect_request (#10): text describing a dotted path's value, without running anything. */
-    inspect(path: string, detail: number): Promise<string | null>;
-    /** The Debugger domain, on targets driven over CDP (#18). */
-    readonly debug?: DebugChannel;
-    /** Answers the target's pending prompt; `interrupted` makes it throw instead (#121). */
-    replyInput(value: string | null, interrupted?: boolean): void;
-    /** What the host waits on, for a kernel that has stopped answering (#237). */
-    diagnose?(): Promise<CdpParams>;
-    /** Lets go of the last cell's result and error, once they are shown (#286). */
-    releaseResults?(): Promise<void>;
-    kill(): void;
-}
+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). */
     executable?: string;
@@ -68,23 +22,6 @@ export declare function launchCommand(runtime: CdpRuntime, bootstrap: string, {
  * install and in Deno's npm cache alike.
  */
 export declare function esbuildBinary(resolve?: (specifier: string) => string, platform?: string, arch?: string): string | null;
-/** Messages the bootstrap sends: message records on stdout, or Bun's channel. */
-export type TargetMessage = {
-    kind: "iopub";
-    msg_type: string;
-    content: CdpParams;
-    metadata: CdpParams;
-    buffers: string[];
-    barrier: number;
-} | {
-    kind: "input_request";
-    prompt: string;
-    password: boolean;
-    barrier: number;
-};
-/** 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;
 /**
  * Splits one output pipe into text and barrier markers, and releases them
  * in order. A gated marker (one that announces a message) pauses
@@ -134,15 +71,6 @@ export declare class Gates {
     open(n: number): void;
     openAll(): void;
 }
-export interface TargetEvents {
-    stream(name: "stdout" | "stderr", text: string): void;
-    message(msg: TargetMessage): void;
-    /** `note` says why, when the target was stopped on purpose. */
-    exit(code: number | null, note?: string): void;
-}
-export declare class Interrupted extends Error {
-    name: string;
-}
 export declare class Target implements KernelTarget {
     #private;
     readonly runtime: CdpRuntime;
@@ -188,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,6 +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, 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).
@@ -19,8 +21,6 @@ import { killOnExit } from "./children.js";
  */
 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
@@ -84,22 +84,6 @@ export function esbuildBinary(resolve = import.meta.resolve, platform = process.
         return null;
     }
 }
-/** The parsed value, or undefined for text that isn't JSON. */
-export function parseJson(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-}
-export function isTargetMessage(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const kind = value.kind;
-    return (kind === "iopub" || kind === "input_request") &&
-        typeof value.barrier === "number";
-}
 const MARKER_PREFIX = "\x1b[cdpk:";
 // A message record: the message's JSON, which never holds a raw ESC, between
 // "\x1b[cdpk:<" and "\x1b]" (#271).
@@ -327,9 +311,6 @@ export class Gates {
         this.#map.clear();
     }
 }
-export class Interrupted extends Error {
-    name = "Interrupted";
-}
 /** A catch handler: a call interrupt() abandoned becomes Interrupted. */
 function interrupted(what) {
     return (err) => {
@@ -351,6 +332,9 @@ export class Target {
     #undelivered = 0;
     #interrupted = false;
     #paused = false;
+    /** What the debugger asked to pause on (#307), and how many kernel calls hold it off. */
+    #pauseOnExceptions = "none";
+    #unpausable = 0;
     /** Set once the main context is gone: the runtime is exiting (#130). */
     #exiting = false;
     #exited;
@@ -400,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)
@@ -414,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");
@@ -484,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
@@ -511,12 +496,43 @@ export class Target {
     /** The Debugger domain on this target's session, for src/debugger.ts. */
     get debug() {
         return {
-            send: (method, params = {}) => this.#shell.send(method, params),
+            send: (method, params = {}) => {
+                if (method === "Debugger.setPauseOnExceptions") {
+                    this.#pauseOnExceptions = String(params.state ?? "none");
+                    // Applied when the kernel's own call in flight finishes.
+                    if (this.#unpausable > 0)
+                        return Promise.resolve({});
+                }
+                if (method === "Debugger.disable")
+                    this.#pauseOnExceptions = "none";
+                return this.#shell.send(method, params);
+            },
             on: (method, listener) => this.#shell.on(method, listener),
             contextId: this.#contextId,
             baselineGlobals: this.#baselineGlobals,
+            withoutPausing: (call) => this.#withoutPausing(call),
         };
     }
+    /**
+     * Runs the kernel's own inspector call with pausing on exceptions off. A
+     * pause inside a call the inspector dispatches holds that call (Node), or
+     * resumes by itself and leaves Deno's event loop stopped for good, so no
+     * later cell runs (#307). A cell that throws meanwhile doesn't pause.
+     */
+    async #withoutPausing(call) {
+        if (this.#pauseOnExceptions === "none" || this.#paused)
+            return call();
+        if (this.#unpausable++ === 0)
+            await this.#shell.send("Debugger.setPauseOnExceptions", { state: "none" });
+        try {
+            return await call();
+        }
+        finally {
+            if (--this.#unpausable === 0 && !this.#exiting) {
+                await this.#shell.send("Debugger.setPauseOnExceptions", { state: this.#pauseOnExceptions }).catch(() => { });
+            }
+        }
+    }
     // Messages wait until both pipes have caught up to their marker,
     // and are delivered strictly in order.
     #deliver(msg, events) {
@@ -665,12 +681,12 @@ export class Target {
      * even a plain return value in a promise it holds only weakly (#55).
      */
     callFunctionOn(functionDeclaration, args) {
-        return this.#shell.send("Runtime.callFunctionOn", {
+        return this.#withoutPausing(() => this.#shell.send("Runtime.callFunctionOn", {
             functionDeclaration,
             arguments: args,
             executionContextId: this.#contextId,
             returnByValue: true,
-        });
+        }));
     }
     /**
      * For functions that return a promise. The target holds it until after
@@ -699,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/traceback.d.ts

@@ -0,0 +1,75 @@
+import type { LineMap } from "./sourcemap.ts";
+export declare const TRACEBACK_MIME = "application/vnd.nteract.traceback+json";
+/** The //# sourceURL a cell's script runs under while not debugging. */
+export declare function cellName(code: string): string;
+/** A cell that ran: its code, and where the notebook knows it from. */
+export interface CellRecord {
+    code: string;
+    executionCount: number | null;
+    cellId: string | null;
+}
+export interface SourceLine extends Record<string, string | number | boolean> {
+    lineno: number;
+    source: string;
+}
+export interface TracebackFrame extends Record<string, unknown> {
+    filename: string;
+    lineno: number;
+    colno?: number;
+    name: string;
+    library: boolean;
+    lines: SourceLine[];
+    execution_count?: number;
+    cell_id?: string;
+}
+/** A frame of CDP's exceptionDetails.stackTrace (0-based positions). */
+export interface CallFrame {
+    url: string;
+    lineNumber: number;
+    columnNumber: number;
+}
+/** A frame as parsed from one line of a stack. */
+export interface StackFrame {
+    name: string;
+    file: string;
+    line: number | null;
+    column: number | null;
+}
+/** One line of a stack as a frame, or null for a line that isn't one (the message). */
+export declare function parseFrame(text: string): StackFrame | null;
+/**
+ * Frames from packages, runtimes and the kernel itself, which a frontend
+ * can dim or fold: a hint, not a boundary.
+ */
+export declare function isLibraryFile(file: string, kernelFiles?: readonly string[]): boolean;
+export interface TracebackSources {
+    /** The cell a script name belongs to, if it is one. */
+    cell(file: string): (CellRecord & {
+        lines: LineMap | null;
+    }) | undefined;
+    /** Another file's source, when it can be read. */
+    readFile?(file: string): string | undefined;
+    /** Path or URL prefixes of the kernel's own runtime files. */
+    kernelFiles?: readonly string[];
+}
+export interface Traceback {
+    /** The classic traceback lines, with cell frames pointing at the cell. */
+    lines: string[];
+    /** The structured payload. */
+    payload: Record<string, unknown>;
+}
+/**
+ * `stack` is the error's stack as the target describes it (src/target.ts's
+ * describeError), message lines included. `callFrames`, from CDP, name the
+ * scripts of frames the stack shows as "<anonymous>": Deno formats stacks
+ * itself and doesn't use a script's //# sourceURL.
+ */
+export declare function buildTraceback(error: {
+    ename: string;
+    evalue: string;
+    stack: string;
+    callFrames?: readonly CallFrame[];
+}, sources: TracebackSources, execution: {
+    executionCount: number | null;
+    cellId: string | null;
+}): Traceback;