nteract
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 16 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nteract/nteract with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nteract/nteract'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/nteract--nteract)HTML
<a href="/listings/nteract--nteract"><img src="/api/listings/nteract--nteract/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
These instructions install nteract Desktop and its notebook tools. Pages has a separate [local setup](apps/pages/README.md#run-locally).
Download the latest release from [GitHub Releases](https://github.com/nteract/nteract/releases).
On Linux (x64 or ARM64) and macOS (Apple silicon or Intel), this command installs the AppImage or signed .app bundle, CLI/daemon, and per-user service (systemd or launchd):
curl --proto '=https' --tlsv1.2 -sSf https://sh.nteract.io | bash
macOS users can equally drag the DMG from GitHub Releases. DEB/RPM/APT installs are not currently supported because `runtimed` is a per-user daemon managed by the app and CLI, not by system package-manager scripts.
For remote workstations (Outerbounds, JupyterHub) that offer compute to hosted notebooks, use the headless installer. See [Remote workstations](docs/runbooks/remote-workstation.md) for details:
curl --proto '=https' --tlsv1.2 -sSf https://sh.nteract.io | bash -s -- --cli
Use `nteract` for notebook, workstation, and MCP operations. CLI-only installation does not configure or start a local daemon service. The desktop app bundles the same CLI. Existing `runt`, `runt-nightly`, and `nteract-mcp` commands remain compatible. See the [CLI guide](docs/runbooks/cli.md) for runtime startup, channel selection, and scripting behavior.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 20 lines
- {
- "name": "nteract",
- "owner": {
- "name": "nteract"
- },
- "plugins": [
- {
- "name": "nteract",
- "source": "./plugins/nteract",
- "description": "nteract notebooks in Claude Code.",
- "version": "0.8.1"
- },
- {
- "name": "nightly",
- "source": "./plugins/nightly",
- "description": "nteract notebooks (nightly channel) in Claude Code.",
- "version": "0.8.1"
- }
- ]
- }
README.md · README · 427 lines · 2 findings marked
- # nteract
- nteract builds tools for thinking with code, data, and documents. This monorepo
- is home to **nteract notebooks**, **Pages**, and the libraries and runtime that
- support them. People and AI agents collaborate on live Automerge documents in
- both products.
- ## Products
- ### nteract notebooks
- A local-first notebook environment for writing and running code, exploring data,
- and working with rich outputs. The native desktop app and hosted browser app
- share notebook UI and document protocols. The `runtimed` daemon manages kernels,
- environments, execution, and outputs; desktop, CLI, MCP, and programmatic clients
- work with the same live notebook.
- [](https://nteract.io/changelog/2.6)
- *Navigate a computational story through its headings and outputs. Screenshot
- from the [nteract 2.6 release notes](https://nteract.io/changelog/2.6), which also
- include video demos.*
- Start with the [desktop installation](#install), [development guide](#development),
- or [hosted notebook guide](apps/notebook-cloud/README.md).
- ### Pages
- Pages is a notebook-like space for writing, thinking, and exploring together.
- Mix rich text, images, diagrams, editable tables, task lists, and interactive
- dataframes in one document. Sketch an idea, explore a dataset, leave a comment
- on a passage, and invite an agent to help develop it. Organize related Pages
- into Projects and share individual Pages with collaborators. It should be as
- fun to explore an idea as it is to write it down.
- Pages has its own browser editor, document model, HTTP API, and MCP server.
- People edit rich content directly; agents use Markdown and structured operations
- on that same content. Pages displays code and diagrams; kernel execution lives
- in notebooks.
- Start with the [Pages guide](apps/pages/README.md)
- for features, local development, and tests, or the
- [deployment guide](apps/pages/DEPLOYMENT.md)
- for release targets. Its source lives in `apps/pages`.
- ## What's in here
- | Project | Purpose |
- |---------|---------|
- | nteract notebooks | Desktop and hosted notebooks for code execution and data exploration |
- | [Pages](apps/pages/README.md) | Rich collaborative documents for people and agents |
- | [Sift](packages/sift/README.md) | Interactive data exploration and table rendering, used in notebooks and Pages and available as a standalone library |
- | `runtimed` | Notebook runtime daemon for environment pools, sync, kernel execution, and outputs |
- | `nteract` command | CLI for notebooks, workstations, runtime operations, and supervised notebook MCP |
- | Client libraries | TypeScript, Node, and Python access to notebook documents and the daemon |
- | Elements | Shared UI catalog and interaction fixtures |
- <details>
- <summary>See Sift's interactive data exploration</summary>
- 
- *Brush a column's distribution to filter the table and update the other
- summaries. Sift powers dataframe exploration in notebooks and Pages; see the
- [Sift guide](packages/sift/README.md) for standalone use and embedding.*
- </details>
- ## Install
- These instructions install nteract Desktop and its notebook tools. Pages has a
- separate [local setup](apps/pages/README.md#run-locally).
- Download the latest release from [GitHub Releases](https://github.com/nteract/nteract/releases).
- On Linux (x64 or ARM64) and macOS (Apple silicon or Intel), this command installs the
- AppImage or signed .app bundle, CLI/daemon, and per-user service
- (systemd or launchd):
- ```bash
- curl --proto '=https' --tlsv1.2 -sSf https://sh.nteract.io | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 81 on GitHub
- ```
- macOS users can equally drag the DMG from GitHub Releases. DEB/RPM/APT
- installs are not currently supported because `runtimed` is a per-user daemon
- managed by the app and CLI, not by system package-manager scripts.
- For remote workstations (Outerbounds, JupyterHub) that offer compute to
- hosted notebooks, use the headless installer. See
- [Remote workstations](docs/runbooks/remote-workstation.md) for details:
- ```bash
- curl --proto '=https' --tlsv1.2 -sSf https://sh.nteract.io | bash -s -- --cli
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 93 on GitHub
- ```
- Use `nteract` for notebook, workstation, and MCP operations. CLI-only installation does not configure or start a local daemon service. The desktop app bundles the same CLI. Existing `runt`, `runt-nightly`, and `nteract-mcp` commands remain compatible. See the [CLI guide](docs/runbooks/cli.md) for runtime startup, channel selection, and scripting behavior.
- ## Runtime model
- nteract notebooks store content in `NotebookDoc` and live kernel and execution
- state in `RuntimeStateDoc`. `CommsDoc` holds widget state and `CommentsDoc` holds
- notebook comments. The daemon owns kernel processes, execution queues, output
- capture, and the write path for execution results.
- Execution requests name a synced `cell_id`; the daemon reads the cell source from the shared document, records queue and status changes in runtime state, and writes outputs through the same model. The desktop app, CLI, MCP server, and agent clients use that path, so programmatic control observes the same notebook state a human is editing.
- Pages stores native rich text in its own Automerge document, with a separate
- comments document. Its host owns authorization and durable receipts. It has its
- own sync and persistence stack. Where the product is going is in
- [Pages direction](apps/pages/DIRECTION.md).
- ## MCP Server
- Both products expose MCP tools. Pages serves its own
- [HTTP MCP endpoint](apps/pages/REFERENCE.md#http-and-mcp-tools)
- for document, Project, and comment operations. The setup below is for notebooks.
- Run `nteract mcp` to connect AI assistants to notebooks. Local notebooks use the runtime daemon; direct hosted connections use WebSockets without a local daemon. Agents can run code, read and write cells, manage dependencies, and collaborate with humans on the same live notebook.
- ### Install the Codex plugin
- ```
- codex plugin marketplace add nteract/agent-plugins
- ```
- Restart Codex, then open the plugin directory, choose the nteract marketplace, and install `nteract`.
- The distribution repository also includes a `nightly` plugin entry for pre-release builds.
- If tools are missing or notebook calls fail after an app update, follow [Upgrade the Codex plugin](#upgrade-the-codex-plugin).
- ### Upgrade the Codex plugin
- The desktop app and the Codex plugin update separately. An older plugin can reject a newer app's notebook routing with `unsupported_notebook_target`, including this misleading message:
- ```text
- This child does not advertise required notebook_handle routing;
- upgrade the child before using notebook tools
- ```
- This can mean the **plugin proxy needs updating**, even when the desktop app is current. It can block notebook creation as well as calls using a notebook ID or handle. Plugin 0.6.6 and desktop 2.8.6 are a verified compatible pairing; their version numbers are independent.
- Save any notebook work before restarting your agent. Refresh the marketplace, then reinstall only the channel you use. Run these commands in a terminal. The `&&` operators stop the sequence if a step fails.
- Stable:
- ```sh
- codex plugin marketplace upgrade nteract-plugins &&
- codex plugin remove nteract@nteract-plugins &&
- codex plugin add nteract@nteract-plugins
- ```
- Nightly:
- ```sh
- codex plugin marketplace upgrade nteract-plugins &&
- codex plugin remove nightly@nteract-plugins &&
- codex plugin add nightly@nteract-plugins
- ```
- If you registered the marketplace at an older release with `--ref`, refreshing keeps that pin. To move to current `main`, replace the marketplace registration before reinstalling:
- ```sh
- codex plugin marketplace remove nteract-plugins &&
- codex plugin marketplace add nteract/agent-plugins --ref main
- ```
- Only reinstall the plugin after registration succeeds. If cloning fails, use the local checkout fallback below.
- Restart Codex and start a fresh session so it loads the updated proxy and tool catalog. The MCP `reconnect` tool restarts the worker behind the proxy; it does not upgrade the plugin proxy. Restarting Codex without updating the cached plugin can still launch the old binary.
- Check the installed plugin version in Codex's plugin settings, then ask the agent to create a notebook and run a cell containing `1 + 1`. Confirm that the cell returns `2`. Seeing a skill or a server in `codex mcp list` alone does not verify notebook execution. If it still fails, include the exact error, plugin version and channel, and `nteract --version` when [reporting an issue](https://github.com/nteract/nteract/issues).
- #### If the marketplace refresh times out
- If `marketplace upgrade` reports `git clone marketplace source timed out after 30s` or `fatal: early EOF`, stop before removing the installed plugin. The replacement marketplace has not finished downloading. Retry the refresh; if it continues to fail, clone a shallow checkout outside Codex's clone deadline and register that local directory. On macOS or Linux, for an existing `nteract-plugins` registration:
- ```sh
- mkdir -p "$HOME/.local/share/nteract" &&
- git clone --depth 1 --single-branch --branch main \
- https://github.com/nteract/agent-plugins.git \
- "$HOME/.local/share/nteract/agent-plugins" &&
- codex plugin marketplace remove nteract-plugins &&
- codex plugin marketplace add "$HOME/.local/share/nteract/agent-plugins"
- ```
- Use a new directory for the clone. The chain finishes downloading before removing the old marketplace registration. Codex requires that removal when changing sources under the same name; `marketplace remove` is separate from uninstalling the plugin with `plugin remove`. If you already removed the marketplace registration, skip that removal command.
- Only after registration succeeds, run the selected channel's `plugin remove` and `plugin add` commands above, then restart Codex. Keep the checkout: it is now the registered marketplace source. For future updates, run `git -C "$HOME/.local/share/nteract/agent-plugins" pull --ff-only` successfully before reinstalling the plugin; `marketplace upgrade` refreshes Git sources, not local directories. To return to a Git-managed marketplace later, use the remove-and-add registration commands above.
- ### Install the Claude Code plugin
- ```
- /plugin marketplace add nteract/agent-plugins
- /plugin install nteract@nteract
- ```
- Pin a specific version:
- ```
- /plugin install nteract@nteract --ref v2.3.0
- ```
- The plugin ships the `nteract-mcp` binary for your platform (macOS arm64/x64, Linux x64/arm64, Windows x64), so no separate install is needed. `main` of `nteract/agent-plugins` always points at the latest stable release.
- For pre-release builds (updated daily):
- ```
- /plugin install nightly@nteract
- ```
- ### Install in Claude Desktop
- If you use the nteract desktop app with Claude Desktop, there's a one-click install path. In the menu bar, choose **nteract → Install Extension for Claude...**
- 
- The nteract desktop app is required: it builds a `.mcpb` bundle at runtime (manifest, icons, `nteract-mcp` binary) and hands it to Claude Desktop, which prompts you to confirm the install.
- ## Usage
- ```bash
- # Open a notebook
- nteract open path/to/notebook.ipynb
- # MCP server for notebook automation
- nteract mcp
- # Daemon management
- nteract daemon status
- nteract daemon logs -f
- ```
- List open notebooks with kernel and environment info:
- ```
- $ nteract notebooks
- ╭──────────────────────────────────────┬────────┬──────────────┬────────┬───────╮
- │ NOTEBOOK │ KERNEL │ ENV │ STATUS │ PEERS │
- ├──────────────────────────────────────┼────────┼──────────────┼────────┼───────┤
- │ ~/notebooks/blobstore.ipynb │ python │ uv:inline │ idle │ 1 │
- │ d4c441d3-d862-4ab0-afe6-ff9145cc2f3d │ python │ uv:prewarmed │ idle │ 1 │
- ╰──────────────────────────────────────┴────────┴──────────────┴────────┴───────╯
- ```
- ## Project structure
- ```
- nteract/nteract
- ├── src/ # Shared UI code (React components, hooks, utilities)
- │ ├── bindings/ # TypeScript types generated from Rust (ts-rs)
- │ ├── components/
- │ │ ├── ui/ # shadcn primitives (button, dialog, etc.)
- │ │ ├── cell/ # Notebook cell components
- │ │ ├── outputs/ # Output renderers (stream, error, display data)
- │ │ ├── editor/ # CodeMirror editor
- │ │ ├── isolated/ # Iframe security isolation (IsolatedFrame, CommBridgeManager)
- │ │ └── widgets/ # ipywidgets controls
- │ ├── hooks/ # Shared hooks (useSyncedSettings, useTheme)
- │ ├── isolated-renderer/ # Code that runs inside isolated iframes
- │ ├── lib/ # Shared utilities (cn(), dark-mode, error-boundary)
- │ └── styles/ # Global stylesheets
- ├── apps/ # App entry points
- │ ├── notebook/ # Desktop notebook Tauri app
- │ ├── notebook-cloud/ # Hosted notebook worker (Cloudflare)
- │ ├── elements/ # Elements design system catalog
- │ ├── pages/ # Pages: collaborative documents (npm, own lockfile)
- │ ├── mcp-app/ # MCP widget dev app
- │ └── renderer-test/ # Isolated renderer test harness
- ├── packages/ # Client and UI libraries
- │ ├── notebook-host/ # Notebook host shell
- │ ├── runtimed/ # TypeScript notebook client and state stores
- │ ├── runtimed-node/ # Node bindings for daemon
- │ ├── sift/ # Standalone data explorer and embeddable table UI
- │ └── odometer/ # Odometer component
- ├── crates/ # Rust code
- │ ├── runt/ # Shared CLI; nteract-cli and legacy runt entrypoints
- │ ├── runtimed/ # Background daemon
- │ ├── runtimed-py/ # Python bindings for the daemon
- │ ├── runtimed-wasm/ # WASM Automerge bindings for frontend
- │ ├── notebook/ # Notebook Tauri app crate
- │ ├── notebook-doc/ # Automerge document operations
- │ ├── notebook-protocol/ # Notebook wire protocol types
- │ ├── notebook-sync/ # Notebook sync layer
- │ ├── kernel-launch/ # Shared kernel launching API
- │ ├── kernel-env/ # Environment progress reporting
- │ ├── runt-mcp/ # Rust-native MCP server
- │ ├── runt-trust/ # Notebook trust extraction
- │ ├── runt-workspace/ # Workspace detection utilities
- │ ├── runtimed-client/ # Shared client library for daemon
- │ ├── repr-llm/ # LLM-friendly text summaries of visualizations
- │ ├── xtask/ # Build automation tasks
- │ └── mcp-supervisor/ # nteract-dev MCP server (proxies runt mcp + dev tools)
- ├── python/ # Python workspace (uv)
- │ ├── runtimed/ # PyPI: runtimed (Python bindings)
- │ ├── nteract/ # PyPI: nteract (thin launcher for `runt mcp`)
- │ ├── gremlin/ # Stress-testing agent
- │ ├── prewarm/ # Environment prewarm script
- │ ├── dx/ # Developer utilities
- │ ├── nteract-kernel-launcher/ # Kernel launcher for hosted notebooks
- │ └── safari-timeline/ # Safari timeline parser
- ├── plugins/ # Agent plugin distribution
- │ └── nteract/ # Codex plugin package
- └── docs/ # Design, decisions, and operations
- ```
- ## Development
- Choose the workflow for the project you're changing:
- - **Notebooks and runtime:** use the prerequisites and `cargo xtask` commands below.
- - **Pages:** use its [npm workspace setup and tests](apps/pages/README.md#run-locally).
- - **Sift:** use its [standalone development guide](packages/sift/README.md#quick-start).
- ### Prerequisites
- | Tool | Version | Install |
- |------|---------|---------|
- | Node.js | 22.13+ | https://nodejs.org |
- | pnpm | 11.9+ | `corepack enable` |
- | Rust | 1.99.1 | https://rustup.rs (version managed by `rust-toolchain.toml`) |
- **Linux only:** Install GTK/WebKit dev libraries:
- ```bash
- sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libxdo-dev \
- libssl-dev libayatana-appindicator3-dev librsvg2-dev
- ```
- ### Quick start
- ```bash
- cargo xtask dev
- ```
- ### Development workflows
- | Workflow | Command | Use when |
- |----------|---------|----------|
- | Full dev loop | `cargo xtask dev` | Setup plus the per-worktree daemon and hot-reload app |
- | Clean dev restart | `cargo xtask dev --fresh` | Recover from stale Tauri listeners, bootstrap, or daemon state |
- | Dev status | `cargo xtask dev status` | Show the exact app identity, PID, executable, Vite URL, and daemon socket |
- | Focus dev app | `cargo xtask dev focus` | Activate this worktree's exact macOS app process |
- | Reset dev state | `cargo xtask dev reset` | Stop this worktree's app and daemon without affecting installed apps |
- | App-only hot reload | `cargo xtask notebook` | Run the app when the per-worktree daemon is already managed separately |
- | Standalone Vite | `cargo xtask vite` | Multi-window testing (Vite survives window closes) |
- | Attach to Vite | `cargo xtask notebook --attach` | Connect Tauri to already-running Vite |
- | Debug build | `cargo xtask build` | Full debug build (frontend + rust) |
- | E2E debug build | `cargo xtask e2e build` | Debug build with built-in WebDriver server |
- | Rust-only build | `cargo xtask build --rust-only` | Rebuild rust, reuse existing frontend |
- | Run bundled | `cargo xtask run notebook.ipynb` | Run standalone binary |
- | Lint (check) | `cargo xtask lint` | Check formatting and linting across Rust, JS/TS, Python |
- | Lint (fix) | `cargo xtask lint --fix` | Auto-fix formatting and linting |
- | Dev daemon | `cargo xtask dev-daemon` | Run per-worktree dev daemon |
- | Artifact status | `cargo xtask artifacts status` | Check generated WASM, renderer, and MCP widget artifacts |
- | Install nightly (Linux/headless) | `./scripts/install-nightly` | Build + install runtimed + runt + nteract-mcp as the local nightly. Refuses on macOS and when an app bundle is installed. |
- | Release .app | `cargo xtask build-app` | Testing app bundle locally |
- | Release DMG | `cargo xtask build-dmg` | Distribution (usually CI) |
- | Generate icons | `cargo xtask icons [source.png]` | Generate icon variants from source image |
- `cargo xtask dev` installs dependencies, ensures generated artifacts, starts the
- per-worktree dev daemon, waits for it to be ready, and then launches the notebook
- app with hot reload. It stops the daemon it started when the app exits. For repeat
- launches, use `cargo xtask dev --skip-install --skip-build`.
- On macOS, every worktree gets a cached app wrapper with a distinct name and bundle
- identifier, such as `nteract Dev f0f9d9` and
- `org.nteract.desktop.dev.f0f9d99b161f`. This keeps unsigned source builds separate
- from installed stable and Nightly apps without changing release packaging or
- claiming `.ipynb` file associations. Use `cargo xtask dev status` to obtain the
- live automation PID. Accessibility scripts should select the System Events process
- by that PID instead of asking LaunchServices for an app named `nteract`:
- ```applescript
- set devPid to 12345 -- copy Automation PID from `cargo xtask dev status`
- tell application "System Events"
- tell first application process whose unix id is devPid
- -- perform UI automation here
- end tell
- end tell
- ```
- Frontend edits continue through Vite hot reload. After changes to Tauri bootstrap
- or event-listener setup, use `cargo xtask dev --fresh` to terminate only this
- worktree's exact app process, stop its daemon, and relaunch both cleanly. The
- equivalent manual sequence is `cargo xtask dev reset` followed by
- `cargo xtask dev`.
- ### Build order
- The UI must be built before Rust because `crates/notebook` embeds assets from `apps/notebook/dist/` via Tauri.
- ### Common commands
- ```bash
- pnpm build # Build notebook UI
- cargo test # Run Rust tests
- pnpm test:run # Run JS tests
- cargo xtask artifacts status # Check generated artifact readiness
- cargo xtask artifacts ensure runtime # Rebuild only runtimed-wasm when needed
- cargo fmt # Format Rust
- vp check --fix # Lint + format JS/TS
- cargo clippy --all-targets -- -D warnings # Lint Rust
- ```
- ## Library crates
- The underlying Rust libraries are published to crates.io:
- - [`jupyter-protocol`](https://crates.io/crates/jupyter-protocol): Jupyter messaging protocol
- - [`jupyter-zmq-client`](https://crates.io/crates/jupyter-zmq-client): Jupyter kernel interactions over ZeroMQ
- - [`nbformat`](https://crates.io/crates/nbformat): Notebook parsing
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor workflows,
- [AGENTS.md](AGENTS.md) for agent guidance, and [docs/README.md](docs/README.md)
- for the documentation map. Key entry points:
- - [Pages contributor guidance](apps/pages/AGENTS.md): document model, editor, host, and tests
- - `crates/runtimed/AGENTS.md`: architecture, daemon, state ownership
- - `apps/notebook/src/AGENTS.md`: frontend architecture
- - `crates/notebook-wire/AGENTS.md`: wire protocol
- - `cargo xtask help`: all build commands
- ## License
- BSD-3-Clause
plugins/nteract/pi/extensions/repl.ts · Bundled script · 1,298 lines · 3 findings marked
- /**
- * nteract Python REPL for pi — direct bindings edition.
- *
- * Uses the in-process @runtimed/node native binding to talk to
- * the running runtimed daemon, with no MCP subprocess. State (imports,
- * variables) persists across calls within the pi session.
- *
- * Config (env vars):
- * NTERACT_RUNTIMED_NODE_PATH override the runtimed-node package path.
- *
- * Daemon socket selection follows the runtimed-node contract:
- * `RUNTIMED_SOCKET_PATH` overrides outright, `RUNTIMED_WORKSPACE_PATH` (or
- * `RUNTIMED_DEV=1` plus a git checkout) selects the per-worktree dev daemon,
- * otherwise the running channel is auto-detected.
- *
- * After editing, run `/reload` in pi.
- */
- import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
- import { highlightCode } from "@earendil-works/pi-coding-agent";
- import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
- import { existsSync } from "node:fs";
- import { createRequire } from "node:module";
- import { homedir } from "node:os";
- import path from "node:path";
- import { fileURLToPath } from "node:url";
- import { Type } from "typebox";
- // --- runtimed-node loader ----------------------------------------------------
- type RuntimedNode = {
- defaultSocketPath(): string;
- PackageManager?: { Uv: "uv"; Conda: "conda"; Pixi: "pixi" };
- createNotebook(opts?: {
- runtime?: string;
- workingDir?: string;
- socketPath?: string;
- peerLabel?: string;
- description?: string;
- dependencies?: string[];
- packageManager?: "uv" | "conda" | "pixi";
- }): Promise<Session>;
- openNotebook(
- notebookId: string,
- opts?: { socketPath?: string; peerLabel?: string; description?: string },
- ): Promise<Session>;
- readParquetFile(filePath: string, offset: number, limit: number): TableRowPage;
- readArrowFile?(filePath: string, offset: number, limit: number): TableRowPage;
- readArrowChunks?(filePaths: string[], offset: number, limit: number): TableRowPage;
- summarizeParquetFile?(filePath: string): TableSummaryResult;
- summarizeArrowFile?(filePath: string): TableSummaryResult;
- summarizeArrowChunks?(filePaths: string[]): TableSummaryResult;
- resolveBlobPath?(hash: string, socketPath?: string): string | null | undefined;
- };
- type JsOutput = {
- outputType: string;
- name?: string;
- text?: string;
- dataJson?: string;
- ename?: string;
- evalue?: string;
- traceback?: string[];
- executionCount?: number;
- blobUrlsJson?: string;
- blobPathsJson?: string;
- };
- type CellResult = {
- cellId: string;
- executionId: string;
- executionCount?: number;
- status: string; // "done" | "error" | "timeout" | "kernel_error"
- success: boolean;
- outputs?: JsOutput[];
- };
- type TableRowPage = {
- columns: string[];
- rows: string[][];
- totalRows: number;
- offset: number;
- };
- type TableSummaryResult = {
- numRows: number;
- numBytes: number;
- columns: Array<{ name: string; dataType: string; nullCount: number; statsJson: string }>;
- };
- type QueuedExecution = {
- cellId: string;
- executionId: string;
- };
- type ExecutionViewSnapshot = {
- execution_count: number | null;
- status: string;
- success: boolean | null;
- output_ids: string[];
- };
- type ExecutionViewChangeset = {
- execution_upserts?: Array<[executionId: string, snapshot: ExecutionViewSnapshot]>;
- };
- type SubscriptionLike = {
- unsubscribe?: () => void;
- dispose?: () => void;
- };
- type ObservableLike<T> = {
- subscribe(next: (value: T) => void): SubscriptionLike;
- };
- type Session = {
- readonly notebookId: string;
- readonly executionViewChanges$?: ObservableLike<ExecutionViewChangeset>;
- runCell(
- source: string,
- opts?: { timeoutMs?: number; cellType?: string; onUpdate?: (progress: CellResult) => void },
- ): Promise<CellResult>;
- queueCell(source: string, opts?: { cellType?: string }): Promise<QueuedExecution>;
- waitForExecution(
- executionId: string,
- opts?: { timeoutMs?: number; cellId?: string; onUpdate?: (progress: CellResult) => void },
- ): Promise<CellResult>;
- addUvDependency?(pkg: string): Promise<void>;
- addDependencies?(
- packages: string[],
- opts?: { packageManager?: "uv" | "conda" | "pixi" },
- ): Promise<void>;
- getDependencyStatus?(): Promise<{ uv?: { dependencies: string[] }; fingerprint?: string }>;
- getRuntimeStatus?(): Promise<{
- status: string;
- lifecycle: string;
- errorReason?: string;
- errorDetails?: string;
- }>;
- syncEnvironment(): Promise<void>;
- saveNotebook(path?: string): Promise<void>;
- shutdownNotebook?(): Promise<boolean>;
- close(): Promise<void>;
- };
- function loadRuntimedNode(): RuntimedNode | null {
- const extensionDir = path.dirname(fileURLToPath(import.meta.url));
- const candidates = [
- process.env.NTERACT_RUNTIMED_NODE_PATH,
- "@runtimed/node",
- path.resolve(extensionDir, "../../../..", "packages", "runtimed-node", "src", "index.cjs"),
- ].filter((candidate): candidate is string => Boolean(candidate));
- const req = createRequire(import.meta.url);
- const errors: string[] = [];
- for (const candidate of candidates) {
- try {
- return req(candidate) as RuntimedNode;
- } catch (e) {
- errors.push(`${candidate}: ${e instanceof Error ? e.message : String(e)}`);
- }
- }
- console.error("[nteract-repl] failed to load runtimed-node:\n" + errors.join("\n"));
- return null;
- }
- // --- bootstrap detection -----------------------------------------------------
- const INSTALL_HINT =
- "The nteract daemon (runtimed) isn't installed yet.\n" +
- "Quick install: curl -fsSL https://sh.nteract.io | bash\n" +
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 173 on GitHub
- "Or visit: https://nteract.io";
- type BootstrapStatus =
- | { kind: "ready"; rn: RuntimedNode }
- | { kind: "missing"; reason: "binding" | "daemon" };
- function findOnPath(cmd: string): string | undefined {
- const dirs = (process.env.PATH ?? "").split(path.delimiter);
- for (const dir of dirs) {
- if (!dir) continue;
- const candidate = path.join(dir, cmd);
- if (existsSync(candidate)) return candidate;
- }
- return undefined;
- }
- function detectBootstrap(): BootstrapStatus {
- const rn = loadRuntimedNode();
- if (!rn) return { kind: "missing", reason: "binding" };
- // defaultSocketPath() already honors RUNTIMED_SOCKET_PATH and the dev /
- // worktree-aware resolution from runt-workspace, so this is the single point
- // of truth. The socket file only exists while the daemon is running, but the
- // parent cache dir survives shutdowns, so dir-existence covers "installed
- // but stopped".
- const socket = rn.defaultSocketPath();
- const installed =
- existsSync(socket) ||
- existsSync(path.dirname(socket)) ||
- Boolean(findOnPath("runt")) ||
- Boolean(findOnPath("runt-nightly"));
- return installed ? { kind: "ready", rn } : { kind: "missing", reason: "daemon" };
- }
- // --- DataTable TUI component --------------------------------------------------
- type Theme = {
- fg: (color: string, text: string) => string;
- bg: (color: string, text: string) => string;
- bold: (text: string) => string;
- };
- type ColumnStats = {
- kind: string;
- min?: number;
- max?: number;
- distinct_count?: number;
- top?: [string, number][];
- true_count?: number;
- false_count?: number;
- };
- const PARQUET_MIME = "application/vnd.apache.parquet";
- const ARROW_STREAM_MIME = "application/vnd.apache.arrow.stream";
- const ARROW_STREAM_MANIFEST_MIME = "application/vnd.nteract.arrow-stream-manifest+json";
- type ArrowManifestColumn = {
- name: string;
- type?: string;
- nullable?: boolean;
- };
- type ArrowManifestChunk = {
- index?: number;
- hash?: string;
- size?: number;
- row_count?: number;
- record_batch_count?: number;
- encoding?: string;
- };
- type ArrowStreamManifest = {
- schema?: {
- columns?: ArrowManifestColumn[];
- };
- chunks?: ArrowManifestChunk[];
- complete?: boolean;
- summary?: {
- total_rows?: number;
- included_rows?: number;
- sampled?: boolean;
- sample_strategy?: string;
- };
- };
- type TableSource =
- | { kind: "parquet"; path: string }
- | { kind: "arrow"; path: string }
- | { kind: "arrow-manifest"; manifest: ArrowStreamManifest; chunkPaths: string[] };
- function formatStat(stats: ColumnStats | null): string {
- if (!stats) return "";
- switch (stats.kind) {
- case "numeric":
- return `${stats.min?.toFixed(1)}..${stats.max?.toFixed(1)}`;
- case "string":
- return `${stats.distinct_count ?? "?"}d`;
- case "boolean":
- return `T:${stats.true_count ?? 0} F:${stats.false_count ?? 0}`;
- default:
- return "";
- }
- }
- function resolvePath(userPath: string, workingDir = process.cwd()): string {
- const expanded = expandHome(userPath);
- return path.isAbsolute(expanded) ? expanded : path.resolve(workingDir, expanded);
- }
- function expandHome(userPath: string): string {
- if (userPath === "~") return homedir();
- if (userPath.startsWith("~/") || userPath.startsWith("~\\")) {
- return path.join(homedir(), userPath.slice(2));
- }
- return userPath;
- }
- const SPARK_CHARS = "▁▂▃▄▅▆▇█";
- const RATIO_PARTIAL_CHARS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
- function sparkline(values: number[], width: number): string {
- if (values.length === 0 || width <= 0) return "";
- const min = Math.min(...values);
- const max = Math.max(...values);
- const bins = Array.from({ length: Math.min(width, 8) }, () => 0);
- if (min === max) {
- return SPARK_CHARS[3].repeat(bins.length);
- }
- const range = max - min;
- for (const v of values) {
- const bi = Math.min(Math.floor(((v - min) / range) * bins.length), bins.length - 1);
- bins[bi]++;
- }
- const maxCount = Math.max(...bins);
- return bins
- .map(
- (c) =>
- SPARK_CHARS[maxCount === 0 ? 0 : Math.round((c / maxCount) * (SPARK_CHARS.length - 1))],
- )
- .join("");
- }
- function ratioBar(numerator: number, denominator: number, width: number): string {
- if (denominator <= 0 || width <= 0) return "";
- const ratio = Math.max(0, Math.min(1, numerator / denominator));
- if (width < 3) {
- const glyphIndex = Math.round(ratio * (RATIO_PARTIAL_CHARS.length - 1));
- return RATIO_PARTIAL_CHARS[glyphIndex] || "█";
- }
- const innerWidth = Math.max(1, width - 2);
- const filledWidth = ratio * innerWidth;
- let fullCells = Math.floor(filledWidth);
- let partialIndex = Math.round((filledWidth - fullCells) * 8);
- if (partialIndex === 8) {
- fullCells += 1;
- partialIndex = 0;
- }
- if (fullCells >= innerWidth) {
- fullCells = innerWidth;
- partialIndex = 0;
- }
- const partial = partialIndex > 0 ? RATIO_PARTIAL_CHARS[partialIndex] : "";
- const usedCells = fullCells + (partial ? 1 : 0);
- const emptyCells = Math.max(0, innerWidth - usedCells);
- return `│${"█".repeat(fullCells)}${partial}${" ".repeat(emptyCells)}│`;
- }
- function rankedFrequencyStrip(stats: ColumnStats, width: number): string {
- if (width <= 0 || !stats.top?.length) return "";
- const top = stats.top.filter(([, count]) => Number.isFinite(count) && count > 0);
- if (!top.length) return "";
- const hasOther = (stats.distinct_count ?? top.length) > top.length;
- const maxWidth = Math.min(width, top.length + (hasOther ? 1 : 0));
- if (maxWidth <= 0) return "";
- const topWidth = hasOther && maxWidth > 1 ? maxWidth - 1 : maxWidth;
- const visibleTop = top.slice(0, topWidth);
- const maxCount = Math.max(...visibleTop.map(([, count]) => count));
- const glyphs = visibleTop
- .map(([, count]) => {
- const index = Math.max(0, Math.ceil((count / maxCount) * SPARK_CHARS.length) - 1);
- return SPARK_CHARS[index];
- })
- .join("");
- return hasOther && maxWidth > visibleTop.length ? `${glyphs}·` : glyphs;
- }
- function sparklineForColumn(
- rows: string[][],
- ci: number,
- stats: ColumnStats | null,
- colType: string,
- width: number,
- ): string {
- if (stats?.kind === "boolean") {
- const t = stats.true_count ?? 0;
- const f = stats.false_count ?? 0;
- const total = t + f;
- if (total === 0) return "";
- return ratioBar(t, total, width);
- }
- if (stats?.kind === "numeric" || /int|float|decimal|uint/.test(colType)) {
- const nums: number[] = [];
- for (const row of rows) {
- const n = parseFloat(row[ci]);
- if (!isNaN(n)) nums.push(n);
- }
- return sparkline(nums, width);
- }
- if (stats?.kind === "string" && stats.top && stats.top.length > 0) {
- return rankedFrequencyStrip(stats, width);
- }
- return "";
- }
- class DataTable {
- private columns: string[];
- private rows: string[][];
- private totalRows: number;
- private colTypes: string[];
- private colStats: (ColumnStats | null)[];
- private theme: Theme;
- private cachedLines?: string[];
- private cachedWidth?: number;
- private indent: number;
- private footerText?: string;
- constructor(
- columns: string[],
- rows: string[][],
- totalRows: number,
- colTypes: string[],
- colStats: (ColumnStats | null)[],
- theme: Theme,
- indent: number = 0,
- footerText?: string,
- ) {
- this.columns = columns;
- this.rows = rows;
- this.totalRows = totalRows;
- this.colTypes = colTypes;
- this.colStats = colStats;
- this.theme = theme;
- this.indent = indent;
- this.footerText = footerText;
- }
- invalidate(): void {
- this.cachedLines = undefined;
- this.cachedWidth = undefined;
- }
- render(width: number): string[] {
- if (this.cachedLines && this.cachedWidth === width) {
- return this.cachedLines;
- }
- const t = this.theme;
- const numRows = this.rows.length;
- const totalCols = this.columns.length;
- const MIN_COL_W = 6;
- // Calculate natural column widths: max of header, type, stat, and data
- const naturalWidths = this.columns.map((col, ci) => {
- let w = col.length;
- w = Math.max(w, (this.colTypes[ci] ?? "").length);
- const statStr = formatStat(this.colStats[ci] ?? null);
- w = Math.max(w, statStr.length);
- for (const row of this.rows) {
- w = Math.max(w, (row[ci] ?? "").length);
- }
- return w;
- });
- // Greedily fit columns left-to-right within the available width.
- // Each column costs its width + 3 chars of border ("│ " + " │").
- let budget = width - 1; // leading "│"
- let visibleCount = 0;
- for (let i = 0; i < totalCols; i++) {
- const colCost = Math.max(naturalWidths[i], MIN_COL_W) + 3;
- if (budget - colCost < 0 && visibleCount > 0) break;
- budget -= colCost;
- visibleCount++;
- }
- visibleCount = Math.max(1, visibleCount);
- const hiddenCols = totalCols - visibleCount;
- // Slice to visible columns
- const columns = this.columns.slice(0, visibleCount);
- const colTypes = this.colTypes.slice(0, visibleCount);
- const colStats = this.colStats.slice(0, visibleCount);
- const rows = this.rows.map((r) => r.slice(0, visibleCount));
- const numCols = columns.length;
- const colWidths = naturalWidths.slice(0, visibleCount);
- // Shrink proportionally only if still over budget after column pruning
- const borderOverhead = 1 + numCols * 3;
- const totalColWidth = colWidths.reduce((a, b) => a + b, 0);
- const availableForCols = width - borderOverhead;
- if (totalColWidth > availableForCols && availableForCols > numCols) {
- const ratio = availableForCols / totalColWidth;
- for (let i = 0; i < numCols; i++) {
- colWidths[i] = Math.max(MIN_COL_W, Math.floor(colWidths[i] * ratio));
- }
- }
- const pad = (s: string, w: number) => {
- const vw = visibleWidth(s);
- return vw >= w ? truncateToWidth(s, w, "…") : s + " ".repeat(w - vw);
- };
- const rpad = (s: string, w: number) => {
- const vw = visibleWidth(s);
- return vw >= w ? truncateToWidth(s, w, "…") : " ".repeat(w - vw) + s;
- };
- // Detect numeric columns for right-alignment
- const isNumeric = colTypes.map((dt) => /int|float|decimal|uint/.test(dt));
- const align = (s: string, ci: number, w: number) => (isNumeric[ci] ? rpad(s, w) : pad(s, w));
- const lines: string[] = [];
- // ── Top border ──
- const topBorder = t.fg("muted", "┌" + colWidths.map((w) => "─".repeat(w + 2)).join("┬") + "┐");
- lines.push(topBorder);
- // ── Column headers ──
- const headerCells = columns.map((col, ci) => t.fg("accent", t.bold(pad(col, colWidths[ci]))));
- lines.push(
- t.fg("muted", "│") + " " + headerCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
- );
- // ── Type row ──
- const typeCells = colTypes.map((dt, ci) => t.fg("dim", pad(dt, colWidths[ci])));
- lines.push(
- t.fg("muted", "│") + " " + typeCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
- );
- // ── Sparkline row ──
- const sparkCells = colStats.map((stats, ci) => {
- const spark = sparklineForColumn(rows, ci, stats, colTypes[ci] ?? "", colWidths[ci]);
- return t.fg("dim", pad(spark, colWidths[ci]));
- });
- lines.push(
- t.fg("muted", "│") + " " + sparkCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
- );
- // ── Stats row ──
- const statCells = colStats.map((stats, ci) => {
- const statStr = formatStat(stats);
- return t.fg("dim", pad(statStr, colWidths[ci]));
- });
- lines.push(
- t.fg("muted", "│") + " " + statCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
- );
- // ── Header separator ──
- const headerSep = t.fg("muted", "╞" + colWidths.map((w) => "═".repeat(w + 2)).join("╪") + "╡");
- lines.push(headerSep);
- // ── Data rows ──
- for (let r = 0; r < numRows; r++) {
- const row = rows[r];
- const cells = row.map((v, ci) => align(v, ci, colWidths[ci]));
- const rowStr =
- t.fg("muted", "│") + " " + cells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│");
- lines.push(rowStr);
- }
- // ── Bottom border ──
- const botBorder = t.fg("muted", "└" + colWidths.map((w) => "─".repeat(w + 2)).join("┴") + "┘");
- lines.push(botBorder);
- // ── Footer info ──
- const showingRows = numRows < this.totalRows ? `showing ${numRows} of ` : "";
- const hiddenSuffix = hiddenCols > 0 ? ` (${hiddenCols} more columns)` : "";
- const infoText =
- this.footerText ?? `${showingRows}${this.totalRows} rows × ${totalCols} columns`;
- const info = t.fg("dim", `${infoText}${hiddenSuffix}`);
- lines.push(info);
- // Indent all lines to align with Out[n]: prompt
- const indent = " ".repeat(this.indent);
- for (let i = 0; i < lines.length; i++) {
- lines[i] = indent + lines[i];
- }
- this.cachedLines = lines;
- this.cachedWidth = width;
- return lines;
- }
- }
- // --- output formatting -------------------------------------------------------
- function stripAnsi(s: string): string {
- const esc = String.fromCharCode(27);
- return s.replace(new RegExp(`${esc}\\[[0-9;]*[A-Za-z]`, "g"), "");
- }
- function formatResult(result: CellResult): {
- content: (TextContent | ImageContent)[];
- isError: boolean;
- } {
- const outputs = result.outputs ?? [];
- const isError =
- result.status === "error" ||
- result.status === "kernel_error" ||
- result.status === "kernel_failed" ||
- outputs.some((o) => o.outputType === "error");
- const parts: (TextContent | ImageContent)[] = [];
- const header = `cell ${result.cellId} [${result.executionCount ?? "?"}] ${result.status}`;
- const textChunks: string[] = [];
- for (const o of outputs) {
- switch (o.outputType) {
- case "stream": {
- const prefix = o.name === "stderr" ? "[stderr] " : "";
- textChunks.push(prefix + (o.text ?? ""));
- break;
- }
- case "execute_result":
- case "display_data": {
- if (!o.dataJson) break;
- let data: Record<string, { type: string; value: unknown }>;
- try {
- data = JSON.parse(o.dataJson);
- } catch {
- break;
- }
- const hasImage = Object.keys(data).some(
- (m) => m.startsWith("image/") && m !== "image/svg+xml",
- );
- // Text-ish rep for the agent. Skip generic Figure reprs when we
- // also have an image — the image is more useful.
- const textRep =
- (data["text/llm+plain"]?.value as string | undefined) ??
- (data["text/plain"]?.value as string | undefined);
- if (textRep && !(hasImage && /^<Figure[^>]*>/.test(textRep.trim()))) {
- textChunks.push(String(textRep));
- }
- // Attach images directly so the model can see them.
- for (const [mime, entry] of Object.entries(data)) {
- if (!mime.startsWith("image/")) continue;
- if (mime === "image/svg+xml") continue; // text, not a raster image
- if (entry?.type !== "binary" || typeof entry.value !== "string") continue;
- // Dedupe images we've already emitted (Jupyter often sends the
- // same image as both execute_result and display_data).
- const dup = parts.some(
- (p) =>
- p.type === "image" &&
- (p as ImageContent).data === entry.value &&
- (p as ImageContent).mimeType === mime,
- );
- if (dup) continue;
- parts.push({
- type: "image",
- mimeType: mime,
- data: entry.value,
- } as ImageContent);
- }
- break;
- }
- case "error": {
- const tb = Array.isArray(o.traceback) ? o.traceback.join("\n") : "";
- textChunks.push(tb || `${o.ename ?? "Error"}: ${o.evalue ?? ""}`);
- break;
- }
- default:
- textChunks.push(`[${o.outputType} output]`);
- }
- }
- const body = stripAnsi(textChunks.join("").replace(/\n+$/, ""));
- parts.unshift({
- type: "text",
- text: body ? `${header}\n${body}` : header,
- });
- return { content: parts, isError };
- }
- function parseJsonObject(raw: string | undefined): Record<string, any> | undefined {
- if (!raw) return undefined;
- try {
- const parsed = JSON.parse(raw);
- return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
- } catch {
- return undefined;
- }
- }
- function parseArrowManifestEntry(entry: any): ArrowStreamManifest | undefined {
- if (!entry || typeof entry !== "object") return undefined;
- let value = entry.value;
- if (entry.type === "text" && typeof value === "string") {
- try {
- value = JSON.parse(value);
- } catch {
- return undefined;
- }
- }
- if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
- return value as ArrowStreamManifest;
- }
- function parseTableManifest(dataJson: string | undefined): ArrowStreamManifest | undefined {
- const data = parseJsonObject(dataJson);
- return parseArrowManifestEntry(data?.[ARROW_STREAM_MANIFEST_MIME]);
- }
- function resolveManifestChunkPaths(
- manifest: ArrowStreamManifest,
- rn: Pick<RuntimedNode, "resolveBlobPath"> | undefined,
- ): string[] {
- const resolveBlobPath = rn?.resolveBlobPath;
- if (!resolveBlobPath) return [];
- const paths: string[] = [];
- for (const chunk of manifest.chunks ?? []) {
- if (typeof chunk.hash !== "string") continue;
- const resolved = resolveBlobPath(chunk.hash);
- if (typeof resolved === "string" && resolved.length > 0) {
- paths.push(resolved);
- }
- }
- return paths;
- }
- function findLegacyParquetBlobPath(result: CellResult): string | undefined {
- const source = findTableSource(result, undefined);
- return source?.kind === "parquet" ? source.path : undefined;
- }
- export function findTableSource(
- result: CellResult,
- rn?: Pick<RuntimedNode, "resolveBlobPath">,
- ): TableSource | undefined {
- for (const o of result.outputs ?? []) {
- const paths = parseJsonObject(o.blobPathsJson);
- const parquetPath = paths?.[PARQUET_MIME];
- if (typeof parquetPath === "string") return { kind: "parquet", path: parquetPath };
- const arrowPath = paths?.[ARROW_STREAM_MIME];
- if (typeof arrowPath === "string") return { kind: "arrow", path: arrowPath };
- }
- for (const o of result.outputs ?? []) {
- const manifest = parseTableManifest(o.dataJson);
- if (manifest) {
- return {
- kind: "arrow-manifest",
- manifest,
- chunkPaths: resolveManifestChunkPaths(manifest, rn),
- };
- }
- }
- return undefined;
- }
- function parseSummaryStats(summary: TableSummaryResult | undefined): {
- colTypes: string[];
- colStats: (ColumnStats | null)[];
- } {
- if (!summary) return { colTypes: [], colStats: [] };
- return {
- colTypes: summary.columns.map((c) => c.dataType),
- colStats: summary.columns.map((c) => {
- try {
- return JSON.parse(c.statsJson) as ColumnStats;
- } catch {
- return null;
- }
- }),
- };
- }
- function renderDataTableText(
- page: TableRowPage,
- count: number | undefined,
- theme: Theme,
- width: number,
- colTypes: string[],
- colStats: (ColumnStats | null)[],
- footerText?: string,
- ): string {
- const prompt = count != null ? `Out[${count}]:` : "Out:";
- const promptStr = theme.fg("muted", prompt);
- const indent = prompt.length + 1;
- const dt = new DataTable(
- page.columns,
- page.rows,
- page.totalRows,
- page.columns.map((_, i) => colTypes[i] ?? ""),
- page.columns.map((_, i) => colStats[i] ?? null),
- theme,
- indent,
- footerText,
- );
- const tableLines = dt.render(width - indent);
- const indentStr = " ".repeat(indent);
- if (tableLines.length > 0 && tableLines[0].startsWith(indentStr)) {
- tableLines[0] = `${promptStr} ${tableLines[0].slice(indent)}`;
- }
- return tableLines.join("\n");
- }
- function manifestColumns(manifest: ArrowStreamManifest): ArrowManifestColumn[] {
- return (manifest.schema?.columns ?? []).filter(
- (column) => column && typeof column.name === "string",
- );
- }
- function manifestIncludedRows(manifest: ArrowStreamManifest): number {
- const included = manifest.summary?.included_rows;
- if (typeof included === "number") return included;
- return (manifest.chunks ?? []).reduce((sum, chunk) => sum + (chunk.row_count ?? 0), 0);
- }
- function manifestTotalRows(manifest: ArrowStreamManifest): number {
- const total = manifest.summary?.total_rows;
- if (typeof total === "number") return total;
- return manifestIncludedRows(manifest);
- }
- function manifestFooterText(manifest: ArrowStreamManifest, columnCount: number): string {
- const included = manifestIncludedRows(manifest);
- const total = manifestTotalRows(manifest);
- const sampled = Boolean(manifest.summary?.sampled);
- const rowText = manifest.complete
- ? sampled && total > included
- ? `sampled ${included} of ${total}`
- : `${total}`
- : total > 0
- ? `loading ${included}/${total}`
- : `loading ${included}`;
- return `${rowText} rows × ${columnCount} columns`;
- }
- function renderManifestSkeletonText(
- source: Extract<TableSource, { kind: "arrow-manifest" }>,
- count: number | undefined,
- theme: Theme,
- width: number,
- ): string | undefined {
- const columns = manifestColumns(source.manifest);
- if (!columns.length) return undefined;
- const page: TableRowPage = {
- columns: columns.map((column) => column.name),
- rows: [],
- totalRows: manifestTotalRows(source.manifest),
- offset: 0,
- };
- return renderDataTableText(
- page,
- count,
- theme,
- width,
- columns.map((column) => column.type ?? ""),
- columns.map(() => null),
- manifestFooterText(source.manifest, columns.length),
- );
- }
- export function renderTableTextForSource(
- source: TableSource | undefined,
- count: number | undefined,
- theme: Theme,
- rn: RuntimedNode,
- width: number = process.stdout.columns || 120,
- ): string | undefined {
- if (!source) return undefined;
- try {
- if (source.kind === "parquet") {
- const page = rn.readParquetFile(source.path, 0, 40);
- if (!page?.columns?.length) return undefined;
- const { colTypes, colStats } = parseSummaryStats(rn.summarizeParquetFile?.(source.path));
- return renderDataTableText(page, count, theme, width, colTypes, colStats);
- }
- if (source.kind === "arrow") {
- const page = rn.readArrowFile?.(source.path, 0, 40);
- if (!page?.columns?.length) return undefined;
- const { colTypes, colStats } = parseSummaryStats(rn.summarizeArrowFile?.(source.path));
- return renderDataTableText(page, count, theme, width, colTypes, colStats);
- }
- const expectedChunkCount = (source.manifest.chunks ?? []).filter(
- (chunk) => typeof chunk.hash === "string",
- ).length;
- const hasAllChunkPaths =
- expectedChunkCount > 0 && source.chunkPaths.length === expectedChunkCount;
- if (source.manifest.complete && hasAllChunkPaths && rn.readArrowChunks) {
- try {
- const page = rn.readArrowChunks(source.chunkPaths, 0, 40);
- if (page?.columns?.length) {
- const { colTypes, colStats } = parseSummaryStats(
- rn.summarizeArrowChunks?.(source.chunkPaths),
- );
- return renderDataTableText(page, count, theme, width, colTypes, colStats);
- }
- } catch {
- // Fall through to the manifest skeleton if chunk files are unavailable.
- }
- }
- return renderManifestSkeletonText(source, count, theme, width);
- } catch {
- return undefined;
- }
- }
- // --- extension ---------------------------------------------------------------
- // Braille frames for the "waiting on first token" spinner shown in `In [*]:`
- // before any input_json_delta arrives. Anthropic validates the JSON server-side,
- // so the gap between toolcall_start and the first delta can be hundreds of ms.
- const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
- const SPINNER_INTERVAL_MS = 80;
- type InCallState = {
- spinner?: { frame: number; timer: ReturnType<typeof setInterval> };
- };
- const PYTHON_PARAMS = Type.Object({
- code: Type.String({
- description:
- "Python source to execute in the persistent notebook session. Use print(...) for side effects; the last expression's repr is returned as the result.",
- }),
- dependencies: Type.Optional(
- Type.Array(Type.String(), {
- description:
- "Packages to add before executing this code. On the first call they are recorded before the kernel starts; on later calls they are hot-synced into the running environment.",
- }),
- ),
- timeout_secs: Type.Optional(
- Type.Number({
- description: "Max seconds to wait for execution (default 120).",
- default: 120,
- }),
- ),
- });
- const ADD_DEPENDENCIES_PARAMS = Type.Object({
- packages: Type.Array(Type.String(), {
- description: "Package specs (e.g. ['matplotlib', 'pandas>=2']).",
- }),
- });
- type AddDependenciesDetails = {
- notebook_id?: string;
- packages?: string[];
- };
- const SAVE_NOTEBOOK_PARAMS = Type.Object({
- path: Type.Optional(
- Type.String({
- description:
- "File path to save to (e.g. './analysis.ipynb'). If omitted, saves to the original location.",
- }),
- ),
- });
- type SaveNotebookDetails = {
- notebook_id: string;
- path?: string;
- };
- export default function nteractReplExtension(pi: ExtensionAPI) {
- const bootstrap = detectBootstrap();
- if (bootstrap.kind === "missing") {
- // Surface a one-liner toast each session so the user sees the hint without
- // having to invoke the tool first.
- pi.on("session_start", async (_event, ctx) => {
- ctx.ui.notify(INSTALL_HINT, "warning");
- });
- // Register python_repl with a stub execute() so the LLM can still advertise
- // the capability and surface install guidance the moment it tries to run
- // Python. Throwing routes the message into the tool-result channel that the
- // model relays back to the user.
- pi.registerTool({
- name: "python_repl",
- label: "Python REPL",
- description:
- "Execute Python in your persistent REPL. Requires the nteract daemon (runtimed). " +
- "If unavailable, recommend the user install with `curl -fsSL https://sh.nteract.io | bash` " +
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 965 on GitHub
- "or download the desktop app at https://nteract.io.",
- promptSnippet:
- "python_repl: requires the nteract daemon. Install with `curl -fsSL https://sh.nteract.io | bash` or via https://nteract.io.",
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 968 on GitHub
- parameters: PYTHON_PARAMS,
- async execute() {
- throw new Error(INSTALL_HINT);
- },
- });
- return;
- }
- const rn = bootstrap.rn;
- let session: Session | null = null;
- let opening: Promise<Session> | null = null;
- let nextExecCount: number | null = 1;
- let executionViewSubscription: SubscriptionLike | null = null;
- function disposeExecutionViewTracking(): void {
- const sub = executionViewSubscription;
- executionViewSubscription = null;
- sub?.unsubscribe?.();
- sub?.dispose?.();
- }
- function trackExecutionView(sess: Session): void {
- disposeExecutionViewTracking();
- executionViewSubscription =
- sess.executionViewChanges$?.subscribe((changeset) => {
- for (const [, snapshot] of changeset.execution_upserts ?? []) {
- const count = snapshot.execution_count;
- if (typeof count === "number") {
- nextExecCount = Math.max(nextExecCount ?? 1, count + 1);
- }
- }
- }) ?? null;
- }
- async function addDependenciesAndSync(sess: Session, packages: string[]): Promise<void> {
- const unique = Array.from(new Set(packages.map((pkg) => pkg.trim()).filter(Boolean)));
- if (!unique.length) return;
- if (sess.addDependencies) {
- await sess.addDependencies(unique);
- } else if (sess.addUvDependency) {
- for (const pkg of unique) {
- await sess.addUvDependency(pkg);
- }
- } else {
- throw new Error("@runtimed/node Session does not support dependency edits");
- }
- await sess.syncEnvironment();
- }
- async function ensureSession(initialDependencies: string[] = []): Promise<Session> {
- const dependencies = Array.from(
- new Set(initialDependencies.map((pkg) => pkg.trim()).filter(Boolean)),
- );
- if (session) {
- await addDependenciesAndSync(session, dependencies);
- return session;
- }
- if (opening) {
- const opened = await opening;
- await addDependenciesAndSync(opened, dependencies);
- return opened;
- }
- opening = (async () => {
- // Omit socketPath so the binding resolves through defaultSocketPath(),
- // which honors RUNTIMED_SOCKET_PATH / RUNTIMED_WORKSPACE_PATH and the
- // channel auto-detect.
- session = await rn.createNotebook({
- runtime: "python",
- workingDir: process.cwd(),
- peerLabel: "pi",
- description: "pi Python REPL",
- dependencies,
- });
- trackExecutionView(session);
- return session;
- })();
- try {
- return await opening;
- } finally {
- opening = null;
- }
- }
- pi.registerTool<typeof PYTHON_PARAMS, unknown, InCallState>({
- name: "python_repl",
- label: "Python REPL",
- description:
- "Execute Python in your persistent REPL. Backed by a real IPython runtime. Variables, imports, and state stick around between calls. The last expression is the result; use print() or display() for intermediate output. Images (matplotlib, PIL, widgets) are returned inline.",
- promptSnippet:
- "python_repl: run Python in your persistent REPL (variables and imports persist; returns stdout + last expression + images).",
- promptGuidelines: [
- "Use `python_repl` for data analysis, plotting, and multi-step workflows. State persists between calls in a real IPython runtime.",
- "Variables and imports stick around. No need to re-import or redefine on every turn unless the user has reloaded the session.",
- "The last expression is the result; use print() or display() for intermediate output.",
- "Images (matplotlib, PIL, widgets) come back inline. The user sees them if their terminal supports graphics.",
- "Pass `dependencies` on the first call to pre-install packages before the kernel starts.",
- "Use `python_add_dependencies` to install packages mid-session without restarting the kernel.",
- ],
- parameters: PYTHON_PARAMS,
- renderCall(args, theme, _context) {
- const text =
- (_context.lastComponent as InstanceType<typeof Text> | undefined) ?? new Text("", 0, 0);
- const code = (args?.code ?? "").replace(/^\n+/, "");
- const count = nextExecCount;
- const prompt = count != null ? `In [${count}]:` : "In [*]:";
- const promptStr = theme.fg("accent", theme.bold(prompt));
- // Anthropic gates input_json_delta on server-side validation, so there is
- // a visible pause between toolcall_start and the first token of `code`.
- // Show a braille spinner in the prompt slot until either the first
- // character streams in or the call resolves another way.
- const state = _context.state as InCallState;
- const waitingForFirstToken =
- !code && !_context.executionStarted && !_context.argsComplete && !_context.isError;
- if (waitingForFirstToken) {
- if (!state.spinner) {
- const timer = setInterval(() => {
- const s = state.spinner;
- if (!s) return;
- s.frame = (s.frame + 1) % SPINNER_FRAMES.length;
- _context.invalidate();
- }, SPINNER_INTERVAL_MS);
- // Don't keep the event loop alive on the spinner alone.
- timer.unref?.();
- state.spinner = { frame: 0, timer };
- }
- const frame = SPINNER_FRAMES[state.spinner.frame];
- text.setText(`${promptStr} ${theme.fg("muted", frame)}`);
- return text;
- }
- if (state.spinner) {
- clearInterval(state.spinner.timer);
- state.spinner = undefined;
- }
- const lines = highlightCode(code, "python");
- // Indent continuation lines to align with first line after prompt
- const pad = " ".repeat(prompt.length + 1);
- const formatted = lines
- .map((l, i) => (i === 0 ? `${promptStr} ${l}` : `${pad}${l}`))
- .join("\n");
- text.setText(formatted);
- return text;
- },
- renderResult(result, _options, theme, _context) {
- const details = (result as any).details ?? {};
- const count = details.execution_count;
- const isErr = details.is_error;
- // Update the closure count for the next renderCall
- if (count != null) {
- nextExecCount = count + 1;
- }
- const tableSource =
- (details.table_source as TableSource | undefined) ??
- (typeof details.parquet_blob_path === "string"
- ? ({ kind: "parquet", path: details.parquet_blob_path } as TableSource)
- : undefined);
- const tableText = renderTableTextForSource(tableSource, count, theme, rn);
- if (tableText) {
- const text =
- (_context.lastComponent instanceof Text ? _context.lastComponent : undefined) ??
- new Text("", 0, 0);
- text.setText(tableText);
- return text;
- }
- // Extract text output from content
- const textContent = (result.content ?? [])
- .filter((c: any) => c.type === "text")
- .map((c: any) => c.text)
- .join("\n");
- // Strip the "cell <id> [n] status" header we put in the text content
- const body = textContent.replace(/^cell \S* \[[^\]]*\] \S*\n?/, "").trim();
- const text =
- (_context.lastComponent instanceof Text ? _context.lastComponent : undefined) ??
- new Text("", 0, 0);
- if (!body) {
- // No output — just show a check/cross
- const icon = isErr ? theme.fg("error", "\u2717") : theme.fg("success", "\u2713");
- text.setText(icon);
- } else if (isErr) {
- text.setText(theme.fg("error", body));
- } else {
- const prompt = count != null ? `Out[${count}]:` : "Out:";
- const promptStr = theme.fg("muted", prompt);
- const pad = " ".repeat(prompt.length + 1);
- const bodyLines = body.split("\n");
- const formatted = bodyLines
- .map((l: string, i: number) => (i === 0 ? `${promptStr} ${l}` : `${pad}${l}`))
- .join("\n");
- text.setText(formatted);
- }
- return text;
- },
- async execute(_toolCallId, params, signal, onUpdate) {
- if (signal?.aborted) throw new Error("aborted");
- const sess = await ensureSession(params.dependencies ?? []);
- const timeoutSecs = Math.max(1, params.timeout_secs ?? 120);
- const result = await sess.runCell(params.code, {
- timeoutMs: Math.round(timeoutSecs * 1000),
- onUpdate: (progress) => {
- const { content, isError } = formatResult(progress);
- onUpdate?.({
- content,
- details: {
- notebook_id: sess.notebookId,
- cell_id: progress.cellId,
- execution_id: progress.executionId,
- status: progress.status,
- execution_count: progress.executionCount,
- is_error: isError,
- table_source: findTableSource(progress, rn),
- parquet_blob_path: findLegacyParquetBlobPath(progress),
- streaming: true,
- },
- });
- },
- });
- const tableSource = findTableSource(result, rn);
- const { content, isError } = formatResult(result);
- return {
- content,
- details: {
- notebook_id: sess.notebookId,
- cell_id: result.cellId,
- execution_id: result.executionId,
- status: result.status,
- execution_count: result.executionCount,
- is_error: isError,
- table_source: tableSource,
- parquet_blob_path: tableSource?.kind === "parquet" ? tableSource.path : undefined,
- runtime: sess.getRuntimeStatus
- ? await sess.getRuntimeStatus().catch(() => undefined)
- : undefined,
- },
- };
- },
- });
- pi.registerTool<typeof ADD_DEPENDENCIES_PARAMS, AddDependenciesDetails>({
- name: "python_add_dependencies",
- label: "Add Dependencies",
- description:
- "Install packages into the running Python environment without restarting. Accepts pip-style specs like 'matplotlib', 'numpy>=2', 'requests'. The kernel stays hot.",
- promptSnippet:
- "python_add_dependencies: install packages into the running Python session (no restart needed).",
- parameters: ADD_DEPENDENCIES_PARAMS,
- async execute(_toolCallId, params, signal) {
- if (signal?.aborted) throw new Error("aborted");
- if (!params.packages.length) {
- return { content: [{ type: "text", text: "No packages given." }], details: {} };
- }
- const sess = await ensureSession();
- await addDependenciesAndSync(sess, params.packages);
- return {
- content: [
- {
- type: "text",
- text: `Installed into ${sess.notebookId}: ${params.packages.join(", ")}`,
- },
- ],
- details: { notebook_id: sess.notebookId, packages: params.packages },
- };
- },
- });
- pi.registerTool<typeof SAVE_NOTEBOOK_PARAMS, SaveNotebookDetails>({
- name: "python_save_notebook",
- label: "Save Notebook",
- description:
- "Save the current Python session as an .ipynb file. If no path is given, saves to the original location (if it was opened from a file). Provide a path to save elsewhere.",
- promptSnippet: "python_save_notebook: save the current session as an .ipynb file.",
- parameters: SAVE_NOTEBOOK_PARAMS,
- async execute(_toolCallId, params, signal) {
- if (signal?.aborted) throw new Error("aborted");
- const sess = await ensureSession();
- const savePath = params.path ? resolvePath(params.path) : undefined;
- await sess.saveNotebook(savePath);
- const where = savePath ?? "original location";
- return {
- content: [{ type: "text", text: `Notebook saved to ${where}` }],
- details: { notebook_id: sess.notebookId, path: savePath },
- };
- },
- });
- pi.registerCommand("python-reset", {
- description:
- "Start fresh: next /python_repl call opens a new kernel (clean slate, no prior variables or imports)",
- handler: async (_args, ctx) => {
- const old = session;
- session = null;
- nextExecCount = 1;
- disposeExecutionViewTracking();
- if (old) {
- try {
- if (old.shutdownNotebook) {
- await old.shutdownNotebook();
- } else {
- await old.close();
- }
- } catch {}
- }
- ctx.ui.notify(
- "Python session closed. Next python_repl call will start a fresh kernel.",
- "info",
- );
- },
- });
- pi.on("session_shutdown", async () => {
- disposeExecutionViewTracking();
- if (session) {
- try {
- if (session.shutdownNotebook) {
- await session.shutdownNotebook();
- } else {
- await session.close();
- }
- } catch {}
- session = null;
- }
- });
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.