@damurka/jovian 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 David Kariuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The bundled R package "hera" (packages/hera) is a separate work with its own
+copyright holders and MIT license; see packages/hera/LICENSE.

package/README.md

@@ -0,0 +1,175 @@
+# Jovian
+
+[![CI](https://github.com/damurka/jovian/actions/workflows/ci.yml/badge.svg)](https://github.com/damurka/jovian/actions/workflows/ci.yml)
+
+Jovian runs **R** and **Python** as supervised Jupyter kernels that you can drive from Node.js and Electron. Every session is its own operating-system process with its own embedded interpreter, so one session blocking on a long call (a Shiny app, a slow loop) never starves another, and a kernel that crashes takes only its own session with it.
+
+```typescript
+import { SessionManager } from '@damurka/jovian';
+
+const manager = new SessionManager();
+
+const r = await manager.createSession({ kernelType: 'r', rHome: process.env.R_HOME, workingDirectory: '/projects/analysis' });
+const result = await r.execute('x <- 1:10; mean(x)');
+console.log(result.success, result.output);
+
+const py = await manager.createSession({ kernelType: 'python', pythonHome: '/path/to/python' });
+console.log((await py.execute('sum(range(1, 11))')).success);
+
+await manager.stopAll();
+```
+
+The pieces are named after moons of Jupiter:
+
+| Name | Role |
+|---|---|
+| **Jovian** | This npm package: a TypeScript client (`lib/`) over the native binaries below. |
+| **Adrastea** | Language-neutral Jupyter kernel framework — wire protocol, ZMQ transport, request loop, the abstract `Interpreter` interface (`native/`, a static library). |
+| **Elara** | The R kernel: embeds R on top of Adrastea (`elara` / `elara.exe`). |
+| **Carpo** | The Python kernel: embeds CPython on top of Adrastea the same way (`carpo` / `carpo.exe`). |
+| **Themisto** | The kernel supervisor: spawns and monitors one kernel process per session and re-exposes sessions over HTTP + WebSocket (`themisto` / `themisto.exe`). |
+| [hera](packages/hera) | The R companion package loaded inside every Elara session (execution, completion, inspection, comms). |
+
+## Install
+
+```bash
+npm install @damurka/jovian
+```
+
+The package ships **prebuilt** `themisto`, `elara` and `carpo` binaries — no compiler, CMake or vcpkg — for **Windows x64** (`win32-x64`), **Linux x64** (`linux-x64`) and **macOS on Apple Silicon** (`darwin-arm64`); Intel Macs and Linux on ARM are not published yet, so build from source there and point `JOVIAN_NATIVE_DIR` at `dist/native/Release`. npm installs the matching `@damurka/jovian-<os>-<cpu>` package automatically as an optional dependency, so do not install with `--omit=optional` / `--no-optional`. Node.js ≥ 22.4 is required (ES modules; global `fetch` and `WebSocket`).
+
+What you must already have on the machine:
+
+- **R** (4.2 or newer; a build with a shared library, which the CRAN/Posit binaries and distribution packages are) for R sessions. Pass its location as `rHome` (`R RHOME` prints it). The `hera` R package that every R session needs ships inside the npm package and is installed into R on a session's first start, which needs the `remotes` package and `hera`'s CRAN dependencies (`cli`, `evaluate`, `glue`, `IRdisplay`, `jsonlite`, `R6`, `repr`, `rlang`):
+
+  ```r
+  install.packages(c("remotes", "cli", "evaluate", "glue", "IRdisplay", "jsonlite", "R6", "repr", "rlang"))
+  ```
+
+- **Python 3** with its shared library (optional, for Python sessions); pass `pythonHome` (`python3 -c "import sys; print(sys.prefix)"`).
+- **Linux:** `libuuid` (`libuuid1`, present on nearly every system) and a glibc at least as new as the one the binaries were built against (Ubuntu 24.04's, 2.39). On an older distribution, [build from source](#requirements).
+- **macOS:** 14 or newer.
+- **Windows:** the [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist) (x64, 2015–2022) — the binaries use the dynamic C++ runtime; most machines already have it.
+
+The rest of this README is for building Jovian from source.
+
+## Features
+
+- **Two kernels, one API.** R (Elara) and Python (Carpo), chosen per session with `kernelType`.
+- **Execution** with streaming stdout/stderr, `execute_result`, rich `display_data` (R plots arrive as `image/png`), `update_display_data`, `clear_output`, and structured errors with tracebacks.
+- **Interactive input.** `input()` (Python) and `readline()` (R) round-trip over the Jupyter stdin channel; see [the input guide](docs/guides/interactive-input.md).
+- **Real interrupt.** `session.interrupt()` breaks running R and Python code (a sleeping call, a busy loop), not just the queue; the kernel keeps running afterwards. See [interrupting](docs/guides/interrupting.md).
+- **Working directory.** `workingDirectory` is where the kernel process starts (`getwd()` / `os.getcwd()`); it survives restarts.
+- **Protocol requests as methods.** `complete`, `inspect`, `isComplete`, `kernelInfo`, `commInfo`, `queryKernelHistory` — real Jupyter messages, answered by the kernel. See [API reference](docs/api/README.md).
+- **Comms.** Open a comm to a kernel-side target, or receive kernel-initiated ones with `session.on('comm', ...)`. See [comms](docs/guides/comms.md).
+- **`user_expressions` and `stop_on_error`.** Evaluate expressions after a cell succeeds; abort everything queued behind a failing cell.
+- **Protocol-driven lifecycle.** `stop()` sends the kernel a real `shutdown_request` (`restart: false`), `restart()` one with `restart: true`; the kernel's `shutdown_reply` surfaces as an event and an orderly exit is never reported as a crash.
+- **Crash detection in milliseconds.** The supervisor watches the OS process handle, with the ZMQ heartbeat as a backstop for a kernel that is alive but stuck. A crashed session can be `restart()`ed in place under the same session id.
+- **Restart with different options.** Switch R or Python installations on restart; unchanged options are kept ([details](docs/guides/sessions-lifecycle.md)).
+- **A browser playground** (Next.js) for exercising live sessions — see [`tools/playground`](tools/playground/README.md).
+- **Standard Jupyter launch mode.** `elara` and `carpo` can also be started directly by `jupyter lab` / `jupyter console` via a generated kernelspec (`npm run jupyter:kernelspec`), no supervisor involved.
+
+## Requirements
+
+*Building from source. To use the published package, see [Install](#install).*
+
+Jovian builds C++ (Adrastea, Elara, Carpo, Themisto) and TypeScript. R and Python are **runtime** dependencies of the kernels, not build-time ones: Elara and Carpo load R's and Python's shared libraries dynamically when a session starts, so the binaries build without either installed (R's headers are still needed to compile Elara).
+
+### All platforms
+
+| Requirement | Notes |
+|---|---|
+| **Git** | To clone the repo and vcpkg. |
+| **CMake ≥ 3.24** | Declared in `CMakeLists.txt`. The local build uses CMake 4.3.1 (the copy bundled with Visual Studio 2026). |
+| **A C++23-capable compiler** | `CMAKE_CXX_STANDARD 23` is required. See the platform sections for what is actually verified. |
+| **vcpkg** with `VCPKG_ROOT` set | Dependencies come from the manifest in `vcpkg.json` (pinned `builtin-baseline`): `nlohmann-json`, `cppzmq`, `zeromq`, `openssl`, `gtest`, `cpp-httplib`, `ixwebsocket`. Clone [microsoft/vcpkg](https://github.com/microsoft/vcpkg) and run its bootstrap script (`bootstrap-vcpkg.bat` / `bootstrap-vcpkg.sh`); CMake picks the manifest up through the toolchain file `$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake`. |
+| **Node.js** (recent LTS) | The library is ES modules compiled with `tsc`; the test files are `.ts` and are run directly with `node --test`, which needs a Node with built-in TypeScript type stripping (unflagged since Node 22.18 / 23.6). Developed on Node 24; CI uses the current LTS. Use the official build from nodejs.org: some distribution packages (Ubuntu's `nodejs`) omit type stripping and fail with `ERR_UNKNOWN_FILE_EXTENSION` on `.ts` files. Global `fetch` and `WebSocket` are used by the client. |
+| **R** (to run R sessions, and its headers to build Elara) | Developed against R 4.6.0; CI uses the latest release. On Windows, R ≥ 4.2 is needed for `readline()` to work over the stdin channel (older R still starts, but `readline()` cannot be answered). |
+| **The R package `hera`** and its dependencies | Every R session needs it. Its `Imports` (from `packages/hera/DESCRIPTION`) are `cli`, `evaluate`, `glue`, `IRdisplay`, `jsonlite`, `R6`, `repr`, `rlang`, `tools`, `utils`. CI installs them with `r-lib/actions/setup-r-dependencies` using `packages: local::packages/hera`; locally, install those packages from CRAN and run **`npm run hera:install`** (`R CMD INSTALL packages/hera`), or pass `heraSrcPath` so Elara installs it on first start (needs the `remotes` package; `heraSrcPath` has no default). Use `hera` >= 0.6.0.9001: earlier versions work but only show the output of one long-running R expression when it ends, not as it is produced — re-run `npm run hera:install` after pulling. |
+| **Python** (optional) | Only needed to run Python sessions and to run `CarpoTest`. Carpo does not include Python's headers or link Python at build time. A CPython 3 installation with its shared library: `python3NN.dll` on Windows, `libpython3.*.so` on Linux, `libpython3.*.dylib` on macOS. |
+
+### Windows
+
+- **Visual Studio with the “Desktop development with C++” workload** (MSVC, Windows SDK, and the bundled CMake). The repository is built and tested here with **Visual Studio 2026 (version 18), MSVC toolset v145**, generator `Visual Studio 18 2026`. CI builds on the GitHub `windows-latest` runner. Earlier Visual Studio versions have not been tried; the build needs MSVC's `/std:c++latest` C++23 mode.
+- `CMakePresets.json` also defines Ninja + `cl.exe` presets (`x64-debug`, `x64-release`, `x86-*`); they require `VCPKG_ROOT` and `VSINSTALLDIR` (open a *Developer PowerShell / Command Prompt*, or configure from Visual Studio).
+- vcpkg installs the `x64-windows` triplet (dynamic DLLs), which is why `dist/native/Release/` contains ZeroMQ/OpenSSL DLLs next to the executables.
+- R's DLL lives in `<R_HOME>\bin\x64`; pass it as `rPath` if it is not on `PATH`. You do **not** need Rtools.
+- Note that `npm run compile` uses `%VCPKG_ROOT%` (cmd.exe syntax); use `npm run build` from any shell.
+
+### Linux
+
+- A C++23 compiler, `cmake`, and vcpkg's own prerequisites (see the vcpkg docs). CI installs one extra package: **`uuid-dev`** (`sudo apt-get install uuid-dev`), because the GUID code calls `uuid_generate()` from libuuid.
+- R **must have been built with a shared library** (`--enable-R-shlib`; distribution packages and the CRAN/Posit binaries are). Elara `dlopen`s `$R_HOME/lib/libR.so`.
+- CI runs on `ubuntu-latest`. The full suite (native, unit, integration) was also run on **Ubuntu 26.04 under WSL**; notes for Debian/Ubuntu:
+  - `cmake/FindR.cmake` finds Debian's split R headers (`R.h` in `/usr/share/R/include`) by asking `R CMD config --cppflags`, so `r-base-dev` is enough.
+  - Carpo looks for libpython in `lib/`, `lib64/` and `lib/<arch>-linux-gnu/`, so a distribution Python works with `PYTHONHOME=/usr` (`sudo apt install python3`; add `python3-venv` to run CarpoTest's venv test).
+  - If `hera` fails to install with `undefined symbol: SETLENGTH`, the apt `r-cran-*` packages were built for a different R ABI: hide the site library (`R_LIBS_SITE=/nonexistent`) and install `hera`'s dependencies from CRAN into a private `R_LIBS_USER`, as CI does.
+  - The distribution's packaged Node.js has no TypeScript type stripping; use the official build from nodejs.org to run the `.ts` tests.
+  - macOS is covered only by CI.
+
+### macOS
+
+- A C++23-capable Apple clang (Xcode or the Command Line Tools); the build links the CoreFoundation framework. CI runs on `macos-latest` using the runner's preinstalled toolchain and installs nothing extra.
+- R must provide `libR.dylib` under `$R_HOME/lib` (CRAN's framework build does).
+
+### Environment variables
+
+| Variable | Used by | Meaning |
+|---|---|---|
+| `VCPKG_ROOT` | build | vcpkg checkout; used by `npm run build` and the CMake presets. |
+| `R_HOME` | runtime, tests, examples | R installation to use when `rHome` is not passed. `R RHOME` is used as a fallback by the tests and the playground. |
+| `R_PATH`, `R_LIBS` | examples, playground | Passed as `rPath` / `rLibs`. |
+| `PYTHONHOME` | runtime, tests | Python installation prefix when `pythonHome` is not passed. |
+| `JOVIAN_NATIVE_DIR` | `lib/` | Directory holding `themisto`, `elara` and `carpo`. Default: the installed `@damurka/jovian-<os>-<cpu>` package, else `dist/native/Release` in a source checkout. Use it to run against a *copy* of the binaries (Windows will not let you overwrite a running `.exe`). |
+| `ELARA_HERA_SRC` | Elara | Set for you from the `heraSrcPath` option: where Elara installs `hera` from if it is missing or older than the source. |
+
+## Building and testing
+
+```sh
+npm install --legacy-peer-deps   # CI uses `npm ci --legacy-peer-deps` (typescript and the eslint plugin disagree on peer versions)
+npm run build                    # native (elara + carpo + themisto, Release) into dist/native, then TypeScript into dist/lib
+```
+
+`npm run build` configures with `VCPKG_ROOT`'s toolchain file when the variable is set. The individual steps are `npm run build:native` (only `cmake --build`, after a configure) and `npm run build:lib` (`tsc --build`).
+
+```sh
+npm test                 # native ctest + TypeScript unit + integration tests (scripts/test.js)
+npm run test:unit        # TypeScript unit tests only (fake WebSocket, no processes)
+npm run test:integration # end-to-end: real themisto + real R / Python kernels
+```
+
+The TypeScript tests import the **compiled** library from `dist/`, so run `npm run build:lib` after changing anything in `lib/`. The integration tests skip themselves when the native binaries are not built, and the Python ones skip when no Python or no `carpo` is available. More in [docs/development.md](docs/development.md).
+
+Other scripts: `npm run hera:install` (install/update the `hera` R package from `packages/hera`), `npm run dev` (TypeScript watch mode), `npm run clean` (removes `dist/`), `npm run format`, `npm run lint`, `npm run jupyter:kernelspec` (write `kernel.json` files for `elara` and `carpo`; `-- --only=r` / `--only=python` for one).
+
+## Playground
+
+A browser UI (Next.js) for driving real R and Python sessions, with completion (`Tab`) and inspection (`Shift+Tab`, double-click in the output):
+
+```sh
+npm run playground:install   # once — the playground has its own node_modules
+npm run playground           # http://127.0.0.1:4173
+```
+
+See [`tools/playground/README.md`](tools/playground/README.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Prerequisites → build → your first R and Python session. |
+| [Architecture](docs/architecture/overview.md) | Components, process and thread model, message flows. |
+| [Protocol](docs/protocol.md) | Jupyter messages supported, Themisto's HTTP API and WebSocket frames. |
+| [API reference](docs/api/README.md) | `SessionManager`, `Session`, `Comm`, options and result types. |
+| Guides | [Interactive input](docs/guides/interactive-input.md) · [Interrupting](docs/guides/interrupting.md) · [Comms](docs/guides/comms.md) · [History](docs/guides/history.md) · [Session lifecycle](docs/guides/sessions-lifecycle.md) · [R and Python environments](docs/guides/environments.md) · [Playground](docs/guides/playground.md) |
+| [Kernels](docs/kernels.md) | How Elara and Carpo work, and where they differ. |
+| [Development](docs/development.md) | Repo layout, build system, test layers, CI, debugging. |
+| [Releasing](docs/releasing.md) | How the npm packages are built and published. |
+| [Troubleshooting](docs/troubleshooting.md) | Real error messages and what causes them. |
+| [C++ usage](docs/cpp-usage.md) | Using Adrastea from C++; writing a new language kernel. |
+
+Runnable examples are in [`examples/`](examples): [`basic/simple-execute.js`](examples/basic/simple-execute.js) (one session) and [`advanced/two-sessions.js`](examples/advanced/two-sessions.js) (two concurrent sessions, one blocking).
+
+## Status
+
+Both kernels support execute, streaming output, display data, errors, completion, inspection, `is_complete`, kernel info, history, comms, interactive input, real interrupt, and session restart / crash recovery. Elara additionally has a standard Jupyter connection-file launch mode alongside the Themisto-supervised one; Carpo's kernelspec is generated too but has not been exercised against a real `jupyter lab` / `jupyter console`. Carpo supports pointing a session at a venv's `site-packages`. Interrupt was verified on Windows; its POSIX implementation (`pthread_kill` of SIGINT to the interpreter thread) is covered by the same tests but relies on CI to run them on Linux and macOS.

package/docs/api/README.md

@@ -0,0 +1,55 @@
+# TypeScript API reference
+
+The `@damurka/jovian` package (ES modules) exports:
+
+```typescript
+import {
+    SessionManager, Session, Comm,          // classes
+    type EngineOptions, type ExecutionOptions, type ExecutionResult, type JupyterMessage,
+    // …every type in ./types (see types.md), plus the middleware classes
+} from '@damurka/jovian';
+```
+
+| Page | Contents |
+|---|---|
+| **This page** | `SessionManager`, events, errors and timeouts |
+| [`session.md`](session.md) | `Session` — every method, property and event; `Comm` |
+| [`types.md`](types.md) | `EngineOptions`, `ExecutionOptions`, `ExecutionResult`, reply content types, message types |
+
+## `SessionManager`
+
+Creates sessions and owns the one shared supervisor process (`themisto`) they all talk to. The supervisor is spawned lazily on the first `createSession()` and killed by `stopAll()` / `killAll()` (and, as a safety net, when the Node process exits).
+
+```typescript
+const manager = new SessionManager();
+```
+
+| Member | Description |
+|---|---|
+| `createSession(options?: EngineOptions): Promise<Session>` | Spawns a kernel process (per `options.kernelType`), waits until it has registered and the session's WebSocket is ready, and resolves with the `Session`. Rejects with the supervisor's message if the kernel could not start: `workingDirectory does not exist or is not a directory: …`, `no kernel executable is configured for kernelType 'python' …`, or — when the kernel process itself failed (R or Python not found, …) — `Kernel process exited before it could register -- check its stderr output for the actual error.` The *actual* R/Python error is printed on stderr with an `[elara]` / `[carpo]` prefix (see [Troubleshooting](../troubleshooting.md)). |
+| `stopAll(): Promise<void>` | Gracefully `stop()`s every session, then kills the supervisor. Call this before your process exits — **without it a script hangs**, because the supervisor's pipes keep Node's event loop alive. |
+| `killAll(): void` | Immediately force-closes every session and kills the supervisor. Use it as the fallback when `stopAll()` is racing a timeout (a kernel stuck inside `shiny::runApp()` cannot process a shutdown until that call returns). |
+
+The kernel binaries are looked up in this order: `$JOVIAN_NATIVE_DIR`; the installed `@damurka/jovian-<os>-<cpu>` package (its `bin/` directory); `dist/native/Release` in a source checkout. If none has `themisto[.exe]`, `createSession()` rejects with an error naming what was expected (`jovian: the kernel binaries were not found. Expected the '@damurka/jovian-…' package …`, or, on a platform without a prebuilt package, the list of supported ones). When the library runs from an installed package and `heraSrcPath` is not given, it defaults to the copy of `hera` shipped in the package.
+
+## Events
+
+`Session` is an `EventEmitter`. Everything the kernel sends is available as events — the full list is in [`session.md`](session.md#events). The two you must know about:
+
+- **Always attach an `'error'` listener.** `Session` re-emits every R/Python error message as Node's special `'error'` event (with the error message string), and internal failures as an `Error` instance. Node **throws** if `'error'` is emitted with no listener, which kills the process. The error is also in the execution's `ExecutionResult` — the listener can be a no-op.
+- `'exit'` means the kernel (or the connection to the supervisor) died unexpectedly.
+
+## Errors and timeouts
+
+| Situation | What you get |
+|---|---|
+| R/Python code raises an error | `execute()` **resolves** with `success: false`, the `error` message, and the `error` iopub message in `output` (with `ename`, `evalue`, `traceback`). It does not reject. |
+| `execute()` exceeds its `timeout` (default **30 000 ms**; `0` = none) | Rejects with `Execution timed out after <n>ms`. The kernel is *not* interrupted — call `interrupt()` yourself if you want the code to stop. |
+| A kernel waits for `input()` / `readline()` | The execution's timeout is cleared while it waits, so a slow human cannot trip it. |
+| Session stopped, restarted, killed or crashed while an `execute()` is queued or running | Rejects with `Queue cleared`. |
+| More than `queueSize` (default **100**) executions queued | Rejects with `Execution queue is full`. |
+| Protocol requests (`complete()`, `kernelInfo()`, …) | Time out after **10 000 ms** by default (`session.request(…, { timeout })` to change), reject on an `error`/`aborted` reply, on a supervisor `requestError`, and with `Session stopped` / `Session process exited: …` / `Session is restarting` / `Session was killed` if the session goes away. |
+| `interrupt()` | Never rejects: resolves `false` if unacknowledged within its timeout (default 5 000 ms). |
+| `restart()` after `stop()`/`kill()` | Throws `Cannot restart session <id>: it was already stopped`. A stopped session is terminal — create a new one. |
+
+Logging: pass `logger` (a `(level, message, data?) => void` function) to route library logs; without it every level, including `trace`/`debug`, is printed to the console. `enableLogging` adds a middleware that prints the first 100 characters of every raw message frame; `enableMetrics` prints a messages/second line per message.

package/docs/api/session.md

@@ -0,0 +1,143 @@
+# `Session` and `Comm`
+
+A `Session` is one kernel process (R or Python) plus its WebSocket connection to the supervisor. You get one from [`SessionManager.createSession()`](README.md#sessionmanager); the constructor is not part of the public API.
+
+```typescript
+const session = await manager.createSession({ kernelType: 'python', pythonHome, workingDirectory: '/projects/a' });
+session.on('error', () => {});                         // required, see README#events
+session.on('stdout', (t) => process.stdout.write(t));
+const result = await session.execute('print("hi"); 1 + 1');
+```
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `info` | `{ sessionId, httpBase, wsBase }` | Where this session lives on the supervisor. `httpBase` + `/sessions/<sessionId>` is the supervisor's own view of it — `status()` reads exactly that. |
+| `options` | `EngineOptions` | What the session is running with: the creation options, updated by any `restart(options)` that changed them. |
+| `executionState` | `'busy'` \| `'idle'` \| `'starting'` \| `undefined` | The kernel's latest iopub `status`. Tracked per request, so an interrupt handled *during* an execution (its own busy/idle pair) does not flip the state to idle while the execution is still running. `undefined` until the first status. |
+
+## Running code
+
+### `execute(code, options?): Promise<ExecutionResult>`
+
+Runs `code`. Calls are queued and sent to the kernel **one at a time** (a kernel runs one thing at a time anyway); each resolves when the kernel's `execute_reply` arrives. See [`ExecutionOptions` / `ExecutionResult`](types.md#execution). Notable options:
+
+- `timeout` — ms, default 30 000, `0` for none. When it fires, `execute()` rejects with `Execution timed out after <n>ms (the kernel was interrupted)` **and the kernel is interrupted** (so it does not keep running code nobody is waiting for, which would block everything queued behind it).
+- `interruptOnTimeout: false` — on a timeout, only reject: leave the kernel running (the message then ends after `ms`, without the parenthesis). The default is `true`.
+- `allowStdin: true` — let `input()` / `readline()` ask for input; see [Interactive input](../guides/interactive-input.md).
+- `stopOnError: true` — if this execution fails, every `execute()` still **queued behind it** is skipped: it resolves with `success: false`, `aborted: true`, `status: 'aborted'`, empty `output`, and never reaches the kernel. Without it a failure does not affect the queue.
+- `userExpressions: { name: 'expr' }` — evaluated in the kernel after the code, only if it succeeded; results in `result.userExpressions[name]`, each `{ status: 'ok', data, metadata }` or `{ status: 'error', ename, evalue, traceback }`.
+- `silent`, `storeHistory` — passed through to the kernel (`silent` suppresses `execute_input`, the execution count and history).
+
+`ExecutionResult.output` holds every iopub message the execution produced (`stream`, `execute_result`, `display_data`, `update_display_data`, `clear_output`, `error`), in arrival order. It does **not** contain `status` messages.
+
+### `interrupt(options?: { timeout?: number }): Promise<boolean>`
+
+Sends `interrupt_request` on the control channel. Resolves `true` if the kernel acknowledged (`interrupt_reply` with `status: 'ok'`), `false` if not within `timeout` (default 5 000 ms) or the session is gone — it **never rejects**. The interrupt is real: the kernel services its control channel on a watcher thread while code runs, so it is answered immediately even mid-execution and running code is broken out of like Ctrl-C (R: an interrupt condition; Python: `KeyboardInterrupt`). The interrupted `execute()` resolves with `success: false`; the kernel stays usable. Interrupting an idle kernel does nothing. See [Interrupting](../guides/interrupting.md) for limits.
+
+### `sendInputReply(value: string): void`
+
+Answers a pending `'input_request'`. Fire-and-forget; what comes back is the running execution finishing.
+
+### `createShiny(options: ShinyAppOptions): Promise<ShinyAppHandle>`
+
+R only. Runs `shiny::runApp()` in the session (with `timeout: 0`) and resolves once the port accepts connections; the returned `done` promise resolves when the app stops. The session is busy for as long as the app runs.
+
+## Protocol requests
+
+Each is a real Jupyter request answered by the kernel; each rejects on an `error`/`aborted` status, on timeout (10 s), or if the session ends. They are queued **behind a running execution** on the kernel's main thread (only `interrupt()` is serviced during one).
+
+| Method | Sends | Resolves with |
+|---|---|---|
+| `complete(code, cursorPos = code.length)` | `complete_request` | `{ status, matches: string[], cursor_start, cursor_end, metadata }` |
+| `inspect(code, cursorPos = code.length, detailLevel = 0)` | `inspect_request` | `{ status, found, data: { 'text/plain'?, 'text/html'? }, metadata }` |
+| `isComplete(code)` | `is_complete_request` | `{ status: 'complete' \| 'incomplete' \| 'invalid' \| 'unknown', indent? }` |
+| `kernelInfo()` | `kernel_info_request` | `{ protocol_version, implementation, implementation_version, language_info: { name, version, … }, banner, … }` |
+| `commInfo(targetName?)` | `comm_info_request` | `{ status, comms: { [commId]: { target_name } } }` |
+| `queryKernelHistory(options?)` | `history_request` | `KernelHistoryEntry[]` — see [History](../guides/history.md) |
+| `request<T>(msgType, content?, { timeout? })` | any whitelisted request/reply pair | the reply `content` |
+
+`request()` is the generic form behind the methods above. It accepts the request types in the [whitelist](../protocol.md#client--themisto); the reply type is derived by replacing `_request` with `_reply`. It is not for `execute_request`, `input_reply` or `shutdown_request`.
+
+## Comms
+
+A *comm* is a named message stream between the client and a target registered inside the kernel (R: `hera::CommManager$register_comm_target(name, callback)`). Carpo has no way to register targets yet, so comms are an R feature today. See [the guide](../guides/comms.md).
+
+| Method | Description |
+|---|---|
+| `openComm(targetName, data?): Promise<Comm>` | Opens a comm and returns a `Comm` object. If the kernel has no such target it answers with a `comm_close`, so the returned comm emits `'close'`. |
+| `commOpen(targetName, data?, commId?)` | Low-level: sends `comm_open`; resolves `{ commId, msgId }`. |
+| `commMsg(commId, data?)` / `commClose(commId, data?)` | Low-level: send `comm_msg` / `comm_close`; resolve with the msg id they were sent under. |
+
+**`Comm`** (`EventEmitter`)
+
+| Member | Description |
+|---|---|
+| `id`, `targetName`, `closed` | Identity and state. |
+| `send(data?): Promise<string>` | Sends a `comm_msg`. Rejects if the comm is closed. |
+| `close(data?): Promise<void>` | Sends `comm_close` (no-op if already closed) and emits `'close'`. |
+| event `'message'` `(data)` | The kernel sent a `comm_msg` on this comm. |
+| event `'close'` `(data)` | Closed by either side, **or** because the kernel restarted, exited, or the session stopped — then `data.reason` is `'kernel restarted'`, `'kernel exited'`, `'session stopped'` or `'connection lost'`. |
+
+Comms the **kernel** opens arrive as the session's `'comm'` event: `session.on('comm', (comm, data) => …)` where `data` is the `comm_open`'s payload.
+
+## History
+
+| Method | Description |
+|---|---|
+| `getHistory(): ExecutionHistoryEntry[]` | This session object's own transcript: `{ code, executionCount?, time, messages, truncated? }` per `execute()`, output included. In memory, capped at the latest **200** entries; within an entry the stream (stdout/stderr) text is bounded to the newest **~500 000 characters** (older stream messages are dropped and `truncated` is `true`; results, display data and errors are kept in full). Survives `restart()`, gone with the `Session` object. It is the live array — copy it if you need a snapshot. |
+| `queryKernelHistory(options?)` | What the *kernel* remembers running (inputs only; lost when the kernel restarts). See [History](../guides/history.md) for the difference. |
+
+## Status
+
+### `status(): Promise<SessionStatusInfo>`
+
+What the supervisor knows about this session's kernel process right now — a plain `GET {httpBase}/sessions/{sessionId}`, so it needs no kernel round trip:
+
+```typescript
+const s = await session.status();
+// { sessionId, status: 'ready', kernelType: 'r', workingDirectory: '...', pid: 4242,
+//   memoryBytes: 88000000, heartbeat: { hasPong: true, rttMs: 0.6, sinceLastPongMs: 42, misses: 0 } }
+```
+
+`heartbeat` is the supervisor's ZMQ ping to the kernel (about ten a second): `rttMs` is the round trip of the last answered ping, `sinceLastPongMs` how long ago that was, `misses` how many pings in a row went unanswered (`0` = healthy). The kernel answers pings from a thread of its own, separate from the one that runs code, so **the heartbeat stays live while the kernel is busy** — unlike `kernelInfo()`, which would wait for the running cell to finish. Use it as a liveness signal ("is it alive?"), not a responsiveness one ("is it free?" — that is `executionState`). `heartbeat` is `null` for a session with no client (e.g. one that has been stopped); `hasPong` is `false` until the first ping has been answered. Rejects if the supervisor cannot be reached or no longer knows the session (a stopped session is removed).
+
+## Lifecycle
+
+### `restart(options?: Partial<EngineOptions>): Promise<void>`
+
+Replaces the kernel process under the **same session id** — recovers a crashed session, or resets a healthy one (Jupyter's "Restart Kernel"). Queued and running `execute()` calls reject with `Queue cleared`; pending requests reject with `Session is restarting`; open comms emit `'close'` with reason `'kernel restarted'`.
+
+`options`, if given, are **merged** with the session's current options (`{ ...session.options, ...options }`) before being sent, so switching only `rHome` keeps `workingDirectory`, `rLibs`, …; `session.options` is updated. To *clear* a field, pass `undefined` or an empty string. The old kernel receives `shutdown_request{restart: true}` — you can observe the kernel's `shutdown_reply` (`restart: true`) as an event before `'restarted'` fires. Throws if the session was already stopped or killed.
+
+### `stop(): Promise<void>`
+
+Sends the kernel `shutdown_request{restart: false}` through the supervisor, waits for the process to exit (force-killed after ~2 s if it does not), waits up to 250 ms for the `shutdown_reply` to be observable, closes the socket and emits `'stopped'`. Idempotent. Pending work rejects (`Queue cleared`, `Session stopped`).
+
+### `kill(): void`
+
+Closes the local socket and rejects pending work **without** telling the supervisor — only for cleanup on the way out; the kernel process is not stopped by this alone (`SessionManager.killAll()` also kills the supervisor, which takes the kernels with it).
+
+### `ready(): Promise<void>`
+
+Resolves once the session's WebSocket is open and bound. `execute()` and the request methods await it for you.
+
+## Events
+
+All are Node `EventEmitter` events on the `Session`.
+
+| Event | Arguments | When |
+|---|---|---|
+| `'message'` | `JupyterMessage` | Every message from the kernel (iopub, shell, control, stdin). |
+| `'*'` | `(msgType, content)` | Same, as a catch-all. |
+| *`<msg_type>`* — e.g. `'status'`, `'execute_reply'`, `'shutdown_reply'`, `'input_request'`, `'comm_msg'`, `'display_data'`, `'update_display_data'`, `'clear_output'` | `content` | Every message also fires an event named after its `msg_type`. |
+| `'stdout'`, `'stderr'` | `text` | Streamed output (`stream` messages by `name`). |
+| `'result'` | `text` | The `text/plain` of each `execute_result` / `display_data`. |
+| `'input_request'` | `{ prompt, password }` | The kernel is blocked waiting for input; answer with `sendInputReply()`. |
+| `'comm'` | `(comm: Comm, data)` | The kernel opened a comm. |
+| `'error'` | `string` (the error's `evalue`) or `Error` | A code error in the kernel, or an internal failure handling a message. **Requires a listener.** |
+| `'exit'` | `{ reason }` | Kernel died unexpectedly (or the supervisor connection dropped). The session is left recoverable via `restart()`. Not emitted for `stop()` / `restart()`. |
+| `'restarted'` | — | `restart()` finished. |
+| `'stopped'` | — | `stop()` finished. |
+| `'requestError'` | `{ id, error }` | The supervisor refused a fire-and-forget request (a `comm_*` message) — e.g. session not found. |

package/docs/api/types.md

@@ -0,0 +1,120 @@
+# Types
+
+Everything here is exported from `jovian` (`lib/types/`). Snake_case fields (`cursor_pos`, `execution_state`, …) are Jupyter's wire names, passed through unchanged; camelCase fields are Jovian's.
+
+## `EngineOptions`
+
+Passed to `SessionManager.createSession()`; also `Partial<EngineOptions>` to `Session.restart()`.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `kernelType` | `'r'` \| `'python'` | `'r'` | Which kernel the session runs. Selects which of the fields below apply and which executable (`elara` / `carpo`) is spawned. |
+| `rHome` | string | — | R installation (`R_HOME`). Required to run R sessions unless `R_HOME` is discoverable by the kernel's environment — pass it explicitly. |
+| `rPath` | string | `<rHome>/bin/x64` (Windows) | Directory containing `R.dll`; put on the kernel's `PATH`. |
+| `rLibs` | string | — | Extra library path (`R_LIBS`, `R_LIBS_USER`, and `R_LIBS_SITE` on Windows); where `hera` is looked up and installed. |
+| `pandocPath` | string | — | Directory with a `pandoc` binary, for bundled R installs that do not ship it on `PATH` (`RSTUDIO_PANDOC`). |
+| `heraSrcPath` | string | — | Source directory of the `hera` package. If set, Elara installs it (`remotes::install_local`, needs `remotes`) when it is missing or older than the source. **There is no built-in default**: if `hera` is not installed and this is unset, R code cannot run (see [Troubleshooting](../troubleshooting.md#hera-is-not-installed)). |
+| `pythonHome` | string | — | Python installation prefix (`PYTHONHOME`). Its shared library is loaded from here. |
+| `pythonPath` | string | — | Extra `PYTHONPATH`. |
+| `venvPath` | string | — | A venv whose `site-packages` is added to `sys.path`. `pythonHome` must still point at the *base* install. |
+| `workingDirectory` | string | supervisor's cwd | Directory the kernel process starts in (`getwd()` / `os.getcwd()`); relative paths resolve against it. Must exist, or `createSession()` rejects with `workingDirectory does not exist or is not a directory: <path>`. Kept across `restart()`. |
+| `queueSize` | number | 100 | Max queued `execute()` calls. |
+| `enableLogging` | boolean | false | Log the first 100 characters of every raw message frame. |
+| `enableMetrics` | boolean | false | Print a messages/second line per message. |
+| `logger` | `(level, message, data?) => void` | console | Receives the library's logs (`trace` … `error`). |
+
+## Execution
+
+### `ExecutionOptions`
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `timeout` | number (ms) | 30 000 | `0` = none. Cleared while the kernel waits for input. When it fires the call rejects and, unless `interruptOnTimeout` is `false`, the kernel is interrupted too. |
+| `interruptOnTimeout` | boolean | true | On a timeout, also send the kernel an interrupt (the rejection message then ends `(the kernel was interrupted)`). Set `false` to leave it running. |
+| `allowStdin` | boolean | false | Permit `input()` / `readline()`. |
+| `stopOnError` | boolean | false | On failure, skip everything queued behind this call (they resolve `aborted`). Also forwarded to the kernel as `stop_on_error`. |
+| `userExpressions` | `Record<string, string>` | — | Expressions evaluated after the code, if it succeeded. |
+| `silent` | boolean | false | No `execute_input`, no execution count, no history. |
+| `storeHistory` | boolean | true | Record in the kernel's history (ignored when `silent`). |
+
+### `ExecutionResult`
+
+| Field | Type | Meaning |
+|---|---|---|
+| `success` | boolean | `true` iff the kernel's reply status was `ok`. |
+| `output` | `JupyterMessage[]` | Every `stream` / `execute_result` / `display_data` / `update_display_data` / `clear_output` / `error` message the execution produced. |
+| `error` | `Error?` | For a failed execution: the message; for an aborted one: `Execution aborted: an earlier execution failed with stopOnError`. |
+| `executionCount` | number? | From the reply; absent for a silent execution. |
+| `status` | `'ok'` \| `'error'` \| `'aborted'`? | The reply's own status. |
+| `aborted` | `true`? | Present when skipped because of an earlier `stopOnError` failure, or when the kernel replied `aborted`. |
+| `userExpressions` | `Record<string, UserExpressionResult>`? | Present when `userExpressions` were requested and evaluated. |
+
+```typescript
+type UserExpressionResult =
+    | { status: 'ok'; data: Record<string, any>; metadata: Record<string, any> }
+    | { status: 'error'; ename: string; evalue: string; traceback: string[] };
+```
+
+### `ExecutionHistoryEntry`
+
+`{ code: string; executionCount?: number; time: number; messages: JupyterMessage[]; truncated?: boolean }` — one entry of `Session.getHistory()`. `truncated` is `true` when the execution printed so much that the oldest stream (stdout/stderr) messages were dropped: an entry keeps the newest ~500 000 characters of stream text and everything else in full.
+
+### `ShinyAppOptions` / `ShinyAppHandle`
+
+`ShinyAppOptions`: `appDir` (required), `port` (default: a free port), `host` (`'127.0.0.1'`), `launchBrowser` (false), `readyTimeout` (10 000 ms), `env` (`Record<string,string>`, applied with `Sys.setenv()` before launch). `ShinyAppHandle`: `{ host, port, url, done: Promise<ExecutionResult> }` — `done` resolves when the app stops.
+
+## Session status
+
+Returned by `Session.status()`.
+
+### `SessionStatusInfo`
+
+`{ sessionId: string; status: 'starting' | 'ready' | 'stopped' | 'crashed'; kernelType: 'r' | 'python'; workingDirectory: string; pid: number; memoryBytes: number | null; heartbeat: HeartbeatInfo | null }` — `pid` is `0` when the kernel process is not running; `memoryBytes` is `null` where it can't be read; `workingDirectory` is empty when the session was created without one.
+
+### `HeartbeatInfo`
+
+`{ hasPong: boolean; rttMs: number; sinceLastPongMs: number; misses: number }` — the supervisor's view of the kernel's heartbeat channel. `hasPong` is `false` until the first ping is answered (`rttMs` and `sinceLastPongMs` are then meaningless); `rttMs` is the round trip of the last answered ping in ms; `sinceLastPongMs` how long ago it arrived; `misses` the number of consecutive unanswered pings. Kept fresh by a kernel thread that is independent of the one running code, so it keeps answering while a cell runs.
+
+## Protocol reply contents
+
+| Type | Fields |
+|---|---|
+| `CompleteReplyContent` | `status`, `matches: string[]`, `cursor_start`, `cursor_end`, `metadata` |
+| `InspectReplyContent` | `status`, `found: boolean`, `data`, `metadata` |
+| `IsCompleteReplyContent` | `status: 'complete' \| 'incomplete' \| 'invalid' \| 'unknown'`, `indent?` |
+| `KernelInfoReplyContent` | `status`, `protocol_version`, `implementation`, `implementation_version`, `language_info: { name, version, mimetype, file_extension, pygments_lexer?, codemirror_mode?, nbconvert_exporter? }`, `banner`, `help_links?` |
+| `CommInfoReplyContent` | `status`, `comms: Record<string, { target_name: string }>` |
+| `InterruptReplyContent` | `status` |
+| `ShutdownReplyContent` | `status`, `restart: boolean` — the payload of the `'shutdown_reply'` event |
+
+### History
+
+```typescript
+interface KernelHistoryOptions {
+    histAccessType?: 'tail' | 'range' | 'search';   // default 'tail'
+    output?: boolean;                               // default false (the kernel records no output today)
+    raw?: boolean;                                  // default true
+    n?: number;                                     // 'tail'/'search'; default 100
+    session?: number; start?: number; stop?: number;    // 'range'
+    pattern?: string; unique?: boolean;                 // 'search' (glob: * ?)
+}
+type KernelHistoryEntry = [session: number, lineNumber: number, input: string | [input: string, output: string]];
+```
+
+## Messages
+
+```typescript
+interface JupyterMessage<T = any> {
+    topic: string;          // iopub: 'kernel_core.<kernel id>.<msg_type>'; shell/control: the msg_type
+    msgType: string;
+    channel: 'iopub' | 'shell' | 'stdin' | 'control';
+    parentMsgId: string;    // the id of the request that caused it ('' for unsolicited messages)
+    content: T;
+    timestamp: number;      // client receive time, ms
+    raw: string;            // the raw frame text
+}
+```
+
+Typed `content` interfaces: `StreamContent` (`name: 'stdout'|'stderr'`, `text`), `ExecuteResultContent`, `DisplayDataContent`, `UpdateDisplayDataContent` (`transient?: { display_id? }`), `ClearOutputContent` (`wait`), `ErrorContent` (`ename`, `evalue`, `traceback`), `StatusContent` (`execution_state: 'busy' | 'idle' | 'starting'`), `ExecuteInputContent` (`code`, `execution_count`), `InputRequestContent` (`prompt`, `password`), `CommOpenContent` / `CommMsgContent` / `CommCloseContent`.
+
+`ExecutionState` = `'busy' | 'idle' | 'starting'`. `LogLevel` = `'trace' | 'debug' | 'info' | 'warn' | 'error'`.