@juspay/neurolink 7.33.2 → 7.33.4

package/dist/constants/retry.js

@@ -0,0 +1,266 @@
+/**
+ * Retry and Circuit Breaker Constants for NeuroLink
+ *
+ * Centralized retry configuration to replace magic numbers throughout the codebase.
+ * Includes retry attempts, delays, backoff strategies, and circuit breaker settings.
+ *
+ * @fileoverview Retry and resilience constants for robust error handling
+ * @author NeuroLink Team
+ * @version 1.0.0
+ */
+/**
+ * Retry attempt configuration
+ * Balanced for reliability vs performance across different operation types
+ */
+export const RETRY_ATTEMPTS = {
+    /** Default retry attempts for most operations */
+    DEFAULT: 3, // 3 attempts - Balance reliability vs speed
+    /** Critical operations that must succeed */
+    CRITICAL: 5, // 5 attempts - High-importance operations
+    /** Quick operations that should fail fast */
+    QUICK: 2, // 2 attempts - Fast operations, minimal retry
+    /** Network operations prone to transient failures */
+    NETWORK: 4, // 4 attempts - Network operations
+    /** Authentication operations */
+    AUTH: 2, // 2 attempts - Auth should fail fast for security
+    /** Database operations */
+    DATABASE: 3, // 3 attempts - Standard DB operations
+    /** File I/O operations */
+    FILE_IO: 2, // 2 attempts - File operations
+};
+/**
+ * Retry delay configuration
+ * Configured to prevent overwhelming services while providing quick recovery
+ */
+export const RETRY_DELAYS = {
+    /** Base delay for exponential backoff */
+    BASE_MS: 1000, // 1s - Starting delay
+    /** Minimum delay between retries */
+    MIN_MS: 500, // 500ms - Minimum wait time
+    /** Maximum delay between retries */
+    MAX_MS: 30000, // 30s - Maximum wait time
+    /** Quick retry delay for fast operations */
+    QUICK_MS: 200, // 200ms - Fast retry for quick operations
+    /** Network operation base delay */
+    NETWORK_BASE_MS: 2000, // 2s - Network-specific base delay
+    /** Authentication delay (security consideration) */
+    AUTH_MS: 3000, // 3s - Auth retry delay for security
+};
+/**
+ * Exponential backoff configuration
+ * Controls how delays increase with each retry attempt
+ */
+export const BACKOFF_CONFIG = {
+    /** Standard exponential multiplier */
+    MULTIPLIER: 2, // 2x - Standard exponential backoff
+    /** Conservative multiplier for sensitive operations */
+    CONSERVATIVE_MULTIPLIER: 1.5, // 1.5x - Gentler backoff
+    /** Aggressive multiplier for operations that should back off quickly */
+    AGGRESSIVE_MULTIPLIER: 3, // 3x - Rapid backoff
+    /** Jitter factor to prevent thundering herd */
+    JITTER_FACTOR: 0.1, // 10% - Random jitter
+    /** Maximum jitter amount in milliseconds */
+    MAX_JITTER_MS: 1000, // 1s - Cap on random jitter
+};
+/**
+ * Circuit breaker configuration
+ * Prevents cascading failures and provides automatic recovery
+ */
+export const CIRCUIT_BREAKER = {
+    /** Failure threshold before opening circuit */
+    FAILURE_THRESHOLD: 5, // 5 failures - Balance sensitivity vs stability
+    /** Success threshold for closing circuit from half-open */
+    SUCCESS_THRESHOLD: 3, // 3 successes - Confirm recovery
+    /** Minimum calls before calculating failure rate */
+    MIN_CALLS: 10, // 10 calls - Statistical significance
+    /** Failure rate threshold (0.0 to 1.0) */
+    FAILURE_RATE_THRESHOLD: 0.5, // 50% - Failure rate to open circuit
+    /** Monitoring window for failure tracking */
+    MONITORING_WINDOW_MS: 300000, // 5m - Sliding window for statistics
+    /** Half-open max calls for testing recovery */
+    HALF_OPEN_MAX_CALLS: 3, // 3 calls - Limited test calls
+};
+/**
+ * Provider-specific retry configuration
+ * Different providers may need different retry strategies
+ */
+export const PROVIDER_RETRY = {
+    /** OpenAI retry configuration */
+    OPENAI: {
+        maxAttempts: RETRY_ATTEMPTS.DEFAULT,
+        baseDelay: RETRY_DELAYS.BASE_MS,
+        maxDelay: RETRY_DELAYS.MAX_MS,
+        multiplier: BACKOFF_CONFIG.MULTIPLIER,
+    },
+    /** Anthropic retry configuration */
+    ANTHROPIC: {
+        maxAttempts: RETRY_ATTEMPTS.DEFAULT,
+        baseDelay: RETRY_DELAYS.BASE_MS,
+        maxDelay: RETRY_DELAYS.MAX_MS,
+        multiplier: BACKOFF_CONFIG.CONSERVATIVE_MULTIPLIER, // More conservative
+    },
+    /** Google (Vertex/Google AI) retry configuration */
+    GOOGLE: {
+        maxAttempts: RETRY_ATTEMPTS.NETWORK,
+        baseDelay: RETRY_DELAYS.NETWORK_BASE_MS,
+        maxDelay: RETRY_DELAYS.MAX_MS,
+        multiplier: BACKOFF_CONFIG.MULTIPLIER,
+    },
+    /** AWS Bedrock retry configuration */
+    BEDROCK: {
+        maxAttempts: RETRY_ATTEMPTS.CRITICAL,
+        baseDelay: RETRY_DELAYS.BASE_MS,
+        maxDelay: RETRY_DELAYS.MAX_MS,
+        multiplier: BACKOFF_CONFIG.CONSERVATIVE_MULTIPLIER,
+    },
+    /** Azure OpenAI retry configuration */
+    AZURE: {
+        maxAttempts: RETRY_ATTEMPTS.DEFAULT,
+        baseDelay: RETRY_DELAYS.BASE_MS,
+        maxDelay: RETRY_DELAYS.MAX_MS,
+        multiplier: BACKOFF_CONFIG.MULTIPLIER,
+    },
+    /** Ollama retry configuration (local service) */
+    OLLAMA: {
+        maxAttempts: RETRY_ATTEMPTS.QUICK,
+        baseDelay: RETRY_DELAYS.QUICK_MS,
+        maxDelay: 5000, // 5s max for local service
+        multiplier: BACKOFF_CONFIG.CONSERVATIVE_MULTIPLIER,
+    },
+};
+/**
+ * Operation-specific retry configuration
+ * Different operations may require different retry strategies
+ */
+export const OPERATION_RETRY = {
+    /** Tool execution retry config */
+    TOOL_EXECUTION: {
+        maxAttempts: RETRY_ATTEMPTS.DEFAULT,
+        baseDelay: RETRY_DELAYS.BASE_MS,
+        circuitBreaker: true,
+    },
+    /** MCP operation retry config */
+    MCP_OPERATION: {
+        maxAttempts: RETRY_ATTEMPTS.QUICK,
+        baseDelay: RETRY_DELAYS.QUICK_MS,
+        circuitBreaker: false, // MCP operations are usually fast
+    },
+    /** Network request retry config */
+    NETWORK_REQUEST: {
+        maxAttempts: RETRY_ATTEMPTS.NETWORK,
+        baseDelay: RETRY_DELAYS.NETWORK_BASE_MS,
+        circuitBreaker: true,
+    },
+    /** Database operation retry config */
+    DATABASE_OPERATION: {
+        maxAttempts: RETRY_ATTEMPTS.DATABASE,
+        baseDelay: RETRY_DELAYS.BASE_MS,
+        circuitBreaker: true,
+    },
+    /** Authentication retry config */
+    AUTHENTICATION: {
+        maxAttempts: RETRY_ATTEMPTS.AUTH,
+        baseDelay: RETRY_DELAYS.AUTH_MS,
+        circuitBreaker: false, // Don't circuit break auth for security
+    },
+};
+/**
+ * Retry utility functions
+ */
+export const RetryUtils = {
+    /**
+     * Calculate exponential backoff delay
+     * @param attempt - Current attempt number (0-based)
+     * @param baseDelay - Base delay in milliseconds
+     * @param multiplier - Exponential multiplier
+     * @param maxDelay - Maximum delay cap
+     * @param jitter - Whether to add random jitter
+     * @returns Calculated delay in milliseconds
+     */
+    calculateBackoffDelay: (attempt, baseDelay = RETRY_DELAYS.BASE_MS, multiplier = BACKOFF_CONFIG.MULTIPLIER, maxDelay = RETRY_DELAYS.MAX_MS, jitter = true) => {
+        const safeAttempt = Math.max(0, attempt);
+        const base = Math.max(baseDelay, RETRY_DELAYS.MIN_MS);
+        const delay = Math.min(base * Math.pow(multiplier, safeAttempt), maxDelay);
+        if (!jitter) {
+            return delay;
+        }
+        const jitterCap = Math.min(BACKOFF_CONFIG.MAX_JITTER_MS, delay * BACKOFF_CONFIG.JITTER_FACTOR);
+        return Math.min(maxDelay, Math.floor(delay + Math.random() * jitterCap));
+    },
+    /**
+     * Check if an error is retriable
+     * @param error - The error to check
+     * @returns True if the error should be retried
+     */
+    isRetriableError: (error) => {
+        if (!error) {
+            return false;
+        }
+        const err = error;
+        // Network/system codes
+        const code = typeof err?.code === "string" ? err.code : undefined;
+        if (code &&
+            ["ENOTFOUND", "ECONNRESET", "ETIMEDOUT", "ECONNREFUSED"].includes(code)) {
+            return true;
+        }
+        // HTTP status
+        const status = typeof err?.status === "number"
+            ? err.status
+            : typeof err?.statusCode === "number"
+                ? err.statusCode
+                : undefined;
+        if (typeof status === "number" &&
+            (status >= 500 || status === 429 || status === 408)) {
+            return true;
+        }
+        // Messages
+        const msg = typeof err?.message === "string" ? err.message.toLowerCase() : "";
+        if (msg.includes("rate limit") ||
+            msg.includes("quota") ||
+            msg.includes("throttle")) {
+            return true;
+        }
+        if (msg.includes("timeout")) {
+            return true;
+        }
+        return false;
+    },
+    /**
+     * Get retry configuration for a specific provider
+     * @param provider - Provider name
+     * @returns Retry configuration object
+     */
+    getProviderRetryConfig: (provider) => {
+        const normalizedProvider = provider.toLowerCase().replace(/[-_]/g, "");
+        switch (normalizedProvider) {
+            case "openai":
+                return PROVIDER_RETRY.OPENAI;
+            case "anthropic":
+                return PROVIDER_RETRY.ANTHROPIC;
+            case "googleai":
+            case "vertex":
+                return PROVIDER_RETRY.GOOGLE;
+            case "bedrock":
+                return PROVIDER_RETRY.BEDROCK;
+            case "azure":
+                return PROVIDER_RETRY.AZURE;
+            case "ollama":
+                return PROVIDER_RETRY.OLLAMA;
+            default:
+                return {
+                    maxAttempts: RETRY_ATTEMPTS.DEFAULT,
+                    baseDelay: RETRY_DELAYS.BASE_MS,
+                    maxDelay: RETRY_DELAYS.MAX_MS,
+                    multiplier: BACKOFF_CONFIG.MULTIPLIER,
+                };
+        }
+    },
+};
+// Legacy compatibility exports
+export const DEFAULT_RETRY_ATTEMPTS = RETRY_ATTEMPTS.DEFAULT;
+export const DEFAULT_INITIAL_DELAY = RETRY_DELAYS.BASE_MS;
+export const DEFAULT_MAX_DELAY = RETRY_DELAYS.MAX_MS;
+export const DEFAULT_BACKOFF_MULTIPLIER = BACKOFF_CONFIG.MULTIPLIER;
+export const CIRCUIT_BREAKER_FAILURE_THRESHOLD = CIRCUIT_BREAKER.FAILURE_THRESHOLD;
+// Single source of truth: re-export from timeouts
+export { CIRCUIT_BREAKER_RESET_MS } from "./timeouts.js";

