@mxf-dev/core 2.0.5 → 3.0.0

package/src/services/ToolExecutionInterceptor.ts

@@ -29,7 +29,7 @@
  * - Prevent infinite correction loops
  */
 
-import { Observable, Subject } from 'rxjs';
+import { Observable, Subject, Subscription } from 'rxjs';
 import { Logger } from '../utils/Logger.js';
 import { EventBus } from '../events/EventBus.js';
 import { Events } from '../events/EventNames.js';
@@ -96,8 +96,13 @@ export class ToolExecutionInterceptor {
     
     // Configuration
     private config: InterceptorConfig;
-    
-    private static instance: ToolExecutionInterceptor;
+    private readonly subscriptions: Subscription[] = [];
+    private readonly pendingDelays = new Map<
+        ReturnType<typeof setTimeout>,
+        (reason?: unknown) => void
+    >();
+
+    private static instance: ToolExecutionInterceptor | undefined;
 
     private constructor() {
         this.logger = new Logger('info', 'ToolExecutionInterceptor', 'server');
@@ -340,7 +345,14 @@ export class ToolExecutionInterceptor {
      * Add delay for retry attempts
      */
     private delay(ms: number): Promise<void> {
-        return new Promise(resolve => setTimeout(resolve, ms));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingDelays.delete(timer);
+                resolve();
+            }, ms);
+            timer.unref?.();
+            this.pendingDelays.set(timer, reject);
+        });
     }
 
     /**
@@ -362,16 +374,16 @@ export class ToolExecutionInterceptor {
      */
     private setupEventListeners(): void {
         // Listen to auto-correction events for additional processing
-        this.autoCorrectionService.correctionEvents.subscribe(attempt => {
+        this.subscriptions.push(this.autoCorrectionService.correctionEvents.subscribe(_attempt => {
             if (this.config.enableLearning) {
             }
-        });
+        }));
 
         // Listen to general tool errors for monitoring
-        EventBus.server.on(Events.Mcp.TOOL_ERROR, (payload) => {
+        this.subscriptions.push(EventBus.server.on(Events.Mcp.TOOL_ERROR, (_payload) => {
             if (this.config.logAllInterceptions) {
             }
-        });
+        }));
 
     }
 
@@ -478,6 +490,25 @@ export class ToolExecutionInterceptor {
         this.activeExecutions.clear();
     }
 
+    /** Cancel pending retry delays and detach every owned subscription. */
+    public shutdown(): void {
+        for (const [timer, reject] of this.pendingDelays) {
+            clearTimeout(timer);
+            reject(new Error('Tool execution interceptor is shutting down'));
+        }
+        this.pendingDelays.clear();
+        for (const subscription of this.subscriptions) {
+            subscription.unsubscribe();
+        }
+        this.subscriptions.length = 0;
+        this.clearExecutionHistory();
+        this.interceptionEvents$.complete();
+
+        if (ToolExecutionInterceptor.instance === this) {
+            ToolExecutionInterceptor.instance = undefined;
+        }
+    }
+
     /**
      * Create a wrapped executor function that includes interception
      */
@@ -510,4 +541,4 @@ export class ToolExecutionInterceptor {
             retryCount
         };
     }
-}
+}

package/src/services/UserInputRequestManager.ts

