@juspay/neurolink 7.38.1 → 7.39.0

package/dist/lib/mcp/externalServerManager.d.ts

@@ -8,6 +8,7 @@
  */
 import { EventEmitter } from "events";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
+import type { HITLManager } from "../hitl/hitlManager.js";
 import type { ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPConfigValidation, ExternalMCPOperationResult, ExternalMCPManagerConfig, ExternalMCPToolInfo } from "../types/externalMcp.js";
 import type { MCPServerInfo } from "../types/mcpTypes.js";
 import type { JsonObject } from "../types/common.js";
@@ -18,9 +19,19 @@ export declare class ExternalServerManager extends EventEmitter {
     private isShuttingDown;
     private toolDiscovery;
     private enableMainRegistryIntegration;
+    private hitlManager?;
     constructor(config?: ExternalMCPManagerConfig, options?: {
         enableMainRegistryIntegration?: boolean;
     });
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager?: HITLManager): void;
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager(): HITLManager | undefined;
     /**
      * Load MCP server configurations from .mcp-config.json file with parallel loading support
      * Automatically registers servers found in the configuration

package/dist/lib/mcp/externalServerManager.js

@@ -11,6 +11,7 @@ import { mcpLogger } from "../utils/logger.js";
 import { MCPClientFactory } from "./mcpClientFactory.js";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
 import { toolRegistry } from "./toolRegistry.js";
+import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
 import { isObject, isNonNullObject } from "../utils/typeUtils.js";
 /**
@@ -76,6 +77,7 @@ export class ExternalServerManager extends EventEmitter {
     isShuttingDown = false;
     toolDiscovery;
     enableMainRegistryIntegration;
+    hitlManager; // Optional HITL manager for safety mechanisms
     constructor(config = {}, options = {}) {
         super();
         // Set defaults for configuration
@@ -106,6 +108,25 @@ export class ExternalServerManager extends EventEmitter {
         process.on("SIGTERM", () => this.shutdown());
         process.on("beforeExit", () => this.shutdown());
     }
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager) {
+        this.hitlManager = hitlManager;
+        if (hitlManager && hitlManager.isEnabled()) {
+            mcpLogger.info("[ExternalServerManager] HITL safety mechanisms enabled for external tool execution");
+        }
+        else {
+            mcpLogger.debug("[ExternalServerManager] HITL safety mechanisms disabled or not configured");
+        }
+    }
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager() {
+        return this.hitlManager;
+    }
     /**
      * Load MCP server configurations from .mcp-config.json file with parallel loading support
      * Automatically registers servers found in the configuration
@@ -1116,8 +1137,54 @@ export class ExternalServerManager extends EventEmitter {
         }
         const startTime = Date.now();
         try {
-            // Execute tool through discovery service
-            const result = await this.toolDiscovery.executeTool(toolName, serverId, instance.client, parameters, {
+            // HITL Safety Check: Request confirmation if required
+            let finalParameters = parameters;
+            if (this.hitlManager && this.hitlManager.isEnabled()) {
+                const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, parameters);
+                if (requiresConfirmation) {
+                    mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' on server '${serverId}' requires HITL confirmation`);
+                    try {
+                        const confirmationResult = await this.hitlManager.requestConfirmation(toolName, parameters, {
+                            serverId: serverId,
+                            sessionId: `external-${serverId}-${Date.now()}`,
+                            userId: undefined, // External tools don't have user context by default
+                        });
+                        if (!confirmationResult.approved) {
+                            // User rejected the tool execution
+                            throw new HITLUserRejectedError(`External tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                        }
+                        // User approved - use modified arguments if provided
+                        if (confirmationResult.modifiedArguments !== undefined) {
+                            finalParameters =
+                                confirmationResult.modifiedArguments;
+                            mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' arguments modified by user`);
+                        }
+                        mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
+                    }
+                    catch (error) {
+                        if (error instanceof HITLTimeoutError) {
+                            // Timeout occurred - user didn't respond in time
+                            mcpLogger.warn(`[ExternalServerManager] External tool '${toolName}' execution timed out waiting for user confirmation`);
+                            throw error;
+                        }
+                        else if (error instanceof HITLUserRejectedError) {
+                            // User explicitly rejected
+                            mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' execution rejected by user`);
+                            throw error;
+                        }
+                        else {
+                            // Other HITL error (configuration, system error, etc.)
+                            mcpLogger.error(`[ExternalServerManager] HITL confirmation failed for external tool '${toolName}':`, error);
+                            throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+                else {
+                    mcpLogger.debug(`[ExternalServerManager] External tool '${toolName}' does not require HITL confirmation`);
+                }
+            }
+            // Execute tool through discovery service (with potentially modified parameters)
+            const result = await this.toolDiscovery.executeTool(toolName, serverId, instance.client, finalParameters, {
                 timeout: options?.timeout || this.config.defaultTimeout,
             });
             const duration = Date.now() - startTime;

package/dist/lib/mcp/toolRegistry.d.ts

@@ -6,6 +6,7 @@ import type { ExecutionContext, ToolInfo } from "./contracts/mcpContract.js";
 import type { ToolResult } from "./factory.js";
 import type { MCPServerInfo } from "../types/mcpTypes.js";
 import { MCPRegistry } from "./registry.js";
+import type { HITLManager } from "../hitl/hitlManager.js";
 interface ToolImplementation {
     execute: (params: unknown, context?: ExecutionContext) => Promise<unknown> | unknown;
     description?: string;
@@ -32,7 +33,17 @@ export declare class MCPToolRegistry extends MCPRegistry {
     private toolImplementations;
     private toolExecutionStats;
     private builtInServerInfos;
+    private hitlManager?;
     constructor();
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager?: HITLManager): void;
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager(): HITLManager | undefined;
     /**
      * Register all direct tools from directAgentTools
      */

