@juspay/neurolink 7.29.0 → 7.29.2

package/dist/neurolink.js

@@ -24,6 +24,7 @@ import { ProviderRegistry } from "./factories/providerRegistry.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
 // Factory processing imports
 import { processFactoryOptions, enhanceTextGenerationOptions, validateFactoryConfig, processStreamingFactoryOptions, createCleanStreamOptions, } from "./utils/factoryProcessing.js";
+// Tool detection and execution imports
 // Transformation utilities
 import { transformToolExecutions, transformToolExecutionsForMCP, transformAvailableTools, transformToolsForMCP, transformToolsToExpectedFormat, transformToolsToDescriptions, extractToolNames, transformParamsForLogging, optimizeToolForCollection, } from "./utils/transformationUtils.js";
 // Enhanced error handling imports
@@ -54,17 +55,52 @@ export class NeuroLink {
      * @param toolName - Name of the tool
      * @param startTime - Timestamp when tool execution started
      * @param success - Whether the tool execution was successful
+     * @param result - The result of the tool execution (optional)
+     * @param error - The error if execution failed (optional)
      */
-    emitToolEndEvent(toolName, startTime, success) {
+    emitToolEndEvent(toolName, startTime, success, result, error) {
+        // Emit tool end event (NeuroLink format - enhanced with result/error)
         this.emitter.emit("tool:end", {
             toolName,
             responseTime: Date.now() - startTime,
             success,
             timestamp: Date.now(),
+            result: result, // Enhanced: include actual result
+            error: error, // Enhanced: include error if present
         });
+        // ADD: Bedrock-compatible tool:end event (positional parameters)
+        this.emitter.emit("tool:end", toolName, success ? result : error);
     }
     // Conversation memory support
     conversationMemory;
+    /**
+     * Creates a new NeuroLink instance for AI text generation with MCP tool integration.
+     *
+     * @param config - Optional configuration object
+     * @param config.conversationMemory - Configuration for conversation memory features
+     * @param config.conversationMemory.enabled - Whether to enable conversation memory (default: false)
+     * @param config.conversationMemory.maxSessions - Maximum number of concurrent sessions (default: 100)
+     * @param config.conversationMemory.maxTurnsPerSession - Maximum conversation turns per session (default: 50)
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const neurolink = new NeuroLink();
+     *
+     * // With conversation memory
+     * const neurolink = new NeuroLink({
+     *   conversationMemory: {
+     *     enabled: true,
+     *     maxSessions: 50,
+     *     maxTurnsPerSession: 20
+     *   }
+     * });
+     * ```
+     *
+     * @throws {Error} When provider registry setup fails
+     * @throws {Error} When conversation memory initialization fails (if enabled)
+     * @throws {Error} When external server manager initialization fails
+     */
     constructor(config) {
         // 🚀 EXHAUSTIVE LOGGING POINT C001: CONSTRUCTOR ENTRY
         const constructorStartTime = Date.now();
@@ -724,6 +760,54 @@ export class NeuroLink {
         this.contextManager = new ContextManager(this.generateTextInternal.bind(this), contextConfig);
         logger.info("[NeuroLink] Automatic context summarization enabled.");
     }
+    /**
+     * Generate AI content using the best available provider with MCP tool integration.
+     * This is the primary method for text generation with full feature support.
+     *
+     * @param optionsOrPrompt - Either a string prompt or a comprehensive GenerateOptions object
+     * @param optionsOrPrompt.input - Input configuration object
+     * @param optionsOrPrompt.input.text - The text prompt to send to the AI (required)
+     * @param optionsOrPrompt.provider - AI provider to use ('auto', 'openai', 'anthropic', etc.)
+     * @param optionsOrPrompt.model - Specific model to use (e.g., 'gpt-4', 'claude-3-opus')
+     * @param optionsOrPrompt.temperature - Randomness in response (0.0 = deterministic, 2.0 = very random)
+     * @param optionsOrPrompt.maxTokens - Maximum tokens in response
+     * @param optionsOrPrompt.systemPrompt - System message to set AI behavior
+     * @param optionsOrPrompt.disableTools - Whether to disable MCP tool usage
+     * @param optionsOrPrompt.enableAnalytics - Whether to include usage analytics
+     * @param optionsOrPrompt.enableEvaluation - Whether to include response quality evaluation
+     * @param optionsOrPrompt.context - Additional context for the request
+     * @param optionsOrPrompt.evaluationDomain - Domain for specialized evaluation
+     * @param optionsOrPrompt.toolUsageContext - Context for tool usage decisions
+     *
+     * @returns Promise resolving to GenerateResult with content, usage data, and optional analytics
+     *
+     * @example
+     * ```typescript
+     * // Simple usage with string prompt
+     * const result = await neurolink.generate("What is artificial intelligence?");
+     * console.log(result.content);
+     *
+     * // Advanced usage with options
+     * const result = await neurolink.generate({
+     *   input: { text: "Explain quantum computing" },
+     *   provider: "openai",
+     *   model: "gpt-4",
+     *   temperature: 0.7,
+     *   maxTokens: 500,
+     *   enableAnalytics: true,
+     *   enableEvaluation: true,
+     *   context: { domain: "science", level: "intermediate" }
+     * });
+     *
+     * // Access analytics and evaluation data
+     * console.log(result.analytics?.usage);
+     * console.log(result.evaluation?.relevance);
+     * ```
+     *
+     * @throws {Error} When input text is missing or invalid
+     * @throws {Error} When all providers fail to generate content
+     * @throws {Error} When conversation memory operations fail (if enabled)
+     */
     async generate(optionsOrPrompt) {
         const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
         // Convert string prompt to full options
@@ -740,11 +824,15 @@ export class NeuroLink {
             options.input.text = this.contextManager.getContextForPrompt("user", options.input.text);
         }
         const startTime = Date.now();
-        // Emit generation start event
+        // Emit generation start event (NeuroLink format - keep existing)
         this.emitter.emit("generation:start", {
             provider: options.provider || "auto",
             timestamp: startTime,
         });
+        // ADD: Bedrock-compatible response:start event
+        this.emitter.emit("response:start");
+        // ADD: Bedrock-compatible message event
+        this.emitter.emit("message", `Starting ${options.provider || "auto"} text generation...`);
         // Process factory configuration
         const factoryResult = processFactoryOptions(options);
         // Validate factory configuration if present
@@ -787,13 +875,18 @@ export class NeuroLink {
         }
         // Use redesigned generation logic
         const textResult = await this.generateTextInternal(textOptions);
-        // Emit generation completion event
+        // Emit generation completion event (NeuroLink format - enhanced with content)
         this.emitter.emit("generation:end", {
             provider: textResult.provider,
             responseTime: Date.now() - startTime,
             toolsUsed: textResult.toolsUsed,
             timestamp: Date.now(),
+            result: textResult, // Enhanced: include full result
         });
+        // ADD: Bedrock-compatible response:end event with content
+        this.emitter.emit("response:end", textResult.content || "");
+        // ADD: Bedrock-compatible message event
+        this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
         // Convert back to GenerateResult
         const generateResult = {
             content: textResult.content,
@@ -926,6 +1019,10 @@ export class NeuroLink {
             promptLength: options.prompt?.length || 0,
             hasConversationMemory: !!this.conversationMemory,
         });
+        // ADD: Bedrock-compatible response:start event for generateTextInternal
+        this.emitter.emit("response:start");
+        // ADD: Bedrock-compatible message event for generateTextInternal
+        this.emitter.emit("message", `Starting ${options.provider || "auto"} text generation (internal)...`);
         try {
             // 🚀 EXHAUSTIVE LOGGING POINT G002: CONVERSATION MEMORY INITIALIZATION
             const conversationMemoryStartTime = process.hrtime.bigint();
@@ -1072,6 +1169,8 @@ export class NeuroLink {
                             });
                             // Store conversation turn
                             await storeConversationTurn(this.conversationMemory, options, mcpResult);
+                            // ADD: Bedrock-compatible response:end event for MCP success path
+                            this.emitter.emit("response:end", mcpResult.content || "");
                             return mcpResult;
                         }
                         else {
@@ -1088,6 +1187,8 @@ export class NeuroLink {
                                 logger.debug(`[${functionTag}] Found tool executions but no content, continuing with result`);
                                 // Store conversation turn even with empty content if tools executed
                                 await storeConversationTurn(this.conversationMemory, options, mcpResult);
+                                // ADD: Bedrock-compatible response:end event for MCP tool execution success path
+                                this.emitter.emit("response:end", mcpResult.content || "");
                                 return mcpResult;
                             }
                         }
@@ -1112,12 +1213,20 @@ export class NeuroLink {
             logger.debug(`[${functionTag}] Direct generation successful`);
             // Store conversation turn
             await storeConversationTurn(this.conversationMemory, options, directResult);
+            // ADD: Bedrock-compatible response:end event for generateTextInternal
+            this.emitter.emit("response:end", directResult.content || "");
+            // ADD: Bedrock-compatible message event for generateTextInternal completion
+            this.emitter.emit("message", `Text generation completed successfully`);
             return directResult;
         }
         catch (error) {
             logger.error(`[${functionTag}] All generation methods failed`, {
                 error: error instanceof Error ? error.message : String(error),
             });
+            // ADD: Bedrock-compatible response:end event for error path (empty content)
+            this.emitter.emit("response:end", "");
+            // ADD: Centralized error event emission
+            this.emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
             throw error;
         }
     }
@@ -1223,6 +1332,9 @@ export class NeuroLink {
             // Create provider and generate
             const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
             this);
+            // ADD: Emit connection events for all providers (Bedrock-compatible)
+            this.emitter.emit("connected");
+            this.emitter.emit("message", `${providerName} provider initialized successfully`);
             // Enable tool execution for the provider using BaseProvider method
             provider.setupToolExecutor({
                 customTools: this.getCustomTools(),
@@ -1317,6 +1429,9 @@ export class NeuroLink {
                 const conversationMessages = await getConversationMessages(this.conversationMemory, options);
                 const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
                 this);
+                // ADD: Emit connection events for successful provider creation (Bedrock-compatible)
+                this.emitter.emit("connected");
+                this.emitter.emit("message", `${providerName} provider initialized successfully`);
                 // Enable tool execution for direct provider generation using BaseProvider method
                 provider.setupToolExecutor({
                     customTools: this.getCustomTools(),
@@ -1378,7 +1493,7 @@ export class NeuroLink {
      * Execute tools if available through centralized registry
      * Simplified approach without domain detection - relies on tool registry
      */
-    async detectAndExecuteTools(prompt, domainType) {
+    async detectAndExecuteTools(prompt, _domainType) {
         const functionTag = "NeuroLink.detectAndExecuteTools";
         try {
             // Simplified: Just return original prompt without complex detection
@@ -1439,8 +1554,55 @@ export class NeuroLink {
         return stringStream();
     }
     /**
-     * PRIMARY METHOD: Stream content using AI (recommended for new code)
-     * Future-ready for multi-modal capabilities with current text focus
+     * Stream AI-generated content in real-time using the best available provider.
+     * This method provides real-time streaming of AI responses with full MCP tool integration.
+     *
+     * @param options - Stream configuration options
+     * @param options.input - Input configuration object
+     * @param options.input.text - The text prompt to send to the AI (required)
+     * @param options.provider - AI provider to use ('auto', 'openai', 'anthropic', etc.)
+     * @param options.model - Specific model to use (e.g., 'gpt-4', 'claude-3-opus')
+     * @param options.temperature - Randomness in response (0.0 = deterministic, 2.0 = very random)
+     * @param options.maxTokens - Maximum tokens in response
+     * @param options.systemPrompt - System message to set AI behavior
+     * @param options.disableTools - Whether to disable MCP tool usage
+     * @param options.enableAnalytics - Whether to include usage analytics
+     * @param options.enableEvaluation - Whether to include response quality evaluation
+     * @param options.context - Additional context for the request
+     * @param options.evaluationDomain - Domain for specialized evaluation
+     *
+     * @returns Promise resolving to StreamResult with an async iterable stream
+     *
+     * @example
+     * ```typescript
+     * // Basic streaming usage
+     * const result = await neurolink.stream({
+     *   input: { text: "Tell me a story about space exploration" }
+     * });
+     *
+     * // Consume the stream
+     * for await (const chunk of result.stream) {
+     *   process.stdout.write(chunk.content);
+     * }
+     *
+     * // Advanced streaming with options
+     * const result = await neurolink.stream({
+     *   input: { text: "Explain machine learning" },
+     *   provider: "openai",
+     *   model: "gpt-4",
+     *   temperature: 0.7,
+     *   enableAnalytics: true,
+     *   context: { domain: "education", audience: "beginners" }
+     * });
+     *
+     * // Access metadata and analytics
+     * console.log(result.provider);
+     * console.log(result.analytics?.usage);
+     * ```
+     *
+     * @throws {Error} When input text is missing or invalid
+     * @throws {Error} When all providers fail to generate content
+     * @throws {Error} When conversation memory operations fail (if enabled)
      */
     async stream(options) {
         const startTime = Date.now();
@@ -1546,7 +1708,7 @@ export class NeuroLink {
                         global.gc();
                         return process.memoryUsage();
                     }
-                    catch (e) {
+                    catch (_e) {
                         return null;
                     }
                 })()
@@ -1684,11 +1846,15 @@ export class NeuroLink {
             cpuAfterValidation: process.cpuUsage(),
             message: "EXHAUSTIVE validation success - proceeding with stream processing",
         });
-        // Emit stream start event
+        // Emit stream start event (NeuroLink format - keep existing)
         this.emitter.emit("stream:start", {
             provider: options.provider || "auto",
             timestamp: startTime,
         });
+        // ADD: Bedrock-compatible response:start event
+        this.emitter.emit("response:start");
+        // ADD: Bedrock-compatible message event
+        this.emitter.emit("message", `Starting ${options.provider || "auto"} stream generation...`);
         // Process factory configuration for streaming
         const factoryResult = processFactoryOptions(options);
         const streamingResult = processStreamingFactoryOptions(options);
@@ -1780,6 +1946,8 @@ export class NeuroLink {
                             // Ensure chunk has content property and it's a string
                             if (typeof chunk.content === "string") {
                                 accumulatedContent += chunk.content;
+                                // ADD: Bedrock-compatible response:chunk event
+                                self.emitter.emit("response:chunk", chunk.content);
                             }
                             else if (chunk.content === undefined ||
                                 chunk.content === null) {
@@ -1791,6 +1959,8 @@ export class NeuroLink {
                                 const stringContent = String(chunk.content || "");
                                 processedChunk = { ...chunk, content: stringContent };
                                 accumulatedContent += stringContent;
+                                // ADD: Bedrock-compatible response:chunk event
+                                self.emitter.emit("response:chunk", stringContent);
                             }
                         }
                         else if (chunk === null || chunk === undefined) {
@@ -1827,11 +1997,16 @@ export class NeuroLink {
                 responseTime,
                 provider: providerName,
             });
-            // Emit stream completion event
+            // Emit stream completion event (NeuroLink format - enhanced with content)
             this.emitter.emit("stream:end", {
                 provider: providerName,
                 responseTime,
+                result: { content: accumulatedContent }, // Enhanced: include accumulated content
             });
+            // ADD: Bedrock-compatible response:end event with full response
+            this.emitter.emit("response:end", accumulatedContent);
+            // ADD: Bedrock-compatible message event
+            this.emitter.emit("message", `Stream completed in ${responseTime}ms (${accumulatedContent.length} chars)`);
             // Convert to StreamResult format - Include analytics and evaluation from provider
             return {
                 stream: processedStream,
@@ -1860,6 +2035,8 @@ export class NeuroLink {
             };
         }
         catch (error) {
+            // ADD: Error event emission for MCP streaming failure
+            this.emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
             // Fall back to regular streaming if MCP fails
             mcpLogger.warn(`[${functionTag}] MCP streaming failed, falling back to regular`, {
                 error: error instanceof Error ? error.message : String(error),
@@ -1895,6 +2072,8 @@ export class NeuroLink {
                     for await (const chunk of streamResult.stream) {
                         if (chunk && typeof chunk.content === "string") {
                             fallbackAccumulatedContent += chunk.content;
+                            // ADD: Bedrock-compatible response:chunk event for fallback
+                            self.emitter.emit("response:chunk", chunk.content);
                         }
                         yield chunk; // Preserve original streaming behavior
                     }
@@ -1922,12 +2101,17 @@ export class NeuroLink {
                 }
             })(this);
             const responseTime = Date.now() - startTime;
-            // Emit stream completion event for fallback
+            // Emit stream completion event for fallback (NeuroLink format - enhanced with content)
             this.emitter.emit("stream:end", {
                 provider: providerName,
                 responseTime,
                 fallback: true,
+                result: { content: fallbackAccumulatedContent }, // Enhanced: include accumulated content
             });
+            // ADD: Bedrock-compatible response:end event with full response
+            this.emitter.emit("response:end", fallbackAccumulatedContent);
+            // ADD: Bedrock-compatible message event
+            this.emitter.emit("message", `Fallback stream completed in ${responseTime}ms (${fallbackAccumulatedContent.length} chars)`);
             return {
                 stream: fallbackProcessedStream,
                 provider: providerName,
@@ -1957,8 +2141,178 @@ export class NeuroLink {
         }
     }
     /**
-     * Get the EventEmitter to listen to NeuroLink events
-     * @returns EventEmitter instance
+     * Get the EventEmitter instance to listen to NeuroLink events for real-time monitoring and debugging.
+     * This method provides access to the internal event system that emits events during AI generation,
+     * tool execution, streaming, and other operations for comprehensive observability.
+     *
+     * @returns EventEmitter instance that emits various NeuroLink operation events
+     *
+     * @example
+     * ```typescript
+     * // Basic event listening setup
+     * const neurolink = new NeuroLink();
+     * const emitter = neurolink.getEventEmitter();
+     *
+     * // Listen to generation events
+     * emitter.on('generation:start', (event) => {
+     *   console.log(`Generation started with provider: ${event.provider}`);
+     *   console.log(`Started at: ${new Date(event.timestamp)}`);
+     * });
+     *
+     * emitter.on('generation:end', (event) => {
+     *   console.log(`Generation completed in ${event.responseTime}ms`);
+     *   console.log(`Tools used: ${event.toolsUsed?.length || 0}`);
+     * });
+     *
+     * // Listen to streaming events
+     * emitter.on('stream:start', (event) => {
+     *   console.log(`Streaming started with provider: ${event.provider}`);
+     * });
+     *
+     * emitter.on('stream:end', (event) => {
+     *   console.log(`Streaming completed in ${event.responseTime}ms`);
+     *   if (event.fallback) console.log('Used fallback streaming');
+     * });
+     *
+     * // Listen to tool execution events
+     * emitter.on('tool:start', (event) => {
+     *   console.log(`Tool execution started: ${event.toolName}`);
+     * });
+     *
+     * emitter.on('tool:end', (event) => {
+     *   console.log(`Tool ${event.toolName} ${event.success ? 'succeeded' : 'failed'}`);
+     *   console.log(`Execution time: ${event.responseTime}ms`);
+     * });
+     *
+     * // Listen to tool registration events
+     * emitter.on('tools-register:start', (event) => {
+     *   console.log(`Registering tool: ${event.toolName}`);
+     * });
+     *
+     * emitter.on('tools-register:end', (event) => {
+     *   console.log(`Tool registration ${event.success ? 'succeeded' : 'failed'}: ${event.toolName}`);
+     * });
+     *
+     * // Listen to external MCP server events
+     * emitter.on('externalMCP:serverConnected', (event) => {
+     *   console.log(`External MCP server connected: ${event.serverId}`);
+     *   console.log(`Tools available: ${event.toolCount || 0}`);
+     * });
+     *
+     * emitter.on('externalMCP:serverDisconnected', (event) => {
+     *   console.log(`External MCP server disconnected: ${event.serverId}`);
+     *   console.log(`Reason: ${event.reason || 'Unknown'}`);
+     * });
+     *
+     * emitter.on('externalMCP:toolDiscovered', (event) => {
+     *   console.log(`New tool discovered: ${event.toolName} from ${event.serverId}`);
+     * });
+     *
+     * // Advanced usage with error handling
+     * emitter.on('error', (error) => {
+     *   console.error('NeuroLink error:', error);
+     * });
+     *
+     * // Clean up event listeners when done
+     * function cleanup() {
+     *   emitter.removeAllListeners();
+     * }
+     *
+     * process.on('SIGINT', cleanup);
+     * process.on('SIGTERM', cleanup);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Advanced monitoring with metrics collection
+     * const neurolink = new NeuroLink();
+     * const emitter = neurolink.getEventEmitter();
+     * const metrics = {
+     *   generations: 0,
+     *   totalResponseTime: 0,
+     *   toolExecutions: 0,
+     *   failures: 0
+     * };
+     *
+     * // Collect performance metrics
+     * emitter.on('generation:end', (event) => {
+     *   metrics.generations++;
+     *   metrics.totalResponseTime += event.responseTime;
+     *   metrics.toolExecutions += event.toolsUsed?.length || 0;
+     * });
+     *
+     * emitter.on('tool:end', (event) => {
+     *   if (!event.success) {
+     *     metrics.failures++;
+     *   }
+     * });
+     *
+     * // Log metrics every 10 seconds
+     * setInterval(() => {
+     *   const avgResponseTime = metrics.generations > 0
+     *     ? metrics.totalResponseTime / metrics.generations
+     *     : 0;
+     *
+     *   console.log('NeuroLink Metrics:', {
+     *     totalGenerations: metrics.generations,
+     *     averageResponseTime: `${avgResponseTime.toFixed(2)}ms`,
+     *     totalToolExecutions: metrics.toolExecutions,
+     *     failureRate: `${((metrics.failures / (metrics.toolExecutions || 1)) * 100).toFixed(2)}%`
+     *   });
+     * }, 10000);
+     * ```
+     *
+     * **Available Events:**
+     *
+     * **Generation Events:**
+     * - `generation:start` - Fired when text generation begins
+     *   - `{ provider: string, timestamp: number }`
+     * - `generation:end` - Fired when text generation completes
+     *   - `{ provider: string, responseTime: number, toolsUsed?: string[], timestamp: number }`
+     *
+     * **Streaming Events:**
+     * - `stream:start` - Fired when streaming begins
+     *   - `{ provider: string, timestamp: number }`
+     * - `stream:end` - Fired when streaming completes
+     *   - `{ provider: string, responseTime: number, fallback?: boolean }`
+     *
+     * **Tool Events:**
+     * - `tool:start` - Fired when tool execution begins
+     *   - `{ toolName: string, timestamp: number }`
+     * - `tool:end` - Fired when tool execution completes
+     *   - `{ toolName: string, responseTime: number, success: boolean, timestamp: number }`
+     * - `tools-register:start` - Fired when tool registration begins
+     *   - `{ toolName: string, timestamp: number }`
+     * - `tools-register:end` - Fired when tool registration completes
+     *   - `{ toolName: string, success: boolean, timestamp: number }`
+     *
+     * **External MCP Events:**
+     * - `externalMCP:serverConnected` - Fired when external MCP server connects
+     *   - `{ serverId: string, toolCount?: number, timestamp: number }`
+     * - `externalMCP:serverDisconnected` - Fired when external MCP server disconnects
+     *   - `{ serverId: string, reason?: string, timestamp: number }`
+     * - `externalMCP:serverFailed` - Fired when external MCP server fails
+     *   - `{ serverId: string, error: string, timestamp: number }`
+     * - `externalMCP:toolDiscovered` - Fired when external MCP tool is discovered
+     *   - `{ toolName: string, serverId: string, timestamp: number }`
+     * - `externalMCP:toolRemoved` - Fired when external MCP tool is removed
+     *   - `{ toolName: string, serverId: string, timestamp: number }`
+     * - `externalMCP:serverAdded` - Fired when external MCP server is added
+     *   - `{ serverId: string, config: MCPServerInfo, toolCount: number, timestamp: number }`
+     * - `externalMCP:serverRemoved` - Fired when external MCP server is removed
+     *   - `{ serverId: string, timestamp: number }`
+     *
+     * **Error Events:**
+     * - `error` - Fired when an error occurs
+     *   - `{ error: Error, context?: object }`
+     *
+     * @throws {Error} This method does not throw errors as it returns the internal EventEmitter
+     *
+     * @since 1.0.0
+     * @see {@link https://nodejs.org/api/events.html} Node.js EventEmitter documentation
+     * @see {@link NeuroLink.generate} for events related to text generation
+     * @see {@link NeuroLink.stream} for events related to streaming
+     * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter() {
         return this.emitter;
@@ -1978,7 +2332,7 @@ export class NeuroLink {
             timestamp: Date.now(),
         });
         try {
-            // --- Start: Added Validation Logic ---
+            // --- Start: Enhanced Validation Logic with FlexibleToolValidator ---
             if (!name || typeof name !== "string") {
                 throw new Error("Invalid tool name");
             }
@@ -1988,55 +2342,36 @@ export class NeuroLink {
             if (typeof tool.execute !== "function") {
                 throw new Error(`Tool '${name}' must have an execute method.`);
             }
-            // --- End: Added Validation Logic ---
-            // Import validation functions synchronously - they are pure functions
-            let validateTool;
-            let isToolNameAvailable;
-            let suggestToolNames;
+            // Use FlexibleToolValidator for consistent validation across SDK and toolRegistry
             try {
-                // Try ES module import first
-                const toolRegistrationModule = require("./sdk/toolRegistration.js");
-                ({ validateTool, isToolNameAvailable, suggestToolNames } =
-                    toolRegistrationModule);
+                const flexibleValidatorModule = require("./mcp/flexibleToolValidator.js");
+                const FlexibleToolValidator = flexibleValidatorModule.FlexibleToolValidator;
+                // Use the same validation logic as toolRegistry (static method)
+                const validationResult = FlexibleToolValidator.validateToolName(name);
+                if (!validationResult.isValid) {
+                    throw new Error(`Tool validation failed: ${validationResult.error}`);
+                }
             }
             catch (error) {
-                // Fallback: skip validation if import fails (graceful degradation)
-                logger.warn("Tool validation module not available, skipping advanced validation", {
+                // If FlexibleToolValidator import fails, use basic safety checks
+                logger.warn("FlexibleToolValidator not available, using basic validation", {
                     error: error instanceof Error ? error.message : String(error),
                 });
-                // Create minimal validation functions
-                validateTool = () => { }; // No-op
-                isToolNameAvailable = () => true; // Allow all names
-                suggestToolNames = () => ["alternative_tool"];
-            }
-            // Check if tool name is available (not reserved)
-            if (!isToolNameAvailable(name)) {
-                const suggestions = suggestToolNames(name);
-                throw new Error(`Tool name '${name}' is not available (reserved or invalid format). ` +
-                    `Suggested alternatives: ${suggestions.slice(0, 3).join(", ")}`);
-            }
-            // Create a simplified tool object for validation
-            const toolForValidation = {
-                description: tool.description || "",
-                execute: async (params) => {
-                    if (tool.execute) {
-                        const result = await tool.execute(params);
-                        return result;
-                    }
-                    return "";
-                },
-                parameters: tool.inputSchema,
-                metadata: {
-                    category: "custom",
-                },
-            };
-            // Use comprehensive validation logic
-            try {
-                validateTool(name, toolForValidation);
-            }
-            catch (error) {
-                throw new Error(`Tool registration failed: ${error instanceof Error ? error.message : String(error)}`);
+                // Basic safety checks to prevent obvious issues
+                if (name.trim() === "") {
+                    throw new Error("Tool name cannot be empty");
+                }
+                if (name.length > 100) {
+                    throw new Error("Tool name is too long (maximum 100 characters)");
+                }
+                // eslint-disable-next-line no-control-regex
+                if (/[\x00-\x1F\x7F]/.test(name)) {
+                    throw new Error("Tool name contains invalid control characters");
+                }
             }
+            // --- End: Enhanced Validation Logic ---
+            // Tool object validation is now handled by FlexibleToolValidator above
+            // Proceed with tool registration since validation passed
             // SMART DEFAULTS: Use utility to eliminate boilerplate creation
             const mcpServerInfo = createCustomToolServerInfo(name, tool);
             // Register with toolRegistry using MCPServerInfo directly
@@ -2196,11 +2531,14 @@ export class NeuroLink {
                 : params,
             hasExternalManager: !!this.externalServerManager,
         });
-        // Emit tool start event
+        // Emit tool start event (NeuroLink format - keep existing)
         this.emitter.emit("tool:start", {
             toolName,
             timestamp: executionStartTime,
+            input: params, // Enhanced: add input parameters
         });
+        // ADD: Bedrock-compatible tool:start event (positional parameters)
+        this.emitter.emit("tool:start", toolName, params);
         // Set default options
         const finalOptions = {
             timeout: options?.timeout || 30000, // 30 second default timeout
@@ -2226,13 +2564,15 @@ export class NeuroLink {
             });
         }
         const metrics = this.toolExecutionMetrics.get(toolName);
-        metrics.totalExecutions++;
+        if (metrics) {
+            metrics.totalExecutions++;
+        }
         try {
             mcpLogger.debug(`[${functionTag}] Executing tool: ${toolName}`, {
                 toolName,
                 params,
                 options: finalOptions,
-                circuitBreakerState: circuitBreaker.getState(),
+                circuitBreakerState: circuitBreaker?.getState(),
             });
             // Execute with circuit breaker, timeout, and retry logic
             const result = await circuitBreaker.execute(async () => {
@@ -2253,12 +2593,14 @@ export class NeuroLink {
             });
             // Update success metrics
             const executionTime = Date.now() - executionStartTime;
-            metrics.successfulExecutions++;
-            metrics.lastExecutionTime = executionTime;
-            metrics.averageExecutionTime =
-                (metrics.averageExecutionTime * (metrics.successfulExecutions - 1) +
-                    executionTime) /
-                    metrics.successfulExecutions;
+            if (metrics) {
+                metrics.successfulExecutions++;
+                metrics.lastExecutionTime = executionTime;
+                metrics.averageExecutionTime =
+                    (metrics.averageExecutionTime * (metrics.successfulExecutions - 1) +
+                        executionTime) /
+                        metrics.successfulExecutions;
+            }
             // Track memory usage
             const endMemory = MemoryManager.getMemoryUsageMB();
             const memoryDelta = endMemory.heapUsed - startMemory.heapUsed;
@@ -2273,15 +2615,17 @@ export class NeuroLink {
                 toolName,
                 executionTime,
                 memoryDelta,
-                circuitBreakerState: circuitBreaker.getState(),
+                circuitBreakerState: circuitBreaker?.getState(),
             });
             // Emit tool end event using the helper method
-            this.emitToolEndEvent(toolName, executionStartTime, true);
+            this.emitToolEndEvent(toolName, executionStartTime, true, result);
             return result;
         }
         catch (error) {
             // Update failure metrics
-            metrics.failedExecutions++;
+            if (metrics) {
+                metrics.failedExecutions++;
+            }
             const executionTime = Date.now() - executionStartTime;
             // Create structured error
             let structuredError;
@@ -2312,8 +2656,10 @@ export class NeuroLink {
             else {
                 structuredError = ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
             }
+            // ADD: Centralized error event emission
+            this.emitter.emit("error", structuredError);
             // Emit tool end event using the helper method
-            this.emitToolEndEvent(toolName, executionStartTime, false);
+            this.emitToolEndEvent(toolName, executionStartTime, false, undefined, structuredError);
             // Add execution context to structured error
             structuredError = new NeuroLinkError({
                 ...structuredError,
@@ -2322,8 +2668,8 @@ export class NeuroLink {
                     executionTime,
                     params,
                     options: finalOptions,
-                    circuitBreakerState: circuitBreaker.getState(),
-                    circuitBreakerFailures: circuitBreaker.getFailureCount(),
+                    circuitBreakerState: circuitBreaker?.getState(),
+                    circuitBreakerFailures: circuitBreaker?.getFailureCount(),
                     metrics: { ...metrics },
                 },
             });
@@ -2374,9 +2720,21 @@ export class NeuroLink {
                 userId: "neurolink-user",
             };
             const result = (await toolRegistry.executeTool(toolName, params, context));
+            // ADD: Check if result indicates a failure and emit error event
+            if (result &&
+                typeof result === "object" &&
+                "success" in result &&
+                result.success === false) {
+                const errorMessage = result.error || "Tool execution failed";
+                const errorToEmit = new Error(errorMessage);
+                this.emitter.emit("error", errorToEmit);
+            }
             return result;
         }
         catch (error) {
+            // ADD: Emergency error event emission (fallback)
+            const errorToEmit = error instanceof Error ? error : new Error(String(error));
+            this.emitter.emit("error", errorToEmit);
             // Check if tool was not found
             if (error instanceof Error && error.message.includes("not found")) {
                 const availableTools = await this.getAllAvailableTools();
@@ -2548,6 +2906,9 @@ export class NeuroLink {
         }
         const { AIProviderFactory } = await import("./core/factory.js");
         const { hasProviderEnvVars } = await import("./utils/providerUtils.js");
+        // Keep references to prevent unused variable warnings
+        void AIProviderFactory;
+        void hasProviderEnvVars;
         const providers = [
             "openai",
             "bedrock",
@@ -2810,7 +3171,7 @@ export class NeuroLink {
             const inMemoryServers = this.getInMemoryServers();
             if (inMemoryServers.has(serverId)) {
                 const serverInfo = inMemoryServers.get(serverId);
-                return !!(serverInfo.tools && serverInfo.tools.length > 0);
+                return !!(serverInfo?.tools && serverInfo.tools.length > 0);
             }
             // Test external MCP servers
             const externalServer = this.externalServerManager.getServer(serverId);
@@ -3317,7 +3678,7 @@ export class NeuroLink {
      * Convert JSON Schema to AI SDK compatible format
      * For now, we'll skip schema validation and let the AI SDK handle parameters dynamically
      */
-    convertJSONSchemaToAISDKFormat(inputSchema) {
+    convertJSONSchemaToAISDKFormat(_inputSchema) {
         // The simplest approach: don't provide parameters schema
         // This lets the AI SDK handle the tool without schema validation
         // Tools will still work, they just won't have strict parameter validation