@juspay/neurolink 9.24.0 → 9.25.1

package/dist/context/contextCompactor.js

@@ -8,9 +8,11 @@
  * Stage 3: LLM Summarization (expensive -- requires LLM call)
  * Stage 4: Sliding Window Truncation (fallback -- no LLM call)
  */
-import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { estimateMessagesTokens } from "../utils/tokenEstimation.js";
 import { logger } from "../utils/logger.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 import { pruneToolOutputs } from "./stages/toolOutputPruner.js";
 import { deduplicateFileReads } from "./stages/fileReadDeduplicator.js";
 import { summarizeMessages } from "./stages/structuredSummarizer.js";
@@ -38,154 +40,160 @@ export class ContextCompactor {
      * Run the multi-stage compaction pipeline until messages fit within budget.
      */
     async compact(messages, targetTokens, memoryConfig, requestId) {
-        const compactionStartTime = Date.now();
-        const provider = this.config.provider || undefined;
-        const tokensBefore = estimateMessagesTokens(messages, provider);
-        const stagesUsed = [];
-        let currentMessages = [...messages];
-        logger.info("[Compaction] Starting", {
-            requestId,
-            estimatedTokens: tokensBefore,
-            budgetTokens: targetTokens,
+        const span = SpanSerializer.createSpan(SpanType.CONTEXT_COMPACTION, "context.compact", {
+            "context.operation": "compact",
+            "context.targetTokens": targetTokens,
         });
-        // Stage 1: Tool Output Pruning
-        if (this.config.enablePrune &&
-            estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-            const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-            const pruneResult = pruneToolOutputs(currentMessages, {
-                protectTokens: this.config.pruneProtectTokens,
-                minimumSavings: this.config.pruneMinimumSavings,
-                protectedTools: this.config.pruneProtectedTools,
-                provider,
-            });
-            if (pruneResult.pruned) {
-                currentMessages = pruneResult.messages;
-                stagesUsed.push("prune");
-            }
-            const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-            logger.info("[Compaction] Stage 1 (prune)", {
+        const spanStartTime = Date.now();
+        try {
+            const provider = this.config.provider || undefined;
+            const tokensBefore = estimateMessagesTokens(messages, provider);
+            const stagesUsed = [];
+            let currentMessages = [...messages];
+            logger.info("[Compaction] Starting", {
                 requestId,
-                ran: pruneResult.pruned,
-                tokensBefore: stageTokensBefore,
-                tokensAfter: stageTokensAfter,
-                saved: stageTokensBefore - stageTokensAfter,
+                estimatedTokens: tokensBefore,
+                budgetTokens: targetTokens,
             });
-        }
-        // Stage 2: File Read Deduplication
-        if (this.config.enableDeduplicate &&
-            estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-            const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-            const dedupResult = deduplicateFileReads(currentMessages);
-            if (dedupResult.deduplicated) {
-                currentMessages = dedupResult.messages;
-                stagesUsed.push("deduplicate");
-            }
-            const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-            logger.info("[Compaction] Stage 2 (deduplicate)", {
-                requestId,
-                ran: dedupResult.deduplicated,
-                tokensBefore: stageTokensBefore,
-                tokensAfter: stageTokensAfter,
-                saved: stageTokensBefore - stageTokensAfter,
-            });
-        }
-        // Stage 3: LLM Summarization
-        if (this.config.enableSummarize &&
-            estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-            const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-            try {
-                const summarizeResult = await summarizeMessages(currentMessages, {
-                    provider: this.config.summarizationProvider,
-                    model: this.config.summarizationModel,
-                    keepRecentRatio: this.config.keepRecentRatio,
-                    memoryConfig,
+            // Stage 1: Tool Output Pruning
+            if (this.config.enablePrune &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                const pruneResult = pruneToolOutputs(currentMessages, {
+                    protectTokens: this.config.pruneProtectTokens,
+                    minimumSavings: this.config.pruneMinimumSavings,
+                    protectedTools: this.config.pruneProtectedTools,
+                    provider,
                 });
-                if (summarizeResult.summarized) {
-                    currentMessages = summarizeResult.messages;
-                    stagesUsed.push("summarize");
+                if (pruneResult.pruned) {
+                    currentMessages = pruneResult.messages;
+                    stagesUsed.push("prune");
                 }
                 const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                logger.info("[Compaction] Stage 3 (summarize)", {
+                logger.info("[Compaction] Stage 1 (prune)", {
                     requestId,
-                    ran: summarizeResult.summarized,
+                    ran: pruneResult.pruned,
                     tokensBefore: stageTokensBefore,
                     tokensAfter: stageTokensAfter,
                     saved: stageTokensBefore - stageTokensAfter,
                 });
             }
-            catch (error) {
-                // Capture the actual error for debugging
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                const errorName = error instanceof Error ? error.name : "UnknownError";
-                logger.warn("[Compaction] Stage 3 (summarize) FAILED", {
+            // Stage 2: File Read Deduplication
+            if (this.config.enableDeduplicate &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                const dedupResult = deduplicateFileReads(currentMessages);
+                if (dedupResult.deduplicated) {
+                    currentMessages = dedupResult.messages;
+                    stagesUsed.push("deduplicate");
+                }
+                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                logger.info("[Compaction] Stage 2 (deduplicate)", {
                     requestId,
-                    error: errorMessage,
-                    errorName,
+                    ran: dedupResult.deduplicated,
                     tokensBefore: stageTokensBefore,
-                    tokensAfter: stageTokensBefore,
-                    saved: 0,
+                    tokensAfter: stageTokensAfter,
+                    saved: stageTokensBefore - stageTokensAfter,
                 });
-                // Record on OTel span for trace visibility
-                const activeSpan = trace.getActiveSpan();
-                if (activeSpan) {
-                    activeSpan.addEvent("compaction.stage3.failed", {
-                        "error.message": errorMessage,
-                        "error.name": errorName,
-                        "stage.tokens_before": stageTokensBefore,
-                    });
-                    if (error instanceof Error) {
-                        activeSpan.recordException(error);
+            }
+            // Stage 3: LLM Summarization
+            if (this.config.enableSummarize &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                try {
+                    const summarizeResult = await withTimeout(summarizeMessages(currentMessages, {
+                        provider: this.config.summarizationProvider,
+                        model: this.config.summarizationModel,
+                        keepRecentRatio: this.config.keepRecentRatio,
+                        memoryConfig,
+                    }), 120_000, "LLM summarization timed out after 120s");
+                    if (summarizeResult.summarized) {
+                        currentMessages = summarizeResult.messages;
+                        stagesUsed.push("summarize");
                     }
-                    // NLK-GAP-005 fix: set error status alongside recordException
-                    activeSpan.setStatus({
-                        code: SpanStatusCode.ERROR,
-                        message: `Compaction stage 3 (summarize) failed: ${errorMessage}`,
+                    const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                    logger.info("[Compaction] Stage 3 (summarize)", {
+                        requestId,
+                        ran: summarizeResult.summarized,
+                        tokensBefore: stageTokensBefore,
+                        tokensAfter: stageTokensAfter,
+                        saved: stageTokensBefore - stageTokensAfter,
+                    });
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    logger.warn("[Compaction] Stage 3 (summarize) FAILED", {
+                        requestId,
+                        error: err.message,
+                        errorName: err.name,
+                        tokensBefore: stageTokensBefore,
+                        tokensAfter: stageTokensBefore,
+                        saved: 0,
+                    });
+                    // Record failure on the compaction span for trace visibility
+                    SpanSerializer.updateAttributes(span, {
+                        "compaction.stage3.error": err.message,
+                        "compaction.stage3.errorName": err.name,
+                        "compaction.stage3.tokensBefore": stageTokensBefore,
+                        "compaction.stage3_failed": true,
                     });
+                    // Fall through to Stage 4 truncation as before
                 }
-                // Fall through to Stage 4 truncation as before
             }
-        }
-        // Stage 4: Sliding Window Truncation (fallback)
-        if (this.config.enableTruncate &&
-            estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-            const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-            const truncResult = truncateWithSlidingWindow(currentMessages, {
-                fraction: this.config.truncationFraction,
-                currentTokens: stageTokensBefore,
-                targetTokens: targetTokens,
-                provider: provider,
-                adaptiveBuffer: 0.15,
-                maxIterations: 3,
-            });
-            if (truncResult.truncated) {
-                currentMessages = truncResult.messages;
-                stagesUsed.push("truncate");
+            // Stage 4: Sliding Window Truncation (fallback)
+            if (this.config.enableTruncate &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                const truncResult = truncateWithSlidingWindow(currentMessages, {
+                    fraction: this.config.truncationFraction,
+                });
+                if (truncResult.truncated) {
+                    currentMessages = truncResult.messages;
+                    stagesUsed.push("truncate");
+                }
+                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                logger.info("[Compaction] Stage 4 (truncate)", {
+                    requestId,
+                    ran: truncResult.truncated,
+                    tokensBefore: stageTokensBefore,
+                    tokensAfter: stageTokensAfter,
+                    saved: stageTokensBefore - stageTokensAfter,
+                });
             }
-            const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-            logger.info("[Compaction] Stage 4 (truncate)", {
+            const tokensAfter = estimateMessagesTokens(currentMessages, provider);
+            logger.info("[Compaction] Complete", {
                 requestId,
-                ran: truncResult.truncated,
-                tokensBefore: stageTokensBefore,
-                tokensAfter: stageTokensAfter,
-                saved: stageTokensBefore - stageTokensAfter,
+                tokensBefore,
+                tokensAfter,
+                totalSaved: tokensBefore - tokensAfter,
+                stagesUsed,
+                durationMs: Date.now() - spanStartTime,
             });
+            const result = {
+                compacted: stagesUsed.length > 0,
+                stagesUsed,
+                tokensBefore,
+                tokensAfter,
+                tokensSaved: tokensBefore - tokensAfter,
+                messages: currentMessages,
+            };
+            span.durationMs = Date.now() - spanStartTime;
+            const endedSpan = SpanSerializer.endSpan(SpanSerializer.updateAttributes(span, {
+                "context.stage": stagesUsed.join(",") || "none",
+                "context.tokensBefore": tokensBefore,
+                "context.tokensAfter": tokensAfter,
+                "context.tokensSaved": tokensBefore - tokensAfter,
+            }), SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+            return result;
+        }
+        catch (error) {
+            span.durationMs = Date.now() - spanStartTime;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+            endedSpan.statusMessage =
+                error instanceof Error ? error.message : String(error);
+            getMetricsAggregator().recordSpan(endedSpan);
+            throw error;
         }
-        const tokensAfter = estimateMessagesTokens(currentMessages, provider);
-        logger.info("[Compaction] Complete", {
-            requestId,
-            tokensBefore,
-            tokensAfter,
-            totalSaved: tokensBefore - tokensAfter,
-            stagesUsed,
-            durationMs: Date.now() - compactionStartTime,
-        });
-        return {
-            compacted: stagesUsed.length > 0,
-            stagesUsed,
-            tokensBefore,
-            tokensAfter,
-            tokensSaved: tokensBefore - tokensAfter,
-            messages: currentMessages,
-        };
     }
 }

package/dist/core/baseProvider.d.ts

@@ -24,6 +24,11 @@ export declare abstract class BaseProvider implements AIProvider {
     protected sessionId?: string;
     protected userId?: string;
     protected neurolink?: NeuroLink;
+    /** Trace context propagated from NeuroLink SDK for span hierarchy */
+    _traceContext: {
+        traceId: string;
+        parentSpanId: string;
+    } | null;
     private readonly messageBuilder;
     private readonly streamHandler;
     private readonly generationHandler;

package/dist/core/baseProvider.js

@@ -1,17 +1,16 @@
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { generateText } from "ai";
-import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-import { tracers } from "../telemetry/tracers.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
+import { ATTR, tracers } from "../telemetry/index.js";
 import { isAbortError } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
-import { calculateCost } from "../utils/pricing.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
 import { TTSProcessor } from "../utils/ttsProcessor.js";
-import { hasVideoFrames, executeVideoAnalysis, } from "../utils/videoAnalysisProcessor.js";
+import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
 import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
@@ -19,7 +18,6 @@ import { StreamHandler } from "./modules/StreamHandler.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 import { ToolsManager } from "./modules/ToolsManager.js";
 import { Utilities } from "./modules/Utilities.js";
-const providerTracer = tracers.provider;
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -39,6 +37,8 @@ export class BaseProvider {
     sessionId;
     userId;
     neurolink; // Reference to actual NeuroLink instance for MCP tools
+    /** Trace context propagated from NeuroLink SDK for span hierarchy */
+    _traceContext = null;
     // Composition modules - Single Responsibility Principle
     messageBuilder;
     streamHandler;
@@ -80,10 +80,18 @@ export class BaseProvider {
      * When tools are involved, falls back to generate() with synthetic streaming
      */
     async stream(optionsOrPrompt, analysisSchema) {
-        return providerTracer.startActiveSpan("neurolink.provider.stream", { kind: SpanKind.INTERNAL }, async (span) => {
-            let options = this.normalizeStreamOptions(optionsOrPrompt);
-            span.setAttribute("gen_ai.system", this.providerName || "unknown");
-            span.setAttribute("gen_ai.request.model", this.modelName || options.model || "unknown");
+        let options = this.normalizeStreamOptions(optionsOrPrompt);
+        // OTEL span for provider-level stream tracing
+        const otelStreamSpan = tracers.provider.startSpan("neurolink.provider.stream", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                [ATTR.GEN_AI_SYSTEM]: this.providerName || "unknown",
+                [ATTR.GEN_AI_MODEL]: this.modelName || options.model || "unknown",
+                [ATTR.GEN_AI_OPERATION]: "stream",
+                [ATTR.NL_PROVIDER]: this.providerName || "unknown",
+            },
+        });
+        try {
             logger.info(`Starting stream`, {
                 provider: this.providerName,
                 hasTools: !options.disableTools && this.supportsTools(),
@@ -94,93 +102,91 @@ export class BaseProvider {
                 temperature: options.temperature,
                 timestamp: Date.now(),
             });
-            try {
-                // ===== EARLY MULTIMODAL DETECTION =====
-                const hasFileInput = !!options.input?.files?.length ||
-                    !!options.input?.videoFiles?.length;
-                if (hasFileInput) {
-                    // ===== VIDEO ANALYSIS DETECTION =====
-                    // Check if video frames are present and handle with fake streaming
-                    const messages = await this.buildMessagesForStream(options);
-                    if (hasVideoFrames(messages)) {
-                        logger.info(`Video frames detected in stream, using fake streaming for video analysis`, {
-                            provider: this.providerName,
-                            model: this.modelName,
-                        });
-                        span.setAttribute("neurolink.stream_mode", "fake");
-                        return await this.executeFakeStreaming(options, analysisSchema);
-                    }
-                }
-                // Image generation models don't support real streaming
-                // Force fake streaming for image models to ensure image output is yielded
-                const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
-                if (isImageModel) {
-                    logger.info(`Image model detected, forcing fake streaming`, {
+            // ===== EARLY MULTIMODAL DETECTION =====
+            const hasFileInput = !!options.input?.files?.length || !!options.input?.videoFiles?.length;
+            if (hasFileInput) {
+                // ===== VIDEO ANALYSIS DETECTION =====
+                // Check if video frames are present and handle with fake streaming
+                const messages = await this.buildMessagesForStream(options);
+                if (hasVideoFrames(messages)) {
+                    logger.info(`Video frames detected in stream, using fake streaming for video analysis`, {
                         provider: this.providerName,
                         model: this.modelName,
-                        reason: "Image generation requires fake streaming to yield image output",
                     });
-                    // Skip real streaming, go directly to fake streaming
-                    span.setAttribute("neurolink.stream_mode", "fake");
                     return await this.executeFakeStreaming(options, analysisSchema);
                 }
-                // Central tool merge: Pre-merge base tools (MCP/built-in) with user-provided
-                // tools (e.g. RAG tools) into options.tools. This way, every provider's
-                // executeStream() can simply use options.tools (or getAllTools() + options.tools)
-                // and get the complete tool set without needing per-provider merge logic.
+            }
+            // CRITICAL: Image generation models don't support real streaming
+            // Force fake streaming for image models to ensure image output is yielded
+            const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
+            if (isImageModel) {
+                logger.info(`Image model detected, forcing fake streaming`, {
+                    provider: this.providerName,
+                    model: this.modelName,
+                    reason: "Image generation requires fake streaming to yield image output",
+                });
+                // Skip real streaming, go directly to fake streaming
+                return await this.executeFakeStreaming(options, analysisSchema);
+            }
+            // Central tool merge: Pre-merge base tools (MCP/built-in) with user-provided
+            // tools (e.g. RAG tools) into options.tools. This way, every provider's
+            // executeStream() can simply use options.tools (or getAllTools() + options.tools)
+            // and get the complete tool set without needing per-provider merge logic.
+            if (!options.disableTools && this.supportsTools()) {
+                const mergedTools = await this.getToolsForStream(options);
+                options = { ...options, tools: mergedTools };
+            }
+            else {
+                options = { ...options, tools: {} };
+            }
+            // CRITICAL FIX: Always prefer real streaming over fake streaming
+            // Try real streaming first, use fake streaming only as fallback
+            try {
+                logger.debug(`Attempting real streaming`, {
+                    provider: this.providerName,
+                    timestamp: Date.now(),
+                });
+                const realStreamResult = await this.executeStream(options, analysisSchema);
+                logger.info(`Real streaming succeeded`, {
+                    provider: this.providerName,
+                    timestamp: Date.now(),
+                });
+                // If real streaming succeeds, return it (with tools support via Vercel AI SDK)
+                return realStreamResult;
+            }
+            catch (realStreamError) {
+                logger.warn(`Real streaming failed for ${this.providerName}, falling back to fake streaming:`, {
+                    error: realStreamError instanceof Error
+                        ? realStreamError.message
+                        : String(realStreamError),
+                    timestamp: Date.now(),
+                });
+                // Fallback to fake streaming only if real streaming fails AND tools are enabled
                 if (!options.disableTools && this.supportsTools()) {
-                    const mergedTools = await this.getToolsForStream(options);
-                    options = { ...options, tools: mergedTools };
+                    return await this.executeFakeStreaming(options, analysisSchema);
                 }
                 else {
-                    options = { ...options, tools: {} };
-                }
-                // CRITICAL FIX: Always prefer real streaming over fake streaming
-                // Try real streaming first, use fake streaming only as fallback
-                try {
-                    logger.debug(`Attempting real streaming`, {
-                        provider: this.providerName,
-                        timestamp: Date.now(),
-                    });
-                    const realStreamResult = await this.executeStream(options, analysisSchema);
-                    logger.info(`Real streaming succeeded`, {
-                        provider: this.providerName,
-                        timestamp: Date.now(),
-                    });
-                    span.setAttribute("neurolink.stream_mode", "real");
-                    // If real streaming succeeds, return it (with tools support via Vercel AI SDK)
-                    return realStreamResult;
-                }
-                catch (realStreamError) {
-                    logger.warn(`Real streaming failed for ${this.providerName}, falling back to fake streaming:`, {
-                        error: realStreamError instanceof Error
-                            ? realStreamError.message
-                            : String(realStreamError),
-                        timestamp: Date.now(),
-                    });
-                    // Fallback to fake streaming only if real streaming fails AND tools are enabled
-                    if (!options.disableTools && this.supportsTools()) {
-                        span.setAttribute("neurolink.stream_mode", "fake");
-                        return await this.executeFakeStreaming(options, analysisSchema);
-                    }
-                    else {
-                        // If real streaming failed and no tools are enabled, re-throw the original error
-                        logger.error(`Real streaming failed for ${this.providerName}:`, realStreamError);
-                        throw this.handleProviderError(realStreamError);
-                    }
+                    // If real streaming failed and no tools are enabled, re-throw the original error
+                    logger.error(`Real streaming failed for ${this.providerName}:`, realStreamError);
+                    throw this.handleProviderError(realStreamError);
                 }
             }
-            catch (error) {
-                span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: error instanceof Error ? error.message : String(error),
-                });
-                throw error;
-            }
-            finally {
-                span.end();
+        }
+        catch (error) {
+            otelStreamSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            otelStreamSpan.end();
+            throw error;
+        }
+        finally {
+            // End OTEL span on success (only if not already ended via error path)
+            if (otelStreamSpan.isRecording()) {
+                otelStreamSpan.setStatus({ code: SpanStatusCode.OK });
+                otelStreamSpan.end();
             }
-        });
+        }
     }
     /**
      * Execute fake streaming - extracted method for reusability
@@ -468,12 +474,24 @@ export class BaseProvider {
      * for consistency and better performance
      */
     async generate(optionsOrPrompt, _analysisSchema) {
-        return providerTracer.startActiveSpan("neurolink.provider.generate", { kind: SpanKind.INTERNAL }, async (span) => {
-            const options = this.normalizeTextOptions(optionsOrPrompt);
-            this.validateOptions(options);
-            const startTime = Date.now();
-            span.setAttribute("gen_ai.system", this.providerName || "unknown");
-            span.setAttribute("gen_ai.request.model", this.modelName || options.model || "unknown");
+        const options = this.normalizeTextOptions(optionsOrPrompt);
+        this.validateOptions(options);
+        const startTime = Date.now();
+        // OTEL span for provider-level generate tracing
+        // Use startActiveSpan pattern via context.with() so child spans become descendants
+        const otelSpan = tracers.provider.startSpan("neurolink.provider.generate", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                [ATTR.GEN_AI_SYSTEM]: this.providerName || "unknown",
+                [ATTR.GEN_AI_MODEL]: this.modelName || options.model || "unknown",
+                [ATTR.GEN_AI_OPERATION]: "generate",
+                [ATTR.NL_PROVIDER]: this.providerName || "unknown",
+            },
+        });
+        // Set this span as the active context so child spans (GenerationHandler, etc.) become descendants
+        const activeCtx = trace.setSpan(context.active(), otelSpan);
+        let otelSpanEnded = false;
+        return await context.with(activeCtx, async () => {
             try {
                 // ===== VIDEO GENERATION MODE =====
                 // Generate video from image + prompt using Veo 3.1
@@ -647,29 +665,15 @@ export class BaseProvider {
                         });
                     }
                 }
-                // Set token usage on span from the result
-                if (enhancedResult?.usage) {
-                    span.setAttribute("gen_ai.usage.input_tokens", enhancedResult.usage.input || 0);
-                    span.setAttribute("gen_ai.usage.output_tokens", enhancedResult.usage.output || 0);
-                    // Cost on span so users can query "what did this trace cost?"
-                    const cost = calculateCost(this.providerName, this.modelName, {
-                        input: enhancedResult.usage.input || 0,
-                        output: enhancedResult.usage.output || 0,
-                        total: enhancedResult.usage.total || 0,
-                    });
-                    span.setAttribute("neurolink.cost", cost ?? 0);
-                }
-                if (enhancedResult?.finishReason) {
-                    span.setAttribute("gen_ai.response.finish_reason", enhancedResult.finishReason);
-                }
-                span.setStatus({ code: SpanStatusCode.OK });
                 return await this.enhanceResult(enhancedResult, options, startTime);
             }
             catch (error) {
-                span.setStatus({
+                otelSpan.setStatus({
                     code: SpanStatusCode.ERROR,
                     message: error instanceof Error ? error.message : String(error),
                 });
+                otelSpan.end();
+                otelSpanEnded = true;
                 // Abort errors are expected when a generation is cancelled — log at info, not error
                 if (isAbortError(error)) {
                     logger.info(`Generate aborted for ${this.providerName}`, {
@@ -682,9 +686,12 @@ export class BaseProvider {
                 throw this.handleProviderError(error);
             }
             finally {
-                span.end();
+                if (!otelSpanEnded) {
+                    otelSpan.setStatus({ code: SpanStatusCode.OK });
+                    otelSpan.end();
+                }
             }
-        });
+        }); // end context.with
     }
     /**
      * Alias for generate method - implements AIProvider interface