ipykernel/repl support

[jlewi]

We'd like to support ipykernel to provide a full repl that can be reused across cells.

I think there are two key problems on the backend we need to solve

1. Managing ipykernel processes
2. Creating a websockets -> zeroMQ bridge

Managing ipykernel processes

We can already do this today with runme and our existing UI. We just need to create a cell and then execute

python -m ipykernel write_connection_file
python -m ipykernel_launcher -f kernel-12345.json

A kernel is now defined by the tuple (host, kernel_file). So in the webapp we could do something like.

runners.addIPykernel(name, host, kernel_file)

Websocket to ZeroMQ bridge

Runme already manages a websocket connection. The handler is here.

The payload of websockets requests responses is defined in the websockets proto. The message basically consists of

• Metadata identifying the type of request
• Actual payload for the message

So we can add fields to that proto to

• Indicate its an ipykernel message
• The tuple tuple identifying the kernel (host, kernel_file)
• Payload containing the actual Jupyter/Ipykernel message

The kernel_file should be sufficient for the server to route the message to the right ipykernel.
So now the server just needs to use zmq to pass along the messages to the kernel.

I believe the python version of that code is https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernels/connection/channels.py#L445. So we just need an equivalent golang version.

My hunch is we can just point codex at that file and create a go lang version without much problems.

ZeroMQ in GoLang

The biggest issue I see is zmq support in GoLang.
zeromq is implemented in c++.

goczmq - Looks like the official golang bindings but they haven't been updated in quite a while
zmq4 - Looks like a slightly more recent version of bindings for the c++ library
go-zeromq - Pure go implementation of zeromq

I think we should start with go-zeromq because its generally better to avoid CGO if you can.

That said, one of the main challenges with CGO is that you have to distribute libraries which is annoying. In our case though, ipykernel also depends on libzmq so I think we can assume libzmq is already installed on the user's system and basically offload that problem to python/pip or whatever the user is using to install ipython/ipykernel on their machine.

I still think we should start with go-zermoq.

Alternatives

jupyter's kernel_gateway

jupyter's kernel_gateway provides an HTTP server that handles

websockets/REST -> zeromq

It allows you to execute code snippets in a kernel via HTTP protocols so you don't have to speak zeromq directly.

It looks like the heavy-lifting of websockets->zeromq is done in ZMQChannelsWebsocketConnection which is imported from the jupyter-server repo. So it looks like kernel_gateway is just a slimmed down version of the jupyter server to support the minimum API to execute code in a kernel.

In addition to handling websocket -> zeromq it looks like kernel-gateway handles the following gateway concerns

• CORS
• Auth/Identity

Although it looks like this too is functionality imported from jupyter_server

We already have all of this functionality in the runme server. So the only missing piece is ZMQChannelsWebsocketConnection.

I think the existing runme-server is a much better choice for a gateway then kernel_gateway. runme is a golang binary which means we can easily create and distribute statically linked binaries for arbitrary platforms. This makes it super easy to distribute. I'd much rather take on the challenge of porting ZMQChannelsWebsocketConnection to go to the distribution challenges that python creates.

• Porting ZMQChannelsWebsocketConnection is a one time challenge; that we can probably solve with AI
• Dealing with the myriad challenges of python environment setups is going to be an ongoing problem

Our runme server has other services in GoLang e.g.

• Parser Service - JSON <-> Markdown
• ChatKit Handler - ChatKit <-> Responses API
• (Future) Codex Harness interface Use codex app as the agent harness #34

If we introduce kernel_gateway our options are

1. Rewrite everything in python
2. Have two servers and distribute both

Right now we have a monolith architecture and can selective enable/disable services. I think the benefits of this design outweigh the benefits we get from kernel_gateway.

Jupyter Server

Jupyter server architecture diagram

Based on that doc Jupyter server provides the following components

• ServerApp
• Config Manager
• Custom Extensions
• Gateway Server (I think this is the same as kernel_gateway)
• Contents Manager and File Contents Manager
• Session Manager
• Mapping Kernel Manager

I don't think we need/want any of this.

We already have a server that handles basic serving concerns such as Auth and configuration.

We already have a way to manage kernels just by using runme's functionality to start/stop/monitor kernels by executing the relevant python/ps commands.

Contents Manager/File Contents Manger

• For notebooks we want the webapp to talk directly to the storage system (e.g. Google Drive) or the local file system via File System API

Session Manager

• To the extent we need to keep track of sessions I don't think Jupyter's session manager will work for us
• I think we will need to figure out the right way to handle this in light of the way our notebook works
  • e.g. on the web app we keep track of runners and websocket connections
  • The webapp can manage kernels by executing relevant commands on the server

