opencode-ipynb 0.1.1 → 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.
Files changed (126) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.md +191 -41
  3. package/dist/domain/cell.d.ts +2 -1
  4. package/dist/domain/errors.d.ts +3 -31
  5. package/dist/domain/execution.d.ts +4 -1
  6. package/dist/domain/notebook.d.ts +1 -1
  7. package/dist/domain/output.d.ts +0 -1
  8. package/dist/format/diagnostics.d.ts +0 -1
  9. package/dist/format/markdown.d.ts +1 -4
  10. package/dist/format/{diff.d.ts → notebook.d.ts} +2 -1
  11. package/dist/format/outputs.d.ts +3 -4
  12. package/dist/index.d.ts +3 -1
  13. package/dist/index.js +7312 -26442
  14. package/dist/load-document.d.ts +16 -0
  15. package/dist/lsp.d.ts +97 -0
  16. package/dist/lsp.js +129 -0
  17. package/dist/notebook-diagnostics.d.ts +55 -0
  18. package/dist/notebook-hooks.d.ts +23 -0
  19. package/dist/plugin-options.d.ts +4 -1
  20. package/dist/plugin-v2.d.ts +35 -0
  21. package/dist/plugin.d.ts +2 -3
  22. package/dist/registrations.d.ts +5 -0
  23. package/dist/rpc.d.ts +141 -0
  24. package/dist/rpc.js +84 -0
  25. package/dist/services/KernelManager.d.ts +36 -0
  26. package/dist/services/NotebookCleanService.d.ts +3 -7
  27. package/dist/services/NotebookEditService.d.ts +6 -12
  28. package/dist/services/NotebookExecutionService.d.ts +15 -11
  29. package/dist/services/NotebookExportService.d.ts +3 -7
  30. package/dist/services/NotebookFileService.d.ts +19 -13
  31. package/dist/services/NotebookInspectService.d.ts +15 -14
  32. package/dist/services/NotebookOutputService.d.ts +4 -10
  33. package/dist/services/NotebookReadService.d.ts +4 -10
  34. package/dist/services/PathService.d.ts +5 -7
  35. package/dist/services/PermissionService.d.ts +6 -8
  36. package/dist/services/PythonService.d.ts +23 -42
  37. package/dist/services/index.d.ts +22 -29
  38. package/dist/services/revision.d.ts +15 -0
  39. package/dist/tool.d.ts +66 -0
  40. package/dist/tools/_readPermission.d.ts +8 -0
  41. package/dist/tools/_resolveOptions.d.ts +13 -2
  42. package/dist/tools/cell_delete.d.ts +4 -13
  43. package/dist/tools/cell_insert.d.ts +10 -21
  44. package/dist/tools/cell_move.d.ts +5 -15
  45. package/dist/tools/clean.d.ts +8 -21
  46. package/dist/tools/doctor.d.ts +3 -11
  47. package/dist/tools/edit.d.ts +10 -21
  48. package/dist/tools/export.d.ts +12 -23
  49. package/dist/tools/inspect.d.ts +7 -19
  50. package/dist/tools/kernel.d.ts +13 -21
  51. package/dist/tools/lsp.d.ts +9 -0
  52. package/dist/tools/outputs.d.ts +15 -29
  53. package/dist/tools/read.d.ts +12 -29
  54. package/dist/tools/repro.d.ts +6 -14
  55. package/dist/tools/run.d.ts +17 -34
  56. package/dist/utils/ansi.d.ts +2 -1
  57. package/dist/utils/atomic-replace.d.ts +6 -0
  58. package/dist/utils/attachments.d.ts +2 -10
  59. package/dist/utils/execution-order.d.ts +8 -0
  60. package/dist/utils/fence.d.ts +2 -0
  61. package/dist/utils/i18n.d.ts +1 -2
  62. package/dist/utils/imports.d.ts +6 -1
  63. package/dist/utils/json.d.ts +0 -1
  64. package/dist/utils/limits.d.ts +12 -2
  65. package/dist/utils/markdown-safe.d.ts +7 -0
  66. package/dist/utils/metadata.d.ts +3 -0
  67. package/dist/utils/mime.d.ts +1 -1
  68. package/dist/utils/paths.d.ts +0 -2
  69. package/dist/utils/truncate.d.ts +0 -1
  70. package/dist/utils/windows.d.ts +4 -0
  71. package/dist/virtual-materialize.d.ts +36 -0
  72. package/package.json +30 -18
  73. package/python/ipynb_runner.py +247 -17
  74. package/python/requirements.txt +5 -4
  75. package/server.js +3 -0
  76. package/dist/domain/cell.d.ts.map +0 -1
  77. package/dist/domain/errors.d.ts.map +0 -1
  78. package/dist/domain/execution.d.ts.map +0 -1
  79. package/dist/domain/notebook.d.ts.map +0 -1
  80. package/dist/domain/output.d.ts.map +0 -1
  81. package/dist/format/diagnostics.d.ts.map +0 -1
  82. package/dist/format/diff.d.ts.map +0 -1
  83. package/dist/format/markdown.d.ts.map +0 -1
  84. package/dist/format/outputs.d.ts.map +0 -1
  85. package/dist/index.d.ts.map +0 -1
  86. package/dist/plugin-options.d.ts.map +0 -1
  87. package/dist/plugin.d.ts.map +0 -1
  88. package/dist/services/DiffService.d.ts +0 -17
  89. package/dist/services/DiffService.d.ts.map +0 -1
  90. package/dist/services/NotebookCleanService.d.ts.map +0 -1
  91. package/dist/services/NotebookEditService.d.ts.map +0 -1
  92. package/dist/services/NotebookExecutionService.d.ts.map +0 -1
  93. package/dist/services/NotebookExportService.d.ts.map +0 -1
  94. package/dist/services/NotebookFileService.d.ts.map +0 -1
  95. package/dist/services/NotebookInspectService.d.ts.map +0 -1
  96. package/dist/services/NotebookOutputService.d.ts.map +0 -1
  97. package/dist/services/NotebookReadService.d.ts.map +0 -1
  98. package/dist/services/PathService.d.ts.map +0 -1
  99. package/dist/services/PermissionService.d.ts.map +0 -1
  100. package/dist/services/PythonService.d.ts.map +0 -1
  101. package/dist/services/index.d.ts.map +0 -1
  102. package/dist/tools/_resolveOptions.d.ts.map +0 -1
  103. package/dist/tools/cell_delete.d.ts.map +0 -1
  104. package/dist/tools/cell_insert.d.ts.map +0 -1
  105. package/dist/tools/cell_move.d.ts.map +0 -1
  106. package/dist/tools/clean.d.ts.map +0 -1
  107. package/dist/tools/doctor.d.ts.map +0 -1
  108. package/dist/tools/edit.d.ts.map +0 -1
  109. package/dist/tools/export.d.ts.map +0 -1
  110. package/dist/tools/inspect.d.ts.map +0 -1
  111. package/dist/tools/kernel.d.ts.map +0 -1
  112. package/dist/tools/outputs.d.ts.map +0 -1
  113. package/dist/tools/read.d.ts.map +0 -1
  114. package/dist/tools/repro.d.ts.map +0 -1
  115. package/dist/tools/run.d.ts.map +0 -1
  116. package/dist/utils/ansi.d.ts.map +0 -1
  117. package/dist/utils/attachments.d.ts.map +0 -1
  118. package/dist/utils/fiber.d.ts +0 -2
  119. package/dist/utils/fiber.d.ts.map +0 -1
  120. package/dist/utils/i18n.d.ts.map +0 -1
  121. package/dist/utils/imports.d.ts.map +0 -1
  122. package/dist/utils/json.d.ts.map +0 -1
  123. package/dist/utils/limits.d.ts.map +0 -1
  124. package/dist/utils/mime.d.ts.map +0 -1
  125. package/dist/utils/paths.d.ts.map +0 -1
  126. 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
