@juspay/neurolink 7.38.0 → 7.39.0

package/dist/lib/hitl/hitlManager.js

@@ -0,0 +1,457 @@
+/**
+ * HITL (Human-in-the-Loop) Manager
+ *
+ * Central orchestrator for all HITL confirmation workflows.
+ * Manages user confirmation requests, timeouts, and argument modifications
+ * for enterprise-grade AI safety.
+ */
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import { HITLTimeoutError, HITLConfigurationError } from "./hitlErrors.js";
+import { logger } from "../utils/logger.js";
+/**
+ * HITLManager - Central orchestrator for Human-in-the-Loop safety mechanisms
+ *
+ * Features:
+ * - Real-time user confirmation via events
+ * - Configurable dangerous action detection
+ * - Custom rule engine for complex scenarios
+ * - Argument modification support
+ * - Comprehensive audit logging
+ * - Timeout handling with cleanup
+ */
+export class HITLManager extends EventEmitter {
+    config;
+    pendingConfirmations = new Map();
+    statistics = {
+        totalRequests: 0,
+        pendingRequests: 0,
+        averageResponseTime: 0,
+        approvedRequests: 0,
+        rejectedRequests: 0,
+        timedOutRequests: 0,
+    };
+    constructor(config) {
+        super();
+        this.config = this.validateConfig(config);
+        this.setupEventHandlers();
+    }
+    /**
+     * Validate HITL configuration and apply defaults
+     */
+    validateConfig(config) {
+        // Apply defaults for optional fields
+        const configWithDefaults = {
+            enabled: config.enabled,
+            dangerousActions: config.dangerousActions,
+            timeout: config.timeout ?? 30000, // Default: 30 seconds
+            confirmationMethod: config.confirmationMethod ?? "event", // Default: "event"
+            allowArgumentModification: config.allowArgumentModification ?? true, // Default: true
+            autoApproveOnTimeout: config.autoApproveOnTimeout ?? false, // Default: false (safe)
+            auditLogging: config.auditLogging ?? false, // Default: false
+            customRules: config.customRules ?? [], // Default: empty array
+        };
+        if (!configWithDefaults.enabled) {
+            return configWithDefaults; // If disabled, don't validate other fields
+        }
+        if (!Array.isArray(configWithDefaults.dangerousActions)) {
+            throw new HITLConfigurationError("dangerousActions must be an array of strings");
+        }
+        if (typeof configWithDefaults.timeout !== "number" ||
+            configWithDefaults.timeout <= 0) {
+            throw new HITLConfigurationError("timeout must be a positive number (milliseconds)");
+        }
+        if (configWithDefaults.confirmationMethod !== "event") {
+            throw new HITLConfigurationError("confirmationMethod must be 'event' (only supported method)");
+        }
+        if (typeof configWithDefaults.allowArgumentModification !== "boolean") {
+            throw new HITLConfigurationError("allowArgumentModification must be a boolean");
+        }
+        return configWithDefaults;
+    }
+    /**
+     * Check if a tool requires confirmation based on configuration
+     */
+    requiresConfirmation(toolName, args) {
+        if (!this.config.enabled) {
+            return false;
+        }
+        // Check dangerous actions keywords
+        const lowerToolName = toolName.toLowerCase();
+        for (const action of this.config.dangerousActions) {
+            if (lowerToolName.includes(action.toLowerCase())) {
+                return true;
+            }
+        }
+        // Check custom rules
+        if (this.config.customRules) {
+            for (const rule of this.config.customRules) {
+                if (rule.requiresConfirmation) {
+                    try {
+                        if (rule.condition(toolName, args)) {
+                            return true;
+                        }
+                    }
+                    catch (error) {
+                        // Log rule evaluation error but don't fail
+                        this.logAuditEvent("rule-evaluation-error", {
+                            ruleName: rule.name,
+                            toolName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Request confirmation for a tool execution
+     */
+    async requestConfirmation(toolName, arguments_, context) {
+        const confirmationId = this.generateConfirmationId();
+        const startTime = Date.now();
+        // Update statistics
+        this.statistics.totalRequests++;
+        this.statistics.pendingRequests++;
+        return new Promise((resolve, reject) => {
+            // Set up timeout
+            const timeoutHandle = setTimeout(() => {
+                this.handleTimeout(confirmationId);
+            }, this.config.timeout);
+            // Store pending confirmation
+            const request = {
+                confirmationId,
+                toolName,
+                arguments: arguments_,
+                timestamp: startTime,
+                timeoutHandle,
+                resolve,
+                reject,
+            };
+            this.pendingConfirmations.set(confirmationId, request);
+            // Create confirmation request event
+            const requestEvent = {
+                type: "hitl:confirmation-request",
+                payload: {
+                    confirmationId,
+                    toolName,
+                    serverId: context?.serverId,
+                    actionType: this.generateActionDescription(toolName, arguments_),
+                    arguments: arguments_,
+                    metadata: {
+                        timestamp: new Date(startTime).toISOString(),
+                        sessionId: context?.sessionId,
+                        userId: context?.userId,
+                        dangerousKeywords: this.getTriggeredKeywords(toolName, arguments_),
+                    },
+                    timeoutMs: this.config.timeout,
+                    allowModification: this.config.allowArgumentModification,
+                },
+            };
+            // Emit confirmation request event
+            this.emit("hitl:confirmation-request", requestEvent);
+            // Log audit trail if enabled
+            if (this.config.auditLogging) {
+                this.logAuditEvent("confirmation-requested", {
+                    confirmationId,
+                    toolName,
+                    userId: context?.userId,
+                    sessionId: context?.sessionId,
+                    timestamp: startTime,
+                    arguments: arguments_,
+                });
+            }
+        });
+    }
+    /**
+     * Process user response to confirmation request
+     */
+    processUserResponse(confirmationId, response) {
+        const request = this.pendingConfirmations.get(confirmationId);
+        if (!request) {
+            logger.warn(`No pending confirmation found for ID: ${confirmationId}`);
+            return;
+        }
+        // Clear timeout
+        clearTimeout(request.timeoutHandle);
+        // Remove from pending
+        this.pendingConfirmations.delete(confirmationId);
+        this.statistics.pendingRequests--;
+        // Calculate response time
+        const responseTime = response.responseTime || Date.now() - request.timestamp;
+        // Update statistics
+        if (response.approved) {
+            this.statistics.approvedRequests++;
+        }
+        else {
+            this.statistics.rejectedRequests++;
+        }
+        // Update average response time
+        const totalResponses = this.statistics.approvedRequests + this.statistics.rejectedRequests;
+        this.statistics.averageResponseTime =
+            (this.statistics.averageResponseTime * (totalResponses - 1) +
+                responseTime) /
+                totalResponses;
+        // Create result
+        const result = {
+            approved: response.approved,
+            reason: response.reason,
+            modifiedArguments: response.modifiedArguments,
+            responseTime,
+        };
+        // Log audit trail if enabled
+        if (this.config.auditLogging) {
+            this.logAuditEvent(response.approved ? "confirmation-approved" : "confirmation-rejected", {
+                confirmationId,
+                toolName: request.toolName,
+                approved: response.approved,
+                reason: response.reason,
+                userId: response.userId,
+                responseTime,
+                arguments: request.arguments,
+            });
+        }
+        // Resolve the promise
+        request.resolve(result);
+    }
+    /**
+     * Handle confirmation timeout
+     */
+    handleTimeout(confirmationId) {
+        const request = this.pendingConfirmations.get(confirmationId);
+        if (!request) {
+            return;
+        }
+        // Remove from pending
+        this.pendingConfirmations.delete(confirmationId);
+        this.statistics.pendingRequests--;
+        this.statistics.timedOutRequests++;
+        // Calculate response time (timeout duration)
+        const responseTime = Date.now() - request.timestamp;
+        // Check if auto-approve on timeout is enabled
+        const shouldAutoApprove = this.config.autoApproveOnTimeout === true;
+        // Log audit trail if enabled
+        if (this.config.auditLogging) {
+            this.logAuditEvent("confirmation-timeout", {
+                confirmationId,
+                toolName: request.toolName,
+                timeout: this.config.timeout,
+                arguments: request.arguments,
+                autoApproved: shouldAutoApprove,
+            });
+        }
+        // Create timeout event
+        const timeoutEvent = {
+            type: "hitl:timeout",
+            payload: {
+                confirmationId,
+                toolName: request.toolName,
+                timeout: this.config.timeout,
+            },
+        };
+        // Emit timeout event
+        this.emit("hitl:timeout", timeoutEvent);
+        if (shouldAutoApprove) {
+            // Auto-approve the request
+            this.statistics.approvedRequests++;
+            // Update average response time
+            const totalResponses = this.statistics.approvedRequests + this.statistics.rejectedRequests;
+            this.statistics.averageResponseTime =
+                (this.statistics.averageResponseTime * (totalResponses - 1) +
+                    responseTime) /
+                    totalResponses;
+            // Log auto-approval if enabled
+            if (this.config.auditLogging) {
+                this.logAuditEvent("confirmation-auto-approved", {
+                    confirmationId,
+                    toolName: request.toolName,
+                    reason: "Auto-approved due to timeout",
+                    responseTime,
+                    arguments: request.arguments,
+                });
+            }
+            // Resolve with auto-approval
+            const result = {
+                approved: true,
+                reason: "Auto-approved due to timeout",
+                responseTime,
+            };
+            request.resolve(result);
+        }
+        else {
+            // Reject with timeout error (original behavior)
+            request.reject(new HITLTimeoutError(`Confirmation timeout for tool: ${request.toolName}`, confirmationId, this.config.timeout));
+        }
+    }
+    /**
+     * Set up event handlers for processing responses
+     */
+    setupEventHandlers() {
+        this.on("hitl:confirmation-response", (event) => {
+            if (event.payload?.confirmationId) {
+                this.processUserResponse(event.payload.confirmationId, {
+                    approved: event.payload.approved,
+                    reason: event.payload.reason,
+                    modifiedArguments: event.payload.modifiedArguments,
+                    responseTime: event.payload.metadata?.responseTime,
+                    userId: event.payload.metadata?.userId,
+                });
+            }
+        });
+    }
+    /**
+     * Generate unique confirmation ID
+     */
+    generateConfirmationId() {
+        return `hitl-${Date.now()}-${randomUUID()}`;
+    }
+    /**
+     * Generate human-readable action description
+     */
+    generateActionDescription(toolName, args) {
+        const lowerToolName = toolName.toLowerCase();
+        // Check for specific action types
+        if (lowerToolName.includes("delete")) {
+            return "Delete Operation";
+        }
+        if (lowerToolName.includes("remove")) {
+            return "Remove Operation";
+        }
+        if (lowerToolName.includes("update")) {
+            return "Update Operation";
+        }
+        if (lowerToolName.includes("create")) {
+            return "Create Operation";
+        }
+        if (lowerToolName.includes("drop")) {
+            return "Drop Operation";
+        }
+        if (lowerToolName.includes("truncate")) {
+            return "Truncate Operation";
+        }
+        if (lowerToolName.includes("restart")) {
+            return "Restart Operation";
+        }
+        if (lowerToolName.includes("stop")) {
+            return "Stop Operation";
+        }
+        if (lowerToolName.includes("kill")) {
+            return "Kill Operation";
+        }
+        // Check custom rules for custom messages
+        if (this.config.customRules) {
+            for (const rule of this.config.customRules) {
+                try {
+                    if (rule.condition(toolName, args) && rule.customMessage) {
+                        return rule.customMessage;
+                    }
+                }
+                catch {
+                    // Ignore rule evaluation errors
+                }
+            }
+        }
+        return `Execute ${toolName}`;
+    }
+    /**
+     * Get keywords that triggered HITL
+     */
+    getTriggeredKeywords(toolName, args) {
+        const triggered = [];
+        const lowerToolName = toolName.toLowerCase();
+        // Check dangerous actions
+        for (const action of this.config.dangerousActions) {
+            if (lowerToolName.includes(action.toLowerCase())) {
+                triggered.push(action);
+            }
+        }
+        // Check custom rules
+        if (this.config.customRules) {
+            for (const rule of this.config.customRules) {
+                try {
+                    if (rule.requiresConfirmation && rule.condition(toolName, args)) {
+                        triggered.push(rule.name);
+                    }
+                }
+                catch {
+                    // Ignore rule evaluation errors
+                }
+            }
+        }
+        return triggered;
+    }
+    /**
+     * Log audit events for compliance and debugging
+     */
+    logAuditEvent(eventType, data) {
+        const auditLog = {
+            timestamp: new Date().toISOString(),
+            eventType: eventType,
+            toolName: data.toolName,
+            userId: data.userId,
+            sessionId: data.sessionId,
+            arguments: data.arguments,
+            reason: data.reason,
+            responseTime: data.responseTime,
+            ...data,
+        };
+        logger.info(`[HITL Audit] ${eventType}:`, auditLog);
+        // Emit audit event for external logging systems
+        this.emit("hitl:audit", auditLog);
+    }
+    /**
+     * Get current HITL usage statistics
+     */
+    getStatistics() {
+        return { ...this.statistics };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration (for dynamic reconfiguration)
+     */
+    updateConfig(newConfig) {
+        const updatedConfig = { ...this.config, ...newConfig };
+        this.config = this.validateConfig(updatedConfig);
+        if (this.config.auditLogging) {
+            this.logAuditEvent("configuration-updated", {
+                oldConfig: this.config,
+                newConfig: updatedConfig,
+            });
+        }
+    }
+    /**
+     * Clean up resources and reject pending confirmations
+     */
+    cleanup() {
+        // Clear all pending confirmations
+        for (const [confirmationId, request] of this.pendingConfirmations) {
+            clearTimeout(request.timeoutHandle);
+            request.reject(new Error(`HITL cleanup: confirmation ${confirmationId} cancelled`));
+        }
+        this.pendingConfirmations.clear();
+        this.statistics.pendingRequests = 0;
+        if (this.config.auditLogging) {
+            this.logAuditEvent("manager-cleanup", {
+                clearedConfirmations: this.pendingConfirmations.size,
+            });
+        }
+    }
+    /**
+     * Check if manager is currently enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Get count of pending confirmations
+     */
+    getPendingCount() {
+        return this.pendingConfirmations.size;
+    }
+}

package/dist/lib/hitl/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HITL (Human-in-the-Loop) Module
+ *
+ * Simple barrel export for HITL components.
+ */
+export { HITLManager } from "./hitlManager.js";
+export type { HITLConfig, HITLRule, ConfirmationRequest, ConfirmationResult, ConfirmationRequestEvent, ConfirmationResponseEvent, ConfirmationTimeoutEvent, HITLStatistics, HITLAuditLog, } from "./types.js";
+export { HITLError, HITLUserRejectedError, HITLTimeoutError, HITLConfigurationError, } from "./hitlErrors.js";

package/dist/lib/hitl/index.js

@@ -0,0 +1,9 @@
+/**
+ * HITL (Human-in-the-Loop) Module
+ *
+ * Simple barrel export for HITL components.
+ */
+// Core HITL Manager
+export { HITLManager } from "./hitlManager.js";
+// Error Classes
+export { HITLError, HITLUserRejectedError, HITLTimeoutError, HITLConfigurationError, } from "./hitlErrors.js";

package/dist/lib/hitl/types.d.ts

@@ -0,0 +1,196 @@
+/**
+ * HITL (Human-in-the-Loop) Type Definitions
+ *
+ * Comprehensive TypeScript interfaces for the HITL safety system.
+ * These types ensure type safety and provide clear contracts for
+ * all HITL-related functionality.
+ */
+/**
+ * Core HITL configuration interface
+ * Controls how the HITL system behaves and what tools require confirmation
+ */
+export interface HITLConfig {
+    /** Master enable/disable switch for HITL functionality */
+    enabled: boolean;
+    /** Keywords that trigger HITL confirmation (e.g., "delete", "remove", "drop") */
+    dangerousActions: string[];
+    /** Timeout in milliseconds for user confirmation (default: 30000) */
+    timeout?: number;
+    /** Communication method - currently only "event" is supported (default: "event") */
+    confirmationMethod?: "event";
+    /** Whether users can modify tool arguments during approval (default: true) */
+    allowArgumentModification?: boolean;
+    /** Auto-approve requests when they timeout (default: false - rejects on timeout) */
+    autoApproveOnTimeout?: boolean;
+    /** Enable audit logging for compliance and debugging (default: false) */
+    auditLogging?: boolean;
+    /** Advanced custom rules for complex tool scenarios (default: []) */
+    customRules?: HITLRule[];
+}
+/**
+ * Custom rule for advanced HITL scenarios
+ * Allows enterprises to define complex conditions for when tools require confirmation
+ */
+export interface HITLRule {
+    /** Human-readable name for the rule */
+    name: string;
+    /** Function that determines if a tool requires confirmation */
+    condition: (toolName: string, args: unknown) => boolean;
+    /** Whether this rule requires confirmation when triggered */
+    requiresConfirmation: boolean;
+    /** Custom message to show users when this rule is triggered */
+    customMessage?: string;
+}
+/**
+ * Internal confirmation request tracking
+ * Used by HITLManager to track pending confirmations
+ */
+export interface ConfirmationRequest {
+    /** Unique identifier for this confirmation request */
+    confirmationId: string;
+    /** Name of the tool requiring confirmation */
+    toolName: string;
+    /** Arguments that will be passed to the tool */
+    arguments: unknown;
+    /** Timestamp when the request was created */
+    timestamp: number;
+    /** Timeout handle for cleanup */
+    timeoutHandle: NodeJS.Timeout;
+    /** Promise resolve function */
+    resolve: (result: ConfirmationResult) => void;
+    /** Promise reject function */
+    reject: (error: Error) => void;
+}
+/**
+ * Result of a confirmation request
+ * Contains user decision and potentially modified arguments
+ */
+export interface ConfirmationResult {
+    /** Whether the user approved the tool execution */
+    approved: boolean;
+    /** Optional reason for rejection (if approved is false) */
+    reason?: string;
+    /** User-modified arguments (if allowArgumentModification is enabled) */
+    modifiedArguments?: unknown;
+    /** Time taken for user to respond in milliseconds */
+    responseTime: number;
+}
+/**
+ * Event payload for confirmation requests
+ * Sent to frontends via EventEmitter when tool needs approval
+ */
+export interface ConfirmationRequestEvent {
+    type: "hitl:confirmation-request";
+    payload: {
+        /** Unique ID for tracking this request */
+        confirmationId: string;
+        /** Name of the tool requiring confirmation */
+        toolName: string;
+        /** MCP server ID (if this is an external tool) */
+        serverId?: string;
+        /** Human-readable description of the action */
+        actionType: string;
+        /** Tool parameters for user review */
+        arguments: unknown;
+        /** Additional metadata about the request */
+        metadata: {
+            /** ISO timestamp when request was created */
+            timestamp: string;
+            /** User session identifier */
+            sessionId?: string;
+            /** User identifier */
+            userId?: string;
+            /** Keywords that triggered HITL */
+            dangerousKeywords: string[];
+        };
+        /** Confirmation timeout in milliseconds */
+        timeoutMs: number;
+        /** Whether user can modify arguments */
+        allowModification: boolean;
+    };
+}
+/**
+ * Event payload for confirmation responses
+ * Sent from frontends back to HITLManager with user decision
+ */
+export interface ConfirmationResponseEvent {
+    type: "hitl:confirmation-response";
+    payload: {
+        /** Matching confirmation ID from the request */
+        confirmationId: string;
+        /** User's approval decision */
+        approved: boolean;
+        /** Optional reason for rejection */
+        reason?: string;
+        /** User-edited parameters (if modification allowed) */
+        modifiedArguments?: unknown;
+        /** Response metadata */
+        metadata: {
+            /** ISO timestamp when user responded */
+            timestamp: string;
+            /** Time taken to respond in milliseconds */
+            responseTime: number;
+            /** User who made the decision */
+            userId?: string;
+        };
+    };
+}
+/**
+ * Event payload for confirmation timeouts
+ * Emitted when user doesn't respond within timeout period
+ */
+export interface ConfirmationTimeoutEvent {
+    type: "hitl:timeout";
+    payload: {
+        /** Confirmation ID that timed out */
+        confirmationId: string;
+        /** Tool name that timed out */
+        toolName: string;
+        /** Timeout duration in milliseconds */
+        timeout: number;
+    };
+}
+/**
+ * HITL audit log entry
+ * Used for compliance and debugging purposes
+ */
+export interface HITLAuditLog {
+    /** ISO timestamp of the event */
+    timestamp: string;
+    /** Type of HITL event */
+    eventType: "confirmation-requested" | "confirmation-approved" | "confirmation-rejected" | "confirmation-timeout" | "confirmation-auto-approved";
+    /** Tool that was involved */
+    toolName: string;
+    /** User who made the decision (if applicable) */
+    userId?: string;
+    /** Session identifier */
+    sessionId?: string;
+    /** Tool arguments (may be sanitized for security) */
+    arguments: unknown;
+    /** Reason for rejection (if applicable) */
+    reason?: string;
+    /** IP address of the user (if available) */
+    ipAddress?: string;
+    /** User agent string (if available) */
+    userAgent?: string;
+    /** Response time in milliseconds (if applicable) */
+    responseTime?: number;
+}
+/**
+ * HITL statistics interface
+ * Provides metrics about HITL usage for monitoring
+ */
+export interface HITLStatistics {
+    /** Total number of confirmation requests made */
+    totalRequests: number;
+    /** Number of pending confirmations */
+    pendingRequests: number;
+    /** Average response time for user decisions */
+    averageResponseTime: number;
+    /** Number of approved requests */
+    approvedRequests: number;
+    /** Number of rejected requests */
+    rejectedRequests: number;
+    /** Number of timed out requests */
+    timedOutRequests: number;
+}

package/dist/lib/hitl/types.js

@@ -0,0 +1,8 @@
+/**
+ * HITL (Human-in-the-Loop) Type Definitions
+ *
+ * Comprehensive TypeScript interfaces for the HITL safety system.
+ * These types ensure type safety and provide clear contracts for
+ * all HITL-related functionality.
+ */
+export {};