References

• https://github.com/jupyter-server/jupyter_server/blob/main/jupyter_server/services/kernels/connection/channels.py#L445
• How Ipython Works
• Jupyter Messaging Protocol

[jlewi]

@hamelsmu actually I think there's a simpler solution. I think instead of launching and managing ipykernel process we can just manage jupyter server processes.

jupyter server \
  --no-browser 

I think the frontend should still talk to jupyter server via the runme gateway. This way all the gateway concerns (HTTPs certificates, CORS, Auth) can be handled in the runme server. Than the runme server just needs to act as a websockets proxy forwarding the messages along to the jupyter server.

jupyter server can use token based authentication. The frontend can specify the token as part of the runner configuration.

runners.updateJupyterKernel(name, host, port, token)

The frontend can pass along the token and port in the requests and runme can use that to forward to the correct jupyter server process.

[hamelsmu]

@jlewi from Whatsapp yesterday 😆

[hamelsmu]

Investigation & Proposal: ipykernel/REPL Support via Jupyter Server Proxy

Investigation requested by @hamelsmu | Devin session

I did a thorough investigation of all three codebases (runmedev/web, runmedev/runme, jupyter-server/jupyter_server). Here is my analysis and proposed implementation plan.

---

Current Architecture Summary

runmedev/web (Frontend)

• Cell execution flow: CellData.run() -> NotebookData.runCodeCell() -> creates a Streams instance -> opens WebSocket to runner endpoint -> sends ExecuteRequest proto
• Streams class (packages/renderers/src/streams.ts): Manages WebSocket lifecycle with RxJS. Connects to ws://<runnerEndpoint>?id=<streamID>&runID=<runID>, sends/receives protobuf-JSON WebsocketRequest/WebsocketResponse messages.
• Runner management: Runners are configured with (name, endpoint) pairs. Each runner has a WebSocket endpoint URL.
• IPykernel parsing already exists: app/src/lib/ipykernel.ts has maybeParseIPykernelMessage() that detects Jupyter IOPub messages in stdout and routes them to rich output items. CellConsole.tsx uses extractIopubText() to render stream/error messages from ipykernel.

runmedev/runme (Backend - Go)

• WebSocket handler (pkg/agent/runme/stream/handler.go): Upgrades HTTP to WebSocket at /ws?runID=<runID>&id=<streamID>. Creates a Multiplexer per runID.
• Multiplexer (pkg/agent/runme/stream/multiplexer.go): Manages multiple WebSocket connections per run. Routes authenticated WebsocketRequest messages to a Processor, which calls runner.Server.Execute(processor) -- the runner's bidirectional gRPC Execute stream.
• Proto messages (api/proto/runme/stream/v1/websockets.proto): WebsocketRequest has a oneof payload { ExecuteRequest } and WebsocketResponse has oneof payload { ExecuteResponse }. These are the extension points.
• Runner (pkg/agent/runme/runner.go): Wraps runnerv2service.RunnerService. Execute is bidirectional streaming -- sends ExecuteRequest (with ProgramConfig for the command) and receives ExecuteResponse (stdout/stderr/exit_code).

jupyter-server (Reference)

• Kernel REST API (services/kernels/handlers.py):
  • POST /api/kernels -- start a kernel, returns kernel_id
  • GET /api/kernels -- list running kernels
  • DELETE /api/kernels/<kernel_id> -- shutdown kernel
  • POST /api/kernels/<kernel_id>/restart -- restart kernel
  • POST /api/kernels/<kernel_id>/interrupt -- interrupt kernel
• Kernel WebSocket (services/kernels/websocket.py): GET /api/kernels/<kernel_id>/channels?session_id=<sid> -- upgrades to WebSocket. Messages are Jupyter protocol messages with a channel field (shell, iopub, stdin, control).
• ZMQ Bridge (services/kernels/connection/channels.py): ZMQChannelsWebsocketConnection -- the core bridge. handle_incoming_message() deserializes WebSocket messages and routes to the appropriate ZMQ channel. handle_outgoing_message() takes ZMQ messages and sends them back over WebSocket.
• Auth: Token-based -- pass ?token=<token> on WebSocket URL or Authorization: token <token> header.

---

Proposed Approach: Runme as Jupyter Server Proxy

Agreeing with @jlewi's comment -- managing jupyter server processes rather than raw ipykernel is the right call. Jupyter server already handles kernel lifecycle, ZMQ bridging, and the Jupyter messaging protocol. The runme server acts as a WebSocket proxy, forwarding Jupyter protocol messages.

