@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/utils/errorHandling.js

@@ -0,0 +1,936 @@
+/**
+ * Robust Error Handling Utilities for NeuroLink
+ * Provides structured error management for tool execution and system operations
+ */
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { logger } from "./logger.js";
+import { CircuitBreakerOpenError } from "../types/circuitBreakerErrors.js";
+// Error codes for different scenarios
+export const ERROR_CODES = {
+    // Tool errors
+    TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+    TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+    TOOL_TIMEOUT: "TOOL_TIMEOUT",
+    TOOL_VALIDATION_FAILED: "TOOL_VALIDATION_FAILED",
+    // Parameter errors
+    INVALID_PARAMETERS: "INVALID_PARAMETERS",
+    MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM",
+    // System errors
+    MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED",
+    NETWORK_ERROR: "NETWORK_ERROR",
+    PERMISSION_DENIED: "PERMISSION_DENIED",
+    // Provider errors
+    PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE",
+    PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+    PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED",
+    // Configuration errors
+    INVALID_CONFIGURATION: "INVALID_CONFIGURATION",
+    MISSING_CONFIGURATION: "MISSING_CONFIGURATION",
+    // Video validation errors
+    INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION",
+    INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH",
+    INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO",
+    INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO",
+    INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE",
+    MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE",
+    EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT",
+    VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG",
+    // Image validation errors
+    EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH",
+    INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE",
+    IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE",
+    IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
+    INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
+    // PDF validation errors
+    PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
+    // Rate limiter errors
+    RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL",
+    RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT",
+    RATE_LIMITER_RESET: "RATE_LIMITER_RESET",
+    // PPT validation errors
+    MISSING_PPT_PROPERTIES: "MISSING_PPT_PROPERTIES",
+    INVALID_PPT_PAGES: "INVALID_PPT_PAGES",
+    INVALID_PPT_FORMAT: "INVALID_PPT_FORMAT",
+    INVALID_PPT_PROVIDER: "INVALID_PPT_PROVIDER",
+    INVALID_PPT_OUTPUT_OPTIONS: "INVALID_PPT_OUTPUT_OPTIONS",
+    INVALID_PPT_OUTPUT_PATH: "INVALID_PPT_OUTPUT_PATH",
+    INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH",
+    INVALID_PPT_MODE: "INVALID_PPT_MODE",
+    INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT",
+};
+/**
+ * Enhanced error class with structured information
+ */
+export class NeuroLinkError extends Error {
+    code;
+    category;
+    severity;
+    retriable;
+    context;
+    timestamp;
+    toolName;
+    serverId;
+    constructor(options) {
+        super(options.message);
+        this.name = "NeuroLinkError";
+        this.code = options.code;
+        this.category = options.category;
+        this.severity = options.severity;
+        this.retriable = options.retriable;
+        this.context = options.context || {};
+        this.timestamp = new Date();
+        this.toolName = options.toolName;
+        this.serverId = options.serverId;
+        // Preserve original error stack if provided
+        if (options.originalError) {
+            this.stack = options.originalError.stack;
+            this.context.originalMessage = options.originalError.message;
+        }
+    }
+    /**
+     * Convert to JSON for logging and serialization
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            category: this.category,
+            severity: this.severity,
+            retriable: this.retriable,
+            context: this.context,
+            timestamp: this.timestamp,
+            toolName: this.toolName,
+            serverId: this.serverId,
+        };
+    }
+}
+/**
+ * Error factory for common error scenarios
+ */
+export class ErrorFactory {
+    /**
+     * Create a tool not found error
+     */
+    static toolNotFound(toolName, availableTools) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.TOOL_NOT_FOUND,
+            message: `Tool '${toolName}' not found`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { toolName, availableTools },
+            toolName,
+        });
+    }
+    /**
+     * Create a tool execution failed error
+     */
+    static toolExecutionFailed(toolName, originalError, serverId) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.TOOL_EXECUTION_FAILED,
+            message: `Tool '${toolName}' execution failed: ${originalError.message}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: true,
+            originalError,
+            toolName,
+            serverId,
+        });
+    }
+    /**
+     * Create a tool timeout error
+     */
+    static toolTimeout(toolName, timeoutMs, serverId) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.TOOL_TIMEOUT,
+            message: `Tool '${toolName}' timed out after ${timeoutMs}ms`,
+            category: ErrorCategory.TIMEOUT,
+            severity: ErrorSeverity.HIGH,
+            retriable: true,
+            context: { timeoutMs },
+            toolName,
+            serverId,
+        });
+    }
+    /**
+     * Create a parameter validation error
+     */
+    static invalidParameters(toolName, validationError, providedParams) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PARAMETERS,
+            message: `Invalid parameters for tool '${toolName}': ${validationError.message}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { providedParams },
+            originalError: validationError,
+            toolName,
+        });
+    }
+    /**
+     * Create a network error
+     */
+    static networkError(toolName, originalError, serverId) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.NETWORK_ERROR,
+            message: `Network error in tool '${toolName}': ${originalError.message}`,
+            category: ErrorCategory.NETWORK,
+            severity: ErrorSeverity.HIGH,
+            retriable: true,
+            originalError,
+            toolName,
+            serverId,
+        });
+    }
+    /**
+     * Create a memory exhaustion error
+     */
+    static memoryExhausted(toolName, memoryUsageMB) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.MEMORY_EXHAUSTED,
+            message: `Memory exhausted during tool '${toolName}' execution (${memoryUsageMB}MB used)`,
+            category: ErrorCategory.RESOURCE,
+            severity: ErrorSeverity.CRITICAL,
+            retriable: false,
+            context: { memoryUsageMB },
+            toolName,
+        });
+    }
+    // ============================================================================
+    // CONFIGURATION ERRORS
+    // ============================================================================
+    /**
+     * Create a missing configuration error (e.g., missing API key)
+     */
+    static missingConfiguration(configName, context) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.MISSING_CONFIGURATION,
+            message: `Missing required configuration: ${configName}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: context || {},
+        });
+    }
+    /**
+     * Create an invalid configuration error (e.g., NaN for numeric values)
+     */
+    static invalidConfiguration(configName, reason, context) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_CONFIGURATION,
+            message: `Invalid configuration for '${configName}': ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: context || {},
+        });
+    }
+    // ============================================================================
+    // VIDEO VALIDATION ERRORS
+    // ============================================================================
+    /**
+     * Create an invalid video resolution error
+     */
+    static invalidVideoResolution(resolution) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_RESOLUTION,
+            message: `Invalid resolution '${resolution}'. Use '720p' or '1080p'`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.resolution",
+                providedValue: resolution,
+                suggestions: ["Use '720p' for standard HD", "Use '1080p' for full HD"],
+            },
+        });
+    }
+    /**
+     * Create an invalid video length error
+     */
+    static invalidVideoLength(length) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_LENGTH,
+            message: `Invalid length '${length}'. Use 4, 6, or 8 seconds`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.length",
+                providedValue: length,
+                suggestions: [
+                    "Use 4 for short clips",
+                    "Use 6 for balanced duration (recommended)",
+                    "Use 8 for longer videos",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid video aspect ratio error
+     */
+    static invalidVideoAspectRatio(aspectRatio) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_ASPECT_RATIO,
+            message: `Invalid aspect ratio '${aspectRatio}'. Use '9:16' or '16:9'`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.aspectRatio",
+                providedValue: aspectRatio,
+                suggestions: [
+                    "Use '9:16' for portrait/vertical video",
+                    "Use '16:9' for landscape",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid video audio option error
+     */
+    static invalidVideoAudio(audio) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_AUDIO,
+            message: `Invalid audio option '${audio}'. Must be true or false`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.video.audio",
+                providedValue: audio,
+                suggestions: [
+                    "Set audio: true to enable audio generation",
+                    "Set audio: false to disable",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid video mode error
+     */
+    static invalidVideoMode() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_VIDEO_MODE,
+            message: "Video generation requires output.mode to be 'video'",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.mode",
+                suggestions: ["Set output: { mode: 'video' } for video generation"],
+            },
+        });
+    }
+    /**
+     * Create a missing video image error
+     */
+    static missingVideoImage() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.MISSING_VIDEO_IMAGE,
+            message: "Video generation requires an input image",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: [
+                    "Provide an image via input.images array",
+                    "Example: input: { text: 'prompt', images: [imageBuffer] }",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an empty video prompt error
+     */
+    static emptyVideoPrompt() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.EMPTY_VIDEO_PROMPT,
+            message: "Video prompt cannot be empty",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.text",
+                suggestions: [
+                    "Provide a text prompt describing the desired video motion/content",
+                    "Example: 'Smooth camera pan with dramatic lighting'",
+                ],
+            },
+        });
+    }
+    /**
+     * Create a video prompt too long error
+     */
+    static videoPromptTooLong(length, maxLength) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.VIDEO_PROMPT_TOO_LONG,
+            message: `Video prompt must be ${maxLength} characters or less (got ${length})`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.text",
+                providedLength: length,
+                maxLength,
+                suggestions: [
+                    `Shorten your prompt to ${maxLength} characters or less`,
+                    "Focus on key visual elements and camera motion",
+                ],
+            },
+        });
+    }
+    // ============================================================================
+    // IMAGE VALIDATION ERRORS
+    // ============================================================================
+    /**
+     * Create an empty image path error
+     */
+    static emptyImagePath() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.EMPTY_IMAGE_PATH,
+            message: "Image path or URL cannot be empty",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: ["Provide a valid file path or URL"],
+            },
+        });
+    }
+    /**
+     * Create an invalid image type error
+     */
+    static invalidImageType() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_IMAGE_TYPE,
+            message: "Image must be a Buffer, file path string, or URL",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: [
+                    "Provide image as Buffer: fs.readFileSync('image.jpg')",
+                    "Or as file path string: './image.jpg'",
+                    "Or as URL: 'https://example.com/image.jpg'",
+                ],
+            },
+        });
+    }
+    // ============================================================================
+    // PDF VALIDATION ERRORS
+    // ============================================================================
+    /**
+     * Create a PDF page limit exceeded error
+     */
+    static pdfPageLimitExceeded(estimatedPages, maxPages, provider) {
+        const alternatives = [
+            `Split the PDF into smaller files (max ${maxPages} pages each)`,
+            "Extract only the pages you need using a PDF editor",
+            "For large files, consider Google AI Studio which supports up to 2000MB file size (though page limits still apply)",
+            "Convert specific pages to images manually before processing",
+            "Bypass this limit with { enforceLimits: false } (not recommended - may cause API errors or unexpected costs)",
+        ];
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_PAGE_LIMIT_EXCEEDED,
+            message: `PDF page limit exceeded: ${estimatedPages} pages detected, but ${provider} supports maximum ${maxPages} pages.\n\n` +
+                `Alternatives:\n` +
+                alternatives.map((alt, i) => `${i + 1}. ${alt}`).join("\n"),
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                estimatedPages,
+                maxPages,
+                provider,
+                alternatives,
+            },
+        });
+    }
+    /**
+     * Create an image too large error
+     */
+    static imageTooLarge(sizeMB, maxMB) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.IMAGE_TOO_LARGE,
+            message: `Image size (${sizeMB}MB) exceeds maximum (${maxMB}MB)`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                sizeMB,
+                maxMB,
+                suggestions: [
+                    `Compress or resize the image to under ${maxMB}MB`,
+                    "Use a lower quality JPEG compression",
+                    "Reduce image dimensions",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an image too small error
+     */
+    static imageTooSmall() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.IMAGE_TOO_SMALL,
+            message: "Image data is too small to be a valid image file",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: ["Provide a valid JPEG, PNG, or WebP image file"],
+            },
+        });
+    }
+    /**
+     * Create an invalid image format error
+     */
+    static invalidImageFormat() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_IMAGE_FORMAT,
+            message: "Unsupported image format. Use JPEG, PNG, or WebP",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                suggestions: [
+                    "Convert your image to JPEG, PNG, or WebP format",
+                    "Ensure the file is not corrupted",
+                    "Check that the file extension matches the actual format",
+                ],
+            },
+        });
+    }
+    // ============================================================================
+    // RATE LIMITER ERRORS
+    // ============================================================================
+    /**
+     * Create a rate limiter queue full error
+     */
+    static rateLimiterQueueFull(maxQueueSize) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.RATE_LIMITER_QUEUE_FULL,
+            message: `Rate limiter queue full: too many pending requests (${maxQueueSize} max)`,
+            category: ErrorCategory.RESOURCE,
+            severity: ErrorSeverity.HIGH,
+            retriable: true,
+            context: { maxQueueSize },
+        });
+    }
+    /**
+     * Create a rate limiter queue timeout error
+     */
+    static rateLimiterQueueTimeout(timeoutMs) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.RATE_LIMITER_QUEUE_TIMEOUT,
+            message: `Rate limiter queue timeout: request exceeded ${timeoutMs}ms wait time`,
+            category: ErrorCategory.TIMEOUT,
+            severity: ErrorSeverity.HIGH,
+            retriable: true,
+            context: { timeoutMs },
+        });
+    }
+    /**
+     * Create a rate limiter reset error
+     */
+    static rateLimiterReset() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.RATE_LIMITER_RESET,
+            message: "Rate limiter was reset while request was pending",
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: true,
+            context: {},
+        });
+    }
+    // ============================================================================
+    // PPT VALIDATION ERRORS
+    // ============================================================================
+    /**
+     * Create a generic missing PPT property error
+     */
+    static missingPPTProperty(field, suggestions) {
+        const defaultSuggestions = [`Provide the required '${field}' field`];
+        return new NeuroLinkError({
+            code: ERROR_CODES.MISSING_PPT_PROPERTIES,
+            message: `PPT generation requires '${field}' field`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field,
+                suggestions: suggestions || defaultSuggestions,
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT pages error
+     */
+    static invalidPPTPages(pages, reason) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_PAGES,
+            message: `Invalid pages value '${pages}': ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.ppt.pages",
+                providedValue: pages,
+                suggestions: [
+                    "Use a number between 5 and 50",
+                    "For longer presentations, consider breaking into multiple decks",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT format error
+     */
+    static invalidPPTFormat(format) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_FORMAT,
+            message: `Invalid format '${format}'. Only 'pptx' is supported`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.ppt.format",
+                providedValue: format,
+                suggestions: ["Use format: 'pptx' or omit (defaults to 'pptx')"],
+            },
+        });
+    }
+    /**
+     * Create a generic invalid PPT output options error
+     */
+    static invalidPPTOutputOptions(field, value, validOptions) {
+        const suggestions = validOptions
+            ? validOptions.map((opt) => `Use '${opt}'`)
+            : ["Check the documentation for valid options"];
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_OUTPUT_OPTIONS,
+            message: `Invalid ${field} value '${value}'`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: `output.ppt.${field}`,
+                providedValue: value,
+                suggestions,
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT output path error
+     */
+    static invalidPPTOutputPath(path, reason) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_OUTPUT_PATH,
+            message: `Invalid outputPath '${path}': ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.ppt.outputPath",
+                providedValue: path,
+                suggestions: [
+                    "Provide a valid file path string",
+                    "Example: './presentations/my-deck.pptx'",
+                    "Omit to use auto-generated path",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT mode error
+     */
+    static invalidPPTMode() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_MODE,
+            message: "Presentation generation requires output.mode to be 'ppt'",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.mode",
+                suggestions: [
+                    "Set output: { mode: 'ppt' } for presentation generation",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT prompt error
+     */
+    static invalidPPTPrompt(reason) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_PROMPT,
+            message: `Invalid PPT prompt: ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.text",
+                suggestions: [
+                    "Provide a non-empty text prompt",
+                    "Keep the prompt under 1000 characters",
+                    "Focus on key topics and structure for the presentation",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT logo path error
+     */
+    static invalidPPTLogoPath(path, reason) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_LOGO_PATH,
+            message: `Invalid logoPath '${path}': ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "output.ppt.logoPath",
+                providedValue: path,
+                suggestions: [
+                    "Provide a valid file path string",
+                    "Example: './assets/logo.png'",
+                    "Omit to skip logo inclusion",
+                ],
+            },
+        });
+    }
+    /**
+     * Create an invalid PPT provider error
+     */
+    static invalidPPTProvider(provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_PPT_PROVIDER,
+            message: `Invalid provider '${provider}' for PPT generation. Supported providers: vertex, openai, azure, anthropic, google-ai, bedrock`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "provider",
+                providedValue: provider,
+                suggestions: [
+                    "Use 'vertex' for Google Vertex AI (Gemini)",
+                    "Use 'openai' for OpenAI GPT models",
+                    "Use 'azure' for Azure OpenAI",
+                    "Use 'anthropic' for Anthropic Claude models",
+                    "Use 'google-ai' for Google AI Studio (Gemini)",
+                    "Use 'bedrock' for AWS Bedrock (Claude, Llama, Nova, etc.)",
+                ],
+            },
+        });
+    }
+}
+/**
+ * Timeout wrapper for async operations
+ */
+export async function withTimeout(promise, timeoutMs, timeoutError) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(timeoutError || new Error(`Operation timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]);
+}
+/**
+ * Retry mechanism for retriable operations
+ */
+export async function withRetry(operation, options) {
+    const { maxAttempts, delayMs, isRetriable = () => true, onRetry } = options;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Don't retry on the last attempt or if error is not retriable
+            if (attempt === maxAttempts || !isRetriable(lastError)) {
+                throw lastError;
+            }
+            if (onRetry) {
+                onRetry(attempt, lastError);
+            }
+            // Wait before retry
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    if (lastError) {
+        throw lastError;
+    }
+    throw new Error("Retry operation failed with no error information");
+}
+/**
+ * Circuit breaker for preventing cascading failures
+ */
+export class CircuitBreaker {
+    failureThreshold;
+    resetTimeoutMs;
+    failures = 0;
+    lastFailureTime = 0;
+    state = "closed";
+    name;
+    constructor(failureThreshold = 5, resetTimeoutMs = 60000, name = "tool-execution") {
+        this.failureThreshold = failureThreshold;
+        this.resetTimeoutMs = resetTimeoutMs;
+        this.name = name;
+    }
+    async execute(operation) {
+        if (this.state === "open") {
+            const retryAfterMs = this.resetTimeoutMs - (Date.now() - this.lastFailureTime);
+            if (retryAfterMs > 0) {
+                throw new CircuitBreakerOpenError({
+                    breakerName: this.name,
+                    retryAfter: new Date(this.lastFailureTime + this.resetTimeoutMs),
+                    retryAfterMs,
+                    breakerState: "open",
+                    failureCount: this.failures,
+                });
+            }
+            this.state = "half-open";
+        }
+        try {
+            const result = await operation();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    onSuccess() {
+        this.failures = 0;
+        this.state = "closed";
+    }
+    onFailure() {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        if (this.failures >= this.failureThreshold) {
+            this.state = "open";
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    getFailureCount() {
+        return this.failures;
+    }
+}
+/**
+ * Detect AbortError from any source (DOMException, plain Error, or message-based).
+ * Used to short-circuit retry/fallback loops when an abort signal fires.
+ *
+ * Uses `includes()` for message checks because provider error handlers
+ * (e.g., googleVertex.formatProviderError) wrap the original AbortError
+ * in a formatted error like "❌ Provider Error\n\nThis operation was aborted\n\n..."
+ * which destroys the exact message match.
+ */
+export function isAbortError(error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+        return true;
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+        return true;
+    }
+    if (error instanceof Error &&
+        (error.message?.includes("This operation was aborted") ||
+            error.message?.includes("The operation was aborted") ||
+            error.message?.includes("The user aborted a request"))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Error handler that decides whether to retry based on error type
+ */
+export function isRetriableError(error) {
+    if (error instanceof NeuroLinkError) {
+        return error.retriable;
+    }
+    // Check for common retriable error patterns
+    const retriablePatterns = [
+        /timeout/i,
+        /network/i,
+        /connection/i,
+        /temporary/i,
+        /rate limit/i,
+        /quota/i,
+        /503/i, // Service unavailable
+        /502/i, // Bad gateway
+        /504/i, // Gateway timeout
+    ];
+    return retriablePatterns.some((pattern) => pattern.test(error.message));
+}
+/**
+ * Determines if an error is likely recoverable (rate limit, timeout, network issues).
+ * Useful for deciding whether to retry or fail fast.
+ */
+export function isRecoverableError(error) {
+    // Check NeuroLinkError.retriable first
+    const errorWithRetriable = error;
+    if ("retriable" in error &&
+        typeof errorWithRetriable.retriable === "boolean") {
+        return errorWithRetriable.retriable;
+    }
+    const message = error.message?.toLowerCase() || "";
+    // Rate limit errors
+    if (message.includes("rate limit") || message.includes("too many requests")) {
+        return true;
+    }
+    if (/\b429\b/.test(message)) {
+        return true;
+    }
+    // Timeout errors
+    if (message.includes("timeout") ||
+        message.includes("etimedout") ||
+        message.includes("timed out")) {
+        return true;
+    }
+    // Network errors
+    if (message.includes("econnreset") ||
+        message.includes("econnrefused") ||
+        message.includes("network") ||
+        message.includes("socket")) {
+        return true;
+    }
+    // Server errors (use word boundaries to avoid false matches)
+    if (/\b50[0234]\b/.test(message)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Enhanced error logger that provides structured logging
+ */
+export function logStructuredError(error, context) {
+    const logData = {
+        ...error.toJSON(),
+        ...context,
+    };
+    switch (error.severity) {
+        case ErrorSeverity.CRITICAL:
+            logger.error(`[CRITICAL] ${error.message}`, logData);
+            break;
+        case ErrorSeverity.HIGH:
+            logger.error(`[HIGH] ${error.message}`, logData);
+            break;
+        case ErrorSeverity.MEDIUM:
+            logger.warn(`[MEDIUM] ${error.message}`, logData);
+            break;
+        case ErrorSeverity.LOW:
+            logger.info(`[LOW] ${error.message}`, logData);
+            break;
+    }
+}