Summary
Add a `notebook_run` tool that executes cells in a Jupyter notebook and returns their outputs (stdout, stderr, display data, errors).
Motivation
`notebook_edit` and `notebook_write` let the model write notebooks, but there is no way to actually run them and observe results. `notebook_run` closes that loop: write code → run it → read outputs → iterate.
Proposed API
```
notebook_run:
notebook_path: /path/to/analysis.ipynb # required
cell_ids: ["cell-0", "cell-1"] # optional — run specific cells only
timeout: 60 # seconds per cell (default 60)
restart_kernel: false # restart before running (default false)
```
Returns per-cell output (stdout, display_data, error tracebacks) and execution counts.
Architecture
This is a non-trivial sub-system:
- Kernel manager (Go) — starts `jupyter kernel` via `uv run` in the Nexus-managed venv (`~/.config/nexus-cli/.venv`), one kernel per notebook path (pooled).
- ZMQ client (Go) — communicates with the kernel over the Jupyter wire protocol (execute_request / execute_reply / iopub stream).
- Output capture — streams stdout/stderr/display_data/error back from iopub channel; respects per-cell timeout.
- Lifecycle — kernels are kept alive between calls (fast subsequent runs) and cleaned up on TUI exit alongside the docling manager.
Dependencies
- `jupyter_client` Python package (installed via the managed venv — see `make install-python`).
- ZMQ bindings: either `go-zeromq/zmq4` (pure Go) or `pebbe/zmq4` (cgo, requires libzmq).
- Prefer pure-Go `go-zeromq/zmq4` to avoid the libzmq system dependency.
Implementation phases
- Install `jupyter_client` and `ipykernel` in `scripts/install-python-env.sh`.
- Implement `internal/python/kernel.go` — `KernelManager` struct (start / execute / shutdown).
- Implement `internal/tools/files/notebook/run.go` — `RunTool` following the same pattern as `EditTool` / `WriteTool`.
- Register in `builtin.go` + add TUI renderer in `notebook.go`.
Notes
- This is the highest-value notebook feature but also the most complex. Estimated effort: 2–3 days.
- Blocked on `go-zeromq/zmq4` compatibility check (pure-Go ZMQ). If that proves difficult, fall back to shelling out to a small Python script via `uv run`.
- Related: [[notebook_create]], [[notebook_write]] (already implemented in `internal/tools/files/notebook/`).
Summary
Add a `notebook_run` tool that executes cells in a Jupyter notebook and returns their outputs (stdout, stderr, display data, errors).
Motivation
`notebook_edit` and `notebook_write` let the model write notebooks, but there is no way to actually run them and observe results. `notebook_run` closes that loop: write code → run it → read outputs → iterate.
Proposed API
```
notebook_run:
notebook_path: /path/to/analysis.ipynb # required
cell_ids: ["cell-0", "cell-1"] # optional — run specific cells only
timeout: 60 # seconds per cell (default 60)
restart_kernel: false # restart before running (default false)
```
Returns per-cell output (stdout, display_data, error tracebacks) and execution counts.
Architecture
This is a non-trivial sub-system:
Dependencies
Implementation phases
Notes