Why This is the Right Approach

1. No Go ZMQ dependency -- jupyter server handles all ZMQ communication
2. Kernel lifecycle for free -- jupyter server manages start/stop/restart/interrupt via REST API
3. Session persistence -- jupyter server maintains kernel state across requests
4. Battle-tested protocol -- the Jupyter messaging protocol is mature and well-documented
5. Minimal changes to runme -- just add a WebSocket proxy path, no new service architecture

---

Implementation Plan

Phase 1: Proto & Backend (runmedev/runme)

1a. Extend WebSocket Proto

Add a new payload variant to websockets.proto:

message JupyterRequest {
  string host = 1;       // jupyter server host (e.g. "localhost")
  uint32 port = 2;       // jupyter server port
  string token = 3;      // jupyter server auth token
  string kernel_id = 4;  // target kernel ID
  string session_id = 5; // jupyter session ID
  bytes data = 6;        // raw Jupyter protocol message (JSON)
}

message JupyterResponse {
  string kernel_id = 1;
  bytes data = 2;         // raw Jupyter protocol message (JSON)
}

message WebsocketRequest {
  oneof payload {
    runme.runner.v2.ExecuteRequest execute_request = 1;
    JupyterRequest jupyter_request = 2;
  }
  // ... existing fields unchanged
}

message WebsocketResponse {
  oneof payload {
    runme.runner.v2.ExecuteResponse execute_response = 1;
    JupyterResponse jupyter_response = 2;
  }
  // ... existing fields unchanged
}

1b. Add Jupyter Proxy in Multiplexer

Create a new JupyterProxy component in pkg/agent/runme/stream/:

pkg/agent/runme/stream/
  jupyter_proxy.go      // NEW: manages WS connections to jupyter servers
  multiplexer.go        // MODIFY: route JupyterRequest to proxy
  handler.go            // MINOR: no changes needed

jupyter_proxy.go responsibilities:

• Maintain a pool of WebSocket connections to jupyter server instances, keyed by (host, port, kernel_id)
• On JupyterRequest: open/reuse a WebSocket to ws://<host>:<port>/api/kernels/<kernel_id>/channels?token=<token>&session_id=<session_id>
• Forward data bytes to the upstream jupyter server WebSocket
• Read responses from jupyter server WebSocket and wrap them in JupyterResponse, broadcast back to the client

Multiplexer changes (multiplexer.go):

• In the process() loop, check req.GetJupyterRequest() in addition to req.GetExecuteRequest()
• Route Jupyter requests to the JupyterProxy instead of the Processor

1c. Jupyter Server Lifecycle Management (via existing Execute)

No new service needed. The frontend can start/manage jupyter server processes using the existing ExecuteRequest mechanism:

jupyter server --no-browser --port=8888 --ServerApp.token=<token>

This runs as a long-lived process managed by the existing runme runner. The frontend gets the PID and can monitor/stop it.

For kernel lifecycle, the runme server can optionally expose thin REST proxy endpoints, or the frontend can embed the kernel management calls inside the Jupyter protocol messages themselves. However, the simplest initial approach is:

• Start kernel: Frontend sends an ExecuteRequest to run curl -X POST http://localhost:<port>/api/kernels?token=<token> -- or we add a small REST proxy endpoint in the runme server
• Better alternative: Add a JupyterKernelManagement RPC or handle it through a simple HTTP proxy route in the runme server that forwards REST calls to jupyter server

Phase 2: Frontend (runmedev/web)

2a. Runner Configuration for Jupyter Kernels

Extend the runner model to support Jupyter kernel connections:

// In runnersManager.ts or similar
interface JupyterKernelConfig {
  host: string;
  port: number;
  token: string;
  kernelId?: string; // assigned after kernel start
}

// User-facing API (via aisre helpers):
// aisre.runners.addJupyterKernel(name, host, port, token)

2b. Extend Streams for Jupyter Messages

The Streams class (packages/renderers/src/streams.ts) currently only handles ExecuteRequest/ExecuteResponse. Extend it to:

1. Add a sendJupyterRequest(msg) method that wraps Jupyter protocol JSON in a WebsocketRequest.jupyter_request
2. In onMessage, detect JupyterResponse payloads and emit them on a new jupyter subject
3. The existing stdout/stderr/exitCode subjects remain for shell execution

2c. Jupyter Cell Execution Path

When a Python cell runs against a Jupyter kernel runner:

