nebula-notebook 0.1.0

package/node-server/dist/notebook/headless-handler.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Headless Operation Handler
+ *
+ * Handles notebook operations when no UI is connected to Nebula.
+ * Mirrors useOperationHandler (React) but operates on files instead of UI state.
+ */
+import { FilesystemService } from '../fs/fs-service';
+import { KernelService } from '../kernel/kernel-service';
+import { UpdateSummary } from './undoRedoManager';
+interface OperationResult {
+    success: boolean;
+    error?: string;
+    [key: string]: unknown;
+}
+interface AgentLockInfo {
+    agentId: string;
+    clientName?: string;
+    clientVersion?: string;
+    expiresAt: number;
+    lockedAt: number;
+}
+interface OperationRouterInterface {
+    startAgentSession: (path: string, agentId: string, metadata?: {
+        clientName?: string;
+        clientVersion?: string;
+    }) => {
+        success: boolean;
+        error?: string;
+        lock?: AgentLockInfo;
+    };
+    endAgentSession: (path: string, agentId: string) => {
+        success: boolean;
+        error?: string;
+    };
+}
+export declare class HeadlessOperationHandler {
+    private fsService;
+    private kernelService;
+    private operationRouter;
+    private undoRedoManager;
+    private cache;
+    private writeLocks;
+    constructor(fsService: FilesystemService, operationRouter?: OperationRouterInterface, kernelService?: KernelService);
+    /**
+     * Get notebook from cache, loading from disk if needed.
+     */
+    private getCachedNotebook;
+    private getCells;
+    private getVisibleOutputs;
+    private saveCells;
+    /**
+     * Persist dirty notebooks to disk.
+     */
+    flush(notebookPath?: string): Promise<void>;
+    private asyncPersist;
+    private schedulePersist;
+    /**
+     * Invalidate cache for a notebook.
+     */
+    invalidate(notebookPath?: string): void;
+    /**
+     * Check if notebook has unsaved changes.
+     */
+    isDirty(notebookPath: string): boolean;
+    /**
+     * Check if agent has permission to modify this notebook.
+     */
+    private checkAgentPermission;
+    /**
+     * Apply a notebook operation.
+     */
+    applyOperation(operation: Record<string, unknown>): Promise<OperationResult>;
+    /**
+     * Read notebook from cache with optional output truncation.
+     */
+    readNotebook(notebookPath: string, includeOutputs?: boolean, maxLines?: number, maxChars?: number, maxLinesError?: number, maxCharsError?: number): Promise<OperationResult>;
+    private truncateCellOutputs;
+    private truncateOutput;
+    private insertCell;
+    private deleteCell;
+    private updateContent;
+    private updateMetadata;
+    private moveCell;
+    private duplicateCell;
+    private updateOutputs;
+    private createNotebook;
+    private readCell;
+    private readCellOutput;
+    private sleep;
+    private saveOutputToTempFile;
+    private clearNotebook;
+    private deleteCells;
+    private insertCells;
+    private searchCells;
+    private clearOutputs;
+    /**
+     * Execute a cell using the kernel service.
+     * Matches Python headless_handler._execute_cell() behavior.
+     */
+    private executeCell;
+    /**
+     * Handle undo operation.
+     */
+    private handleUndo;
+    /**
+     * Handle redo operation.
+     */
+    private handleRedo;
+    /**
+     * Record an undoable operation (helper method for other operations).
+     */
+    private recordUndoableOperation;
+    /**
+     * Record a non-undoable log operation (helper method for other operations).
+     */
+    private recordLogOperation;
+    /**
+     * Get updates since a timestamp (public method for operation router).
+     * Used by startAgentSession to inform agent what changed between sessions.
+     */
+    getUpdatesSince(notebookPath: string, sinceTimestamp: number): UpdateSummary[];
+    private startKernelOp;
+    private shutdownKernelOp;
+    private restartKernelOp;
+    private interruptKernelOp;
+}
+export {};