Repository navigation
Runnable Jupyter notebooks in T3: run cells from the side-pane notebook viewer, and agent tools to build and run them #208
Description
Owner request, 2026-10-28: full Jupyter notebook support in the side pane. That means running cells, plus agents creating notebooks to show results and analysis. The owner wants to try both ways, built by Codex agents.
Done now, no T3 code
Each research project has a JupyterLab project script:
| Project | Port |
|---|---|
| Lithium_Extraction | 8891 |
| ePC-SAFT | 8892 |
| Amine-Thermodynamics | 8893 |
| MEA-Absorption-Column | 8894 |
The script runs uv run --no-sync --with jupyterlab jupyter lab --no-browser --ServerApp.ip=127.0.0.1 --ServerApp.port=<port> --IdentityProvider.token=<per-project token>. It layers JupyterLab over the project's own .venv, so the kernel imports the project's packages, and it opens in T3's in-app browser pane (previewUrl, autoOpenPreview). It was checked on Lithium_Extraction: the server started, the python3 kernel is available, and it stopped cleanly. The browser pane shows real browser tabs, so JupyterLab's frame-ancestors 'self' doesn't matter.
Wanted: native cell running (option 3)
Today: upstream's apps/web/src/components/files/NotebookPreview.tsx renders .ipynb read-only with saved outputs.
Proposed shape, as an optional extension:
- A server service talks to a Jupyter kernel through the Jupyter Server REST and WebSocket API, or
jupyter_clientthrough a small sidecar. It runs one kernel per open notebook in the project's environment, with execute, interrupt and restart, and streams outputs back over T3's WebSocket as typed contracts. - The notebook viewer gets Run, Run all and Interrupt, shows live outputs, and saves them back to the
.ipynb. - Agents get MCP tools to create a notebook, add or edit cells, run them and read the outputs. Scheduled tasks use the same service. Agents can then build analysis notebooks and leave them run for the owner to open.
Constraints:
- Off unless a Jupyter server or kernel is available for the project.
- Never binds beyond
127.0.0.1. - Kernels stop when their notebook closes or after idle time, and
t3_preview_list-style tools show running kernels. - Performance: stream outputs without re-rendering the whole notebook.
- Fork rules: Modular fork: move remaining fork code out of upstream files #24, as fork-owned files with small hooks.
- Out of scope: mobile, and providers other than Codex and Claude.
Steps
- Read-only design: the kernel transport choice, contracts, UI, agent tools, lifecycle and security. Size it and split it into PRs.
- The owner approves the design.
- The build.
Also include agent guidance for the JupyterLab path in the meantime:
- create
.ipynbfiles with the analysis; - run them headless with
uv run --no-sync --with jupyterlab jupyter nbconvert --to notebook --execute --inplace <file>; - open them in the file viewer, which shows the outputs, or in the JupyterLab tab.
Activity
tannerpolley commentedon Oct 28, 2026
Design pass (2026-10-28, read-only, GPT-6.1 Sol high). The full doc is
~/.local/share/t3-fork-notes/notebook-execution-design.md.Recommendation
T3's server connects to a project-local Jupyter Server through REST (
/api/kernels, kernelspecs, interrupt, restart, delete) and one kernel WebSocket per notebook. The JSON wire format is enough..ipynb. Jupyter's Contents API is not used.jupyter_clientsidecar, which adds another process to own; and "embed JupyterLab only", which is the interim path, not native.Shape
Fork-owned modules:
apps/server/src/notebook/NotebookService.ts,JupyterTransport.ts,notebookDocument.tsandpackages/contracts/src/notebook.ts, with small hooks inForkWsRpc, layer assembly, authorization and MCP.Methods:
open,edit/create,execute(returns a run id, one active run per notebook),interrupt,restart(with a kernel generation),subscribe(snapshot plus typed deltas),readOutputs,saveandlistKernels.Rules:
allow_stdin=false, and widget/comm messages are not rendered.Live probe (Jupyter Server on 127.0.0.1:8899, Lithium_Extraction)
Verified:
.venvimports through uv's overlay.execute_replyand idle arrived in both orders across runs, and the design accounts for that.Unverified: the UI, remote and multi-device use, output flooding, and running after a restart.
PR split (about 9–15 engineering days)
The doc also has paste-ready interim guidance for agents on the JupyterLab path. Waiting on the owner's approval before building.
tannerpolley commentedon Oct 28, 2026
T3 Code status: Unavailable
Issue: #208 Runnable Jupyter notebooks in T3: run cells from the side-pane notebook viewer, and agent tools to build and run them
Thread: thread:delegated-task:command%3Amcp%3A88ea76df-ad9e-4a1d-b66f-1a9ef47273be%3Adelegate-task%3A04d33e07-734d-4cea-8f73-375b363ffd79
Model: gpt-6.1-sol
Branch: issue-208-runnable-jupyter-notebooks-in-t3-run
Updated: 2026-11-13T05:08:38.489Z
tannerpolley commentedon Oct 29, 2026
T3 Code closeout: done
Issue: #208 Runnable Jupyter notebooks in T3: run cells from the side-pane notebook viewer, and agent tools to build and run them
Thread: thread:delegated-task:command%3Amcp%3A88ea76df-ad9e-4a1d-b66f-1a9ef47273be%3Adelegate-task%3A04d33e07-734d-4cea-8f73-375b363ffd79
Model: gpt-6.1-sol
Branch: issue-208-runnable-jupyter-notebooks-in-t3-run
Completed: 2026-10-29T22:06:15.083Z
#208 and all four sub-issues are closed. Each phase passed independent Codex review, merged sequentially into
main, and was pushed.5cde48b9ff51a075ae2c27f1680723509c9a1a658c764e5ca36c4a88ce314d3c4d1e0341fa2dd95b4c8582a2589f0f1a1868798fb318ccb1c607e23a615154bbffe3f2565d1cb3303cefa01298987cddmainThe #213 pagination correction passed independent reconstruction probes, including Unicode and escaped text. Oversized output records now remain readable through bounded pages without losing data or changing saved notebook contents.
The overall
check:changedgate still reports the established unrelated baseline: three mobile type errors, three unused files, and 74 unused exports. Format, lint, GraphQL, and affected tests passed. Free eval context and dry-run checks passed; paid evaluation was skipped because no API key exists and is not an open gate.Cleanup is complete: the stale implementor run is interrupted, #213’s local/remote branches and both worktrees—including
-2—are gone. Remotemainmatches the delivered commit. No migration, dev seeding, T3 installation/restart, or release build was performed.The external notebook skill update is applied and reviewed, but remains uncommitted in the shared skills repository, preserving unrelated work. Its focused diff is retained. Execution still requires trusted project configuration; disclosed save-race, crash-recovery, process-local draft, and binary-frame limits remain.
PR #249, head
615154bbffe3f2565d1cb3303cefa01298987cdd, checks and reviews: independent checker passed; affected checks passed with the baseline exceptions above; merged.