@juspay/neurolink 9.54.6 → 9.54.8

package/dist/neurolink.js

@@ -15,7 +15,7 @@ try {
 catch {
     // Environment variables should be set externally in production
 }
-import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
 import { AsyncLocalStorage } from "async_hooks";
 import { EventEmitter } from "events";
 import pLimit from "p-limit";
@@ -133,6 +133,29 @@ function mcpCategoryToErrorCategory(mcpCategory) {
             return ErrorCategory.EXECUTION;
     }
 }
+/**
+ * Extract a human-readable error string from an MCP isError result object.
+ * Returns an empty string if nothing useful can be extracted.
+ */
+function extractMcpErrorText(raw) {
+    try {
+        const resultObj = typeof raw === "string" ? JSON.parse(raw) : raw;
+        if (!resultObj || typeof resultObj !== "object") {
+            return "";
+        }
+        const content = resultObj.content;
+        if (!Array.isArray(content)) {
+            return "";
+        }
+        const texts = content
+            .filter((c) => c.type === "text" && c.text)
+            .map((c) => c.text);
+        return texts.join(" ").substring(0, 500);
+    }
+    catch {
+        return "";
+    }
+}
 /**
  * Check if an error is a non-retryable provider error that should immediately
  * stop the retry/fallback chain. These errors represent permanent failures
@@ -179,6 +202,78 @@ function isNonRetryableProviderError(error) {
     }
     return false;
 }
+/**
+ * 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-preview'
+ * });
+ *
+ * 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
+ */
 /**
  * Module-level AsyncLocalStorage for per-request metrics trace context.
  * Eliminates the race condition where overlapping generate/stream calls on the
@@ -396,6 +491,24 @@ export class NeuroLink {
         return await callback();
     }
     createMetricsTraceContext() {
+        // Attempt to reuse the active OTel trace context so Pipeline B spans
+        // land in the same Langfuse trace as Pipeline A spans.
+        const activeSpan = trace.getSpan(context.active());
+        if (activeSpan) {
+            const spanCtx = activeSpan.spanContext();
+            // Only use the OTel context if it has a valid trace ID.
+            // parentSpanId stores the active span's ID as a parent reference;
+            // each Pipeline B span must generate its own unique spanId to comply
+            // with the OTel/W3C requirement that spanIds are unique per trace.
+            if (spanCtx.traceId &&
+                spanCtx.traceId !== "00000000000000000000000000000000") {
+                return {
+                    traceId: spanCtx.traceId,
+                    parentSpanId: spanCtx.spanId,
+                };
+            }
+        }
+        // Fallback: no active OTel context (e.g. standalone Pipeline B usage)
         return {
             traceId: crypto.randomUUID().replace(/-/g, ""),
             parentSpanId: crypto.randomUUID().replace(/-/g, "").substring(0, 16),
@@ -2192,6 +2305,13 @@ Current user's request: ${currentInput}`;
     initializeMetricsListeners() {
         this.emitter.on("generation:end", ((...args) => {
             const data = args[0];
+            // A2 fix: When Pipeline A (AI SDK → @langfuse/otel) already creates a
+            // GENERATION observation, skip the Pipeline B span to avoid duplicates.
+            // Native providers (Bedrock, Ollama, Gemini 3) do NOT set this flag —
+            // Pipeline B remains their only observation source.
+            if (data.pipelineAHandled) {
+                return;
+            }
             try {
                 const result = data.result;
                 const usage = result?.usage;
@@ -2211,10 +2331,10 @@ Current user's request: ${currentInput}`;
                     temperature: data.temperature,
                     maxTokens: data.maxTokens,
                 });
-                // Make this the root span by using the pre-generated rootSpanId
+                // Link to the OTel parent span; each Pipeline B span keeps its own
+                // unique spanId to comply with OTel/W3C uniqueness requirements.
                 if (traceCtx) {
-                    span.spanId = traceCtx.parentSpanId;
-                    span.parentSpanId = undefined;
+                    span.parentSpanId = traceCtx.parentSpanId;
                 }
                 // Mark failed generations with ERROR status so metrics count them correctly
                 const spanStatus = data.success === false || data.error
@@ -2222,6 +2342,19 @@ Current user's request: ${currentInput}`;
                     : SpanStatus.OK;
                 span = SpanSerializer.endSpan(span, spanStatus, data.error ? String(data.error) : undefined);
                 span.durationMs = responseTime;
+                // G2 fix: Check finishReason and escalate to WARNING for partial failures
+                const finishReason = result?.finishReason ??
+                    data.finishReason;
+                if (finishReason) {
+                    span.attributes["gen_ai.finish_reason"] = finishReason;
+                    if (finishReason === "content-filter" || finishReason === "length") {
+                        span = SpanSerializer.endSpan(span, SpanStatus.WARNING, `Generation stopped: finishReason=${finishReason}`);
+                    }
+                }
+                // G6 fix: Record retry count on Pipeline B span
+                if (data.retryCount !== undefined) {
+                    span.attributes["gen_ai.retry_count"] = data.retryCount;
+                }
                 if (usage) {
                     span = SpanSerializer.enrichWithTokenUsage(span, {
                         promptTokens: usage.input || 0,
@@ -2283,15 +2416,24 @@ Current user's request: ${currentInput}`;
                     name: `gen_ai.${provider}.stream`,
                     traceId: traceCtx?.traceId,
                 });
-                // Make this the root span by using the pre-generated rootSpanId
+                // Link to the OTel parent span; keep unique spanId per W3C spec.
                 if (traceCtx) {
-                    span.spanId = traceCtx.parentSpanId;
-                    span.parentSpanId = undefined;
+                    span.parentSpanId = traceCtx.parentSpanId;
                 }
                 span = SpanSerializer.endSpan(span, SpanStatus.OK);
                 span.durationMs = durationMs;
                 span.attributes["stream.chunk_count"] = chunkCount;
                 span.attributes["stream.content_length"] = totalLength;
+                // S3 fix: Record finishReason on Pipeline B stream span
+                const streamFinishReason = metadata?.finishReason ??
+                    data.finishReason;
+                if (streamFinishReason) {
+                    span.attributes["gen_ai.finish_reason"] = streamFinishReason;
+                    if (streamFinishReason === "content-filter" ||
+                        streamFinishReason === "length") {
+                        span = SpanSerializer.endSpan(span, SpanStatus.WARNING, `Stream stopped: finishReason=${streamFinishReason}`);
+                    }
+                }
                 // Record stream input prompt
                 if (data.prompt) {
                     const promptStr = String(data.prompt);
@@ -2359,9 +2501,13 @@ Current user's request: ${currentInput}`;
                 }, traceCtx?.parentSpanId, traceCtx?.traceId);
                 span = SpanSerializer.endSpan(span, success ? SpanStatus.OK : SpanStatus.ERROR);
                 span.durationMs = responseTime;
-                if (!success && data.error) {
-                    span.statusMessage =
-                        data.error.message || String(data.error);
+                if (!success) {
+                    if (data.error) {
+                        span.statusMessage = String(data.error);
+                    }
+                    else if (data.result) {
+                        span.statusMessage = extractMcpErrorText(data.result);
+                    }
                 }
                 if (data.result) {
                     try {
@@ -2395,15 +2541,22 @@ Current user's request: ${currentInput}`;
                     name: `gen_ai.${provider}.stream.error`,
                     traceId: traceCtx?.traceId,
                 });
-                // Make this the root span
+                // Link to the OTel parent span; keep unique spanId per W3C spec.
                 if (traceCtx) {
-                    span.spanId = traceCtx.parentSpanId;
-                    span.parentSpanId = undefined;
+                    span.parentSpanId = traceCtx.parentSpanId;
                 }
                 span = SpanSerializer.endSpan(span, SpanStatus.ERROR);
                 span.durationMs = durationMs;
                 span.statusMessage = `${errorName}: ${errorMessage}`;
                 span.attributes["stream.chunk_count"] = chunkCount;
+                // S7 fix: Distinguish aborts from errors
+                const isAbort = errorName === "AbortError" ||
+                    errorMessage.toLowerCase().includes("aborted") ||
+                    errorMessage.toLowerCase().includes("abort");
+                span.attributes["error.type"] = isAbort ? "abort" : errorName;
+                if (isAbort) {
+                    span.attributes["stream.aborted"] = true;
+                }
                 this.metricsAggregator.recordSpan(span);
                 getMetricsAggregator().recordSpan(span);
             }
@@ -2535,6 +2688,12 @@ Current user's request: ${currentInput}`;
                 code: SpanStatusCode.ERROR,
                 message: error instanceof Error ? error.message : String(error),
             });
+            // G7 fix: Distinguish context overflow errors with dedicated attributes
+            if (error instanceof ContextBudgetExceededError) {
+                generateSpan.setAttribute("neurolink.error.type", "context_overflow");
+                generateSpan.setAttribute("neurolink.context.estimated_tokens", error.estimatedTokens);
+                generateSpan.setAttribute("neurolink.context.available_tokens", error.availableTokens);
+            }
             this.emitGenerateErrorEvent(optionsOrPrompt, error);
             throw error;
         }
@@ -2749,6 +2908,10 @@ Current user's request: ${currentInput}`;
             prompt: options.input?.text || options.prompt,
             temperature: textOptions.temperature,
             maxTokens: textOptions.maxTokens,
+            // A2 fix: Signal that Pipeline A (AI SDK → @langfuse/otel) already
+            // creates a GENERATION observation for this call. The generation:end
+            // listener should skip creating a duplicate Pipeline B span.
+            pipelineAHandled: true,
         });
         this.emitter.emit("response:end", textResult.content || "");
         this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
@@ -2797,6 +2960,12 @@ Current user's request: ${currentInput}`;
         generateSpan.setAttribute("neurolink.tokens.input", generateResult.usage?.input || 0);
         generateSpan.setAttribute("neurolink.tokens.output", generateResult.usage?.output || 0);
         generateSpan.setAttribute("neurolink.finish_reason", generateResult.finishReason || "unknown");
+        // G3 fix: Record step count and whether max steps was reached
+        // Read steps from the raw provider result (textResult), not the flattened DTO
+        const stepCount = textResult?.steps?.length ?? 1;
+        const maxSteps = options.maxSteps ?? 200; // DEFAULT_MAX_STEPS
+        generateSpan.setAttribute("neurolink.step_count", stepCount);
+        generateSpan.setAttribute("neurolink.max_steps_reached", stepCount >= maxSteps);
         generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
         generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
         generateSpan.setAttribute("generate.retry_count", generateResult.retries?.count || 0);
@@ -4494,6 +4663,7 @@ Current user's request: ${currentInput}`;
                         content: accumulatedContent,
                         provider: metadata.fallbackProvider ?? providerName,
                         model: metadata.fallbackModel ?? streamModel ?? enhancedOptions.model,
+                        finishReason: streamState.finishReason ?? "stop",
                         prompt: enhancedOptions.input?.text ||
                             enhancedOptions.prompt,
                         metadata: {
@@ -4502,6 +4672,7 @@ Current user's request: ${currentInput}`;
                             durationMs: Date.now() - streamStartTime,
                             sessionId,
                             usage: resolvedUsage,
+                            finishReason: streamState.finishReason ?? "stop",
                             ...(metadata.fallbackAttempted && {
                                 primaryProvider: providerName,
                                 primaryModel: enhancedOptions.model,
@@ -5212,23 +5383,20 @@ Current user's request: ${currentInput}`;
         logger.error("Stream generation failed, attempting fallback", {
             error: error instanceof Error ? error.message : String(error),
         });
-        // Record a failed-provider span for the primary provider that threw
+        // S1 fix: Emit stream:error so the Pipeline B listener creates an error span.
+        // S8 fix: The old direct SpanSerializer.createGenerationSpan block is removed —
+        // the stream:error listener now handles span creation, avoiding duplication.
         try {
-            const failedProvider = options.provider || "unknown";
-            const traceCtx = this._metricsTraceContext;
-            let failedSpan = SpanSerializer.createGenerationSpan({
-                provider: failedProvider,
+            this.emitter.emit("stream:error", {
+                content: error instanceof Error ? error.message : String(error),
+                metadata: {
+                    errorName: error instanceof Error ? error.name : "UnknownError",
+                    durationMs: Date.now() - startTime,
+                    chunkCount: 0,
+                },
+                provider: options.provider || "unknown",
                 model: options.model || "unknown",
-                name: `gen_ai.${failedProvider}.stream.failed`,
-                traceId: traceCtx?.traceId,
-                parentSpanId: traceCtx?.parentSpanId,
             });
-            failedSpan = SpanSerializer.endSpan(failedSpan, SpanStatus.ERROR);
-            failedSpan.statusMessage =
-                error instanceof Error ? error.message : String(error);
-            failedSpan.durationMs = Date.now() - startTime;
-            this.metricsAggregator.recordSpan(failedSpan);
-            getMetricsAggregator().recordSpan(failedSpan);
         }
         catch {
             /* non-blocking */
