@juspay/neurolink 9.15.0 → 9.16.0

package/dist/lib/factories/providerRegistry.d.ts

@@ -5,11 +5,16 @@ import type { ProviderRegistryOptions } from "../types/index.js";
  */
 export declare class ProviderRegistry {
     private static registered;
+    private static registrationPromise;
     private static options;
     /**
      * Register all providers with the factory
      */
     static registerAllProviders(): Promise<void>;
+    /**
+     * Internal registration implementation
+     */
+    private static _doRegister;
     /**
      * Check if providers are registered
      */

package/dist/lib/factories/providerRegistry.js

@@ -7,6 +7,7 @@ import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexMo
  */
 export class ProviderRegistry {
     static registered = false;
+    static registrationPromise = null;
     static options = {
         enableManualMCP: false, // Default to disabled for safety
     };
@@ -17,6 +18,22 @@ export class ProviderRegistry {
         if (this.registered) {
             return;
         }
+        if (this.registrationPromise) {
+            return this.registrationPromise;
+        }
+        this.registrationPromise = this._doRegister();
+        try {
+            await this.registrationPromise;
+        }
+        catch (error) {
+            this.registrationPromise = null; // Allow retry on failure
+            throw error;
+        }
+    }
+    /**
+     * Internal registration implementation
+     */
+    static async _doRegister() {
         try {
             // Register providers with dynamic import factory functions
             const { ProviderFactory } = await import("./providerFactory.js");
@@ -34,7 +51,7 @@ export class ProviderRegistry {
             ProviderFactory.registerProvider(AIProviderName.ANTHROPIC, async (modelName, _providerName, sdk) => {
                 const { AnthropicProvider } = await import("../providers/anthropic.js");
                 return new AnthropicProvider(modelName, sdk);
-            }, AnthropicModels.CLAUDE_SONNET_4_0, ["claude", "anthropic"]);
+            }, AnthropicModels.CLAUDE_SONNET_4_6, ["claude", "anthropic"]);
             // Register Amazon Bedrock provider
             ProviderFactory.registerProvider(AIProviderName.BEDROCK, async (modelName, _providerName, sdk, region) => {
                 const { AmazonBedrockProvider } = await import("../providers/amazonBedrock.js");
@@ -54,7 +71,7 @@ export class ProviderRegistry {
             ProviderFactory.registerProvider(AIProviderName.VERTEX, async (modelName, providerName, sdk, region) => {
                 const { GoogleVertexProvider } = await import("../providers/googleVertex.js");
                 return new GoogleVertexProvider(modelName, providerName, sdk, region);
-            }, VertexModels.CLAUDE_4_0_SONNET, ["vertex", "googleVertex"]);
+            }, VertexModels.CLAUDE_4_6_SONNET, ["vertex", "googleVertex"]);
             // Register Hugging Face provider (Unified Router implementation)
             ProviderFactory.registerProvider(AIProviderName.HUGGINGFACE, async (modelName) => {
                 const { HuggingFaceProvider } = await import("../providers/huggingFace.js");
@@ -130,6 +147,7 @@ export class ProviderRegistry {
     static clearRegistrations() {
         ProviderFactory.clearRegistrations();
         this.registered = false;
+        this.registrationPromise = null;
     }
     /**
      * Set registry options (should be called before initialization)

package/dist/lib/index.d.ts

@@ -49,9 +49,9 @@ export { NeuroLink };
 export type { MCPServerInfo } from "./types/mcpTypes.js";
 export type { LangfuseConfig, LangfuseSpanAttributes, ObservabilityConfig, OpenTelemetryConfig, TraceNameFormat, } from "./types/observability.js";
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, setLangfuseContext, shutdownOpenTelemetry } from "./services/server/ai/observability/instrumentation.js";
+import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry } from "./services/server/ai/observability/instrumentation.js";
 export type { LangfuseContext } from "./services/server/ai/observability/instrumentation.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, };
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export type { MiddlewareConfig, MiddlewareContext, MiddlewareFactoryOptions, MiddlewarePreset, NeuroLinkMiddleware, } from "./types/middlewareTypes.js";

package/dist/lib/index.js

@@ -60,13 +60,15 @@ import { createContextEnricher, flushOpenTelemetry,
 // Enhanced context and tracing
 getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, 
 // NEW EXPORTS - External TracerProvider Support
-getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
+getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { getTelemetryStatus as getStatus, initializeTelemetry as init, } from "./telemetry/index.js";
 export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
 // NEW EXPORTS - External TracerProvider Support
 getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
 // Enhanced context and tracing
-getLangfuseContext, getTracer, };
+getLangfuseContext, getTracer, 
+// ALS context propagation helper
+runWithCurrentLangfuseContext, };
 // Analytics Middleware exports
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { MiddlewareFactory } from "./middleware/factory.js";

package/dist/lib/mcp/externalServerManager.js

@@ -14,6 +14,9 @@ import { toolRegistry } from "./toolRegistry.js";
 import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
 import { isObject, isNonNullObject } from "../utils/typeUtils.js";
+import { TelemetryService } from "../telemetry/telemetryService.js";
+import { tracers } from "../telemetry/tracers.js";
+import { SpanStatusCode } from "@opentelemetry/api";
 /**
  * Recursively substitute environment variables in strings
  * Replaces ${VAR_NAME} with the value from process.env.VAR_NAME
@@ -745,6 +748,16 @@ export class ExternalServerManager extends EventEmitter {
             throw new Error(`Server '${serverId}' not found`);
         }
         const config = instance.config;
+        const span = tracers.mcp.startSpan("neurolink.mcp.server.start", {
+            attributes: {
+                "mcp.server_id": serverId,
+                "mcp.transport": config.transport,
+                "mcp.command_name": config.command
+                    ? config.command.split(/[\\/]/).pop() || ""
+                    : "",
+                "mcp.command_present": Boolean(config.command),
+            },
+        });
         try {
             this.updateServerStatus(serverId, "connecting");
             mcpLogger.debug(`[ExternalServerManager] Starting server: ${serverId}`, {
@@ -803,6 +816,8 @@ export class ExternalServerManager extends EventEmitter {
                 toolCount: instance.toolsMap.size,
                 timestamp: new Date(),
             });
+            span.setAttribute("mcp.tool_count", instance.toolsMap.size);
+            span.setStatus({ code: SpanStatusCode.OK });
             mcpLogger.info(`[ExternalServerManager] Server started successfully: ${serverId}`);
         }
         catch (error) {
@@ -810,8 +825,16 @@ export class ExternalServerManager extends EventEmitter {
             this.updateServerStatus(serverId, "failed");
             instance.lastError =
                 error instanceof Error ? error.message : String(error);
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
             throw error;
         }
+        finally {
+            span.end();
+        }
     }
     /**
      * Stop an external MCP server
@@ -821,6 +844,11 @@ export class ExternalServerManager extends EventEmitter {
         if (!instance) {
             return;
         }
+        const span = tracers.mcp.startSpan("neurolink.mcp.server.stop", {
+            attributes: {
+                "mcp.server_id": serverId,
+            },
+        });
         try {
             this.updateServerStatus(serverId, "stopping");
             // Clear timers
@@ -851,11 +879,20 @@ export class ExternalServerManager extends EventEmitter {
                 instance.process = null;
             }
             this.updateServerStatus(serverId, "stopped");
+            span.setStatus({ code: SpanStatusCode.OK });
             mcpLogger.info(`[ExternalServerManager] Server stopped: ${serverId}`);
         }
         catch (error) {
             mcpLogger.error(`[ExternalServerManager] Error stopping server ${serverId}:`, error);
             this.updateServerStatus(serverId, "failed");
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            span.end();
         }
     }
     /**
@@ -959,16 +996,32 @@ export class ExternalServerManager extends EventEmitter {
             return;
         } // already scheduled
         instance.restartTimer = setTimeout(async () => {
+            const restartSpan = tracers.mcp.startSpan("neurolink.mcp.server.restart", {
+                attributes: {
+                    "mcp.server_id": serverId,
+                    "mcp.restart_attempt": instance.reconnectAttempts,
+                    "mcp.restart_delay_ms": delay,
+                },
+            });
             try {
                 await this.stopServer(serverId);
                 await this.startServer(serverId);
                 // Reset restart attempts on successful restart
                 instance.reconnectAttempts = 0;
+                restartSpan.setStatus({ code: SpanStatusCode.OK });
             }
             catch (error) {
                 mcpLogger.error(`[ExternalServerManager] Restart failed for ${serverId}:`, error);
+                restartSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                restartSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
                 this.scheduleRestart(serverId); // Try again
             }
+            finally {
+                restartSpan.end();
+            }
         }, delay);
     }
     /**
@@ -1376,6 +1429,12 @@ export class ExternalServerManager extends EventEmitter {
                 mcpLogger.debug(`[ExternalServerManager] Tool executed successfully: ${toolName} on ${serverId}`, {
                     duration,
                 });
+                try {
+                    TelemetryService.getInstance()?.recordMCPToolCall(toolName, duration, true);
+                }
+                catch {
+                    /* telemetry should not break execution */
+                }
                 return result.data;
             }
             else {
@@ -1384,6 +1443,13 @@ export class ExternalServerManager extends EventEmitter {
         }
         catch (error) {
             instance.metrics.totalErrors++;
+            try {
+                const errorDuration = Date.now() - startTime;
+                TelemetryService.getInstance()?.recordMCPToolCall(toolName, errorDuration, false);
+            }
+            catch {
+                /* telemetry should not break execution */
+            }
             mcpLogger.error(`[ExternalServerManager] Tool execution failed: ${toolName} on ${serverId}`, error);
             throw error;
         }

package/dist/lib/mcp/mcpCircuitBreaker.js

@@ -4,6 +4,7 @@
  * Provides fault tolerance and prevents cascading failures
  */
 import { EventEmitter } from "events";
+import { trace } from "@opentelemetry/api";
 import { mcpLogger } from "../utils/logger.js";
 /**
  * MCPCircuitBreaker
@@ -53,6 +54,17 @@ export class MCPCircuitBreaker extends EventEmitter {
                 this.halfOpenCalls >= this.config.halfOpenMaxCalls) {
                 throw new Error(`Circuit breaker '${this.name}' is half-open but call limit reached`);
             }
+            // NLK-GAP-009: Record half-open test event when executing in half-open state
+            if (this.state === "half-open") {
+                const activeSpan = trace.getActiveSpan();
+                if (activeSpan) {
+                    activeSpan.addEvent("circuit.half_open_test", {
+                        "circuit.name": this.name,
+                        "circuit.half_open_call": this.halfOpenCalls + 1,
+                        "circuit.half_open_max_calls": this.config.halfOpenMaxCalls,
+                    });
+                }
+            }
             // Execute operation with timeout
             const result = await Promise.race([
                 operation(),
@@ -145,6 +157,18 @@ export class MCPCircuitBreaker extends EventEmitter {
         const oldState = this.state;
         this.state = newState;
         this.lastStateChange = new Date();
+        // NLK-GAP-009: Record state transition on active OTel span
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan) {
+            activeSpan.addEvent("circuit.state_change", {
+                "circuit.name": this.name,
+                "circuit.from_state": oldState,
+                "circuit.to_state": newState,
+                "circuit.reason": reason.slice(0, 128),
+                "circuit.failure_count": this.callHistory.filter((c) => !c.success)
+                    .length,
+            });
+        }
         // Reset counters based on state
         if (newState === "half-open") {
             this.halfOpenCalls = 0;

package/dist/lib/mcp/mcpClientFactory.js

@@ -15,6 +15,8 @@ import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { withHTTPRetry, DEFAULT_HTTP_RETRY_CONFIG, } from "./httpRetryHandler.js";
 import { globalRateLimiterManager } from "./httpRateLimiter.js";
 import { NeuroLinkOAuthProvider, InMemoryTokenStorage } from "./auth/index.js";
+import { tracers } from "../telemetry/tracers.js";
+import { SpanStatusCode } from "@opentelemetry/api";
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -36,6 +38,13 @@ export class MCPClientFactory {
      */
     static async createClient(config, timeout = 10000) {
         const startTime = Date.now();
+        const span = tracers.mcp.startSpan("neurolink.mcp.client.create", {
+            attributes: {
+                "mcp.server_id": config.id,
+                "mcp.transport": config.transport,
+                "mcp.timeout_ms": timeout,
+            },
+        });
         try {
             mcpLogger.info(`[MCPClientFactory] Creating client for ${config.id}`, {
                 transport: config.transport,
@@ -94,6 +103,7 @@ export class MCPClientFactory {
                 duration: Date.now() - startTime,
                 capabilities: result.capabilities,
             });
+            span.setStatus({ code: SpanStatusCode.OK });
             return {
                 ...result,
                 success: true,
@@ -103,12 +113,18 @@ export class MCPClientFactory {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             mcpLogger.error(`[MCPClientFactory] Failed to create client for ${config.id}:`, error);
+            // NLK-GAP-004 fix: Record both exception AND error status on span
+            span.recordException(error instanceof Error ? error : new Error(errorMessage));
+            span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
             return {
                 success: false,
                 error: errorMessage,
                 duration: Date.now() - startTime,
             };
         }
+        finally {
+            span.end();
+        }
     }
     /**
      * Internal client creation logic

package/dist/lib/mcp/toolDiscoveryService.js

@@ -8,6 +8,10 @@ import { mcpLogger } from "../utils/logger.js";
 import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { isObject, isNullish } from "../utils/typeUtils.js";
 import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
+import { withTimeout } from "../utils/errorHandling.js";
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../telemetry/tracers.js";
+const mcpTracer = tracers.mcp;
 /**
  * ToolDiscoveryService
  * Handles automatic tool discovery and registration from external MCP servers
@@ -336,13 +340,35 @@ export class ToolDiscoveryService extends EventEmitter {
             });
             // Execute tool with circuit breaker protection
             const result = await circuitBreaker.execute(async () => {
-                const timeout = options.timeout || 30000;
-                const executePromise = client.callTool({
-                    name: toolName,
-                    arguments: parameters,
+                return mcpTracer.startActiveSpan("neurolink.mcp.callTool", {
+                    kind: SpanKind.CLIENT,
+                    attributes: {
+                        "mcp.server_id": serverId,
+                        "mcp.tool_name": toolName,
+                        "mcp.timeout_ms": options.timeout || 30000,
+                    },
+                }, async (callSpan) => {
+                    try {
+                        const timeout = options.timeout || 30000;
+                        const callResult = await withTimeout(client.callTool({
+                            name: toolName,
+                            arguments: parameters,
+                        }), timeout, new Error(`Tool execution timeout: ${toolName}`));
+                        callSpan.setStatus({ code: SpanStatusCode.OK });
+                        return callResult;
+                    }
+                    catch (err) {
+                        callSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: err.message,
+                        });
+                        callSpan.recordException(err);
+                        throw err;
+                    }
+                    finally {
+                        callSpan.end();
+                    }
                 });
-                const timeoutPromise = this.createTimeoutPromise(timeout, `Tool execution timeout: ${toolName}`);
-                return await Promise.race([executePromise, timeoutPromise]);
             });
             const duration = Date.now() - startTime;
             // Update tool statistics