Skip to content

Fix connect mode with Jupyter Server vanilla (no collaboration packages)#96

Open
andrii-i wants to merge 28 commits into
jupyter-ai-contrib:mainfrom
andrii-i:connect-mode-vanilla-jupyter-server
Open

Fix connect mode with Jupyter Server vanilla (no collaboration packages)#96
andrii-i wants to merge 28 commits into
jupyter-ai-contrib:mainfrom
andrii-i:connect-mode-vanilla-jupyter-server

Conversation

@andrii-i

@andrii-i andrii-i commented Jun 10, 2026

Copy link
Copy Markdown
Collaborator

Fixes #93

Problem

Connect mode requires Y.js infrastructure (FileID API, collaboration room WebSocket) for every remote operation and fails against vanilla jupyter_server with no collaboration packages installed (as seen in CI failures in #91). Vanilla jupyter_server provides everything needed: the kernel WebSocket already delivers all execution outputs (the remote executor currently discards them), and the Contents API reads and writes notebooks.

Changes

  • nb connect probes POST /api/fileid/index, stores ydoc_available in .jupyter/cli.json, prints Mode: direct or Mode: collaborative. GET /api/fileid/id cannot be used as the probe: it 404s for unindexed paths even when the extension is installed, so fresh servers would always probe as vanilla. POST /api/fileid/index is registered by jupyter-server-documents only (verified against all three server types). Ad-hoc --server/--token probes per command, --skip-validation skips the probe.
  • execute_code_kernel_ws() in remote/mod.rs collects outputs from kernel WS messages (stream, execute_result, display_data, error, clear_output), same set as the local executor. Coalesces consecutive same-name streams and defers clear_output(wait=True) until the next output, matching nbclient. Every recv is bounded by the per-cell deadline.
  • websocket.rs negotiates the v1.kernel.websocket.jupyter.org subprotocol and fails fast if not accepted, since the client only speaks v1 binary framing.
  • execute saves the notebook with outputs via PUT /api/contents/{path} when no Y.js backend is present. The notebook is read from the server first, so the write-back is a consistent read-modify-save.
  • cell add/update/delete and output clear share a with_contents_api() read-modify-save helper in common.rs. Results print only after the save succeeds.
  • The pre-idle tokio::select! in the Y.js output loop gained a deadline arm; previously a missed Status(Idle) blocked forever. Same defect Fix execute hang in remote mode #89 fixes, deduplicate on rebase.
  • jupyter-collaboration probes as direct and works through the Contents API path. Full Y.js support for it is Fix connect mode with jupyter-collaboration #95.

Testing

End-to-end against real servers in clean venvs.

Scenario vanilla 2.19.0 jupyter-server-documents 0.2.2 jupyter-collaboration 4.4.1
nb connect mode detected direct collaborative direct
add / update / delete / output clear OK (Contents API) OK (Y.js) OK (Contents API)
execute, error capture, stream coalescing OK OK OK
single-cell re-exec keeps kernel state OK OK OK
ad-hoc --server/--token, --skip-validation OK OK OK

jupyter-server-documents must be tested with a fresh JUPYTER_DATA_DIR: the fileid database is user-global and a stale probe record masks detection bugs.

Merge order

No hard ordering, second to merge rebases:

@andrii-i andrii-i added the enhancement New feature or request label Jun 10, 2026
andrii-i added 22 commits June 10, 2026 11:40
@andrii-i andrii-i marked this pull request as ready for review June 11, 2026 17:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Connect mode fails without jupyter-server-documents or jupyter-collaboration

1 participant