@@ -5267,6 +5435,25 @@ Current user's request: ${currentInput}`;
                         responseTimeMs: Date.now() - startTime,
                         contentLength: fallbackAccumulatedContent.length,
                     });
+                    // S6 fix: Emit stream:complete after successful fallback so Pipeline B records it
+                    try {
+                        self.emitter.emit("stream:complete", {
+                            content: fallbackAccumulatedContent,
+                            provider: providerName,
+                            model: options.model || "unknown",
+                            finishReason: "stop",
+                            metadata: {
+                                durationMs: Date.now() - startTime,
+                                chunkCount: 0,
+                                totalLength: fallbackAccumulatedContent.length,
+                                isFallback: true,
+                                finishReason: "stop",
+                            },
+                        });
+                    }
+                    catch {
+                        /* non-blocking */
+                    }
                 }
                 // Store memory after fallback stream consumption is complete
                 // Guard: skip storing if fallback accumulated content is empty
@@ -6194,6 +6381,7 @@ Current user's request: ${currentInput}`;
         };
     }
     async runPreparedToolExecution(toolName, params, prepared, executionContext, toolSpan) {
+        let toolRetryCount = 0;
         try {
             mcpLogger.debug(`[${executionContext.functionTag}] Executing tool: ${toolName}`, {
                 toolName,
@@ -6207,6 +6395,7 @@ Current user's request: ${currentInput}`;
                     delayMs: prepared.finalOptions.retryDelayMs,
                     isRetriable: isRetriableError,
                     onRetry: (attempt, error) => {
+                        toolRetryCount = attempt;
                         mcpLogger.warn(`[${executionContext.functionTag}] Retrying tool execution (attempt ${attempt})`, {
                             toolName,
                             error: error.message,
@@ -6215,9 +6404,12 @@ Current user's request: ${currentInput}`;
                     },
                 });
             });
+            toolSpan.setAttribute("tool.retry_count", toolRetryCount);
             return await this.handleSuccessfulToolExecution(toolName, result, prepared, executionContext, toolSpan);
         }
         catch (error) {
+            // Ensure retry count is recorded even on failure
+            toolSpan.setAttribute("tool.retry_count", toolRetryCount);
             return this.handleFailedToolExecution(toolName, params, error, prepared, executionContext, toolSpan);
         }
     }
