@damurka/jovian 0.1.0

package/docs/releasing.md

@@ -0,0 +1,73 @@
+# Releasing
+
+Jovian is published to npm as four packages under the `@damurka` scope (Windows x64, Linux x64 and macOS arm64; see [Adding a platform](#adding-a-platform) for the others):
+
+| Package | Contents |
+|---|---|
+| `@damurka/jovian` | The compiled TypeScript library, the `hera` R package, docs. Lists the platform packages below as `optionalDependencies`. This is the one users install. |
+| `@damurka/jovian-win32-x64` | `themisto.exe`, `elara.exe`, `carpo.exe` and the DLLs they need. |
+| `@damurka/jovian-linux-x64`, `-darwin-arm64` | `themisto`, `elara`, `carpo`. |
+
+Each platform package declares `os` and `cpu`, so npm installs only the one that matches the machine. At run time the library finds the binaries in that package (see [`lib/session/native-paths.ts`](../lib/session/native-paths.ts): `JOVIAN_NATIVE_DIR`, then the platform package, then a source checkout's `dist/native/Release`). All four packages are published at the **same version**; the main package pins the platform packages to it.
+
+The repository's own `package.json` is `"private": true` — it is the development workspace and is never published. Everything published is staged by `scripts/release.mjs` under `dist/release/`.
+
+## One-time setup
+
+1. **The scope.** `@damurka` must be a user or organization you can publish to on npmjs.com. If you use a different scope, change it in two places — `SCOPE` in `scripts/release.mjs` and `PACKAGE_SCOPE` in `lib/session/native-paths.ts` (a unit test fails if they differ) — plus the names in `README.md`, `docs/`, and the tarball globs in `.github/workflows/release.yml`.
+2. **A token.** On npmjs.com create an *automation* access token (or a granular token with read/write on the `@damurka` packages) and add it to the GitHub repository as the secret **`NPM_TOKEN`** (Settings → Secrets and variables → Actions). If your account enforces 2FA for publishing, the token must be of the automation kind, which bypasses the prompt.
+3. Scoped packages are private by default on npm; the packages carry `publishConfig.access: public`, and the workflow passes `--access public`.
+4. The workflow publishes with **provenance** (`--provenance`, needs the `id-token: write` permission it declares), which requires the GitHub repository to be public.
+
+## Cutting a release
+
+1. Make sure `main` is green on CI.
+2. Decide the version (semver). Nothing in the repository holds it: it comes from the tag.
+3. Tag and push:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+4. `release.yml` runs. For each platform it builds the native binaries in Release, compiles the library, stages both packages, packs them, and **smoke-tests the packed tarballs**: `scripts/release-smoke.mjs` installs the platform tarball and the main tarball into an empty project (outside the repository, with an empty R library so the bundled `hera` has to install from the package) and starts a real R kernel and a real Python kernel from them.
+5. Only if every platform passed does the `publish` job run: the platform packages first, then the main package (so nothing ever depends on a version that is not there yet).
+
+A version with a hyphen (`v0.2.0-rc.1`) is published under the `next` dist-tag, so it does not become what `npm install` picks by default.
+
+### Dry run
+
+Run the workflow by hand (Actions → Release → Run workflow). It does everything except publish and uploads the tarballs as artifacts, which you can download and `npm install` yourself.
+
+### Locally
+
+```bash
+npm run build                                                    # native + TypeScript
+node scripts/release.mjs platform --version 0.1.0                # this machine's platform package
+node scripts/release.mjs main --version 0.1.0
+mkdir -p dist/release/tarballs
+(cd dist/release/jovian-win32-x64 && npm pack --pack-destination ../tarballs)   # your platform's name
+(cd dist/release/jovian && npm pack --pack-destination ../tarballs)
+node scripts/release-smoke.mjs --dir dist/release/tarballs --python
+```
+
+Nothing there publishes. Publishing by hand is `npm publish <tarball> --access public`, platform packages first.
+
+## Adding a platform
+
+Only the platforms that have been built and smoke-tested end to end are published (Windows x64, Ubuntu x64 and macOS arm64, the three the CI matrix covers). To add `linux-arm64` or `darwin-x64`:
+
+1. Add the target to `TARGETS` in `scripts/release.mjs` and to `SUPPORTED_PLATFORMS` in `lib/session/native-paths.ts` (a unit test fails if they differ).
+2. Add it to the build matrix in `.github/workflows/release.yml` (`ubuntu-24.04-arm`, `macos-15-intel`); the job `env` already sets `MACOSX_DEPLOYMENT_TARGET: '14.0'` for macOS.
+3. Run the workflow by hand (a dry run) and fix what the smoke test finds before tagging a release.
+
+Until a platform is added, its users get `jovian: there are no prebuilt kernels for <os>-<cpu>` and can build from source and set `JOVIAN_NATIVE_DIR`.
+
+## Things to know
+
+- **hera upgrades.** npm resets file modification times, so the kernel's usual "is the hera source newer than the installed one" check cannot fire for an npm install. The staged `hera` `DESCRIPTION` is stamped with `Config/jovian/release: <version>`, and the kernel reinstalls `hera` when that stamp differs from the installed copy's. Users therefore get the matching `hera` after upgrading the package, once.
+- **Linux binaries and glibc.** They are built on `ubuntu-24.04` (glibc 2.39) and run on any distribution with at least that glibc. Building on an older image would widen compatibility; a `linux-arm64` build would use `ubuntu-24.04-arm`.
+- **macOS.** The build sets `MACOSX_DEPLOYMENT_TARGET=14.0`. The binaries are not code-signed or notarized; binaries installed through npm are not quarantined by Gatekeeper, so this works, but bundling them into a downloaded `.app` would require signing.
+- **Windows.** The DLLs come from vcpkg's `x64-windows` triplet and are copied next to the executables; the binaries link the dynamic Visual C++ runtime (`MSVCP140.dll`, `VCRUNTIME140.dll`, checked with `dumpbin /dependents`), which is **not** bundled: users need the "Microsoft Visual C++ Redistributable" (x64, 2015–2022), and the README's Install section says so. Bundling the runtime DLLs into the package, or linking the runtime statically, would remove that requirement.
+- **Executable bit.** npm does not reliably preserve it; the library `chmod`s the kernels before starting them.
+- **Versions cannot be reused.** npm never lets a published version be republished. If a release fails half-way (say the platform packages published but the main package did not), bump the version and release again.

package/docs/troubleshooting.md

@@ -0,0 +1,110 @@
+# Troubleshooting
+
+Messages below are quoted from the code. **First habit:** a kernel that fails to start reports only a generic error to your code; the real cause is on stderr, prefixed `[elara]` (R) or `[carpo]` (Python) — the supervisor re-prints everything the kernel writes. Read that output first.
+
+## Building
+
+| Symptom | Cause / fix |
+|---|---|
+| CMake cannot find `nlohmann_json` / `zeromq` / `cppzmq` / `httplib` / `ixwebsocket` | vcpkg's toolchain was not used. Set `VCPKG_ROOT` and re-configure with `-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake` (`npm run build` does this when `VCPKG_ROOT` is set). |
+| `FindR.cmake requires the following variables to be set: R_COMMAND` | `cmake/FindR.cmake` runs `R RHOME`; put `R` on `PATH` or pass `-DR_COMMAND=<path to R>`. Only R's *headers* are needed to build. |
+| `R.h: No such file or directory` (Debian/Ubuntu) | Install `r-base-dev`. `cmake/FindR.cmake` finds Debian's split headers (`R.h` in `/usr/share/R/include`) via `R CMD config --cppflags`; if your R reports no such directory, add it with `-DCMAKE_CXX_FLAGS=-I<dir containing R.h>`. |
+| `ERR_UNKNOWN_FILE_EXTENSION … ".ts"` running the tests | The Node build has no TypeScript type stripping (Ubuntu's packaged `nodejs`). Use the official build from nodejs.org. |
+| `undefined reference to uuid_generate` (Linux) | Install `uuid-dev` (`sudo apt-get install uuid-dev`). |
+| `LNK1104: cannot open file '…\themisto.exe'` (Windows) | A `themisto` / `elara` / `carpo` process is still running from an earlier run. Kill strays (`tasklist \| findstr /i "themisto elara carpo"`) — or run against a *copy* of `dist/native/Release` via `JOVIAN_NATIVE_DIR`. |
+| C++23 / `/std:c++latest` errors on Windows | Use Visual Studio 2026 (the toolset the repo is built with); older toolsets are untested. |
+| `npm ci` fails on peer dependencies | Use `--legacy-peer-deps` (as CI does): TypeScript 7 conflicts with the `@typescript-eslint` plugin's declared range. |
+| Unit tests fail after editing `lib/` | The tests import `dist/lib`: run `npm run build:lib`. |
+
+## Creating a session
+
+| Message | Meaning and fix |
+|---|---|
+| `jovian: the kernel binaries were not found. Expected the '@damurka/jovian-<os>-<cpu>' package …` | The platform package was not installed: it is an optional dependency, so `npm install --omit=optional` / `--no-optional` skips it (reinstall without the flag), or a lockfile made on another OS omitted it (`npm install` on this OS). In a source checkout: run `npm run build`, or set `$JOVIAN_NATIVE_DIR`. |
+| `jovian: there are no prebuilt kernels for <os>-<cpu> (supported: …)` | Prebuilt packages exist for `win32-x64`, `linux-x64` and `darwin-arm64` only (Intel Macs and Linux on ARM are not published yet). Elsewhere, [build from source](../README.md#requirements) and set `$JOVIAN_NATIVE_DIR` to `dist/native/Release`. |
+| `version 'GLIBC_2.xx' not found` on Linux | The prebuilt Linux binaries need a glibc at least as new as the one they were built with (Ubuntu 24.04: 2.39). Build from source on the older system. |
+| `Supervisor process exited before it was ready (code 1)` | `themisto` refused to start — typically `[themisto] FATAL: kernel executable not found at … (pass --kernel-exe to override)`: `elara` is missing next to `themisto`. |
+| `no kernel executable is configured for kernelType 'python' …` | `carpo` was not built (or not found beside `themisto`). It is built by default; check `dist/native/Release/carpo[.exe]` and Themisto's `[themisto] NOTE: no Python kernel executable found` line. R sessions are unaffected. |
+| `workingDirectory does not exist or is not a directory: <path>` | Create the directory first, or fix the path. |
+| `Kernel process exited before it could register -- check its stderr output for the actual error.` | The kernel crashed at start-up. See the R / Python sections below and read the `[elara]` / `[carpo]` lines. |
+| `Did not receive kernel configuration within 60s -- the kernel process is still running but never registered. Check its stderr output for what it's doing.` | The kernel started but hung before registering — e.g. R blocked loading packages, a very slow disk, or a security product scanning the process. The stderr shows how far it got. |
+| `WebSocket connection to session <id> failed` / `Session <id> closed before it was ready` | The supervisor accepted the session but the WebSocket could not be established/kept — usually the supervisor died. Look for its exit. |
+
+### R
+
+| Symptom | Cause / fix |
+|---|---|
+| `Could not load R.dll (…). Is R installed? Checked PATH and R_HOME=… Install R from https://cran.r-project.org, or make sure R_HOME/the R bin directory is configured correctly.` | Windows: `rHome` wrong, or `rPath` (the folder containing `R.dll`, normally `<R_HOME>\bin\x64`) is not right. |
+| `R_HOME is not set -- elara needs a working R installation to run. …` | Linux/macOS: pass `rHome` (find it with `R RHOME`). |
+| `Could not load …/lib/libR.so (…). Is R installed at '…'? If this R was built from source, it needs to have been configured with --enable-R-shlib, or no libR.so exists at all` | Use a distribution/CRAN R, or rebuild R with `--enable-R-shlib`. |
+| No `libR.dylib` on macOS | Point `rHome` at the framework's `Resources` directory (what `R RHOME` prints). |
+
+#### `hera` is not installed
+
+Symptoms: the kernel log says `WARNING: 'hera' package could not be loaded (status: …)`, then `execute()` results in an error — the reply carries `R evaluation of hera:::hera_call("execute", ...) failed (is the 'hera' package installed?): …`, and completion/inspect fail the same way.
+
+On Debian/Ubuntu, `R CMD INSTALL` may fail loading an apt package with `undefined symbol: SETLENGTH` (`rlang`, `vctrs`, `htmltools`, …): those `r-cran-*` packages were built for a different R ABI. Hide the site library and install from CRAN into a private one — `export R_LIBS_SITE=/nonexistent R_LIBS_USER=$HOME/Rlib`, then `install.packages()` the dependencies and run `npm run hera:install` in the same shell, keeping both variables set when you start sessions.
+
+Fix: install `hera` and its dependencies into the library the session uses (`npm run hera:install`, i.e. `R CMD INSTALL packages/hera`, after installing `cli`, `evaluate`, `glue`, `IRdisplay`, `jsonlite`, `R6`, `repr`, `rlang` from CRAN), or pass `heraSrcPath: '<repo>/packages/hera'` (needs `remotes`) so Elara installs it. The status names in the warning: `no_source_configured` (not installed and no `heraSrcPath`), `source_not_found` (path does not exist), `remotes_unavailable` (install `remotes`), `install_failed` (see R's error above it — usually a missing dependency or an unwritable library: set `rLibs`).
+
+There is **no bundled fallback**: `heraSrcPath` has no default, whatever older comments say.
+
+#### R code fails after the kernel started
+
+- `there is no package called '…'` — the package is not in `rLibs` / the default library of that R installation.
+
+### Python
+
+| Message | Cause / fix |
+|---|---|
+| `No python3NN.dll was found directly under python_home ('…'). Is Python installed there? …` | Windows: `pythonHome` must be the install root that directly contains `python3NN.dll`. |
+| `No libpython3.*.so*/.dylib was found under '<home>/lib' (or lib64/, lib/<arch>-linux-gnu/). …` | POSIX: `pythonHome` must be the prefix whose `lib/`, `lib64/` or `lib/<arch>-linux-gnu/` has the shared library (a distribution Python works with `pythonHome: '/usr'`). Some builds (pyenv without `--enable-shared`, some Homebrew/conda layouts) have none. |
+| `Could not load <path> (…)` | The library was found but would not load — a 32/64-bit mismatch or a missing dependency. |
+| Imports from your venv fail | Set `venvPath` **and** keep `pythonHome` at the base install (`sys.base_prefix`). Inside a venv, `sys.prefix` has neither libpython nor the standard library. |
+
+## Running code
+
+| Symptom | Cause / fix |
+|---|---|
+| `Execution timed out after 30000ms (the kernel was interrupted)` | The default `timeout` fired. The library interrupted the kernel, so it is usable again straight away. Raise the timeout (`execute(code, { timeout })`) or use `0` for none. With `interruptOnTimeout: false` the message has no parenthesis and the kernel is **still running** the code: `interrupt()` or restart it, or new work — and `complete()` / `inspect()` — queue behind it and look hung. |
+| `complete()` / `inspect()` / `kernelInfo()` time out (10 s) | The kernel is busy: it answers requests on the thread that runs code, so they wait until the running execution ends (only `interrupt()` is answered mid-run). Usually a long or timed-out execution left running (`interruptOnTimeout: false`, or a client that gave up without interrupting). `interrupt()` it. |
+| Output of one long R expression (a `for` loop of `print()`s) only appears when it finishes | An older `hera` is installed. Live streaming inside a single top-level expression needs `hera` >= 0.6.0.9001: run `npm run hera:install` (see [Environments](guides/environments.md#the-hera-package-required)). |
+| `Queue cleared` | The session was stopped, restarted, killed or crashed while your `execute()` was queued or running. |
+| `Execution queue is full` | More than `queueSize` (100) queued calls. |
+| `Execution aborted: an earlier execution failed with stopOnError` | Expected: a previous call with `stopOnError` failed (`result.aborted === true`). |
+| `This execution didn't allow interactive input (allow_stdin was false) …` | Pass `{ allowStdin: true }` and answer `'input_request'` — see [Interactive input](guides/interactive-input.md). |
+| The process crashes with `Unhandled 'error' event` | You did not attach `session.on('error', …)`. Node throws for `'error'` without a listener. |
+| A script never exits | Call `await manager.stopAll()` — the supervisor's pipes keep the event loop alive. |
+| `execute()` never resolves while a Shiny app runs | `shiny::runApp()` blocks the kernel; use `createShiny()` (which passes `timeout: 0`) and `interrupt()` to stop it. |
+| `interrupt()` returned `false` | The kernel did not answer within 5 s: it is blocked waiting for `input()`, stuck in native code, or dead. See [Interrupting](guides/interrupting.md#limits). |
+| A request (`complete`, `kernelInfo`, …) times out after 10 s | The kernel is busy running code — requests other than interrupt wait for the running execution. |
+| `Timed out waiting for a <x>_reply after <n>ms` | Same, or the kernel is hung. |
+| Comm messages seem lost | Attach the `'comm'` listener before running the R code that opens the comm; register the target before `new_comm()` (an unregistered target yields `NULL`). Comms only exist in R sessions. |
+
+## Crashed and unresponsive sessions
+
+| You see | Meaning |
+|---|---|
+| `'exit'` with `kernel process exited unexpectedly (process exited with code 0xc0000005 (STATUS_ACCESS_VIOLATION -- a native crash, e.g. in a compiled R package))` | The kernel process died. Common codes are decoded (`STATUS_STACK_OVERFLOW`, `STATUS_STACK_BUFFER_OVERRUN`). `await session.restart()` recovers the session under the same id. |
+| `'exit'` with `heartbeat gave up waiting for a response (…)` | The process is alive but stopped answering pings for about a minute — deadlocked or stuck in a native call. Restart it. |
+| `session.status().heartbeat` shows `misses > 0` (the playground's HEARTBEAT readout says "no reply") | The kernel process is still there but is not answering pings — it is stuck (deadlocked, or inside a native call that never returns), not merely busy: a busy kernel keeps answering from its heartbeat thread. If it does not recover, the heartbeat gives up after about a minute and you get the `'exit'` event above; restart it earlier if you can't wait. |
+| `'exit'` with `kernel process exited unexpectedly` while the heartbeat looked healthy a moment before | The process died between pings; process exit is detected by the OS process handle within milliseconds and does not wait for the heartbeat. `heartbeat` is a liveness hint, the exit event is authoritative. |
+| `'exit'` with `WebSocket connection to the supervisor closed unexpectedly` | The supervisor process is gone; create a new `SessionManager`. |
+| `Cannot restart session <id>: it was already stopped` | `stop()` is final. Create a new session. |
+| Orphaned `elara`/`carpo` processes after a hard kill of Node | Kernels normally die with the supervisor (a Windows job object kills them when it exits); a supervisor that itself survived (killed test runner) keeps them. End the `themisto` process. |
+
+## Interrupt does nothing
+
+- Idle kernel: nothing to interrupt (that is normal; `interrupt()` still returns `true`).
+- Long native call (a C extension, a blocking read): interrupted only when it returns to the interpreter.
+- Waiting on `input()`: answer it first.
+- Linux/macOS: the interrupt path there (`pthread_kill`) is newer than the Windows one; if a Python `time.sleep()` does not wake on your platform, please report it with the platform and Python version.
+
+## Playground
+
+| Symptom | Fix |
+|---|---|
+| `next: not found` / dependencies missing | `npm run playground:install` (the playground has its own `node_modules`). |
+| Sessions fail with the supervisor executable missing | Run `npm run build` first; or set `JOVIAN_NATIVE_DIR`. |
+| R/Python not pre-filled | Set `R_HOME` / `PYTHONHOME`, or enter the paths in the *New Kernel Session* dialog. |
+| Port in use | `PLAYGROUND_PORT=4200 npm run playground`. |

package/lib/execution/execution-queue.d.ts

@@ -0,0 +1,20 @@
+import type { EventEmitter } from 'events';
+import type { ExecutionOptions, ExecutionResult } from '../types/index.js';
+import type { Logger } from '../utils/logger.js';
+export declare class ExecutionQueue {
+    private queue;
+    private executing;
+    private addon;
+    private maxSize;
+    private pending;
+    private logger?;
+    private onTimeout?;
+    constructor(addon: any, emitter: EventEmitter, maxSize?: number, logger?: Logger, onTimeout?: (msgId: string) => void);
+    execute(code: string, options?: ExecutionOptions): Promise<ExecutionResult>;
+    private processNext;
+    private handleMessage;
+    private abortQueued;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=execution-queue.d.ts.map

package/lib/execution/execution-queue.js

@@ -0,0 +1,256 @@
+const DEFAULT_TIMEOUT_MS = 30000;
+const ABORTED_MESSAGE = 'Execution aborted: an earlier execution failed with stopOnError';
+export class ExecutionQueue {
+    queue = [];
+    executing = false;
+    addon;
+    maxSize;
+    pending = new Map();
+    logger;
+    onTimeout;
+    // `onTimeout` is called when an execution times out (unless that
+    // execution opted out with interruptOnTimeout: false), so the owner can
+    // interrupt the kernel -- otherwise the kernel keeps running code nobody
+    // is waiting for, and everything queued behind it (and every complete/
+    // inspect request) is stuck behind it.
+    constructor(addon, emitter, maxSize = 100, logger, onTimeout) {
+        this.addon = addon;
+        this.onTimeout = onTimeout;
+        this.maxSize = maxSize;
+        this.logger = logger;
+        emitter.on('message', (message) => this.handleMessage(message));
+    }
+    execute(code, options = {}) {
+        return new Promise((resolve, reject) => {
+            if (this.queue.length >= this.maxSize) {
+                this.logger?.error(`Execution queue is full (maxSize=${this.maxSize}); rejecting new request`);
+                reject(new Error('Execution queue is full'));
+                return;
+            }
+            this.logger?.trace(`Queued execution (queue depth: ${this.queue.length + 1})`, { timeout: options.timeout });
+            this.queue.push({
+                code,
+                options,
+                resolve,
+                reject,
+                timestamp: Date.now()
+            });
+            // Start processing if not already executing
+            if (!this.executing) {
+                this.processNext();
+            }
+        });
+    }
+    processNext() {
+        if (this.queue.length === 0) {
+            this.executing = false;
+            return;
+        }
+        this.executing = true;
+        const item = this.queue.shift();
+        const queuedMs = Date.now() - item.timestamp;
+        let msgId;
+        try {
+            msgId = this.addon.execute(item.code, item.options);
+        }
+        catch (error) {
+            this.logger?.error('Native addon threw while starting execution', { error, queuedMs });
+            item.reject(error);
+            this.processNext();
+            return;
+        }
+        if (!msgId) {
+            this.logger?.error('Native addon did not return a message id for this execution', { queuedMs });
+            item.reject(new Error('Native addon did not return a message id for this execution'));
+            this.processNext();
+            return;
+        }
+        this.logger?.trace(`Execution ${msgId} started after ${queuedMs}ms in queue`);
+        // A timeout of 0 means "no timeout" -- used for long-running calls
+        // that intentionally block the R session until something external
+        // stops them (e.g. shiny::runApp(), see Session.createShiny in
+        // lib/session/session-manager.ts).
+        // Note this also means no *further* queued execute() calls will be
+        // sent until this one's execute_reply arrives, since R itself is
+        // single-threaded and busy running it.
+        const timeoutMs = item.options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const timer = timeoutMs > 0
+            ? setTimeout(() => {
+                this.logger?.error(`Execution ${msgId} timed out after ${timeoutMs}ms`, { code: previewCode(item.code) });
+                this.pending.delete(msgId);
+                const interrupting = item.options.interruptOnTimeout !== false && this.onTimeout !== undefined;
+                if (interrupting) {
+                    try {
+                        this.onTimeout(msgId);
+                    }
+                    catch (error) {
+                        this.logger?.error('Interrupting after a timeout failed', { error });
+                    }
+                }
+                item.reject(new Error(`Execution timed out after ${timeoutMs}ms` + (interrupting ? ' (the kernel was interrupted)' : '')));
+                this.processNext();
+            }, timeoutMs)
+            : undefined;
+        this.pending.set(msgId, {
+            stopOnError: item.options.stopOnError === true,
+            output: [],
+            timer,
+            finish: (result) => {
+                clearTimeout(timer);
+                this.pending.delete(msgId);
+                this.logger?.trace(`Execution ${msgId} finished`, { success: result.success, outputMessages: result.output?.length ?? 0 });
+                item.resolve(result);
+                this.processNext();
+            },
+            reject: (error) => {
+                clearTimeout(timer);
+                this.pending.delete(msgId);
+                this.logger?.error(`Execution ${msgId} rejected`, { error });
+                item.reject(error);
+            }
+        });
+    }
+    handleMessage(message) {
+        const pending = this.pending.get(message.parentMsgId);
+        if (!pending) {
+            return;
+        }
+        switch (message.msgType) {
+            case 'input_request':
+                // The kernel is now genuinely blocked waiting on a human to
+                // answer a prompt (see Session's own 'input_request' event/
+                // sendInputReply()) -- there's no way to know how long that
+                // will take, so the fixed execution timeout no longer
+                // applies once this arrives. Without this, an execute()
+                // with allowStdin: true could time out from nothing more
+                // than a user taking longer than DEFAULT_TIMEOUT_MS to
+                // answer a prompt, even though the kernel is behaving
+                // completely normally and will resume the moment it gets a
+                // reply.
+                if (pending.timer) {
+                    clearTimeout(pending.timer);
+                    pending.timer = undefined;
+                }
+                break;
+            case 'stream':
+            case 'execute_result':
+            case 'display_data':
+            case 'update_display_data':
+            case 'clear_output':
+                pending.output.push(message);
+                break;
+            case 'error':
+                pending.output.push(message);
+                this.logger?.error(`Execution ${message.parentMsgId} reported an R error`, { evalue: message.content?.evalue });
+                if (pending.stopOnError) {
+                    this.abortQueued();
+                }
+                pending.finish({
+                    success: false,
+                    status: 'error',
+                    output: pending.output,
+                    error: new Error(message.content?.evalue ?? 'R execution error')
+                });
+                break;
+            case 'execute_reply': {
+                const executionCount = message.content?.execution_count;
+                const replyStatus = message.content?.status;
+                const finishNow = () => {
+                    if (replyStatus !== 'ok' && pending.stopOnError) {
+                        this.abortQueued();
+                    }
+                    const result = {
+                        success: replyStatus === 'ok',
+                        output: pending.output,
+                        executionCount
+                    };
+                    if (replyStatus)
+                        result.status = replyStatus;
+                    if (replyStatus === 'aborted') {
+                        result.aborted = true;
+                        result.error = new Error(ABORTED_MESSAGE);
+                    }
+                    const userExpressions = message.content?.user_expressions;
+                    if (userExpressions && Object.keys(userExpressions).length > 0) {
+                        result.userExpressions = userExpressions;
+                    }
+                    pending.finish(result);
+                };
+                // iopub (stream/execute_result/display_data) and shell
+                // (execute_reply) are separate ZMQ channels/sockets with no
+                // cross-channel delivery-order guarantee -- the kernel
+                // publishes iopub content before sending the shell reply
+                // (confirmed directly: RInterpreter/PyInterpreter's own
+                // executeRequestImpl always calls publishExecutionResult()
+                // before invoking the reply callback), but nothing enforces
+                // that this client *observes* them in that same order once
+                // they've gone through themisto's relay. Confirmed as a
+                // real, if rare, flake via CI (a passing execute_reply
+                // resolving with empty output, the execute_result iopub
+                // message arriving microseconds later, too late to matter).
+                // Only a short, bounded wait for output that should exist --
+                // an actually-empty-output execution (e.g. a bare
+                // assignment) still resolves immediately, since this only
+                // triggers on the narrow "ok but nothing collected yet"
+                // case, not on every execution.
+                if (pending.output.length === 0 && message.content?.status === 'ok') {
+                    setTimeout(() => {
+                        if (this.pending.has(message.parentMsgId)) {
+                            finishNow();
+                        }
+                    }, 50);
+                }
+                else {
+                    finishNow();
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // stopOnError: an execution that failed takes everything still waiting
+    // behind it down with it, unrun -- the client-side half of Jupyter's
+    // stop_on_error (the kernel does the same to requests already queued on
+    // ITS side, but this queue is single-flight, so anything behind the
+    // failure is still here, never sent).
+    abortQueued() {
+        if (this.queue.length === 0) {
+            return;
+        }
+        this.logger?.warn(`Aborting ${this.queue.length} queued execution(s) after a failure (stopOnError)`);
+        const aborted = this.queue;
+        this.queue = [];
+        for (const item of aborted) {
+            item.resolve({
+                success: false,
+                status: 'aborted',
+                aborted: true,
+                output: [],
+                error: new Error(ABORTED_MESSAGE)
+            });
+        }
+    }
+    clear() {
+        if (this.queue.length > 0 || this.pending.size > 0) {
+            this.logger?.warn(`Clearing execution queue (${this.queue.length} queued, ${this.pending.size} in flight)`);
+        }
+        this.queue.forEach(item => {
+            item.reject(new Error('Queue cleared'));
+        });
+        this.queue = [];
+        this.executing = false;
+        // Reject in-flight executions too, so callers never end up with a
+        // promise that silently hangs forever (or rejects long after the
+        // caller stopped caring, once its timeout eventually fires).
+        this.pending.forEach(pending => pending.reject(new Error('Queue cleared')));
+    }
+    get size() {
+        return this.queue.length;
+    }
+}
+function previewCode(code, maxLength = 200) {
+    const singleLine = code.replace(/\s+/g, ' ').trim();
+    return singleLine.length > maxLength ? `${singleLine.slice(0, maxLength)}…` : singleLine;
+}
+//# sourceMappingURL=execution-queue.js.map

package/lib/handlers/display-handler.d.ts

@@ -0,0 +1,7 @@
+import type { MessageHandler } from '../messaging/message-router.js';
+import type { JupyterMessage, DisplayDataContent } from '../types/messages.js';
+import { EventEmitter } from 'events';
+export declare class DisplayHandler implements MessageHandler {
+    handle(message: JupyterMessage<DisplayDataContent>, emitter: EventEmitter): void;
+}
+//# sourceMappingURL=display-handler.d.ts.map

package/lib/handlers/display-handler.js

@@ -0,0 +1,10 @@
+export class DisplayHandler {
+    handle(message, emitter) {
+        if (message.content && message.content.data && message.content.data['text/plain']) {
+            const textPlain = message.content.data['text/plain'];
+            const resultText = Array.isArray(textPlain) ? textPlain.join('\n') : textPlain;
+            emitter.emit('result', resultText);
+        }
+    }
+}
+//# sourceMappingURL=display-handler.js.map

package/lib/handlers/error-handler.d.ts

@@ -0,0 +1,7 @@
+import type { MessageHandler } from '../messaging/message-router.js';
+import type { JupyterMessage, ErrorContent } from '../types/messages.js';
+import { EventEmitter } from 'events';
+export declare class ErrorHandler implements MessageHandler {
+    handle(message: JupyterMessage<ErrorContent>, emitter: EventEmitter): void;
+}
+//# sourceMappingURL=error-handler.d.ts.map

package/lib/handlers/error-handler.js

@@ -0,0 +1,8 @@
+export class ErrorHandler {
+    handle(message, emitter) {
+        if (message.content && message.content.evalue) {
+            emitter.emit('error', message.content.evalue);
+        }
+    }
+}
+//# sourceMappingURL=error-handler.js.map

package/lib/handlers/result-handler.d.ts

@@ -0,0 +1,7 @@
+import type { MessageHandler } from '../messaging/message-router.js';
+import type { JupyterMessage, ExecuteResultContent } from '../types/messages.js';
+import { EventEmitter } from 'events';
+export declare class ResultHandler implements MessageHandler {
+    handle(message: JupyterMessage<ExecuteResultContent>, emitter: EventEmitter): void;
+}
+//# sourceMappingURL=result-handler.d.ts.map

package/lib/handlers/result-handler.js

@@ -0,0 +1,10 @@
+export class ResultHandler {
+    handle(message, emitter) {
+        if (message.content && message.content.data && message.content.data['text/plain']) {
+            const textPlain = message.content.data['text/plain'];
+            const resultText = Array.isArray(textPlain) ? textPlain.join('\n') : textPlain;
+            emitter.emit('result', resultText);
+        }
+    }
+}
+//# sourceMappingURL=result-handler.js.map

package/lib/handlers/stream-handler.d.ts

@@ -0,0 +1,7 @@
+import type { MessageHandler } from '../messaging/message-router.js';
+import type { JupyterMessage, StreamContent } from '../types/messages.js';
+import { EventEmitter } from 'events';
+export declare class StreamHandler implements MessageHandler {
+    handle(message: JupyterMessage<StreamContent>, emitter: EventEmitter): void;
+}
+//# sourceMappingURL=stream-handler.d.ts.map

package/lib/handlers/stream-handler.js

@@ -0,0 +1,8 @@
+export class StreamHandler {
+    handle(message, emitter) {
+        if (message.content && message.content.text) {
+            emitter.emit(message.content.name === 'stderr' ? 'stderr' : 'stdout', message.content.text);
+        }
+    }
+}
+//# sourceMappingURL=stream-handler.js.map

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+export { Session, SessionManager } from './session/session-manager.js';
+export { Comm } from './session/comm.js';
+export type { ShinyAppHandle as SessionShinyAppHandle } from './session/session-manager.js';
+export * from './types/index.js';
+export * from './middleware/index.js';
+export type { EngineOptions, ExecutionOptions, ExecutionResult, JupyterMessage, MessageTopic } from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,5 @@
+export { Session, SessionManager } from './session/session-manager.js';
+export { Comm } from './session/comm.js';
+export * from './types/index.js';
+export * from './middleware/index.js';
+//# sourceMappingURL=index.js.map

package/lib/messaging/message-parser.d.ts

@@ -0,0 +1,6 @@
+import type { JupyterMessage } from '../types/messages.js';
+export declare class MessageParser {
+    static parse(raw: string): JupyterMessage;
+    static stringify(message: JupyterMessage): string;
+}
+//# sourceMappingURL=message-parser.d.ts.map

package/lib/messaging/message-parser.js

@@ -0,0 +1,33 @@
+export class MessageParser {
+    static parse(raw) {
+        let envelope;
+        try {
+            envelope = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse message envelope: ${error}`);
+        }
+        if (!envelope || typeof envelope.msg_type !== 'string') {
+            throw new Error(`Invalid message format: ${raw}`);
+        }
+        return {
+            topic: envelope.topic,
+            msgType: envelope.msg_type,
+            channel: envelope.channel,
+            parentMsgId: envelope.parent_msg_id ?? '',
+            content: envelope.content,
+            timestamp: Date.now(),
+            raw
+        };
+    }
+    static stringify(message) {
+        return JSON.stringify({
+            channel: message.channel,
+            topic: message.topic,
+            msg_type: message.msgType,
+            parent_msg_id: message.parentMsgId,
+            content: message.content
+        });
+    }
+}
+//# sourceMappingURL=message-parser.js.map

package/lib/messaging/message-router.d.ts

@@ -0,0 +1,14 @@
+import { EventEmitter } from 'events';
+import type { JupyterMessage } from '../types/messages.js';
+export interface MessageHandler {
+    handle(message: JupyterMessage, emitter: EventEmitter): Promise<void> | void;
+}
+export declare class MessageRouter {
+    private handlers;
+    private emitter;
+    constructor(emitter: EventEmitter);
+    route(rawMessage: string): Promise<void>;
+    private findHandler;
+    registerHandler(msgType: string, handler: MessageHandler): void;
+}
+//# sourceMappingURL=message-router.d.ts.map