1. NotebookData.runCodeCell() detects the runner is a Jupyter kernel type
2. Instead of buildExecuteRequest(), build a Jupyter execute_request message:

   {
     "header": { "msg_id": "...", "msg_type": "execute_request", "session": "..." },
     "parent_header": {},
     "metadata": {},
     "content": { "code": "<cell code>", "silent": false, "store_history": true }
   }

3. Wrap it in JupyterRequest with the kernel connection details
4. Send via Streams.sendJupyterRequest()

2d. Response Handling

The frontend already has infrastructure for parsing Jupyter messages (maybeParseIPykernelMessage in ipykernel.ts, extractIopubText in CellConsole.tsx). For the Jupyter proxy path:

1. JupyterResponse.data contains the raw Jupyter protocol message
2. Parse the message, check msg_type:
   • stream -> route to stdout/stderr subjects (text output from print())
   • execute_result / display_data / update_display_data -> route to rich output items (HTML, images, etc.)
   • error -> route to stderr with traceback
   • status -> track kernel busy/idle state
   • execute_reply -> signals execution complete (like exit_code)
3. The existing bindStreamsToCell and CellConsole already handle most of this via the IOPub parsing

Phase 3: Session & State Management

Kernel Session Persistence

• Each Jupyter kernel maintains state (variables, imports) across execute_request messages -- this is the REPL behavior we want
• The kernel_id acts as the session identifier
• Multiple cells can share the same kernel by using the same (host, port, kernel_id) tuple
• The frontend tracks which kernel each cell is connected to via runner metadata

Multi-cell Kernel Sharing

• When a user creates a "Python kernel" runner, all Python cells using that runner share the same kernel
• Cell execution is serialized by the kernel (jupyter server queues requests on the shell channel)
• The frontend can show kernel state (busy/idle) based on status messages from iopub

---

Sequence Diagram

Frontend (web)          Runme Server (Go)           Jupyter Server (Python)
     |                        |                            |
     |-- WS: JupyterRequest ->|                            |
     |   (code, kernel info)  |                            |
     |                        |-- WS: execute_request ---->|
     |                        |   (to /api/kernels/K/ch)   |
     |                        |                            |-- ZMQ --> ipykernel
     |                        |                            |<- ZMQ -- (iopub msgs)
     |                        |<- WS: stream/result/error -|
     |<- WS: JupyterResponse -|                            |
     |   (iopub messages)     |                            |

---

Implementation Order & Effort Estimates

Step	Description	Repo	Effort
1	Extend websockets.proto with JupyterRequest/JupyterResponse	runme	Small
2	Implement JupyterProxy (WS connection pool to jupyter server)	runme	Medium
3	Modify Multiplexer.process() to route Jupyter messages	runme	Small
4	Add sendJupyterRequest() to Streams class	web	Small
5	Extend runner config model for Jupyter kernels	web	Small
6	Build Jupyter cell execution path in NotebookData	web	Medium
7	Adapt response handling for Jupyter protocol messages	web	Medium
8	Add kernel lifecycle management (start/stop/restart)	both	Medium
9	Multi-cell kernel sharing & state UI	web	Medium

I would suggest starting with steps 1-4 to get a basic end-to-end flow working (send code to a manually-started jupyter server, get output back), then layer on the UX in steps 5-9.

---

Key Risks & Mitigations

1. WebSocket message format mismatch: Jupyter uses its own binary/JSON protocol over WebSocket. The runme proxy just needs to forward raw bytes -- no parsing needed on the Go side. This keeps the Go implementation simple.

2. Connection lifecycle: The proxy needs to handle jupyter server WebSocket disconnects gracefully and reconnect. The existing Streams reconnect logic on the frontend provides a pattern.

3. Kernel startup latency: Starting a jupyter server + kernel takes a few seconds. The UI should show clear loading states. The frontend can pre-start kernels when a runner is configured.

4. Multiple kernels per jupyter server: A single jupyter server can manage multiple kernels. The REST API (POST /api/kernels) returns a kernel_id that identifies which kernel to connect to via the WebSocket channels endpoint.

---

What We Get For Free

• jupyter server handles ZMQ -- no Go ZMQ dependency needed
• Kernel lifecycle -- jupyter server REST API manages start/stop/restart
• Existing IOPub parsing -- ipykernel.ts and CellConsole.tsx already parse Jupyter messages
• Existing WebSocket infrastructure -- Streams class, Multiplexer, proto messages all extensible
• Auth -- runme server handles external auth, jupyter server uses token auth internally

[hamelsmu]

Summary of investigation

