nebula-notebook 0.1.1 → 0.2.1

package/node-server/dist/kernel/kernel-service.d.ts

@@ -7,6 +7,36 @@
 import { KernelOutput, ExecutionResult, ExecutionQueueInfo, StartKernelOptions, SessionInfo, KernelServiceConfig } from './types';
 import { SessionStore } from './session-store';
 import { KernelSpec } from './kernelspec';
+/** Kernel-originated comm event surfaced to onComm listeners. */
+export interface CommEvent {
+    msgType: 'comm_open' | 'comm_msg' | 'comm_close';
+    commId: string;
+    targetName?: string;
+    data: Record<string, unknown>;
+    /** Binary buffer frames, base64-encoded. Present only when non-empty. */
+    buffers?: string[];
+}
+/** Resolved by BoundedAsyncQueue.next() when the queue has been closed. */
+export declare const IOPUB_QUEUE_CLOSED: unique symbol;
+/** Resolved by BoundedAsyncQueue.next(timeoutMs) when the wait timed out. */
+export declare const IOPUB_QUEUE_TIMEOUT: unique symbol;
+/**
+ * Polyfill IPython-style `!command` lines for kernels whose language lacks
+ * them, by rewriting each such line into the language's own shell-call idiom
+ * before the code reaches the kernel. Because the rewritten code still runs
+ * in the kernel process, cwd, environment (conda env, loaded modules), and
+ * machine (allocation node) are all the kernel's — the same guarantees
+ * IPython's native `!` gives Python users.
+ *
+ * Python kernels are deliberately untouched: IPython's `!` is richer than a
+ * plain shell call (output capture `x = !ls`, `{var}` interpolation,
+ * streaming output) and a rewrite would break it.
+ *
+ * Only whole lines that start with `!` are rewritten. Known limits (v1):
+ * a line inside a multi-line string that happens to start with `!` would be
+ * rewritten too, and R's intern=TRUE buffers output until the command exits.
+ */
+export declare function rewriteShellLines(code: string, language: string | undefined): string;
 export declare class KernelService {
     private sessions;
     private fileToSession;
@@ -28,7 +58,23 @@ export declare class KernelService {
     private cellOutputBuffers;
     private cellOutputTracking;
     private executingCellIds;
+    private iopubReaders;
+    private iopubParentSubscribers;
+    private iopubCatchAllSubscribers;
+    private commStates;
+    private shellReaders;
+    private shellReplyWaiters;
     constructor(config?: KernelServiceConfig, sessionStore?: SessionStore);
+    private deadListeners;
+    onSessionDead(cb: (sessionId: string) => void): void;
+    private notifySessionDead;
+    private commListeners;
+    onComm(cb: (sessionId: string, comm: CommEvent) => void): void;
+    private notifyComm;
+    private livenessTimer;
+    private startLivenessSweep;
+    /** One liveness pass (exposed for tests; normally driven by the timer). */
+    sweepLiveness(): void;
     setServerIdentity(serverId: string, serverInstanceId?: string): void;
     /**
      * Check if a PID is still alive.
@@ -109,6 +155,57 @@ export declare class KernelService {
      * @param pid Optional kernel PID — used to distinguish "busy" from "dead" on timeout
      */
     private waitForReady;
+    private startIopubReader;
+    private stopIopubReader;
+    private closeIopubSubscribers;
+    private dispatchIopubMessage;
+    /**
+     * Subscribe to iopub messages parented by a specific msg_id. Must be called
+     * BEFORE sending the request so no reply can slip past the demux. Callers
+     * must unsubscribe in a finally block.
+     */
+    private subscribeIopubParent;
+    private unsubscribeIopubParent;
+    /** Subscribe to ALL iopub messages for a session (any parent). */
+    private subscribeIopubCatchAll;
+    private unsubscribeIopubCatchAll;
+    private startShellReader;
+    private stopShellReader;
+    private closeShellReplyWaiters;
+    /**
+     * Register a one-shot waiter for the shell reply parented by msgId. Must be
+     * called BEFORE sending the request so the reply cannot slip past the
+     * dispatch. Resolves 'closed' immediately if no reader loop is alive, or
+     * later when the reader stops (kernel stop/restart/cleanup).
+     */
+    private registerShellReplyWaiter;
+    private removeShellReplyWaiter;
+    /**
+     * Await a previously registered shell reply with a timeout. The waiter is
+     * always deregistered on the way out (timeout, reply, or error), so a late
+     * reply is dropped by the reader instead of leaking a waiter.
+     */
+    private waitForShellReply;
+    private handleKernelCommMessage;
+    private rememberOpenComm;
+    /**
+     * Open comms known for a session (for late-joining clients).
+     * Returns comm_id -> { targetName, openData } where openData is the last
+     * state-carrying comm_open payload observed for that comm.
+     */
+    getOpenComms(sessionId: string): Record<string, {
+        targetName: string;
+        openData: Record<string, unknown>;
+    }>;
+    /**
+     * Send a comm message (comm_open / comm_msg / comm_close) to the kernel on
+     * the shell channel. Comm messages produce NO shell reply, so the queued
+     * slot releases as soon as the send completes — we never block waiting for
+     * a reply that will not come.
+     *
+     * @param buffers Optional binary buffer frames, base64-encoded.
+     */
+    sendCommMessage(sessionId: string, msgType: 'comm_open' | 'comm_msg' | 'comm_close', content: Record<string, unknown>, buffers?: string[]): Promise<void>;
     /**
      * Monitor a busy reattached kernel on iopub. When its current execution
      * finishes (status: idle on iopub), verify shell connectivity and update
@@ -128,10 +225,16 @@ export declare class KernelService {
      * Get or create kernel for a file (one notebook = one kernel).
      * Returns whether a new session was created.
      */
+    /** In-flight create/attach per normalized file path (single-flight).
+     *  Without this, two near-simultaneous requests (UI re-render + agent op,
+     *  double-click) both miss the fileToSession check and spawn TWO kernel
+     *  processes — the second overwrites the mapping and the first leaks. */
+    private inflightKernelCreates;
     getOrCreateKernel(filePath: string, kernelName?: string): Promise<{
         sessionId: string;
         created: boolean;
     }>;
+    private getOrCreateKernelInternal;
     /**
      * Get existing kernel session ID for a notebook file (if any).
      * Returns null if no live session is associated with the file.
@@ -156,7 +259,11 @@ export declare class KernelService {
     executeCode(sessionId: string, code: string, onOutput: (output: KernelOutput, cellId?: string | null) => Promise<void>, onQueueInfo?: (info: ExecutionQueueInfo) => void, cellId?: string | null): Promise<ExecutionResult>;
     private enqueueExecution;
     /**
-     * Queue shell socket requests to prevent concurrent receive operations
+     * Serialize shell socket SENDS. Receives are owned by the unified shell
+     * reader, so tasks queued here must be send-only and release the slot as
+     * soon as the send completes (register any reply waiter BEFORE enqueueing,
+     * await the reply AFTER the slot is released). Holding the slot across a
+     * reply wait would let one slow request delay every later send.
      */
     private enqueueShellRequest;
     private reserveExecutionSlot;
@@ -174,7 +281,10 @@ export declare class KernelService {
         cursor_end: number;
     }>;
     /**
-     * Internal completion implementation (runs within shell queue)
+     * Internal completion implementation. The send is serialized through the
+     * shell queue; the reply is awaited via the unified shell reader, so a
+     * timeout here simply drops the waiter and can never block or swallow a
+     * later request's reply.
      */
     private completeInternal;
     /**
@@ -247,6 +357,15 @@ export declare class KernelService {
      */
     getSessionStatusFast(sessionId: string): SessionInfo | null;
     getSessionStatus(sessionId: string): Promise<SessionInfo | null>;
+    /**
+     * Activity snapshot for the idle auto-release monitor (client mode):
+     * whether any kernel is busy/starting, and the most recent kernel activity
+     * across sessions in ms since epoch (sessions track it in seconds).
+     */
+    getIdleSnapshot(): {
+        anyBusy: boolean;
+        lastActivityMs: number | null;
+    };
     /**
      * Get all sessions
      */
@@ -261,6 +380,15 @@ export declare class KernelService {
         status: string;
         lastHeartbeat: number;
     }[];
+    /**
+     * Auto-delete dead session rows whose kernel process is CONFIRMED gone
+     * (no PID, PID not running, or PID reused by another process). These are
+     * pure bookkeeping — nothing to kill, nothing to lose — so they need no
+     * user confirmation. Rows whose PID is still alive are kept for the
+     * explicit "Clean Up" flow (killing a process should stay a user action,
+     * and legacy rows without a start-time fingerprint can't be verified).
+     */
+    autoCleanupDeadSessions(): Promise<number>;
     /**
      * Cleanup dead sessions by deleting them from the database
      */