@@ -6251,6 +6443,18 @@ Current user's request: ${currentInput}`;
             : undefined;
         const isToolError = (resultObj && "isError" in resultObj && resultObj.isError === true) ||
             (resultObj && "success" in resultObj && resultObj.success === false);
+        const contentArr = isToolError
+            ? resultObj?.content
+            : undefined;
+        const errorText = isToolError
+            ? contentArr
+                ?.filter((content) => content.type === "text" && content.text)
+                .map((content) => content.text)
+                .join(" ") ||
+                (typeof resultObj?.error === "string"
+                    ? resultObj.error
+                    : "Unknown error")
+            : undefined;
         if (isToolError) {
             try {
                 await prepared.circuitBreaker.execute(async () => {
@@ -6265,15 +6469,7 @@ Current user's request: ${currentInput}`;
                 circuitBreakerState: prepared.circuitBreaker.getState(),
                 circuitBreakerFailures: prepared.circuitBreaker.getFailureCount(),
             });
-            const contentArr = resultObj?.content;
-            const errorText = contentArr
-                ?.filter((content) => content.type === "text" && content.text)
-                .map((content) => content.text)
-                .join(" ") ||
-                (typeof resultObj?.error === "string"
-                    ? resultObj.error
-                    : "Unknown error");
-            const errorCategory = classifyMcpErrorMessage(errorText);
+            const errorCategory = classifyMcpErrorMessage(errorText ?? "Unknown error");
             const prefix = `[TOOL_ERROR: ${toolName} failed (${errorCategory})] `;
             if (resultObj && Array.isArray(contentArr)) {
                 const clonedContent = contentArr.map((content) => ({ ...content }));
@@ -6285,11 +6481,11 @@ Current user's request: ${currentInput}`;
                 }
                 resultObj.content = clonedContent;
             }
-            toolSpan.setAttribute("tool.error.message", errorText.substring(0, 500));
+            toolSpan.setAttribute("tool.error.message", (errorText ?? "Unknown error").substring(0, 500));
             toolSpan.setAttribute("tool.error.category", errorCategory);
             toolSpan.setStatus({
                 code: SpanStatusCode.ERROR,
-                message: `MCP tool returned isError: ${errorText.substring(0, 200)}`,
+                message: `MCP tool returned isError: ${(errorText ?? "Unknown error").substring(0, 200)}`,
             });
             prepared.metrics.failedExecutions++;
             const prevSuccessful = prepared.metrics.successfulExecutions;
@@ -6304,7 +6500,7 @@ Current user's request: ${currentInput}`;
             prepared.metrics.errorCategories[mappedCategory] =
                 (prepared.metrics.errorCategories[mappedCategory] || 0) + 1;
         }
