@damurka/jovian 0.1.0

package/lib/messaging/message-router.js

@@ -0,0 +1,41 @@
+import { MessageParser } from './message-parser.js';
+export class MessageRouter {
+    handlers;
+    emitter;
+    constructor(emitter) {
+        this.emitter = emitter;
+        this.handlers = new Map();
+    }
+    async route(rawMessage) {
+        const message = MessageParser.parse(rawMessage);
+        // Emit raw message event
+        this.emitter.emit('*', message.msgType, message.content);
+        this.emitter.emit('message', message);
+        // Route to specific handler (dispatch on the plain msg_type, e.g.
+        // "stream" / "execute_result" — `topic` is a kernel-namespaced
+        // string like "kernel_core.<id>.stream" and isn't matched here)
+        const handler = this.findHandler(message.msgType);
+        if (handler) {
+            await handler.handle(message, this.emitter);
+        }
+        // Always emit msg_type-specific event
+        this.emitter.emit(message.msgType, message.content);
+    }
+    findHandler(msgType) {
+        // Exact match
+        if (this.handlers.has(msgType)) {
+            return this.handlers.get(msgType);
+        }
+        // Prefix match (e.g., "stream" matches "stream.stdout")
+        for (const [key, handler] of this.handlers) {
+            if (msgType.startsWith(key)) {
+                return handler;
+            }
+        }
+        return undefined;
+    }
+    registerHandler(msgType, handler) {
+        this.handlers.set(msgType, handler);
+    }
+}
+//# sourceMappingURL=message-router.js.map

package/lib/middleware/index.d.ts

@@ -0,0 +1,5 @@
+export * from './middleware.js';
+export * from './middleware-chain.js';
+export * from './plugins/logging-plugin.js';
+export * from './plugins/metrics-plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/middleware/index.js

@@ -0,0 +1,5 @@
+export * from './middleware.js';
+export * from './middleware-chain.js';
+export * from './plugins/logging-plugin.js';
+export * from './plugins/metrics-plugin.js';
+//# sourceMappingURL=index.js.map

package/lib/middleware/middleware-chain.d.ts

@@ -0,0 +1,7 @@
+import type { Middleware } from './middleware.js';
+export declare class MiddlewareChain {
+    private middlewares;
+    use(middleware: Middleware): void;
+    process(message: string): Promise<string>;
+}
+//# sourceMappingURL=middleware-chain.d.ts.map

package/lib/middleware/middleware-chain.js

