sub-agents-mcp 0.1.2

package/dist/execution/ExecutionLimits.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * Execution limits configuration and enforcement for agent execution.
+ *
+ * Provides configurable limits for resource usage including memory, concurrency,
+ * execution time, and output size to ensure system stability and prevent abuse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionLimits = exports.DEFAULT_EXECUTION_LIMITS = void 0;
+const ErrorHandler_1 = require("../utils/ErrorHandler");
+/**
+ * Default execution limits configuration.
+ */
+exports.DEFAULT_EXECUTION_LIMITS = {
+    maxConcurrentExecutions: 5,
+    maxMemoryUsageMB: 100,
+    maxOutputSizeBytes: 1024 * 1024, // 1MB
+    maxExecutionTimeMs: 90000, // 90 seconds
+    enableResourceMonitoring: true,
+};
+/**
+ * Execution limits enforcer for resource constraint management.
+ *
+ * Monitors and enforces limits on concurrent executions, memory usage,
+ * output size, and execution time to prevent resource exhaustion.
+ */
+class ExecutionLimits {
+    /**
+     * Creates a new ExecutionLimits instance.
+     *
+     * @param config - Execution limits configuration (uses defaults if not provided)
+     */
+    constructor(config = {}) {
+        this.activeExecutions = new Set();
+        this.config = { ...exports.DEFAULT_EXECUTION_LIMITS, ...config };
+    }
+    /**
+     * Checks if a new execution can be started within limits.
+     *
+     * @param executionId - Unique identifier for the execution
+     * @throws {ResourceLimitError} When concurrent execution limit is exceeded
+     */
+    checkConcurrencyLimit(executionId) {
+        if (this.activeExecutions.size >= this.config.maxConcurrentExecutions) {
+            throw new ErrorHandler_1.ResourceLimitError(`Maximum concurrent executions exceeded: ${this.config.maxConcurrentExecutions}`, 'CONCURRENCY_LIMIT_EXCEEDED', 'concurrency', this.config.maxConcurrentExecutions, {
+                operation: 'concurrency_check',
+                metadata: { executionId, currentCount: this.activeExecutions.size },
+            });
+        }
+    }
+    /**
+     * Registers a new execution as active.
+     *
+     * @param executionId - Unique identifier for the execution
+     */
+    registerExecution(executionId) {
+        this.checkConcurrencyLimit(executionId);
+        this.activeExecutions.add(executionId);
+    }
+    /**
+     * Unregisters an execution as completed.
+     *
+     * @param executionId - Unique identifier for the execution
+     */
+    unregisterExecution(executionId) {
+        this.activeExecutions.delete(executionId);
+    }
+    /**
+     * Checks if memory usage is within limits.
+     *
+     * @param memoryUsageMB - Current memory usage in MB
+     * @throws {ResourceLimitError} When memory limit is exceeded
+     */
+    checkMemoryLimit(memoryUsageMB) {
+        if (memoryUsageMB > this.config.maxMemoryUsageMB) {
+            throw new ErrorHandler_1.ResourceLimitError(`Memory usage exceeded: ${memoryUsageMB}MB > ${this.config.maxMemoryUsageMB}MB`, 'MEMORY_LIMIT_EXCEEDED', 'memory', this.config.maxMemoryUsageMB);
+        }
+    }
+    /**
+     * Checks if output size is within limits.
+     *
+     * @param outputSizeBytes - Current output size in bytes
+     * @throws {ResourceLimitError} When output size limit is exceeded
+     */
+    checkOutputSizeLimit(outputSizeBytes) {
+        if (outputSizeBytes > this.config.maxOutputSizeBytes) {
+            throw new ErrorHandler_1.ResourceLimitError(`Output size exceeded: ${outputSizeBytes} bytes > ${this.config.maxOutputSizeBytes} bytes`, 'OUTPUT_SIZE_LIMIT_EXCEEDED', 'output_size', this.config.maxOutputSizeBytes);
+        }
+    }
+    /**
+     * Gets current resource usage statistics.
+     *
+     * @param currentMemoryMB - Current memory usage in MB
+     * @param currentOutputBytes - Current output size in bytes
+     * @param executionTimeMs - Current execution time in milliseconds
+     * @returns Resource usage statistics
+     */
+    getResourceUsage(currentMemoryMB = 0, currentOutputBytes = 0, executionTimeMs = 0) {
+        return {
+            memoryUsageMB: currentMemoryMB,
+            activeExecutions: this.activeExecutions.size,
+            outputSizeBytes: currentOutputBytes,
+            executionTimeMs,
+        };
+    }
+    /**
+     * Gets the current configuration.
+     *
+     * @returns Execution limits configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Gets the number of active executions.
+     *
+     * @returns Number of active executions
+     */
+    getActiveExecutionCount() {
+        return this.activeExecutions.size;
+    }
+    /**
+     * Checks if resource monitoring is enabled.
+     *
+     * @returns True if resource monitoring is enabled
+     */
+    isResourceMonitoringEnabled() {
+        return this.config.enableResourceMonitoring;
+    }
+    /**
+     * Gets adaptive resource limits based on current system state.
+     *
+     * @param systemMemoryMB - Current available system memory in MB
+     * @param systemLoad - Current system load (0-1)
+     * @returns Adjusted execution limits configuration
+     */
+    getAdaptiveLimits(systemMemoryMB, systemLoad = 0.5) {
+        const baseLimits = this.getConfig();
+        // Adjust limits based on available system resources
+        const memoryMultiplier = Math.min(systemMemoryMB / 1000, 2); // Scale up to 2x for high memory systems
+        const loadMultiplier = Math.max(1 - systemLoad, 0.3); // Reduce limits under high load
+        return {
+            ...baseLimits,
+            maxConcurrentExecutions: Math.max(Math.floor(baseLimits.maxConcurrentExecutions * loadMultiplier), 1),
+            maxMemoryUsageMB: Math.floor(baseLimits.maxMemoryUsageMB * memoryMultiplier),
+            maxExecutionTimeMs: systemLoad > 0.8
+                ? Math.floor(baseLimits.maxExecutionTimeMs * 1.5) // More time under high load
+                : baseLimits.maxExecutionTimeMs,
+        };
+    }
+    /**
+     * Monitors resource usage and suggests optimizations.
+     *
+     * @param currentUsage - Current resource usage
+     * @returns Resource optimization suggestions
+     */
+    analyzeResourceUsage(currentUsage) {
+        const config = this.getConfig();
+        const recommendations = [];
+        let severity = 'low';
+        let shouldThrottle = false;
+        // Analyze concurrency
+        const concurrencyUtilization = currentUsage.activeExecutions / config.maxConcurrentExecutions;
+        if (concurrencyUtilization > 0.8) {
+            recommendations.push('High concurrency utilization detected - consider queuing new requests');
+            severity = 'medium';
+            shouldThrottle = true;
+        }
+        // Analyze memory usage
+        const memoryUtilization = currentUsage.memoryUsageMB / config.maxMemoryUsageMB;
+        if (memoryUtilization > 0.9) {
+            recommendations.push('Memory usage approaching limit - consider reducing concurrent executions');
+            severity = 'high';
+            shouldThrottle = true;
+        }
+        else if (memoryUtilization > 0.7) {
+            recommendations.push('Memory usage elevated - monitor closely');
+            if (severity === 'low')
+                severity = 'medium';
+        }
+        // Analyze output size trends
+        const outputUtilization = currentUsage.outputSizeBytes / config.maxOutputSizeBytes;
+        if (outputUtilization > 0.8) {
+            recommendations.push('Output size approaching limit - consider using spawn method for large outputs');
+            if (severity === 'low')
+                severity = 'medium';
+        }
+        // Analyze execution time
+        if (currentUsage.executionTimeMs > config.maxExecutionTimeMs * 0.8) {
+            recommendations.push('Execution time approaching timeout - consider optimizing agent performance');
+            if (severity === 'low')
+                severity = 'medium';
+        }
+        return {
+            recommendations,
+            severity,
+            shouldThrottle,
+        };
+    }
+    /**
+     * Creates execution limits optimized for specific operation types.
+     *
+     * @param operationType - Type of operation (light, standard, heavy)
+     * @returns Optimized execution limits configuration
+     */
+    createOptimizedConfig(operationType) {
+        const baseLimits = exports.DEFAULT_EXECUTION_LIMITS;
+        switch (operationType) {
+            case 'light':
+                return {
+                    ...baseLimits,
+                    maxConcurrentExecutions: baseLimits.maxConcurrentExecutions * 2,
+                    maxMemoryUsageMB: baseLimits.maxMemoryUsageMB * 0.5,
+                    maxExecutionTimeMs: baseLimits.maxExecutionTimeMs * 0.5,
+                    maxOutputSizeBytes: baseLimits.maxOutputSizeBytes * 0.5,
+                };
+            case 'heavy':
+                return {
+                    ...baseLimits,
+                    maxConcurrentExecutions: Math.max(baseLimits.maxConcurrentExecutions * 0.5, 1),
+                    maxMemoryUsageMB: baseLimits.maxMemoryUsageMB * 2,
+                    maxExecutionTimeMs: baseLimits.maxExecutionTimeMs * 2,
+                    maxOutputSizeBytes: baseLimits.maxOutputSizeBytes * 2,
+                };
+            default: // standard
+                return baseLimits;
+        }
+    }
+}
+exports.ExecutionLimits = ExecutionLimits;
+//# sourceMappingURL=ExecutionLimits.js.map