-        this.emitToolEndEvent(toolName, executionContext.executionStartTime, !isToolError, result);
+        this.emitToolEndEvent(toolName, executionContext.executionStartTime, !isToolError, result, isToolError && errorText ? new Error(errorText) : undefined);
         toolSpan.setAttribute("tool.result.status", isToolError ? "error" : "success");
         toolSpan.setAttribute("tool.duration_ms", executionTime);
         return result;
@@ -6323,7 +6519,7 @@ Current user's request: ${currentInput}`;
             });
             prepared.metrics.errorCategories[ErrorCategory.EXECUTION] =
                 (prepared.metrics.errorCategories[ErrorCategory.EXECUTION] || 0) + 1;
-            this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined);
+            this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, new Error(`Circuit breaker open for ${toolName} (state=${error.breakerState}, failures=${error.failureCount})`));
             toolSpan.setAttribute("tool.result.status", "circuit_breaker_open");
             toolSpan.setAttribute("tool.duration_ms", executionTime);
             toolSpan.setAttribute("tool.circuit_breaker.state", error.breakerState);

package/dist/observability/exporterRegistry.d.ts

@@ -3,24 +3,7 @@
  * Manages multiple observability exporters with circuit breaker protection
  */
 import type { BaseExporter } from "./exporters/baseExporter.js";
