@damurka/jovian 0.1.1 → 0.1.2

package/README.md

@@ -36,7 +36,7 @@ The pieces are named after moons of Jupiter:
 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`).
+The package ships **prebuilt** `themisto`, `elara` and `carpo` binaries — no compiler, CMake or vcpkg — for **Windows x64**, **Linux x64 and arm64**, and **macOS x64 (Intel) and arm64 (Apple Silicon)**. Windows on ARM and 32-bit ARM Linux are not supported (there is no ARM64 R for Windows yet); build from source elsewhere 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.13 is required. The package is an ES module: use `import` (in a project with `"type": "module"`, or `.mjs`/`.mts` files), or `require()` it from CommonJS on Node 22.13+.
 
 What you must already have on the machine:
 

package/docs/api/README.md

@@ -21,9 +21,18 @@ import {
 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();
+const manager = new SessionManager();                          // quiet
+const verbose = new SessionManager({ logLevel: 'debug' });     // everything, plus the kernels' own output
 ```
 
+**Logging.** The library is quiet by default: it prints only one-time setup notices (the install of the R packages on the first R session), warnings and errors. A kernel that fails to start reports its own error in the exception's message (`Kernel output: …`). To see more:
+
+| Option / variable | Effect |
+|---|---|
+| `logLevel: 'trace' \| 'debug' \| 'info' \| 'notice' \| 'warn' \| 'error' \| 'silent'` (or env `JOVIAN_LOG_LEVEL`) | What the built-in console logger prints: this level and above. Default `'notice'`. `'debug'` and `'trace'` also print the kernels' start-up output. |
+| `logger: (level, message, data?) => void` | Receives **every** message (do your own filtering) instead of the console. A session's own `logger` option takes precedence for that session. |
+| `kernelOutput: boolean` (or env `JOVIAN_KERNEL_OUTPUT=1`) | Print the kernels' own `[elara]` / `[carpo]` start-up output to stderr as it happens. Default off (on for `debug`/`trace`). |
+
 | 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)). |

package/docs/development.md

@@ -88,8 +88,8 @@ The npm packages are built and published by `.github/workflows/release.yml` from
 
 ## Debugging
 