package/dist/execution/ExecutionLimits.js.map

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

package/dist/execution/McpRequestTimeout.d.ts

@@ -0,0 +1,166 @@
+import { Logger } from '../utils/Logger';
+/**
+ * Configuration for MCP request timeout management
+ * Following MCP specification recommendations for handling long-running LLM operations
+ */
+export interface McpTimeoutConfig {
+    /**
+     * Default timeout for MCP requests in milliseconds
+     * Considering LLM processing characteristics, set to 2 minutes by default
+     */
+    defaultTimeoutMs: number;
+    /**
+     * Maximum absolute timeout in milliseconds
+     * Prevents infinite waiting even with progress updates (5 minutes by default)
+     */
+    maxTimeoutMs: number;
+    /**
+     * Whether to reset timeout when progress notification is received
+     * Recommended by MCP specification for long-running operations
+     */
+    progressResetEnabled: boolean;
+    /**
+     * Warning threshold in milliseconds
+     * Sends progress notification to improve UX (1 minute by default)
+     */
+    warningThresholdMs: number;
+    /**
+     * Enable debug logging for timeout operations
+     */
+    enableDebugLogging: boolean;
+}
+/**
+ * Default timeout configuration for MCP requests
+ * Based on MCP best practices and LLM operation characteristics
+ */
+export declare const DEFAULT_MCP_TIMEOUT_CONFIG: McpTimeoutConfig;
+/**
+ * Progress notification data for MCP requests
+ */
+export interface ProgressNotification {
+    requestId: string;
+    message: string;
+    percentage?: number;
+    timestamp: number;
+}
+/**
+ * Timeout context for tracking request execution
+ */
+export interface TimeoutContext {
+    requestId: string;
+    startTime: number;
+    currentTimeout: NodeJS.Timeout | null;
+    warningTimeout: NodeJS.Timeout | null;
+    maxTimeout: NodeJS.Timeout | null;
+    progressCount: number;
+    lastProgressTime: number;
+    isCompleted: boolean;
+    isCancelled: boolean;
+    onTimeout?: TimeoutCallback;
+    onProgress?: ProgressCallback;
+}
+/**
+ * Callback for handling timeout events
+ */
+export type TimeoutCallback = (context: TimeoutContext) => void;
+/**
+ * Callback for sending progress notifications
+ */
+export type ProgressCallback = (notification: ProgressNotification) => void;
+/**
+ * McpRequestTimeout manages timeout behavior for MCP server requests
+ * Implements MCP specification recommendations for handling long-running operations
+ *
+ * This class handles AI -> MCP level timeouts, separate from MCP -> AI (AgentExecutor) timeouts
+ * Following MCP best practices:
+ * - Progressive timeout with reset on progress
+ * - Maximum absolute timeout enforcement
+ * - Progress notifications for better UX
+ * - Graceful cancellation support
+ */
+export declare class McpRequestTimeout {
+    private readonly config;
+    private readonly logger;
+    private readonly contexts;
+    /**
+     * Creates a new McpRequestTimeout instance
+     *
+     * @param config - Optional timeout configuration
+     * @param logger - Optional logger instance
+     */
+    constructor(config?: Partial<McpTimeoutConfig>, logger?: Logger);
+    /**
+     * Start timeout tracking for a request
+     *
+     * @param requestId - Unique request identifier
+     * @param onTimeout - Callback when timeout occurs
+     * @param onProgress - Optional callback for progress notifications
+     * @returns TimeoutContext for the request
+     */
+    startTimeout(requestId: string, onTimeout: TimeoutCallback, onProgress?: ProgressCallback): TimeoutContext;
+    /**
+     * Report progress and optionally reset timeout
+     * Following MCP specification: MAY reset timeout on progress, but enforce maximum
+     *
+     * @param requestId - Request identifier
+     * @param message - Progress message
+     * @param percentage - Optional completion percentage
+     */
+    reportProgress(requestId: string, message: string, percentage?: number): void;
+    /**
+     * Mark request as completed and clear timeouts
+     *
+     * @param requestId - Request identifier
+     */
+    complete(requestId: string): void;
+    /**
+     * Cancel request and clear timeouts
+     * Following MCP specification for cancellation
+     *
+     * @param requestId - Request identifier
+     * @param reason - Cancellation reason
+     */
+    cancel(requestId: string, reason: string): void;
+    /**
+     * Clear timeout for a request
+     *
+     * @param requestId - Request identifier
+     */
+    clearTimeout(requestId: string): void;
+    /**
+     * Check if request has timed out
+     *
+     * @param requestId - Request identifier
+     * @returns true if timed out
+     */
+    hasTimedOut(requestId: string): boolean;
+    /**
+     * Get timeout statistics for monitoring
+     *
+     * @returns Current timeout statistics
+     */
+    getStats(): {
+        activeRequests: number;
+        averageProgressCount: number;
+        longestRunningMs: number;
+    };
+    /**
+     * Handle timeout event
+     *
+     * @private
+     */
+    private handleTimeout;
+    /**
+     * Send progress notification
+     *
+     * @private
+     */
+    private sendProgressNotification;
+    /**
+     * Clear all timeouts for a context
+     *
+     * @private
+     */
+    private clearTimeouts;
+}
+//# sourceMappingURL=McpRequestTimeout.d.ts.map