-import type { ExporterHealthStatus, ExportResult, Sampler, SpanData } from "../types/index.js";
-/**
- * Circuit breaker state for an exporter
- */
-type CircuitBreakerState = {
-    failures: number;
-    lastFailure: number;
-    state: "closed" | "open" | "half-open";
-};
-/**
- * Circuit breaker configuration
- */
-type CircuitBreakerConfig = {
-    /** Number of failures before opening the circuit */
-    failureThreshold: number;
-    /** Time in ms to wait before trying half-open state */
-    resetTimeout: number;
-};
+import type { ExportResult, ExporterHealthStatus, ObservabilityCircuitBreakerConfig, ObservabilityCircuitBreakerState, Sampler, SpanData } from "../types/index.js";
 /**
  * Registry for managing multiple observability exporters
  * Includes circuit breaker protection to prevent cascading failures
@@ -71,7 +54,7 @@ export declare class ExporterRegistry {
      * Configure the circuit breaker settings
      * @param config - Partial circuit breaker configuration
      */
-    configureCircuitBreaker(config: Partial<CircuitBreakerConfig>): void;
+    configureCircuitBreaker(config: Partial<ObservabilityCircuitBreakerConfig>): void;
     /**
      * Check if circuit is open for an exporter
      * @param exporterName - Name of the exporter
@@ -94,7 +77,7 @@ export declare class ExporterRegistry {
      * @param exporterName - Name of the exporter
      * @returns Circuit breaker state or undefined if not tracked
      */
