nebula-notebook 0.1.0

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

@@ -0,0 +1,12 @@
+/**
+ * Notebook Operations WebSocket
+ *
+ * Handles real-time communication between UI and backend for notebook operations.
+ * Path: /api/notebook/{notebook_path}/ws
+ */
+import { WebSocketServer } from 'ws';
+import { Server as HttpServer } from 'http';
+/**
+ * Setup notebook operations WebSocket handler
+ */
+export declare function setupNotebookWebSocket(server: HttpServer): WebSocketServer;

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

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Notebook Operations WebSocket
+ *
+ * Handles real-time communication between UI and backend for notebook operations.
+ * Path: /api/notebook/{notebook_path}/ws
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupNotebookWebSocket = setupNotebookWebSocket;
+const ws_1 = require("ws");
+const url_1 = require("url");
+const operation_router_1 = require("./operation-router");
+/**
+ * Setup notebook operations WebSocket handler
+ */
+function setupNotebookWebSocket(server) {
+    const wss = new ws_1.WebSocketServer({
+        noServer: true,
+        perMessageDeflate: false,
+    });
+    // Handle upgrade requests for /api/notebook/{path}/ws
+    server.on('upgrade', (request, socket, head) => {
+        const parsedUrl = (0, url_1.parse)(request.url || '', true);
+        const pathname = parsedUrl.pathname || '';
+        // Match /api/notebook/{encoded_path}/ws
+        const match = pathname.match(/^\/api\/notebook\/(.+)\/ws$/);
+        if (match) {
+            // Authenticate WebSocket connection
+            const { authWebSocketMiddleware } = require('../auth');
+            if (!authWebSocketMiddleware(request)) {
+                socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                wss.emit('connection', ws, request);
+            });
+        }
+        // Don't destroy socket for non-matching paths
+    });
+    wss.on('connection', async (ws, req) => {
+        const parsedUrl = (0, url_1.parse)(req.url || '', true);
+        const pathname = parsedUrl.pathname || '';
+        const match = pathname.match(/^\/api\/notebook\/(.+)\/ws$/);
+        if (!match) {
+            ws.close(1008, 'Invalid path');
+            return;
+        }
+        // Decode the notebook path
+        const encodedPath = match[1];
+        const notebookPath = decodeURIComponent(encodedPath);
+        console.log(`[Notebook WS] Connected for notebook: ${notebookPath}`);
+        // Register UI connection
+        await operation_router_1.operationRouter.registerUI(ws, notebookPath);
+        const heartbeatInterval = setInterval(() => {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                try {
+                    ws.ping();
+                }
+                catch {
+                    // Ignore ping failures; close/error handlers will clean up.
+                }
+            }
+        }, 15000);
+        ws.on('error', (err) => {
+            console.error(`[Notebook WS] WebSocket error for ${notebookPath}:`, err);
+        });
+        ws.on('pong', () => {
+            operation_router_1.operationRouter.markUIActivity(ws, notebookPath);
+        });
+        ws.on('message', async (data) => {
+            operation_router_1.operationRouter.markUIActivity(ws, notebookPath);
+            try {
+                const message = JSON.parse(data.toString());
+                if (message.type === 'operationResult') {
+                    // UI is responding to an operation request
+                    operation_router_1.operationRouter.handleUIResponse(notebookPath, message);
+                }
+                else if (message.type === 'notebookData') {
+                    // UI is responding to a readNotebook request
+                    // Pass message directly like Python does - it contains { requestId, result: { success, data } }
+                    operation_router_1.operationRouter.handleUIResponse(notebookPath, message);
+                }
+                else if (message.type === 'ping') {
+                    // Respond to keep-alive ping with pong
+                    ws.send(JSON.stringify({ type: 'pong' }));
+                }
+                else {
+                    console.warn(`[Notebook WS] Unknown message type:`, message.type);
+                }
+            }
+            catch (err) {
+                console.error('[Notebook WS] Error parsing message:', err);
+            }
+        });
+        ws.on('close', () => {
+            clearInterval(heartbeatInterval);
+            console.log(`[Notebook WS] Disconnected for notebook: ${notebookPath}`);
+            operation_router_1.operationRouter.unregisterUI(ws, notebookPath);
+        });
+    });
+    return wss;
+}

package/node-server/dist/notebook/operation-router.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Notebook Operation Router
+ *
+ * Routes notebook operations to either:
+ * 1. Connected UI via WebSocket (real-time collaboration)
+ * 2. Headless notebook manager (file-based when no UI)
+ *
+ * From the agent's (MCP) perspective, operations look identical regardless of mode.
+ */
+import { WebSocket } from 'ws';
+import { HeadlessOperationHandler } from './headless-handler';
+interface KernelChangedPayload {
+    kernelName: string;
+    serverId?: string | null;
+}
+type Backend = 'ui' | 'headless';
+interface OperationResult {
+    success: boolean;
+    error?: string;
+    backend?: Backend;
+    [key: string]: unknown;
+}
+interface AgentLock {
+    agentId: string;
+    clientName?: string;
+    clientVersion?: string;
+    expiresAt: number;
+    notebookPath: string;
+    lockedAt: number;
+}
+export declare class OperationRouter {
+    private uiConnections;
+    private headlessHandler;
+    private operationTimeout;
+    private agentLocks;
+    setHeadlessHandler(handler: HeadlessOperationHandler): void;
+    /**
+     * Register a UI connection for a notebook path.
+     */
+    registerUI(websocket: WebSocket, notebookPath: string): Promise<void>;
+    /**
+     * Unregister a UI connection.
+     */
+    unregisterUI(websocket: WebSocket, notebookPath: string): void;
+    notifyKernelChanged(notebookPath: string, payload: KernelChangedPayload): void;
+    /**
+     * Check if a UI is connected for the notebook.
+     */
+    hasUI(notebookPath: string): boolean;
+    /**
+     * Record UI WebSocket activity so stale connections stop intercepting operations.
+     */
+    markUIActivity(websocket: WebSocket, notebookPath: string): void;
+    /**
+     * Start an agent session with locking.
+     * Returns success if lock acquired, error if already locked by another agent.
+     */
+    startAgentSession(notebookPath: string, agentId: string, metadata?: {
+        clientName?: string;
+        clientVersion?: string;
+    }): {
+        success: boolean;
+        error?: string;
+        lock?: AgentLock;
+    };
+    /**
+     * End an agent session and release the lock.
+     * Only the lock holder can release the lock.
+     */
+    endAgentSession(notebookPath: string, agentId: string): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Check if a notebook is in an agent session.
+     */
+    isAgentSession(notebookPath: string): boolean;
+    /**
+     * Get the agent ID holding the lock, if any.
+     */
+    getAgentLock(notebookPath: string): AgentLock | null;
+    /**
+     * Refresh lock timeout for an agent operation.
+     */
+    refreshAgentLock(notebookPath: string, agentId: string): boolean;
+    /**
+     * Clean up expired locks.
+     */
+    private cleanupExpiredLocks;
+    /**
+     * Get the first available UI connection (for operations that can use any UI).
+     */
+    private getAnyUIConnection;
+    private isUIConnectionResponsive;
+    private getResponsiveUIConnection;
+    /**
+     * Apply a notebook operation.
+     */
+    applyOperation(operation: Record<string, unknown>): Promise<OperationResult>;
+    private forwardToUI;
+    /**
+     * Handle operation response from UI.
+     */
+    handleUIResponse(notebookPath: string, response: Record<string, unknown>): void;
+    private applyHeadless;
+    /**
+     * Read notebook state.
+     */
+    readNotebook(notebookPath: string, includeOutputs?: boolean, maxLines?: number, maxChars?: number, maxLinesError?: number, maxCharsError?: number): Promise<OperationResult>;
+    private readFromUI;
+    private readFromFile;
+    private applyOutputTruncation;
+}
+export declare const operationRouter: OperationRouter;
+export {};