@tlockney/cdp-kernel 0.9.0 → 0.10.0

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.9.0";
+export const VERSION = "0.10.0";
 /**
  * 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-11-09";
+export const RELEASE_DATE = "2026-11-11";
 /**
  * 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
@@ -43,6 +43,7 @@ export const RUNTIME_FILES = [
     "workerd-worker.mjs",
     "display.mjs",
     "comm.mjs",
+    "host.mjs",
     "widget.mjs",
     "node-hooks.mjs",
     "deno-compat.mjs",

package/dist/workerd-target.js

@@ -35,7 +35,7 @@ import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
 import { ensureInstalledAsync, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
 /** The driver Worker's modules; the first is its main module. */
-export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs", "introspect.mjs"];
+export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "host.mjs", "widget.mjs", "evaluator.mjs", "introspect.mjs"];
 /** See BunTarget: how long an interrupted cell has to show it isn't busy. */
 export const INTERRUPT_GRACE_MS = 500;
 export function restartNote(runtime) {
@@ -71,6 +71,7 @@ const driver :Workerd.Worker = (
     (name = "UNSAFE", unsafeEval = void),
     (name = "TOKEN", fromEnvironment = "CDPK_TOKEN"),
     (name = "META", fromEnvironment = "CDPK_META"),
+    (name = "CDPK_PARAMS", fromEnvironment = "CDPK_PARAMS"),
   ],
 );
 `;
@@ -332,7 +333,10 @@ export class RawWorkerd {
             copyFileSync(join(source, name), join(dir, name));
         writeFileSync(join(dir, "config.capnp"), workerdConfig({ socket, compatibilityDate }));
         const token = randomBytes(32).toString("hex");
-        const env = { ...process.env, CDPK_TOKEN: token, CDPK_META: JSON.stringify(cellMeta(cwd)) };
+        const env = { ...process.env, CDPK_TOKEN: token, CDPK_META: JSON.stringify(cellMeta(cwd)),
+            // jupyter.params (#456); always set, so the binding exists.
+            CDPK_PARAMS: process.env.GANYMEDE_PARAMS ?? "",
+        };
         // --experimental: the UnsafeEval binding.
         const child = spawn(workerd, ["serve", "config.capnp", "--experimental"], { cwd: dir, stdio: ["ignore", "pipe", "pipe"], env });
         child.once("exit", () => rmSync(dir, { recursive: true, force: true }));

package/dist/workers-project.js

@@ -185,7 +185,7 @@ export async function startMiniflare(configPath, cwd, startTimeoutMs) {
         unsafeEvalBinding: "UNSAFE",
         compatibilityDate: date,
         compatibilityFlags: compatibilityFlagsFor(workerOptions.compatibilityFlags ?? []),
-        bindings: { ...workerOptions.bindings, TOKEN: token, META: JSON.stringify(cellMeta(cwd)) },
+        bindings: { ...workerOptions.bindings, TOKEN: token, META: JSON.stringify(cellMeta(cwd)), CDPK_PARAMS: process.env.GANYMEDE_PARAMS ?? "" },
         // Miniflare 5 renamed Miniflare 4's defaultPersistRoot.
         ...(v5 ? { resourcePersistencePath: state } : { defaultPersistRoot: state }),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on Node, Deno, Bun, workerd and celld",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -77,11 +77,11 @@
   "dependencies": {
     "acorn": "^8.15.0",
     "acorn-walk": "^8.3.4",
-    "esbuild": "^0.25.10",
+    "esbuild": "^0.28.2",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@types/node": "^24.19.2",
+    "@types/node": "^26.6.6",
     "medium-zoom": "^1.1.0",
     "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",

package/runtime/bootstrap.mjs

@@ -83,6 +83,8 @@ function send(payload) {
 
 const jupyter = createJupyter({
   inspect: (value) => inspect(value),
+  // jupyter.params (#456): the kernel's environment reaches the target.
+  params: () => (isDeno ? Deno.env.get("GANYMEDE_PARAMS") : process.env.GANYMEDE_PARAMS),
   base64,
   readFile,
   send(msgType, content, metadata, buffers) {

package/runtime/browser-worker.mjs

@@ -65,7 +65,10 @@ const jupyter = createJupyter({
   // A synchronous prompt would need SharedArrayBuffer and Atomics.wait, so
   // a cross-origin isolated page; until then, as with no stdin.
   input: () => null,
+  // jupyter.params (#456): the target's `params` option, sent with info.
+  params: () => paramsText,
 });
+let paramsText;
 
 // --- Modules ----------------------------------------------------------------
 let cdn = DEFAULT_CDN;
@@ -150,7 +153,8 @@ async function preload(urls, base) {
 // --- The shim cells and the evaluator use -----------------------------------
 let handle = null;
 
-function install({ base, cdn: cdnBase }) {
+function install({ base, cdn: cdnBase, params }) {
+  if (typeof params === "string") paramsText = params;
   if (typeof cdnBase === "string") cdn = cdnBase.endsWith("/") ? cdnBase : cdnBase + "/";
   const url = new URL("$cdpk$repl.mjs", base).href;
   globalThis.__cdpk = {

package/runtime/display.d.mts

@@ -1,7 +1,8 @@
 import type { CommApi, Comms } from "./comm.d.mts";
+import type { Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch } from "./host.d.mts";
 import type { Widget, WidgetOptions } from "./widget.d.mts";
 
-export type { CommApi, Widget, WidgetOptions };
+export type { CommApi, Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch, Widget, WidgetOptions };
 
 /**
  * The symbol a class implements to choose how its instances appear. At
@@ -23,8 +24,16 @@ export interface DisplayHost {
   readFile: (path: string) => Uint8Array;
   send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void;
   input: (prompt: string, password: boolean) => string | null;
+  /** The run's parameters as JSON text, or `undefined` when there are none. */
+  params?: () => string | undefined;
 }
 
+/** The MIME type of a named result: `{ name, value }`. */
+export const RESULT_MIME: "application/vnd.ganymede.result+json";
+
+/** A JSON value, as `JSON.parse` returns it. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
 /** Options for `jupyter.display`. */
 export interface DisplayOptions {
   /**
@@ -283,6 +292,71 @@ export interface JupyterNamespace {
    * @see jupyter-api.md#stopping-on-interrupt-jupyter-signal
    */
   readonly signal: AbortSignal;
+  /**
+   * The parameters of this run: a frozen object, empty unless whoever
+   * started the kernel passed some, such as `ganymede execute -p
+   * counter="2nd Ave"`. They arrive as a JSON object in the kernel's
+   * `GANYMEDE_PARAMS` environment variable. Take defaults with
+   * destructuring, so the notebook also runs on its own.
+   *
+   * @throws {TypeError} `GANYMEDE_PARAMS` is set but isn't a JSON object.
+   * @availability Node, Deno, Bun, workerd and celld read the kernel's
+   *   environment; the browser target takes `params` from its options.
+   * @example
+   * ```ts
+   * const { counter = "Fremont", days = 30 } = jupyter.params as { counter?: string; days?: number };
+   * `${counter}, last ${days} days`;
+   * ```
+   * @see jupyter-api.md#parameters-and-named-results
+   */
+  readonly params: { readonly [name: string]: JsonValue };
+  /**
+   * Publish a value under a name, as an output that a run's caller reads
+   * by name instead of parsing outputs: `ganymede execute --results`, or
+   * another notebook. The output has the MIME type
+   * `application/vnd.ganymede.result+json` holding `{ name, value }`, and
+   * a `text/plain` line `name = value` for frontends that don't know the
+   * type. When a name is published twice, readers take the last one.
+   *
+   * @param name The result's name.
+   * @param value Any value `JSON.stringify` accepts; it is stored as JSON,
+   *   so a `Date` becomes its ISO string.
+   * @throws {TypeError} `name` is empty, or `value` isn't JSON (a
+   *   function, `undefined`, a `BigInt` or a cycle).
+   * @example
+   * ```ts
+   * const counts = [3120, 2890, 2410];
+   * jupyter.result("weekday_drop", (counts[2] - counts[0]) / counts[0]);
+   * jupyter.result("counts", counts);
+   * ```
+   * @see jupyter-api.md#parameters-and-named-results
+   */
+  result(name: string, value: unknown): void;
+  /**
+   * The Ganymede server running this kernel, through its host API: read,
+   * search and (when granted) run other notebooks under its root. The
+   * server opens a comm to the kernel when it starts; this resolves to
+   * `null` when none answers, as under plain Jupyter.
+   *
+   * Each call returns a promise and takes `{ signal }`, by default
+   * `jupyter.signal`, so an interrupt cancels it. A failed call rejects
+   * with a `HostError` whose `code` says why: `denied` for a notebook or
+   * method this notebook isn't granted. Branch on `code`: `HostError`
+   * isn't a global, so `instanceof` isn't available.
+   *
+   * @param options `timeout`: how long to wait for a server, in ms.
+   * @throws {HostError} `cancelled` when an interrupt ends the wait.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * if (host) {
+   *   const { hits } = await host.notebooks.search({ query: "weekday drop", dir: "journal" });
+   *   hits.map((h) => `${h.path}: ${h.excerpt}`);
+   * }
+   * ```
+   * @see jupyter-api.md#other-notebooks-jupyter-host
+   */
+  host(options?: HostOptions): Promise<Host | null>;
 }
 
 export interface Jupyter {

package/runtime/display.mjs

@@ -15,6 +15,7 @@
 // Deno doesn't have; see comm.mjs and widget.mjs.
 
 import { createComms } from "./comm.mjs";
+import { createHost } from "./host.mjs";
 import { createWidgetFactory } from "./widget.mjs";
 
 export const $display = Symbol.for("Jupyter.display");
@@ -343,8 +344,20 @@ function isMediaBundle(obj) {
  *   readFile: (path: string) => Uint8Array,
  *   send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void,
  *   input: (prompt: string, password: boolean) => string | null,
+ *   params?: () => string | undefined,
  * }} host
  */