package/dist/execution/McpRequestTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpRequestTimeout.d.ts","sourceRoot":"","sources":["../../src/execution/McpRequestTimeout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAA;IAE7B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAA;IAE1B;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAMxC,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IACrC,cAAc,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IACrC,UAAU,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;AAE/D;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,YAAY,EAAE,oBAAoB,KAAK,IAAI,CAAA;AAE3E;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;IAK/D;;;;;;;OAOG;IACH,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,eAAe,EAC1B,UAAU,CAAC,EAAE,gBAAgB,GAC5B,cAAc;IA+DjB;;;;;;;OAOG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IA4C7E;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAmBjC;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAkB/C;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAUvC;;;;OAIG;IACH,QAAQ,IAAI;QACV,cAAc,EAAE,MAAM,CAAA;QACtB,oBAAoB,EAAE,MAAM,CAAA;QAC5B,gBAAgB,EAAE,MAAM,CAAA;KACzB;IAoBD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;;OAIG;IACH,OAAO,CAAC,aAAa;CActB"}

package/dist/execution/McpRequestTimeout.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpRequestTimeout = exports.DEFAULT_MCP_TIMEOUT_CONFIG = void 0;
+const Logger_1 = require("../utils/Logger");
+/**
+ * Default timeout configuration for MCP requests
+ * Based on MCP best practices and LLM operation characteristics
+ */
+exports.DEFAULT_MCP_TIMEOUT_CONFIG = {
+    defaultTimeoutMs: 360000, // 6 minutes - considering complex agent operations
+    maxTimeoutMs: 660000, // 11 minutes - absolute maximum for AI->MCP
+    progressResetEnabled: true,
+    warningThresholdMs: 60000, // 1 minute - send progress notification
+    enableDebugLogging: false,
+};
+/**
+ * McpRequestTimeout manages timeout behavior for MCP server requests
+ * Implements MCP specification recommendations for handling long-running operations
+ *
+ * This class handles AI -> MCP level timeouts, separate from MCP -> AI (AgentExecutor) timeouts
+ * Following MCP best practices:
+ * - Progressive timeout with reset on progress
+ * - Maximum absolute timeout enforcement
+ * - Progress notifications for better UX
+ * - Graceful cancellation support
+ */
+class McpRequestTimeout {
+    /**
+     * Creates a new McpRequestTimeout instance
+     *
+     * @param config - Optional timeout configuration
+     * @param logger - Optional logger instance
+     */
+    constructor(config, logger) {
+        this.contexts = new Map();
+        this.config = { ...exports.DEFAULT_MCP_TIMEOUT_CONFIG, ...config };
+        this.logger = logger || new Logger_1.Logger(process.env['LOG_LEVEL'] || 'info');
+    }
+    /**
+     * Start timeout tracking for a request
+     *
+     * @param requestId - Unique request identifier
+     * @param onTimeout - Callback when timeout occurs
+     * @param onProgress - Optional callback for progress notifications
+     * @returns TimeoutContext for the request
+     */
+    startTimeout(requestId, onTimeout, onProgress) {
+        // Clear any existing timeout for this request
+        this.clearTimeout(requestId);
+        const context = {
+            requestId,
+            startTime: Date.now(),
+            currentTimeout: null,
+            warningTimeout: null,
+            maxTimeout: null,
+            progressCount: 0,
+            lastProgressTime: Date.now(),
+            isCompleted: false,
+            isCancelled: false,
+            onTimeout,
+            ...(onProgress && { onProgress }),
+        };
+        // Set warning timeout (for progress notification)
+        if (onProgress && this.config.warningThresholdMs > 0) {
+            context.warningTimeout = setTimeout(() => {
+                if (!context.isCompleted && !context.isCancelled) {
+                    this.sendProgressNotification(context, onProgress, 'Processing is taking longer than expected');
+                }
+            }, this.config.warningThresholdMs);
+        }
+        // Set default timeout
+        context.currentTimeout = setTimeout(() => {
+            if (!context.isCompleted && !context.isCancelled) {
+                this.handleTimeout(context, onTimeout);
+            }
+        }, this.config.defaultTimeoutMs);
+        // Set maximum absolute timeout (cannot be reset)
+        context.maxTimeout = setTimeout(() => {
+            if (!context.isCompleted && !context.isCancelled) {
+                this.logger.warn('Maximum timeout reached, forcing termination', {
+                    requestId,
+                    elapsedMs: Date.now() - context.startTime,
+                    maxTimeoutMs: this.config.maxTimeoutMs,
+                });
+                this.handleTimeout(context, onTimeout);
+            }
+        }, this.config.maxTimeoutMs);
+        this.contexts.set(requestId, context);
+        if (this.config.enableDebugLogging) {
+            this.logger.debug('Timeout tracking started', {
+                requestId,
+                defaultTimeoutMs: this.config.defaultTimeoutMs,
+                maxTimeoutMs: this.config.maxTimeoutMs,
+            });
+        }
+        return context;
+    }
+    /**
+     * Report progress and optionally reset timeout
+     * Following MCP specification: MAY reset timeout on progress, but enforce maximum
+     *
+     * @param requestId - Request identifier
+     * @param message - Progress message
+     * @param percentage - Optional completion percentage
+     */
+    reportProgress(requestId, message, percentage) {
+        const context = this.contexts.get(requestId);
+        if (!context || context.isCompleted || context.isCancelled) {
+            return;
+        }
+        context.progressCount++;
+        context.lastProgressTime = Date.now();
+        if (this.config.enableDebugLogging) {
+            this.logger.debug('Progress reported', {
+                requestId,
+                message,
+                percentage,
+                progressCount: context.progressCount,
+                elapsedMs: Date.now() - context.startTime,
+            });
+        }
+        // Reset timeout if enabled (but maximum timeout remains)
+        if (this.config.progressResetEnabled && context.currentTimeout) {
+            clearTimeout(context.currentTimeout);
+            // Calculate remaining time before max timeout
+            const elapsedMs = Date.now() - context.startTime;
+            const remainingMs = this.config.maxTimeoutMs - elapsedMs;
+            const newTimeoutMs = Math.min(this.config.defaultTimeoutMs, remainingMs);
+            if (newTimeoutMs > 0 && context.onTimeout) {
+                context.currentTimeout = setTimeout(() => {
+                    if (!context.isCompleted && !context.isCancelled) {
+                        this.handleTimeout(context, context.onTimeout);
+                    }
+                }, newTimeoutMs);
+                this.logger.info('Timeout reset due to progress', {
+                    requestId,
+                    newTimeoutMs,
+                    remainingBeforeMaxMs: remainingMs,
+                });
+            }
+        }
+    }
+    /**
+     * Mark request as completed and clear timeouts
+     *
+     * @param requestId - Request identifier
+     */
+    complete(requestId) {
+        const context = this.contexts.get(requestId);
+        if (!context) {
+            return;
+        }
+        context.isCompleted = true;
+        this.clearTimeouts(context);
+        const totalTime = Date.now() - context.startTime;
+        this.logger.info('Request completed within timeout', {
+            requestId,
+            totalTimeMs: totalTime,
+            progressCount: context.progressCount,
+        });
+        this.contexts.delete(requestId);
+    }
+    /**
+     * Cancel request and clear timeouts
+     * Following MCP specification for cancellation
+     *
+     * @param requestId - Request identifier
+     * @param reason - Cancellation reason
+     */
+    cancel(requestId, reason) {
+        const context = this.contexts.get(requestId);
+        if (!context) {
+            return;
+        }
+        context.isCancelled = true;
+        this.clearTimeouts(context);
+        this.logger.info('Request cancelled', {
+            requestId,
+            reason,
+            elapsedMs: Date.now() - context.startTime,
+        });
+        this.contexts.delete(requestId);
+    }
+    /**
+     * Clear timeout for a request
+     *
+     * @param requestId - Request identifier
+     */
+    clearTimeout(requestId) {
+        const context = this.contexts.get(requestId);
+        if (context) {
+            this.clearTimeouts(context);
+            this.contexts.delete(requestId);
+        }
+    }
+    /**
+     * Check if request has timed out
+     *
+     * @param requestId - Request identifier
+     * @returns true if timed out
+     */
+    hasTimedOut(requestId) {
+        const context = this.contexts.get(requestId);
+        if (!context) {
+            return false;
+        }
+        const elapsedMs = Date.now() - context.startTime;
+        return elapsedMs >= this.config.maxTimeoutMs;
+    }
+    /**
+     * Get timeout statistics for monitoring
+     *
+     * @returns Current timeout statistics
+     */
+    getStats() {
+        const activeContexts = Array.from(this.contexts.values()).filter((c) => !c.isCompleted && !c.isCancelled);
+        const now = Date.now();
+        const longestRunningMs = activeContexts.reduce((max, c) => Math.max(max, now - c.startTime), 0);
+        const averageProgressCount = activeContexts.length > 0
+            ? activeContexts.reduce((sum, c) => sum + c.progressCount, 0) / activeContexts.length
+            : 0;
+        return {
+            activeRequests: activeContexts.length,
+            averageProgressCount,
+            longestRunningMs,
+        };
+    }
+    /**
+     * Handle timeout event
+     *
+     * @private
+     */
+    handleTimeout(context, onTimeout) {
+        const elapsedMs = Date.now() - context.startTime;
+        this.logger.warn('Request timeout occurred', {
+            requestId: context.requestId,
+            elapsedMs,
+            progressCount: context.progressCount,
+            lastProgressMs: Date.now() - context.lastProgressTime,
+        });
+        onTimeout(context);
+        this.clearTimeouts(context);
+    }
+    /**
+     * Send progress notification
+     *
+     * @private
+     */
+    sendProgressNotification(context, onProgress, message) {
+        const notification = {
+            requestId: context.requestId,
+            message,
+            timestamp: Date.now(),
+        };
+        onProgress(notification);
+    }
+    /**
+     * Clear all timeouts for a context
+     *
+     * @private
+     */
+    clearTimeouts(context) {
+        if (context.currentTimeout) {
+            clearTimeout(context.currentTimeout);
+            context.currentTimeout = null;
+        }
+        if (context.warningTimeout) {
+            clearTimeout(context.warningTimeout);
+            context.warningTimeout = null;
+        }
+        if (context.maxTimeout) {
+            clearTimeout(context.maxTimeout);
+            context.maxTimeout = null;
+        }
+    }
+}
+exports.McpRequestTimeout = McpRequestTimeout;
+//# sourceMappingURL=McpRequestTimeout.js.map