- The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode core. It exposes thirteen agent tools that operate on `.ipynb` files with explicit permissions, granular context control, and a strongly-typed [Effect](https://effect.website) runtime internally.
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 must ask permission every time.
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
- After the package is published on npm, add it to your `opencode.json`:
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
- "plugin": ["opencode-ipynb"]
26
+ "plugins": ["/absolute/path/to/opencode-ipynb"]
25
27
  }
26
28
  ```
27
29
 
28
- For local development, point OpenCode at a checkout or built tarball:
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
- "plugin": ["file:./opencode-ipynb"]
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 `"opencode-ipynb"` (or the local path) to your `opencode.json`.
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 textual diff, output clearing policy, permission gate, and per-file lock. |
54
- | `ipynb_cell_insert` | Insert a code/markdown/raw cell before or after a target index. |
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 `ipynb.warmKernel: true` is enabled. |
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 `context.ask` before touching the disk.
120
- - Every execution (`ipynb_run`) calls `context.ask` with rich metadata: file path, mode (`cell` / `range` / `all` / `from`), cell range, save flag, working directory, timeout.
121
- - `PathService` rejects paths that resolve outside of the OpenCode worktree. The lock manager serializes per-file writes to prevent accidental corruption.
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 / base64 are always omitted (you only get a size notice).
130
- - `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap the size of any single response.
131
- - `maxTracebackChars` (default 8 000) caps error tracebacks.
132
- - Every truncation appends `... (truncated, use maxXxx to increase)`.
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
- The relevant constants live in `src/utils/limits.ts`.
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. Three ways to tell the plugin which one to use, in priority order:
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
- "plugin": [
171
- [
172
- "opencode-ipynb",
173
- {
174
- "pythonPath": "C:/Users/Gabriel/miniconda3/envs/data/python.exe",
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` and `ipynb_outputs read` when the user does not pass `maxOutputChars`.
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 `ipynb.pythonPath` only. `OPENCODE_IPYNB_OPTIONS` overrides the whole `ipynb.*` block (a JSON object validated by the same schema as `opencode.json`). These are both set by the plugin on first load if they are not already set in the environment, so an explicit shell value always wins.
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 tries `python`, then `python3`.
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`, full nbformat outputs are preserved on disk.
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 from the npm package via `.npmignore` and are also gitignored so they are not versioned in this repository. Contributors track their work through GitHub Issues and Discussions.
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 v0.1.0 && git push --tags
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 `v0.1.0`. The CI runs `bun run typecheck`, `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`).
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 package name `opencode-ipynb` is currently available on npm. If you publish under a scope instead, update `package.json`, the install snippet, and this release tag convention together.
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 OpenCode TypeScript LSP (built-in) also picks up the workspace TypeScript and therefore respects the `@effect/language-service` plugin. A minimal `opencode.json` in the project root enables it:
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 # Plugin object, registers all 13 tools
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
@@ -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
@@ -1,5 +1,4 @@
1
- import { Effect } from "effect";
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
- declare const NotebookAttachmentError_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 & {
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
@@ -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
@@ -12,4 +12,3 @@ export interface CellInspection {
12
12
  outputSummary: string;
13
13
  }
14
14
  export declare const inspectCell: (cell: CellRaw, index: number) => CellInspection;
15
- //# sourceMappingURL=diagnostics.d.ts.map
@@ -1,7 +1,6 @@
1
1
  import type { CellRaw } from "../domain/cell.js";
2
2
  import { type OutputFormatOptions } from "./outputs.js";
3
- import type { ToolAttachment } from "@opencode-ai/plugin";
4
- import type { SavedAttachment } from "../utils/attachments.js";
3
+ import type { ToolAttachment } from "../tool.js";
5
4
  export interface MarkdownReadOptions {
6
5
  readonly includeOutputs: boolean;
7
6
  readonly includeErrors: boolean;
@@ -14,8 +13,6 @@ export interface MarkdownReadOptions {
14
13
  export interface FormattedCell {
15
14
  readonly rendered: string;
16
15
  readonly attachments: ReadonlyArray<ToolAttachment>;
17
- readonly savedAttachments: ReadonlyArray<SavedAttachment>;
18
16
  }
19
17
  export declare const formatCellMarkdown: (cell: CellRaw, index: number, optsInput?: Partial<MarkdownReadOptions>) => string;
20
18
  export declare const formatCellMarkdownDetailed: (cell: CellRaw, index: number, optsInput?: Partial<MarkdownReadOptions>) => Promise<FormattedCell>;
21
- //# 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