@runtimed/node 0.1.1 → 0.2.2

package/README.md

@@ -24,12 +24,24 @@ async function main() {
   const session = await createNotebook({
     runtime: "python",
     workingDir: process.cwd(),
+    // Record these before the first cell runs.
+    dependencies: ["numpy", "matplotlib"],
+    description: "plotting smoke test",
   });
 
   try {
     console.log("daemon socket:", defaultSocketPath());
 
-    const result = await session.runCell("sum(range(10))");
+    await session.syncEnvironment();
+
+    const result = await session.runCell(`
+import numpy as np
+import matplotlib.pyplot as plt
+
+x = np.linspace(0, 6.28, 200)
+plt.plot(x, np.sin(x))
+plt.show()
+`);
     console.log(result.status);
     console.log(result.outputs);
 
@@ -45,19 +57,62 @@ main().catch((error) => {
 });
 ```
 
+## Notebook Dependencies
+
+`createNotebook()` accepts `dependencies` so agent code can declare packages
+up-front instead of failing the first import and retrying after `addDependencies()`.
+When `packageManager` is omitted, the daemon/user environment choice remains in
+charge. Later dependency edits also infer the manager from the running kernel,
+inline notebook metadata (`uv`, then `conda`, then `pixi`), or detected project
+file, falling back to UV for fresh Python notebooks with no other signal. Pass
+the native binding's `PackageManager` string enum (`"uv"`, `"conda"`, or
+`"pixi"`) only when you need to target a specific metadata section.
+`description` can be used as a human-readable peer label for agent-created
+sessions.
+
 ## API Surface
 
 - `defaultSocketPath()` returns the socket path for the current nteract channel
   or the `RUNTIMED_SOCKET_PATH` override.
 - `socketPathForChannel("stable" | "nightly")` returns a channel-specific
   daemon socket path.
-- `createNotebook(options)` creates a notebook and starts a runtime.
-- `openNotebook(notebookId, options)` connects to an existing notebook.
+- `listActiveNotebooks(options)` lists active daemon notebook rooms.
+- `createNotebook(options)` creates a notebook and records optional first-call dependencies.
+- `openNotebook(notebookId, options)` connects to an existing daemon notebook.
+- `openNotebookPath(path, options)` opens a notebook file through the daemon.
+- `showNotebook(options)` opens an active notebook or path in nteract Desktop,
+  returning a structured `opened: false` response in headless environments.
+- `shutdownNotebook(notebookId, options)` shuts down a notebook room by ID.
 - `getExecutionResult(executionId, options)` reads a result by execution ID.
+- `Session.listCells()` and `Session.getCell(cellId)` inspect notebook cells.
+- `Session.createCell(source, options)`, `Session.setCell(cellId, options)`,
+  `Session.deleteCell(cellId)`, and `Session.moveCell(cellId, options)` provide
+  direct notebook editing without MCP JSON round-trips.
+- `Session.executeCell(cellId, options)` runs an existing code cell.
+- `Session.showNotebook()` opens the session in nteract Desktop when a display
+  is available.
+- `Session.interruptKernel()`, `Session.shutdownKernel()`, and
+  `Session.restartKernel()` manage the running kernel.
+- `Session.shutdownNotebook()` shuts down this notebook room and closes the session.
 - `Session.runCell(source, options)` creates, runs, and waits for a cell.
 - `Session.queueCell(source, options)` queues a cell and returns IDs.
 - `Session.waitForExecution(executionId, options)` waits for queued work.
-- `Session.addUvDependency(spec)` records a UV dependency for the notebook.
+  Pass `onUpdate(progress)` to receive resolved output snapshots while the
+  execution is still running.
+- `Session.runtimeState$`, `Session.executionTransitions$`,
+  `Session.cellChanges$`, `Session.broadcasts$`, and `Session.sessionStatus$`
+  expose the same projected event families used by the browser sync engine.
+- `Session.addDependency(spec, { packageManager })` /
+  `Session.addDependencies(specs, { packageManager })` and
+  `Session.removeDependency(spec, { packageManager })` /
+  `Session.removeDependencies(specs, { packageManager })` edit notebook
+  dependency metadata for UV, Conda, or Pixi. Omit `packageManager` to follow
+  the notebook's running/configured manager. Batch variants use one CRDT
+  metadata transaction.
+- `Session.getDependencyStatus()` returns dependency metadata, fingerprint, and
+  trust state in one call.
+- `Session.getRuntimeStatus()` returns kernel lifecycle, activity, env source,
+  and startup error details.
 - `Session.syncEnvironment()` installs recorded notebook dependencies.
 - `Session.saveNotebook(path?)` saves the notebook.
 - `Session.close()` releases the daemon connection.
@@ -74,6 +129,22 @@ cargo xtask dev-daemon
 Published nteract desktop builds manage their own daemon. Set
 `RUNTIMED_SOCKET_PATH` when you need to connect to a specific daemon instance.
 
+## Development Smoke Test
+
+After building the native binding, run the daemon-backed API smoke test with:
+
+```bash
+RUNTIMED_SOCKET_PATH=/path/to/runtimed.sock pnpm --dir packages/runtimed-node smoke:api
+```
+
+When testing an out-of-tree N-API build, point the smoke script at it:
+
+```bash
+RUNTIMED_NODE_SMOKE_MODULE=/tmp/runtimed-node-napi-check/index.cjs \
+RUNTIMED_SOCKET_PATH=/path/to/runtimed.sock \
+pnpm --dir packages/runtimed-node smoke:api
+```
+
 ## Platform Packages
 
 The platform packages are implementation details and should normally be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtimed/node",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "description": "Node.js bindings for controlling nteract runtimed notebooks and Python kernels.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -35,6 +35,8 @@
     "README.md",
     "src/index.cjs",
     "src/index.d.ts",
+    "src/session.cjs",
+    "src/napi-observables.cjs",
     "src/binding.cjs",
     "src/binding.d.ts"
   ],
@@ -46,10 +48,14 @@
       "x86_64-pc-windows-msvc"
     ]
   },
+  "dependencies": {
+    "rxjs": "^7.8.2",
+    "runtimed": "0.2.4"
+  },
   "optionalDependencies": {
-    "@runtimed/node-darwin-arm64": "0.1.1",
-    "@runtimed/node-linux-x64-gnu": "0.1.1",
-    "@runtimed/node-win32-x64-msvc": "0.1.1"
+    "@runtimed/node-darwin-arm64": "0.2.2",
+    "@runtimed/node-linux-x64-gnu": "0.2.2",
+    "@runtimed/node-win32-x64-msvc": "0.2.2"
   },
   "publishConfig": {
     "access": "public"
@@ -63,6 +69,7 @@
     "build:debug": "napi build --platform --js binding.cjs --dts binding.d.ts --manifest-path ../../crates/runtimed-node/Cargo.toml --output-dir src",
     "pack:platform:dry-run": "node scripts/assemble-platform-package.mjs --pack-dry-run",
     "pack:dry-run": "pnpm pack --dry-run",
-    "smoke": "node -e \"const m = require('./src/index.cjs'); console.log('defaultSocketPath:', m.defaultSocketPath());\""
+    "smoke": "node -e \"const m = require('./src/index.cjs'); console.log('defaultSocketPath:', m.defaultSocketPath());\"",
+    "smoke:api": "node scripts/smoke-api.cjs"
   }
 }

package/src/binding.cjs

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-android-arm64')
         const bindingPackageVersion = require('@runtimed/node-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-android-arm-eabi')
         const bindingPackageVersion = require('@runtimed/node-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-win32-x64-gnu')
         const bindingPackageVersion = require('@runtimed/node-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-win32-x64-msvc')
         const bindingPackageVersion = require('@runtimed/node-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-win32-ia32-msvc')
         const bindingPackageVersion = require('@runtimed/node-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-win32-arm64-msvc')
         const bindingPackageVersion = require('@runtimed/node-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('@runtimed/node-darwin-universal')
       const bindingPackageVersion = require('@runtimed/node-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-darwin-x64')
         const bindingPackageVersion = require('@runtimed/node-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-darwin-arm64')
         const bindingPackageVersion = require('@runtimed/node-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-freebsd-x64')
         const bindingPackageVersion = require('@runtimed/node-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-freebsd-arm64')
         const bindingPackageVersion = require('@runtimed/node-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-x64-musl')
           const bindingPackageVersion = require('@runtimed/node-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-x64-gnu')
           const bindingPackageVersion = require('@runtimed/node-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-arm64-musl')
           const bindingPackageVersion = require('@runtimed/node-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-arm64-gnu')
           const bindingPackageVersion = require('@runtimed/node-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-arm-musleabihf')
           const bindingPackageVersion = require('@runtimed/node-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@runtimed/node-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-loong64-musl')
           const bindingPackageVersion = require('@runtimed/node-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-loong64-gnu')
           const bindingPackageVersion = require('@runtimed/node-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-riscv64-musl')
           const bindingPackageVersion = require('@runtimed/node-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('@runtimed/node-linux-riscv64-gnu')
           const bindingPackageVersion = require('@runtimed/node-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-linux-ppc64-gnu')
         const bindingPackageVersion = require('@runtimed/node-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-linux-s390x-gnu')
         const bindingPackageVersion = require('@runtimed/node-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-openharmony-arm64')
         const bindingPackageVersion = require('@runtimed/node-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-openharmony-x64')
         const bindingPackageVersion = require('@runtimed/node-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('@runtimed/node-openharmony-arm')
         const bindingPackageVersion = require('@runtimed/node-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -576,11 +576,17 @@ if (!nativeBinding) {
 }
 
 module.exports = nativeBinding
+module.exports.EventSubscription = nativeBinding.EventSubscription
 module.exports.Session = nativeBinding.Session
 module.exports.createNotebook = nativeBinding.createNotebook
 module.exports.defaultSocketPath = nativeBinding.defaultSocketPath
 module.exports.getExecutionResult = nativeBinding.getExecutionResult
+module.exports.listActiveNotebooks = nativeBinding.listActiveNotebooks
 module.exports.openNotebook = nativeBinding.openNotebook
+module.exports.openNotebookPath = nativeBinding.openNotebookPath
+module.exports.PackageManager = nativeBinding.PackageManager
 module.exports.readParquetFile = nativeBinding.readParquetFile
+module.exports.showNotebook = nativeBinding.showNotebook
+module.exports.shutdownNotebook = nativeBinding.shutdownNotebook
 module.exports.socketPathForChannel = nativeBinding.socketPathForChannel
 module.exports.summarizeParquetFile = nativeBinding.summarizeParquetFile

package/src/binding.d.ts

@@ -1,9 +1,39 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/** A live event subscription returned by `Session.on*` methods. */
+export declare class EventSubscription {
+  /** Stop delivering events to the callback. */
+  dispose(): void
+}
+
 /** A connected notebook session. */
 export declare class Session {
   /** The notebook ID (always a UUID). */
   get notebookId(): string
+  /** Subscribe to RuntimeStateDoc snapshots. Callback receives a JSON string. */
+  onRuntimeState(callback: (arg0: string) => void): EventSubscription
+  /** Subscribe to execution lifecycle transitions. Callback receives a JSON string. */
+  onExecutionTransition(callback: (arg0: string) => void): EventSubscription
+  /**
+   * Subscribe to resolved progress snapshots for one execution.
+   *
+   * Callback receives the same JSON shape as `CellResult`, emitted whenever
+   * the RuntimeStateDoc entry for the execution changes. The subscription
+   * ends after an authoritative terminal snapshot, including kernel
+   * failure/close.
+   */
+  onExecutionProgress(executionId: string, cellId: string | undefined | null, callback: (arg0: string) => void): EventSubscription
+  /**
+   * Subscribe to notebook document changes. Callback receives a JSON string.
+   *
+   * The native handle currently reports `null` as a full-materialization
+   * marker, matching the browser SyncEngine's no-changeset fallback.
+   */
+  onCellChange(callback: (arg0: string) => void): EventSubscription
+  /** Subscribe to comm broadcasts. Callback receives a JSON string. */
+  onBroadcast(callback: (arg0: string) => void): EventSubscription
+  /** Subscribe to handshake/readiness status updates. Callback receives a JSON string. */
+  onSessionStatus(callback: (arg0: string) => void): EventSubscription
   /**
    * Save the notebook to disk. If a path is given, saves to that path
    * (creating the file if needed). Otherwise saves to the original location.
@@ -11,11 +41,39 @@ export declare class Session {
   saveNotebook(path?: string | undefined | null): Promise<void>
   /** Close the session and release the underlying connection. */
   close(): Promise<void>
+  /**
+   * Add dependencies to the selected package manager in one CRDT transaction.
+   * When no manager is provided, the running/configured notebook manager is used.
+   * Call `syncEnvironment()` or restart the kernel to install them.
+   */
+  addDependencies(packages: Array<string>, options?: DependencyEditOptions | undefined | null): Promise<void>
+  /**
+   * Add a dependency to the selected package manager.
+   * When no manager is provided, the running/configured notebook manager is used.
+   * Call `syncEnvironment()` or restart the kernel to install it.
+   */
+  addDependency(pkg: string, options?: DependencyEditOptions | undefined | null): Promise<void>
+  /**
+   * Remove dependencies from the selected package manager in one CRDT transaction.
+   * When no manager is provided, the running/configured notebook manager is used.
+   * Returns the number of dependencies removed.
+   */
+  removeDependencies(packages: Array<string>, options?: DependencyEditOptions | undefined | null): Promise<number>
+  /**
+   * Remove a dependency from the selected package manager.
+   * When no manager is provided, the running/configured notebook manager is used.
+   * Returns true if a dependency was removed.
+   */
+  removeDependency(pkg: string, options?: DependencyEditOptions | undefined | null): Promise<boolean>
   /**
    * Add a UV dependency to the notebook (e.g. `"matplotlib>=3.8"`).
    * Call `syncEnvironment()` or restart the kernel to install it.
    */
   addUvDependency(pkg: string): Promise<void>
+  /** Get runtime/kernel state, including lifecycle error details. */
+  getRuntimeStatus(): Promise<RuntimeStatus>
+  /** Get dependency metadata, fingerprint, and current trust state. */
+  getDependencyStatus(): Promise<DependencyStatus>
   /** Get the current dependency fingerprint for diagnostics. */
   dependencyFingerprint(): Promise<string | null>
   /** Approve and sign the current dependency metadata. */
@@ -26,6 +84,23 @@ export declare class Session {
    * Returns once the install finishes.
    */
   syncEnvironment(): Promise<void>
+  /** Return all cells in notebook order. */
+  listCells(): Promise<Array<JsCellSnapshot>>
+  /** Return one cell by ID, or null if it does not exist. */
+  getCell(cellId: string): Promise<JsCellSnapshot | null>
+  /** Create a cell without executing it. Returns the new cell ID. */
+  createCell(source: string, options?: CreateCellOptions | undefined | null): Promise<string>
+  /** Replace a cell's source and/or type. Returns true if the cell existed. */
+  setCell(cellId: string, options: SetCellOptions): Promise<boolean>
+  /** Delete a cell. Returns true if the cell existed. */
+  deleteCell(cellId: string): Promise<boolean>
+  /**
+   * Move a cell after another cell, or to the beginning when omitted/null.
+   * Returns the new position string.
+   */
+  moveCell(cellId: string, options?: MoveCellOptions | undefined | null): Promise<string>
+  /** Execute an existing code cell and wait for terminal outputs. */
+  executeCell(cellId: string, options?: ExecuteCellOptions | undefined | null): Promise<CellResult>
   /**
    * Execute a source string as a new cell. Starts the kernel on demand.
    * Returns the cell's outputs once execution is terminal.
@@ -33,10 +108,36 @@ export declare class Session {
   runCell(source: string, options?: RunCellOptions | undefined | null): Promise<CellResult>
   /** Queue a source string as a new cell without waiting for execution. */
   queueCell(source: string, options?: QueueCellOptions | undefined | null): Promise<QueuedExecution>
+  /** Interrupt the currently executing cell. */
+  interruptKernel(): Promise<boolean>
+  /** Shutdown the running kernel. Returns false when no kernel is running. */
+  shutdownKernel(): Promise<boolean>
+  /** Restart the kernel, clearing in-memory state while preserving notebook dependencies. */
+  restartKernel(): Promise<boolean>
+  /** Shutdown this notebook's kernel and evict its daemon room. */
+  shutdownNotebook(): Promise<boolean>
+  /**
+   * Open this notebook in nteract Desktop. In headless environments, returns
+   * `opened: false` with a reason instead of failing.
+   */
+  showNotebook(): Promise<ShowNotebookResult>
   /** Wait for an already-queued execution in this live session. */
   waitForExecution(executionId: string, options?: WaitExecutionOptions | undefined | null): Promise<CellResult>
 }
 
+/** An active notebook room reported by the daemon. */
+export interface ActiveNotebook {
+  notebookId: string
+  activePeers: number
+  hadPeers: boolean
+  hasKernel: boolean
+  kernelType?: string
+  envSource?: string
+  kernelStatus?: string
+  ephemeral: boolean
+  notebookPath?: string
+}
+
 /** Result of running a cell. */
 export interface CellResult {
   cellId: string
@@ -48,6 +149,21 @@ export interface CellResult {
   outputs: Array<JsOutput>
 }
 
+/** Conda dependency metadata. */
+export interface CondaDependencyStatus {
+  dependencies: Array<string>
+  channels: Array<string>
+  python?: string
+}
+
+/** Options for `Session.createCell()`. */
+export interface CreateCellOptions {
+  /** Cell source type: `"code"` (default), `"markdown"`, or `"raw"`. */
+  cellType?: string
+  /** Insert after this cell, or omit to insert at the beginning. */
+  afterCellId?: string
+}
+
 /** Create a new (ephemeral) notebook against the daemon. */
 export declare function createNotebook(options?: CreateNotebookOptions | undefined | null): Promise<Session>
 
@@ -61,6 +177,16 @@ export interface CreateNotebookOptions {
   socketPath?: string
   /** Actor label for presence / Automerge provenance. */
   peerLabel?: string
+  /** Human-readable session description. Used as the peer label when `peerLabel` is omitted. */
+  description?: string
+  /**
+   * Packages to record before the kernel starts (for example `["numpy", "matplotlib"]`).
+   * Python notebooks use the selected package manager; Deno notebooks treat these as
+   * runtime-native import dependencies.
+   */
+  dependencies?: Array<string>
+  /** Package manager for Python dependencies. Defaults to the daemon/user setting. */
+  packageManager?: PackageManager
 }
 
 /**
@@ -71,6 +197,40 @@ export interface CreateNotebookOptions {
  */
 export declare function defaultSocketPath(): string
 
+/** Options for dependency edit methods. */
+export interface DependencyEditOptions {
+  /**
+   * Dependency manager to edit. Defaults to the running/configured manager,
+   * falling back to UV for fresh Python notebooks.
+   */
+  packageManager?: PackageManager
+}
+
+/** Notebook dependency metadata and trust/runtime status. */
+export interface DependencyStatus {
+  uv?: UvDependencyStatus
+  conda?: CondaDependencyStatus
+  pixi?: PixiDependencyStatus
+  fingerprint?: string
+  trust: DependencyTrustStatus
+}
+
+/** Notebook trust state for dependency metadata. */
+export interface DependencyTrustStatus {
+  status?: string
+  needsApproval?: boolean
+  approvedUvDependencies: Array<string>
+  approvedCondaDependencies: Array<string>
+  approvedPixiDependencies: Array<string>
+  approvedPixiPypiDependencies: Array<string>
+}
+
+/** Options for `Session.executeCell()`. */
+export interface ExecuteCellOptions {
+  /** Max milliseconds to wait for execution. Default 120_000 (2 min). */
+  timeoutMs?: number
+}
+
 /** Read a terminal execution result from the daemon's durable execution store. */
 export declare function getExecutionResult(executionId: string, options?: GetExecutionResultOptions | undefined | null): Promise<CellResult>
 
@@ -80,6 +240,18 @@ export interface GetExecutionResultOptions {
   socketPath?: string
 }
 
+/** A notebook cell snapshot. */
+export interface JsCellSnapshot {
+  id: string
+  cellType: string
+  position: string
+  source: string
+  /** JSON-encoded metadata object. */
+  metadataJson: string
+  /** Legacy execution count as stored in the notebook doc. */
+  executionCount?: string
+}
+
 /** One output from a cell. `data` values are: `{ type: "text"|"binary"|"json", value: ... }`. */
 export interface JsOutput {
   outputType: string
@@ -95,13 +267,47 @@ export interface JsOutput {
   blobPathsJson?: string
 }
 
+/** List active notebook rooms from the daemon. */
+export declare function listActiveNotebooks(options?: ListActiveNotebooksOptions | undefined | null): Promise<Array<ActiveNotebook>>
+
+/** Options for top-level `listActiveNotebooks()`. */
+export interface ListActiveNotebooksOptions {
+  /** Override daemon socket path (otherwise uses `defaultSocketPath()`). */
+  socketPath?: string
+}
+
+/** Options for `Session.moveCell()`. */
+export interface MoveCellOptions {
+  /** Move after this cell, or omit/null to move to the beginning. */
+  afterCellId?: string
+}
+
 /** Open an existing notebook by ID. */
 export declare function openNotebook(notebookId: string, options?: OpenNotebookOptions | undefined | null): Promise<Session>
 
-/** Options for `openNotebook()`. */
+/** Options for `openNotebook()` and `openNotebookPath()`. */
 export interface OpenNotebookOptions {
   socketPath?: string
   peerLabel?: string
+  /** Human-readable session description. Used as the peer label when `peerLabel` is omitted. */
+  description?: string
+}
+
+/** Open an existing notebook file by path. */
+export declare function openNotebookPath(path: string, options?: OpenNotebookOptions | undefined | null): Promise<Session>
+
+/**
+ * Package manager for Python notebook dependencies.
+ *
+ * This mirrors `notebook_protocol::connection::PackageManager` at the N-API
+ * boundary. We cannot attach `#[napi]` to the protocol crate's external enum,
+ * and that enum intentionally includes an `Unknown(String)` wire-compatibility
+ * variant that should not be exposed as a typed JavaScript option.
+ */
+export declare const enum PackageManager {
+  Uv = 'uv',
+  Conda = 'conda',
+  Pixi = 'pixi'
 }
 
 export interface ParquetColumnInfo {
@@ -128,6 +334,14 @@ export interface ParquetSummaryResult {
   columns: Array<ParquetColumnInfo>
 }
 
+/** Pixi dependency metadata. */
+export interface PixiDependencyStatus {
+  dependencies: Array<string>
+  pypiDependencies: Array<string>
+  channels: Array<string>
+  python?: string
+}
+
 /** Options for `Session.queueCell()`. */
 export interface QueueCellOptions {
   /** Cell source type: `"code"` (default), `"markdown"`, or `"raw"`. */
@@ -154,6 +368,62 @@ export interface RunCellOptions {
   cellType?: string
 }
 
+/** Runtime/kernel status from RuntimeStateDoc. */
+export interface RuntimeStatus {
+  status: string
+  lifecycle: string
+  activity?: string
+  startingPhase: string
+  name: string
+  language: string
+  envSource: string
+  runtimeAgentId: string
+  errorReason?: string
+  errorDetails?: string
+}
+
+/** Options for `Session.setCell()`. */
+export interface SetCellOptions {
+  /** New source text. Omit to leave unchanged. */
+  source?: string
+  /** New cell source type. Omit to leave unchanged. */
+  cellType?: string
+}
+
+/**
+ * Open a notebook in nteract Desktop by active notebook ID or file path.
+ * In headless environments, returns `opened: false` with a reason instead of failing.
+ */
+export declare function showNotebook(options?: ShowNotebookOptions | undefined | null): Promise<ShowNotebookResult>
+
+/** Options for top-level `showNotebook()`. */
+export interface ShowNotebookOptions {
+  /** Override daemon socket path (otherwise uses `defaultSocketPath()`). */
+  socketPath?: string
+  /** Active notebook UUID to open in the app. */
+  notebookId?: string
+  /** File path to open in the app. If both path and notebookId are provided, path wins. */
+  path?: string
+}
+
+/** Result of asking nteract Desktop to show a notebook. */
+export interface ShowNotebookResult {
+  notebookId?: string
+  path?: string
+  opened: boolean
+  reason?: string
+  warning?: string
+}
+
+/** Shutdown a notebook's kernel and evict its daemon room by notebook ID. */
+export declare function shutdownNotebook(notebookId: string, options?: ShutdownNotebookOptions | undefined | null): Promise<boolean>
+
+/** Options for top-level `shutdownNotebook()`. */
+export interface ShutdownNotebookOptions {
+  /** Override daemon socket path (otherwise uses `defaultSocketPath()`). */
+  socketPath?: string
+}
+
 /**
  * Return the daemon socket path for a specific channel ("stable" or
  * "nightly"). Ignores `RUNTIMED_SOCKET_PATH`.
@@ -163,6 +433,12 @@ export declare function socketPathForChannel(channel: string): string
 /** Summarize a parquet file from a local blob/file path. */
 export declare function summarizeParquetFile(filePath: string): ParquetSummaryResult
 
+/** UV dependency metadata. */
+export interface UvDependencyStatus {
+  dependencies: Array<string>
+  requiresPython?: string
+}
+
 /** Options for `Session.waitForExecution()`. */
 export interface WaitExecutionOptions {
   /** Cell ID to use when reporting kernel failures before terminal state syncs. */

package/src/index.cjs

@@ -8,5 +8,20 @@
 "use strict";
 
 const binding = require("./binding.cjs");
+const { Session } = require("./session.cjs");
 
-module.exports = binding;
+async function createNotebook(options) {
+  return new Session(await binding.createNotebook(options));
+}
+
+async function openNotebook(notebookId, options) {
+  return new Session(await binding.openNotebook(notebookId, options));
+}
+
+module.exports = {
+  ...binding,
+  createNotebook,
+  openNotebook,
+  NativeSession: binding.Session,
+  Session,
+};

package/src/index.d.ts

@@ -1,7 +1,203 @@
-/**
- * @runtimed/node — Node.js bindings for the runtimed daemon.
- *
- * This file re-exports the types generated by napi-rs into binding.d.ts.
- */
+import type { Observable } from "rxjs";
+import type { ExecutionTransition, RuntimeState, SessionStatus } from "runtimed";
 
-export * from "./binding.cjs";
+export type RuntimeKind = "python" | "deno" | (string & {});
+export type PackageManager = "uv" | "conda" | "pixi";
+
+export const PackageManager: {
+  readonly Uv: "uv";
+  readonly Conda: "conda";
+  readonly Pixi: "pixi";
+};
+
+export interface CreateNotebookOptions {
+  runtime?: RuntimeKind;
+  workingDir?: string;
+  socketPath?: string;
+  peerLabel?: string;
+  description?: string;
+  dependencies?: string[];
+  packageManager?: PackageManager;
+}
+
+export interface OpenNotebookOptions {
+  socketPath?: string;
+  peerLabel?: string;
+  description?: string;
+}
+
+export interface RunCellOptions {
+  timeoutMs?: number;
+  cellType?: "code" | "markdown" | "raw";
+  onUpdate?: (progress: CellResult) => void;
+}
+
+export interface QueueCellOptions {
+  cellType?: "code" | "markdown" | "raw";
+}
+
+export interface DependencyEditOptions {
+  packageManager?: PackageManager;
+}
+
+export interface WaitExecutionOptions {
+  cellId?: string;
+  timeoutMs?: number;
+  onUpdate?: (progress: CellResult) => void;
+}
+
+export interface QueuedExecution {
+  cellId: string;
+  executionId: string;
+}
+
+export interface JsOutput {
+  outputType: string;
+  name?: string;
+  text?: string;
+  dataJson?: string;
+  ename?: string;
+  evalue?: string;
+  traceback?: string[];
+  executionCount?: number;
+  blobUrlsJson?: string;
+  blobPathsJson?: string;
+}
+
+export interface CellResult {
+  cellId: string;
+  executionId: string;
+  executionCount?: number;
+  status:
+    | "done"
+    | "error"
+    | "timeout"
+    | "kernel_error"
+    | "kernel_failed"
+    | "closed"
+    | "queued"
+    | "running"
+    | (string & {});
+  success: boolean;
+  outputs: JsOutput[];
+}
+
+export interface EventSubscription {
+  dispose(): void;
+}
+
+export interface CellSnapshot {
+  id: string;
+  cellType: string;
+  position: string;
+  source: string;
+  metadataJson: string;
+  executionCount?: string;
+}
+
+export interface CreateCellOptions {
+  cellType?: "code" | "markdown" | "raw";
+  afterCellId?: string | null;
+}
+
+export interface SetCellOptions {
+  source?: string;
+  cellType?: "code" | "markdown" | "raw";
+}
+
+export interface RuntimeStatus {
+  status: string;
+  lifecycle: string;
+  activity?: string;
+  startingPhase: string;
+  name: string;
+  language: string;
+  envSource: string;
+  runtimeAgentId: string;
+  errorReason?: string;
+  errorDetails?: string;
+}
+
+export interface DependencyStatus {
+  uv?: {
+    dependencies: string[];
+    requiresPython?: string;
+  };
+  conda?: {
+    dependencies: string[];
+    channels: string[];
+    python?: string;
+  };
+  pixi?: {
+    dependencies: string[];
+    pypiDependencies: string[];
+    channels: string[];
+    python?: string;
+  };
+  fingerprint?: string;
+  trust?: unknown;
+}
+
+export class Session {
+  readonly notebookId: string;
+  readonly runtimeState$: Observable<RuntimeState>;
+  readonly executionTransitions$: Observable<ExecutionTransition>;
+  readonly cellChanges$: Observable<null>;
+  readonly broadcasts$: Observable<unknown>;
+  readonly sessionStatus$: Observable<SessionStatus>;
+
+  queueCell(source: string, options?: QueueCellOptions): Promise<QueuedExecution>;
+  waitForExecution(executionId: string, options?: WaitExecutionOptions): Promise<CellResult>;
+  runCell(source: string, options?: RunCellOptions): Promise<CellResult>;
+  saveNotebook(path?: string): Promise<void>;
+  listCells(): Promise<CellSnapshot[]>;
+  getCell(cellId: string): Promise<CellSnapshot | null>;
+  createCell(source: string, options?: CreateCellOptions): Promise<string>;
+  setCell(cellId: string, options: SetCellOptions): Promise<boolean>;
+  deleteCell(cellId: string): Promise<boolean>;
+  moveCell(cellId: string, afterCellId?: string | null): Promise<string>;
+  executeCell(cellId: string, options?: { timeoutMs?: number }): Promise<CellResult>;
+  showNotebook(): Promise<unknown>;
+  interruptKernel(): Promise<void>;
+  shutdownKernel(): Promise<void>;
+  restartKernel(): Promise<void>;
+  shutdownNotebook(): Promise<boolean>;
+  addDependency(pkg: string, options?: DependencyEditOptions): Promise<void>;
+  addDependencies(packages: string[], options?: DependencyEditOptions): Promise<void>;
+  removeDependency(pkg: string, options?: DependencyEditOptions): Promise<boolean>;
+  removeDependencies(packages: string[], options?: DependencyEditOptions): Promise<number>;
+  getDependencyStatus(): Promise<DependencyStatus>;
+  getRuntimeStatus(): Promise<RuntimeStatus>;
+  dependencyFingerprint(): Promise<string | null>;
+  approveTrust(observedHeads?: string[]): Promise<void>;
+  syncEnvironment(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export const NativeSession: unknown;
+
+export function defaultSocketPath(): string;
+export function socketPathForChannel(channel: "stable" | "nightly"): string;
+export function createNotebook(options?: CreateNotebookOptions): Promise<Session>;
+export function openNotebook(notebookId: string, options?: OpenNotebookOptions): Promise<Session>;
+export function getExecutionResult(
+  executionId: string,
+  options?: { socketPath?: string },
+): Promise<CellResult>;
+
+export function readParquetFile(
+  filePath: string,
+  offset: number,
+  limit: number,
+): {
+  columns: string[];
+  rows: string[][];
+  totalRows: number;
+  offset: number;
+};
+
+export function summarizeParquetFile(filePath: string): {
+  numRows: number;
+  numBytes: number;
+  columns: Array<{ name: string; dataType: string; nullCount: number; statsJson: string }>;
+};

package/src/napi-observables.cjs

@@ -0,0 +1,9 @@
+"use strict";
+
+function parseJsonEvent(json) {
+  return typeof json === "string" ? JSON.parse(json) : json;
+}
+
+module.exports = {
+  parseJsonEvent,
+};

package/src/session.cjs

@@ -0,0 +1,217 @@
+"use strict";
+
+const { Subject } = require("rxjs");
+const { parseJsonEvent } = require("./napi-observables.cjs");
+
+class Session {
+  constructor(nativeSession) {
+    this._native = nativeSession;
+    this._subscriptions = [];
+    this._runtimeStateSubject = new Subject();
+    this._executionTransitionsSubject = new Subject();
+    this._cellChangesSubject = new Subject();
+    this._broadcastsSubject = new Subject();
+    this._sessionStatusSubject = new Subject();
+    this.runtimeState$ = this._runtimeStateSubject.asObservable();
+    this.executionTransitions$ = this._executionTransitionsSubject.asObservable();
+    this.cellChanges$ = this._cellChangesSubject.asObservable();
+    this.broadcasts$ = this._broadcastsSubject.asObservable();
+    this.sessionStatus$ = this._sessionStatusSubject.asObservable();
+
+    if (typeof nativeSession.onRuntimeState === "function") {
+      this._subscriptions.push(
+        nativeSession.onRuntimeState((json) =>
+          this._runtimeStateSubject.next(parseJsonEvent(json)),
+        ),
+      );
+    }
+    if (typeof nativeSession.onCellChange === "function") {
+      this._subscriptions.push(
+        nativeSession.onCellChange((json) => this._cellChangesSubject.next(parseJsonEvent(json))),
+      );
+    }
+    if (typeof nativeSession.onBroadcast === "function") {
+      this._subscriptions.push(
+        nativeSession.onBroadcast((json) => this._broadcastsSubject.next(parseJsonEvent(json))),
+      );
+    }
+    if (typeof nativeSession.onSessionStatus === "function") {
+      this._subscriptions.push(
+        nativeSession.onSessionStatus((json) =>
+          this._sessionStatusSubject.next(parseJsonEvent(json)),
+        ),
+      );
+    }
+    if (typeof nativeSession.onExecutionTransition === "function") {
+      this._subscriptions.push(
+        nativeSession.onExecutionTransition((json) =>
+          this._executionTransitionsSubject.next(parseJsonEvent(json)),
+        ),
+      );
+    }
+  }
+
+  get notebookId() {
+    return this._native.notebookId;
+  }
+
+  queueCell(source, options) {
+    return this._native.queueCell(source, options);
+  }
+
+  async waitForExecution(executionId, options = {}) {
+    const { onUpdate, ...nativeOptions } = options ?? {};
+    const cellId = nativeOptions.cellId;
+    let progressSubscription = null;
+    if (typeof onUpdate === "function" && typeof this._native.onExecutionProgress === "function") {
+      progressSubscription = this._native.onExecutionProgress(
+        executionId,
+        cellId ?? null,
+        (json) => {
+          onUpdate(parseJsonEvent(json));
+        },
+      );
+    }
+
+    try {
+      return await this._native.waitForExecution(executionId, nativeOptions);
+    } finally {
+      progressSubscription?.dispose?.();
+    }
+  }
+
+  async runCell(source, options = {}) {
+    if (typeof options?.onUpdate !== "function") {
+      return this._native.runCell(source, options);
+    }
+    const queued = await this.queueCell(source, options);
+    return this.waitForExecution(queued.executionId, {
+      ...options,
+      cellId: queued.cellId,
+    });
+  }
+
+  saveNotebook(path) {
+    return this._native.saveNotebook(path);
+  }
+
+  listCells() {
+    return this._native.listCells();
+  }
+
+  getCell(cellId) {
+    return this._native.getCell(cellId);
+  }
+
+  createCell(source, options) {
+    return this._native.createCell(source, options);
+  }
+
+  setCell(cellId, options) {
+    return this._native.setCell(cellId, options);
+  }
+
+  deleteCell(cellId) {
+    return this._native.deleteCell(cellId);
+  }
+
+  moveCell(cellId, afterCellId) {
+    return this._native.moveCell(cellId, { afterCellId: afterCellId ?? null });
+  }
+
+  executeCell(cellId, options) {
+    return this._native.executeCell(cellId, options);
+  }
+
+  showNotebook() {
+    return this._native.showNotebook();
+  }
+
+  interruptKernel() {
+    return this._native.interruptKernel();
+  }
+
+  shutdownKernel() {
+    return this._native.shutdownKernel();
+  }
+
+  restartKernel() {
+    return this._native.restartKernel();
+  }
+
+  shutdownNotebook() {
+    return this._native.shutdownNotebook();
+  }
+
+  addDependency(pkg, options) {
+    return this._native.addDependency(pkg, normalizeDependencyOptions(options));
+  }
+
+  addDependencies(packages, options) {
+    return this._native.addDependencies(
+      normalizePackages(packages),
+      normalizeDependencyOptions(options),
+    );
+  }
+
+  removeDependency(pkg, options) {
+    return this._native.removeDependency(pkg, normalizeDependencyOptions(options));
+  }
+
+  removeDependencies(packages, options) {
+    return this._native.removeDependencies(
+      normalizePackages(packages),
+      normalizeDependencyOptions(options),
+    );
+  }
+
+  getDependencyStatus() {
+    return this._native.getDependencyStatus();
+  }
+
+  getRuntimeStatus() {
+    return this._native.getRuntimeStatus();
+  }
+
+  dependencyFingerprint() {
+    return this._native.dependencyFingerprint();
+  }
+
+  approveTrust(observedHeads) {
+    return this._native.approveTrust(observedHeads);
+  }
+
+  syncEnvironment() {
+    return this._native.syncEnvironment();
+  }
+
+  close() {
+    for (const subscription of this._subscriptions.splice(0)) {
+      subscription?.dispose?.();
+    }
+    this._runtimeStateSubject.complete();
+    this._executionTransitionsSubject.complete();
+    this._cellChangesSubject.complete();
+    this._broadcastsSubject.complete();
+    this._sessionStatusSubject.complete();
+    return this._native.close();
+  }
+}
+
+function normalizePackages(packages) {
+  if (!Array.isArray(packages)) {
+    throw new TypeError("packages must be an array of dependency specifiers");
+  }
+  return Array.from(new Set(packages.map((pkg) => String(pkg).trim()).filter(Boolean)));
+}
+
+function normalizeDependencyOptions(options) {
+  if (!options?.packageManager) {
+    return undefined;
+  }
+  return { packageManager: options.packageManager };
+}
+
+module.exports = {
+  Session,
+};