@juspay/neurolink 9.24.0 → 9.25.1

package/dist/mcp/httpRateLimiter.js

@@ -4,6 +4,8 @@
  * Provides fault tolerance and prevents server overload
  */
 import { mcpLogger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * Default rate limit configuration
  * Provides sensible defaults for most MCP HTTP transport use cases
@@ -71,19 +73,44 @@ export class HTTPRateLimiter {
      * @throws Error if the wait queue is too long
      */
     async acquire() {
-        // First, try to acquire without waiting
-        if (this.tryAcquire()) {
-            return;
-        }
-        // Add to wait queue
-        return new Promise((resolve, reject) => {
-            this.waitQueue.push({ resolve, reject });
-            mcpLogger.debug(`[HTTPRateLimiter] Request queued, queue length: ${this.waitQueue.length}`);
-            // Start processing the queue if not already processing
-            if (!this.processingQueue) {
-                this.processQueue();
-            }
+        const span = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.rateLimit", {
+            "mcp.transport": "http",
+            "mcp.operation": "rateLimit",
+            "mcp.rateLimit.tokensAvailable": this.tokens,
+            "mcp.rateLimit.maxBurst": this.config.maxBurst,
         });
+        const startTime = Date.now();
+        try {
+            // First, try to acquire without waiting
+            if (this.tryAcquire()) {
+                span.durationMs = Date.now() - startTime;
+                span.attributes["mcp.rateLimit.waited"] = false;
+                const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                getMetricsAggregator().recordSpan(endedSpan);
+                return;
+            }
+            // Add to wait queue
+            await new Promise((resolve, reject) => {
+                this.waitQueue.push({ resolve, reject });
+                mcpLogger.debug(`[HTTPRateLimiter] Request queued, queue length: ${this.waitQueue.length}`);
+                // Start processing the queue if not already processing
+                if (!this.processingQueue) {
+                    this.processQueue();
+                }
+            });
+            span.durationMs = Date.now() - startTime;
+            span.attributes["mcp.rateLimit.waited"] = true;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+        }
+        catch (error) {
+            span.durationMs = Date.now() - startTime;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+            endedSpan.statusMessage =
+                error instanceof Error ? error.message : String(error);
+            getMetricsAggregator().recordSpan(endedSpan);
+            throw error;
+        }
     }
     /**
      * Process the wait queue, granting tokens as they become available

package/dist/mcp/httpRetryHandler.js

@@ -7,6 +7,8 @@
 import { isAbortError } from "../utils/errorHandling.js";
 import { calculateBackoffDelay } from "../utils/retryHandler.js";
 import { logger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * Default HTTP retry configuration
  */
@@ -129,10 +131,23 @@ export async function withHTTPRetry(operation, config = {}) {
         ...DEFAULT_HTTP_RETRY_CONFIG,
         ...config,
     };
+    const span = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.retry", {
+        "mcp.transport": "http",
+        "mcp.operation": "retry",
+        "mcp.maxAttempts": mergedConfig.maxAttempts,
+    });
+    const startTime = Date.now();
     let lastError;
+    let actualAttempts = 0;
     for (let attempt = 1; attempt <= mergedConfig.maxAttempts; attempt++) {
+        actualAttempts = attempt;
         try {
-            return await operation();
+            const result = await operation();
+            span.durationMs = Date.now() - startTime;
+            span.attributes["mcp.retryAttempt"] = attempt;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+            return result;
         }
         catch (error) {
             lastError = error;
@@ -153,5 +168,11 @@ export async function withHTTPRetry(operation, config = {}) {
             await sleep(delay);
         }
     }
+    span.durationMs = Date.now() - startTime;
+    span.attributes["mcp.retryAttempt"] = actualAttempts;
+    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+    endedSpan.statusMessage =
+        lastError instanceof Error ? lastError.message : String(lastError);
+    getMetricsAggregator().recordSpan(endedSpan);
     throw lastError;
 }

package/dist/mcp/mcpClientFactory.js

