@juspay/neurolink 9.26.2 → 9.28.0

package/dist/lib/mcp/elicitation/elicitationManager.js

@@ -0,0 +1,377 @@
+/**
+ * Elicitation Manager
+ *
+ * Manager for handling elicitation requests during tool execution.
+ * Enables MCP tools to request interactive user input mid-execution.
+ *
+ * @module mcp/elicitation/elicitationManager
+ * @since 8.39.0
+ */
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import { logger } from "../../utils/logger.js";
+/**
+ * Manager for handling elicitation requests during tool execution
+ *
+ * The elicitation protocol allows MCP tools to request interactive user input
+ * mid-execution. This is useful for:
+ * - Confirming destructive operations
+ * - Requesting missing information
+ * - Getting user preferences
+ * - Handling authentication challenges
+ *
+ * @example
+ * ```typescript
+ * const elicitationManager = new ElicitationManager({
+ *   defaultTimeout: 60000,
+ *   handler: async (request) => {
+ *     // Implement UI prompt based on request type
+ *     if (request.type === "confirmation") {
+ *       const confirmed = await showConfirmDialog(request.message);
+ *       return {
+ *         requestId: request.id,
+ *         responded: true,
+ *         value: confirmed,
+ *         timestamp: Date.now(),
+ *       };
+ *     }
+ *     // Handle other types...
+ *   },
+ * });
+ *
+ * // Use in a tool
+ * const response = await elicitationManager.request({
+ *   type: "confirmation",
+ *   message: "Are you sure you want to delete this file?",
+ *   toolName: "deleteFile",
+ * });
+ *
+ * if (response.value === true) {
+ *   // Proceed with deletion
+ * }
+ * ```
+ */
+export class ElicitationManager extends EventEmitter {
+    config;
+    pendingRequests = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = {
+            defaultTimeout: config.defaultTimeout ?? 60000,
+            enabled: config.enabled ?? true,
+            handler: config.handler ?? this.defaultHandler.bind(this),
+            fallbackBehavior: config.fallbackBehavior ?? "timeout",
+        };
+    }
+    /**
+     * Set the elicitation handler
+     */
+    setHandler(handler) {
+        this.config.handler = handler;
+    }
+    /**
+     * Enable or disable elicitation
+     */
+    setEnabled(enabled) {
+        this.config.enabled = enabled;
+        if (!enabled) {
+            // Resolve all pending requests with timeout/default
+            for (const [requestId, pending] of this.pendingRequests) {
+                if (pending.settled) {
+                    continue;
+                }
+                pending.settled = true;
+                this.handleDisabled(pending.request, pending.resolve);
+                if (pending.timer) {
+                    clearTimeout(pending.timer);
+                }
+                this.pendingRequests.delete(requestId);
+            }
+        }
+    }
+    /**
+     * Check if elicitation is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Request user input
+     */
+    async request(elicitation) {
+        const request = {
+            ...elicitation,
+            id: elicitation.id ?? randomUUID(),
+        };
+        // If disabled, handle according to fallback behavior
+        if (!this.config.enabled) {
+            return this.handleDisabledRequest(request);
+        }
+        const timeout = request.timeout ?? this.config.defaultTimeout;
+        return new Promise((resolve) => {
+            // Set up timeout
+            const timer = setTimeout(() => {
+                const pending = this.pendingRequests.get(request.id);
+                if (!pending || pending.settled) {
+                    return;
+                }
+                pending.settled = true;
+                this.handleTimeout(request, resolve);
+            }, timeout);
+            // Store pending request with shared settled flag
+            this.pendingRequests.set(request.id, {
+                request,
+                resolve,
+                timer,
+                settled: false,
+            });
+            // Emit request event
+            this.emit("elicitationRequested", request);
+            // Call handler (wrapped to catch synchronous throws)
+            Promise.resolve()
+                .then(() => this.config.handler(request))
+                .then((response) => {
+                const pending = this.pendingRequests.get(request.id);
+                if (!pending || pending.settled) {
+                    return;
+                }
+                pending.settled = true;
+                clearTimeout(timer);
+                this.pendingRequests.delete(request.id);
+                this.emit("elicitationResponded", response);
+                resolve(response);
+            })
+                .catch((error) => {
+                const pending = this.pendingRequests.get(request.id);
+                if (!pending || pending.settled) {
+                    return;
+                }
+                pending.settled = true;
+                clearTimeout(timer);
+                this.pendingRequests.delete(request.id);
+                const errorResponse = {
+                    requestId: request.id,
+                    responded: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    timestamp: Date.now(),
+                };
+                this.emit("elicitationError", { request, error });
+                resolve(errorResponse);
+            });
+        });
+    }
+    /**
+     * Convenience method for confirmation requests
+     */
+    async confirm(message, options) {
+        const request = {
+            type: "confirmation",
+            message,
+            toolName: options?.toolName ?? "unknown",
+            serverId: options?.serverId,
+            confirmLabel: options?.confirmLabel,
+            cancelLabel: options?.cancelLabel,
+            timeout: options?.timeout,
+        };
+        const response = await this.request(request);
+        return response.value === true;
+    }
+    /**
+     * Convenience method for text input
+     */
+    async getText(message, options) {
+        const request = {
+            type: "text",
+            message,
+            toolName: options?.toolName ?? "unknown",
+            placeholder: options?.placeholder,
+            defaultValue: options?.defaultValue,
+            timeout: options?.timeout,
+        };
+        const response = await this.request(request);
+        return response.value;
+    }
+    /**
+     * Convenience method for selection
+     */
+    async select(message, options, config) {
+        const request = {
+            type: "select",
+            message,
+            toolName: config?.toolName ?? "unknown",
+            options: options,
+            timeout: config?.timeout,
+        };
+        const response = await this.request(request);
+        return response.value;
+    }
+    /**
+     * Convenience method for multiple selection
+     */
+    async multiSelect(message, options, config) {
+        const request = {
+            type: "multiselect",
+            message,
+            toolName: config?.toolName ?? "unknown",
+            options: options,
+            timeout: config?.timeout,
+            minSelections: config?.minSelections,
+            maxSelections: config?.maxSelections,
+        };
+        const response = await this.request(request);
+        return response.value;
+    }
+    /**
+     * Convenience method for form input
+     */
+    async form(message, fields, config) {
+        const request = {
+            type: "form",
+            message,
+            toolName: config?.toolName ?? "unknown",
+            serverId: config?.serverId,
+            fields,
+            submitLabel: config?.submitLabel,
+            timeout: config?.timeout,
+        };
+        const response = await this.request(request);
+        return response.value;
+    }
+    /**
+     * Convenience method for secret input
+     */
+    async getSecret(message, options) {
+        const request = {
+            type: "secret",
+            message,
+            toolName: options?.toolName ?? "unknown",
+            hint: options?.hint,
+            timeout: options?.timeout,
+        };
+        const response = await this.request(request);
+        return response.value;
+    }
+    /**
+     * Cancel a pending request
+     */
+    cancel(requestId, reason) {
+        const pending = this.pendingRequests.get(requestId);
+        if (pending) {
+            if (pending.settled) {
+                return;
+            }
+            pending.settled = true;
+            if (pending.timer) {
+                clearTimeout(pending.timer);
+            }
+            const response = {
+                requestId,
+                responded: false,
+                cancelled: true,
+                error: reason,
+                timestamp: Date.now(),
+            };
+            pending.resolve(response);
+            this.pendingRequests.delete(requestId);
+            this.emit("elicitationCancelled", { requestId, reason });
+        }
+    }
+    /**
+     * Default handler when none is provided
+     */
+    async defaultHandler(request) {
+        logger.warn(`[ElicitationManager] No handler for elicitation request: ${request.id}`);
+        // If there's a default value, use it
+        if (request.defaultValue !== undefined) {
+            return {
+                requestId: request.id,
+                responded: true,
+                value: request.defaultValue,
+                timestamp: Date.now(),
+            };
+        }
+        // Otherwise, return not responded
+        return {
+            requestId: request.id,
+            responded: false,
+            error: "No elicitation handler configured",
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Handle timeout
+     */
+    handleTimeout(request, resolve) {
+        this.pendingRequests.delete(request.id);
+        const response = {
+            requestId: request.id,
+            responded: false,
+            timedOut: true,
+            value: request.defaultValue,
+            timestamp: Date.now(),
+        };
+        this.emit("elicitationTimeout", { request });
+        resolve(response);
+    }
+    /**
+     * Handle disabled elicitation
+     */
+    handleDisabled(request, resolve) {
+        resolve(this.handleDisabledRequest(request));
+    }
+    /**
+     * Handle disabled request based on fallback behavior
+     */
+    handleDisabledRequest(request) {
+        switch (this.config.fallbackBehavior) {
+            case "default":
+                return {
+                    requestId: request.id,
+                    responded: request.defaultValue !== undefined,
+                    value: request.defaultValue,
+                    timestamp: Date.now(),
+                };
+            case "error":
+                return {
+                    requestId: request.id,
+                    responded: false,
+                    error: "Elicitation is disabled",
+                    timestamp: Date.now(),
+                };
+            case "timeout":
+            default:
+                return {
+                    requestId: request.id,
+                    responded: false,
+                    timedOut: true,
+                    value: request.defaultValue,
+                    timestamp: Date.now(),
+                };
+        }
+    }
+    /**
+     * Get pending request count
+     */
+    getPendingCount() {
+        return this.pendingRequests.size;
+    }
+    /**
+     * Get all pending requests
+     */
+    getPendingRequests() {
+        return Array.from(this.pendingRequests.values()).map((p) => p.request);
+    }
+    /**
+     * Clear all pending requests
+     */
+    clearPending(reason) {
+        for (const [requestId] of this.pendingRequests) {
+            this.cancel(requestId, reason ?? "Cleared");
+        }
+    }
+}
+/**
+ * Global elicitation manager instance
+ */
+export const globalElicitationManager = new ElicitationManager();
+//# sourceMappingURL=elicitationManager.js.map

package/dist/lib/mcp/elicitation/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Elicitation Protocol Module
+ *
+ * Exports for the MCP elicitation protocol that enables tools
+ * to request interactive user input during execution.
+ *
+ * @module mcp/elicitation
+ * @since 8.39.0
+ */
+export type { ElicitationType, ElicitationRequest, ConfirmationElicitation, TextElicitation, SelectOption, SelectElicitation, MultiSelectElicitation, FormField, FormElicitation, FileElicitation, SecretElicitation, Elicitation, ElicitationResponse, ElicitationHandler, ElicitationManagerConfig, ElicitationContext, } from "./types.js";
+export { ElicitationManager, globalElicitationManager, } from "./elicitationManager.js";

package/dist/lib/mcp/elicitation/index.js

@@ -0,0 +1,12 @@
+/**
+ * Elicitation Protocol Module
+ *
+ * Exports for the MCP elicitation protocol that enables tools
+ * to request interactive user input during execution.
+ *
+ * @module mcp/elicitation
+ * @since 8.39.0
+ */
+// Manager
+export { ElicitationManager, globalElicitationManager, } from "./elicitationManager.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/mcp/elicitation/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Elicitation Protocol Types
+ *
+ * Type definitions for the MCP elicitation protocol that enables
+ * tools to request interactive user input during execution.
+ *
+ * @module mcp/elicitation/types
+ * @since 8.39.0
+ */
+import type { JsonValue, JsonObject } from "../../types/common.js";
+/**
+ * Elicitation request types
+ */
+export type ElicitationType = "confirmation" | "text" | "select" | "multiselect" | "form" | "file" | "secret";
+/**
+ * Base elicitation request
+ */
+export type ElicitationRequest = {
+    /**
+     * Unique request identifier
+     */
+    id: string;
+    /**
+     * Type of elicitation
+     */
+    type: ElicitationType;
+    /**
+     * Message to display to user
+     */
+    message: string;
+    /**
+     * Tool requesting the elicitation
+     */
+    toolName: string;
+    /**
+     * Server ID of the requesting tool
+     */
+    serverId?: string;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Whether the request can be skipped
+     */
+    optional?: boolean;
+    /**
+     * Default value if skipped or timed out
+     */
+    defaultValue?: JsonValue;
+    /**
+     * Additional context for the request
+     */
+    context?: JsonObject;
+};
+/**
+ * Confirmation elicitation
+ */
+export type ConfirmationElicitation = ElicitationRequest & {
+    type: "confirmation";
+    /**
+     * Confirm button label
+     */
+    confirmLabel?: string;
+    /**
+     * Cancel button label
+     */
+    cancelLabel?: string;
+};
+/**
+ * Text input elicitation
+ */
+export type TextElicitation = ElicitationRequest & {
+    type: "text";
+    /**
+     * Input placeholder
+     */
+    placeholder?: string;
+    /**
+     * Minimum length
+     */
+    minLength?: number;
+    /**
+     * Maximum length
+     */
+    maxLength?: number;
+    /**
+     * Validation regex pattern
+     */
+    pattern?: string;
+    /**
+     * Whether to allow multiline input
+     */
+    multiline?: boolean;
+};
+/**
+ * Selection option
+ */
+export type SelectOption = {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+};
+/**
+ * Select elicitation
+ */
+export type SelectElicitation = ElicitationRequest & {
+    type: "select";
+    options: SelectOption[];
+};
+/**
+ * Multi-select elicitation
+ */
+export type MultiSelectElicitation = ElicitationRequest & {
+    type: "multiselect";
+    options: SelectOption[];
+    minSelections?: number;
+    maxSelections?: number;
+};
+/**
+ * Form field definition
+ */
+export type FormField = {
+    name: string;
+    label: string;
+    type: "text" | "number" | "boolean" | "select" | "date" | "password";
+    required?: boolean;
+    defaultValue?: JsonValue;
+    options?: SelectOption[];
+    validation?: {
+        min?: number;
+        max?: number;
+        pattern?: string;
+        message?: string;
+    };
+    placeholder?: string;
+    description?: string;
+};
+/**
+ * Form elicitation
+ */
+export type FormElicitation = ElicitationRequest & {
+    type: "form";
+    fields: FormField[];
+    submitLabel?: string;
+};
+/**
+ * File elicitation
+ */
+export type FileElicitation = ElicitationRequest & {
+    type: "file";
+    /**
+     * Accepted file types (MIME types or extensions)
+     */
+    accept?: string[];
+    /**
+     * Allow multiple files
+     */
+    multiple?: boolean;
+    /**
+     * Maximum file size in bytes
+     */
+    maxSize?: number;
+};
+/**
+ * Secret elicitation
+ */
+export type SecretElicitation = ElicitationRequest & {
+    type: "secret";
+    /**
+     * Hint about what secret is needed
+     */
+    hint?: string;
+};
+/**
+ * Union of all elicitation types
+ */
+export type Elicitation = ConfirmationElicitation | TextElicitation | SelectElicitation | MultiSelectElicitation | FormElicitation | FileElicitation | SecretElicitation;
+/**
+ * Elicitation response
+ */
+export type ElicitationResponse = {
+    /**
+     * Request ID this responds to
+     */
+    requestId: string;
+    /**
+     * Whether the user provided a response
+     */
+    responded: boolean;
+    /**
+     * The user's response value
+     */
+    value?: JsonValue;
+    /**
+     * Whether the request was cancelled
+     */
+    cancelled?: boolean;
+    /**
+     * Whether the request timed out
+     */
+    timedOut?: boolean;
+    /**
+     * Error message if response failed
+     */
+    error?: string;
+    /**
+     * Response timestamp
+     */
+    timestamp: number;
+};
+/**
+ * Elicitation handler function type
+ */
+export type ElicitationHandler = (request: Elicitation) => Promise<ElicitationResponse>;
+/**
+ * Elicitation manager configuration
+ */
+export type ElicitationManagerConfig = {
+    /**
+     * Default timeout for elicitation requests
+     */
+    defaultTimeout?: number;
+    /**
+     * Whether to allow elicitation (can be disabled for automated environments)
+     */
+    enabled?: boolean;
+    /**
+     * Handler for processing elicitation requests
+     */
+    handler?: ElicitationHandler;
+    /**
+     * Fallback behavior when no handler is available
+     */
+    fallbackBehavior?: "timeout" | "default" | "error";
+};
+/**
+ * Elicitation context passed to tools
+ */
+export type ElicitationContext = {
+    /**
+     * Request user confirmation
+     */
+    confirm: (message: string, options?: {
+        confirmLabel?: string;
+        cancelLabel?: string;
+    }) => Promise<boolean>;
+    /**
+     * Request text input
+     */
+    getText: (message: string, options?: {
+        placeholder?: string;
+        defaultValue?: string;
+    }) => Promise<string | undefined>;
+    /**
+     * Request selection
+     */
+    select: <T extends string>(message: string, options: Array<{
+        value: T;
+        label: string;
+    }>) => Promise<T | undefined>;
+    /**
+     * Request multiple selections
+     */
+    multiSelect: <T extends string>(message: string, options: Array<{
+        value: T;
+        label: string;
+    }>) => Promise<T[] | undefined>;
+    /**
+     * Request form input
+     */
+    form: <T extends Record<string, unknown>>(message: string, fields: FormField[]) => Promise<T | undefined>;
+    /**
+     * Request raw elicitation
+     */
+    request: (elicitation: Omit<Elicitation, "id">) => Promise<ElicitationResponse>;
+};

package/dist/lib/mcp/elicitation/types.js

@@ -0,0 +1,11 @@
+/**
+ * Elicitation Protocol Types
+ *
+ * Type definitions for the MCP elicitation protocol that enables
+ * tools to request interactive user input during execution.
+ *
+ * @module mcp/elicitation/types
+ * @since 8.39.0
+ */
+export {};
+//# sourceMappingURL=types.js.map