+/** The MIME type of a named result (cdp-kernel#456): `{ name, value }`. */
+export const RESULT_MIME = "application/vnd.ganymede.result+json";
+
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value)) deepFreeze(v);
+    Object.freeze(value);
+  }
+  return value;
+}
+
 export function createJupyter(host) {
   async function format(obj) {
     return await formatNow(obj);
@@ -439,6 +452,46 @@ export function createJupyter(host) {
     return answer === "" ? defaultValue : answer;
   }
 
+  // jupyter.params (cdp-kernel#456): the run's parameters, which the host
+  // (ganymede execute -p) passes as JSON in GANYMEDE_PARAMS. Parsed on first
+  // read, so a bad value fails the cell that reads it, not the kernel.
+  let params;
+  function readParams() {
+    if (params !== undefined) return params;
+    const text = host.params?.();
+    if (text === undefined || text === "") return (params = Object.freeze({}));
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch (err) {
+      throw new TypeError(`GANYMEDE_PARAMS is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new TypeError("GANYMEDE_PARAMS must be a JSON object, such as {\"counter\": \"Fremont\"}");
+    }
+    return (params = deepFreeze(value));
+  }
+
+  // jupyter.result (cdp-kernel#456): a named value as an output of
+  // Ganymede's result type, which a run's caller reads without parsing
+  // outputs. JSON only, so every reader sees the same value.
+  function result(name, value) {
+    if (typeof name !== "string" || name === "") throw new TypeError("jupyter.result: name must be a non-empty string");
+    let text;
+    try {
+      text = JSON.stringify(value);
+    } catch (err) {
+      throw new TypeError(`jupyter.result: ${name} is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (text === undefined) throw new TypeError(`jupyter.result: ${name} is not JSON (${typeof value})`);
+    const json = JSON.parse(text);
+    broadcast("display_data", {
+      data: { [RESULT_MIME]: { name, value: json }, "text/plain": `${name} = ${text}` },
+      metadata: {},
+      transient: {},
+    });
+  }
+
   const comms = createComms((msgType, content, metadata, buffers) => host.send(msgType, content, metadata, buffers));
 
   // jupyter.signal (#418): aborted when the kernel is interrupted, so cell
@@ -462,6 +515,11 @@ export function createJupyter(host) {
     for (const controller of handlers.keys()) controller.abort(reason);
     handlers.clear();
   }
+  // jupyter.host() (#461): Ganymede's host API. Registers its comm target
+  // now, so the comm the server opens at kernel start finds it. A call
+  // without a signal watches the jupyter.signal of whatever started it.
+  const hostApi = createHost(comms.api, () => current.signal);
+
   async function commDispatch(msgType, content, metadata, buffers, ownSignal = false) {
     // A handler during a cell shares the cell's signal, and is tracked
     // apart from it: it can outlive the cell.
@@ -484,6 +542,10 @@ export function createJupyter(host) {
       },
       broadcast,
       display,
+      get params() {
+        return readParams();
+      },
+      result,
       format,
       md: taggedTemplate("text/markdown"),
       html: taggedTemplate("text/html"),
@@ -491,6 +553,7 @@ export function createJupyter(host) {
       image,
       $display,
       comm: comms.api,
+      host: hostApi.host,
       widget: createWidgetFactory(comms.api, $display),
     },
     broadcastResult,

package/runtime/host.d.mts

@@ -0,0 +1,246 @@
+import type { CommApi } from "./comm.d.mts";
+
+/** The target name of the comm a Ganymede server opens to the kernel. */
+export const HOST_TARGET: "ganymede.host.v1";
+
+/** Why a host call failed. The codes are ganymede-device's. */
+export type HostErrorCode = "unavailable" | "denied" | "cancelled" | "timeout" | "failed" | "disconnected";
+
+/**
+ * A failed host call. Branch on `code` (or `name === "HostError"`): the
+ * class isn't a global, so `instanceof` isn't available in a cell.
+ *
+ * A failed host call: `unavailable` (no such method), `denied` (not
+ * granted to this notebook), `cancelled` (its signal aborted), `timeout`,
+ * `failed` (the server couldn't do it), `disconnected` (the host comm
+ * closed, such as on a server restart).
+ */
+export class HostError extends Error {
+  readonly code: HostErrorCode;
+  constructor(code: HostErrorCode, message: string);
+  static from(err: unknown): HostError;
+}
+
+/** Options for a host call. */
+export interface HostCallOptions {
+  /** Aborting it cancels the call. Default `jupyter.signal`. */
+  signal?: AbortSignal;
+}
+
+/** Parameters and results are JSON; the host API's design note lists each method's. */
+export type HostParams = { [key: string]: unknown };
+
+/** An entry `notebooks.list` returns: a folder, or a notebook this notebook may read. */
+export interface NotebookEntry {
+  path: string;
+  type: "directory" | "notebook";
+  /** Its first heading, for a notebook that has one. */
+  title?: string | null;
+  /** Its kernelspec name. */
+  kernel?: string | null;
+  /** ISO 8601. */
+  modified: string;
+}
+
+/** A cell `notebooks.search` matched. */
+export interface NotebookHit {
+  path: string;
+  title: string | null;
+  /** The cell's position in the notebook. */
+  index: number;
+  id: string | null;
+  cell_type: "code" | "markdown" | "raw";
+  /** Where the first word matched. */
+  in: "source" | "output";
+  excerpt: string;
+}
+
+/** What `notebooks.search` returns. */
+export interface NotebookSearch {
+  hits: NotebookHit[];
+  /** Matching cells, beyond `limit` too. */
+  total: number;
+  truncated: boolean;
+}
+
+/** The Ganymede server that runs this kernel, from `jupyter.host()`. */
+export interface Host {
+  /** The host API's protocol version. */
+  readonly protocol: number;
+  /** The server's version. */
+  readonly server: string;
+  /** This notebook's path under the server's root, or null when the kernel has none. */
+  readonly notebook: string | null;
+  /** The methods this notebook may call. */
+  readonly methods: readonly string[];
+  /**
+   * Whether this notebook may call `method`.
+   *
+   * @param method The method, such as `"notebooks.run"`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * host?.has("notebooks.run"); // false unless the notebook is granted runs
+   * ```
+   */
+  has(method: string): boolean;
+  /**
+   * Call a method by name. The shortcuts under `notebooks` and `self` call
+   * this.
+   *
+   * @param method The method, such as `"notebooks.read"`.
+   * @param params Its parameters, a JSON object. Default `{}`.
+   * @param options `signal` cancels the call.
+   * @returns What the server answered, as JSON.
+   * @throws {HostError} The call failed; `code` says why.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook } = await host!.call("notebooks.read", { path: "journal/a.ipynb" });
+   * notebook.cells.length;
+   * ```
+   */
+  call(method: string, params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /** Other notebooks under the server's root, as far as this notebook's grant reaches. */
+  readonly notebooks: HostNotebooks;
+  /** This notebook's own cells. Not on a server yet: they reject `unavailable`. */
+  readonly self: HostSelf;
+}
+
+/** `host.notebooks`: other notebooks under the server's root. */
+export interface HostNotebooks {
+  /**
+   * The notebooks this notebook may read, and the folders, in a folder.
+   *
+   * @param params `dir`: the folder, relative to the root. Default the root.
+   * @param options `signal` cancels the call.
+   * @returns One entry per notebook or folder.
+   * @throws {HostError} `denied` when the grant doesn't reach `dir`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const entries = await host!.notebooks.list({ dir: "journal" });
+   * entries.filter((e) => e.type === "notebook").map((e) => e.title ?? e.path);
+   * ```
+   */
+  list(params?: { dir?: string }, options?: HostCallOptions): Promise<NotebookEntry[]>;
+  /**
+   * A notebook as nbformat JSON (from its open document when someone has
+   * it open), and each cell's source hash by cell id.
+   *
+   * @param params `path`: the notebook, relative to the root.
+   * @param options `signal` cancels the call.
+   * @returns The notebook and its hashes.
+   * @throws {HostError} `denied` when the grant doesn't reach `path`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook } = await host!.notebooks.read({ path: "journal/a.ipynb" });
+   * notebook.cells.length;
+   * ```
+   */
+  read(params: { path: string }, options?: HostCallOptions): Promise<{ notebook: any; hashes: { [cellId: string]: string } }>;
+  /**
+   * Cells that hold every word of `query`, in the notebooks this notebook
+   * may read: in sources, and in outputs too with `outputs: true`.
+   *
+   * @param params `query`, and optionally `dir`, `outputs`, `cell_type`
+   *   (`code`, `markdown` or `raw`) and `limit` (default 20, at most 200).
+   * @param options `signal` cancels the call.
+   * @returns The matches, how many there are in all, and whether `limit` cut them.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { hits } = await host!.notebooks.search({ query: "weekday drop", dir: "journal" });
+   * hits.map((h) => `${h.path}: ${h.excerpt}`);
+   * ```
+   */
+  search(
+    params: { query: string; dir?: string; outputs?: boolean; cell_type?: "code" | "markdown" | "raw"; limit?: number },
+    options?: HostCallOptions,
+  ): Promise<NotebookSearch>;
+  /**
+   * A notebook's named results. Not on a server yet: rejects `unavailable`.
+   *
+   * @param params `path`: the notebook.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const results = await host!.notebooks.results({ path: "journal/fremont.ipynb" });
+   * ```
+   */
+  results(params: { path: string }, options?: HostCallOptions): Promise<any>;
+  /**
+   * Run a notebook with parameters and return its results. Not on a
+   * server yet: rejects `unavailable`.
+   *
+   * @param params `path`: the notebook; `params`: its parameters.
+   * @param options `signal` cancels the run.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const run = await host!.notebooks.run({ path: "journal/fremont.ipynb", params: { counter: "2nd Ave" } });
+   * ```
+   */
+  run(params: { path: string; params?: HostParams }, options?: HostCallOptions): Promise<any>;
+}
+
+/** `host.self`: this notebook's own cells. Not on a server yet: each rejects `unavailable`. */
+export interface HostSelf {
+  /**
+   * Add a cell to this notebook.
+   *
+   * @param params The cell, as the host API's design note describes.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * await host!.self.add({ cell_type: "markdown", source: "## Index" });
+   * ```
+   */
+  add(params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /**
+   * Change a cell's source, given the hash of the source it replaces.
+   *
+   * @param params The cell id, its new source and the old source's hash.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook, hashes } = await host!.notebooks.read({ path: host!.notebook! });
+   * const id = notebook.cells[0].id;
+   * await host!.self.edit({ id, source: "# New title", source_hash: hashes[id] });
+   * ```
+   */
+  edit(params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /**
+   * Delete a cell, given its source's hash.
+   *
+   * @param params The cell id and its source's hash.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook, hashes } = await host!.notebooks.read({ path: host!.notebook! });
+   * const id = notebook.cells.at(-1).id;
+   * await host!.self.delete({ id, source_hash: hashes[id] });
+   * ```
+   */
+  delete(params?: HostParams, options?: HostCallOptions): Promise<any>;
+}
+
+/** Options for `jupyter.host()`. */
+export interface HostOptions {
+  /**
+   * How long to wait for a server that hasn't opened the comm, in ms.
+   * Default 1000. Once a wait goes unanswered, later calls answer `null`
+   * at once.
+   */
+  timeout?: number;
+}
+
+export function createHost(
+  comms: CommApi,
+  defaultSignal?: () => AbortSignal | undefined,
+): { host(options?: HostOptions): Promise<Host | null> };