package/dist/constants/timeouts.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Timeout Constants for NeuroLink
+ *
+ * Centralized timeout configuration to replace magic numbers throughout the codebase.
+ * Each timeout value includes business justification and use case documentation.
+ *
+ * @fileoverview Timeout constants organized by functional area
+ * @author NeuroLink Team
+ * @version 1.0.0
+ */
+/**
+ * Tool execution timeout constants
+ * These values balance reliability vs performance for AI tool operations
+ */
+export declare const TOOL_TIMEOUTS: {
+    /** Default timeout for AI tool execution - handles most complex operations */
+    readonly EXECUTION_DEFAULT_MS: 30000;
+    /** Fast timeout for simple tools that should complete quickly */
+    readonly EXECUTION_FAST_MS: 5000;
+    /** Extended timeout for complex analysis operations */
+    readonly EXECUTION_COMPLEX_MS: 60000;
+    /** Ultra-long timeout for batch operations */
+    readonly EXECUTION_BATCH_MS: 120000;
+};
+/**
+ * Provider connectivity and health check timeouts
+ * Tuned for quick health checks while allowing for network latency
+ */
+export declare const PROVIDER_TIMEOUTS: {
+    /** Quick provider health check - should fail fast */
+    readonly TEST_MS: 5000;
+    /** Provider connection establishment timeout */
+    readonly CONNECTION_MS: 10000;
+    /** Authentication validation timeout */
+    readonly AUTH_MS: 3000;
+    /** Model availability check timeout */
+    readonly MODEL_CHECK_MS: 8000;
+    /** Provider capability discovery timeout */
+    readonly CAPABILITY_DISCOVERY_MS: 15000;
+};
+/**
+ * MCP (Model Context Protocol) system timeouts
+ * Balanced for reliable MCP server communication
+ */
+export declare const MCP_TIMEOUTS: {
+    /** MCP server initialization timeout */
+    readonly INITIALIZATION_MS: 3000;
+    /** Tool discovery timeout per server */
+    readonly TOOL_DISCOVERY_MS: 10000;
+    /** MCP client connection timeout */
+    readonly CLIENT_CONNECTION_MS: 5000;
+    /** External MCP server startup timeout */
+    readonly EXTERNAL_SERVER_STARTUP_MS: 15000;
+    /** MCP server shutdown timeout */
+    readonly SHUTDOWN_MS: 5000;
+};
+/**
+ * Circuit breaker timeout configuration
+ * Prevents cascading failures while allowing recovery
+ */
+export declare const CIRCUIT_BREAKER_TIMEOUTS: {
+    /** Circuit breaker reset timeout - how long to wait before retry */
+    readonly RESET_MS: 60000;
+    /** Half-open state timeout - trial period for recovery */
+    readonly HALF_OPEN_MS: 30000;
+    /** Monitoring window for failure rate calculation */
+    readonly MONITORING_WINDOW_MS: 300000;
+};
+/**
+ * Network operation timeouts
+ * Configured for various network conditions and use cases
+ */
+export declare const NETWORK_TIMEOUTS: {
+    /** Standard network request timeout */
+    readonly REQUEST_MS: 15000;
+    /** Quick connectivity check timeout */
+    readonly QUICK_CHECK_MS: 2000;
+    /** File download/upload timeout per MB */
+    readonly TRANSFER_PER_MB_MS: 1000;
+    /** DNS resolution timeout */
+    readonly DNS_RESOLUTION_MS: 3000;
+    /** WebSocket connection timeout */
+    readonly WEBSOCKET_CONNECTION_MS: 10000;
+};
+/**
+ * System operation timeouts
+ * For application lifecycle and resource management
+ */
+export declare const SYSTEM_TIMEOUTS: {
+    /** Application graceful shutdown timeout */
+    readonly GRACEFUL_SHUTDOWN_MS: 30000;
+    /** Resource cleanup timeout */
+    readonly CLEANUP_OPERATION_MS: 5000;
+    /** Cache flush timeout */
+    readonly CACHE_FLUSH_MS: 3000;
+    /** Health check interval */
+    readonly HEALTH_CHECK_INTERVAL_MS: 30000;
+    /** Metrics collection timeout */
+    readonly METRICS_COLLECTION_MS: 1000;
+};
+/**
+ * Development and testing timeouts
+ * Separate timeouts for development vs production environments
+ */
+export declare const DEV_TIMEOUTS: {
+    /** Extended timeout for debugging */
+    readonly DEBUG_EXTENDED_MS: 300000;
+    /** Unit test timeout */
+    readonly UNIT_TEST_MS: 10000;
+    /** Integration test timeout */
+    readonly INTEGRATION_TEST_MS: 60000;
+    /** Mock service response delay */
+    readonly MOCK_DELAY_MS: 100;
+};
+/**
+ * Combined timeout constants for easy access
+ * Exports all timeout categories in a single object
+ */
+export declare const TIMEOUTS: {
+    readonly TOOL: {
+        /** Default timeout for AI tool execution - handles most complex operations */
+        readonly EXECUTION_DEFAULT_MS: 30000;
+        /** Fast timeout for simple tools that should complete quickly */
+        readonly EXECUTION_FAST_MS: 5000;
+        /** Extended timeout for complex analysis operations */
+        readonly EXECUTION_COMPLEX_MS: 60000;
+        /** Ultra-long timeout for batch operations */
+        readonly EXECUTION_BATCH_MS: 120000;
+    };
+    readonly PROVIDER: {
+        /** Quick provider health check - should fail fast */
+        readonly TEST_MS: 5000;
+        /** Provider connection establishment timeout */
+        readonly CONNECTION_MS: 10000;
+        /** Authentication validation timeout */
+        readonly AUTH_MS: 3000;
+        /** Model availability check timeout */
+        readonly MODEL_CHECK_MS: 8000;
+        /** Provider capability discovery timeout */
+        readonly CAPABILITY_DISCOVERY_MS: 15000;
+    };
+    readonly MCP: {
+        /** MCP server initialization timeout */
+        readonly INITIALIZATION_MS: 3000;
+        /** Tool discovery timeout per server */
+        readonly TOOL_DISCOVERY_MS: 10000;
+        /** MCP client connection timeout */
+        readonly CLIENT_CONNECTION_MS: 5000;
+        /** External MCP server startup timeout */
+        readonly EXTERNAL_SERVER_STARTUP_MS: 15000;
+        /** MCP server shutdown timeout */
+        readonly SHUTDOWN_MS: 5000;
+    };
+    readonly CIRCUIT_BREAKER: {
+        /** Circuit breaker reset timeout - how long to wait before retry */
+        readonly RESET_MS: 60000;
+        /** Half-open state timeout - trial period for recovery */
+        readonly HALF_OPEN_MS: 30000;
+        /** Monitoring window for failure rate calculation */
+        readonly MONITORING_WINDOW_MS: 300000;
+    };
+    readonly NETWORK: {
+        /** Standard network request timeout */
+        readonly REQUEST_MS: 15000;
+        /** Quick connectivity check timeout */
+        readonly QUICK_CHECK_MS: 2000;
+        /** File download/upload timeout per MB */
+        readonly TRANSFER_PER_MB_MS: 1000;
+        /** DNS resolution timeout */
+        readonly DNS_RESOLUTION_MS: 3000;
+        /** WebSocket connection timeout */
+        readonly WEBSOCKET_CONNECTION_MS: 10000;
+    };
+    readonly SYSTEM: {
+        /** Application graceful shutdown timeout */
+        readonly GRACEFUL_SHUTDOWN_MS: 30000;
+        /** Resource cleanup timeout */
+        readonly CLEANUP_OPERATION_MS: 5000;
+        /** Cache flush timeout */
+        readonly CACHE_FLUSH_MS: 3000;
+        /** Health check interval */
+        readonly HEALTH_CHECK_INTERVAL_MS: 30000;
+        /** Metrics collection timeout */
+        readonly METRICS_COLLECTION_MS: 1000;
+    };
+    readonly DEV: {
+        /** Extended timeout for debugging */
+        readonly DEBUG_EXTENDED_MS: 300000;
+        /** Unit test timeout */
+        readonly UNIT_TEST_MS: 10000;
+        /** Integration test timeout */
+        readonly INTEGRATION_TEST_MS: 60000;
+        /** Mock service response delay */
+        readonly MOCK_DELAY_MS: 100;
+    };
+};
+/**
+ * Timeout utility functions
+ */
+export declare const TimeoutUtils: {
+    /**
+     * Get environment-adjusted timeout
+     * @param baseTimeout - Base timeout value in milliseconds
+     * @param environment - Target environment (development gets 2x timeout)
+     * @returns Adjusted timeout value
+     */
+    readonly getEnvironmentTimeout: (baseTimeout: number, environment?: string | undefined) => number;
+    /**
+     * Get timeout with jitter to prevent thundering herd
+     * @param baseTimeout - Base timeout value
+     * @param jitterFactor - Jitter factor (0.1 = 10% random variation)
+     * @returns Timeout with random jitter applied
+     */
+    readonly getTimeoutWithJitter: (baseTimeout: number, jitterFactor?: number) => number;
+    /**
+     * Parse timeout string to milliseconds
+     * @param timeout - Timeout string like "30s", "2m", "1h" or number
+     * @returns Timeout in milliseconds
+     */
+    readonly parseTimeout: (timeout: string | number) => number;
+};
+export declare const DEFAULT_TIMEOUT: 30000;
+export declare const PROVIDER_TEST_TIMEOUT: 5000;
+export declare const MCP_INIT_TIMEOUT: 3000;
+export declare const CIRCUIT_BREAKER_RESET_MS: 60000;

