dsh-plugin-notebook-tools

Cell-aware Jupyter notebook tools for DSH agents. A zero-dependency Node ESM
plugin that ports the OpenClaw notebook-tools plugin (9 tools) onto the DSH
host.

The core read / write / edit tools treat .ipynb files as opaque JSON,
which is error-prone, token-hungry, and easy to corrupt. This plugin provides a
structured, cell-aware API instead: stable cell ids, output-aware truncation,
stale-edit guards, and format-preserving atomic writes.

Install

dsh plugin --profile desktop add --config.minimumReleaseAge=0 F:\path\to\dsh-plugin-notebook-tools

dsh plugin forwards to the pnpm bundled with DSH, and --profile is
required. The --config.minimumReleaseAge=0 override is needed while the
target profile's existing lockfile entries are newer than pnpm's default
minimumReleaseAge cutoff (pnpm 11.7.0 enforces that default even when the
profile's pnpm-workspace.yaml lists the same offenders under
minimumReleaseAgeExclude). Without it you get
ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION naming packages you did not touch.

On success the package is appended to both dependencies and
dsh.profile.bundles in \profiles\\package.json — no
manual edit needed. A failed run can still leave a link in node_modules, so
treat the package.json entry, not node_modules, as proof.

The plugin ships a cordis.patch.yml that inserts it under the id
notebook-tools. DSH composes that row at boot, so restart the DSH app for
the tools to appear in an already-running session.

No dependencies are installed: pnpm install is unnecessary, and the package
imports only node: builtins.

Companion skill

skill/notebook-tools/SKILL.md is the matching DSH skill: it tells the agent
when to reach for these tools, which of them can mutate a notebook, and how
stable a cell id really is. Copy it into the skills directory:

Copy-Item -Recurse skill\notebook-tools "$env:USERPROFILE\.dsh\skills\notebook-tools" -Force

DSH hot-reloads the skills directory, so the skill shows up without a restart —
unlike the plugin itself, which is composed at boot.

Tools

Guarantees

• Writes preserve the file's own formatting. The plugin probes the layout a
  notebook already uses — JSON indent (0/1/2/4), CRLF vs LF, trailing newline —
  and writes it back unchanged, so a notebook produced by JupyterLab,
  nbformat.writes, or a text editor is not reformatted. A cell whose source
  is a plain string stays a string, and keys that were absent (outputs,
  execution_count, metadata) are not invented. Read-then-write with no edit
  is byte-identical. Not preserved: tab indentation, \uXXXX-escaped non-ASCII
  (Python's ensure_ascii=True), and more than one trailing newline.
• Atomic saves. Mutations serialize to a sibling temp file
  (.‹basename›.tmp-‹pid›-‹counter›-‹random›) in the same directory, fsync it,
  then rename over the target. A killed process can never leave a half-written
  notebook, and no temp file ever lands in the system temp directory.
• Validation before every write. A notebook that fails the deep audit — cell
  ids outside ^[A-Za-z0-9_-]{1,64}$ or duplicated, non-object metadata,
  non-array outputs, non-string source elements — is refused by the writers
  and reported by notebook_validate, instead of being silently rewritten.
• Cell ids over indexes. notebook_read, notebook_list_cells, and
  notebook_search always return an id. A notebook too old to store ids
  (nbformat < 4.5) gets ids derived from sha256("v1||"), so
  the same cell keeps the same id across loads and processes; the derived id is
  persisted only once the file's format supports ids. nbformat_minor is never
  bumped. Indexes shift after every insert/delete — prefer ids.
• Editing a code cell clears outputs and execution_count, and the
  response text says so.
• Three stale-edit guards on every mutating tool. expected_file_sha256
  catches any change to the bytes on disk — including a rewrite inside the same
  millisecond, which expected_file_mtime_ms cannot see; expected_source_sha256
  catches a change to the one cell an operation depends on (the anchor cell for
  an insert, the target cell for an edit, delete, or clear); the mtime check is
  the cheap one and tolerates sub-millisecond jitter. All of them fail before
  any write. notebook_read and notebook_list_cells return both mtime_ms
  and file_sha256; only notebook_read returns per-cell source_sha256.
• nbformat 4 only. v3 and earlier are rejected.
• No kernel execution, ever.
• Failures throw a NotebookError subclass carrying a stable code
  (NOTEBOOK_NOT_FOUND, STALE_NOTEBOOK, CELL_NOT_FOUND, …). There is no
  isError field on the DSH tool result contract.

Usage

notebook_list_cells  { path: "~/analysis.ipynb" }
notebook_read        { path: "~/analysis.ipynb", cell_ids: ["a1b2c3d4"] }
notebook_search      { path: "~/analysis.ipynb", query: "train_test_split" }
notebook_edit_cell   { path: "~/analysis.ipynb", cell_id: "a1b2c3d4",
new_source: "model.fit(X, y)\n",
expected_source_sha256: "…",
expected_file_sha256: "…" }
notebook_validate    { path: "~/analysis.ipynb" }

Pass the guards straight back from the read that produced them — file_sha256
comes from notebook_read or notebook_list_cells, source_sha256 only from
notebook_read.

Development

node --test          # from this directory

Tests use node:test + node:assert/strict and require Node >= 22 (verified
on Node 24).

Releasing

Releases are one command, run from a clean main that already contains the
version bump:

npm run release -- --title "v0.2.1 - short one-line summary"

It refuses to run unless CHANGELOG.md carries a non-empty ## []
section and a []: link reference for the version in package.json,
the working tree is clean, and HEAD is the commit that carries the bump. Then it
runs node --test, pushes the release branch, creates the annotated tag
v, pushes it, and
creates the GitHub Release: the tag annotation is the release title and the
CHANGELOG section is its body. Credentials come from GITHUB_TOKEN / GH_TOKEN,
falling back to the stored git credential for github.com (nothing is ever
printed); the GitHub CLI is not required.

Other flags: --dry-run (print the plan, change nothing), --skip-tests,
--branch (default main), --remote (default origin).

Layout

lib/index.js              composition only — registers the 9 tools on ctx.tools
lib/nb/*.js               pure domain; node: builtins only, no host SDK imports
lib/tools/*.js            adapters: JSON Schema params, error mapping, response text
scripts/release.mjs       the release command behind "npm run release"
test/*.test.js            node:test suites
cordis.patch.yml          the composition row DSH merges at boot
skill/notebook-tools/     the companion skill (SKILL.md)

The domain layer (lib/nb/) knows nothing about DSH — it only knows about
notebooks, so it stays unit-testable in isolation.

Credits and license

MIT. This is a port, not a fork: the domain layer and all nine tool
adapters were re-implemented for the DSH plugin host from the original plugin's
documented behavior.

• Upstream: Lightbridge-KS/openclaw-notebook-tools
  by Kittipos Sirivongrungson (MIT). The tool surface, the behavioral spec in
  its docs/Notebook-Tools-Spec.md, and the companion skill all originate
  there.
• This port: the DSH packaging (cordis.patch.yml, the dsh.bundle.patch
  hook), the zero-dependency plain-object tool descriptors, and the test
  suites.

LICENSE carries both copyright notices.