-- **Kernel logs.** Everything a kernel prints (`[R Interpreter] …`, `[carpo] …`, and anything R/Python writes outside an execution) appears on the *supervisor's* stderr, which `lib/` forwards to your process's stderr, prefixed `[elara]` / `[carpo]`. That is the first place to look when a session fails to start.
-- **Library logs.** Pass `logger` to `createSession()` (or read the default console output): `trace` shows queueing, request ids and timeouts.
+- **Kernel logs.** Everything a kernel prints (`[R Interpreter] …`, `[carpo] …`, and anything R/Python writes outside an execution) appears on the *supervisor's* stderr, prefixed `[elara]` / `[carpo]`. `lib/` keeps it quiet by default (and puts the relevant lines in the error when a kernel fails to start); set `JOVIAN_LOG_LEVEL=debug` (or `JOVIAN_KERNEL_OUTPUT=1`, or `new SessionManager({ kernelOutput: true })`) to forward it to your stderr. That is the first place to look when a session fails to start.
+- **Library logs.** Quiet by default; `JOVIAN_LOG_LEVEL=trace` (or `new SessionManager({ logLevel: 'trace' })`) shows queueing, request ids and timeouts, and `logger` receives every message.
 - **Run a kernel by hand.** Generate a kernelspec (`npm run jupyter:kernelspec`) and start it from `jupyter console --kernel elara`, or run `elara -f <connection-file> --r-home …` yourself — no supervisor involved.
 - **Talk to the supervisor directly.** Start `themisto` (it prints `{"type":"supervisorReady","httpPort":…,"wsPort":…}`) and use `curl` against [its HTTP API](protocol.md#2-themistos-http-api) and any WebSocket client against `ws://127.0.0.1:<wsPort>/sessions/<id>/messages`.
 - **One native test.** `dist/native/Release/session_registry_test.exe --gtest_filter=*Interrupt*` (kernel log noise goes to the same stdout; filter with `grep -v "^\[elara\]"`).

package/docs/releasing.md

@@ -1,12 +1,12 @@
 # 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):
+Jovian is published to npm as six packages under the `@damurka` scope, one library and five platform packages (Windows x64, Linux x64 and arm64, macOS x64 and arm64; see [Platforms that are not supported](#platforms-that-are-not-supported)):
 
 | 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`. |
+| `@damurka/jovian-linux-x64`, `-linux-arm64`, `-darwin-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.
 
@@ -69,20 +69,26 @@ 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
+## Platforms that are not supported
+
+A platform is published only when there is a real R for it to pair with and a runner that can build and smoke-test it end to end.
+
+- **Windows on ARM (`win32-arm64`).** R for Windows on ARM64 is experimental and not on CRAN (no binary packages either), so there is no R for a native ARM64 kernel to load. People on Windows on ARM run x64 R under emulation, which would need the x64 kernel, but npm installs the x64 package only on x64 CPUs. Not supported until R for Windows on ARM64 is released.
+- **32-bit ARM Linux (`linux-armhf`).** GitHub's hosted runners cannot run 32-bit ARM code (the arm64 machines lack AArch32), so it can only be built by cross-compiling and tested under QEMU emulation, which is not set up.
 
-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`:
+Their users get `jovian: there are no prebuilt kernels for <os>-<cpu>` and can build from source and set `JOVIAN_NATIVE_DIR`.
+
+## Adding a platform
 
 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.
+2. Add it to the build matrix in `.github/workflows/release.yml`.
 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`.
+4. A new platform is a **new package on npm**, and npm cannot stage the first version of a package: publish it by hand once (see [The first release is published by hand](#the-first-release-is-published-by-hand)) before the main package that depends on it is approved. The workflow prints a warning naming each such package and does not fail.
 
 ## 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`.
+- **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; the `linux-arm64` build runs on `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.

package/docs/troubleshooting.md

@@ -21,13 +21,13 @@ Messages below are quoted from the code. **First habit:** a kernel that fails to
 | 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`. |
+| `jovian: there are no prebuilt kernels for <os>-<cpu> (supported: …)` | Prebuilt packages exist for `win32-x64`, `linux-x64`, `linux-arm64`, `darwin-x64` and `darwin-arm64` only (Windows on ARM and 32-bit ARM Linux are not supported). 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. |
+| `Kernel process exited before it could register -- check its stderr output for the actual error.` | The kernel crashed at start-up. The exception's message ends with `Kernel output:` and the kernel's own error lines; for the full output run with `JOVIAN_LOG_LEVEL=debug` (or `new SessionManager({ kernelOutput: true })`). See the R / Python sections below. |
+| `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. Run with `JOVIAN_LOG_LEVEL=debug` to print the kernel's output and see 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
@@ -38,6 +38,7 @@ Messages below are quoted from the code. **First habit:** a kernel that fails to
 | `R_HOME is not set -- elara needs a working R installation to run. …` | The library could not find R (it tries `$R_HOME`, `R RHOME`, and on Windows the registry): put R on `PATH` or pass `rHome` (`R RHOME` prints it). |
 | `No libpython3.*.so* … was found under '/lib' … Is Python installed at ''?` | The library could not find Python (it tries `$PYTHONHOME`, then `python3`/`python` on `PATH`): install Python 3 (`sudo apt install python3`) or pass `pythonHome`. |
 | `Could not set up the R packages the kernel needs: …` | The one-time install of `hera` and its dependencies (see the README's Install section) failed; the text after the colon is R's own reason (no internet access to CRAN, no compiler on Linux, a library that cannot be written to). Fix that and call `createSession()` again; it retries. `JOVIAN_SKIP_R_SETUP=1` skips the step. |
+| `ERROR: failed to lock directory '<library>' for modifying. Try removing '<library>/00LOCK-<pkg>'` | An earlier install of that package was interrupted (Ctrl+C, a kill, a timeout) and left its lock folder, which makes R refuse every later install of it. The automatic setup removes locks older than 5 minutes itself; to clear one now: `rm -rf <library>/00LOCK-*` (Windows: delete the `00LOCK-*` folder), then run again. |
 | `unable to load shared object '/usr/lib/R/site-library/<pkg>/libs/<pkg>.so': undefined symbol: SETLENGTH` (or another `undefined symbol`) | Only when the automatic setup is skipped or you install by hand. Debian/Ubuntu: a package installed with `apt` (`r-cran-*`, in `/usr/lib/R/site-library`) was built for an older R than yours (the automatic setup reinstalls these itself). Reinstall it, and everything it needs, from CRAN into your own library, which R searches first. Needs a compiler (`sudo apt install build-essential`):<br>`wanted <- c("remotes","cli","evaluate","glue","IRdisplay","jsonlite","R6","repr","rlang")`<br>`all <- unique(c(wanted, unlist(tools::package_dependencies(wanted, db = available.packages(), recursive = TRUE), use.names = FALSE)))`<br>`ip <- installed.packages(); install.packages(setdiff(all, rownames(ip)[!is.na(ip[, "Priority"])]), repos = "https://cloud.r-project.org")` |
 | `WARNING: 'hera' package could not be loaded (status: install_failed: …)` | Elara could not install the bundled `hera` R package; the text after `install_failed:` is R's own reason. Usually one of `hera`'s CRAN dependencies is missing or cannot be built (install them first: `install.packages(c("remotes", "cli", "evaluate", "glue", "IRdisplay", "jsonlite", "R6", "repr", "rlang"))`), or the R library is not writable. To see the full output run `R CMD INSTALL node_modules/@damurka/jovian/packages/hera`. |
 | `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`. |

package/lib/execution/execution-queue.js

@@ -141,7 +141,7 @@ export class ExecutionQueue {
                 break;
             case 'error':
                 pending.output.push(message);
-                this.logger?.error(`Execution ${message.parentMsgId} reported an R error`, { evalue: message.content?.evalue });
+                this.logger?.debug(`Execution ${message.parentMsgId} reported an R error`, { evalue: message.content?.evalue });
                 if (pending.stopOnError) {
                     this.abortQueued();
                 }

package/lib/session/native-paths.d.ts

@@ -7,7 +7,7 @@ export declare const PACKAGE_NAME = "@damurka/jovian";
  * the main package only where it matches (each declares `os`/`cpu`). These are
  * the platforms that get a package.
  */
-export declare const SUPPORTED_PLATFORMS: readonly ['win32-x64', 'linux-x64', 'darwin-arm64'];
+export declare const SUPPORTED_PLATFORMS: readonly ['win32-x64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'];
 export declare function platformPackageName(platform?: string, arch?: string): string | undefined;
 export interface NativeLocation {
     /** Directory holding themisto, elara and carpo. */

package/lib/session/native-paths.js

@@ -11,7 +11,7 @@ export const PACKAGE_NAME = `${PACKAGE_SCOPE}/jovian`;
  * the main package only where it matches (each declares `os`/`cpu`). These are
  * the platforms that get a package.
  */
-export const SUPPORTED_PLATFORMS = ['win32-x64', 'linux-x64', 'darwin-arm64'];
+export const SUPPORTED_PLATFORMS = ['win32-x64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'];
 export function platformPackageName(platform = process.platform, arch = process.arch) {
     const key = `${platform}-${arch}`;
     return SUPPORTED_PLATFORMS.includes(key) ? `${PACKAGE_NAME}-${key}` : undefined;

package/lib/session/r-setup.d.ts

@@ -20,6 +20,7 @@ export declare const R_SETUP_SCRIPT: string;
 export interface SetupLogger {
     debug(message: string): void;
     info(message: string): void;
+    notice(message: string): void;
 }
 export interface SetupProcessOutcome {
     code: number | null;

package/lib/session/r-setup.js

@@ -24,6 +24,7 @@ import { createInterface } from 'node:readline';
 export const R_SETUP_SCRIPT = String.raw `
 src <- commandArgs(trailingOnly = TRUE)[1]
 say <- function(...) cat("JOVIAN_R_SETUP: ", ..., "\n", sep = "")
+note <- function(...) cat("JOVIAN_R_SETUP_INFO: ", ..., "\n", sep = "")
 fail <- function(...) {
     cat("JOVIAN_R_SETUP_ERROR: ", ..., "\n", sep = "")
     quit(save = "no", status = 1)
@@ -41,7 +42,7 @@ hera_current <- function() {
     suppressWarnings(suppressMessages(requireNamespace("hera", quietly = TRUE)))
 }
 if (hera_current()) {
-    say("hera is already installed")
+    note("hera is already installed")
     quit(save = "no", status = 0)
 }
 
@@ -59,6 +60,15 @@ if (is.na(lib)) {
     .libPaths(c(lib, .libPaths()))
 }
 
+for (lock in Sys.glob(file.path(lib, "00LOCK-*"))) {
+    # An install that was killed (Ctrl+C, a timeout) leaves its lock behind, and
+    # every later install of that package is refused until it is removed.
+    if (difftime(Sys.time(), file.info(lock)$mtime, units = "mins") > 5) {
+        say("removing a stale lock left by an interrupted install: ", lock)
+        unlink(lock, recursive = TRUE)
+    }
+}
+
 ip <- installed.packages()
 base_packages <- rownames(ip)[!is.na(ip[, "Priority"])]
 fields <- tryCatch(read.dcf(file.path(src, "DESCRIPTION"), fields = c("Depends", "Imports", "LinkingTo")), error = function(e) NULL)
@@ -90,9 +100,28 @@ if (length(missing) > 0) {
              error = function(e) fail("installing R packages failed: ", conditionMessage(e)))
     still_missing <- missing[!vapply(missing, usable, logical(1))]
     if (length(still_missing) > 0) {
+        # The warnings only say "non-zero exit status". Packages that need
+        # another one that failed fail too, so re-run the install of the ones
+        # that do not, on their own, and report what R and the compiler said.
+        needs <- tryCatch(tools::package_dependencies(still_missing, db = available, recursive = FALSE), error = function(e) list())
+        roots <- still_missing[vapply(still_missing, function(p) !any(needs[[p]] %in% still_missing), logical(1))]
+        reasons <- character()
+        for (p in utils::head(roots, 2)) {
+            why <- tryCatch({
+                tarball <- utils::download.packages(p, destdir = tempdir(), repos = getOption("repos"), type = "source", quiet = TRUE)[1, 2]
+                out <- suppressWarnings(system2(file.path(R.home("bin"), "R"), c("CMD", "INSTALL", paste0("--library=", shQuote(lib)), shQuote(tarball)), stdout = TRUE, stderr = TRUE))
+                if (is.null(attr(out, "status")) || identical(attr(out, "status"), 0L)) {
+                    "it installed when retried on its own, so the failure may be temporary: try again"
+                } else {
+                    important <- grep("error|ERROR|undefined|fatal|cannot|not found|No such file|Killed", out, value = TRUE)
+                    substr(gsub("[[:space:]]+", " ", paste(utils::tail(if (length(important)) important else out, 5), collapse = " ; ")), 1, 700)
+                }
+            }, error = function(e) conditionMessage(e))
+            reasons <- c(reasons, paste0(p, ": ", why))
+        }
         fail("could not install these R packages: ", paste(still_missing, collapse = ", "),
-             " -- on Linux they are compiled from source, which needs a compiler (Ubuntu: sudo apt install build-essential)",
-             if (length(warnings_seen)) paste0(" | ", substr(paste(unique(warnings_seen), collapse = " | "), 1, 400)) else "")
+             if (length(reasons)) paste0(" -- ", paste(reasons, collapse = " | ")) else "",
+             " (on Linux packages are compiled from source and need a compiler: sudo apt install build-essential)")
     }
 }
 
@@ -187,7 +216,9 @@ async function setUp(rscript, heraSrcPath, rLibs, logger, deps) {
             if (line.startsWith('JOVIAN_R_SETUP_ERROR: '))
                 failure = line.slice('JOVIAN_R_SETUP_ERROR: '.length);
             else if (line.startsWith('JOVIAN_R_SETUP: '))
-                logger.info(`R setup: ${line.slice('JOVIAN_R_SETUP: '.length)}`);
+                logger.notice(`R setup: ${line.slice('JOVIAN_R_SETUP: '.length)}`);
+            else if (line.startsWith('JOVIAN_R_SETUP_INFO: '))
+                logger.info(`R setup: ${line.slice('JOVIAN_R_SETUP_INFO: '.length)}`);
             else if (line.trim())
                 otherOutput.push(line.trim());
         };

package/lib/session/session-manager.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import type { CommInfoReplyContent, CompleteReplyContent, EngineOptions, ExecutionHistoryEntry, ExecutionOptions, ExecutionResult, InspectReplyContent, IsCompleteReplyContent, KernelHistoryEntry, KernelHistoryOptions, KernelInfoReplyContent, SessionStatusInfo, ShinyAppHandle, ShinyAppOptions } from '../types/index.js';
+import type { CommInfoReplyContent, CompleteReplyContent, EngineOptions, ExecutionHistoryEntry, ExecutionOptions, ExecutionResult, InspectReplyContent, IsCompleteReplyContent, KernelHistoryEntry, KernelHistoryOptions, KernelInfoReplyContent, LoggerFunction, LogThreshold, SessionManagerOptions, SessionStatusInfo, ShinyAppHandle, ShinyAppOptions } from '../types/index.js';
 import type { ExecutionState } from '../types/messages.js';
 import { SupervisorClient, type SessionConnectionInfo } from './supervisor-client.js';
 import { Comm } from './comm.js';
@@ -27,7 +27,10 @@ export declare class Session extends EventEmitter {
     private readonly executionHistory;
     private readonly executionHistoryByMsgId;
     private readonly historyStreamChars;
-    constructor(info: SessionConnectionInfo, options: EngineOptions, supervisor: SupervisorClient);
+    constructor(info: SessionConnectionInfo, options: EngineOptions, supervisor: SupervisorClient, logging?: {
+        level?: LogThreshold | undefined;
+        logger?: LoggerFunction | undefined;
+    });
     /**
      * (Re)establishes the WebSocket to this.info's session and resolves
      * once it's ready. Used both by the constructor and by restart() --
@@ -209,10 +212,18 @@ export declare class Session extends EventEmitter {
     kill(): void;
 }
 export declare class SessionManager {
+    private readonly logLevel;
+    private readonly customLogger;
     private readonly logger;
     private readonly supervisor;
     private readonly sessions;
     private exitHandlerRegistered;
+    /**
+     * Quiet by default: only one-time setup notices, warnings and errors are
+     * printed. See SessionManagerOptions for `logLevel`, `logger` and
+     * `kernelOutput` (and the JOVIAN_LOG_LEVEL / JOVIAN_KERNEL_OUTPUT variables).
+     */
+    constructor(options?: SessionManagerOptions);
     /** Creates a new R session in its own OS process and waits for it to be ready. */
     createSession(requested?: EngineOptions): Promise<Session>;
     /** Gracefully stops every session managed by this instance. */

package/lib/session/session-manager.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
-import { Logger } from '../utils/logger.js';
+import { Logger, defaultLogLevel } from '../utils/logger.js';
 import { MessageRouter } from '../messaging/message-router.js';
 import { ExecutionQueue } from '../execution/execution-queue.js';
 import { MiddlewareChain } from '../middleware/middleware-chain.js';
@@ -89,12 +89,12 @@ export class Session extends EventEmitter {
     executionHistory = [];
     executionHistoryByMsgId = new Map();
     historyStreamChars = new WeakMap();
-    constructor(info, options, supervisor) {
+    constructor(info, options, supervisor, logging = {}) {
         super();
         this.info = info;
         this.currentOptions = options;
         this.supervisor = supervisor;
-        this.logger = new Logger(options.logger);
+        this.logger = new Logger(options.logger ?? logging.logger, logging.level);
         this.on('message', (message) => {
             this.recordExecutionHistory(message);
             this.settleRequest(message);
@@ -781,10 +781,25 @@ export class Session extends EventEmitter {
     }
 }
 export class SessionManager {
-    logger = new Logger();
-    supervisor = new SupervisorClient(this.logger);
+    logLevel;
+    customLogger;
+    logger;
+    supervisor;
     sessions = new Set();
     exitHandlerRegistered = false;
+    /**
+     * Quiet by default: only one-time setup notices, warnings and errors are
+     * printed. See SessionManagerOptions for `logLevel`, `logger` and
+     * `kernelOutput` (and the JOVIAN_LOG_LEVEL / JOVIAN_KERNEL_OUTPUT variables).
+     */
+    constructor(options = {}) {
+        this.logLevel = options.logLevel ?? defaultLogLevel();
+        this.customLogger = options.logger;
+        this.logger = new Logger(this.customLogger, this.logLevel);
+        const verbose = this.logLevel === 'trace' || this.logLevel === 'debug';
+        const forwardKernelOutput = options.kernelOutput ?? (Boolean(process.env.JOVIAN_KERNEL_OUTPUT) || verbose);
+        this.supervisor = new SupervisorClient(this.logger, { forwardKernelOutput });
+    }
     /** Creates a new R session in its own OS process and waits for it to be ready. */
     async createSession(requested = {}) {
         // Finds R / Python when rHome / pythonHome were not given (see runtimes.ts).
@@ -793,7 +808,7 @@ export class SessionManager {
         // First R session only: installs hera and what it needs (see r-setup.ts).
         await ensureRPackages(options, this.logger);
         const info = await this.supervisor.createSession(options);
-        const session = new Session(info, options, this.supervisor);
+        const session = new Session(info, options, this.supervisor, { level: this.logLevel, logger: this.customLogger });
         this.sessions.add(session);
         this.registerExitHandler();
         try {
@@ -809,7 +824,7 @@ export class SessionManager {
     async stopAll() {
         await Promise.all([...this.sessions].map((session) => session.stop()));
         this.sessions.clear();
-        this.supervisor.kill();
+        this.supervisor.kill(true);
     }
     /**
      * Forcibly terminates every session. Prefer stopAll(), but a session

package/lib/session/supervisor-client.d.ts

@@ -10,7 +10,14 @@ export declare class SupervisorClient {
     private child;
     private readyPromise;
     private readonly logger;
-    constructor(logger: Logger);
+    private readonly forwardKernelOutput;
+    private readonly recentOutput;
+    constructor(logger: Logger, options?: {
+        forwardKernelOutput?: boolean;
+    });
+    private rememberOutput;
+    /** The message plus what the kernels said just before, when that was not already printed. */
+    private withKernelOutput;
     private ensureStarted;
     private spawnSupervisor;
     createSession(options: EngineOptions): Promise<SessionConnectionInfo>;
@@ -30,7 +37,11 @@ export declare class SupervisorClient {
      * close this session and create a new one just to pick a different R.
      */
     restartSession(info: SessionConnectionInfo, options?: Partial<EngineOptions>): Promise<void>;
-    /** Skips graceful per-session shutdown -- only for cleanup on the way out. */
-    kill(): void;
+    /**
+     * Skips graceful per-session shutdown -- only for cleanup on the way out.
+     * `expected` is the normal end of stopAll(), after every session was
+     * stopped: not worth a warning.
+     */
+    kill(expected?: boolean): void;
 }
 //# sourceMappingURL=supervisor-client.d.ts.map

package/lib/session/supervisor-client.js

@@ -33,8 +33,29 @@ export class SupervisorClient {
     child;
     readyPromise;
     logger;
-    constructor(logger) {
+    forwardKernelOutput;
+    // The supervisor's stderr is where every kernel's start-up output ends up
+    // ([elara] ..., [carpo] ...). It is kept, not printed, unless asked for,
+    // and attached to the error when a kernel fails to start.
+    recentOutput = [];
+    constructor(logger, options = {}) {
         this.logger = logger;
+        this.forwardKernelOutput = options.forwardKernelOutput ?? false;
+    }
+    rememberOutput(line) {
+        if (!line.trim())
+            return;
+        this.recentOutput.push(line);
+        if (this.recentOutput.length > 200)
+            this.recentOutput.shift();
+    }
+    /** The message plus what the kernels said just before, when that was not already printed. */
+    withKernelOutput(message) {
+        if (this.forwardKernelOutput || this.recentOutput.length === 0)
+            return message;
+        const notable = this.recentOutput.filter((line) => /error|fatal|warning|failed|cannot|not found|no such/i.test(line));
+        const lines = (notable.length > 0 ? notable : this.recentOutput).slice(-8);
+        return `${message}\nKernel output:\n  ${lines.join('\n  ')}`;
     }
     ensureStarted() {
         if (!this.readyPromise) {
@@ -48,7 +69,11 @@ export class SupervisorClient {
             this.logger.debug(`Spawning supervisor process from: ${exePath}`);
             const child = spawn(exePath, [], { stdio: ['ignore', 'pipe', 'pipe'] });
             this.child = child;
-            child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+            createInterface({ input: child.stderr }).on('line', (line) => {
+                this.rememberOutput(line);
+                if (this.forwardKernelOutput)
+                    process.stderr.write(`${line}\n`);
+            });
             const rl = createInterface({ input: child.stdout });
             const onLine = (line) => {
                 let message;
@@ -87,7 +112,7 @@ export class SupervisorClient {
         });
         const body = await res.json();
         if (!res.ok || !body.sessionId) {
-            throw new Error(body.error ?? `Supervisor failed to create session (HTTP ${res.status})`);
+            throw new Error(this.withKernelOutput(body.error ?? `Supervisor failed to create session (HTTP ${res.status})`));
         }
         return { sessionId: body.sessionId, httpBase, wsBase: `ws://127.0.0.1:${wsPort}` };
     }
@@ -126,10 +151,18 @@ export class SupervisorClient {
             throw new Error(body.error ?? `Supervisor failed to restart session ${info.sessionId} (HTTP ${res.status})`);
         }
     }
-    /** Skips graceful per-session shutdown -- only for cleanup on the way out. */
-    kill() {
+    /**
+     * Skips graceful per-session shutdown -- only for cleanup on the way out.
+     * `expected` is the normal end of stopAll(), after every session was
+     * stopped: not worth a warning.
+     */
+    kill(expected = false) {
         if (this.child && !this.child.killed) {
-            this.logger.warn(`Force-killing supervisor process (pid ${this.child.pid})`);
+            const message = `Force-killing supervisor process (pid ${this.child.pid})`;
+            if (expected)
+                this.logger.debug(message);
+            else
+                this.logger.warn(message);
             this.child.kill();
         }
     }

package/lib/types/engine.d.ts

@@ -1,5 +1,29 @@
 import type { JupyterMessage } from './messages.js';
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 'notice' is for the few things a user should be told even when the library
+ * is otherwise quiet (e.g. the one-time install of the R packages, which takes
+ * a while); it sits between 'info' and 'warn'.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'notice' | 'warn' | 'error';
+/** What the built-in console logger prints: this level and above; 'silent' prints nothing. */
+export type LogThreshold = LogLevel | 'silent';
+export interface SessionManagerOptions {
+    /**
+     * How much the library prints to the console (default 'notice': one-time
+     * setup messages, warnings and errors; env JOVIAN_LOG_LEVEL sets the
+     * default). Ignored for messages sent to `logger`, which receives all of them.
+     */
+    logLevel?: LogThreshold | undefined;
+    /** Receives every log message instead of the console. */
+    logger?: LoggerFunction | undefined;
+    /**
+     * Print the kernels' own start-up output (the `[elara]` / `[carpo]` lines)
+     * to stderr as it happens. Off by default -- it is included in the error
+     * when a kernel fails to start -- and on when logLevel is 'debug' or
+     * 'trace' or env JOVIAN_KERNEL_OUTPUT is set.
+     */
+    kernelOutput?: boolean | undefined;
+}
 export type LoggerFunction = (level: LogLevel, message: string, data?: any) => void;
 export interface EngineOptions {
     /**

package/lib/utils/logger.d.ts

@@ -1,11 +1,22 @@
-import type { LoggerFunction } from '../types/index.js';
+import type { LogLevel, LoggerFunction, LogThreshold } from '../types/index.js';
 export declare function timestamp(): string;
+/** True when a message at `level` passes `threshold`. */
+export declare function passes(threshold: LogThreshold, level: LogLevel): boolean;
+/** The console threshold when none is given: $JOVIAN_LOG_LEVEL if it names one, else 'notice'. */
+export declare function defaultLogLevel(env?: Record<string, string | undefined>): LogThreshold;
 export declare class Logger {
-    private customLogger?;
-    constructor(customLogger?: LoggerFunction);
+    private readonly customLogger;
+    private readonly threshold;
+    /**
+     * A custom logger receives every message (it does its own filtering, as it
+     * always has); `threshold` only limits what is printed to the console.
+     */
+    constructor(customLogger?: LoggerFunction, threshold?: LogThreshold);
+    private emit;
     trace(message: string, data?: any): void;
     debug(message: string, data?: any): void;
     info(message: string, data?: any): void;
+    notice(message: string, data?: any): void;
     warn(message: string, data?: any): void;
     error(message: string, error?: any): void;
 }

package/lib/utils/logger.js

@@ -9,50 +9,58 @@ export function timestamp() {
     return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
         `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}`;
 }
+const ORDER = { trace: 0, debug: 1, info: 2, notice: 3, warn: 4, error: 5, silent: 6 };
+/** True when a message at `level` passes `threshold`. */
+export function passes(threshold, level) {
+    return ORDER[level] >= ORDER[threshold];
+}
+/** The console threshold when none is given: $JOVIAN_LOG_LEVEL if it names one, else 'notice'. */
+export function defaultLogLevel(env = process.env) {
+    const wanted = env.JOVIAN_LOG_LEVEL?.trim().toLowerCase();
+    return wanted && wanted in ORDER ? wanted : 'notice';
+}
 export class Logger {
     customLogger;
-    constructor(customLogger) {
+    threshold;
+    /**
+     * A custom logger receives every message (it does its own filtering, as it
+     * always has); `threshold` only limits what is printed to the console.
+     */
+    constructor(customLogger, threshold = defaultLogLevel()) {
         this.customLogger = customLogger;
+        this.threshold = threshold;
     }
-    trace(message, data) {
+    emit(level, message, data) {
         if (this.customLogger) {
-            this.customLogger('trace', message, data);
-        }
-        else {
-            console.log(`${timestamp()} [trace] ${message}`, data ? data : '');
+            this.customLogger(level, message, data);
+            return;
         }
+        if (!passes(this.threshold, level))
+            return;
+        const print = level === 'warn' ? console.warn : level === 'error' ? console.error : console.log;
+        const line = `${timestamp()} [${level}] ${message}`;
+        if (data)
+            print(line, data);
+        else
+            print(line);
+    }
+    trace(message, data) {
+        this.emit('trace', message, data);
     }
     debug(message, data) {
-        if (this.customLogger) {
-            this.customLogger('debug', message, data);
-        }
-        else {
-            console.log(`${timestamp()} [debug] ${message}`, data ? data : '');
-        }
+        this.emit('debug', message, data);
     }
     info(message, data) {
-        if (this.customLogger) {
-            this.customLogger('info', message, data);
-        }
-        else {
-            console.log(`${timestamp()} [info] ${message}`, data ? data : '');
-        }
+        this.emit('info', message, data);
+    }
+    notice(message, data) {
+        this.emit('notice', message, data);
     }
     warn(message, data) {
-        if (this.customLogger) {
-            this.customLogger('warn', message, data);
-        }
-        else {
-            console.warn(`${timestamp()} [warn] ${message}`, data ? data : '');
-        }
+        this.emit('warn', message, data);
     }
     error(message, error) {
-        if (this.customLogger) {
-            this.customLogger('error', message, error);
-        }
-        else {
-            console.error(`${timestamp()} [error] ${message}`, error ? error : '');
-        }
+        this.emit('error', message, error);
     }
 }
 //# sourceMappingURL=logger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damurka/jovian",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "author": "David Kariuki",
   "repository": {
@@ -31,16 +31,18 @@
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "import": "./lib/index.js"
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
     },
     "./types": {
       "types": "./lib/types/index.d.ts",
-      "import": "./lib/types/index.js"
+      "import": "./lib/types/index.js",
+      "default": "./lib/types/index.js"
     },
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=22.4.0"
+    "node": ">=22.13.0"
   },
   "files": [
     "lib",
@@ -50,8 +52,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@damurka/jovian-win32-x64": "0.1.1",
-    "@damurka/jovian-linux-x64": "0.1.1",
-    "@damurka/jovian-darwin-arm64": "0.1.1"
+    "@damurka/jovian-win32-x64": "0.1.2",
+    "@damurka/jovian-linux-x64": "0.1.2",
+    "@damurka/jovian-linux-arm64": "0.1.2",
+    "@damurka/jovian-darwin-x64": "0.1.2",
+    "@damurka/jovian-darwin-arm64": "0.1.2"
   }
 }

package/packages/hera/DESCRIPTION

@@ -26,4 +26,4 @@ Imports:
 URL: https://github.com/damurka/jovian
 BugReports: https://github.com/damurka/jovian/issues
 Config/roxygen2/version: 8.0.0
-Config/jovian/release: 0.1.1
+Config/jovian/release: 0.1.2