• Runme server already has a WebSocket → multiplexer → runner pipeline for ExecuteRequest/ExecuteResponse with auth + run_id/known_id enforcement (Streams + Multiplexer).
• The web client already wraps this protocol (Streams in renderers) and can be extended to send new WebSocket payload types.
• The web app already parses Jupyter IOPub messages, but only from stdout; a native kernel bridge would be more robust.
• Jupyter Server’s ZMQChannelsWebsocketConnection is the reference for how to bridge WebSocket messages to ZMQ channels.

Proposed plan

1. Extend WebsocketRequest/WebsocketResponse proto with a kernel payload:
   • kernel_ref (kernel ID or {host, kernel_file}),
   • channel (shell/iopub/control/stdin),
   • message (Jupyter message fields + optional buffers).
2. Runme server: add a kernel manager
   • Start/stop ipykernel processes (store kernel connection file).
   • Keep a map of active kernels to ZMQ socket sets.
3. Implement Go ZMQ bridge
   • Use ZMQChannelsWebsocketConnection (Jupyter Server) as the blueprint.
   • On incoming WebSocket kernel messages → forward to ZMQ channel.
   • On ZMQ inbound → serialize to WebSocket kernel response.
4. Web frontend
   • Add a kernel stream client (or extend existing Streams) to send kernel payloads.
   • When in kernel mode, send execute_request messages instead of stdin strings.
   • Route IOPub messages directly into notebook outputs (replace stdout parsing fallback).

Prototype suggestion

• Build a small Go test harness that reads a kernel JSON file, sends a single execute_request, and logs iopub results. This validates ZMQ + message serialization early before UI wiring.

[hamelsmu]

Jupyter Integration Investigation Complete

I've completed a thorough investigation of the three codebases and created a prototype implementation. Here's a summary of findings and the recommended approach.

Investigation Summary

runmedev/web:

• Already has partial IPykernel support (app/src/lib/ipykernel.ts) for parsing Jupyter IOPub messages
• Streams infrastructure provides RxJS-based WebSocket streaming compatible with Jupyter's async model
• RunnersManager pattern allows easy addition of Jupyter kernel backends
• CellConsole already handles stream and error IOPub message types

runmedev/runme:

• Clean extensible design with Executable interface for adding new execution backends
• Session management with environment persistence
• WebSocket streaming through agent server
• Well-defined protobuf schemas that can be extended for kernel messages

jupyter-server:

• Provides the ZMQ-to-WebSocket bridge we need
• REST API for kernel/session management (/api/kernels, /api/sessions)
• WebSocket API at /api/kernels/{id}/channels multiplexes all Jupyter channels
• Token-based authentication with CORS support

Recommended Approach: Jupyter Server Proxy

After analyzing all options, I recommend Option 2 from the issue: managing Jupyter server instances. This is more practical than implementing ZMQ bridging in Go because:

1. Leverages existing infrastructure - Jupyter Server already handles the complex ZMQ-to-WebSocket translation
2. Immediate access to all kernels - Python, R, Julia, and any other Jupyter kernel works out of the box
3. Simpler implementation - HTTP/WebSocket proxy vs reimplementing Jupyter protocol in Go (~2-4 weeks vs 3-6 months)
4. Battle-tested - Jupyter's kernel management is mature and well-maintained

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                  Runme Web Frontend                      │
│   CellConsole ◄─── JupyterStreamsAdapter ◄─── Session   │
└───────────────────────────┬─────────────────────────────┘
                            │ WebSocket
┌───────────────────────────┼─────────────────────────────┐
│              Runme Go Backend                            │
│              ┌────────────▼────────────┐                │
│              │   Jupyter Proxy Handler │                │
│              └────────────┬────────────┘                │
│              ┌────────────▼────────────┐                │
│              │    Jupyter Server       │                │
│              │    (subprocess)         │                │
│              └─────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

Prototype Implementation

I've created working prototype files demonstrating the integration:

1. app/src/lib/runtime/jupyterKernelProxy.ts (~540 lines)

   • Full WebSocket client for Jupyter kernel channels
   • Session and kernel lifecycle management
   • Message parsing for all IOPub message types
   • RxJS observables for stdout/stderr/displayData/exitCode

2. app/src/lib/runtime/jupyterIntegration.ts (~270 lines)

   • JupyterSessionManager - One session per notebook for REPL behavior
   • JupyterStreamsAdapter - Bridges Jupyter output to existing Runme Streams interface
   • renderJupyterOutput() - Handles rich MIME types (HTML, images, LaTeX)

Implementation Phases

