Skip to content

docs(jupyter-live-kernel): document zmq transport fallback and disable_check_xsrf pitfalls - #27283

Closed
upicat wants to merge 1 commit into
NousResearch:mainfrom
upicat:docs/jupyter-live-kernel-websocket-pitfalls
Closed

docs(jupyter-live-kernel): document zmq transport fallback and disable_check_xsrf pitfalls#27283
upicat wants to merge 1 commit into
NousResearch:mainfrom
upicat:docs/jupyter-live-kernel-websocket-pitfalls

Conversation

@upicat

@upicat upicat commented May 17, 2026

Copy link
Copy Markdown
Contributor

What\n\nAdd two pitfalls to the jupyter-live-kernel skill, both encountered when running against a freshly started Jupyter server.\n\n### Pitfall #9 — Force zmq transport when websocket hangs\n\nOn some hosts the websocket reply channel hangs on every execute even though the kernel actually ran (REST shows execution_state=idle and execution_count increments). The symptom from the skill side is the error message:\n\n> Websocket execution may already have reached the kernel, so auto fallback was skipped\n\nThe workaround is to pass --transport zmq so the skill talks to the kernel through jupyter_client directly and sidesteps the broken websocket layer.\n\n### Pitfall #10disable_check_xsrf for REST-only flows\n\nA fresh ServerApp rejects POST /api/sessions with:\n\n> _xsrf argument missing from POST\n\nThe skill drives the server purely over REST, so no browser/cookie ever establishes an XSRF token. The fix is to start the server with --ServerApp.disable_check_xsrf=True.\n\n## Why\n\nBoth failure modes are easy to misdiagnose — pitfall #9 in particular looks like the kernel hung, when in fact only the reply path is broken. Documenting the symptom + the one-flag fix in the same place as the rest of the pitfalls section saves the next user from re-tracing the same investigation.\n\n## Scope\n\nPure docs change to skills/data-science/jupyter-live-kernel/SKILL.md — no code or behavior changes. +11 lines, 0 deletions, 0 lint targets.

…e_check_xsrf pitfalls

Add two pitfalls discovered when running the skill against a fresh
Jupyter server:

- Pitfall NousResearch#9: When the websocket reply channel hangs on every execute
  even though the kernel actually ran (REST shows execution_state=idle
  and execution_count increments), force zmq transport with
  --transport zmq. The zmq transport uses jupyter_client directly and
  sidesteps the broken websocket layer.

- Pitfall NousResearch#10: A fresh ServerApp rejects POST /api/sessions with
  "_xsrf argument missing from POST" unless you start it with
  --ServerApp.disable_check_xsrf=True. Needed for REST-only flows
  where no browser/cookie is establishing the XSRF token.
@cardtest15-coder

This comment was marked as spam.

@alt-glitch alt-glitch added type/docs Documentation improvements P3 Low — cosmetic, nice to have tool/skills Skills system (list, view, manage) labels May 17, 2026
@teknium1

teknium1 commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

Thanks for the focused documentation update. Current main still creates a notebook session through a direct REST POST /api/sessions at skills/data-science/jupyter-live-kernel/SKILL.md:70-76 and has only generic retry guidance for websocket timeouts at skills/data-science/jupyter-live-kernel/SKILL.md:160-161.

The proposed ZMQ guidance matches the helper's current transport behavior: the upstream helper raises the stated unsafe-auto-fallback message at skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py:1072-1077 and dispatches explicit ZMQ execution at :1061-1068. The patch is documentation-only and remains within the bundled skill.

This is an automated hermes-sweeper review.

@teknium1 teknium1 added sweeper:risk-security-boundary Sweeper risk: may affect sandboxing, auth, credentials, or sensitive data sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users labels Jul 13, 2026
@teknium1

Copy link
Copy Markdown
Contributor

Thanks @upicat — both pitfalls are now on main via #70482, which cherry-picked your commit directly so your authorship is preserved in history (a4fa699).

The skill moved and was renamed while your PR was open (skills/data-science/jupyter-live-kernel → optional-skills/data-science/jupyter-notebook, #70431), so a direct merge was no longer possible — the salvage applied your change to the new path and added the regenerated docs page + zh-Hans translation on top. Closing this one; the content is fully landed.

@teknium1 teknium1 closed this Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low — cosmetic, nice to have sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users sweeper:risk-security-boundary Sweeper risk: may affect sandboxing, auth, credentials, or sensitive data tool/skills Skills system (list, view, manage) type/docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants