nebula-notebook 0.1.0

package/node-server/dist/notebook/headless-handler.js

@@ -0,0 +1,1530 @@
+"use strict";
+/**
+ * Headless Operation Handler
+ *
+ * Handles notebook operations when no UI is connected to Nebula.
+ * Mirrors useOperationHandler (React) but operates on files instead of UI state.
+ */
+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.HeadlessOperationHandler = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const uuid_1 = require("uuid");
+const cell_metadata_1 = require("./cell-metadata");
+const undoRedoManager_1 = require("./undoRedoManager");
+const kernelspec_1 = require("../kernel/kernelspec");
+function copyCellOutput(output) {
+    return {
+        type: (output.type || 'stdout'),
+        content: output.content || '',
+        ...(output.mimeBundle ? { mimeBundle: output.mimeBundle } : {}),
+        ...(output.metadata ? { metadata: output.metadata } : {}),
+        ...(output.preferredMimeType ? { preferredMimeType: output.preferredMimeType } : {}),
+    };
+}
+// Output truncation defaults
+const OUTPUT_DEFAULT_MAX_LINES = 100;
+const OUTPUT_DEFAULT_MAX_CHARS = 10000;
+const OUTPUT_DEFAULT_MAX_LINES_ERROR = 200;
+const OUTPUT_DEFAULT_MAX_CHARS_ERROR = 20000;
+class HeadlessOperationHandler {
+    fsService;
+    kernelService;
+    operationRouter;
+    undoRedoManager;
+    cache = new Map();
+    writeLocks = new Map();
+    constructor(fsService, operationRouter, kernelService) {
+        this.fsService = fsService;
+        this.operationRouter = operationRouter || null;
+        this.kernelService = kernelService || null;
+        this.undoRedoManager = (0, undoRedoManager_1.getUndoRedoManager)(this.fsService);
+    }
+    /**
+     * Get notebook from cache, loading from disk if needed.
+     */
+    getCachedNotebook(notebookPath) {
+        if (!this.cache.has(notebookPath)) {
+            const result = this.fsService.getNotebookCells(notebookPath);
+            this.cache.set(notebookPath, {
+                cells: result.cells || [],
+                metadata: result.metadata || {},
+                dirty: false,
+            });
+        }
+        return this.cache.get(notebookPath);
+    }
+    getCells(notebookPath) {
+        return this.getCachedNotebook(notebookPath).cells;
+    }
+    getVisibleOutputs(cell) {
+        if (cell.pendingOutputReset) {
+            return [];
+        }
+        return cell.outputs || [];
+    }
+    saveCells(notebookPath, cells) {
+        const notebook = this.getCachedNotebook(notebookPath);
+        notebook.cells = cells;
+        notebook.dirty = true;
+    }
+    /**
+     * Persist dirty notebooks to disk.
+     */
+    async flush(notebookPath) {
+        const paths = notebookPath ? [notebookPath] : Array.from(this.cache.keys());
+        for (const p of paths) {
+            const notebook = this.cache.get(p);
+            if (notebook?.dirty) {
+                await this.asyncPersist(p);
+            }
+        }
+    }
+    async asyncPersist(notebookPath) {
+        const notebook = this.cache.get(notebookPath);
+        if (!notebook)
+            return;
+        // Keep writing while dirty
+        while (notebook.dirty) {
+            const cells = JSON.parse(JSON.stringify(notebook.cells));
+            notebook.dirty = false;
+            const history = this.undoRedoManager.getHistory(notebookPath, cells);
+            await this.fsService.saveNotebookBundle(notebookPath, cells, undefined, history);
+        }
+    }
+    schedulePersist(notebookPath) {
+        // Schedule async persist
+        this.asyncPersist(notebookPath).catch(err => {
+            console.error(`[HeadlessHandler] Failed to persist ${notebookPath}:`, err);
+        });
+    }
+    /**
+     * Invalidate cache for a notebook.
+     */
+    invalidate(notebookPath) {
+        if (notebookPath) {
+            this.cache.delete(notebookPath);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    /**
+     * Check if notebook has unsaved changes.
+     */
+    isDirty(notebookPath) {
+        return this.cache.get(notebookPath)?.dirty || false;
+    }
+    /**
+     * Check if agent has permission to modify this notebook.
+     */
+    checkAgentPermission(notebookPath, _operationType) {
+        const status = this.fsService.getAgentPermissionStatus(notebookPath);
+        if (status.agent_created) {
+            return null;
+        }
+        if (status.agent_permitted) {
+            if (!status.has_history) {
+                return {
+                    success: false,
+                    error: `Agent cannot modify "${notebookPath}": notebook is user-permitted but history is not enabled. Open the notebook in the UI first to enable history tracking, or the agent can create a new notebook.`,
+                };
+            }
+            return null;
+        }
+        return {
+            success: false,
+            error: `Agent cannot modify "${notebookPath}": notebook is not agent-permitted. Either open the notebook in Nebula UI and grant agent permission, or the agent can create a new notebook which will be automatically permitted.`,
+        };
+    }
+    /**
+     * Apply a notebook operation.
+     */
+    async applyOperation(operation) {
+        const opType = operation.type;
+        const notebookPath = operation.notebookPath || '';
+        // Read-only operations
+        const readOnlyOps = new Set(['readCell', 'readCellOutput', 'searchCells', 'getUpdatesSince', 'startAgentSession', 'endAgentSession']);
+        const permissionExemptOps = new Set(['createNotebook', 'readCell', 'readCellOutput', 'searchCells', 'getUpdatesSince', 'startAgentSession', 'endAgentSession']);
+        // Check permission for write operations
+        if (!permissionExemptOps.has(opType) && notebookPath) {
+            const permissionError = this.checkAgentPermission(notebookPath, opType);
+            if (permissionError) {
+                return permissionError;
+            }
+        }
+        try {
+            let result;
+            switch (opType) {
+                case 'insertCell':
+                    result = await this.insertCell(operation);
+                    break;
+                case 'deleteCell':
+                    result = await this.deleteCell(operation);
+                    break;
+                case 'updateContent':
+                    result = await this.updateContent(operation);
+                    break;
+                case 'updateMetadata':
+                    result = await this.updateMetadata(operation);
+                    break;
+                case 'moveCell':
+                    result = await this.moveCell(operation);
+                    break;
+                case 'duplicateCell':
+                    result = await this.duplicateCell(operation);
+                    break;
+                case 'updateOutputs':
+                    result = await this.updateOutputs(operation);
+                    break;
+                case 'createNotebook':
+                    result = await this.createNotebook(operation);
+                    break;
+                case 'readCell':
+                    result = await this.readCell(operation);
+                    break;
+                case 'readCellOutput':
+                    result = await this.readCellOutput(operation);
+                    break;
+                case 'clearNotebook':
+                    result = await this.clearNotebook(operation);
+                    break;
+                case 'deleteCells':
+                    result = await this.deleteCells(operation);
+                    break;
+                case 'insertCells':
+                    result = await this.insertCells(operation);
+                    break;
+                case 'searchCells':
+                    result = await this.searchCells(operation);
+                    break;
+                case 'getUpdatesSince': {
+                    const sinceTimestamp = operation.sinceTimestamp || 0;
+                    const updatesSince = this.getUpdatesSince(notebookPath, sinceTimestamp);
+                    result = {
+                        success: true,
+                        updatesSince,
+                        serverTimestamp: Date.now(),
+                    };
+                    break;
+                }
+                case 'clearOutputs':
+                    result = await this.clearOutputs(operation);
+                    break;
+                case 'startKernel':
+                    result = await this.startKernelOp(operation, notebookPath);
+                    break;
+                case 'shutdownKernel':
+                    result = await this.shutdownKernelOp(notebookPath);
+                    break;
+                case 'restartKernel':
+                    result = await this.restartKernelOp(notebookPath);
+                    break;
+                case 'interruptKernel':
+                    result = await this.interruptKernelOp(notebookPath);
+                    break;
+                case 'executeCell':
+                    result = await this.executeCell(operation, notebookPath);
+                    break;
+                case 'startAgentSession': {
+                    const agentId = operation.agentId || 'unknown';
+                    const clientName = operation.clientName;
+                    const clientVersion = operation.clientVersion;
+                    if (this.operationRouter) {
+                        result = this.operationRouter.startAgentSession(notebookPath, agentId, { clientName, clientVersion });
+                    }
+                    else {
+                        result = { success: true, lock: { agentId, clientName, clientVersion, expiresAt: Date.now() + 5 * 60 * 1000, lockedAt: Date.now() } };
+                    }
+                    break;
+                }
+                case 'endAgentSession': {
+                    const agentId = operation.agentId || 'unknown';
+                    if (this.operationRouter) {
+                        result = this.operationRouter.endAgentSession(notebookPath, agentId);
+                    }
+                    else {
+                        result = { success: true };
+                    }
+                    break;
+                }
+                case 'undo':
+                    result = await this.handleUndo(notebookPath);
+                    break;
+                case 'redo':
+                    result = await this.handleRedo(notebookPath);
+                    break;
+                default:
+                    return { success: false, error: `Unknown operation type: ${opType}` };
+            }
+            // Schedule persist for write operations
+            if (result.success && !readOnlyOps.has(opType) && notebookPath) {
+                this.schedulePersist(notebookPath);
+            }
+            return result;
+        }
+        catch (err) {
+            return { success: false, error: String(err) };
+        }
+    }
+    /**
+     * Read notebook from cache with optional output truncation.
+     */
+    async readNotebook(notebookPath, includeOutputs = true, maxLines, maxChars, maxLinesError, maxCharsError) {
+        try {
+            const notebook = this.getCachedNotebook(notebookPath);
+            let cells = notebook.cells;
+            if (includeOutputs) {
+                const effectiveMaxLines = maxLines ?? OUTPUT_DEFAULT_MAX_LINES;
+                const effectiveMaxChars = maxChars ?? OUTPUT_DEFAULT_MAX_CHARS;
+                const effectiveMaxLinesError = maxLinesError ?? OUTPUT_DEFAULT_MAX_LINES_ERROR;
+                const effectiveMaxCharsError = maxCharsError ?? OUTPUT_DEFAULT_MAX_CHARS_ERROR;
+                cells = this.truncateCellOutputs(cells, effectiveMaxLines, effectiveMaxChars, effectiveMaxLinesError, effectiveMaxCharsError);
+            }
+            else {
+                cells = cells.map(cell => ({ ...cell, outputs: [] }));
+            }
+            return {
+                success: true,
+                data: {
+                    path: notebookPath,
+                    cells,
+                    metadata: notebook.metadata,
+                },
+            };
+        }
+        catch (err) {
+            return { success: false, error: String(err) };
+        }
+    }
+    truncateCellOutputs(cells, maxLines, maxChars, maxLinesError, maxCharsError) {
+        return cells.map(cell => ({
+            ...cell,
+            outputs: (cell.outputs || []).map(output => {
+                const outputType = output.type || 'stdout';
+                const content = output.content || '';
+                let result;
+                // Skip truncation for binary/image outputs
+                if (outputType === 'image' || outputType === 'html' || outputType === 'display_data') {
+                    result = {
+                        ...output,
+                        type: outputType,
+                        content,
+                        is_binary: outputType === 'image',
+                    };
+                }
+                else {
+                    // Use separate limits for error outputs
+                    const linesLimit = outputType === 'error' ? maxLinesError : maxLines;
+                    const charsLimit = outputType === 'error' ? maxCharsError : maxChars;
+                    const { truncatedContent, metadata } = this.truncateOutput(content, linesLimit, charsLimit, 0);
+                    result = {
+                        ...output,
+                        type: outputType,
+                        content: truncatedContent,
+                        ...metadata,
+                    };
+                }
+                // Strip internal-only fields: `id`/`timestamp` are stamped by convertOutputs
+                // for the live UI, but the headless/MCP read contract returns clean outputs
+                // (see the "should apply output truncation" test).
+                const mutable = result;
+                delete mutable.id;
+                delete mutable.timestamp;
+                return result;
+            }),
+        }));
+    }
+    truncateOutput(content, maxLines, maxChars, lineOffset = 0) {
+        const lines = content.split('\n');
+        const totalLines = lines.length;
+        const totalChars = content.length;
+        const offsetLines = lines.slice(lineOffset);
+        const startLine = lineOffset;
+        let endLine = startLine;
+        let charCount = 0;
+        let truncated = false;
+        let truncationReason = null;
+        const resultLines = [];
+        for (let i = 0; i < offsetLines.length; i++) {
+            const line = offsetLines[i];
+            const newCharCount = charCount + line.length + (i > 0 ? 1 : 0);
+            if (i >= maxLines) {
+                truncated = true;
+                truncationReason = 'lines';
+                break;
+            }
+            if (newCharCount > maxChars && i > 0) {
+                truncated = true;
+                truncationReason = 'chars';
+                break;
+            }
+            resultLines.push(line);
+            charCount = newCharCount;
+            endLine = startLine + i + 1;
+        }
+        const truncatedContent = resultLines.join('\n');
+        return {
+            truncatedContent,
+            metadata: {
+                truncated,
+                truncation_reason: truncationReason,
+                total_lines: totalLines,
+                total_chars: totalChars,
+                returned_range: {
+                    start_line: startLine,
+                    end_line: endLine,
+                    char_count: truncatedContent.length,
+                },
+            },
+        };
+    }
+    // Operation implementations
+    async insertCell(operation) {
+        const notebookPath = operation.notebookPath;
+        const index = operation.index;
+        const cellData = operation.cell;
+        const metadata = cellData.metadata || {};
+        const cells = this.getCells(notebookPath);
+        let cellId = cellData.id;
+        const existingIds = new Set(cells.map(c => c.id));
+        const originalId = cellId;
+        let idModified = false;
+        if (existingIds.has(cellId)) {
+            let counter = 2;
+            while (existingIds.has(`${originalId}-${counter}`)) {
+                counter++;
+            }
+            cellId = `${originalId}-${counter}`;
+            idModified = true;
+        }
+        const newCell = {
+            id: cellId,
+            type: cellData.type || 'code',
+            content: cellData.content || '',
+            outputs: [],
+            isExecuting: false,
+            executionCount: null,
+            scrolled: metadata.scrolled,
+            scrolledHeight: metadata.scrolledHeight,
+        };
+        let actualIndex;
+        if (index === -1 || index >= cells.length) {
+            cells.push(newCell);
+            actualIndex = cells.length - 1;
+        }
+        else {
+            cells.splice(index, 0, newCell);
+            actualIndex = index;
+        }
+        this.saveCells(notebookPath, cells);
+        // Record operation for undo/redo
+        this.recordUndoableOperation(notebookPath, {
+            type: 'insertCell',
+            index: actualIndex,
+            cell: newCell,
+            source: 'mcp'
+        });
+        return {
+            success: true,
+            cellId,
+            cellIndex: actualIndex,
+            idModified,
+            requestedId: idModified ? originalId : null,
+            totalCells: cells.length,
+        };
+    }
+    async deleteCell(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        const cellIndex = operation.cellIndex;
+        const cells = this.getCells(notebookPath);
+        let targetIndex = null;
+        if (cellId) {
+            targetIndex = cells.findIndex(c => c.id === cellId);
+            if (targetIndex === -1)
+                targetIndex = null;
+        }
+        else if (cellIndex !== undefined) {
+            targetIndex = cellIndex;
+        }
+        if (targetIndex === null || targetIndex >= cells.length) {
+            return { success: false, error: 'Cell not found' };
+        }
+        // Save the cell for undo before deleting
+        const deletedCell = { ...cells[targetIndex] };
+        cells.splice(targetIndex, 1);
+        this.saveCells(notebookPath, cells);
+        // Record operation for undo/redo
+        this.recordUndoableOperation(notebookPath, {
+            type: 'deleteCell',
+            index: targetIndex,
+            cell: deletedCell,
+            source: 'mcp'
+        });
+        return {
+            success: true,
+            cellIndex: targetIndex,
+            totalCells: cells.length,
+        };
+    }
+    async updateContent(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        const content = operation.content;
+        const cells = this.getCells(notebookPath);
+        const targetIndex = cells.findIndex(c => c.id === cellId);
+        if (targetIndex === -1) {
+            return { success: false, error: `Cell with ID "${cellId}" not found` };
+        }
+        // Save old content for undo
+        const oldContent = cells[targetIndex].content;
+        cells[targetIndex].content = content;
+        this.saveCells(notebookPath, cells);
+        // Record operation for undo/redo (only if content changed)
+        if (oldContent !== content) {
+            this.recordUndoableOperation(notebookPath, {
+                type: 'updateContent',
+                cellId,
+                oldContent,
+                newContent: content,
+                source: 'mcp'
+            });
+        }
+        return {
+            success: true,
+            cellId,
+            cellIndex: targetIndex,
+        };
+    }
+    async updateMetadata(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        const changes = operation.changes;
+        // Validate all changes
+        const errors = [];
+        for (const [key, value] of Object.entries(changes)) {
+            const validation = (0, cell_metadata_1.validateMetadataValue)(key, value);
+            if (!validation.valid) {
+                errors.push(validation.error || `Invalid field: ${key}`);
+            }
+        }
+        if (errors.length > 0) {
+            return { success: false, error: errors.join('; ') };
+        }
+        const cells = this.getCells(notebookPath);
+        const targetIndex = cells.findIndex(c => c.id === cellId);
+        if (targetIndex === -1) {
+            return { success: false, error: `Cell with ID "${cellId}" not found` };
+        }
+        const cell = cells[targetIndex];
+        const oldValues = {};
+        // Handle ID change specially
+        if ('id' in changes) {
+            const newId = changes.id;
+            const existingIds = new Set(cells.map(c => c.id));
+            existingIds.delete(cellId);
+            let actualNewId = newId;
+            let idModified = false;
+            if (existingIds.has(newId)) {
+                let counter = 2;
+                while (existingIds.has(`${newId}-${counter}`)) {
+                    counter++;
+                }
+                actualNewId = `${newId}-${counter}`;
+                idModified = true;
+            }
+            oldValues.id = cellId;
+            cell.id = actualNewId;
+        }
+        // Apply other changes
+        for (const [key, value] of Object.entries(changes)) {
+            if (key === 'id')
+                continue;
+            oldValues[key] = cell[key];
+            cell[key] = value;
+        }
+        this.saveCells(notebookPath, cells);
+        // Record operation for undo/redo
+        const metadataChanges = {};
+        for (const [k, v] of Object.entries(changes)) {
+            metadataChanges[k] = { old: oldValues[k], new: v };
+        }
+        this.recordUndoableOperation(notebookPath, {
+            type: 'updateMetadata',
+            cellId: cell.id,
+            changes: metadataChanges,
+            source: 'mcp'
+        });
+        return {
+            success: true,
+            cellId: cell.id,
+            cellIndex: targetIndex,
+            changes: Object.fromEntries(Object.entries(changes).map(([k, v]) => [k, { old: oldValues[k], new: v }])),
+        };
+    }
+    async moveCell(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        let fromIndex = operation.fromIndex;
+        let toIndex = operation.toIndex;
+        const afterCellId = operation.afterCellId;
+        const cells = this.getCells(notebookPath);
+        // Determine source
+        if (cellId) {
+            fromIndex = cells.findIndex(c => c.id === cellId);
+            if (fromIndex === -1) {
+                return { success: false, error: `Cell with ID "${cellId}" not found` };
+            }
+        }
+        else if (fromIndex === undefined) {
+            return { success: false, error: 'Must provide cellId or fromIndex' };
+        }
+        if (fromIndex < 0 || fromIndex >= cells.length) {
+            return { success: false, error: 'Invalid fromIndex' };
+        }
+        // Determine target
+        if (afterCellId) {
+            const afterIndex = cells.findIndex(c => c.id === afterCellId);
+            if (afterIndex === -1) {
+                return { success: false, error: `Cell with ID "${afterCellId}" not found` };
+            }
+            toIndex = afterIndex + 1;
+            if (fromIndex < toIndex) {
+                toIndex--;
+            }
+        }
+        else if (toIndex === -1) {
+            toIndex = 0;
+        }
+        else if (toIndex === undefined) {
+            return { success: false, error: 'Must provide afterCellId or toIndex' };
+        }
+        if (toIndex < 0 || toIndex >= cells.length) {
+            return { success: false, error: 'Invalid toIndex' };
+        }
+        // Perform move
+        const [cell] = cells.splice(fromIndex, 1);
+        cells.splice(toIndex, 0, cell);
+        this.saveCells(notebookPath, cells);
+        // Record operation for undo/redo
+        this.recordUndoableOperation(notebookPath, {
+            type: 'moveCell',
+            fromIndex,
+            toIndex,
+            source: 'mcp'
+        });
+        return {
+            success: true,
+            cellId: cell.id,
+            fromIndex,
+            toIndex,
+        };
+    }
+    async duplicateCell(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellIndex = operation.cellIndex;
+        const newCellId = operation.newCellId;
+        const cells = this.getCells(notebookPath);
+        if (cellIndex < 0 || cellIndex >= cells.length) {
+            return { success: false, error: 'Invalid cellIndex' };
+        }
+        const originalCell = cells[cellIndex];
+        const existingIds = new Set(cells.map(c => c.id));
+        let actualId = newCellId;
+        let idModified = false;
+        if (existingIds.has(newCellId)) {
+            let counter = 2;
+            while (existingIds.has(`${newCellId}-${counter}`)) {
+                counter++;
+            }
+            actualId = `${newCellId}-${counter}`;
+            idModified = true;
+        }
+        const newCell = {
+            id: actualId,
+            type: originalCell.type,
+            content: originalCell.content,
+            outputs: [],
+            isExecuting: false,
+            executionCount: null,
+        };
+        cells.splice(cellIndex + 1, 0, newCell);
+        this.saveCells(notebookPath, cells);
+        return {
+            success: true,
+            cellId: actualId,
+            cellIndex: cellIndex + 1,
+            idModified,
+            totalCells: cells.length,
+        };
+    }
+    async updateOutputs(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        const outputs = operation.outputs;
+        const executionCount = operation.executionCount;
+        const cells = this.getCells(notebookPath);
+        const targetIndex = cells.findIndex(c => c.id === cellId);
+        if (targetIndex === -1) {
+            return { success: false, error: `Cell with ID "${cellId}" not found` };
+        }
+        cells[targetIndex].outputs = outputs.map(o => copyCellOutput(o));
+        if (executionCount !== undefined) {
+            cells[targetIndex].executionCount = executionCount;
+        }
+        this.saveCells(notebookPath, cells);
+        return {
+            success: true,
+            cellId,
+            cellIndex: targetIndex,
+        };
+    }
+    async createNotebook(operation) {
+        const notebookPath = operation.notebookPath;
+        const overwrite = operation.overwrite || false;
+        const kernelName = operation.kernelName || 'python3';
+        const kernelDisplayName = operation.kernelDisplayName || 'Python 3';
+        const normalizedPath = this.fsService.normalizePath(notebookPath);
+        if (fs.existsSync(normalizedPath) && !overwrite) {
+            return {
+                success: false,
+                error: `Notebook already exists: ${notebookPath}. Use overwrite=true to replace.`,
+            };
+        }
+        const notebook = {
+            nbformat: 4,
+            nbformat_minor: 5,
+            metadata: {
+                kernelspec: {
+                    name: kernelName,
+                    display_name: kernelDisplayName,
+                },
+                language_info: {
+                    name: 'python',
+                },
+                nebula: {
+                    agent_created: true,
+                    agent_permitted: true,
+                },
+            },
+            cells: [],
+        };
+        const dir = path.dirname(normalizedPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(normalizedPath, JSON.stringify(notebook, null, 2), 'utf-8');
+        this.invalidate(notebookPath);
+        const mtime = fs.statSync(normalizedPath).mtimeMs / 1000; // Convert to seconds like Python
+        return {
+            success: true,
+            path: notebookPath,
+            mtime,
+        };
+    }
+    async readCell(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        const cellIndex = operation.cellIndex;
+        const cells = this.getCells(notebookPath);
+        let targetIndex = null;
+        let cell = null;
+        if (cellId) {
+            targetIndex = cells.findIndex(c => c.id === cellId);
+            if (targetIndex === -1) {
+                return { success: false, error: `Cell with ID "${cellId}" not found` };
+            }
+            cell = cells[targetIndex];
+        }
+        else if (cellIndex !== undefined) {
+            if (cellIndex < 0 || cellIndex >= cells.length) {
+                return { success: false, error: `Cell index ${cellIndex} out of range` };
+            }
+            targetIndex = cellIndex;
+            cell = cells[cellIndex];
+        }
+        else {
+            return { success: false, error: 'Must provide cellId or cellIndex' };
+        }
+        return {
+            success: true,
+            cellId: cell.id,
+            cellIndex: targetIndex,
+            cell: {
+                id: cell.id,
+                type: cell.type,
+                content: cell.content || '',
+                outputs: (cell.outputs || []).map(o => copyCellOutput(o)),
+                executionCount: cell.executionCount,
+                metadata: {
+                    scrolled: cell.scrolled,
+                    scrolledHeight: cell.scrolledHeight,
+                },
+            },
+        };
+    }
+    async readCellOutput(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId ?? operation.cell_id;
+        const cellIndex = operation.cellIndex ?? operation.cell_index;
+        const maxLines = operation.max_lines ?? OUTPUT_DEFAULT_MAX_LINES;
+        const maxChars = operation.max_chars ?? OUTPUT_DEFAULT_MAX_CHARS;
+        const maxLinesError = operation.max_lines_error ?? OUTPUT_DEFAULT_MAX_LINES_ERROR;
+        const maxCharsError = operation.max_chars_error ?? OUTPUT_DEFAULT_MAX_CHARS_ERROR;
+        const lineOffset = operation.line_offset ?? 0;
+        const saveToFile = operation.save_to_file ?? false;
+        const maxWait = (operation.maxWait ?? operation.max_wait ?? 0); // seconds
+        let cells = this.getCells(notebookPath);
+        let targetIndex = null;
+        let cell = null;
+        let targetCellId = null;
+        if (cellId) {
+            targetIndex = cells.findIndex(c => c.id === cellId);
+            if (targetIndex === -1) {
+                return { success: false, error: `Cell with ID "${cellId}" not found` };
+            }
+            cell = cells[targetIndex];
+            targetCellId = cell.id;
+        }
+        else if (cellIndex !== undefined) {
+            if (cellIndex < 0 || cellIndex >= cells.length) {
+                return { success: false, error: `Cell index ${cellIndex} out of range` };
+            }
+            targetIndex = cellIndex;
+            cell = cells[cellIndex];
+            targetCellId = cell.id;
+        }
+        else {
+            return { success: false, error: 'Must provide cellId or cellIndex' };
+        }
+        // Poll for new outputs if maxWait > 0
+        if (maxWait > 0) {
+            let visibleOutputs = this.getVisibleOutputs(cell);
+            let baselineOutputCount = visibleOutputs.length;
+            let baselineOutputChars = visibleOutputs.reduce((sum, o) => sum + (o.content?.length || 0), 0);
+            let baselineExecutionCount = cell.executionCount;
+            let wasExecuting = !!cell.isExecuting;
+            const startTime = Date.now();
+            const pollInterval = 500; // Poll every 500ms like Python
+            while ((Date.now() - startTime) < maxWait * 1000) {
+                await this.sleep(pollInterval);
+                // Re-read cells from cache to detect new outputs
+                cells = this.getCells(notebookPath);
+                if (targetCellId) {
+                    targetIndex = cells.findIndex(c => c.id === targetCellId);
+                    if (targetIndex === -1) {
+                        return { success: false, error: `Cell with ID "${targetCellId}" not found` };
+                    }
+                }
+                cell = cells[targetIndex];
+                if (!cell) {
+                    return { success: false, error: 'Cell not found' };
+                }
+                // If execution starts after we began polling (e.g. queued), reset the baseline so we
+                // wait for outputs from this run rather than comparing against previous outputs.
+                if (!wasExecuting && cell.isExecuting) {
+                    wasExecuting = true;
+                    visibleOutputs = this.getVisibleOutputs(cell);
+                    baselineOutputCount = visibleOutputs.length;
+                    baselineOutputChars = visibleOutputs.reduce((sum, o) => sum + (o.content?.length || 0), 0);
+                    baselineExecutionCount = cell.executionCount;
+                }
+                visibleOutputs = this.getVisibleOutputs(cell);
+                const currentOutputCount = visibleOutputs.length;
+                const currentOutputChars = visibleOutputs.reduce((sum, o) => sum + (o.content?.length || 0), 0);
+                const executionCountChanged = cell.executionCount !== baselineExecutionCount;
+                // Check if outputs changed (more outputs or more content)
+                if (currentOutputCount > baselineOutputCount || currentOutputChars > baselineOutputChars || executionCountChanged) {
+                    break; // New output arrived
+                }
+                // If the cell finished executing but produced no additional output, stop waiting.
+                if (wasExecuting && !cell.isExecuting) {
+                    break;
+                }
+                // If the cell is already idle, there is no in-flight execution to wait on.
+                if (!wasExecuting && !cell.isExecuting) {
+                    break;
+                }
+            }
+        }
+        const processedOutputs = [];
+        const tempFiles = [];
+        for (const output of this.getVisibleOutputs(cell)) {
+            const outputType = output.type || 'stdout';
+            const content = output.content || '';
+            // Images are returned as-is
+            if (outputType === 'image') {
+                processedOutputs.push({
+                    type: outputType,
+                    content,
+                    truncated: false,
+                    is_binary: true,
+                });
+                continue;
+            }
+            // Save to temp file if requested
+            let tempFilePath;
+            if (saveToFile && content) {
+                tempFilePath = this.saveOutputToTempFile(content, cell.id);
+                tempFiles.push(tempFilePath);
+            }
+            // Use separate limits for errors
+            const linesLimit = outputType === 'error' ? maxLinesError : maxLines;
+            const charsLimit = outputType === 'error' ? maxCharsError : maxChars;
+            const { truncatedContent, metadata } = this.truncateOutput(content, linesLimit, charsLimit, lineOffset);
+            const processedOutput = {
+                type: outputType,
+                content: truncatedContent,
+                ...metadata,
+            };
+            if (tempFilePath) {
+                processedOutput.temp_file = tempFilePath;
+                processedOutput.temp_file_size = content.length;
+            }
+            processedOutputs.push(processedOutput);
+        }
+        return {
+            success: true,
+            cellId: cell.id,
+            cellIndex: targetIndex,
+            outputs: processedOutputs,
+            executionCount: cell.executionCount,
+            executionStatus: cell.isExecuting ? 'busy' : 'idle',
+            output_count: processedOutputs.length,
+            temp_files: tempFiles.length > 0 ? tempFiles : null,
+        };
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    saveOutputToTempFile(content, cellId) {
+        const tempDir = path.join(os.tmpdir(), 'nebula', 'outputs');
+        if (!fs.existsSync(tempDir)) {
+            fs.mkdirSync(tempDir, { recursive: true });
+        }
+        const filename = `cell_output_${cellId}_${(0, uuid_1.v4)().slice(0, 8)}.txt`;
+        const filepath = path.join(tempDir, filename);
+        fs.writeFileSync(filepath, content, 'utf-8');
+        return filepath;
+    }
+    async clearNotebook(operation) {
+        const notebookPath = operation.notebookPath;
+        const cells = this.getCells(notebookPath);
+        const deletedCount = cells.length;
+        if (deletedCount === 0) {
+            return { success: true, deletedCount: 0 };
+        }
+        // Delete from end to start to avoid index shifting issues
+        for (let i = cells.length - 1; i >= 0; i--) {
+            const deletedCell = { ...cells[i] };
+            cells.splice(i, 1);
+            this.saveCells(notebookPath, cells);
+            this.recordUndoableOperation(notebookPath, {
+                type: 'deleteCell',
+                index: i,
+                cell: deletedCell,
+                source: 'mcp'
+            });
+        }
+        return {
+            success: true,
+            deletedCount,
+        };
+    }
+    async deleteCells(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellIds = operation.cellIds || [];
+        if (cellIds.length === 0) {
+            return { success: false, error: 'No cell IDs provided' };
+        }
+        const cells = this.getCells(notebookPath);
+        const deletedIds = [];
+        const notFound = [];
+        const indicesToDelete = [];
+        for (const cellId of cellIds) {
+            const idx = cells.findIndex(c => c.id === cellId);
+            if (idx !== -1) {
+                indicesToDelete.push(idx);
+                deletedIds.push(cellId);
+            }
+            else {
+                notFound.push(cellId);
+            }
+        }
+        // Delete in reverse order
+        for (const idx of indicesToDelete.sort((a, b) => b - a)) {
+            cells.splice(idx, 1);
+        }
+        this.saveCells(notebookPath, cells);
+        return {
+            success: true,
+            deletedCount: deletedIds.length,
+            deletedIds,
+            notFound: notFound.length > 0 ? notFound : null,
+            totalCells: cells.length,
+        };
+    }
+    async insertCells(operation) {
+        const notebookPath = operation.notebookPath;
+        const position = operation.position ?? -1;
+        const newCells = operation.cells || [];
+        if (newCells.length === 0) {
+            return { success: false, error: 'No cells provided' };
+        }
+        const cells = this.getCells(notebookPath);
+        const insertedCells = [];
+        for (let i = 0; i < newCells.length; i++) {
+            const cellData = newCells[i];
+            const cellId = cellData.id || `cell-${cells.length + i}-${Date.now()}`;
+            insertedCells.push({
+                id: cellId,
+                type: cellData.type || 'code',
+                content: cellData.content || '',
+                outputs: cellData.outputs || [],
+                isExecuting: false,
+                executionCount: cellData.executionCount ?? null,
+            });
+        }
+        let insertIndex;
+        if (position < 0 || position >= cells.length) {
+            insertIndex = cells.length;
+            cells.push(...insertedCells);
+        }
+        else {
+            insertIndex = position;
+            cells.splice(position, 0, ...insertedCells);
+        }
+        this.saveCells(notebookPath, cells);
+        return {
+            success: true,
+            insertedCount: insertedCells.length,
+            insertedIds: insertedCells.map(c => c.id),
+            startIndex: insertIndex,
+            totalCells: cells.length,
+        };
+    }
+    async searchCells(operation) {
+        const notebookPath = operation.notebookPath;
+        const query = operation.query || '';
+        const includeOutputs = operation.includeOutputs ?? false;
+        const limit = operation.limit ?? 10;
+        if (!query) {
+            return { success: false, error: 'No search query provided' };
+        }
+        const cells = this.getCells(notebookPath);
+        const queryLower = query.toLowerCase();
+        const matches = [];
+        for (let i = 0; i < cells.length && matches.length < limit; i++) {
+            const cell = cells[i];
+            const content = cell.content || '';
+            // Search in source
+            if (content.toLowerCase().includes(queryLower)) {
+                const lines = content.split('\n');
+                let matchLine = null;
+                for (let j = 0; j < lines.length; j++) {
+                    if (lines[j].toLowerCase().includes(queryLower)) {
+                        matchLine = j;
+                        break;
+                    }
+                }
+                matches.push({
+                    cellId: cell.id,
+                    cellIndex: i,
+                    matchLocation: 'source',
+                    matchLine,
+                    preview: content.slice(0, 200) + (content.length > 200 ? '...' : ''),
+                });
+            }
+            // Search in outputs
+            if (includeOutputs) {
+                for (let j = 0; j < (cell.outputs || []).length; j++) {
+                    const output = cell.outputs[j];
+                    const outContent = output.content || '';
+                    if (outContent.toLowerCase().includes(queryLower)) {
+                        matches.push({
+                            cellId: cell.id,
+                            cellIndex: i,
+                            matchLocation: 'output',
+                            outputIndex: j,
+                            outputType: output.type || 'unknown',
+                            preview: outContent.slice(0, 200) + (outContent.length > 200 ? '...' : ''),
+                        });
+                    }
+                }
+            }
+        }
+        return {
+            success: true,
+            query,
+            matchCount: matches.length,
+            matches: matches.slice(0, limit),
+            hasMore: matches.length > limit,
+        };
+    }
+    async clearOutputs(operation) {
+        const notebookPath = operation.notebookPath;
+        const cellId = operation.cellId;
+        const cellIds = operation.cellIds || [];
+        // Support both single ID and list
+        const targetIds = cellId && cellIds.length === 0 ? [cellId] : cellIds;
+        const cells = this.getCells(notebookPath);
+        const clearedIds = [];
+        const notFound = [];
+        if (targetIds.length === 0) {
+            // Clear all cells
+            for (const cell of cells) {
+                if (cell.outputs && cell.outputs.length > 0) {
+                    cell.outputs = [];
+                    clearedIds.push(cell.id);
+                }
+            }
+        }
+        else {
+            // Clear specific cells
+            for (const id of targetIds) {
+                const cell = cells.find(c => c.id === id);
+                if (cell) {
+                    cell.outputs = [];
+                    clearedIds.push(id);
+                }
+                else {
+                    notFound.push(id);
+                }
+            }
+        }
+        this.saveCells(notebookPath, cells);
+        return {
+            success: true,
+            clearedCount: clearedIds.length,
+            clearedIds,
+            notFound: notFound.length > 0 ? notFound : null,
+        };
+    }
+    /**
+     * Execute a cell using the kernel service.
+     * Matches Python headless_handler._execute_cell() behavior.
+     */
+    async executeCell(operation, notebookPath) {
+        const cellId = operation.cellId ?? operation.cell_id;
+        const cellIndex = operation.cellIndex ?? operation.cell_index;
+        const maxWait = (operation.maxWait ?? operation.max_wait ?? 10);
+        const saveOutputs = (operation.saveOutputs ?? operation.save_outputs ?? true);
+        // Get the cell
+        const cells = this.getCells(notebookPath);
+        let targetIndex;
+        let cell;
+        if (cellId) {
+            targetIndex = cells.findIndex(c => c.id === cellId);
+            if (targetIndex === -1) {
+                return { success: false, error: `Cell with ID "${cellId}" not found` };
+            }
+            cell = cells[targetIndex];
+        }
+        else if (cellIndex !== undefined) {
+            if (cellIndex < 0 || cellIndex >= cells.length) {
+                return { success: false, error: `Cell index ${cellIndex} out of range` };
+            }
+            targetIndex = cellIndex;
+            cell = cells[cellIndex];
+        }
+        else {
+            return { success: false, error: 'Must provide cellId or cellIndex' };
+        }
+        const actualCellId = cell.id;
+        // Only execute code cells
+        if (cell.type !== 'code') {
+            return { success: false, error: `Cell ${targetIndex} is not a code cell` };
+        }
+        const code = cell.content || '';
+        // Handle empty cells - just clear outputs
+        if (!code.trim()) {
+            cell.outputs = [];
+            cell.executionCount = null;
+            if (saveOutputs) {
+                this.saveCells(notebookPath, cells);
+            }
+            return {
+                success: true,
+                cellId: actualCellId,
+                cellIndex: targetIndex,
+                executionStatus: 'idle',
+                outputs: [],
+                executionCount: null,
+            };
+        }
+        // Check if kernel service is available
+        if (!this.kernelService) {
+            return {
+                success: false,
+                error: 'Kernel service not available. Make sure the Node.js server is properly initialized.',
+            };
+        }
+        // Get or create a kernel session for this notebook
+        const requestedSessionId = operation.sessionId ?? operation.session_id;
+        const preferredKernelName = this.kernelService.getNotebookKernelPreference(notebookPath)?.kernelName || 'python3';
+        let sessionId = null;
+        if (requestedSessionId && this.kernelService.hasSession(requestedSessionId)) {
+            sessionId = requestedSessionId;
+        }
+        else {
+            sessionId = this.kernelService.getSessionIdForFile(notebookPath);
+        }
+        if (!sessionId) {
+            try {
+                const result = await this.kernelService.getOrCreateKernel(notebookPath, preferredKernelName);
+                sessionId = result.sessionId;
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                return { success: false, error: `Failed to start kernel: ${errMsg}` };
+            }
+        }
+        // Preserve previous outputs until fresh output arrives so UI consumers can still
+        // render them, but mark them stale so read_output hides them for this new run.
+        cell.isExecuting = true;
+        cell.pendingOutputReset = true;
+        // Execute the cell with periodic output saving
+        const runId = (0, uuid_1.v4)();
+        const startTime = Date.now();
+        this.recordLogOperation(notebookPath, {
+            type: 'event',
+            category: 'execution',
+            name: 'runCell',
+            target: { cellId: actualCellId, cellIndex: targetIndex },
+            runId,
+            data: { sessionId },
+            source: 'mcp',
+        });
+        const outputs = [];
+        let executionCount = null;
+        let executionError = null;
+        let executionComplete = false;
+        let queueInfo = null;
+        const publishOutputs = () => {
+            if (outputs.length > 0) {
+                cell.outputs = [...outputs];
+                cell.pendingOutputReset = false;
+                return;
+            }
+            if (executionComplete) {
+                cell.outputs = [];
+                cell.pendingOutputReset = false;
+            }
+        };
+        const outputCallback = async (output) => {
+            outputs.push(copyCellOutput(output));
+            // Save outputs periodically (every 5 outputs) like Python
+            if (saveOutputs && outputs.length % 5 === 0) {
+                publishOutputs();
+                this.saveCells(notebookPath, cells);
+            }
+        };
+        try {
+            // Create execution promise
+            const executeTask = async () => {
+                try {
+                    const result = await this.kernelService.executeCode(sessionId, code, outputCallback, (info) => {
+                        queueInfo = info;
+                    }, actualCellId);
+                    executionCount = result.executionCount;
+                    if (!queueInfo && result.queuePosition !== undefined && result.queueLength !== undefined) {
+                        queueInfo = { queuePosition: result.queuePosition, queueLength: result.queueLength };
+                    }
+                    if (result.status === 'error') {
+                        executionError = result.error || 'Unknown error';
+                    }
+                }
+                catch (err) {
+                    executionError = err instanceof Error ? err.message : String(err);
+                }
+                finally {
+                    executionComplete = true;
+                }
+            };
+            // Start execution
+            const executionPromise = executeTask();
+            // Wait for completion or timeout
+            const timeoutPromise = new Promise((resolve) => {
+                setTimeout(resolve, maxWait * 1000);
+            });
+            await Promise.race([executionPromise, timeoutPromise]);
+            const elapsed = Date.now() - startTime;
+            const status = executionComplete
+                ? (executionError ? 'error' : 'idle')
+                : 'busy';
+            // Update cell with any fresh outputs from this run.
+            publishOutputs();
+            if (executionCount !== null) {
+                cell.executionCount = executionCount;
+            }
+            cell.isExecuting = !executionComplete;
+            if (saveOutputs) {
+                this.saveCells(notebookPath, cells);
+            }
+            // Cast queueInfo to avoid TS narrowing issues with async closures
+            const qi = queueInfo;
+            if (!executionComplete) {
+                // Execution continues in background - finalize when promise resolves
+                executionPromise.then(() => {
+                    const finalElapsed = Date.now() - startTime;
+                    publishOutputs();
+                    if (executionCount !== null) {
+                        cell.executionCount = executionCount;
+                    }
+                    cell.isExecuting = false;
+                    if (saveOutputs) {
+                        this.saveCells(notebookPath, cells);
+                    }
+                    const success = !executionError;
+                    this.recordLogOperation(notebookPath, {
+                        type: 'event',
+                        category: 'execution',
+                        name: 'runCellComplete',
+                        target: { cellId: actualCellId, cellIndex: targetIndex },
+                        runId,
+                        data: { durationMs: finalElapsed, success },
+                        source: 'mcp',
+                    });
+                }).catch(() => { });
+                // Execution is still running
+                return {
+                    success: true,
+                    executionStatus: 'busy',
+                    cellId: actualCellId,
+                    cellIndex: targetIndex,
+                    outputs: outputs.map(o => copyCellOutput(o)),
+                    executionTime: elapsed,
+                    sessionId,
+                    queuePosition: qi?.queuePosition,
+                    queueLength: qi?.queueLength,
+                    message: `Cell still executing after ${maxWait}s. Use read_output with max_wait to poll for results.`,
+                };
+            }
+            const success = !executionError;
+            this.recordLogOperation(notebookPath, {
+                type: 'event',
+                category: 'execution',
+                name: 'runCellComplete',
+                target: { cellId: actualCellId, cellIndex: targetIndex },
+                runId,
+                data: { durationMs: elapsed, success },
+                source: 'mcp',
+            });
+            return {
+                success: true,
+                cellId: actualCellId,
+                cellIndex: targetIndex,
+                executionStatus: status,
+                executionCount,
+                outputs: outputs.map(o => copyCellOutput(o)),
+                executionTime: elapsed,
+                sessionId,
+                queuePosition: qi?.queuePosition,
+                queueLength: qi?.queueLength,
+                error: executionError || undefined,
+            };
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            return { success: false, error: `Execution failed: ${errMsg}` };
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Undo/Redo Operations
+    // -------------------------------------------------------------------------
+    /**
+     * Handle undo operation.
+     */
+    async handleUndo(notebookPath) {
+        const cells = this.getCells(notebookPath);
+        const { cells: newCells, result } = this.undoRedoManager.undo(notebookPath, cells);
+        if (result.success) {
+            this.saveCells(notebookPath, newCells);
+        }
+        return {
+            success: result.success,
+            affectedCellIds: result.affectedCellIds,
+            operationType: result.operationType,
+            error: result.error,
+            canUndo: this.undoRedoManager.canUndo(notebookPath, newCells),
+            canRedo: this.undoRedoManager.canRedo(notebookPath, newCells),
+        };
+    }
+    /**
+     * Handle redo operation.
+     */
+    async handleRedo(notebookPath) {
+        const cells = this.getCells(notebookPath);
+        const { cells: newCells, result } = this.undoRedoManager.redo(notebookPath, cells);
+        if (result.success) {
+            this.saveCells(notebookPath, newCells);
+        }
+        return {
+            success: result.success,
+            affectedCellIds: result.affectedCellIds,
+            operationType: result.operationType,
+            error: result.error,
+            canUndo: this.undoRedoManager.canUndo(notebookPath, newCells),
+            canRedo: this.undoRedoManager.canRedo(notebookPath, newCells),
+        };
+    }
+    /**
+     * Record an undoable operation (helper method for other operations).
+     */
+    recordUndoableOperation(notebookPath, op) {
+        const cells = this.getCells(notebookPath);
+        this.undoRedoManager.recordOperation(notebookPath, cells, op);
+    }
+    /**
+     * Record a non-undoable log operation (helper method for other operations).
+     */
+    recordLogOperation(notebookPath, op) {
+        const cells = this.getCells(notebookPath);
+        this.undoRedoManager.recordLogOperation(notebookPath, cells, op);
+    }
+    /**
+     * Get updates since a timestamp (public method for operation router).
+     * Used by startAgentSession to inform agent what changed between sessions.
+     */
+    getUpdatesSince(notebookPath, sinceTimestamp) {
+        const cells = this.getCells(notebookPath);
+        return this.undoRedoManager.getUpdatesSince(notebookPath, cells, sinceTimestamp);
+    }
+    // -------------------------------------------------------------------------
+    // Kernel Operations
+    // -------------------------------------------------------------------------
+    async startKernelOp(operation, notebookPath) {
+        if (!this.kernelService) {
+            return { success: false, error: 'Kernel service not available' };
+        }
+        const kernelName = operation.kernelName || 'python3';
+        try {
+            const { sessionId, created } = await this.kernelService.getOrCreateKernel(notebookPath, kernelName);
+            this.kernelService.saveNotebookKernelPreference(notebookPath, kernelName);
+            const spec = (0, kernelspec_1.getKernelSpec)(kernelName);
+            const metadataResult = await this.fsService.updateNotebookMetadata(notebookPath, {
+                kernelspec: {
+                    name: kernelName,
+                    display_name: spec?.displayName || (kernelName === 'python3' ? 'Python 3' : kernelName),
+                    language: spec?.language || 'python',
+                },
+            });
+            if (!metadataResult.success) {
+                return { success: false, error: metadataResult.error || `Failed to update kernel metadata for ${notebookPath}` };
+            }
+            if (created) {
+                this.recordLogOperation(notebookPath, {
+                    type: 'event',
+                    category: 'kernel',
+                    name: 'startKernel',
+                    data: { sessionId, kernelName },
+                    source: 'mcp',
+                });
+            }
+            return { success: true, sessionId, kernelName };
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            return { success: false, error: `Failed to start kernel: ${errMsg}` };
+        }
+    }
+    async shutdownKernelOp(notebookPath) {
+        if (!this.kernelService) {
+            return { success: false, error: 'Kernel service not available' };
+        }
+        const sessionId = this.kernelService.getSessionIdForFile(notebookPath);
+        if (!sessionId) {
+            return { success: false, error: 'No kernel session found for notebook' };
+        }
+        const success = await this.kernelService.stopKernel(sessionId);
+        if (!success) {
+            return { success: false, error: 'Failed to shutdown kernel (session not found)' };
+        }
+        this.recordLogOperation(notebookPath, {
+            type: 'event',
+            category: 'kernel',
+            name: 'shutdownKernel',
+            data: { sessionId },
+            source: 'mcp',
+        });
+        return { success: true, sessionId };
+    }
+    async restartKernelOp(notebookPath) {
+        if (!this.kernelService) {
+            return { success: false, error: 'Kernel service not available' };
+        }
+        const sessionId = this.kernelService.getSessionIdForFile(notebookPath);
+        if (!sessionId) {
+            return { success: false, error: 'No kernel session found for notebook' };
+        }
+        const success = await this.kernelService.restartKernel(sessionId);
+        if (!success) {
+            return { success: false, error: 'Failed to restart kernel (session not found)' };
+        }
+        this.recordLogOperation(notebookPath, {
+            type: 'event',
+            category: 'kernel',
+            name: 'restartKernel',
+            data: { sessionId },
+            source: 'mcp',
+        });
+        return { success: true, sessionId };
+    }
+    async interruptKernelOp(notebookPath) {
+        if (!this.kernelService) {
+            return { success: false, error: 'Kernel service not available' };
+        }
+        const sessionId = this.kernelService.getSessionIdForFile(notebookPath);
+        if (!sessionId) {
+            return { success: false, error: 'No kernel session found for notebook' };
+        }
+        const success = await this.kernelService.interruptKernel(sessionId);
+        if (!success) {
+            return { success: false, error: 'Failed to interrupt kernel (session not found)' };
+        }
+        this.recordLogOperation(notebookPath, {
+            type: 'event',
+            category: 'kernel',
+            name: 'interruptKernel',
+            data: { sessionId },
+            source: 'mcp',
+        });
+        return { success: true, sessionId };
+    }
+}
+exports.HeadlessOperationHandler = HeadlessOperationHandler;