@juspay/neurolink 7.38.1 → 7.39.0

package/dist/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/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 {};

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

@@ -0,0 +1,38 @@
+/**
+ * HITL (Human-in-the-Loop) Error Classes
+ *
+ * Provides structured error handling for HITL safety mechanisms.
+ * These errors allow applications to distinguish between different
+ * types of HITL failures and handle them appropriately.
+ */
+/**
+ * Base class for all HITL-related errors
+ */
+export declare class HITLError extends Error {
+    readonly confirmationId?: string | undefined;
+    constructor(message: string, confirmationId?: string | undefined);
+}
+/**
+ * Thrown when a user explicitly rejects a tool execution request
+ * This indicates the HITL system worked correctly - the user saw the request
+ * and made a conscious decision to deny it.
+ */
+export declare class HITLUserRejectedError extends HITLError {
+    readonly toolName: string;
+    readonly reason?: string | undefined;
+    constructor(message: string, toolName: string, reason?: string | undefined, confirmationId?: string);
+}
+/**
+ * Thrown when a confirmation request times out without user response
+ * This indicates the user didn't respond within the configured timeout period.
+ */
+export declare class HITLTimeoutError extends HITLError {
+    readonly timeout: number;
+    constructor(message: string, confirmationId: string, timeout: number);
+}
+/**
+ * Thrown when HITL configuration is invalid or missing required properties
+ */
+export declare class HITLConfigurationError extends HITLError {
+    constructor(message: string);
+}

package/dist/lib/hitl/hitlErrors.js

@@ -0,0 +1,54 @@
+/**
+ * HITL (Human-in-the-Loop) Error Classes
+ *
+ * Provides structured error handling for HITL safety mechanisms.
+ * These errors allow applications to distinguish between different
+ * types of HITL failures and handle them appropriately.
+ */
+/**
+ * Base class for all HITL-related errors
+ */
+export class HITLError extends Error {
+    confirmationId;
+    constructor(message, confirmationId) {
+        super(message);
+        this.confirmationId = confirmationId;
+        this.name = "HITLError";
+    }
+}
+/**
+ * Thrown when a user explicitly rejects a tool execution request
+ * This indicates the HITL system worked correctly - the user saw the request
+ * and made a conscious decision to deny it.
+ */
+export class HITLUserRejectedError extends HITLError {
+    toolName;
+    reason;
+    constructor(message, toolName, reason, confirmationId) {
+        super(message, confirmationId);
+        this.toolName = toolName;
+        this.reason = reason;
+        this.name = "HITLUserRejectedError";
+    }
+}
+/**
+ * Thrown when a confirmation request times out without user response
+ * This indicates the user didn't respond within the configured timeout period.
+ */
+export class HITLTimeoutError extends HITLError {
+    timeout;
+    constructor(message, confirmationId, timeout) {
+        super(message, confirmationId);
+        this.timeout = timeout;
+        this.name = "HITLTimeoutError";
+    }
+}
+/**
+ * Thrown when HITL configuration is invalid or missing required properties
+ */
+export class HITLConfigurationError extends HITLError {
+    constructor(message) {
+        super(message);
+        this.name = "HITLConfigurationError";
+    }
+}

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

@@ -0,0 +1,100 @@
+/**
+ * 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 type { HITLConfig, ConfirmationResult, HITLStatistics } from "./types.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 declare class HITLManager extends EventEmitter {
+    private config;
+    private pendingConfirmations;
+    private statistics;
+    constructor(config: HITLConfig);
+    /**
+     * Validate HITL configuration and apply defaults
+     */
+    private validateConfig;
+    /**
+     * Check if a tool requires confirmation based on configuration
+     */
+    requiresConfirmation(toolName: string, args?: unknown): boolean;
+    /**
+     * Request confirmation for a tool execution
+     */
+    requestConfirmation(toolName: string, arguments_: unknown, context?: {
+        serverId?: string;
+        sessionId?: string;
+        userId?: string;
+    }): Promise<ConfirmationResult>;
+    /**
+     * Process user response to confirmation request
+     */
+    processUserResponse(confirmationId: string, response: {
+        approved: boolean;
+        reason?: string;
+        modifiedArguments?: unknown;
+        responseTime?: number;
+        userId?: string;
+    }): void;
+    /**
+     * Handle confirmation timeout
+     */
+    private handleTimeout;
+    /**
+     * Set up event handlers for processing responses
+     */
+    private setupEventHandlers;
+    /**
+     * Generate unique confirmation ID
+     */
+    private generateConfirmationId;
+    /**
+     * Generate human-readable action description
+     */
+    private generateActionDescription;
+    /**
+     * Get keywords that triggered HITL
+     */
+    private getTriggeredKeywords;
+    /**
+     * Log audit events for compliance and debugging
+     */
+    private logAuditEvent;
+    /**
+     * Get current HITL usage statistics
+     */
+    getStatistics(): HITLStatistics;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HITLConfig;
+    /**
+     * Update configuration (for dynamic reconfiguration)
+     */
+    updateConfig(newConfig: Partial<HITLConfig>): void;
+    /**
+     * Clean up resources and reject pending confirmations
+     */
+    cleanup(): void;
+    /**
+     * Check if manager is currently enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get count of pending confirmations
+     */
+    getPendingCount(): number;
+}