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 <DSH_HOME>\profiles\<profile>\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
| Tool | Writes | Purpose |
|---|
notebook_create | yes | Create a notebook from structured cells |
notebook_read | no | Structured read, optionally with outputs |
notebook_list_cells | no | Cheap index: id, type, preview, counts |
notebook_search | no | Find cells by text or regex |
notebook_validate | no | Validate structure and report facts |
notebook_edit_cell | yes | Replace a cell's source / type |
notebook_insert_cell | yes | Insert a new cell at a position |
notebook_delete_cell | yes | Delete a cell by id or index |
notebook_clear_outputs | yes | Clear outputs (all or one cell) |
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|<ordinal>|<source>"), 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 ; only returns per-cell .
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 ## [<version>]
section and a [<version>]: 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<version>, 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 <name> (default main), --remote <name> (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.
