opencode-ipynb 0.1.2 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +37 -0
- package/README.md +191 -41
- package/dist/domain/cell.d.ts +2 -1
- package/dist/domain/errors.d.ts +3 -31
- package/dist/domain/execution.d.ts +4 -1
- package/dist/domain/notebook.d.ts +1 -1
- package/dist/domain/output.d.ts +0 -1
- package/dist/format/diagnostics.d.ts +0 -1
- package/dist/format/markdown.d.ts +1 -2
- package/dist/format/{diff.d.ts → notebook.d.ts} +2 -1
- package/dist/format/outputs.d.ts +3 -2
- package/dist/index.d.ts +3 -1
- package/dist/index.js +7303 -26413
- package/dist/load-document.d.ts +16 -0
- package/dist/lsp.d.ts +97 -0
- package/dist/lsp.js +129 -0
- package/dist/notebook-diagnostics.d.ts +55 -0
- package/dist/notebook-hooks.d.ts +23 -0
- package/dist/plugin-options.d.ts +4 -1
- package/dist/plugin-v2.d.ts +35 -0
- package/dist/plugin.d.ts +2 -3
- package/dist/registrations.d.ts +5 -0
- package/dist/rpc.d.ts +141 -0
- package/dist/rpc.js +84 -0
- package/dist/services/KernelManager.d.ts +36 -0
- package/dist/services/NotebookCleanService.d.ts +3 -7
- package/dist/services/NotebookEditService.d.ts +6 -12
- package/dist/services/NotebookExecutionService.d.ts +15 -11
- package/dist/services/NotebookExportService.d.ts +3 -7
- package/dist/services/NotebookFileService.d.ts +19 -13
- package/dist/services/NotebookInspectService.d.ts +15 -14
- package/dist/services/NotebookOutputService.d.ts +4 -10
- package/dist/services/NotebookReadService.d.ts +4 -10
- package/dist/services/PathService.d.ts +5 -7
- package/dist/services/PermissionService.d.ts +6 -8
- package/dist/services/PythonService.d.ts +23 -42
- package/dist/services/index.d.ts +22 -29
- package/dist/services/revision.d.ts +15 -0
- package/dist/tool.d.ts +66 -0
- package/dist/tools/_readPermission.d.ts +8 -0
- package/dist/tools/_resolveOptions.d.ts +13 -2
- package/dist/tools/cell_delete.d.ts +4 -13
- package/dist/tools/cell_insert.d.ts +10 -21
- package/dist/tools/cell_move.d.ts +5 -15
- package/dist/tools/clean.d.ts +8 -21
- package/dist/tools/doctor.d.ts +3 -11
- package/dist/tools/edit.d.ts +10 -21
- package/dist/tools/export.d.ts +12 -23
- package/dist/tools/inspect.d.ts +7 -19
- package/dist/tools/kernel.d.ts +13 -21
- package/dist/tools/lsp.d.ts +9 -0
- package/dist/tools/outputs.d.ts +15 -29
- package/dist/tools/read.d.ts +12 -29
- package/dist/tools/repro.d.ts +6 -14
- package/dist/tools/run.d.ts +17 -34
- package/dist/utils/ansi.d.ts +2 -1
- package/dist/utils/atomic-replace.d.ts +6 -0
- package/dist/utils/attachments.d.ts +2 -3
- package/dist/utils/execution-order.d.ts +8 -0
- package/dist/utils/fence.d.ts +2 -0
- package/dist/utils/i18n.d.ts +1 -2
- package/dist/utils/imports.d.ts +6 -1
- package/dist/utils/json.d.ts +0 -1
- package/dist/utils/limits.d.ts +12 -2
- package/dist/utils/markdown-safe.d.ts +7 -0
- package/dist/utils/metadata.d.ts +3 -0
- package/dist/utils/mime.d.ts +1 -1
- package/dist/utils/paths.d.ts +0 -2
- package/dist/utils/truncate.d.ts +0 -1
- package/dist/utils/windows.d.ts +4 -0
- package/dist/virtual-materialize.d.ts +36 -0
- package/package.json +30 -18
- package/python/ipynb_runner.py +247 -17
- package/python/requirements.txt +5 -4
- package/server.js +3 -0
- package/dist/domain/cell.d.ts.map +0 -1
- package/dist/domain/errors.d.ts.map +0 -1
- package/dist/domain/execution.d.ts.map +0 -1
- package/dist/domain/notebook.d.ts.map +0 -1
- package/dist/domain/output.d.ts.map +0 -1
- package/dist/format/diagnostics.d.ts.map +0 -1
- package/dist/format/diff.d.ts.map +0 -1
- package/dist/format/markdown.d.ts.map +0 -1
- package/dist/format/outputs.d.ts.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/plugin-options.d.ts.map +0 -1
- package/dist/plugin.d.ts.map +0 -1
- package/dist/services/DiffService.d.ts +0 -17
- package/dist/services/DiffService.d.ts.map +0 -1
- package/dist/services/NotebookCleanService.d.ts.map +0 -1
- package/dist/services/NotebookEditService.d.ts.map +0 -1
- package/dist/services/NotebookExecutionService.d.ts.map +0 -1
- package/dist/services/NotebookExportService.d.ts.map +0 -1
- package/dist/services/NotebookFileService.d.ts.map +0 -1
- package/dist/services/NotebookInspectService.d.ts.map +0 -1
- package/dist/services/NotebookOutputService.d.ts.map +0 -1
- package/dist/services/NotebookReadService.d.ts.map +0 -1
- package/dist/services/PathService.d.ts.map +0 -1
- package/dist/services/PermissionService.d.ts.map +0 -1
- package/dist/services/PythonService.d.ts.map +0 -1
- package/dist/services/index.d.ts.map +0 -1
- package/dist/tools/_resolveOptions.d.ts.map +0 -1
- package/dist/tools/cell_delete.d.ts.map +0 -1
- package/dist/tools/cell_insert.d.ts.map +0 -1
- package/dist/tools/cell_move.d.ts.map +0 -1
- package/dist/tools/clean.d.ts.map +0 -1
- package/dist/tools/doctor.d.ts.map +0 -1
- package/dist/tools/edit.d.ts.map +0 -1
- package/dist/tools/export.d.ts.map +0 -1
- package/dist/tools/inspect.d.ts.map +0 -1
- package/dist/tools/kernel.d.ts.map +0 -1
- package/dist/tools/outputs.d.ts.map +0 -1
- package/dist/tools/read.d.ts.map +0 -1
- package/dist/tools/repro.d.ts.map +0 -1
- package/dist/tools/run.d.ts.map +0 -1
- package/dist/utils/ansi.d.ts.map +0 -1
- package/dist/utils/attachments.d.ts.map +0 -1
- package/dist/utils/fiber.d.ts +0 -2
- package/dist/utils/fiber.d.ts.map +0 -1
- package/dist/utils/i18n.d.ts.map +0 -1
- package/dist/utils/imports.d.ts.map +0 -1
- package/dist/utils/json.d.ts.map +0 -1
- package/dist/utils/limits.d.ts.map +0 -1
- package/dist/utils/mime.d.ts.map +0 -1
- package/dist/utils/paths.d.ts.map +0 -1
- package/dist/utils/truncate.d.ts.map +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 2.0.0
|
|
4
|
+
|
|
5
|
+
- OpenCode V2-only plugin (`@opencode/plugin` 2.2.2). The V1 `server()` export is removed.
|
|
6
|
+
- 14 native notebook tools with JSON Schema inputs, permission assertions, and V2 result metadata.
|
|
7
|
+
- Real-path path confinement, symlink-alias locking, and atomic notebook writes.
|
|
8
|
+
- Notebook LSP support: virtual Python document, cell mapping, post-edit/on-demand
|
|
9
|
+
pyright diagnostics, and a materialized `.py` sidecar for per-cell hover,
|
|
10
|
+
go-to-definition, find-references, and document symbols through
|
|
11
|
+
`opencode-v2-lsp-support`. Sidecars live next to the notebook
|
|
12
|
+
(`opencode-ipynb-lsp-<hash>.py`) so sibling imports resolve; add
|
|
13
|
+
`opencode-ipynb-lsp-*.py` to `.gitignore`.
|
|
14
|
+
- Token-efficient `ipynb_edit` results (no echoed source or diff).
|
|
15
|
+
- Warm-kernel source reload, per-request timeouts, abort handling, and startup timeouts.
|
|
16
|
+
- `allowOutsideWorktree` escape hatch preserved for notebook reads/writes and exports.
|
|
17
|
+
- Services migrated to Effect **4.0.6**, matching OpenCode 2's plugin SDK.
|
|
18
|
+
- New `docs/architecture.md`, `docs/contributing.md`, a CI workflow, and an
|
|
19
|
+
`opencode.example.jsonc` template.
|
|
20
|
+
|
|
21
|
+
### Breaking changes
|
|
22
|
+
|
|
23
|
+
- V1 OpenCode is no longer supported. Use plugin `0.1.2` with OpenCode 1.
|
|
24
|
+
- `ipynb_edit` no longer returns a textual old/new/diff body; it returns a concise
|
|
25
|
+
confirmation plus diagnostics.
|
|
26
|
+
- LSP diagnostics use a 0-based cell index and 1-based line/character positions in human-readable text.
|
|
27
|
+
- Read-only notebook tools (`ipynb_inspect`, `ipynb_read`, `ipynb_repro`) now declare and assert the V2 `read` action; mixed tools assert `read`/`edit` per branch.
|
|
28
|
+
- `ipynb_kernel restart` stops the current kernel; the next run starts a new one (it does not respawn eagerly).
|
|
29
|
+
- `helperRelativePath` is now resolved only relative to the plugin package or as an absolute path; it is no longer searched in the project cwd/worktree (prevents helper shadowing).
|
|
30
|
+
- `ipynb_run save=true` requires an `edit` permission in addition to `shell`,
|
|
31
|
+
and the edit is asserted before user code runs. A denied edit executes nothing.
|
|
32
|
+
- `ipynb_run` now defaults `maxOutputChars` to `defaultMaxOutputChars` (6000),
|
|
33
|
+
matching the other read tools. Pass `maxOutputChars` explicitly for larger output.
|
|
34
|
+
|
|
35
|
+
## 0.1.2
|
|
36
|
+
|
|
37
|
+
- Final V1 release. See the repository history for the V1 feature set.
|
package/README.md
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
A community [OpenCode](https://opencode.ai) plugin that adds robust support for Jupyter Notebook (`.ipynb`) files: inspect, read, edit, run, outputs, clean, export, reproducibility reports, and warm Python kernels.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> **OpenCode 2.x only.** The plugin implements the V2 plugin API and does not load on OpenCode 1.x.
|
|
6
|
+
|
|
7
|
+
The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode core. It exposes fourteen agent tools that operate on `.ipynb` files with explicit permissions, granular context control, and a strongly-typed [Effect 4.0.6](https://effect.website) runtime internally, matching OpenCode 2.
|
|
6
8
|
|
|
7
9
|
> Repository: https://github.com/Restodecoca/opencode-ipynb
|
|
8
10
|
> Issues: https://github.com/Restodecoca/opencode-ipynb/issues
|
|
@@ -10,39 +12,42 @@ The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode
|
|
|
10
12
|
## Why a plugin and not core
|
|
11
13
|
|
|
12
14
|
- Notebooks are large, binary-like artifacts. Dumping them into the agent context burns tokens.
|
|
13
|
-
- Reading outputs and editing cells are high-trust actions that
|
|
15
|
+
- Reading outputs and editing cells are high-trust actions that are gated by the host permission system.
|
|
14
16
|
- The execution flow needs a Python runtime, which is not something every OpenCode user wants installed.
|
|
15
17
|
- A plugin lets the community iterate on these workflows without forcing changes on the OpenCode core.
|
|
16
18
|
|
|
17
19
|
## Installation
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
OpenCode 2.x loads plugins from the `plugins` key. Until the V2 line (`2.0.0`) is published, point OpenCode at a checkout directory:
|
|
20
22
|
|
|
21
23
|
```json
|
|
22
24
|
{
|
|
23
25
|
"$schema": "https://opencode.ai/config.json",
|
|
24
|
-
"
|
|
26
|
+
"plugins": ["/absolute/path/to/opencode-ipynb"]
|
|
25
27
|
}
|
|
26
28
|
```
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
The npm `latest` tag still points at the V1 `0.1.2` package, which does **not** load in OpenCode 2. After the V2 package is published, the versioned form is:
|
|
29
31
|
|
|
30
32
|
```json
|
|
31
33
|
{
|
|
32
|
-
"
|
|
34
|
+
"$schema": "https://opencode.ai/config.json",
|
|
35
|
+
"plugins": ["opencode-ipynb@2.0.0"]
|
|
33
36
|
}
|
|
34
37
|
```
|
|
35
38
|
|
|
39
|
+
`opencode.example.jsonc` is a machine-independent local example.
|
|
40
|
+
|
|
36
41
|
Or run directly from this repo:
|
|
37
42
|
|
|
38
43
|
```bash
|
|
39
44
|
git clone https://github.com/Restodecoca/opencode-ipynb
|
|
40
45
|
cd opencode-ipynb
|
|
41
46
|
bun install
|
|
42
|
-
bun run build
|
|
47
|
+
bun run build # requires Bun and Node (Node clears dist/)
|
|
43
48
|
```
|
|
44
49
|
|
|
45
|
-
Then add
|
|
50
|
+
Then add the **absolute path** to this checkout to the `plugins` array in your `opencode.json` (package-name resolution only works after the V2 package is published).
|
|
46
51
|
|
|
47
52
|
## Tools
|
|
48
53
|
|
|
@@ -50,17 +55,18 @@ Then add `"opencode-ipynb"` (or the local path) to your `opencode.json`.
|
|
|
50
55
|
| -------------------- | ------- |
|
|
51
56
|
| `ipynb_inspect` | Compact summary: kernel/language metadata, cell table, output stats, execution-order warnings, optional missing-package checks. |
|
|
52
57
|
| `ipynb_read` | Granular read of one cell or a range, with optional outputs/errors/metadata/images and truncation limits. |
|
|
53
|
-
| `ipynb_edit` | Safe per-cell source edit with
|
|
54
|
-
| `ipynb_cell_insert` | Insert a code/markdown/raw cell
|
|
58
|
+
| `ipynb_edit` | Safe per-cell source edit with a concise confirmation, output clearing policy, permission gate, and per-file lock. |
|
|
59
|
+
| `ipynb_cell_insert` | Insert a code/markdown/raw cell at a target index, or append when the index is omitted. |
|
|
55
60
|
| `ipynb_cell_delete` | Delete one cell by index and return a preview of the deleted source. |
|
|
56
61
|
| `ipynb_cell_move` | Move one cell to a new index. |
|
|
57
62
|
| `ipynb_run` | Execute one cell, a range, from a cell, or a full notebook via the Python helper. Supports save-to-notebook and optional warm kernels. |
|
|
58
63
|
| `ipynb_outputs` | List / read / read_error / clear_cell / clear_all outputs with pagination and permission gates for writes. |
|
|
59
64
|
| `ipynb_clean` | Strip outputs, execution counts, widget state, large images, and normalize `source` arrays for Git-friendly diffs. |
|
|
60
|
-
| `ipynb_export` | Export to Markdown, Python, or summary; optionally write to disk after permission. |
|
|
65
|
+
| `ipynb_export` | Export to Markdown, Python, or summary; optionally write to disk after permission. Files are written with full text outputs (images are represented by notices); the tool output is capped by `maxExportChars`. |
|
|
61
66
|
| `ipynb_doctor` | Diagnose Python, helper discovery, and required Jupyter dependencies. |
|
|
62
67
|
| `ipynb_repro` | Reproducibility report: kernel/env info, `pip freeze`, filesystem reads, random seeds, non-determinism, missing packages. |
|
|
63
|
-
| `ipynb_kernel` | Inspect/restart/shutdown warm kernels when `
|
|
68
|
+
| `ipynb_kernel` | Inspect/restart/shutdown warm kernels when the `warmKernel` plugin option is enabled. `restart` stops the current kernel; the next run starts a new one. |
|
|
69
|
+
| `ipynb_lsp` | Run on-demand Python diagnostics, or materialize the virtual `.py` for per-cell LSP navigation. |
|
|
64
70
|
|
|
65
71
|
### Examples
|
|
66
72
|
|
|
@@ -114,11 +120,40 @@ ipynb_export({
|
|
|
114
120
|
})
|
|
115
121
|
```
|
|
116
122
|
|
|
123
|
+
## Edit results and diagnostics
|
|
124
|
+
|
|
125
|
+
`ipynb_edit` returns a concise confirmation (cell, file, type, and whether outputs were cleared) instead of echoing the old/new source or a diff. The model already has the source it sent, so the extra text only spends tokens.
|
|
126
|
+
|
|
127
|
+
After code-changing tools, the plugin runs pyright on the notebook's virtual Python document for **Python notebooks only** and appends errors in the same block shape used by [`opencode-v2-lsp-support`](https://github.com/christensenjairus/opencode-v2-lsp-support):
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
LSP errors detected in this file, please fix:
|
|
131
|
+
<diagnostics file="/absolute/path/notebook.ipynb">
|
|
132
|
+
ERROR [cell 0, line 1:10] Type "Literal['no']" is not assignable to declared type "int"
|
|
133
|
+
</diagnostics>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The cell-mapped errors are also available as `metadata.notebookDiagnostics`; `metadata.diagnostics` is not emitted for custom tools because OpenCode 2 only feeds that field to its native edit renderer. `ipynb_lsp` runs the same check on demand and reports whether it was skipped (timeout, missing pyright, invalid output, not-analyzed, temp-unwritable, aborted, unsupported-language) instead of claiming a clean result.
|
|
137
|
+
|
|
117
138
|
## Safety and permissions
|
|
118
139
|
|
|
119
|
-
- Every write (`ipynb_edit`, `ipynb_clean`, `ipynb_outputs clear_*`, `ipynb_export --outputPath`) calls `
|
|
120
|
-
-
|
|
121
|
-
|
|
140
|
+
- Every write (`ipynb_edit`, `ipynb_cell_insert`, `ipynb_cell_delete`, `ipynb_cell_move`, `ipynb_clean`, `ipynb_outputs clear_*`, `ipynb_export --outputPath`, and `ipynb_lsp operation=materialize` for its sidecar) calls `ctx.permission.assert` before touching the disk, and every execution (`ipynb_run`) asks with rich metadata: file path, mode (`cell` / `range` / `all` / `from`), cell range, save flag, working directory, timeout. When `save=true`, a second `edit` assert covers the notebook write.
|
|
141
|
+
- Permission requests use V2 action names: writes use `edit`, reads use `read`, and execution uses `shell`. Configure them with the ordered `permissions` array, for example `[{ "action": "edit", "resource": "*", "effect": "ask" }, { "action": "shell", "resource": "*", "effect": "ask" }, { "action": "lsp", "resource": "*", "effect": "ask" }]`. **Rules are evaluated in order and the last matching rule wins**: put a specific `deny` after a broad `allow`, otherwise the allow overrides it. The plugin sends absolute, real, and session-relative resource paths so relative rules such as `secrets/*` also apply. For example:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
"permissions": [
|
|
145
|
+
{ "action": "read", "resource": "*", "effect": "allow" },
|
|
146
|
+
{ "action": "read", "resource": "secrets/*", "effect": "deny" },
|
|
147
|
+
{ "action": "edit", "resource": "*", "effect": "allow" },
|
|
148
|
+
{ "action": "edit", "resource": "secrets/*", "effect": "deny" },
|
|
149
|
+
{ "action": "shell", "resource": "*", "effect": "ask" },
|
|
150
|
+
{ "action": "lsp", "resource": "*", "effect": "ask" }
|
|
151
|
+
]
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Note that a tool-level `edit: deny` also removes tools that declare `options.permission: "edit"` from the model catalog; mixed tools remain visible and fail when their write branch asserts `edit`.
|
|
155
|
+
- Tools that always mutate (`ipynb_edit`, `ipynb_cell_insert`, `ipynb_cell_delete`, `ipynb_cell_move`, `ipynb_clean`) declare `options.permission: "edit"`, and `ipynb_run` declares `"shell"`. `ipynb_lsp` declares `"lsp"`; diagnostics asks for `lsp`/`read` on the notebook and `edit` on its temporary analysis file; materialize asks for `read`/`lsp` on the notebook and `edit` on the sidecar path. Read-only tools (`ipynb_inspect`, `ipynb_read`, `ipynb_repro`) declare `"read"` and also assert `read` on the notebook path. When they need Python, they assert `shell` before spawning it: `ipynb_repro` always does, and `ipynb_inspect` only when `checkMissingPackages=true`. This ordering means a denied `shell` action prevents the subprocess entirely. `ipynb_doctor` also asserts `shell` for the interpreter before probing it. Mixed read/write tools (`ipynb_outputs`, `ipynb_export`) do not declare a tool-level permission; their read branches assert `read` and their writes assert `edit`. `ipynb_doctor` declares no permission action. `ipynb_kernel` declares no tool-level action, but `restart`/`shutdown` assert `shell` on the kernel's notebook path before stopping it.
|
|
156
|
+
- `PathService` rejects paths that resolve outside of the OpenCode worktree, and `NotebookFileService` pins the resolved real path inside the worktree before reading or writing. Symlink aliases share a lock and writes update the real target rather than replacing the link. The lock manager keys by real path and serializes per-file writes to prevent accidental corruption.
|
|
122
157
|
- The Python execution helper is an opt-in, isolated subprocess; it does not auto-install Jupyter. The user installs `python/requirements.txt` only when they want real execution.
|
|
123
158
|
|
|
124
159
|
## Context control
|
|
@@ -126,12 +161,81 @@ ipynb_export({
|
|
|
126
161
|
Notebooks can be enormous. By default the plugin never dumps a full notebook into context:
|
|
127
162
|
|
|
128
163
|
- `ipynb_inspect` returns a table with the first line of every cell, plus aggregate counts. It never includes the full source.
|
|
129
|
-
- `ipynb_read` defaults to **not** including outputs. Set `includeOutputs: true` to opt in. Images
|
|
130
|
-
- `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap
|
|
131
|
-
- `
|
|
132
|
-
-
|
|
164
|
+
- `ipynb_read` defaults to **not** including outputs. Set `includeOutputs: true` to opt in. Images/base64 are omitted by default; set `includeImages: true` to receive them as file attachments (the text block still only contains a size notice).
|
|
165
|
+
- `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap per-cell source/output; tracebacks have their own 8 000-character cap.
|
|
166
|
+
- Notebook reads are limited to 50 MB and `ipynb_read` ranges to 500 cells; use `ipynb_inspect` for a compact summary of very large notebooks.
|
|
167
|
+
- `ipynb_run save=true` reports `saved:false` when no code cell was actually written (for example a markdown-only target).
|
|
168
|
+
- Error tracebacks are capped internally at 8 000 characters.
|
|
169
|
+
- Truncation appends `... (truncated, use maxXxx to increase)`; with extremely small budgets the hint itself may exceed the requested maximum, but original content is never included.
|
|
170
|
+
|
|
171
|
+
Most limits live in `src/utils/limits.ts`; the traceback cap is fixed in `src/format/outputs.ts`.
|
|
172
|
+
|
|
173
|
+
## LSP integration
|
|
174
|
+
|
|
175
|
+
The plugin does not ship or require a language server, but it exposes a stable, provider-agnostic bridge so an OpenCode LSP or a third-party plugin can consume notebook edits.
|
|
176
|
+
|
|
177
|
+
The compatibility model is the **file-based virtual document** used by jupyter-lsp, jedi-language-server, Ruff, and Pyrefly: code cells are concatenated into one virtual source file, and positions are mapped back to `(cellIndex, line, character)`. Clients that implement LSP 3.17 `notebookDocument` synchronization can build on the per-cell `text`/`uri` fields; they still need to supply notebook type, versions, and stable cell identity themselves.
|
|
178
|
+
|
|
179
|
+
- `opencode-ipynb/lsp` exports `buildNotebookVirtualDocument()` plus `toCellPosition()` / `toVirtualPosition()` / `makePositionMapper()`. The document also carries `languageId`, `fileExtension`, `kernelName`, and the configured `pythonPath` so a client can select the right environment (including a conda or uv environment) before starting pyright/pylsp/jedi.
|
|
180
|
+
- The `opencode-ipynb` RPC contract (`opencode-ipynb/rpc`) exposes:
|
|
181
|
+
- `document({ filePath })` → `{ filePath, notebookUri, languageId, fileExtension, kernelName, pythonPath, text, sanitizedText, cells }`
|
|
182
|
+
- `changed({ filePath })` → emitted after tools that modify the notebook (`ipynb_edit`, cell insert/delete/move, `ipynb_clean`, output clearing, and `ipynb_run` when `save` is not `false`).
|
|
183
|
+
|
|
184
|
+
The RPC document is client-facing and is not routed through model tool permissions. A third-party server plugin can subscribe to `changed`, call `document`, and feed `sanitizedText` to pyright/jedi (`text` is the raw concatenation; `sanitizedText` blanks IPython magics and `?`/`!!` help syntax). The per-cell `text`/`uri` fields are a starting point for an LSP 3.17 notebook client, which remains responsible for notebook/cell versions and stable cell identity.
|
|
185
|
+
|
|
186
|
+
The plugin also ships a small built-in consumer so diagnostics are useful without a third-party plugin:
|
|
187
|
+
|
|
188
|
+
- After code-changing tools (`ipynb_edit`, cell insert/delete/move), it runs pyright on the virtual document for Python notebooks and appends mapped errors to the tool result in the same wrapper shape used by `opencode-v2-lsp-support` (`LSP errors detected ... <diagnostics file=...>`). The inner error lines add `[cell N, line L:C]`; `opencode-v2-lsp-support` does not parse blocks produced by other plugins.
|
|
189
|
+
- `ipynb_lsp` runs the same check on demand.
|
|
190
|
+
- Non-Python notebooks are left alone; missing pyright is skipped silently, while timeout/invalid-output is reported explicitly.
|
|
191
|
+
- Set `lspDiagnostics: false` to disable the automatic pass, or `pyrightPath` to point at a specific executable. Missing pyright is ignored; the notebook tools keep working.
|
|
192
|
+
|
|
193
|
+
### Per-cell navigation with `opencode-v2-lsp-support`
|
|
194
|
+
|
|
195
|
+
OpenCode 2 has no native LSP runtime; the [`opencode-v2-lsp-support`](https://github.com/christensenjairus/opencode-v2-lsp-support) plugin provides the `lsp` tool and its servers. To use hover, go-to-definition, find-references, or document symbols on a notebook cell, materialize the notebook's virtual document:
|
|
196
|
+
|
|
197
|
+
```text
|
|
198
|
+
ipynb_lsp({ filePath: "notebooks/eda.ipynb", operation: "materialize" })
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
It writes a small, visible `.py` sidecar **next to the notebook** (still inside the session directory, which is the root used by `opencode-v2-lsp-support`) and returns the path plus a cell-to-line map. Writing it beside the notebook is what lets pyright resolve sibling imports such as `notebooks/helpers.py`:
|
|
202
|
+
|
|
203
|
+
```text
|
|
204
|
+
Virtual Python document: /project/notebooks/opencode-ipynb-lsp-4f2c1a9b7d3e5f60.py
|
|
205
|
+
Call the lsp tool from opencode-v2-lsp-support with this path. Positions are 1-based.
|
|
206
|
+
Cell map:
|
|
207
|
+
- cell 0 (code): lines 1-8
|
|
208
|
+
- cell 1 (code): lines 9-12
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Then call the LSP plugin's `lsp` tool with that path and a 1-based line/character from the map:
|
|
212
|
+
|
|
213
|
+
```text
|
|
214
|
+
lsp({ operation: "hover", path: "/project/notebooks/opencode-ipynb-lsp-4f2c1a9b7d3e5f60.py", line: 10, character: 12 })
|
|
215
|
+
lsp({ operation: "goToDefinition", path: "...", line: 10, character: 12 })
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
The result is a normal LSP location (for the virtual file, e.g. `opencode-ipynb-lsp-4f2c1a9b7d3e5f60.py:10:5`); use the cell map to report it as `[cell 1, line 2:5]`. Coordinate contract: tool `cellIndex` is 0-based; the external `lsp` tool's line/character are 1-based; `metadata.notebookDiagnostics` and RPC cells are 0-based LSP positions; the `metadata.cells` start/end lines from `materialize` are 1-based for the external tool (cell indices remain 0-based). The same works for `findReferences`, `documentSymbol`, and the other operations supported by that plugin. The cell map contains code cells only. Materialized files are refreshed automatically after plugin notebook edits (`ipynb_*`); edits made outside the plugin require re-running `materialize`. `ipynb_edit` changes that add or remove source lines, and `ipynb_cell_insert`, `ipynb_cell_delete`, or `ipynb_cell_move`, shift code-cell line numbers. Re-run `materialize` after any such edit if you need an updated cell map. Sidecars are removed when the plugin unloads, so run `materialize` and the `lsp` calls in the same session. Add `opencode-ipynb-lsp-*.py` to `.gitignore` (this repository already does).
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
import { NotebookRpc } from "opencode-ipynb/rpc"
|
|
222
|
+
|
|
223
|
+
export default {
|
|
224
|
+
id: "my-notebook-lsp",
|
|
225
|
+
async setup(ctx: any) {
|
|
226
|
+
const notebook = ctx.rpc(NotebookRpc)
|
|
227
|
+
notebook.events.on("changed", async (event) => {
|
|
228
|
+
const doc = await notebook.document({ filePath: event.data.filePath })
|
|
229
|
+
// Analyze doc.sanitizedText as a virtual .py file, then map diagnostics back with
|
|
230
|
+
// the exported position helpers; or use doc.cells with notebook sync.
|
|
231
|
+
})
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Conda itself does not provide a notebook language server. `conda-lsp`/YAML language servers target conda/YAML files, not Python cells. Use conda or uv to select the interpreter (`pythonPath`/`kernelName`) and a Python language server for the code. Do not add `.ipynb` to pyright's `extensions`: pyright must receive the virtual `.py` text, not the notebook JSON.
|
|
133
237
|
|
|
134
|
-
|
|
238
|
+
Known limitations of the virtual-document model: the whole notebook is re-analyzed when any cell changes; Python-bodied cell magics (`%%time`, `%%capture`) keep their body, while shell/non-Python cell magics are blanked; shell assignment forms (`x = !ls`) are not analyzed; top-level `await` and kernel-only state are not understood by static servers; diagnostics may differ from runtime behavior.
|
|
135
239
|
|
|
136
240
|
## Python execution
|
|
137
241
|
|
|
@@ -140,7 +244,7 @@ The plugin **never installs Python dependencies automatically**. Running `ipynb_
|
|
|
140
244
|
### Preferred: `uv`
|
|
141
245
|
|
|
142
246
|
```bash
|
|
143
|
-
uv pip install nbformat nbclient jupyter_client ipykernel
|
|
247
|
+
uv pip install pip nbformat nbclient jupyter_client ipykernel
|
|
144
248
|
python -m ipykernel install --user
|
|
145
249
|
```
|
|
146
250
|
|
|
@@ -161,33 +265,38 @@ conda install -c conda-forge nbformat nbclient jupyter_client ipykernel
|
|
|
161
265
|
|
|
162
266
|
### Pointing the plugin at a specific Python
|
|
163
267
|
|
|
164
|
-
OpenCode may use a different Python interpreter than the one in your terminal.
|
|
268
|
+
OpenCode may use a different Python interpreter than the one in your terminal. The environment variable takes precedence over plugin options; the PATH fallback is used only when neither sets an interpreter. The sections below are ordered from configuration to fallback:
|
|
165
269
|
|
|
166
270
|
1. Plugin options (in `opencode.json`):
|
|
167
271
|
|
|
168
272
|
```json
|
|
169
273
|
{
|
|
170
|
-
"
|
|
171
|
-
|
|
172
|
-
"opencode-ipynb",
|
|
173
|
-
{
|
|
174
|
-
"pythonPath": "
|
|
274
|
+
"plugins": [
|
|
275
|
+
{
|
|
276
|
+
"package": "/absolute/path/to/opencode-ipynb",
|
|
277
|
+
"options": {
|
|
278
|
+
"pythonPath": "/home/gabriel/.venv/bin/python",
|
|
279
|
+
"helperRelativePath": "python/ipynb_runner.py",
|
|
175
280
|
"preferUv": true,
|
|
176
281
|
"defaultTimeoutMs": 120000,
|
|
177
282
|
"defaultMaxOutputChars": 6000,
|
|
178
283
|
"warmKernel": false,
|
|
179
284
|
"allowOutsideWorktree": false
|
|
180
285
|
}
|
|
181
|
-
|
|
286
|
+
}
|
|
182
287
|
]
|
|
183
288
|
}
|
|
184
289
|
```
|
|
185
290
|
|
|
186
|
-
- `pythonPath` (string): absolute path to a Python interpreter.
|
|
291
|
+
- `pythonPath` (string): absolute path to a Python interpreter, or a bare name resolved through `PATH`. Path-like relative values are rejected so the permission resource and the spawned executable cannot diverge.
|
|
292
|
+
- `helperRelativePath` (string, default `python/ipynb_runner.py`): helper path relative to the plugin package, or an absolute path. It is deliberately never resolved from the project cwd, so a repository cannot shadow the shipped helper.
|
|
187
293
|
- `preferUv` (boolean, default `true`): the doctor and the Python service prefer `uv pip install` over `pip install` in their suggestions.
|
|
188
294
|
- `defaultTimeoutMs` (number, default `120000`): timeout in milliseconds for `ipynb_run`.
|
|
189
|
-
- `defaultMaxOutputChars` (number, default `6000`): fallback for `ipynb_read
|
|
295
|
+
- `defaultMaxOutputChars` (number, default `6000`): fallback for `ipynb_read`, `ipynb_outputs read`, and `ipynb_run` when the user does not pass `maxOutputChars`.
|
|
190
296
|
- `warmKernel` (boolean, default `false`): keep a long-lived Python subprocess per notebook path for faster repeated `ipynb_run mode=all` / `mode=cell` calls. Manage it with `ipynb_kernel`.
|
|
297
|
+
- `lspDiagnostics` (boolean, default `true`): after `ipynb_edit`, `ipynb_cell_insert`, `ipynb_cell_delete`, or `ipynb_cell_move`, run pyright on the notebook's virtual Python document and append errors to the tool result. Set `false` to disable the extra pass.
|
|
298
|
+
- `pyrightPath` (string, default `pyright`): pyright executable for the diagnostics pass. Use an absolute path if pyright is not on `PATH`.
|
|
299
|
+
- `diagnosticsTimeoutMs` (number, default `15000`): timeout for the diagnostics pass.
|
|
191
300
|
- `allowOutsideWorktree` (boolean, default `false`): power-user escape hatch — when `true`, the plugin will read and write `.ipynb` files outside the OpenCode worktree. Leave at `false` unless you know why you need it.
|
|
192
301
|
|
|
193
302
|
2. Environment variables (the shell wins over plugin options):
|
|
@@ -197,9 +306,9 @@ OpenCode may use a different Python interpreter than the one in your terminal. T
|
|
|
197
306
|
OPENCODE_IPYNB_OPTIONS='{"pythonPath":"/usr/bin/python3","defaultMaxOutputChars":4000}' opencode
|
|
198
307
|
```
|
|
199
308
|
|
|
200
|
-
`OPENCODE_IPYNB_PYTHON` overrides `
|
|
309
|
+
`OPENCODE_IPYNB_PYTHON` overrides the plugin `pythonPath` option only. `OPENCODE_IPYNB_OPTIONS` overrides the whole plugin options object (a JSON object validated by the same schema). Both are process-level overrides, so prefer the `plugins` object form when you only want to configure one project.
|
|
201
310
|
|
|
202
|
-
3. PATH fallback: the plugin
|
|
311
|
+
3. PATH fallback: the plugin uses the first `python` if present, otherwise `python3`. It does not retry after a broken interpreter, so every spawned interpreter is covered by the shell permission request. Path-like `pythonPath` values must be absolute; bare names are resolved through PATH.
|
|
203
312
|
|
|
204
313
|
### Diagnose first
|
|
205
314
|
|
|
@@ -215,8 +324,9 @@ It reports the selected interpreter, every Jupyter dependency (`[ok]` / `[missin
|
|
|
215
324
|
|
|
216
325
|
- Python execution depends on the user's local Python/Jupyter environment. The plugin diagnoses missing packages but never installs them.
|
|
217
326
|
- Warm kernels are intentionally limited to `ipynb_run mode=all` and `mode=cell`; `range`, `from`, and `env` use one-shot helper processes.
|
|
218
|
-
- Large notebooks and rich outputs are truncated in tool responses to protect context. When `ipynb_run save=true
|
|
219
|
-
- `allowOutsideWorktree` is a power-user escape hatch. Keep it disabled unless you explicitly need cross-worktree notebook access.
|
|
327
|
+
- Large notebooks and rich outputs are truncated in tool responses to protect context. When `ipynb_run save=true` completes successfully, the executed code cells write their nbformat outputs to disk; a failed run returns its error without writing partial results.
|
|
328
|
+
- `allowOutsideWorktree` is a power-user escape hatch. Keep it disabled unless you explicitly need cross-worktree notebook access. Enabling it also bypasses the host's `external_directory` deny rules for plugin tools; restrict the plugin tools themselves if that matters.
|
|
329
|
+
- `ipynb_run` `workingDirectory` controls the one-shot helper process, not the notebook cell cwd; nbclient always runs cells in the notebook directory. Warm kernels reject any non-undefined `workingDirectory`.
|
|
220
330
|
|
|
221
331
|
## Examples
|
|
222
332
|
|
|
@@ -234,26 +344,28 @@ expected output.
|
|
|
234
344
|
|
|
235
345
|
## Release
|
|
236
346
|
|
|
237
|
-
The published npm tarball contains only the runtime: `dist/`, `python/ipynb_runner.py`, `python/requirements.txt`, `README.md`, and `LICENSE`. Internal developer docs, helper dev scripts, and `.github/` workflows are excluded
|
|
347
|
+
The published npm tarball contains only the runtime: `dist/`, `server.js`, `python/ipynb_runner.py`, `python/requirements.txt`, `README.md`, `CHANGELOG.md`, and `LICENSE`. Internal developer docs, helper dev scripts, and `.github/` workflows are excluded by the `files` whitelist in `package.json` (with `.npmignore` as a second guard). `AGENTS.md` and `TODO.md` are local and gitignored; `docs/` is tracked for contributors and is not shipped to npm. Contributors track their work through GitHub Issues and Discussions.
|
|
238
348
|
|
|
239
349
|
Cut a release by tagging the commit and pushing the tag, then publish it on GitHub — the workflow runs only on the `published` release event:
|
|
240
350
|
|
|
241
351
|
```bash
|
|
242
|
-
git tag
|
|
352
|
+
git tag vX.Y.Z && git push --tags
|
|
243
353
|
```
|
|
244
354
|
|
|
245
|
-
Then create a GitHub release at https://github.com/Restodecoca/opencode-ipynb/releases/new pointing at `
|
|
355
|
+
Then create a GitHub release at https://github.com/Restodecoca/opencode-ipynb/releases/new pointing at `vX.Y.Z`. The CI runs `bun run typecheck`, `bun run typecheck:tests`, `bun test`, and `bun run build` before `npm publish --provenance --access public`. The repository must have a single secret configured: `NPM_TOKEN` (an npm automation token with publish rights for the package name in `package.json`).
|
|
246
356
|
|
|
247
357
|
Before publishing, run a local package check:
|
|
248
358
|
|
|
249
359
|
```bash
|
|
250
360
|
bun run typecheck
|
|
361
|
+
bun run typecheck:tests
|
|
251
362
|
bun test
|
|
363
|
+
bun run test:coverage
|
|
252
364
|
bun run build
|
|
253
365
|
npm pack --dry-run
|
|
254
366
|
```
|
|
255
367
|
|
|
256
|
-
The
|
|
368
|
+
The `2.0.0` release is the V2-only line. The npm `latest` tag currently points at the V1 `0.1.2` package; publish `2.0.0` before advertising the package name as a V2 install. If you publish under a scope instead, update `package.json`, the install snippet, and this release tag convention together.
|
|
257
369
|
|
|
258
370
|
## Effect LSP setup (for development)
|
|
259
371
|
|
|
@@ -284,13 +396,14 @@ The project does NOT add this as a `prepare` script. Patch only when you want it
|
|
|
284
396
|
|
|
285
397
|
For VS Code, Cursor, Zed or NVim, make sure the editor uses the workspace TypeScript (not the bundled one). In VS Code / Cursor, open a `.ts` file, click the TypeScript version in the status bar, and select **Use Workspace Version**.
|
|
286
398
|
|
|
287
|
-
The
|
|
399
|
+
The `opencode-v2-lsp-support` TypeScript LSP also picks up the workspace TypeScript and therefore respects the `@effect/language-service` plugin. A minimal `opencode.json` in the project root enables it:
|
|
288
400
|
|
|
289
401
|
```json
|
|
290
402
|
{
|
|
291
403
|
"$schema": "https://opencode.ai/config.json",
|
|
292
404
|
"lsp": {
|
|
293
405
|
"typescript": {
|
|
406
|
+
"command": ["typescript-language-server", "--stdio"],
|
|
294
407
|
"extensions": [".ts", ".tsx", ".mts", ".cts"]
|
|
295
408
|
}
|
|
296
409
|
}
|
|
@@ -302,6 +415,7 @@ The OpenCode TypeScript LSP (built-in) also picks up the workspace TypeScript an
|
|
|
302
415
|
```bash
|
|
303
416
|
bun install
|
|
304
417
|
bun run typecheck
|
|
418
|
+
bun run typecheck:tests
|
|
305
419
|
bun test
|
|
306
420
|
bun run build
|
|
307
421
|
```
|
|
@@ -309,9 +423,19 @@ bun run build
|
|
|
309
423
|
Layout:
|
|
310
424
|
|
|
311
425
|
```
|
|
426
|
+
server.js # V2 local-directory entrypoint (re-exports dist/index.js)
|
|
312
427
|
src/
|
|
313
428
|
index.ts # re-exports the plugin
|
|
314
|
-
plugin.ts #
|
|
429
|
+
plugin.ts # V2 lifecycle: setup(), RPC, hook install, cleanup
|
|
430
|
+
plugin-v2.ts # V2 adapter: JSON Schema inputs, permission.assert, result mapping
|
|
431
|
+
plugin-options.ts # per-instance options + env precedence
|
|
432
|
+
registrations.ts # tool definitions + permission names
|
|
433
|
+
notebook-hooks.ts # pure changed/no-op rules and result helpers
|
|
434
|
+
notebook-diagnostics.ts # pyright virtual-document diagnostics + LSP metadata
|
|
435
|
+
virtual-materialize.ts # safe notebook-adjacent sidecar writer/cleanup
|
|
436
|
+
lsp.ts # virtual notebook document + position mapping for LSPs
|
|
437
|
+
rpc.ts # public RPC contract (document method, changed event)
|
|
438
|
+
tool.ts # internal zod tool contract shared by the 14 tool implementations
|
|
315
439
|
domain/ # zod schemas + types for cells, outputs, execution
|
|
316
440
|
services/ # Effect-style services (Path, Permission, File, ...)
|
|
317
441
|
format/ # markdown / output / diagnostic / export formatters
|
|
@@ -319,10 +443,36 @@ src/
|
|
|
319
443
|
utils/ # limits, paths, mime, truncate, json helpers
|
|
320
444
|
python/
|
|
321
445
|
ipynb_runner.py # JSON-stdin/stdout runner using nbformat + nbclient
|
|
322
|
-
requirements.txt
|
|
446
|
+
requirements.txt # runtime execution deps
|
|
447
|
+
requirements-test.txt # CI/test deps (numpy, matplotlib, scikit-learn)
|
|
323
448
|
test/
|
|
324
449
|
fixtures/ # simple, outputs, error, images
|
|
325
450
|
unit/ # bun:test suites
|
|
451
|
+
docs/
|
|
452
|
+
architecture.md # module map, lifecycle, LSP and file-safety invariants
|
|
453
|
+
contributing.md # setup, commands, adding tools, review/release checklist
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
The plugin targets `@opencode/plugin` 2.2.x (tested with 2.2.2). It is V2-only; there is no V1 `server()` entrypoint.
|
|
457
|
+
|
|
458
|
+
Architecture and contribution notes:
|
|
459
|
+
|
|
460
|
+
- [Architecture](https://github.com/Restodecoca/opencode-ipynb/blob/main/docs/architecture.md)
|
|
461
|
+
- [Contributing](https://github.com/Restodecoca/opencode-ipynb/blob/main/docs/contributing.md)
|
|
462
|
+
- [`opencode.example.jsonc`](https://github.com/Restodecoca/opencode-ipynb/blob/main/opencode.example.jsonc) is the versioned, machine-independent local config example. The real `opencode.jsonc` is intentionally not versioned because it contains machine-specific paths.
|
|
463
|
+
|
|
464
|
+
### Development environment on WSL
|
|
465
|
+
|
|
466
|
+
Use a native Linux Bun inside WSL, not the Windows npm shim. Running `bun install` through Windows Bun against a WSL path can corrupt `node_modules` or fail to replace `bun.lock`.
|
|
467
|
+
|
|
468
|
+
```bash
|
|
469
|
+
curl -fsSL https://bun.sh/install | bash
|
|
470
|
+
export PATH="$HOME/.bun/bin:$PATH"
|
|
471
|
+
|
|
472
|
+
uv venv .venv
|
|
473
|
+
uv pip install --python .venv/bin/python pip -r python/requirements-test.txt
|
|
474
|
+
.venv/bin/python -m ipykernel install --user --name python3
|
|
475
|
+
PATH="$PWD/.venv/bin:$PATH" bun test
|
|
326
476
|
```
|
|
327
477
|
|
|
328
478
|
## License
|
package/dist/domain/cell.d.ts
CHANGED
|
@@ -25,6 +25,7 @@ export declare const RawCellSchema: z.ZodObject<{
|
|
|
25
25
|
id: z.ZodOptional<z.ZodString>;
|
|
26
26
|
metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
27
27
|
source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
|
|
28
|
+
attachments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
28
29
|
}, z.core.$loose>;
|
|
29
30
|
export type RawCellRaw = z.infer<typeof RawCellSchema>;
|
|
30
31
|
export declare const CellSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
@@ -45,6 +46,6 @@ export declare const CellSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
|
45
46
|
id: z.ZodOptional<z.ZodString>;
|
|
46
47
|
metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
47
48
|
source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
|
|
49
|
+
attachments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
48
50
|
}, z.core.$loose>]>;
|
|
49
51
|
export type CellRaw = z.infer<typeof CellSchema>;
|
|
50
|
-
//# sourceMappingURL=cell.d.ts.map
|
package/dist/domain/errors.d.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
export type NotebookErrorKind = "NotebookNotFound" | "NotebookParse" | "NotebookValidation" | "CellIndexOutOfBounds" | "NotebookWrite" | "NotebookExecution" | "PythonRunner" | "PermissionDenied" | "OutputTooLarge" | "PathOutsideWorktree" | "NotebookNotImplemented" | "NotebookAttachment" | "LockError";
|
|
1
|
+
export type NotebookErrorKind = "NotebookNotFound" | "NotebookParse" | "NotebookValidation" | "CellIndexOutOfBounds" | "NotebookWrite" | "NotebookExecution" | "PythonRunner" | "PermissionDenied" | "PathOutsideWorktree" | "NotebookNotImplemented";
|
|
3
2
|
declare const NotebookNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
4
3
|
readonly _tag: "NotebookNotFound";
|
|
5
4
|
} & Readonly<A>;
|
|
@@ -66,15 +65,7 @@ declare const PermissionDeniedError_base: new <A extends Record<string, any> = {
|
|
|
66
65
|
export declare class PermissionDeniedError extends PermissionDeniedError_base<{
|
|
67
66
|
readonly message: string;
|
|
68
67
|
readonly action: string;
|
|
69
|
-
|
|
70
|
-
}
|
|
71
|
-
declare const OutputTooLargeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
72
|
-
readonly _tag: "OutputTooLarge";
|
|
73
|
-
} & Readonly<A>;
|
|
74
|
-
export declare class OutputTooLargeError extends OutputTooLargeError_base<{
|
|
75
|
-
readonly message: string;
|
|
76
|
-
readonly cellIndex: number;
|
|
77
|
-
readonly bytes: number;
|
|
68
|
+
readonly cause?: unknown;
|
|
78
69
|
}> {
|
|
79
70
|
}
|
|
80
71
|
declare const PathOutsideWorktreeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
@@ -94,26 +85,7 @@ export declare class NotebookNotImplementedError extends NotebookNotImplementedE
|
|
|
94
85
|
readonly feature: string;
|
|
95
86
|
}> {
|
|
96
87
|
}
|
|
97
|
-
|
|
98
|
-
readonly _tag: "NotebookAttachment";
|
|
99
|
-
} & Readonly<A>;
|
|
100
|
-
export declare class NotebookAttachmentError extends NotebookAttachmentError_base<{
|
|
101
|
-
readonly message: string;
|
|
102
|
-
readonly mime: string;
|
|
103
|
-
}> {
|
|
104
|
-
}
|
|
105
|
-
declare const LockError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
106
|
-
readonly _tag: "LockError";
|
|
107
|
-
} & Readonly<A>;
|
|
108
|
-
export declare class LockError extends LockError_base<{
|
|
109
|
-
readonly message: string;
|
|
110
|
-
readonly filePath: string;
|
|
111
|
-
readonly cause: string;
|
|
112
|
-
}> {
|
|
113
|
-
}
|
|
114
|
-
export type NotebookError = NotebookNotFoundError | NotebookParseError | NotebookValidationError | CellIndexOutOfBoundsError | NotebookWriteError | NotebookExecutionError | PythonRunnerError | PermissionDeniedError | OutputTooLargeError | PathOutsideWorktreeError | NotebookNotImplementedError | NotebookAttachmentError | LockError;
|
|
88
|
+
export type NotebookError = NotebookNotFoundError | NotebookParseError | NotebookValidationError | CellIndexOutOfBoundsError | NotebookWriteError | NotebookExecutionError | PythonRunnerError | PermissionDeniedError | PathOutsideWorktreeError | NotebookNotImplementedError;
|
|
115
89
|
export declare const isNotebookError: (u: unknown) => u is NotebookError;
|
|
116
90
|
export declare const errorToMessage: (e: unknown) => string;
|
|
117
|
-
export declare const failWith: <E extends NotebookError>(e: E) => Effect.Effect<never, E, never>;
|
|
118
91
|
export {};
|
|
119
|
-
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -18,6 +18,8 @@ export declare const RunRequestSchema: z.ZodObject<{
|
|
|
18
18
|
kernel: z.ZodOptional<z.ZodString>;
|
|
19
19
|
timeoutMs: z.ZodOptional<z.ZodNumber>;
|
|
20
20
|
save: z.ZodOptional<z.ZodBoolean>;
|
|
21
|
+
includeRawOutputs: z.ZodOptional<z.ZodBoolean>;
|
|
22
|
+
kernelEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
21
23
|
workingDirectory: z.ZodOptional<z.ZodString>;
|
|
22
24
|
maxOutputChars: z.ZodOptional<z.ZodNumber>;
|
|
23
25
|
}, z.core.$strip>;
|
|
@@ -35,6 +37,7 @@ export declare const CellExecutionSummarySchema: z.ZodObject<{
|
|
|
35
37
|
sizeBytes: z.ZodNumber;
|
|
36
38
|
}, z.core.$strip>>>;
|
|
37
39
|
rawOutputs: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
|
|
40
|
+
rawOutputsOmitted: z.ZodOptional<z.ZodBoolean>;
|
|
38
41
|
errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
39
42
|
ename: z.ZodString;
|
|
40
43
|
evalue: z.ZodString;
|
|
@@ -60,6 +63,7 @@ export declare const RunResponseSchema: z.ZodObject<{
|
|
|
60
63
|
sizeBytes: z.ZodNumber;
|
|
61
64
|
}, z.core.$strip>>>;
|
|
62
65
|
rawOutputs: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
|
|
66
|
+
rawOutputsOmitted: z.ZodOptional<z.ZodBoolean>;
|
|
63
67
|
errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
64
68
|
ename: z.ZodString;
|
|
65
69
|
evalue: z.ZodString;
|
|
@@ -84,4 +88,3 @@ export declare const RunResponseSchema: z.ZodObject<{
|
|
|
84
88
|
}, z.core.$strip>>;
|
|
85
89
|
}, z.core.$strip>;
|
|
86
90
|
export type RunResponse = z.infer<typeof RunResponseSchema>;
|
|
87
|
-
//# sourceMappingURL=execution.d.ts.map
|
|
@@ -57,9 +57,9 @@ export declare const NotebookSchema: z.ZodObject<{
|
|
|
57
57
|
id: z.ZodOptional<z.ZodString>;
|
|
58
58
|
metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
59
59
|
source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
|
|
60
|
+
attachments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
60
61
|
}, z.core.$loose>]>>;
|
|
61
62
|
}, z.core.$loose>;
|
|
62
63
|
export type NotebookRaw = z.infer<typeof NotebookSchema>;
|
|
63
64
|
export declare const normalizeSource: (source: z.infer<typeof SourceSchema>) => string;
|
|
64
65
|
export declare const cellSource: (cell: CellRaw) => string;
|
|
65
|
-
//# sourceMappingURL=notebook.d.ts.map
|
package/dist/domain/output.d.ts
CHANGED
|
@@ -47,4 +47,3 @@ export declare const CellOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
|
47
47
|
export type CellOutputRaw = z.infer<typeof CellOutputSchema>;
|
|
48
48
|
export type CellOutputKind = "stream" | "display_data" | "execute_result" | "error" | "unknown";
|
|
49
49
|
export declare const detectOutputKind: (raw: Record<string, unknown>) => CellOutputKind;
|
|
50
|
-
//# sourceMappingURL=output.d.ts.map
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { CellRaw } from "../domain/cell.js";
|
|
2
2
|
import { type OutputFormatOptions } from "./outputs.js";
|
|
3
|
-
import type { ToolAttachment } from "
|
|
3
|
+
import type { ToolAttachment } from "../tool.js";
|
|
4
4
|
export interface MarkdownReadOptions {
|
|
5
5
|
readonly includeOutputs: boolean;
|
|
6
6
|
readonly includeErrors: boolean;
|
|
@@ -16,4 +16,3 @@ export interface FormattedCell {
|
|
|
16
16
|
}
|
|
17
17
|
export declare const formatCellMarkdown: (cell: CellRaw, index: number, optsInput?: Partial<MarkdownReadOptions>) => string;
|
|
18
18
|
export declare const formatCellMarkdownDetailed: (cell: CellRaw, index: number, optsInput?: Partial<MarkdownReadOptions>) => Promise<FormattedCell>;
|
|
19
|
-
//# sourceMappingURL=markdown.d.ts.map
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export interface MarkdownCellInput {
|
|
2
2
|
readonly cell_type: "code" | "markdown" | "raw";
|
|
3
3
|
readonly source: string;
|
|
4
|
+
/** Rendered image links appended after a raw-cell fence. */
|
|
5
|
+
readonly attachments?: ReadonlyArray<string> | undefined;
|
|
4
6
|
}
|
|
5
7
|
export interface FormatMarkdownOptions {
|
|
6
8
|
readonly includeOutputs?: boolean | undefined;
|
|
@@ -17,4 +19,3 @@ export declare const formatNotebookAsPython: (params: {
|
|
|
17
19
|
cells: ReadonlyArray<MarkdownCellInput>;
|
|
18
20
|
header?: string;
|
|
19
21
|
}) => string;
|
|
20
|
-
//# sourceMappingURL=diff.d.ts.map
|