package/dist/lib/mcp/toolRegistry.js

@@ -9,17 +9,38 @@ import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
+import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 export class MCPToolRegistry extends MCPRegistry {
     tools = new Map();
     toolImplementations = new Map(); // Store actual tool implementations
     toolExecutionStats = new Map();
     builtInServerInfos = []; // DIRECT storage for MCPServerInfo
+    hitlManager; // Optional HITL manager for safety mechanisms
     constructor() {
         super();
         if (!shouldDisableBuiltinTools()) {
             this.registerDirectTools();
         }
     }
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager) {
+        this.hitlManager = hitlManager;
+        if (hitlManager && hitlManager.isEnabled()) {
+            registryLogger.info("HITL safety mechanisms enabled for tool execution");
+        }
+        else {
+            registryLogger.debug("HITL safety mechanisms disabled or not configured");
+        }
+    }
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager() {
+        return this.hitlManager;
+    }
     /**
      * Register all direct tools from directAgentTools
      */
@@ -237,9 +258,54 @@ export class MCPToolRegistry extends MCPRegistry {
             if (!toolImpl || typeof toolImpl?.execute !== "function") {
                 throw new Error(`Tool '${toolName}' implementation not found or not executable`);
             }
-            // Execute the actual tool
-            registryLogger.debug(`Executing tool '${toolName}' with args:`, args);
-            const toolResult = await toolImpl.execute(args, execContext);
+            // HITL Safety Check: Request confirmation if required
+            let finalArgs = args;
+            if (this.hitlManager && this.hitlManager.isEnabled()) {
+                const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, args);
+                if (requiresConfirmation) {
+                    registryLogger.info(`Tool '${toolName}' requires HITL confirmation`);
+                    try {
+                        const confirmationResult = await this.hitlManager.requestConfirmation(toolName, args, {
+                            serverId: tool.serverId,
+                            sessionId: execContext.sessionId,
+                            userId: execContext.userId,
+                        });
+                        if (!confirmationResult.approved) {
+                            // User rejected the tool execution
+                            throw new HITLUserRejectedError(`Tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                        }
+                        // User approved - use modified arguments if provided
+                        if (confirmationResult.modifiedArguments !== undefined) {
+                            finalArgs = confirmationResult.modifiedArguments;
+                            registryLogger.info(`Tool '${toolName}' arguments modified by user`);
+                        }
+                        registryLogger.info(`Tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
+                    }
+                    catch (error) {
+                        if (error instanceof HITLTimeoutError) {
+                            // Timeout occurred - user didn't respond in time
+                            registryLogger.warn(`Tool '${toolName}' execution timed out waiting for user confirmation`);
+                            throw error;
+                        }
+                        else if (error instanceof HITLUserRejectedError) {
+                            // User explicitly rejected
+                            registryLogger.info(`Tool '${toolName}' execution rejected by user`);
+                            throw error;
+                        }
+                        else {
+                            // Other HITL error (configuration, system error, etc.)
+                            registryLogger.error(`HITL confirmation failed for tool '${toolName}':`, error);
+                            throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+                else {
+                    registryLogger.debug(`Tool '${toolName}' does not require HITL confirmation`);
+                }
+            }
+            // Execute the actual tool (with potentially modified arguments)
+            registryLogger.debug(`Executing tool '${toolName}' with args:`, finalArgs);
+            const toolResult = await toolImpl.execute(finalArgs, execContext);
             // Properly wrap raw results in ToolResult format
             let result;
             // Check if result is already a ToolResult object

package/dist/lib/neurolink.d.ts

@@ -16,6 +16,7 @@ import type { BatchOperationResult } from "./types/typeAliases.js";
 import type { ConversationMemoryConfig, ChatMessage } from "./types/conversation.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
+import type { HITLConfig } from "./hitl/types.js";
 import type { ExternalMCPServerInstance, ExternalMCPOperationResult, ExternalMCPToolInfo } from "./types/externalMcp.js";
 export interface ProviderStatus {
     provider: string;
@@ -68,6 +69,7 @@ export declare class NeuroLink {
     private conversationMemoryNeedsInit;
     private conversationMemoryConfig?;
     private enableOrchestration;
+    private hitlManager?;
     /**
      * Context storage for tool execution
      * This context will be merged with any runtime context passed by the AI model
@@ -82,6 +84,11 @@ export declare class NeuroLink {
      * @param config.conversationMemory.maxSessions - Maximum number of concurrent sessions (default: 100)
      * @param config.conversationMemory.maxTurnsPerSession - Maximum conversation turns per session (default: 50)
      * @param config.enableOrchestration - Whether to enable smart model orchestration (default: false)
+     * @param config.hitl - Configuration for Human-in-the-Loop safety features
+     * @param config.hitl.enabled - Whether to enable HITL tool confirmation (default: false)
+     * @param config.hitl.dangerousActions - Keywords that trigger confirmation (default: ['delete', 'remove', 'drop'])
+     * @param config.hitl.timeout - Confirmation timeout in milliseconds (default: 30000)
+     * @param config.hitl.allowArgumentModification - Allow users to modify tool parameters (default: true)
      *
      * @example
      * ```typescript
@@ -101,15 +108,27 @@ export declare class NeuroLink {
      * const neurolink = new NeuroLink({
      *   enableOrchestration: true
      * });
+     *
+     * // With HITL safety features
+     * const neurolink = new NeuroLink({
+     *   hitl: {
+     *     enabled: true,
+     *     dangerousActions: ['delete', 'remove', 'drop', 'truncate'],
+     *     timeout: 30000,
+     *     allowArgumentModification: true
+     *   }
+     * });
      * ```
      *
      * @throws {Error} When provider registry setup fails
      * @throws {Error} When conversation memory initialization fails (if enabled)
      * @throws {Error} When external server manager initialization fails
+     * @throws {Error} When HITL configuration is invalid (if enabled)
      */
     constructor(config?: {
         conversationMemory?: Partial<ConversationMemoryConfig>;
         enableOrchestration?: boolean;
+        hitl?: HITLConfig;
     });
     /**
      * Initialize provider registry with security settings
@@ -119,6 +138,14 @@ export declare class NeuroLink {
      * Initialize conversation memory if enabled
      */
     private initializeConversationMemory;
+    /**
+     * Initialize HITL (Human-in-the-Loop) if enabled
+     */
+    private initializeHITL;
+    /**
+     * Set up HITL event forwarding to main emitter
+     */
+    private setupHITLEventForwarding;
     /**
      * Initialize external server manager with event handlers
      */

package/dist/lib/neurolink.js

@@ -33,6 +33,7 @@ import { ErrorFactory, NeuroLinkError, withTimeout, withRetry, isRetriableError,
 import { EventEmitter } from "events";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
+import { HITLManager } from "./hitl/hitlManager.js";
 // Import direct tools server for automatic registration
 import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 // Import orchestration components
@@ -84,6 +85,8 @@ export class NeuroLink {
     conversationMemoryConfig;
     // Add orchestration property
     enableOrchestration;
+    // HITL (Human-in-the-Loop) support
+    hitlManager;
     /**
      * Context storage for tool execution
      * This context will be merged with any runtime context passed by the AI model
@@ -98,6 +101,11 @@ export class NeuroLink {
      * @param config.conversationMemory.maxSessions - Maximum number of concurrent sessions (default: 100)
      * @param config.conversationMemory.maxTurnsPerSession - Maximum conversation turns per session (default: 50)
      * @param config.enableOrchestration - Whether to enable smart model orchestration (default: false)
+     * @param config.hitl - Configuration for Human-in-the-Loop safety features
+     * @param config.hitl.enabled - Whether to enable HITL tool confirmation (default: false)
+     * @param config.hitl.dangerousActions - Keywords that trigger confirmation (default: ['delete', 'remove', 'drop'])
+     * @param config.hitl.timeout - Confirmation timeout in milliseconds (default: 30000)
+     * @param config.hitl.allowArgumentModification - Allow users to modify tool parameters (default: true)
      *
      * @example
      * ```typescript
@@ -117,11 +125,22 @@ export class NeuroLink {
      * const neurolink = new NeuroLink({
      *   enableOrchestration: true
      * });
+     *
+     * // With HITL safety features
+     * const neurolink = new NeuroLink({
+     *   hitl: {
+     *     enabled: true,
+     *     dangerousActions: ['delete', 'remove', 'drop', 'truncate'],
+     *     timeout: 30000,
+     *     allowArgumentModification: true
+     *   }
+     * });
      * ```
      *
      * @throws {Error} When provider registry setup fails
      * @throws {Error} When conversation memory initialization fails (if enabled)
      * @throws {Error} When external server manager initialization fails
+     * @throws {Error} When HITL configuration is invalid (if enabled)
      */
     constructor(config) {
         // Initialize orchestration setting
@@ -137,6 +156,7 @@ export class NeuroLink {
         this.initializeProviderRegistry(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeConversationMemory(config, constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeExternalServerManager(constructorId, constructorStartTime, constructorHrTimeStart);
+        this.initializeHITL(config, constructorId, constructorStartTime, constructorHrTimeStart);
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
     }
     /**
@@ -198,6 +218,132 @@ export class NeuroLink {
             });
         }
     }
+    /**
+     * Initialize HITL (Human-in-the-Loop) if enabled
+     */
+    initializeHITL(config, constructorId, constructorStartTime, constructorHrTimeStart) {
+        if (config?.hitl?.enabled) {
+            const hitlInitStartTime = process.hrtime.bigint();
+            logger.debug(`[NeuroLink] 🛡️ LOG_POINT_C015_HITL_INIT_START`, {
+                logPoint: "C015_HITL_INIT_START",
+                constructorId,
+                timestamp: new Date().toISOString(),
+                elapsedMs: Date.now() - constructorStartTime,
+                elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                hitlInitStartTimeNs: hitlInitStartTime.toString(),
+                hitlConfig: {
+                    enabled: config.hitl.enabled,
+                    dangerousActions: config.hitl.dangerousActions || [],
+                    timeout: config.hitl.timeout || 30000,
+                    allowArgumentModification: config.hitl.allowArgumentModification ?? true,
+                    auditLogging: config.hitl.auditLogging ?? false,
+                },
+                message: "Starting HITL (Human-in-the-Loop) initialization",
+            });
+            try {
+                // Initialize HITL manager
+                this.hitlManager = new HITLManager(config.hitl);
+                // Inject HITL manager into tool registry
+                toolRegistry.setHITLManager(this.hitlManager);
+                // Inject HITL manager into external server manager
+                this.externalServerManager.setHITLManager(this.hitlManager);
+                // Set up HITL event forwarding to main emitter
+                this.setupHITLEventForwarding();
+                const hitlInitEndTime = process.hrtime.bigint();
+                const hitlInitDurationNs = hitlInitEndTime - hitlInitStartTime;
+                logger.debug(`[NeuroLink] ✅ LOG_POINT_C016_HITL_INIT_SUCCESS`, {
+                    logPoint: "C016_HITL_INIT_SUCCESS",
+                    constructorId,
+                    timestamp: new Date().toISOString(),
+                    elapsedMs: Date.now() - constructorStartTime,
+                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                    hitlInitDurationNs: hitlInitDurationNs.toString(),
+                    hitlInitDurationMs: Number(hitlInitDurationNs) / NANOSECOND_TO_MS_DIVISOR,
+                    hasHitlManager: !!this.hitlManager,
+                    message: "HITL (Human-in-the-Loop) initialized successfully",
+                });
+                logger.info(`[NeuroLink] HITL safety features enabled`, {
+                    dangerousActions: config.hitl.dangerousActions?.length || 0,
+                    timeout: config.hitl.timeout || 30000,
+                    allowArgumentModification: config.hitl.allowArgumentModification ?? true,
+                    auditLogging: config.hitl.auditLogging ?? false,
+                });
+            }
+            catch (error) {
+                const hitlInitErrorTime = process.hrtime.bigint();
+                const hitlInitDurationNs = hitlInitErrorTime - hitlInitStartTime;
+                logger.error(`[NeuroLink] ❌ LOG_POINT_C017_HITL_INIT_ERROR`, {
+                    logPoint: "C017_HITL_INIT_ERROR",
+                    constructorId,
+                    timestamp: new Date().toISOString(),
+                    elapsedMs: Date.now() - constructorStartTime,
+                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                    hitlInitDurationNs: hitlInitDurationNs.toString(),
+                    hitlInitDurationMs: Number(hitlInitDurationNs) / NANOSECOND_TO_MS_DIVISOR,
+                    error: error instanceof Error ? error.message : String(error),
+                    errorName: error instanceof Error ? error.name : "UnknownError",
+                    errorStack: error instanceof Error ? error.stack : undefined,
+                    message: "HITL (Human-in-the-Loop) initialization failed",
+                });
+                throw error;
+            }
+        }
+        else {
+            logger.debug(`[NeuroLink] 🚫 LOG_POINT_C018_HITL_DISABLED`, {
+                logPoint: "C018_HITL_DISABLED",
+                constructorId,
+                timestamp: new Date().toISOString(),
+                elapsedMs: Date.now() - constructorStartTime,
+                elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                hasConfig: !!config,
+                hasHitlConfig: !!config?.hitl,
+                hitlEnabled: config?.hitl?.enabled || false,
+                reason: !config
+                    ? "NO_CONFIG"
+                    : !config.hitl
+                        ? "NO_HITL_CONFIG"
+                        : !config.hitl.enabled
+                            ? "HITL_DISABLED"
+                            : "UNKNOWN",
+                message: "HITL (Human-in-the-Loop) not enabled - skipping initialization",
+            });
+        }
+    }
+    /**
+     * Set up HITL event forwarding to main emitter
+     */
+    setupHITLEventForwarding() {
+        if (!this.hitlManager) {
+            return;
+        }
+        // Forward HITL confirmation requests to main emitter
+        this.hitlManager.on("hitl:confirmation-request", (event) => {
+            logger.debug("Forwarding HITL confirmation request", {
+                confirmationId: event.payload?.confirmationId,
+                toolName: event.payload?.toolName,
+            });
+            this.emitter.emit("hitl:confirmation-request", event);
+        });
+        // Forward HITL timeout events to main emitter
+        this.hitlManager.on("hitl:timeout", (event) => {
+            logger.debug("Forwarding HITL timeout event", {
+                confirmationId: event.payload?.confirmationId,
+                toolName: event.payload?.toolName,
+            });
+            this.emitter.emit("hitl:timeout", event);
+        });
+        // Listen for confirmation responses from main emitter and forward to HITL manager
+        this.emitter.on("hitl:confirmation-response", (event) => {
+            const typedEvent = event;
+            logger.debug("Received HITL confirmation response", {
+                confirmationId: typedEvent.payload?.confirmationId,
+                approved: typedEvent.payload?.approved,
+            });
+            // Forward to HITL manager
+            this.hitlManager?.emit("hitl:confirmation-response", typedEvent);
+        });
+        logger.debug("HITL event forwarding configured successfully");
+    }
     /**
      * Initialize external server manager with event handlers
      */

package/dist/mcp/externalServerManager.d.ts

@@ -8,6 +8,7 @@
  */
 import { EventEmitter } from "events";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
+import type { HITLManager } from "../hitl/hitlManager.js";
 import type { ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPConfigValidation, ExternalMCPOperationResult, ExternalMCPManagerConfig, ExternalMCPToolInfo } from "../types/externalMcp.js";
 import type { MCPServerInfo } from "../types/mcpTypes.js";
 import type { JsonObject } from "../types/common.js";
@@ -18,9 +19,19 @@ export declare class ExternalServerManager extends EventEmitter {
     private isShuttingDown;
     private toolDiscovery;
     private enableMainRegistryIntegration;
+    private hitlManager?;
     constructor(config?: ExternalMCPManagerConfig, options?: {
         enableMainRegistryIntegration?: boolean;
     });
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager?: HITLManager): void;
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager(): HITLManager | undefined;
     /**
      * Load MCP server configurations from .mcp-config.json file with parallel loading support
      * Automatically registers servers found in the configuration

package/dist/mcp/externalServerManager.js

@@ -11,6 +11,7 @@ import { mcpLogger } from "../utils/logger.js";
 import { MCPClientFactory } from "./mcpClientFactory.js";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
 import { toolRegistry } from "./toolRegistry.js";
+import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
 import { isObject, isNonNullObject } from "../utils/typeUtils.js";
 /**
@@ -76,6 +77,7 @@ export class ExternalServerManager extends EventEmitter {
     isShuttingDown = false;
     toolDiscovery;
     enableMainRegistryIntegration;
+    hitlManager; // Optional HITL manager for safety mechanisms
     constructor(config = {}, options = {}) {
         super();
         // Set defaults for configuration
@@ -106,6 +108,25 @@ export class ExternalServerManager extends EventEmitter {
         process.on("SIGTERM", () => this.shutdown());
         process.on("beforeExit", () => this.shutdown());
     }
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager) {
+        this.hitlManager = hitlManager;
+        if (hitlManager && hitlManager.isEnabled()) {
+            mcpLogger.info("[ExternalServerManager] HITL safety mechanisms enabled for external tool execution");
+        }
+        else {
+            mcpLogger.debug("[ExternalServerManager] HITL safety mechanisms disabled or not configured");
+        }
+    }
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager() {
+        return this.hitlManager;
+    }
     /**
      * Load MCP server configurations from .mcp-config.json file with parallel loading support
      * Automatically registers servers found in the configuration
@@ -1116,8 +1137,54 @@ export class ExternalServerManager extends EventEmitter {
         }
         const startTime = Date.now();
         try {
-            // Execute tool through discovery service
-            const result = await this.toolDiscovery.executeTool(toolName, serverId, instance.client, parameters, {
+            // HITL Safety Check: Request confirmation if required
+            let finalParameters = parameters;
+            if (this.hitlManager && this.hitlManager.isEnabled()) {
+                const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, parameters);
+                if (requiresConfirmation) {
+                    mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' on server '${serverId}' requires HITL confirmation`);
+                    try {
+                        const confirmationResult = await this.hitlManager.requestConfirmation(toolName, parameters, {
+                            serverId: serverId,
+                            sessionId: `external-${serverId}-${Date.now()}`,
+                            userId: undefined, // External tools don't have user context by default
+                        });
+                        if (!confirmationResult.approved) {
+                            // User rejected the tool execution
+                            throw new HITLUserRejectedError(`External tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                        }
+                        // User approved - use modified arguments if provided
+                        if (confirmationResult.modifiedArguments !== undefined) {
+                            finalParameters =
+                                confirmationResult.modifiedArguments;
+                            mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' arguments modified by user`);
+                        }
+                        mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
+                    }
+                    catch (error) {
+                        if (error instanceof HITLTimeoutError) {
+                            // Timeout occurred - user didn't respond in time
+                            mcpLogger.warn(`[ExternalServerManager] External tool '${toolName}' execution timed out waiting for user confirmation`);
+                            throw error;
+                        }
+                        else if (error instanceof HITLUserRejectedError) {
+                            // User explicitly rejected
+                            mcpLogger.info(`[ExternalServerManager] External tool '${toolName}' execution rejected by user`);
+                            throw error;
+                        }
+                        else {
+                            // Other HITL error (configuration, system error, etc.)
+                            mcpLogger.error(`[ExternalServerManager] HITL confirmation failed for external tool '${toolName}':`, error);
+                            throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+                else {
+                    mcpLogger.debug(`[ExternalServerManager] External tool '${toolName}' does not require HITL confirmation`);
+                }
+            }
+            // Execute tool through discovery service (with potentially modified parameters)
+            const result = await this.toolDiscovery.executeTool(toolName, serverId, instance.client, finalParameters, {
                 timeout: options?.timeout || this.config.defaultTimeout,
             });
             const duration = Date.now() - startTime;

package/dist/mcp/toolRegistry.d.ts

@@ -6,6 +6,7 @@ import type { ExecutionContext, ToolInfo } from "./contracts/mcpContract.js";
 import type { ToolResult } from "./factory.js";
 import type { MCPServerInfo } from "../types/mcpTypes.js";
 import { MCPRegistry } from "./registry.js";
+import type { HITLManager } from "../hitl/hitlManager.js";
 interface ToolImplementation {
     execute: (params: unknown, context?: ExecutionContext) => Promise<unknown> | unknown;
     description?: string;
@@ -32,7 +33,17 @@ export declare class MCPToolRegistry extends MCPRegistry {
     private toolImplementations;
     private toolExecutionStats;
     private builtInServerInfos;
+    private hitlManager?;
     constructor();
+    /**
+     * Set HITL manager for human-in-the-loop safety mechanisms
+     * @param hitlManager - HITL manager instance (optional, can be undefined to disable)
+     */
+    setHITLManager(hitlManager?: HITLManager): void;
+    /**
+     * Get current HITL manager
+     */
+    getHITLManager(): HITLManager | undefined;
     /**
      * Register all direct tools from directAgentTools
      */