nebula-notebook-mcp 0.1.0

package/dist/circuit-breaker.js

@@ -0,0 +1,237 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ *
+ * Prevents cascading failures by temporarily disabling requests to a failing service.
+ * When a service fails repeatedly, the circuit "opens" and subsequent requests
+ * fail immediately without attempting the operation, allowing the service time to recover.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Service is failing, requests fail immediately
+ * - HALF_OPEN: Testing if service has recovered
+ */
+import { classifyError, ErrorCategory } from './errors.js';
+/**
+ * Circuit breaker states
+ */
+export var CircuitState;
+(function (CircuitState) {
+    /** Normal operation - requests pass through */
+    CircuitState["CLOSED"] = "CLOSED";
+    /** Service is failing - requests fail immediately */
+    CircuitState["OPEN"] = "OPEN";
+    /** Testing recovery - limited requests pass through */
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+/**
+ * Circuit Breaker implementation
+ */
+export class CircuitBreaker {
+    state = CircuitState.CLOSED;
+    failures = []; // Timestamps of failures within the window
+    successCount = 0;
+    lastFailureTime = 0;
+    openedAt = 0;
+    failureThreshold;
+    resetTimeout;
+    successThreshold;
+    failureWindow;
+    tripOnCategories;
+    name;
+    listeners = [];
+    constructor(options = {}) {
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.resetTimeout = options.resetTimeout ?? 30000;
+        this.successThreshold = options.successThreshold ?? 2;
+        this.failureWindow = options.failureWindow ?? 60000;
+        this.tripOnCategories = new Set(options.tripOnCategories ?? [ErrorCategory.NETWORK, ErrorCategory.TIMEOUT, ErrorCategory.SERVER]);
+        this.name = options.name ?? 'default';
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        this.checkStateTransition();
+        return this.state;
+    }
+    /**
+     * Get circuit breaker metrics
+     */
+    getMetrics() {
+        this.checkStateTransition();
+        return {
+            state: this.state,
+            failureCount: this.getRecentFailureCount(),
+            successCount: this.successCount,
+            lastFailureTime: this.lastFailureTime,
+            openedAt: this.openedAt,
+        };
+    }
+    /**
+     * Check if the circuit allows requests
+     */
+    isAllowed() {
+        this.checkStateTransition();
+        return this.state !== CircuitState.OPEN;
+    }
+    /**
+     * Execute an operation through the circuit breaker
+     */
+    async execute(operation) {
+        this.checkStateTransition();
+        // If circuit is open, reject immediately
+        if (this.state === CircuitState.OPEN) {
+            this.emit({ type: 'request_rejected', state: this.state });
+            return {
+                success: false,
+                error: `Circuit breaker is open (${this.name}). Service temporarily unavailable.`,
+                rejectedByCircuit: true,
+            };
+        }
+        try {
+            const result = await operation();
+            this.recordSuccess();
+            return { success: true, data: result };
+        }
+        catch (error) {
+            const classified = classifyError(error);
+            this.recordFailure(classified);
+            return {
+                success: false,
+                error: classified.message,
+                rejectedByCircuit: false,
+                classifiedError: classified,
+            };
+        }
+    }
+    /**
+     * Record a successful operation
+     */
+    recordSuccess() {
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            this.emit({ type: 'success_recorded', successCount: this.successCount });
+            if (this.successCount >= this.successThreshold) {
+                this.transitionTo(CircuitState.CLOSED, 'Success threshold reached');
+            }
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // In closed state, success helps decay the failure count
+            this.emit({ type: 'success_recorded', successCount: this.successCount });
+        }
+    }
+    /**
+     * Record a failed operation
+     */
+    recordFailure(error) {
+        // Only trip on configured categories
+        if (!this.tripOnCategories.has(error.category)) {
+            return;
+        }
+        const now = Date.now();
+        this.failures.push(now);
+        this.lastFailureTime = now;
+        // Clean up old failures outside the window
+        this.failures = this.failures.filter((t) => now - t < this.failureWindow);
+        this.emit({
+            type: 'failure_recorded',
+            error,
+            failureCount: this.failures.length,
+        });
+        if (this.state === CircuitState.HALF_OPEN) {
+            // Any failure in half-open state reopens the circuit
+            this.transitionTo(CircuitState.OPEN, 'Failure in half-open state');
+        }
+        else if (this.state === CircuitState.CLOSED && this.failures.length >= this.failureThreshold) {
+            // Threshold reached in closed state
+            this.transitionTo(CircuitState.OPEN, `Failure threshold reached (${this.failures.length}/${this.failureThreshold})`);
+        }
+    }
+    /**
+     * Manually reset the circuit breaker to closed state
+     */
+    reset() {
+        this.failures = [];
+        this.successCount = 0;
+        this.lastFailureTime = 0;
+        this.openedAt = 0;
+        if (this.state !== CircuitState.CLOSED) {
+            this.transitionTo(CircuitState.CLOSED, 'Manual reset');
+        }
+    }
+    /**
+     * Force the circuit open (for testing or emergency)
+     */
+    forceOpen() {
+        if (this.state !== CircuitState.OPEN) {
+            this.transitionTo(CircuitState.OPEN, 'Forced open');
+        }
+    }
+    /**
+     * Add an event listener
+     */
+    onEvent(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== listener);
+        };
+    }
+    /**
+     * Check if state should transition based on time
+     */
+    checkStateTransition() {
+        if (this.state === CircuitState.OPEN) {
+            const now = Date.now();
+            if (now - this.openedAt >= this.resetTimeout) {
+                this.transitionTo(CircuitState.HALF_OPEN, 'Reset timeout elapsed');
+            }
+        }
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState, reason) {
+        const oldState = this.state;
+        this.state = newState;
+        if (newState === CircuitState.OPEN) {
+            this.openedAt = Date.now();
+        }
+        else if (newState === CircuitState.HALF_OPEN) {
+            this.successCount = 0;
+        }
+        else if (newState === CircuitState.CLOSED) {
+            this.failures = [];
+            this.successCount = 0;
+            this.openedAt = 0;
+        }
+        this.emit({ type: 'state_change', from: oldState, to: newState, reason });
+    }
+    /**
+     * Get count of failures within the window
+     */
+    getRecentFailureCount() {
+        const now = Date.now();
+        this.failures = this.failures.filter((t) => now - t < this.failureWindow);
+        return this.failures.length;
+    }
+    /**
+     * Emit an event to listeners
+     */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+/**
+ * Create a new circuit breaker instance
+ */
+export function createCircuitBreaker(options) {
+    return new CircuitBreaker(options);
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Error classification and handling utilities for nebula-tools
+ *
+ * Provides structured error types for better error handling and recovery strategies.
+ */
+/**
+ * Error categories for classification
+ */
+export declare enum ErrorCategory {
+    /** Network connectivity issues (connection refused, reset, DNS failures) */
+    NETWORK = "NETWORK",
+    /** Request timeout exceeded */
+    TIMEOUT = "TIMEOUT",
+    /** Server-side errors (5xx HTTP status) */
+    SERVER = "SERVER",
+    /** Client-side errors (4xx HTTP status) */
+    CLIENT = "CLIENT",
+    /** Validation errors (invalid input, out of range, etc.) */
+    VALIDATION = "VALIDATION",
+    /** Kernel-related errors (not found, crashed, busy) */
+    KERNEL = "KERNEL",
+    /** Notebook-related errors (parse failures, missing cells) */
+    NOTEBOOK = "NOTEBOOK",
+    /** Code execution errors (runtime errors, exceptions) */
+    EXECUTION = "EXECUTION",
+    /** Unknown or uncategorized errors */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Whether an error is recoverable (can be retried or has a fallback)
+ */
+export type RecoverabilityStatus = 'recoverable' | 'non-recoverable' | 'potentially-recoverable';
+/**
+ * Structured error information
+ */
+export interface ClassifiedError {
+    /** Original error message */
+    message: string;
+    /** Error category for programmatic handling */
+    category: ErrorCategory;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Whether this error can be recovered from */
+    recoverable: RecoverabilityStatus;
+    /** Whether this error should be retried */
+    retryable: boolean;
+    /** Suggested retry delay in milliseconds (if retryable) */
+    retryDelayMs?: number;
+    /** Original error for debugging */
+    originalError?: unknown;
+}
+/**
+ * Classify an error into a structured format
+ */
+export declare function classifyError(error: unknown, statusCode?: number): ClassifiedError;
+/**
+ * Extract error message from various error types
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Create a user-friendly error message from a classified error
+ */
+export declare function formatErrorMessage(error: ClassifiedError): string;
+/**
+ * Check if an error should trigger a retry
+ */
+export declare function shouldRetry(error: ClassifiedError, attemptNumber: number, maxRetries: number): boolean;
+/**
+ * Calculate retry delay with exponential backoff
+ */
+export declare function calculateRetryDelay(error: ClassifiedError, attemptNumber: number): number;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,oBAAY,aAAa;IACvB,4EAA4E;IAC5E,OAAO,YAAY;IACnB,+BAA+B;IAC/B,OAAO,YAAY;IACnB,2CAA2C;IAC3C,MAAM,WAAW;IACjB,2CAA2C;IAC3C,MAAM,WAAW;IACjB,4DAA4D;IAC5D,UAAU,eAAe;IACzB,uDAAuD;IACvD,MAAM,WAAW;IACjB,8DAA8D;IAC9D,QAAQ,aAAa;IACrB,yDAAyD;IACzD,SAAS,cAAc;IACvB,sCAAsC;IACtC,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,iBAAiB,GAAG,yBAAyB,CAAC;AAEjG;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,aAAa,CAAC;IACxB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,WAAW,EAAE,oBAAoB,CAAC;IAClC,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,eAAe,CAuGlF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWtD;AA6JD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAiBjE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAKtG;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAMzF"}

package/dist/errors.js

@@ -0,0 +1,314 @@
+/**
+ * Error classification and handling utilities for nebula-tools
+ *
+ * Provides structured error types for better error handling and recovery strategies.
+ */
+/**
+ * Error categories for classification
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** Network connectivity issues (connection refused, reset, DNS failures) */
+    ErrorCategory["NETWORK"] = "NETWORK";
+    /** Request timeout exceeded */
+    ErrorCategory["TIMEOUT"] = "TIMEOUT";
+    /** Server-side errors (5xx HTTP status) */
+    ErrorCategory["SERVER"] = "SERVER";
+    /** Client-side errors (4xx HTTP status) */
+    ErrorCategory["CLIENT"] = "CLIENT";
+    /** Validation errors (invalid input, out of range, etc.) */
+    ErrorCategory["VALIDATION"] = "VALIDATION";
+    /** Kernel-related errors (not found, crashed, busy) */
+    ErrorCategory["KERNEL"] = "KERNEL";
+    /** Notebook-related errors (parse failures, missing cells) */
+    ErrorCategory["NOTEBOOK"] = "NOTEBOOK";
+    /** Code execution errors (runtime errors, exceptions) */
+    ErrorCategory["EXECUTION"] = "EXECUTION";
+    /** Unknown or uncategorized errors */
+    ErrorCategory["UNKNOWN"] = "UNKNOWN";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Classify an error into a structured format
+ */
+export function classifyError(error, statusCode) {
+    const message = getErrorMessage(error);
+    const lowerMessage = message.toLowerCase();
+    // Priority 1: Check for AbortError (special timeout case from fetch)
+    // This takes highest priority as it's a programmatic signal
+    if (error instanceof Error && error.name === 'AbortError') {
+        return {
+            message,
+            category: ErrorCategory.TIMEOUT,
+            statusCode,
+            recoverable: 'recoverable',
+            retryable: true,
+            retryDelayMs: 1000,
+            originalError: error,
+        };
+    }
+    // Priority 2: HTTP status codes take precedence over message-based classification
+    // This ensures server responses are correctly classified
+    if (statusCode !== undefined) {
+        return classifyByStatusCode(message, statusCode, error);
+    }
+    // Priority 3: Check for timeout errors (message-based)
+    if (isTimeoutError(lowerMessage)) {
+        return {
+            message,
+            category: ErrorCategory.TIMEOUT,
+            statusCode,
+            recoverable: 'recoverable',
+            retryable: true,
+            retryDelayMs: 1000,
+            originalError: error,
+        };
+    }
+    // Priority 4: Check for network errors
+    if (isNetworkError(lowerMessage)) {
+        return {
+            message,
+            category: ErrorCategory.NETWORK,
+            statusCode,
+            recoverable: 'recoverable',
+            retryable: true,
+            retryDelayMs: 1000,
+            originalError: error,
+        };
+    }
+    // Priority 5: Check for kernel errors
+    if (isKernelError(lowerMessage)) {
+        return {
+            message,
+            category: ErrorCategory.KERNEL,
+            recoverable: isKernelRecoverable(lowerMessage) ? 'potentially-recoverable' : 'non-recoverable',
+            retryable: false,
+            originalError: error,
+        };
+    }
+    // Priority 6: Check for execution errors (before notebook to catch "in cell" context)
+    if (isExecutionError(lowerMessage)) {
+        return {
+            message,
+            category: ErrorCategory.EXECUTION,
+            recoverable: 'non-recoverable',
+            retryable: false,
+            originalError: error,
+        };
+    }
+    // Priority 7: Check for notebook errors
+    if (isNotebookError(lowerMessage)) {
+        return {
+            message,
+            category: ErrorCategory.NOTEBOOK,
+            recoverable: 'non-recoverable',
+            retryable: false,
+            originalError: error,
+        };
+    }
+    // Priority 8: Check for validation errors
+    if (isValidationError(lowerMessage)) {
+        return {
+            message,
+            category: ErrorCategory.VALIDATION,
+            recoverable: 'non-recoverable',
+            retryable: false,
+            originalError: error,
+        };
+    }
+    // Default to unknown
+    return {
+        message,
+        category: ErrorCategory.UNKNOWN,
+        statusCode,
+        recoverable: 'potentially-recoverable',
+        retryable: false,
+        originalError: error,
+    };
+}
+/**
+ * Extract error message from various error types
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Check if error message indicates a timeout error
+ */
+function isTimeoutError(lowerMessage) {
+    return lowerMessage.includes('timeout') || lowerMessage.includes('timed out');
+}
+/**
+ * Check if error is a network error
+ */
+function isNetworkError(lowerMessage) {
+    return (lowerMessage.includes('network') ||
+        lowerMessage.includes('econnrefused') ||
+        lowerMessage.includes('econnreset') ||
+        lowerMessage.includes('enotfound') ||
+        lowerMessage.includes('connection refused') ||
+        lowerMessage.includes('connection reset') ||
+        lowerMessage.includes('dns') ||
+        lowerMessage.includes('socket'));
+}
+/**
+ * Check if error is a kernel error
+ */
+function isKernelError(lowerMessage) {
+    return (lowerMessage.includes('kernel') ||
+        lowerMessage.includes('session not found') ||
+        lowerMessage.includes('session_id'));
+}
+/**
+ * Check if kernel error is potentially recoverable
+ */
+function isKernelRecoverable(lowerMessage) {
+    return (lowerMessage.includes('busy') ||
+        lowerMessage.includes('starting') ||
+        lowerMessage.includes('restarting'));
+}
+/**
+ * Check if error is a notebook error
+ */
+function isNotebookError(lowerMessage) {
+    return (lowerMessage.includes('notebook') ||
+        lowerMessage.includes('parse') ||
+        lowerMessage.includes('invalid json') ||
+        lowerMessage.includes('cell') ||
+        lowerMessage.includes('nbformat'));
+}
+/**
+ * Check if error is an execution error
+ */
+function isExecutionError(lowerMessage) {
+    return (lowerMessage.includes('execution') ||
+        lowerMessage.includes('runtime error') ||
+        lowerMessage.includes('exception') ||
+        lowerMessage.includes('traceback'));
+}
+/**
+ * Check if error is a validation error
+ */
+function isValidationError(lowerMessage) {
+    return (lowerMessage.includes('invalid') ||
+        lowerMessage.includes('out of range') ||
+        lowerMessage.includes('required') ||
+        lowerMessage.includes('missing'));
+}
+/**
+ * Classify error by HTTP status code
+ */
+function classifyByStatusCode(message, statusCode, originalError) {
+    if (statusCode >= 500) {
+        return {
+            message,
+            category: ErrorCategory.SERVER,
+            statusCode,
+            recoverable: 'recoverable',
+            retryable: true,
+            retryDelayMs: 1000 * Math.min(Math.ceil(statusCode / 100), 5),
+            originalError,
+        };
+    }
+    if (statusCode >= 400) {
+        // Specific client error handling
+        if (statusCode === 404) {
+            return {
+                message,
+                category: ErrorCategory.CLIENT,
+                statusCode,
+                recoverable: 'non-recoverable',
+                retryable: false,
+                originalError,
+            };
+        }
+        if (statusCode === 429) {
+            // Rate limiting - recoverable with backoff
+            return {
+                message,
+                category: ErrorCategory.CLIENT,
+                statusCode,
+                recoverable: 'recoverable',
+                retryable: true,
+                retryDelayMs: 5000,
+                originalError,
+            };
+        }
+        if (statusCode === 408) {
+            // Request timeout
+            return {
+                message,
+                category: ErrorCategory.TIMEOUT,
+                statusCode,
+                recoverable: 'recoverable',
+                retryable: true,
+                retryDelayMs: 1000,
+                originalError,
+            };
+        }
+        return {
+            message,
+            category: ErrorCategory.CLIENT,
+            statusCode,
+            recoverable: 'non-recoverable',
+            retryable: false,
+            originalError,
+        };
+    }
+    // Non-error status codes shouldn't reach here, but handle gracefully
+    return {
+        message,
+        category: ErrorCategory.UNKNOWN,
+        statusCode,
+        recoverable: 'potentially-recoverable',
+        retryable: false,
+        originalError,
+    };
+}
+/**
+ * Create a user-friendly error message from a classified error
+ */
+export function formatErrorMessage(error) {
+    const categoryDescriptions = {
+        [ErrorCategory.NETWORK]: 'Network error',
+        [ErrorCategory.TIMEOUT]: 'Request timed out',
+        [ErrorCategory.SERVER]: 'Server error',
+        [ErrorCategory.CLIENT]: 'Client error',
+        [ErrorCategory.VALIDATION]: 'Validation error',
+        [ErrorCategory.KERNEL]: 'Kernel error',
+        [ErrorCategory.NOTEBOOK]: 'Notebook error',
+        [ErrorCategory.EXECUTION]: 'Execution error',
+        [ErrorCategory.UNKNOWN]: 'Error',
+    };
+    const prefix = categoryDescriptions[error.category];
+    const statusSuffix = error.statusCode ? ` (${error.statusCode})` : '';
+    return `${prefix}${statusSuffix}: ${error.message}`;
+}
+/**
+ * Check if an error should trigger a retry
+ */
+export function shouldRetry(error, attemptNumber, maxRetries) {
+    if (!error.retryable) {
+        return false;
+    }
+    return attemptNumber < maxRetries;
+}
+/**
+ * Calculate retry delay with exponential backoff
+ */
+export function calculateRetryDelay(error, attemptNumber) {
+    const baseDelay = error.retryDelayMs || 1000;
+    // Exponential backoff with jitter
+    const exponentialDelay = baseDelay * Math.pow(2, attemptNumber);
+    const jitter = Math.random() * 0.3 * exponentialDelay;
+    return Math.min(exponentialDelay + jitter, 30000); // Cap at 30 seconds
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Nebula MCP tools and client library.
+ *
+ * This package is installable on the agent/client machine and talks to a
+ * running Nebula Notebook server over HTTP/WebSocket.
+ */
+export * from './types.js';
+export { classifyError, getErrorMessage, formatErrorMessage, shouldRetry, calculateRetryDelay, ErrorCategory, type ClassifiedError, type RecoverabilityStatus, } from './errors.js';
+export { CircuitBreaker, createCircuitBreaker, CircuitState, type CircuitBreakerOptions, type CircuitBreakerEvent, type CircuitBreakerListener, type CircuitBreakerResult, } from './circuit-breaker.js';
+export { NebulaClient, createNebulaClient, type NebulaClientConfig, type KernelSession, type ExecutionResult, type WriteCellResult, } from './notebook/client.js';
+export { type Tool, type ToolDefinition, type ToolResult, type MCPContent, allTools, toolsByName, toolCategories, notebookTools, kernelTools, executionTools, getToolDefinitions, executeToolByName, executeToolForMCP, getTool, hasTool, getToolNamesByCategory, readNotebookTool, readCellTool, readOutputTool, insertCellTool, updateCellTool, deleteCellTool, createNotebookTool, moveCellTool, duplicateCellTool, searchCellsTool, updateMetadataTool, listKernelsTool, kernelStartTool, kernelStopTool, kernelRestartTool, kernelInterruptTool, executeCellTool, } from './tools/index.js';
+export { readNotebookCells, writeNotebookCell, executeCell, searchNotebookCells, readCellsToolDefinition, writeCellToolDefinition, executeCellToolDefinition, searchCellsToolDefinition, type ReadCellsParams, type ReadCellsResult, type WriteCellParams, type ExecuteCellParams, type ExecuteCellResult, type SearchCellsParams, type SearchCellsResult, } from './notebook/tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,cAAc,YAAY,CAAC;AAK3B,OAAO,EACL,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AAKrB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EAGf,QAAQ,EACR,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EAGd,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,sBAAsB,EAGtB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAGlB,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EAGnB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC"}