nebula-notebook 0.1.0 → 0.2.0

package/node-server/dist/notebook/undoRedoManager.d.ts

@@ -182,7 +182,10 @@ export declare class HeadlessUndoRedoManager {
     /**
      * Clear state for a notebook (e.g., when closing).
      */
-    clearState(notebookPath: string): void;
+    /** Drop in-memory state so the next access rebuilds from the persisted
+     *  history file (the file/history may have changed underneath us: UI save,
+     *  external-edit reconciliation). Omit the path to clear all. */
+    clearState(notebookPath?: string): void;
     /**
      * Get updates since a timestamp (for agent awareness).
      * Returns human-readable summaries of operations made between agent sessions.

package/node-server/dist/notebook/undoRedoManager.js

@@ -142,7 +142,7 @@ class HeadlessUndoRedoManager {
             // Try to load existing history
             let loadedHistory = [];
             try {
-                loadedHistory = this.fsService.loadHistory(notebookPath);
+                loadedHistory = this.fsService.loadHistorySync(notebookPath);
             }
             catch (err) {
                 console.warn(`[UndoRedoManager] Failed to load history for ${notebookPath}:`, err);
@@ -357,8 +357,16 @@ class HeadlessUndoRedoManager {
     /**
      * Clear state for a notebook (e.g., when closing).
      */
+    /** Drop in-memory state so the next access rebuilds from the persisted
+     *  history file (the file/history may have changed underneath us: UI save,
+     *  external-edit reconciliation). Omit the path to clear all. */
     clearState(notebookPath) {
-        this.states.delete(notebookPath);
+        if (notebookPath) {
+            this.states.delete(notebookPath);
+        }
+        else {
+            this.states.clear();
+        }
     }
     /**
      * Get updates since a timestamp (for agent awareness).

package/node-server/dist/output/display-data.js

@@ -8,6 +8,8 @@ exports.buildDisplayOutput = buildDisplayOutput;
 exports.convertMimeBundleToJupyter = convertMimeBundleToJupyter;
 const PREFERRED_MIME_TYPES = [
     'application/vnd.nebula.web+json',
+    // Widget views must win over plotly/html when both are present
+    'application/vnd.jupyter.widget-view+json',
     'application/vnd.plotly.v1+json',
     'text/html',
     'image/png',

package/node-server/dist/routes/cluster.js

@@ -27,11 +27,11 @@ async function clusterRoutes(fastify) {
      * Body can include { resources } for initial resource info
      */
     fastify.post('/servers/register', async (request, reply) => {
-        const { host, port, name, secret, resources } = request.body;
+        const { host, port, name, secret, resources, allocationToken } = request.body;
         if (!host || !port) {
             return reply.code(400).send({ error: 'host and port are required' });
         }
-        const result = server_registry_1.serverRegistry.register({ host, port, name, secret, resources });
+        const result = server_registry_1.serverRegistry.register({ host, port, name, secret, resources, allocationToken });
         if (!result.success) {
             return reply.code(403).send({ error: result.error });
         }

package/node-server/dist/routes/compute.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compute allocation API — submit and manage scheduler-backed compute.
+ *
+ * All routes live under /api/compute and are auth-protected like the rest of the
+ * API. They are no-ops (return `enabled: false`) when no scheduler is detected.
+ */
+import { FastifyInstance } from 'fastify';
+export default function computeRoutes(fastify: FastifyInstance): Promise<void>;

package/node-server/dist/routes/compute.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Compute allocation API — submit and manage scheduler-backed compute.
+ *
+ * All routes live under /api/compute and are auth-protected like the rest of the
+ * API. They are no-ops (return `enabled: false`) when no scheduler is detected.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = computeRoutes;
+const os = __importStar(require("os"));
+const allocation_service_1 = require("../scheduler/allocation-service");
+function currentUser() {
+    return process.env.USER || process.env.LOGNAME || os.userInfo().username;
+}
+/** Build a JobSpec from request input, applying MVP defaults. */
+function parseSpec(x) {
+    const partition = String(x?.partition || '').trim();
+    const qos = x?.qos ? String(x.qos).trim() : undefined;
+    const account = x?.account ? String(x.account).trim() : undefined;
+    const cpus = Math.max(1, Math.floor(Number(x?.cpus) || 1));
+    const memGb = Math.max(1, Math.floor(Number(x?.memGb) || 4));
+    const gpusRaw = Math.floor(Number(x?.gpus) || 0);
+    const gpus = gpusRaw > 0 ? gpusRaw : undefined;
+    const gpuType = gpus && x?.gpuType ? String(x.gpuType).trim() || undefined : undefined;
+    const walltimeMinutes = Math.max(1, Math.floor(Number(x?.walltimeMinutes) || 120));
+    // Opt-in idle auto-release (minutes). Absent/invalid/<=0 = disabled.
+    const idleRaw = Math.floor(Number(x?.idleTimeoutMinutes) || 0);
+    const idleTimeoutMinutes = idleRaw > 0 ? idleRaw : undefined;
+    const jobName = (x?.jobName ? String(x.jobName) : `nebula-${partition || 'compute'}`)
+        .replace(/[^A-Za-z0-9._-]/g, '-')
+        .slice(0, 60) || 'nebula';
+    return { partition, qos, account, cpus, memGb, gpus, gpuType, walltimeMinutes, jobName, idleTimeoutMinutes };
+}
+async function computeRoutes(fastify) {
+    /** Whether scheduler-backed compute is available on this server. */
+    fastify.get('/compute/status', async (_req, reply) => {
+        return reply.send({
+            enabled: allocation_service_1.allocationService.isEnabled(),
+            scheduler: allocation_service_1.allocationService.getScheduler()?.name ?? null,
+        });
+    });
+    /** Allowed partitions/QoS for the current user + a live load snapshot. */
+    fastify.get('/compute/partitions', async (_req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        if (!sched)
+            return reply.send({ enabled: false, associations: null, load: null });
+        const [associations, load] = await Promise.all([
+            sched.associations(currentUser()).catch(() => null),
+            sched.load().catch(() => null),
+        ]);
+        return reply.send({ enabled: true, associations, load });
+    });
+    /** QoS names a partition will accept (null = any). Drives the modal's QoS filter. */
+    fastify.get('/compute/partition-qos', async (req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        if (!sched)
+            return reply.send({ allowed: null });
+        const partition = String(req.query?.partition || '').trim();
+        if (!partition)
+            return reply.send({ allowed: null });
+        const allowed = await sched.allowedQos(partition).catch(() => null);
+        return reply.send({ allowed });
+    });
+    /** Dry-run estimated start time for a prospective allocation. */
+    fastify.get('/compute/estimate', async (req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        if (!sched)
+            return reply.code(400).send({ error: 'scheduler not available' });
+        const spec = parseSpec(req.query);
+        if (!spec.partition)
+            return reply.code(400).send({ error: 'partition is required' });
+        const estimate = await sched.estimateStart(spec);
+        return reply.send(estimate);
+    });
+    /** List current allocations (pending / running / active / ended). */
+    fastify.get('/compute/allocations', async (_req, reply) => {
+        return reply.send({ allocations: allocation_service_1.allocationService.list() });
+    });
+    /** Submit a new compute allocation. */
+    fastify.post('/compute/allocations', async (req, reply) => {
+        if (!allocation_service_1.allocationService.isEnabled()) {
+            return reply.code(400).send({ error: 'scheduler not available' });
+        }
+        const spec = parseSpec(req.body);
+        if (!spec.partition)
+            return reply.code(400).send({ error: 'partition is required' });
+        try {
+            const alloc = await allocation_service_1.allocationService.create(spec);
+            return reply.send(alloc);
+        }
+        catch (e) {
+            return reply.code(500).send({ error: e?.message || 'submit failed' });
+        }
+    });
+    /** Cancel an allocation (scancel + evict its server). */
+    fastify.delete('/compute/allocations/:id', async (req, reply) => {
+        const { id } = req.params;
+        const ok = await allocation_service_1.allocationService.cancel(id);
+        if (!ok)
+            return reply.code(404).send({ error: 'allocation not found' });
+        return reply.send({ cancelled: true });
+    });
+}

package/node-server/dist/routes/fs.js

@@ -121,7 +121,7 @@ async function fsRoutes(fastify) {
             if (!filePath) {
                 return reply.code(400).send({ detail: 'path query parameter is required' });
             }
-            const result = fs_service_1.fsService.getFileMtime(filePath);
+            const result = await fs_service_1.fsService.getFileMtime(filePath);
             return reply.send(result);
         }
         catch (err) {
@@ -143,7 +143,7 @@ async function fsRoutes(fastify) {
             if (!filePath) {
                 return reply.code(400).send({ detail: 'path query parameter is required' });
             }
-            const result = fs_service_1.fsService.readFile(filePath);
+            const result = await fs_service_1.fsService.readFile(filePath);
             return reply.send(result);
         }
         catch (err) {

package/node-server/dist/routes/kernel.js

@@ -49,6 +49,7 @@ const fs_service_1 = require("../fs/fs-service");
 const operation_router_1 = require("../notebook/operation-router");
 const kernel_proxy_1 = require("../cluster/kernel-proxy");
 const server_registry_1 = require("../cluster/server-registry");
+const allocation_service_1 = require("../scheduler/allocation-service");
 // Track all WebSocket connections per kernel session for broadcasting
 const sessionWebSockets = new Map();
 // Only send streaming outputs to sockets after they've performed an initial output sync.
@@ -58,6 +59,51 @@ const outputSubscribedSockets = new WeakSet();
 // Shared kernel service instance - exported for use by headless handler
 const kernelService = new kernel_service_1.KernelService();
 exports.kernelService = kernelService;
+// When a kernel dies (crash, OOM, reattached PID gone), push the status to
+// every client immediately — otherwise the UI shows 'busy' until the next
+// poll or failed execute.
+kernelService.onSessionDead((sessionId) => {
+    const sockets = sessionWebSockets.get(sessionId);
+    if (!sockets || sockets.size === 0)
+        return;
+    const msg = JSON.stringify({ type: 'status', status: 'dead' });
+    for (const socket of sockets) {
+        try {
+            if (socket.readyState === ws_1.WebSocket.OPEN)
+                socket.send(msg);
+        }
+        catch {
+            // Socket already closing — the reconnect loop will handle it
+        }
+    }
+});
+// Broadcast kernel-originated comm messages (ipywidgets state sync, etc.) to
+// every client attached to the session. This includes idle-time traffic from
+// widget observers — comm messages are demuxed regardless of parent request.
+kernelService.onComm((sessionId, comm) => {
+    const sockets = sessionWebSockets.get(sessionId);
+    if (!sockets || sockets.size === 0)
+        return;
+    const msg = JSON.stringify({
+        type: 'comm',
+        comm: {
+            msg_type: comm.msgType,
+            comm_id: comm.commId,
+            ...(comm.targetName !== undefined && { target_name: comm.targetName }),
+            data: comm.data,
+            ...(comm.buffers && { buffers: comm.buffers }),
+        },
+    });
+    for (const socket of sockets) {
+        try {
+            if (socket.readyState === ws_1.WebSocket.OPEN)
+                socket.send(msg);
+        }
+        catch {
+            // Socket already closing — the reconnect loop will handle it
+        }
+    }
+});
 // Initialize kernel service on module load
 kernelService.initialize().catch(err => {
     console.error('Failed to initialize kernel service:', err);
@@ -190,6 +236,41 @@ function setupKernelWebSocket(wss) {
                     const result = await kernelService.complete(sessionId, code, cursorPos);
                     ws.send(JSON.stringify({ type: 'complete_reply', result }));
                 }
+                else if (message.type === 'comm') {
+                    // Client -> kernel comm message (ipywidgets interaction):
+                    // { type: 'comm', comm: { msg_type, comm_id, target_name?, data, buffers? } }
+                    const comm = (message.comm && typeof message.comm === 'object') ? message.comm : {};
+                    const msgType = comm.msg_type;
+                    if (msgType !== 'comm_open' && msgType !== 'comm_msg' && msgType !== 'comm_close') {
+                        ws.send(JSON.stringify({ type: 'error', error: `Invalid comm msg_type: ${String(msgType)}` }));
+                        return;
+                    }
+                    if (typeof comm.comm_id !== 'string' || comm.comm_id.length === 0) {
+                        ws.send(JSON.stringify({ type: 'error', error: 'comm.comm_id is required' }));
+                        return;
+                    }
+                    const content = {
+                        comm_id: comm.comm_id,
+                        data: (comm.data && typeof comm.data === 'object') ? comm.data : {},
+                    };
+                    if (msgType === 'comm_open') {
+                        content.target_name = typeof comm.target_name === 'string' ? comm.target_name : '';
+                    }
+                    const buffers = Array.isArray(comm.buffers)
+                        ? comm.buffers.filter((b) => typeof b === 'string')
+                        : undefined;
+                    await kernelService.sendCommMessage(sessionId, msgType, content, buffers);
+                }
+                else if (message.type === 'comm_info') {
+                    // Late-joiner support: list open comms known for this session.
+                    // Reply only to the requesting socket.
+                    const openComms = kernelService.getOpenComms(sessionId);
+                    const comms = {};
+                    for (const [commId, info] of Object.entries(openComms)) {
+                        comms[commId] = { target_name: info.targetName };
+                    }
+                    ws.send(JSON.stringify({ type: 'comm_info_reply', comms }));
+                }
             }
             catch (err) {
                 const errMessage = err instanceof Error ? err.message : 'Unknown error';
@@ -340,6 +421,10 @@ async function kernelRoutes(fastify) {
                 return reply.code(500).send({ detail: message });
             }
         }
+        // Confirmed-dead rows (process gone) are auto-removed without user
+        // confirmation — only ambiguous leftovers (PID still alive) are reported
+        // for the explicit Clean Up flow.
+        await kernelService.autoCleanupDeadSessions().catch(() => { });
         const deadSessions = kernelService.getDeadSessions();
         const sessions = deadSessions.map(s => ({
             session_id: s.sessionId,
@@ -390,7 +475,7 @@ async function kernelRoutes(fastify) {
                     const metadataResult = await persistNotebookKernelMetadata(file_path, kernel_name);
                     notebookMtime = metadataResult.mtime;
                     if (client_origin !== 'ui') {
-                        operation_router_1.operationRouter.notifyKernelChanged(file_path, { kernelName: kernel_name, serverId: server_id });
+                        operation_router_1.operationRouter.notifyKernelChanged(file_path, { kernelName: kernel_name, serverId: server_id, mtime: metadataResult.mtime });
                     }
                 }
                 return reply.send({ session_id: result.sessionId, kernel_name, server_id, mtime: notebookMtime });
@@ -407,7 +492,7 @@ async function kernelRoutes(fastify) {
                 const metadataResult = await persistNotebookKernelMetadata(file_path, kernel_name);
                 notebookMtime = metadataResult.mtime;
                 if (client_origin !== 'ui') {
-                    operation_router_1.operationRouter.notifyKernelChanged(file_path, { kernelName: kernel_name, serverId: localServerId });
+                    operation_router_1.operationRouter.notifyKernelChanged(file_path, { kernelName: kernel_name, serverId: localServerId, mtime: metadataResult.mtime });
                 }
             }
             return reply.send({ session_id: sessionId, kernel_name, server_id: localServerId, mtime: notebookMtime });
@@ -473,6 +558,7 @@ async function kernelRoutes(fastify) {
                     operation_router_1.operationRouter.notifyKernelChanged(normalizedFilePath, {
                         kernelName: effectiveKernelName,
                         serverId: effectiveServerId,
+                        mtime: metadataResult.mtime,
                     });
                 }
                 return reply.send({
@@ -494,6 +580,7 @@ async function kernelRoutes(fastify) {
                 operation_router_1.operationRouter.notifyKernelChanged(normalizedFilePath, {
                     kernelName: effectiveKernelName,
                     serverId: localServerId,
+                    mtime: metadataResult.mtime,
                 });
             }
             return reply.send({
@@ -610,10 +697,35 @@ async function kernelRoutes(fastify) {
         if ((0, kernel_proxy_1.isProxiedSession)(sessionId)) {
             try {
                 const remoteStatus = await (0, kernel_proxy_1.getRemoteKernelStatus)(sessionId);
-                return reply.send(remoteStatus);
+                // Return the COMPOSITE session id (serverId::remoteId) — the remote
+                // server reports its own local id, and leaking that to clients makes
+                // them reference a session the main server doesn't recognize.
+                return reply.send({ ...remoteStatus, id: sessionId });
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : 'Unknown error';
+                // "Server is offline / not found" from the registry is a HEARTBEAT
+                // signal, not ground truth: a compute node saturated by a heavy
+                // execution can miss heartbeats for minutes while its SLURM job (and
+                // kernel) are perfectly alive — then recover. Treating that as
+                // terminal permanently killed live kernels (red kernel, reconnect
+                // loop stopped, only a page refresh recovered).
+                //
+                // The scheduler is the authority: return 410 Gone (terminal) only
+                // when the session's allocation is confirmed ended/failed/cancelled
+                // by squeue polling. Everything else is 503 (transient) so the
+                // client's reconnect loop keeps trying and revives the kernel when
+                // the node recovers.
+                if (/server (is offline|not found)/i.test(message)) {
+                    const { serverId } = (0, kernel_proxy_1.parseSessionId)(sessionId);
+                    const allocation = serverId
+                        ? allocation_service_1.allocationService.list().find(a => a.serverId === serverId)
+                        : undefined;
+                    if (allocation && ['ended', 'failed', 'cancelled'].includes(allocation.state)) {
+                        return reply.code(410).send({ detail: `Allocation ${allocation.state} — kernel stopped`, reason: 'server_gone' });
+                    }
+                    return reply.code(503).send({ detail: `${message} (may be transient — compute node busy or re-registering)`, reason: 'server_unreachable' });
+                }
                 return reply.code(500).send({ detail: message });
             }
         }

package/node-server/dist/routes/notebook.js

@@ -87,6 +87,12 @@ async function notebookRoutes(fastify) {
                 return reply.code(400).send({ detail: 'cells is required' });
             }
             const result = await fs_service_1.fsService.saveNotebookBundle(filePath, cells, kernel_name, history);
+            // The UI just wrote newer content than whatever the headless handler may
+            // have cached. Drop the cache so headless ops (an agent working after the
+            // user closes the tab) reload from disk instead of serving — or worse,
+            // OCC-validating against — stale cells.
+            headlessHandler.invalidate(filePath);
+            headlessHandler.invalidate(fs_service_1.fsService.normalizePath(filePath));
             return reply.send({ status: 'ok', path: filePath, mtime: result.mtime });
         }
         catch (err) {
@@ -103,7 +109,7 @@ async function notebookRoutes(fastify) {
             if (!notebookPath) {
                 return reply.code(400).send({ detail: 'notebook_path query parameter is required' });
             }
-            const history = fs_service_1.fsService.loadHistory(notebookPath);
+            const history = await fs_service_1.fsService.loadHistory(notebookPath);
             return reply.send({ notebook_path: notebookPath, history });
         }
         catch (err) {
@@ -178,6 +184,7 @@ async function notebookRoutes(fastify) {
             return reply.send({
                 status: 'ok',
                 notebook_path,
+                mtime: result.mtime,
                 ...(result.status || fs_service_1.fsService.getAgentPermissionStatus(notebook_path)),
             });
         }
@@ -332,4 +339,31 @@ async function notebookRoutes(fastify) {
             return reply.code(500).send({ detail: message });
         }
     });
+    /**
+     * Persist live ipywidgets state into notebook metadata.widgets
+     * (application/vnd.jupyter.widget-state+json), making saved notebooks
+     * render static widgets in Jupyter/nbviewer.
+     */
+    fastify.post('/notebook/widget-state', async (request, reply) => {
+        try {
+            const { path: filePath, widget_state } = request.body;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path is required' });
+            }
+            if (!widget_state || typeof widget_state !== 'object') {
+                return reply.code(400).send({ detail: 'widget_state must be an object' });
+            }
+            const updateResult = await fs_service_1.fsService.updateNotebookMetadata(filePath, {
+                widgets: { 'application/vnd.jupyter.widget-state+json': widget_state },
+            });
+            if (!updateResult.success) {
+                return reply.code(500).send({ detail: updateResult.error || 'Failed to update notebook metadata' });
+            }
+            return reply.send({ status: 'ok', notebook_path: filePath, mtime: updateResult.mtime });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
 }

package/node-server/dist/scheduler/allocation-service.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Allocation service — owns the lifecycle a compute allocation has *before* and
+ * *around* the cluster registry: submit a job, follow it through the queue, and
+ * correlate the client-server's registration (by one-time token) back to the
+ * allocation. Once correlated, the allocation is a normal registered server and
+ * kernels run on it through the existing cluster path.
+ *
+ * Phase-1 MVP: in-memory allocations, direct transport (no SSH tunnel — not
+ * needed where compute↔login is directly reachable).
+ */
+import type { Scheduler, JobSpec } from './types';
+import { type LaunchContext } from './job-template';
+export type AllocationState = 'pending' | 'running' | 'active' | 'ended' | 'failed' | 'cancelled';
+export interface Allocation {
+    id: string;
+    jobId?: string;
+    token: string;
+    spec: JobSpec;
+    state: AllocationState;
+    serverId?: string;
+    nodes?: string[];
+    reason?: string;
+    createdAt: number;
+    walltimeEndsAt?: number;
+}
+declare class AllocationService {
+    private scheduler;
+    private ctx;
+    private allocations;
+    private pollTimer;
+    private enabled;
+    init(scheduler: Scheduler, ctx: LaunchContext): void;
+    isEnabled(): boolean;
+    getScheduler(): Scheduler | null;
+    list(): Allocation[];
+    get(id: string): Allocation | undefined;
+    create(spec: JobSpec): Promise<Allocation>;
+    cancel(id: string): Promise<boolean>;
+    private poll;
+    shutdown(): void;
+}
+export declare const allocationService: AllocationService;
+export {};