package/dist/constants/timeouts.js

@@ -0,0 +1,182 @@
+/**
+ * Timeout Constants for NeuroLink
+ *
+ * Centralized timeout configuration to replace magic numbers throughout the codebase.
+ * Each timeout value includes business justification and use case documentation.
+ *
+ * @fileoverview Timeout constants organized by functional area
+ * @author NeuroLink Team
+ * @version 1.0.0
+ */
+/**
+ * Tool execution timeout constants
+ * These values balance reliability vs performance for AI tool operations
+ */
+export const TOOL_TIMEOUTS = {
+    /** Default timeout for AI tool execution - handles most complex operations */
+    EXECUTION_DEFAULT_MS: 30000, // 30s - Complex AI tool operations requiring LLM calls
+    /** Fast timeout for simple tools that should complete quickly */
+    EXECUTION_FAST_MS: 5000, // 5s - Simple tool operations (calculations, lookups)
+    /** Extended timeout for complex analysis operations */
+    EXECUTION_COMPLEX_MS: 60000, // 60s - Complex analysis, multiple API calls
+    /** Ultra-long timeout for batch operations */
+    EXECUTION_BATCH_MS: 120000, // 2m - Batch processing, large data operations
+};
+/**
+ * Provider connectivity and health check timeouts
+ * Tuned for quick health checks while allowing for network latency
+ */
+export const PROVIDER_TIMEOUTS = {
+    /** Quick provider health check - should fail fast */
+    TEST_MS: 5000, // 5s - Provider health check ping
+    /** Provider connection establishment timeout */
+    CONNECTION_MS: 10000, // 10s - Initial connection setup
+    /** Authentication validation timeout */
+    AUTH_MS: 3000, // 3s - API key validation
+    /** Model availability check timeout */
+    MODEL_CHECK_MS: 8000, // 8s - Model existence/availability check
+    /** Provider capability discovery timeout */
+    CAPABILITY_DISCOVERY_MS: 15000, // 15s - Feature discovery and validation
+};
+/**
+ * MCP (Model Context Protocol) system timeouts
+ * Balanced for reliable MCP server communication
+ */
+export const MCP_TIMEOUTS = {
+    /** MCP server initialization timeout */
+    INITIALIZATION_MS: 3000, // 3s - MCP server startup
+    /** Tool discovery timeout per server */
+    TOOL_DISCOVERY_MS: 10000, // 10s - Tool enumeration from MCP server
+    /** MCP client connection timeout */
+    CLIENT_CONNECTION_MS: 5000, // 5s - Client connection establishment
+    /** External MCP server startup timeout */
+    EXTERNAL_SERVER_STARTUP_MS: 15000, // 15s - External process startup
+    /** MCP server shutdown timeout */
+    SHUTDOWN_MS: 5000, // 5s - Graceful server shutdown
+};
+/**
+ * Circuit breaker timeout configuration
+ * Prevents cascading failures while allowing recovery
+ */
+export const CIRCUIT_BREAKER_TIMEOUTS = {
+    /** Circuit breaker reset timeout - how long to wait before retry */
+    RESET_MS: 60000, // 60s - Circuit breaker reset time
+    /** Half-open state timeout - trial period for recovery */
+    HALF_OPEN_MS: 30000, // 30s - Half-open state timeout
+    /** Monitoring window for failure rate calculation */
+    MONITORING_WINDOW_MS: 300000, // 5m - Sliding window for failure tracking
+};
+/**
+ * Network operation timeouts
+ * Configured for various network conditions and use cases
+ */
+export const NETWORK_TIMEOUTS = {
+    /** Standard network request timeout */
+    REQUEST_MS: 15000, // 15s - Standard HTTP requests
+    /** Quick connectivity check timeout */
+    QUICK_CHECK_MS: 2000, // 2s - Fast network availability check
+    /** File download/upload timeout per MB */
+    TRANSFER_PER_MB_MS: 1000, // 1s per MB - File transfer operations
+    /** DNS resolution timeout */
+    DNS_RESOLUTION_MS: 3000, // 3s - DNS lookup timeout
+    /** WebSocket connection timeout */
+    WEBSOCKET_CONNECTION_MS: 10000, // 10s - WebSocket handshake
+};
+/**
+ * System operation timeouts
+ * For application lifecycle and resource management
+ */
+export const SYSTEM_TIMEOUTS = {
+    /** Application graceful shutdown timeout */
+    GRACEFUL_SHUTDOWN_MS: 30000, // 30s - Complete application shutdown
+    /** Resource cleanup timeout */
+    CLEANUP_OPERATION_MS: 5000, // 5s - Memory/resource cleanup
+    /** Cache flush timeout */
+    CACHE_FLUSH_MS: 3000, // 3s - Cache clearing operations
+    /** Health check interval */
+    HEALTH_CHECK_INTERVAL_MS: 30000, // 30s - Periodic health monitoring
+    /** Metrics collection timeout */
+    METRICS_COLLECTION_MS: 1000, // 1s - Performance metrics gathering
+};
+/**
+ * Development and testing timeouts
+ * Separate timeouts for development vs production environments
+ */
+export const DEV_TIMEOUTS = {
+    /** Extended timeout for debugging */
+    DEBUG_EXTENDED_MS: 300000, // 5m - Long timeout for debugging sessions
+    /** Unit test timeout */
+    UNIT_TEST_MS: 10000, // 10s - Individual test timeout
+    /** Integration test timeout */
+    INTEGRATION_TEST_MS: 60000, // 60s - Full integration test
+    /** Mock service response delay */
+    MOCK_DELAY_MS: 100, // 100ms - Simulated service delay
+};
+/**
+ * Combined timeout constants for easy access
+ * Exports all timeout categories in a single object
+ */
+export const TIMEOUTS = {
+    TOOL: TOOL_TIMEOUTS,
+    PROVIDER: PROVIDER_TIMEOUTS,
+    MCP: MCP_TIMEOUTS,
+    CIRCUIT_BREAKER: CIRCUIT_BREAKER_TIMEOUTS,
+    NETWORK: NETWORK_TIMEOUTS,
+    SYSTEM: SYSTEM_TIMEOUTS,
+    DEV: DEV_TIMEOUTS,
+};
+/**
+ * Timeout utility functions
+ */
+export const TimeoutUtils = {
+    /**
+     * Get environment-adjusted timeout
+     * @param baseTimeout - Base timeout value in milliseconds
+     * @param environment - Target environment (development gets 2x timeout)
+     * @returns Adjusted timeout value
+     */
+    getEnvironmentTimeout: (baseTimeout, environment = process.env.NODE_ENV) => {
+        return environment === "development" ? baseTimeout * 2 : baseTimeout;
+    },
+    /**
+     * Get timeout with jitter to prevent thundering herd
+     * @param baseTimeout - Base timeout value
+     * @param jitterFactor - Jitter factor (0.1 = 10% random variation)
+     * @returns Timeout with random jitter applied
+     */
+    getTimeoutWithJitter: (baseTimeout, jitterFactor = 0.1) => {
+        const jitter = Math.random() * baseTimeout * jitterFactor;
+        return Math.floor(baseTimeout + jitter);
+    },
+    /**
+     * Parse timeout string to milliseconds
+     * @param timeout - Timeout string like "30s", "2m", "1h" or number
+     * @returns Timeout in milliseconds
+     */
+    parseTimeout: (timeout) => {
+        if (typeof timeout === "number") {
+            return timeout;
+        }
+        const match = timeout.match(/^(\d+(?:\.\d+)?)(s|m|h)?$/);
+        if (!match) {
+            throw new Error(`Invalid timeout format: ${timeout}`);
+        }
+        const value = parseFloat(match[1]);
+        const unit = match[2] || "s";
+        switch (unit) {
+            case "s":
+                return value * 1000;
+            case "m":
+                return value * 60 * 1000;
+            case "h":
+                return value * 60 * 60 * 1000;
+            default:
+                return value;
+        }
+    },
+};
+// Legacy compatibility - maintain backward compatibility
+export const DEFAULT_TIMEOUT = TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS;
+export const PROVIDER_TEST_TIMEOUT = PROVIDER_TIMEOUTS.TEST_MS;
+export const MCP_INIT_TIMEOUT = MCP_TIMEOUTS.INITIALIZATION_MS;
+export const CIRCUIT_BREAKER_RESET_MS = CIRCUIT_BREAKER_TIMEOUTS.RESET_MS;