Phase	Duration	Description
1	Week 1-2	Frontend Jupyter Client (✅ prototype done)
2	Week 2-3	Backend Proxy - Route connections through Runme
3	Week 3-4	Rich Output Rendering - Full MIME type support
4	Week 4	Language Detection - Auto-routing Python cells

Key Design Decisions

Decision	Choice	Rationale
Session Scope	Per-notebook	Variables persist across cells, matching Jupyter behavior
Kernel Process Owner	Runme backend	Clean lifecycle management
Authentication	Token passthrough	Runme auth tokens used, Jupyter in trusted mode

Next Steps

1. Review this proposal and provide feedback
2. Begin Phase 1 implementation with real Jupyter server testing
3. Extend backend to manage Jupyter server subprocess

Full proposal document and prototype code available on request.

---

Slack thread: https://parlancelabs.slack.com/archives/C094HF3MV3L/p1770503738301749

[hamelsmu]

I’m hamelsmu’s codex agent (codex 5.3) tasked with this investigation.

This is an amended, implementation-ready handoff plan (not just architecture), so another coding agent can execute directly.

0) Scope + Non-Goals

In scope (v1)

• Persistent Python REPL across notebook cells using Jupyter kernel state.
• Frontend communicates only with Runme gateway.
• Runme proxies:
  • WebSocket kernel channel traffic to Jupyter /api/kernels/{id}/channels
  • HTTP kernel/session lifecycle APIs to Jupyter REST.

Out of scope (v1)

• Reimplementing Jupyter ZMQ bridge in Go.
• Replacing Jupyter Server internals.
• Advanced Jupyter widget binary buffer parity (defer; text/JSON first, preserve extension point).

1) Confirmed facts from current code (must drive implementation)

• runme websocket protocol currently only carries ExecuteRequest/ExecuteResponse (api/proto/runme/stream/v1/websockets.proto).
• runme /ws path enforces runID + knownID consistency in pkg/agent/runme/stream/streams.go and routes only execute payloads in pkg/agent/runme/stream/multiplexer.go.
• web currently parses ipykernel messages from stdout text (app/src/lib/ipykernel.ts, app/src/lib/notebookData.ts, app/src/components/Actions/CellConsole.tsx).
• jupyter_server already provides robust channels + REST APIs:
  • REST: jupyter_server/services/kernels/handlers.py, .../sessions/handlers.py
  • WS/ZMQ bridge: jupyter_server/services/kernels/websocket.py, .../connection/channels.py

2) Delivery plan (PR-sliced)

PR-1: Runme protocol extension + WS Jupyter proxy (manual kernel id)

2.1 Protobuf changes

Edit runme:

• api/proto/runme/stream/v1/websockets.proto

Add:

message JupyterRequest {
  string host = 1;          // "localhost" etc.
  uint32 port = 2;          // jupyter server port
  string token = 3;         // jupyter token
  string kernel_id = 4;     // target kernel
  string session_id = 5;    // frontend session id
  bool secure = 6;          // ws vs wss
  bytes data = 7;           // raw frame payload (JSON for v1)
}

message JupyterResponse {
  string kernel_id = 1;
  string session_id = 2;
  bool binary = 3;
  bytes data = 4;
}

Extend oneofs:

• WebsocketRequest.payload: add jupyter_request = 2
• WebsocketResponse.payload: add jupyter_response = 2

Then run in runme:

• make proto/generate

Expected generated updates include:

• api/gen/proto/go/runme/stream/v1/websockets.pb.go
• api/gen/proto/ts/runme/stream/v1/websockets_pb.*
• api/gen/proto/es/runme/stream/v1/websockets_pb.*

2.2 Backend WS proxy component

Add file:

• pkg/agent/runme/stream/jupyter_proxy.go

Implement:

• type JupyterProxy struct with upstream connection pool keyed by:
  (host, port, kernel_id, session_id, secure)
• Forward(req *streamv1.JupyterRequest, onMessage func(*streamv1.JupyterResponse), onError func(error))
• Dial URL:
  • ws:// or wss://
  • /api/kernels/{kernel_id}/channels?session_id={session_id}&token={token}
• One read goroutine per upstream conn that emits JupyterResponse back to multiplexer.
• Safe concurrent writes (mutex per upstream conn).
• Connection cleanup on error/close.

2.3 Multiplexer routing (critical)

Modify:

• pkg/agent/runme/stream/multiplexer.go

Required refactor:

• Do not eagerly start Processor/runner.Server.Execute() on multiplexer start.
• Start execute processor lazily only when first execute_request arrives.
• Route jupyter_request directly to JupyterProxy.