@@ -0,0 +1,14 @@
+export class MiddlewareChain {
+    middlewares = [];
+    use(middleware) {
+        this.middlewares.push(middleware);
+    }
+    async process(message) {
+        let result = message;
+        for (const middleware of this.middlewares) {
+            result = await middleware.process(result);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=middleware-chain.js.map

package/lib/middleware/middleware.d.ts

@@ -0,0 +1,5 @@
+export interface Middleware {
+    name: string;
+    process(message: string): Promise<string> | string;
+}
+//# sourceMappingURL=middleware.d.ts.map

package/lib/middleware/middleware.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=middleware.js.map

package/lib/middleware/plugins/logging-plugin.d.ts

@@ -0,0 +1,6 @@
+import type { Middleware } from '../middleware.js';
+export declare class LoggingMiddleware implements Middleware {
+    name: string;
+    process(message: string): string;
+}
+//# sourceMappingURL=logging-plugin.d.ts.map

package/lib/middleware/plugins/logging-plugin.js

@@ -0,0 +1,9 @@
+export class LoggingMiddleware {
+    name = 'logging';
+    process(message) {
+        const timestamp = new Date().toISOString();
+        console.log(`[${timestamp}] Message: ${message.substring(0, 100)}...`);
+        return message;
+    }
+}
+//# sourceMappingURL=logging-plugin.js.map

package/lib/middleware/plugins/metrics-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { Middleware } from '../middleware.js';
+export declare class MetricsMiddleware implements Middleware {
+    name: string;
+    private messageCount;
+    private startTime;
+    process(message: string): string;
+}
+//# sourceMappingURL=metrics-plugin.d.ts.map

package/lib/middleware/plugins/metrics-plugin.js

@@ -0,0 +1,13 @@
+export class MetricsMiddleware {
+    name = 'metrics';
+    messageCount = 0;
+    startTime = Date.now();
+    process(message) {
+        this.messageCount++;
+        const elapsed = (Date.now() - this.startTime) / 1000;
+        const rate = this.messageCount / elapsed;
+        console.log(`Messages/sec: ${rate.toFixed(2)}`);
+        return message;
+    }
+}
+//# sourceMappingURL=metrics-plugin.js.map

package/lib/session/comm.d.ts

@@ -0,0 +1,39 @@
+import { EventEmitter } from 'events';
+/**
+ * The parts of a Session a Comm needs -- kept as an interface so this file
+ * doesn't import session-manager (which imports it).
+ */
+export interface CommTransport {
+    commMsg(commId: string, data: Record<string, unknown>): Promise<string>;
+    commClose(commId: string, data: Record<string, unknown>): Promise<string>;
+}
+/**
+ * One open comm: a named, bidirectional message channel between this client
+ * and a target registered inside the kernel (in R, `hera::CommManager$
+ * register_comm_target()`).
+ *
+ * Get one either from `session.openComm(target)` (client-initiated) or from
+ * the session's `'comm'` event (kernel-initiated, e.g. R calling
+ * `CommManager$new_comm()` then `$open()`).
+ *
+ * Events: `'message'` (data) for every comm_msg the kernel sends over it and
+ * `'close'` (data) once it is closed by either side -- or because the kernel
+ * restarted or the session ended, in which case `data.reason` says so.
+ */
+export declare class Comm extends EventEmitter {
+    readonly id: string;
+    readonly targetName: string;
+    private readonly transport;
+    private isClosed;
+    constructor(id: string, targetName: string, transport: CommTransport);
+    get closed(): boolean;
+    /** Sends `data` to the kernel-side handler. Rejects if the comm is closed. */
+    send(data?: Record<string, unknown>): Promise<string>;
+    /** Closes the comm (the kernel is told; no-op if it is already closed). */
+    close(data?: Record<string, unknown>): Promise<void>;
+    /** @internal Called by Session for the kernel's own comm_msg / comm_close. */
+    receiveMessage(data: Record<string, unknown>): void;
+    /** @internal */
+    receiveClose(data: Record<string, unknown>): void;
+}
+//# sourceMappingURL=comm.d.ts.map

package/lib/session/comm.js

@@ -0,0 +1,58 @@
+import { EventEmitter } from 'events';
+/**
+ * One open comm: a named, bidirectional message channel between this client
+ * and a target registered inside the kernel (in R, `hera::CommManager$
+ * register_comm_target()`).
+ *
+ * Get one either from `session.openComm(target)` (client-initiated) or from
+ * the session's `'comm'` event (kernel-initiated, e.g. R calling
+ * `CommManager$new_comm()` then `$open()`).
+ *
+ * Events: `'message'` (data) for every comm_msg the kernel sends over it and
+ * `'close'` (data) once it is closed by either side -- or because the kernel
+ * restarted or the session ended, in which case `data.reason` says so.
+ */
+export class Comm extends EventEmitter {
+    id;
+    targetName;
+    transport;
+    isClosed = false;
+    constructor(id, targetName, transport) {
+        super();
+        this.id = id;
+        this.targetName = targetName;
+        this.transport = transport;
+    }
+    get closed() {
+        return this.isClosed;
+    }
+    /** Sends `data` to the kernel-side handler. Rejects if the comm is closed. */
+    send(data = {}) {
+        if (this.isClosed) {
+            return Promise.reject(new Error(`Comm ${this.id} (${this.targetName}) is closed`));
+        }
+        return this.transport.commMsg(this.id, data);
+    }
+    /** Closes the comm (the kernel is told; no-op if it is already closed). */
+    async close(data = {}) {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        await this.transport.commClose(this.id, data);
+        this.emit('close', data);
+    }
+    /** @internal Called by Session for the kernel's own comm_msg / comm_close. */
+    receiveMessage(data) {
+        this.emit('message', data);
+    }
+    /** @internal */
+    receiveClose(data) {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        this.emit('close', data);
+    }
+}
+//# sourceMappingURL=comm.js.map

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

@@ -0,0 +1,48 @@
+/** The npm scope the packages are published under (also set in scripts/release.mjs; a test keeps them in step). */
+export declare const PACKAGE_SCOPE = "@damurka";
+export declare const PACKAGE_NAME = "@damurka/jovian";
+/**
+ * The prebuilt kernels (themisto, elara, carpo) ship in one small package per
+ * platform -- `@scope/jovian-<os>-<cpu>` -- that npm installs alongside
+ * 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 function platformPackageName(platform?: string, arch?: string): string | undefined;
+export interface NativeLocation {
+    /** Directory holding themisto, elara and carpo. */
+    dir: string;
+    source: 'JOVIAN_NATIVE_DIR' | 'platform package' | 'source build';
+}
+export interface NativeLookup {
+    env: Record<string, string | undefined>;
+    platform: string;
+    arch: string;
+    exists: (path: string) => boolean;
+    /** Absolute path of a package's package.json, or undefined if it is not installed. */
+    resolvePackageJson: (packageName: string) => string | undefined;
+    /** dist/native/Release of a source checkout. */
+    sourceBuildDir: string;
+}
+/**
+ * Where the kernels are, in order of precedence:
+ *   1. JOVIAN_NATIVE_DIR -- an explicit directory (a copy of the binaries, an
+ *      app that bundles them elsewhere);
+ *   2. the installed `@scope/jovian-<os>-<cpu>` package for this machine;
+ *   3. a source checkout's dist/native/Release (development).
+ */
+export declare function locateNativeDirectory(lookup?: NativeLookup): NativeLocation;
+/**
+ * npm does not reliably keep the executable bit on files in a tarball, so make
+ * sure the kernels can be run (POSIX only; a no-op on Windows).
+ */
+export declare function ensureExecutable(dir: string, platform?: string): void;
+/**
+ * The copy of the 'hera' R package that ships inside the npm package, used to
+ * install/refresh it in R on a session's first start when the caller gave no
+ * heraSrcPath. Only when running from an installed package (under
+ * node_modules): a source checkout leaves hera alone so development and CI
+ * control which one is loaded.
+ */
+export declare function bundledHeraSource(baseDir?: string, exists?: (path: string) => boolean): string | undefined;
+//# sourceMappingURL=native-paths.d.ts.map

package/lib/session/native-paths.js

@@ -0,0 +1,108 @@
+import { chmodSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The npm scope the packages are published under (also set in scripts/release.mjs; a test keeps them in step). */
+export const PACKAGE_SCOPE = '@damurka';
+export const PACKAGE_NAME = `${PACKAGE_SCOPE}/jovian`;
+/**
+ * The prebuilt kernels (themisto, elara, carpo) ship in one small package per
+ * platform -- `@scope/jovian-<os>-<cpu>` -- that npm installs alongside
+ * 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 function platformPackageName(platform = process.platform, arch = process.arch) {
+    const key = `${platform}-${arch}`;
+    return SUPPORTED_PLATFORMS.includes(key) ? `${PACKAGE_NAME}-${key}` : undefined;
+}
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+function defaultLookup() {
+    const require = createRequire(import.meta.url);
+    return {
+        env: process.env,
+        platform: process.platform,
+        arch: process.arch,
+        exists: existsSync,
+        resolvePackageJson: (name) => {
+            try {
+                return require.resolve(`${name}/package.json`);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        // dist/lib/session -> dist/native/Release
+        sourceBuildDir: join(moduleDir, '../../native/Release')
+    };
+}
+/**
+ * Where the kernels are, in order of precedence:
+ *   1. JOVIAN_NATIVE_DIR -- an explicit directory (a copy of the binaries, an
+ *      app that bundles them elsewhere);
+ *   2. the installed `@scope/jovian-<os>-<cpu>` package for this machine;
+ *   3. a source checkout's dist/native/Release (development).
+ */
+export function locateNativeDirectory(lookup = defaultLookup()) {
+    const exe = lookup.platform === 'win32' ? 'themisto.exe' : 'themisto';
+    const has = (dir) => lookup.exists(join(dir, exe));
+    const override = lookup.env.JOVIAN_NATIVE_DIR;
+    if (override) {
+        if (!has(override)) {
+            throw new Error(`jovian: JOVIAN_NATIVE_DIR is set to '${override}' but there is no ${exe} in it.`);
+        }
+        return { dir: override, source: 'JOVIAN_NATIVE_DIR' };
+    }
+    const packageName = platformPackageName(lookup.platform, lookup.arch);
+    if (packageName) {
+        const packageJson = lookup.resolvePackageJson(packageName);
+        if (packageJson) {
+            const dir = join(dirname(packageJson), 'bin');
+            if (has(dir)) {
+                return { dir, source: 'platform package' };
+            }
+        }
+    }
+    if (has(lookup.sourceBuildDir)) {
+        return { dir: lookup.sourceBuildDir, source: 'source build' };
+    }
+    if (!packageName) {
+        throw new Error(`jovian: there are no prebuilt kernels for ${lookup.platform}-${lookup.arch} ` +
+            `(supported: ${SUPPORTED_PLATFORMS.join(', ')}). Build them from source and point ` +
+            `JOVIAN_NATIVE_DIR at the output directory.`);
+    }
+    throw new Error(`jovian: the kernel binaries were not found. Expected the '${packageName}' package ` +
+        `(installed automatically as an optional dependency -- reinstall without --omit=optional / ` +
+        `--no-optional), or a source build at ${lookup.sourceBuildDir}, or JOVIAN_NATIVE_DIR.`);
+}
+/**
+ * npm does not reliably keep the executable bit on files in a tarball, so make
+ * sure the kernels can be run (POSIX only; a no-op on Windows).
+ */
+export function ensureExecutable(dir, platform = process.platform) {
+    if (platform === 'win32')
+        return;
+    for (const name of ['themisto', 'elara', 'carpo']) {
+        try {
+            chmodSync(join(dir, name), 0o755);
+        }
+        catch {
+            // Absent (carpo is optional) or not ours to change: running it will say so.
+        }
+    }
+}
+/**
+ * The copy of the 'hera' R package that ships inside the npm package, used to
+ * install/refresh it in R on a session's first start when the caller gave no
+ * heraSrcPath. Only when running from an installed package (under
+ * node_modules): a source checkout leaves hera alone so development and CI
+ * control which one is loaded.
+ */
+export function bundledHeraSource(baseDir = moduleDir, exists = existsSync) {
+    if (!baseDir.split(sep).includes('node_modules'))
+        return undefined;
+    // <package>/lib/session -> <package>/packages/hera (the published layout)
+    const candidate = join(baseDir, '../../packages/hera');
+    return exists(join(candidate, 'DESCRIPTION')) ? candidate : undefined;
+}
+//# sourceMappingURL=native-paths.js.map

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

@@ -0,0 +1,229 @@
+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 { ExecutionState } from '../types/messages.js';
+import { SupervisorClient, type SessionConnectionInfo } from './supervisor-client.js';
+import { Comm } from './comm.js';
+export type { ShinyAppHandle };
+export declare class Session extends EventEmitter {
+    private ws;
+    readonly info: SessionConnectionInfo;
+    private currentOptions;
+    private readonly supervisor;
+    private readonly logger;
+    private readonly router;
+    private readonly middleware;
+    private readonly queue;
+    /**
+     * The options this session is currently running with: what it was
+     * created with, updated by any `restart(options)` that changed them.
+     */
+    get options(): EngineOptions;
+    private readyPromise;
+    private stopped;
+    private readonly comms;
+    private readonly busyRequests;
+    private readonly pendingRequests;
+    private kernelExecutionState;
+    private readonly executionHistory;
+    private readonly executionHistoryByMsgId;
+    private readonly historyStreamChars;
+    constructor(info: SessionConnectionInfo, options: EngineOptions, supervisor: SupervisorClient);
+    /**
+     * (Re)establishes the WebSocket to this.info's session and resolves
+     * once it's ready. Used both by the constructor and by restart() --
+     * info.sessionId/httpBase/wsBase don't change across a restart
+     * (SessionRegistry::restartSession() replaces the kernel in place under
+     * the same id), so reconnecting to the exact same URL is enough to pick
+     * back up a session the supervisor just gave a fresh kernel.
+     */
+    private connect;
+    /**
+     * Replaces this session's kernel process in place, keeping the same
+     * session id -- recovers a crashed session (kernelExit/unexpected close
+     * leaves the Session object itself alive but every execute() rejecting
+     * forever otherwise), and doubles as Jupyter's "Restart Kernel" for a
+     * still-healthy one. Not available after an explicit stop()/kill(): at
+     * that point the caller's intent was to end the session, not reset it
+     * -- create a new one instead via SessionManager.createSession().
+     *
+     * `options`, if given, switches this session's R installation on the
+     * restart (rHome/rPath/etc) instead of reusing whatever it was created
+     * with -- e.g. flip from R 4.4 to R 4.6 on the fly, without closing
+     * this session and opening a new one (a different session id/WS URL)
+     * just to pick a different R.
+     */
+    restart(options?: Partial<EngineOptions>): Promise<void>;
+    private send;
+    private recordExecutionHistory;
+    private boundStreamHistory;
+    private handleFrame;
+    /** Resolves once this session's R interpreter has started. */
+    ready(): Promise<void>;
+    execute(code: string, options?: ExecutionOptions): Promise<ExecutionResult>;
+    /**
+     * Answers a pending input_request -- this session emits one (see the
+     * 'input_request' event, content: {prompt, password}) whenever the
+     * kernel calls input()/readline()/scan() during an execute() that was
+     * given { allowStdin: true }, and genuinely blocks its single execution
+     * thread until this arrives (ServerZmqImpl::sendStdin() in
+     * native/src/adrastea/transport/server/server_zmq_impl.cpp does a real,
+     * untimed ZMQ recv underneath). Fire-and-forget like interrupt(): the
+     * reply that eventually unblocks the kernel surfaces through the
+     * *execute_request's own* execute_reply/stream messages, not through a
+     * reply to this call.
+     */
+    sendInputReply(value: string): void;
+    /**
+     * This session's own local record of every execute() call it has made
+     * and what each one produced (code + every iopub message), for as long
+     * as this Session object has been alive. Purely in-memory and
+     * process-local -- gone if the process holding this Session restarts,
+     * same as the Session object itself. Useful for e.g. rebuilding a UI's
+     * transcript after some *other* thing (not this process) reconnects to
+     * it, or for inspecting what actually ran without threading your own
+     * bookkeeping through every execute() call site.
+     *
+     * Not the same thing as queryKernelHistory(): this is this session's
+     * own bookkeeping (full fidelity -- includes actual output, which the
+     * kernel's own history manager doesn't track), while that one asks the
+     * *kernel itself* what it remembers running (input code only,
+     * authoritative even if some other client executed it, but capped by
+     * this process's own historical view of it, and lost across a kernel
+     * restart the same as the kernel's own memory of it is).
+     */
+    getHistory(): ExecutionHistoryEntry[];
+    /**
+     * Sends a real Jupyter history_request and resolves with the kernel's
+     * own history_reply (KernelCore::historyRequest() ->
+     * HistoryManager::processRequest(), native/src/adrastea/core/history/)
+     * -- the kernel's own authoritative record of what it has executed,
+     * independent of which client (or how many, over how many reconnects)
+     * actually ran it. Defaults to the 100 most recent executions ('tail').
+     * See KernelHistoryOptions' own doc comment for the other access modes,
+     * and getHistory()'s doc comment for how this differs from that.
+     */
+    queryKernelHistory(options?: KernelHistoryOptions): Promise<KernelHistoryEntry[]>;
+    /**
+     * Sends interrupt_request over the control channel and resolves true if
+     * the kernel acknowledged it (interrupt_reply, status ok), false if it
+     * didn't within `options.timeout` (default 5s) or the session is gone --
+     * never rejects, since a caller typically fires this from a "stop"
+     * button and has nothing useful to do with an error.
+     *
+     * A real interrupt: the kernel services its control channel on a
+     * separate thread while code runs, so this is answered immediately even
+     * mid-execution, and the running code is broken out of exactly as Ctrl-C
+     * would (R: an interrupt condition; Python: KeyboardInterrupt). The
+     * interrupted execute() resolves with success: false. Interrupting an
+     * idle kernel does nothing. Limits: code blocked inside a native call
+     * that never returns to the interpreter (a long C extension call, a
+     * blocking socket read) is only interrupted once it does, and a kernel
+     * waiting on an input() / readline() reply must be answered (or its
+     * execute() timed out) first.
+     */
+    interrupt(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * The latest iopub `status` the kernel reported ('busy' while it is
+     * handling a request, 'idle' between them) -- undefined until the first
+     * one arrives. Also available as the 'status' event.
+     */
+    get executionState(): ExecutionState | undefined;
+    /**
+     * Sends any of the Jupyter requests that have a plain request/reply
+     * shape and resolves with the kernel's reply content: complete_request,
+     * inspect_request, is_complete_request, kernel_info_request,
+     * history_request, comm_info_request (shell) and interrupt_request
+     * (control) -- the typed methods below (complete(), inspect(), ...) are
+     * this with the right message type and content filled in. Rejects on a
+     * reply whose status is 'error'/'aborted', when the supervisor refuses
+     * the request, on timeout, or if the session goes away first.
+     *
+     * Deliberately not for execute_request (use execute(): it owns the
+     * queue/timeout/stdin semantics), input_reply (sendInputReply()) or
+     * shutdown_request (stop()/restart()) -- the supervisor rejects those.
+     */
+    request<T = any>(msgType: string, content?: Record<string, unknown>, options?: {
+        timeout?: number;
+    }): Promise<T>;
+    private trackExecutionState;
+    private routeComm;
+    private closeAllComms;
+    private settleRequest;
+    private rejectPendingRequests;
+    private watchFor;
+    /**
+     * What the supervisor knows about this session's kernel process right
+     * now: lifecycle status, pid, memory, working directory and the
+     * heartbeat (round-trip time of the last ping, missed pings). The
+     * heartbeat is answered by a kernel thread separate from the one that
+     * runs code, so it stays live while the kernel is busy -- unlike
+     * kernelInfo(), which would wait for the running code to finish.
+     */
+    status(): Promise<SessionStatusInfo>;
+    /** complete_request: completions for the code at `cursorPos` (default: the end of `code`). */
+    complete(code: string, cursorPos?: number): Promise<CompleteReplyContent>;
+    /** inspect_request: documentation/details for the symbol at `cursorPos` (default: the end of `code`). */
+    inspect(code: string, cursorPos?: number, detailLevel?: 0 | 1): Promise<InspectReplyContent>;
+    /**
+     * is_complete_request: whether `code` is a complete statement, needs more
+     * lines ('incomplete', with an `indent` hint when the kernel has one),
+     * or can never parse ('invalid') -- what a console needs to decide
+     * between "run it" and "keep prompting".
+     */
+    isComplete(code: string): Promise<IsCompleteReplyContent>;
+    /** kernel_info_request: what the kernel is -- implementation, language and its version, protocol version, banner. */
+    kernelInfo(): Promise<KernelInfoReplyContent>;
+    /** comm_info_request: the comms currently open in the kernel, optionally only those for one target. */
+    commInfo(targetName?: string): Promise<CommInfoReplyContent>;
+    private sendComm;
+    /** Opens a comm to a kernel-side `targetName`; resolves with its comm id and the msg id it was sent under. */
+    commOpen(targetName: string, data?: Record<string, unknown>, commId?: string): Promise<{
+        commId: string;
+        msgId: string;
+    }>;
+    /**
+     * Opens a comm to a kernel-side `targetName` and returns it as a Comm
+     * object (send()/close(), 'message'/'close' events). If the kernel has
+     * no such target it answers with a comm_close, so the returned comm
+     * emits 'close' shortly after. Kernel-initiated comms arrive as this
+     * session's 'comm' event instead: `session.on('comm', (comm, data) => ...)`.
+     */
+    openComm(targetName: string, data?: Record<string, unknown>): Promise<Comm>;
+    /** Sends `data` over an open comm. */
+    commMsg(commId: string, data?: Record<string, unknown>): Promise<string>;
+    /** Closes a comm. */
+    commClose(commId: string, data?: Record<string, unknown>): Promise<string>;
+    /**
+     * Launches a Shiny app in this session's R process and resolves once
+     * it's actually accepting connections. shiny::runApp() blocks the R
+     * session for as long as the app runs, so -- unlike execute() --
+     * resolving here does not mean the app is done; that's what the
+     * returned `done` promise is for.
+     */
+    createShiny(options: ShinyAppOptions): Promise<ShinyAppHandle>;
+    /** Stops the R session and waits for its process to exit. */
+    stop(): Promise<void>;
+    /** Skips the graceful shutdown protocol -- only for cleanup on the way out. */
+    kill(): void;
+}
+export declare class SessionManager {
+    private readonly supervisor;
+    private readonly sessions;
+    private exitHandlerRegistered;
+    /** Creates a new R session in its own OS process and waits for it to be ready. */
+    createSession(options?: EngineOptions): Promise<Session>;
+    /** Gracefully stops every session managed by this instance. */
+    stopAll(): Promise<void>;
+    /**
+     * Forcibly terminates every session. Prefer stopAll(), but a session
+     * whose R interpreter is blocked in a long-running call (e.g.
+     * shiny::runApp()) can't process a graceful shutdown until that call
+     * returns -- callers wanting a bounded-time exit (e.g. a Ctrl+C
+     * handler) should race stopAll() against a timeout and fall back to this.
+     */
+    killAll(): void;
+    private registerExitHandler;
+}
+//# sourceMappingURL=session-manager.d.ts.map