@@ -103,10 +103,14 @@ export class UserInputRequestManager {
     private static readonly CLEANUP_INTERVAL_MS = 60 * 1000;
 
     private constructor() {
-        // Start periodic cleanup of expired requests
+        // Start periodic cleanup of expired requests. The sweep must not be what
+        // keeps the process alive: the manager is created lazily by the first
+        // forwarded user-input request, and a referenced interval here kept the
+        // server running after every shutdown step had completed.
         this.cleanupInterval = setInterval(() => {
             this.cleanupExpired();
         }, UserInputRequestManager.CLEANUP_INTERVAL_MS);
+        this.cleanupInterval.unref?.();
     }
 
     /**
@@ -119,6 +123,20 @@ export class UserInputRequestManager {
         return UserInputRequestManager.instance;
     }
 
+    /**
+     * Shut down the live manager, if one was ever created, without constructing
+     * one solely for teardown.
+     *
+     * @returns true when a manager existed and was shut down
+     */
+    public static shutdownExisting(): boolean {
+        if (!UserInputRequestManager.instance) {
+            return false;
+        }
+        UserInputRequestManager.instance.shutdown();
+        return true;
+    }
+
     /**
      * Create a new user input request and return a Promise that resolves when the user responds.
      *
@@ -187,20 +205,35 @@ export class UserInputRequestManager {
      *
      * @param requestId - The request ID to respond to
      * @param value - The user's response value
-     * @throws Error if requestId not found, request not pending, or value is invalid
+     * @param responderAgentId - Authenticated agent submitting the response
+     * @param responderChannelId - Authenticated channel of the responder
+     * @throws Error if the request is missing, outside the responder's scope,
+     *         not pending, or the value is invalid
      */
-    public submitResponse(requestId: string, value: UserInputResponseValue): void {
+    public submitResponse(
+        requestId: string,
+        value: UserInputResponseValue,
+        responderAgentId: string,
+        responderChannelId: string
+    ): void {
         const validator = createStrictValidator('UserInputRequestManager.submitResponse');
         validator.assertIsNonEmptyString(requestId, 'requestId is required');
+        validator.assertIsNonEmptyString(responderAgentId, 'responderAgentId is required');
+        validator.assertIsNonEmptyString(responderChannelId, 'responderChannelId is required');
 
         const pending = this.pendingRequests.get(requestId);
         if (!pending) {
             throw new Error(`User input request ${requestId} not found`);
         }
 
+        if (pending.request.agentId !== responderAgentId ||
+            pending.request.channelId !== responderChannelId) {
+            throw new Error('User input response is outside the authenticated agent/channel scope');
+        }
+
         if (pending.status !== 'pending') {
-            // Idempotent: duplicate responses are expected when multiple agents receive
-            // the same user_input:request broadcast and each independently emits a response.
+            // Preserve idempotence for client retries or duplicate transport
+            // delivery after the exact owner has already responded.
             logger.debug(`User input request ${requestId} is already ${pending.status}, ignoring duplicate response`);
             return;
         }
@@ -276,16 +309,28 @@ export class UserInputRequestManager {
      * @param requestId - The request ID to check
      * @returns Status info, or null if not found
      */
-    public getRequest(requestId: string): {
+    public getRequest(requestId: string, requesterAgentId: string, requesterChannelId: string): {
         status: UserInputRequestStatus;
         value?: UserInputResponseValue;
         request: UserInputRequestData;
     } | null {
+        const validator = createStrictValidator('UserInputRequestManager.getRequest');
+        validator.assertIsNonEmptyString(requestId, 'requestId is required');
+        validator.assertIsNonEmptyString(requesterAgentId, 'requesterAgentId is required');
+        validator.assertIsNonEmptyString(requesterChannelId, 'requesterChannelId is required');
+
         const pending = this.pendingRequests.get(requestId);
         if (!pending) {
             return null;
         }
 
+        // Return the same result as an unknown id so callers cannot use a
+        // leaked or guessed request id to probe another agent's prompt or value.
+        if (pending.request.agentId !== requesterAgentId ||
+            pending.request.channelId !== requesterChannelId) {
+            return null;
+        }
+
         return {
             status: pending.status,
             value: pending.responseValue,

package/src/services/UserMemoryService.ts

@@ -45,6 +45,11 @@ const MEILISEARCH_INDEX = 'mxf-user-memories';
 
 const logger = new Logger('info', 'UserMemoryService', 'server');
 
+/** Escape one string literal embedded in a Meilisearch filter expression. */
+export const escapeUserMemoryFilterLiteral = (value: string): string => (
+    value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+);
+
 // ─── Exported Interfaces ─────────────────────────────────────────────────────
 
 /** Result shape returned by recall and getSessionContext */
@@ -405,7 +410,7 @@ export class UserMemoryService {
         try {
             const client = service.getClient();
             await client.index(MEILISEARCH_INDEX).deleteDocuments({
-                filter: `userId = "${userId}"`
+                filter: `userId = "${escapeUserMemoryFilterLiteral(userId)}"`
             });
         } catch (err) {
             logger.warn('clearUserFromMeilisearch failed', err);
@@ -430,8 +435,12 @@ export class UserMemoryService {
             const client = service.getClient();
 
             // Build filter expression: always filter by userId, optionally by type
-            const filters = [`userId = "${userId}"`];
-            if (type) filters.push(`type = "${type}"`);
+            const filters = [
+                `userId = "${escapeUserMemoryFilterLiteral(userId)}"`
+            ];
+            if (type) {
+                filters.push(`type = "${escapeUserMemoryFilterLiteral(type)}"`);
+            }
             const filter = filters.join(' AND ');
 
             const result = await client.index(MEILISEARCH_INDEX).search<UserMemoryMeilisearchDoc>(

package/src/services/ValidationAnalyticsService.ts

@@ -30,6 +30,7 @@
  */
 
 import { EventEmitter } from 'events';
+import type { Subscription } from 'rxjs';
 import { Logger } from '../utils/Logger.js';
 import { EventBus } from '../events/EventBus.js';
 import { Events } from '../events/EventNames.js';
@@ -203,8 +204,10 @@ export class ValidationAnalyticsService extends EventEmitter {
         retentionPeriod: 90 * 24 * 60 * 60 * 1000, // 90 days
         enableRealTimeStreaming: true
     };
-    
-    private static instance: ValidationAnalyticsService;
+    private readonly eventSubscriptions: Subscription[] = [];
+    private aggregationInterval?: ReturnType<typeof setInterval>;
+
+    private static instance: ValidationAnalyticsService | undefined;
     
     private constructor() {
         super();
@@ -1037,7 +1040,7 @@ export class ValidationAnalyticsService extends EventEmitter {
      */
     private setupEventListeners(): void {
         // Listen to validation events
-        EventBus.server.on(Events.Mcp.TOOL_VALIDATION_ERROR, (event) => {
+        this.eventSubscriptions.push(EventBus.server.on(Events.Mcp.TOOL_VALIDATION_ERROR, (event) => {
             this.recordMetric({
                 name: 'validation_error',
                 value: 1,
@@ -1048,9 +1051,9 @@ export class ValidationAnalyticsService extends EventEmitter {
                     errorType: event.errorType
                 }
             });
-        });
+        }));
         
-        EventBus.server.on(Events.Mcp.TOOL_RESULT, (event) => {
+        this.eventSubscriptions.push(EventBus.server.on(Events.Mcp.TOOL_RESULT, (event) => {
             if (event.success) {
                 this.recordMetric({
                     name: 'tool_success',
@@ -1062,10 +1065,10 @@ export class ValidationAnalyticsService extends EventEmitter {
                     }
                 });
             }
-        });
+        }));
         
         // Listen to correction events
-        EventBus.server.on(Events.Mcp.TOOL_RESULT, (event) => {
+        this.eventSubscriptions.push(EventBus.server.on(Events.Mcp.TOOL_RESULT, (event) => {
             this.recordMetric({
                 name: 'auto_correction',
                 value: 1,
@@ -1075,16 +1078,17 @@ export class ValidationAnalyticsService extends EventEmitter {
                     tool: event.toolName
                 }
             });
-        });
+        }));
     }
     
     /**
      * Start aggregation worker
      */
     private startAggregationWorker(): void {
-        setInterval(() => {
-            this.performAggregation();
+        this.aggregationInterval = setInterval(() => {
+            void this.performAggregation();
         }, this.config.aggregationInterval);
+        this.aggregationInterval.unref?.();
     }
     
     /**
@@ -1170,4 +1174,25 @@ export class ValidationAnalyticsService extends EventEmitter {
         this.metricsBuffer.length = 0;
         this.aggregatedMetrics.clear();
     }
-}
+
+    /** Release every timer and subscription owned by this singleton. */
+    public shutdown(): void {
+        if (this.aggregationInterval) {
+            clearInterval(this.aggregationInterval);
+            this.aggregationInterval = undefined;
+        }
+        for (const subscription of this.eventSubscriptions) {
+            subscription.unsubscribe();
+        }
+        this.eventSubscriptions.length = 0;
+        this.clearMetrics();
+        this.activeABTests.clear();
+        this.abTestResults.clear();
+        this.customReports.clear();
+        this.removeAllListeners();
+
+        if (ValidationAnalyticsService.instance === this) {
+            ValidationAnalyticsService.instance = undefined;
+        }
+    }
+}

package/src/services/ValidationCacheService.ts

@@ -197,9 +197,11 @@ export class ValidationCacheService {
     private mongoCollection: any = null;
     
     // Background tasks
-    private cleanupInterval: NodeJS.Timeout | null = null;
-    
-    private static instance: ValidationCacheService;
+    private cleanupInterval?: ReturnType<typeof setInterval>;
+    private mongoCleanupInterval?: ReturnType<typeof setInterval>;
+    private statisticsInterval?: ReturnType<typeof setInterval>;
+
+    private static instance: ValidationCacheService | undefined;
 
     private constructor() {
         this.logger = new Logger('info', 'ValidationCacheService', 'server');
@@ -962,21 +964,24 @@ export class ValidationCacheService {
             this.cleanupInterval = setInterval(() => {
                 this.cleanupExpiredMemoryEntries();
             }, this.config.memoryCache.cleanupInterval);
+            this.cleanupInterval.unref?.();
         }
 
         // MongoDB background cleanup
         if (this.config.mongoCache.backgroundCleanup) {
-            setInterval(() => {
+            this.mongoCleanupInterval = setInterval(() => {
                 this.cleanupMongoCache().catch(error => {
                     this.logger.warn('MongoDB cache cleanup failed:', error);
                 });
             }, 60 * 60 * 1000); // Every hour
+            this.mongoCleanupInterval.unref?.();
         }
 
         // Statistics reporting
-        setInterval(() => {
+        this.statisticsInterval = setInterval(() => {
             this.reportCacheStatistics();
         }, 5 * 60 * 1000); // Every 5 minutes
+        this.statisticsInterval.unref?.();
     }
 
     private cleanupExpiredMemoryEntries(): void {
@@ -1166,12 +1171,30 @@ export class ValidationCacheService {
     public shutdown(): void {
         if (this.cleanupInterval) {
             clearInterval(this.cleanupInterval);
-            this.cleanupInterval = null;
+            this.cleanupInterval = undefined;
+        }
+        if (this.mongoCleanupInterval) {
+            clearInterval(this.mongoCleanupInterval);
+            this.mongoCleanupInterval = undefined;
+        }
+        if (this.statisticsInterval) {
+            clearInterval(this.statisticsInterval);
+            this.statisticsInterval = undefined;
         }
 
         if (this.redisClient) {
             // this.redisClient.disconnect();
         }
 
+        this.memoryCache.clear();
+        this.accessOrder.clear();
+        this.accessFrequency.clear();
+        this.memoryCacheSize = 0;
+        this.cacheEvents$.complete();
+
+        if (ValidationCacheService.instance === this) {
+            ValidationCacheService.instance = undefined;
+        }
+
     }
-}
+}

package/src/services/ValidationMiddleware.ts

@@ -25,7 +25,7 @@
  * Integrates with ToolExecutionInterceptor and adds proactive validation layer.
  */
 
-import { Observable, Subject } from 'rxjs';
+import { Observable, Subject, Subscription } from 'rxjs';
 import { Logger } from '../utils/Logger.js';
 import { EventBus } from '../events/EventBus.js';
 import { Events } from '../events/EventNames.js';
@@ -127,8 +127,16 @@ export class ValidationMiddleware {
     
     // Emergency bypass tracking
     private emergencyBypassUntil = 0;
-    
-    private static instance: ValidationMiddleware;
+    private readonly subscriptions: Subscription[] = [];
+    private readonly pendingValidationTimeouts = new Map<
+        ReturnType<typeof setTimeout>,
+        (reason?: unknown) => void
+    >();
+    private metricsInterval?: ReturnType<typeof setInterval>;
+    private interceptionCleanupInterval?: ReturnType<typeof setInterval>;
+    private healthCheckInterval?: ReturnType<typeof setInterval>;
+
+    private static instance: ValidationMiddleware | undefined;
 
     private constructor() {
         this.logger = new Logger('info', 'ValidationMiddleware', 'server');
@@ -415,9 +423,9 @@ export class ValidationMiddleware {
         // This ensures all tool calls go through both validation and auto-correction
         
         // Listen to tool execution interceptor events
-        this.toolExecutionInterceptor.interceptionEvents.subscribe(event => {
+        this.subscriptions.push(this.toolExecutionInterceptor.interceptionEvents.subscribe(event => {
             this.handleToolExecutionEvent(event);
-        });
+        }));
         
     }
 
@@ -625,13 +633,19 @@ export class ValidationMiddleware {
     private async withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
+                this.pendingValidationTimeouts.delete(timer);
                 reject(new Error('TIMEOUT'));
             }, timeoutMs);
+            timer.unref?.();
+            this.pendingValidationTimeouts.set(timer, reject);
 
             promise
                 .then(resolve)
                 .catch(reject)
-                .finally(() => clearTimeout(timer));
+                .finally(() => {
+                    clearTimeout(timer);
+                    this.pendingValidationTimeouts.delete(timer);
+                });
         });
     }
 
@@ -689,31 +703,34 @@ export class ValidationMiddleware {
 
     private setupEventListeners(): void {
         // Listen to system events for emergency bypass triggers
-        EventBus.server.on(Events.System.MAINTENANCE_MODE, () => {
+        this.subscriptions.push(EventBus.server.on(Events.System.MAINTENANCE_MODE, () => {
             this.activateEmergencyBypass(30 * 60 * 1000); // 30 minutes
-        });
+        }));
 
         // Listen to validation performance events
-        this.proactiveValidationService.validationEvents.subscribe(event => {
+        this.subscriptions.push(this.proactiveValidationService.validationEvents.subscribe(_event => {
             // Could use these events for additional learning or optimization
-        });
+        }));
     }
 
     private startPeriodicTasks(): void {
         // Performance reporting
-        setInterval(() => {
+        this.metricsInterval = setInterval(() => {
             this.reportPerformanceMetrics();
         }, 60 * 1000); // Every minute
+        this.metricsInterval.unref?.();
 
         // Cleanup expired interceptions
-        setInterval(() => {
+        this.interceptionCleanupInterval = setInterval(() => {
             this.cleanupExpiredInterceptions();
         }, 5 * 60 * 1000); // Every 5 minutes
+        this.interceptionCleanupInterval.unref?.();
 
         // Health checks
-        setInterval(() => {
+        this.healthCheckInterval = setInterval(() => {
             this.performHealthCheck();
         }, 30 * 1000); // Every 30 seconds
+        this.healthCheckInterval.unref?.();
     }
 
     private reportPerformanceMetrics(): void {
@@ -873,4 +890,35 @@ export class ValidationMiddleware {
             totalValidationTime: 0
         });
     }
-}
+
+    /** Release every timer and subscription owned by this singleton. */
+    public shutdown(): void {
+        if (this.metricsInterval) {
+            clearInterval(this.metricsInterval);
+            this.metricsInterval = undefined;
+        }
+        if (this.interceptionCleanupInterval) {
+            clearInterval(this.interceptionCleanupInterval);
+            this.interceptionCleanupInterval = undefined;
+        }
+        if (this.healthCheckInterval) {
+            clearInterval(this.healthCheckInterval);
+            this.healthCheckInterval = undefined;
+        }
+        for (const [timer, reject] of this.pendingValidationTimeouts) {
+            clearTimeout(timer);
+            reject(new Error('Validation middleware is shutting down'));
+        }
+        this.pendingValidationTimeouts.clear();
+        for (const subscription of this.subscriptions) {
+            subscription.unsubscribe();
+        }
+        this.subscriptions.length = 0;
+        this.activeInterceptions.clear();
+        this.middlewareEvents$.complete();
+
+        if (ValidationMiddleware.instance === this) {
+            ValidationMiddleware.instance = undefined;
+        }
+    }
+}

package/src/services/ValidationPerformanceService.ts

@@ -23,7 +23,7 @@
  * Phase 1: Extension of AgentPerformanceService for validation metrics
  */
 
-import { Observable, Subject, of } from 'rxjs';
+import { Observable, Subject, type Subscription } from 'rxjs';
 import { Logger } from '../utils/Logger.js';
 import { EventBus } from '../events/EventBus.js';
 import { Events } from '../events/EventNames.js';
@@ -52,8 +52,11 @@ export class ValidationPerformanceService {
     
     // Observable for validation events
     private readonly validationEvents$ = new Subject<ValidationEvent>();
-    
-    private static instance: ValidationPerformanceService;
+
+    // EventBus subscriptions owned by this singleton, released by shutdown()
+    private readonly eventSubscriptions: Subscription[] = [];
+
+    private static instance: ValidationPerformanceService | undefined;
 
     private constructor() {
         this.logger = new Logger('info', 'ValidationPerformanceService', 'server');
@@ -77,42 +80,61 @@ export class ValidationPerformanceService {
     // =============================================================================
 
     private setupEventListeners(): void {
+        // Handlers return their promise so the EventBus shutdown drain waits for
+        // in-flight tracking and logs a rejection instead of leaving it unhandled.
+
         // Track validation errors
-        EventBus.server.on(Events.Mcp.TOOL_ERROR, (payload) => {
+        this.eventSubscriptions.push(EventBus.server.on(Events.Mcp.TOOL_ERROR, (payload): Promise<void> | undefined => {
             const error = payload.error || payload.data?.error || payload.data?.errorMessage;
-            if (this.isValidationError(error)) {
-                this.trackValidationError(
-                    payload.agentId,
-                    payload.channelId,
-                    payload.data?.toolName || payload.toolName,
-                    error,
-                    payload.data?.parameters
-                );
+            if (!this.isValidationError(error)) {
+                return undefined;
             }
-        });
+            return this.trackValidationError(
+                payload.agentId,
+                payload.channelId,
+                payload.data?.toolName || payload.toolName,
+                error,
+                payload.data?.parameters
+            );
+        }));
 
         // Track successful tool calls (for success rate calculation)
-        EventBus.server.on(Events.Mcp.TOOL_RESULT, (payload) => {
+        this.eventSubscriptions.push(EventBus.server.on(Events.Mcp.TOOL_RESULT, (payload) =>
             this.trackValidationSuccess(
                 payload.agentId,
                 payload.channelId,
                 payload.data?.toolName || payload.toolName
-            );
-        });
+            )
+        ));
 
         // Track help tool usage
-        EventBus.server.on(Events.Mcp.TOOL_CALL, (payload) => {
+        this.eventSubscriptions.push(EventBus.server.on(Events.Mcp.TOOL_CALL, (payload): Promise<void> | undefined => {
             const toolName = payload.data?.toolName || payload.toolName;
-            if (this.isHelpTool(toolName)) {
-                this.trackHelpToolUsage(
-                    payload.agentId,
-                    payload.channelId,
-                    toolName,
-                    payload.data?.parameters
-                );
+            if (!this.isHelpTool(toolName)) {
+                return undefined;
             }
-        });
+            return this.trackHelpToolUsage(
+                payload.agentId,
+                payload.channelId,
+                toolName,
+                payload.data?.parameters
+            );
+        }));
+    }
 
+    /** Release every EventBus subscription and cached state owned by this singleton. */
+    public shutdown(): void {
+        for (const subscription of this.eventSubscriptions) {
+            subscription.unsubscribe();
+        }
+        this.eventSubscriptions.length = 0;
+        this.validationMetrics.clear();
+        this.errorTimestamps.clear();
+        this.validationEvents$.complete();
+
+        if (ValidationPerformanceService.instance === this) {
+            ValidationPerformanceService.instance = undefined;
+        }
     }
 
     // =============================================================================