@@ -15,8 +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";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -38,12 +38,10 @@ 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,
-            },
+        const obsSpan = SpanSerializer.createSpan(SpanType.MCP_TRANSPORT, "mcp.connect", {
+            "mcp.transport": config.transport,
+            "mcp.operation": "connect",
+            "mcp.server_id": config.id,
         });
         try {
             mcpLogger.info(`[MCPClientFactory] Creating client for ${config.id}`, {
@@ -103,7 +101,9 @@ export class MCPClientFactory {
                 duration: Date.now() - startTime,
                 capabilities: result.capabilities,
             });
-            span.setStatus({ code: SpanStatusCode.OK });
+            obsSpan.durationMs = Date.now() - startTime;
+            const endedObsSpan = SpanSerializer.endSpan(obsSpan, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedObsSpan);
             return {
                 ...result,
                 success: true,
@@ -113,18 +113,16 @@ 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 });
+            obsSpan.durationMs = Date.now() - startTime;
+            const endedObsSpan = SpanSerializer.endSpan(obsSpan, SpanStatus.ERROR);
+            endedObsSpan.statusMessage = errorMessage;
+            getMetricsAggregator().recordSpan(endedObsSpan);
             return {
                 success: false,
                 error: errorMessage,
                 duration: Date.now() - startTime,
             };
         }
-        finally {
-            span.end();
-        }
     }
     /**
      * Internal client creation logic

package/dist/memory/memoryRetrievalTools.js

@@ -9,6 +9,8 @@
 import { tool } from "ai";
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /** Maximum characters returned per retrieval request */
 const DEFAULT_RETRIEVAL_LIMIT = 50_000;
 /** Hard maximum for user/LLM-supplied limit to prevent massive tool outputs */