Reason: current process() assumes execute-only run and always spins runner execution.

Implementation details:

• Add jupyterProxy *JupyterProxy to Multiplexer.
• In request loop:
  • if req.GetExecuteRequest() != nil: ensure processor started; enqueue request.
  • if req.GetJupyterRequest() != nil: jupyterProxy.Forward(...).
• For Jupyter outbound, wrap as WebsocketResponse{payload: jupyter_response, status: OK} and broadcast with existing Streams.broadcast.

2.4 Inactivity/keepalive fix for Jupyter runs

Current inactivity timeout can cancel multiplexer even without execute processor activity.

Modify multiplexer.go:

• track lastActivity timestamp and refresh on:
  • incoming authenticated request (execute/jupyter/ping)
  • outgoing execute/jupyter responses
• timeout compares now-lastActivity instead of static deadline.

2.5 Security guardrails (must include)

To avoid proxy SSRF:

• In jupyter_proxy.go, validate host (v1: allow localhost, 127.0.0.1, ::1 only).
• Validate port range (1-65535).
• Reject non-local hosts with PERMISSION_DENIED status in websocket response.

(If remote-host support is needed later, add explicit allowlist config flag.)

2.6 PR-1 tests

Add/extend tests in runme:

• pkg/agent/runme/stream/handler_test.go
• new: pkg/agent/runme/stream/jupyter_proxy_test.go

Test cases:

1. jupyter_request roundtrip via fake upstream websocket server.
2. Mixed-mode run: execute + jupyter requests both function.
3. runID mismatch still denied.
4. knownID mismatch still denied.
5. ping/pong behavior unchanged.
6. inactivity timer refreshes on jupyter traffic.
7. disallowed host rejected.

Run:

• go test ./pkg/agent/runme/stream/...
• go test ./pkg/agent/server/...

PR-2: Web frontend WS support (manual kernel id)

2.7 Streams API extension

Modify:

• packages/renderers/src/streams.ts

Add:

• sendJupyterRequest(req: pb.JupyterRequest)
• new observable subject: jupyter (raw Jupyter frames as bytes + parsed JSON helper)

In websocket onMessage path:

• branch on payload case:
  • executeResponse (existing path)
  • jupyterResponse (new path)
• decode jupyterResponse.data and emit.

Keep existing execute behavior unchanged.

2.8 Runner model extension

Modify:

• app/src/lib/runner.ts
• app/src/lib/runtime/runnersManager.ts
• app/src/components/AppConsole/AppConsole.tsx

Add runner kind:

• kind: "runme" | "jupyter" (default runme)
• jupyter?: { host; port; token; secure?; kernelId?; sessionId? }

Add JS console command helper:

• aisre.runners.updateJupyterKernel(name, endpoint, host, port, token, kernelId?)

Persist new fields in localStorage manager.

2.9 Notebook execution path

Modify:

• app/src/lib/notebookData.ts

In runCodeCell:

• if runner kind runme: existing execute flow unchanged.
• if runner kind jupyter:
  • create/reuse Streams as usual
  • build Jupyter execute_request JSON message:
    • header.msg_type = "execute_request"
    • content.code = cell.value
    • content.silent = false
    • content.store_history = true
  • send via sendJupyterRequest

Add per-notebook session cache:

• map runner name -> {kernelId, sessionId}
• for PR-2, kernelId can be preconfigured manually.

2.10 Output binding update

Modify:

• app/src/lib/notebookData.ts (bindStreamsToCell)
• app/src/components/Actions/CellConsole.tsx

New behavior:

• Prefer Jupyter channel messages over stdout JSON sniffing when available.
• Parse msg_type directly:
  • stream -> stdout/stderr
  • error -> stderr traceback
  • display_data / execute_result / update_display_data -> notebook output items
  • execute_reply -> synthesize completion event (exitCode 0/1)
  • status -> busy/idle metadata (optional v1)

Keep old stdout parsing as fallback for legacy flows.

2.11 PR-2 tests

Add/extend:

• app/src/lib/notebookData.test.ts
• new tests under packages/renderers for Streams jupyter payload handling.

Test cases:

1. Jupyter runner sends jupyter_request, not execute.
2. stream message appears in stdout output item.
3. error message maps to stderr output item.
4. execute_reply completes run.
5. Legacy runme runner behavior unchanged.

Run:

• pnpm -C /path/to/web install
• pnpm -C /path/to/web test
• pnpm -C /path/to/web build

PR-3: Runme HTTP proxy for kernel/session lifecycle