-    getCircuitBreakerStatus(exporterName: string): CircuitBreakerState | undefined;
+    getCircuitBreakerStatus(exporterName: string): ObservabilityCircuitBreakerState | undefined;
     /**
      * Reset circuit breaker for an exporter
      * @param exporterName - Name of the exporter
@@ -148,4 +131,3 @@ export declare function getExporterRegistry(): ExporterRegistry;
  * Reset the global exporter registry (for testing)
  */
 export declare function resetExporterRegistry(): void;
-export {};

package/dist/observability/exporters/sentryExporter.js

@@ -5,6 +5,7 @@
 import { logger } from "../../utils/logger.js";
 import { SpanStatus } from "../../types/index.js";
 import { BaseExporter } from "./baseExporter.js";
+// Sentry types - optional dependency
 /**
  * Sentry exporter for error tracking and performance monitoring
  * Captures AI errors as exceptions and traces as transactions

package/dist/observability/metricsAggregator.d.ts

@@ -1,34 +1,5 @@
 import { TokenTracker } from "./tokenTracker.js";
-import type { SpanData, TraceView, TokenUsageStats, LatencyStats, MetricsSummary, ModelCostStats, ProviderCostStats } from "../types/index.js";
-/**
- * Time window statistics
- */
-type TimeWindowStats = {
-    windowStart: Date;
-    windowEnd: Date;
-    windowDurationMs: number;
-    requestCount: number;
-    errorCount: number;
-    successRate: number;
-    throughput: number;
-    latency: LatencyStats;
-    tokens: TokenUsageStats;
-    costByProvider: Map<string, ProviderCostStats>;
-    costByModel: Map<string, ModelCostStats>;
-};
-/**
- * Configuration for the metrics aggregator
- */
-type MetricsAggregatorConfig = {
-    /** Maximum spans to retain in memory */
-    maxSpansRetained?: number;
-    /** Enable time-window statistics */
-    enableTimeWindows?: boolean;
-    /** Time window size in milliseconds (default: 60000 = 1 minute) */
-    timeWindowMs?: number;
-    /** Maximum time windows to retain */
-    maxTimeWindows?: number;
-};
+import type { LatencyStats, MetricsAggregatorConfig, MetricsSummary, ModelCostStats, ProviderCostStats, SpanData, TimeWindowStats, TokenUsageStats, TraceView } from "../types/index.js";
 /**
  * Metrics Aggregator for comprehensive telemetry analysis
  * Provides latency percentiles, token aggregation, and cost tracking
@@ -153,4 +124,3 @@ export declare function getMetricsAggregator(): MetricsAggregator;
  * Reset the global metrics aggregator (for testing)
  */
 export declare function resetMetricsAggregator(): void;
-export {};

package/dist/observability/tokenTracker.d.ts

@@ -2,15 +2,7 @@
  * Token Usage Tracker
  * Aggregates token usage and cost across spans
  */
-import type { SpanData, TokenUsageStats } from "../types/index.js";
-/**
- * Model pricing information
- */
-type ModelPricing = {
-    inputPricePerMillion: number;
-    outputPricePerMillion: number;
-    cachedInputPricePerMillion?: number;
-};
+import type { ObservabilityModelPricing, SpanData, TokenUsageStats } from "../types/index.js";
 /**
  * Token tracker for aggregating usage across spans
  */