@@ -62,9 +64,18 @@ export function createMemoryRetrievalTools(memoryManager) {
                     "Returns matching lines with line numbers."),
             }),
             execute: async (args) => {
+                const span = SpanSerializer.createSpan(SpanType.MEMORY, "memory.retrieve", {
+                    "memory.operation": "retrieve",
+                    "memory.store": "redis",
+                    "memory.query": args.search || args.messageId || `lastN:${args.lastN ?? "all"}`,
+                });
+                const startTime = Date.now();
                 try {
                     const conversation = await memoryManager.getSessionRaw(args.sessionId);
                     if (!conversation) {
+                        span.durationMs = Date.now() - startTime;
+                        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                        getMetricsAggregator().recordSpan(endedSpan);
                         return { error: "Session not found", sessionId: args.sessionId };
                     }
                     let messages = conversation.messages;
@@ -72,6 +83,9 @@ export function createMemoryRetrievalTools(memoryManager) {
                     if (args.messageId) {
                         const msg = messages.find((m) => m.id === args.messageId);
                         if (!msg) {
+                            span.durationMs = Date.now() - startTime;
+                            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                            getMetricsAggregator().recordSpan(endedSpan);
                             return { error: "Message not found", messageId: args.messageId };
                         }
                         messages = [msg];
@@ -130,9 +144,17 @@ export function createMemoryRetrievalTools(memoryManager) {
                             hasMore: end < content.length,
                         };
                     });
+                    span.durationMs = Date.now() - startTime;
+                    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                    getMetricsAggregator().recordSpan(endedSpan);
                     return { messages: results, totalMessages: results.length };
                 }
                 catch (error) {
+                    span.durationMs = Date.now() - startTime;
+                    const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+                    endedSpan.statusMessage =
+                        error instanceof Error ? error.message : String(error);
+                    getMetricsAggregator().recordSpan(endedSpan);
                     logger.error("[MemoryRetrievalTools] Error retrieving context", {
                         error: error instanceof Error ? error.message : String(error),
                     });

package/dist/neurolink.d.ts

@@ -10,6 +10,8 @@ import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
+import type { MetricsSummary, TraceView } from "./observability/metricsAggregator.js";
+import type { SpanData } from "./observability/types/spanTypes.js";
 import type { JsonObject, NeuroLinkEvents, TypedEventEmitter } from "./types/common.js";
 import type { NeurolinkConstructorConfig } from "./types/configTypes.js";
 import type { ChatMessage } from "./types/conversation.js";
@@ -21,78 +23,6 @@ import type { ObservabilityConfig } from "./types/observability.js";
 import type { StreamOptions, StreamResult } from "./types/streamTypes.js";
 import type { ToolExecutionContext, ToolExecutionSummary, ToolInfo } from "./types/tools.js";
 import type { BatchOperationResult } from "./types/typeAliases.js";
-/**
- * NeuroLink - Universal AI Development Platform
- *
- * Main SDK class providing unified access to 14+ AI providers with enterprise features:
- * - Multi-provider support (OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, etc.)
- * - MCP (Model Context Protocol) tool integration with 58+ external servers
- * - Human-in-the-Loop (HITL) security workflows for regulated industries
- * - Redis-based conversation memory and persistence
- * - Enterprise middleware system for monitoring and control
- * - Automatic provider fallback and retry logic
- * - Streaming with real-time token delivery
- * - Multimodal support (text, images, PDFs, CSV)
- *
- * @category Core
- *
- * @example Basic usage
- * ```typescript
- * import { NeuroLink } from '@juspay/neurolink';
- *
- * const neurolink = new NeuroLink();
- *
- * const result = await neurolink.generate({
- *   input: { text: 'Explain quantum computing' },
- *   provider: 'vertex',
- *   model: 'gemini-3-flash'
- * });
- *
- * console.log(result.content);
- * ```
- *
- * @example With HITL security
- * ```typescript
- * const neurolink = new NeuroLink({
- *   hitl: {
- *     enabled: true,
- *     requireApproval: ['writeFile', 'executeCode'],
- *     confidenceThreshold: 0.85
- *   }
- * });
- * ```
- *
- * @example With Redis memory
- * ```typescript
- * const neurolink = new NeuroLink({
- *   conversationMemory: {
- *     enabled: true,
- *     redis: {
- *       url: 'redis://localhost:6379'
- *     }
- *   }
- * });
- * ```
- *
- * @example With MCP tools
- * ```typescript
- * const neurolink = new NeuroLink();
- *
- * // Discover available tools
- * const tools = await neurolink.getAvailableTools();
- *
- * // Use tools in generation
- * const result = await neurolink.generate({
- *   input: { text: 'Read the README.md file' },
- *   tools: ['readFile']
- * });
- * ```
- *
- * @see {@link GenerateOptions} for generation options
- * @see {@link StreamOptions} for streaming options
- * @see {@link NeurolinkConstructorConfig} for configuration options
- * @since 1.0.0
- */
 export declare class NeuroLink {
     private mcpInitialized;
     private mcpInitPromise;
@@ -203,6 +133,13 @@ export declare class NeuroLink {
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
     private observabilityConfig?;
+    private metricsAggregator;
+    /**
+     * Per-request metrics trace context backed by AsyncLocalStorage.
+     * Safe for concurrent requests on the same SDK instance.
+     * Context is set via metricsTraceContextStorage.run() in generate/stream.
+     */
+    private get _metricsTraceContext();
     constructor(config?: NeurolinkConstructorConfig);
     /**
      * Initialize provider registry with security settings
@@ -385,6 +322,56 @@ export declare class NeuroLink {
      * Centralized utility to avoid duplication across providers
      */
     isTelemetryEnabled(): boolean;
+    /**
+     * Get comprehensive telemetry status including Langfuse, OTel, and exporter health
+     */
+    getTelemetryStatus(): {
+        enabled: boolean;
+        langfuse?: {
+            enabled: boolean;
+            baseUrl?: string;
+            environment?: string;
+        };
+        openTelemetry?: {
+            enabled: boolean;
+            endpoint?: string;
+            serviceName?: string;
+        };
+        exporters?: Array<{
+            name: string;
+            enabled: boolean;
+            healthy: boolean;
+            pendingSpans: number;
+            lastExportTime?: string;
+            latencyMs?: number;
+            errors?: string[];
+        }>;
+    };
+    /**
+     * Get aggregated observability metrics (latency, tokens, cost, success rate)
+     */
+    getMetrics(): MetricsSummary;
+    /**
+     * Get all recorded spans
+     */
+    getSpans(): SpanData[];
+    /**
+     * Get traces (spans grouped by traceId with parent-child hierarchy)
+     */
+    getTraces(): TraceView[];
+    /**
+     * Reset all collected metrics and spans
+     */
+    resetMetrics(): void;
+    /**
+     * Record a span for metrics tracking
+     */
+    recordMetricsSpan(span: SpanData): void;
+    /**
+     * Record a memory operation span to both instance and global metrics aggregators.
+     * This ensures memory spans are visible via sdk.getSpans() and getMetricsAggregator().getSpans().
+     */
+    private recordMemorySpan;
     /**
      * Public method to initialize Langfuse observability
      * This method can be called externally to ensure Langfuse is properly initialized
@@ -394,6 +381,11 @@ export declare class NeuroLink {
      * Gracefully shutdown NeuroLink and all MCP connections
      */
     shutdown(): Promise<void>;
+    /**
+     * Initialize event listeners that feed span data to MetricsAggregator.
+     * Listens to generation:end, stream:complete, and tool:end events.
+     */
+    private initializeMetricsListeners;
     /**
      * Generate AI response with comprehensive feature support.
      *