2.12 Add HTTP proxy handler

Add files:

• pkg/agent/server/jupyter_proxy.go
• pkg/agent/server/jupyter_proxy_test.go

Register in pkg/agent/server/server.go:

• protected route prefix, e.g. /jupyter/http/.

Behavior:

• Forward incoming method/path/query/body to Jupyter host/port from request headers:
  • X-Runme-Jupyter-Host
  • X-Runme-Jupyter-Port
  • X-Runme-Jupyter-Token
  • optional X-Runme-Jupyter-Secure
• add Authorization: token <token> upstream (or query token).
• return upstream status/body as-is.
• apply same localhost/port validation as WS proxy.

This allows frontend to call through Runme only:

• /jupyter/http/api/kernels
• /jupyter/http/api/sessions
• restart/interrupt/delete routes

2.13 PR-3 tests

• upstream fake HTTP server passthrough tests.
• auth-protected route test.
• disallowed host test.

PR-4: Frontend lifecycle wiring (no manual kernel id)

2.14 Kernel/session manager in web

Add file:

• app/src/lib/runtime/jupyterSessionManager.ts

Responsibilities:

• ensure kernel exists for notebook+runner (via Runme /jupyter/http/api/kernels)
• ensure session exists (optional but recommended) via /api/sessions
• persist {kernelId, sessionId} in notebook model metadata.

Integrate in NotebookData.runCodeCell before first jupyter execute.

2.15 UX details (minimum)

• If kernel startup is pending, show running/loading state in cell.
• If kernel dies, clear cached kernelId and retry once.
• Add command(s) in AppConsole for restart/interrupt current kernel.

3) Payload examples (for implementer)

WebsocketRequest (jupyter)

{
  "knownId": "cell_code_abcd",
  "runId": "run_01...",
  "payload": {
    "case": "jupyterRequest",
    "value": {
      "host": "localhost",
      "port": 8888,
      "token": "abc123",
      "kernelId": "<kernel-uuid>",
      "sessionId": "<session-uuid>",
      "secure": false,
      "data": "<bytes>"
    }
  }
}

Jupyter execute_request JSON inside data

{
  "header": {
    "msg_id": "<uuid>",
    "msg_type": "execute_request",
    "session": "<session-uuid>",
    "username": "aisre",
    "version": "5.3"
  },
  "parent_header": {},
  "metadata": {},
  "content": {
    "code": "print('hello')",
    "silent": false,
    "store_history": true,
    "allow_stdin": true,
    "stop_on_error": true
  }
}

4) Implementation order (strict)

1. PR-1 runme protocol + WS proxy + tests
2. PR-2 web stream + runner + execution + tests (manual kernel id)
3. PR-3 runme HTTP lifecycle proxy + tests
4. PR-4 web automatic kernel/session lifecycle + UX polish

Do not start PR-4 before PR-1/2 are stable.

5) Local end-to-end validation script

Setup

1. Start Jupyter Server:
   • jupyter server --no-browser --port=8888 --ServerApp.token=test-token
2. Start Runme server with websocket endpoint.
3. In web app, configure jupyter runner pointing at Runme ws endpoint + jupyter host/port/token.

Verify

1. Create kernel via Runme lifecycle proxy (POST /jupyter/http/api/kernels).
2. Execute cell a = 2 then a + 3 in same runner.
3. Confirm second cell returns 5 (state persistence).
4. Confirm print('x') arrives as stream output.
5. Confirm Python exception renders traceback.
6. Restart kernel and confirm state reset.

6) Definition of done

• Cells using jupyter runner execute over Runme gateway.
• Multi-cell REPL state persists via shared kernel id.
• No Go ZMQ dependency added.
• Existing runme execute path remains green.
• New tests pass in both repos.
• Documented runner configuration and troubleshooting in repo docs.

7) Risks and mitigations

• Risk: SSRF via arbitrary host proxying.
  Mitigation: localhost-only validation in v1.
• Risk: mixed execute/jupyter lifecycle race in existing multiplexer.
  Mitigation: lazy processor initialization + separate jupyter path handling.
• Risk: jupyter binary frame edge cases (widgets).
  Mitigation: carry binary flag now; implement full widget buffer support in follow-up.

8) Follow-up (post-v1)

• Add configurable host allowlist for remote jupyter targets.
• Add richer kernel status UI (busy/idle icon, interrupt button).
• Add binary buffer support parity with Jupyter WS v1 protocol.
• Evaluate optional /jupyter/ws dedicated endpoint if long-term separation from execute multiplexer is preferred.