@@ -22,30 +14,30 @@ export declare class TokenTracker {
      * @param modelName - The model name (e.g., "gpt-4o", "claude-3-5-sonnet")
      * @param pricing - The pricing information
      */
-    setModelPricing(modelName: string, pricing: ModelPricing): void;
+    setObservabilityModelPricing(modelName: string, pricing: ObservabilityModelPricing): void;
     /**
-     * Update pricing for an existing model (alias for setModelPricing)
+     * Update pricing for an existing model (alias for setObservabilityModelPricing)
      * @param model - The model name
      * @param pricing - The new pricing information
      */
-    updatePricing(model: string, pricing: ModelPricing): void;
+    updatePricing(model: string, pricing: ObservabilityModelPricing): void;
     /**
      * Load pricing configuration from a config object
      * Useful for loading pricing from environment or config files
      * @param config - Record of model names to pricing information
      */
-    loadPricingFromConfig(config: Record<string, ModelPricing>): void;
+    loadPricingFromConfig(config: Record<string, ObservabilityModelPricing>): void;
     /**
      * Get pricing for a specific model
      * @param model - The model name
      * @returns The pricing information or undefined if not found
      */
-    getModelPricing(model: string): ModelPricing | undefined;
+    getModelPricing(model: string): ObservabilityModelPricing | undefined;
     /**
      * Get all available model pricing (custom + built-in)
      * @returns Record of all model pricing
      */
-    getAllPricing(): Record<string, ModelPricing>;
+    getAllPricing(): Record<string, ObservabilityModelPricing>;
     /**
      * Remove custom pricing for a model (falls back to built-in)
      * @param model - The model name to remove custom pricing for
@@ -115,4 +107,3 @@ export declare function getTokenTracker(): TokenTracker;
  * Reset the global token tracker (for testing)
  */
 export declare function resetTokenTracker(): void;
-export {};

package/dist/observability/tokenTracker.js

@@ -88,11 +88,11 @@ export class TokenTracker {
      * @param modelName - The model name (e.g., "gpt-4o", "claude-3-5-sonnet")
      * @param pricing - The pricing information
      */
-    setModelPricing(modelName, pricing) {
+    setObservabilityModelPricing(modelName, pricing) {
         this.customPricing.set(modelName, pricing);
     }
     /**
-     * Update pricing for an existing model (alias for setModelPricing)
+     * Update pricing for an existing model (alias for setObservabilityModelPricing)
      * @param model - The model name
      * @param pricing - The new pricing information
      */
@@ -122,7 +122,9 @@ export class TokenTracker {
      * @returns Record of all model pricing
      */
     getAllPricing() {
-        const allPricing = { ...MODEL_PRICING };
+        const allPricing = {
+            ...MODEL_PRICING,
+        };
         // Custom pricing takes precedence
         const customPricingEntries = Array.from(this.customPricing.entries());
         for (const [model, pricing] of customPricingEntries) {
@@ -298,7 +300,7 @@ export class TokenTracker {
         const tracker = new TokenTracker();
         // Copy custom pricing so windowed calculations use the same rates
         for (const [model, pricing] of this.customPricing) {
-            tracker.setModelPricing(model, pricing);
+            tracker.setObservabilityModelPricing(model, pricing);
         }
         for (const span of spans) {
             tracker.trackSpan(span);

package/dist/observability/utils/spanSerializer.d.ts

@@ -8,7 +8,11 @@ import { type LangfuseSpan, type LangSmithRun, type OtelSpan, type SpanAttribute
  */
 export declare class SpanSerializer {
     /**
-     * Create a new span with generated IDs
+     * Create a new span with generated IDs.
+     *
+     * When `traceId` / `parentSpanId` are omitted, the method automatically
+     * attempts to inherit them from the active OTel context so that Pipeline B
+     * spans land inside the same Langfuse trace as Pipeline A spans (fix A5).
      */
     static createSpan(type: SpanType, name: string, attributes?: Partial<SpanAttributes>, parentSpanId?: string, traceId?: string): SpanData;
     /**