@juspay/neurolink 9.24.0 → 9.25.1

package/dist/neurolink.js

@@ -13,15 +13,17 @@ try {
 catch {
     // Environment variables should be set externally in production
 }
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { AsyncLocalStorage } from "async_hooks";
 import { EventEmitter } from "events";
 import pLimit from "p-limit";
 import { ErrorCategory, ErrorSeverity } from "./constants/enums.js";
 import { CIRCUIT_BREAKER, CIRCUIT_BREAKER_RESET_MS, MEMORY_THRESHOLDS, NANOSECOND_TO_MS_DIVISOR, PERFORMANCE_THRESHOLDS, PROVIDER_TIMEOUTS, RETRY_ATTEMPTS, RETRY_DELAYS, TOOL_TIMEOUTS, } from "./constants/index.js";
 import { checkContextBudget } from "./context/budgetChecker.js";
 import { ContextCompactor, } from "./context/contextCompactor.js";
-import { isContextOverflowError, getContextOverflowProvider, parseProviderOverflowDetails, } from "./context/errorDetection.js";
-import { ContextBudgetExceededError } from "./context/errors.js";
 import { emergencyContentTruncation } from "./context/emergencyTruncation.js";
+import { getContextOverflowProvider, isContextOverflowError, parseProviderOverflowDetails, } from "./context/errorDetection.js";
+import { ContextBudgetExceededError } from "./context/errors.js";
 import { repairToolPairs } from "./context/toolPairRepair.js";
 import { SYSTEM_LIMITS } from "./core/constants.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
@@ -34,11 +36,17 @@ import { ExternalServerManager } from "./mcp/externalServerManager.js";
 // Import direct tools server for automatic registration
 import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
+import { initializeHippocampus, } from "./memory/hippocampusInitializer.js";
 import { initializeMem0 } from "./memory/mem0Initializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
-import { initializeHippocampus, } from "./memory/hippocampusInitializer.js";
+import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
+import { SpanStatus, SpanType } from "./observability/types/spanTypes.js";
+import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { flushOpenTelemetry, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
+import { ATTR } from "./telemetry/attributes.js";
+import { tracers } from "./telemetry/tracers.js";
 import { ConversationMemoryError } from "./types/conversation.js";
+import { AuthenticationError, AuthorizationError, InvalidModelError, } from "./types/errors.js";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
 import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
@@ -49,17 +57,13 @@ import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { getBestProvider } from "./utils/providerUtils.js";
+import { NON_RETRYABLE_HTTP_STATUS_CODES } from "./utils/retryability.js";
 import { isZodSchema } from "./utils/schemaConversion.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Tool detection and execution imports
 // Transformation utilities
 import { extractToolNames, optimizeToolForCollection, transformAvailableTools, transformParamsForLogging, transformToolExecutions, transformToolExecutionsForMCP, transformToolsForMCP, transformToolsToDescriptions, transformToolsToExpectedFormat, } from "./utils/transformationUtils.js";
-import { InvalidModelError, AuthenticationError, AuthorizationError, } from "./types/errors.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
-import { NON_RETRYABLE_HTTP_STATUS_CODES } from "./utils/retryability.js";
-import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-import { tracers } from "./telemetry/tracers.js";
-import { ATTR } from "./telemetry/attributes.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
 /**
@@ -109,77 +113,11 @@ 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'
- * });
- *
- * 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
+ * same NeuroLink instance would clobber each other's trace context.
  */
+const metricsTraceContextStorage = new AsyncLocalStorage();
 export class NeuroLink {
     mcpInitialized = false;
     mcpInitPromise = null;
@@ -422,6 +360,15 @@ export class NeuroLink {
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
     observabilityConfig;
+    metricsAggregator = new 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.
+     */
+    get _metricsTraceContext() {
+        return metricsTraceContextStorage.getStore() ?? null;
+    }
     constructor(config) {
         this.toolRegistry = config?.toolRegistry || new MCPToolRegistry();
         this.fileRegistry = new FileReferenceRegistry();
@@ -444,6 +391,7 @@ export class NeuroLink {
         this.registerFileTools();
         this.registerMemoryRetrievalTools();
         this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
+        this.initializeMetricsListeners();
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
     }
     /**
@@ -666,9 +614,6 @@ export class NeuroLink {
             logger.debug("[NeuroLink] Skipping memory retrieval tools — requires Redis conversation memory");
             return;
         }
-        // Defer registration until conversation memory is actually initialized
-        // We register a placeholder that will use the lazy-initialized memory manager
-        const self = this;
         const tools = {
             retrieve_context: {
                 description: "Retrieve messages from conversation memory. Use this to access full tool " +
@@ -676,7 +621,7 @@ export class NeuroLink {
                     "or search through conversation history.",
                 execute: async (params) => {
                     // Lazy access: conversationMemory is initialized on first generate() call
-                    const memoryManager = self.conversationMemory;
+                    const memoryManager = this.conversationMemory;
                     if (!memoryManager || !("getSessionRaw" in memoryManager)) {
                         return {
                             success: false,
@@ -1576,6 +1521,88 @@ Current user's request: ${currentInput}`;
         // Check if OpenTelemetry was initialized (by this or external app)
         return isOpenTelemetryInitialized();
     }
+    /**
+     * Get comprehensive telemetry status including Langfuse, OTel, and exporter health
+     */
+    getTelemetryStatus() {
+        const langfuseConfig = this.observabilityConfig?.langfuse;
+        const otelConfig = this.observabilityConfig?.openTelemetry;
+        return {
+            enabled: this.isTelemetryEnabled(),
+            langfuse: langfuseConfig
+                ? {
+                    enabled: langfuseConfig.enabled ?? false,
+                    baseUrl: langfuseConfig.baseUrl,
+                    environment: langfuseConfig.environment,
+                }
+                : undefined,
+            openTelemetry: otelConfig
+                ? {
+                    enabled: otelConfig.enabled ?? false,
+                    endpoint: otelConfig.endpoint,
+                    serviceName: otelConfig.serviceName,
+                }
+                : isOpenTelemetryInitialized() ||
+                    process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+                    ? {
+                        enabled: isOpenTelemetryInitialized(),
+                        endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+                        serviceName: process.env.OTEL_SERVICE_NAME,
+                    }
+                    : undefined,
+            exporters: [],
+        };
+    }
+    /**
+     * Get aggregated observability metrics (latency, tokens, cost, success rate)
+     */
+    getMetrics() {
+        return this.metricsAggregator.getMetrics();
+    }
+    /**
+     * Get all recorded spans
+     */
+    getSpans() {
+        return this.metricsAggregator.getSpans();
+    }
+    /**
+     * Get traces (spans grouped by traceId with parent-child hierarchy)
+     */
+    getTraces() {
+        return this.metricsAggregator.getTraces();
+    }
+    /**
+     * Reset all collected metrics and spans
+     */
+    resetMetrics() {
+        this.metricsAggregator.reset();
+    }
+    /**
+     * Record a span for metrics tracking
+     */
+    recordMetricsSpan(span) {
+        this.metricsAggregator.recordSpan(span);
+    }
+    /**
+     * Record a memory operation span to both instance and global metrics aggregators.
+     * This ensures memory spans are visible via sdk.getSpans() and getMetricsAggregator().getSpans().
+     */
+    recordMemorySpan(operationName, attributes, durationMs, status, statusMessage) {
+        const traceCtx = this._metricsTraceContext;
+        const span = SpanSerializer.createSpan(SpanType.MEMORY, operationName, attributes, traceCtx?.parentSpanId, traceCtx?.traceId);
+        span.durationMs = durationMs;
+        const endedSpan = SpanSerializer.endSpan(span, status);
+        if (statusMessage) {
+            endedSpan.statusMessage = statusMessage;
+        }
+        this.metricsAggregator.recordSpan(endedSpan);
+        try {
+            getMetricsAggregator().recordSpan(endedSpan);
+        }
+        catch {
+            /* ignore */
+        }
+    }
     /**
      * Public method to initialize Langfuse observability
      * This method can be called externally to ensure Langfuse is properly initialized
@@ -1618,6 +1645,16 @@ Current user's request: ${currentInput}`;
                     logger.warn("[NeuroLink] MCP servers shutdown failed:", error);
                 }
             }
+            // Close conversation memory manager (release Redis connections, etc.)
+            if (this.conversationMemory?.close) {
+                try {
+                    await this.conversationMemory.close();
+                    logger.debug("[NeuroLink] Conversation memory shutdown completed");
+                }
+                catch (error) {
+                    logger.warn("[NeuroLink] Conversation memory shutdown failed:", error);
+                }
+            }
             logger.debug("[NeuroLink] Graceful shutdown completed");
         }
         catch (error) {
@@ -1625,6 +1662,233 @@ Current user's request: ${currentInput}`;
             throw error;
         }
     }
+    /**
+     * Initialize event listeners that feed span data to MetricsAggregator.
+     * Listens to generation:end, stream:complete, and tool:end events.
+     */
+    initializeMetricsListeners() {
+        this.emitter.on("generation:end", ((...args) => {
+            const data = args[0];
+            try {
+                const result = data.result;
+                const usage = result?.usage;
+                const analytics = result?.analytics;
+                const provider = data.provider ||
+                    result?.provider ||
+                    "unknown";
+                const model = result?.model || "unknown";
+                const responseTime = data.responseTime || 0;
+                const traceCtx = this._metricsTraceContext;
+                let span = SpanSerializer.createGenerationSpan({
+                    provider,
+                    model,
+                    name: `gen_ai.${provider}.chat`,
+                    traceId: traceCtx?.traceId,
+                    input: data.prompt,
+                    temperature: data.temperature,
+                    maxTokens: data.maxTokens,
+                });
+                // Make this the root span by using the pre-generated rootSpanId
+                if (traceCtx) {
+                    span.spanId = traceCtx.parentSpanId;
+                    span.parentSpanId = undefined;
+                }
+                // Mark failed generations with ERROR status so metrics count them correctly
+                const spanStatus = data.success === false || data.error
+                    ? SpanStatus.ERROR
+                    : SpanStatus.OK;
+                span = SpanSerializer.endSpan(span, spanStatus, data.error ? String(data.error) : undefined);
+                span.durationMs = responseTime;
+                if (usage) {
+                    span = SpanSerializer.enrichWithTokenUsage(span, {
+                        promptTokens: usage.input || 0,
+                        completionTokens: usage.output || 0,
+                        totalTokens: usage.total || (usage.input || 0) + (usage.output || 0),
+                    });
+                }
+                if (analytics?.cost && analytics.cost > 0) {
+                    span = SpanSerializer.enrichWithCost(span, {
+                        totalCost: analytics.cost,
+                    });
+                }
+                else if (usage && model !== "unknown") {
+                    // Fallback: compute cost from token usage + built-in pricing
+                    const tokenTracker = this.metricsAggregator.getTokenTracker();
+                    const pricing = tokenTracker.getModelPricing(model);
+                    if (pricing) {
+                        const inputCost = ((usage.input || 0) / 1_000_000) * pricing.inputPricePerMillion;
+                        const outputCost = ((usage.output || 0) / 1_000_000) * pricing.outputPricePerMillion;
+                        const totalCost = inputCost + outputCost;
+                        if (totalCost > 0) {
+                            span = SpanSerializer.enrichWithCost(span, {
+                                inputCost,
+                                outputCost,
+                                totalCost,
+                            });
+                        }
+                    }
+                }
+                // Record output (truncated for safety)
+                const content = result?.content || result?.text;
+                if (content) {
+                    span = SpanSerializer.updateAttributes(span, {
+                        output: content.length > 5000
+                            ? content.substring(0, 5000) + "...[truncated]"
+                            : content,
+                    });
+                }
+                this.metricsAggregator.recordSpan(span);
+                getMetricsAggregator().recordSpan(span);
+            }
+            catch {
+                // Non-blocking
+            }
+        }));
+        this.emitter.on("stream:complete", ((...args) => {
+            const data = args[0];
+            try {
+                const metadata = data.metadata;
+                const durationMs = metadata?.durationMs || 0;
+                const chunkCount = metadata?.chunkCount || 0;
+                const totalLength = metadata?.totalLength || 0;
+                const provider = data.provider || "unknown";
+                const model = data.model || "unknown";
+                const traceCtx = this._metricsTraceContext;
+                let span = SpanSerializer.createGenerationSpan({
+                    provider,
+                    model,
+                    name: `gen_ai.${provider}.stream`,
+                    traceId: traceCtx?.traceId,
+                });
+                // Make this the root span by using the pre-generated rootSpanId
+                if (traceCtx) {
+                    span.spanId = traceCtx.parentSpanId;
+                    span.parentSpanId = undefined;
+                }
+                span = SpanSerializer.endSpan(span, SpanStatus.OK);
+                span.durationMs = durationMs;
+                span.attributes["stream.chunk_count"] = chunkCount;
+                span.attributes["stream.content_length"] = totalLength;
+                // Record stream input prompt
+                if (data.prompt) {
+                    const promptStr = String(data.prompt);
+                    span = SpanSerializer.updateAttributes(span, {
+                        input: promptStr.length > 5000
+                            ? promptStr.substring(0, 5000) + "...[truncated]"
+                            : promptStr,
+                    });
+                }
+                // Record streamed output (truncated for safety)
+                const streamContent = data.content;
+                if (streamContent) {
+                    span = SpanSerializer.updateAttributes(span, {
+                        output: streamContent.length > 5000
+                            ? streamContent.substring(0, 5000) + "...[truncated]"
+                            : streamContent,
+                    });
+                }
+                // Enrich stream span with token usage if available
+                const usage = metadata?.usage;
+                if (usage) {
+                    span = SpanSerializer.enrichWithTokenUsage(span, {
+                        promptTokens: usage.input || 0,
+                        completionTokens: usage.output || 0,
+                        totalTokens: usage.total || (usage.input || 0) + (usage.output || 0),
+                    });
+                    // Compute cost from token usage
+                    if (model !== "unknown") {
+                        const tokenTracker = this.metricsAggregator.getTokenTracker();
+                        const pricing = tokenTracker.getModelPricing(model);
+                        if (pricing) {
+                            const inputCost = ((usage.input || 0) / 1_000_000) * pricing.inputPricePerMillion;
+                            const outputCost = ((usage.output || 0) / 1_000_000) *
+                                pricing.outputPricePerMillion;
+                            const totalCost = inputCost + outputCost;
+                            if (totalCost > 0) {
+                                span = SpanSerializer.enrichWithCost(span, {
+                                    inputCost,
+                                    outputCost,
+                                    totalCost,
+                                });
+                            }
+                        }
+                    }
+                }
+                this.metricsAggregator.recordSpan(span);
+                getMetricsAggregator().recordSpan(span);
+            }
+            catch {
+                // Non-blocking
+            }
+        }));
+        this.emitter.on("tool:end", ((...args) => {
+            const data = args[0];
+            try {
+                // Handle both event formats: {toolName} (from emitToolEnd) and {tool} (from executeToolInternal)
+                const toolName = data.toolName || data.tool || "unknown";
+                const responseTime = data.responseTime || data.duration || 0;
+                // success is explicit in one format; infer from error presence in the other
+                const success = data.success !== undefined ? data.success : !data.error;
+                const traceCtx = this._metricsTraceContext;
+                let span = SpanSerializer.createSpan(SpanType.TOOL_CALL, `tool.${toolName}`, {
+                    "tool.name": toolName,
+                    "tool.success": success,
+                }, 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 (data.result) {
+                    try {
+                        span.attributes["tool.result"] = JSON.stringify(data.result).substring(0, 500);
+                    }
+                    catch {
+                        // Non-blocking
+                    }
+                }
+                this.metricsAggregator.recordSpan(span);
+                getMetricsAggregator().recordSpan(span);
+            }
+            catch {
+                // Non-blocking
+            }
+        }));
+        this.emitter.on("stream:error", ((...args) => {
+            const data = args[0];
+            try {
+                const metadata = data.metadata;
+                const durationMs = metadata?.durationMs || 0;
+                const chunkCount = metadata?.chunkCount || 0;
+                const errorName = metadata?.errorName || "UnknownError";
+                const errorMessage = data.content || "Stream error";
+                const provider = data.provider || "unknown";
+                const model = data.model || "unknown";
+                const traceCtx = this._metricsTraceContext;
+                let span = SpanSerializer.createGenerationSpan({
+                    provider,
+                    model,
+                    name: `gen_ai.${provider}.stream.error`,
+                    traceId: traceCtx?.traceId,
+                });
+                // Make this the root span
+                if (traceCtx) {
+                    span.spanId = traceCtx.parentSpanId;
+                    span.parentSpanId = undefined;
+                }
+                span = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+                span.durationMs = durationMs;
+                span.statusMessage = `${errorName}: ${errorMessage}`;
+                span.attributes["stream.chunk_count"] = chunkCount;
+                this.metricsAggregator.recordSpan(span);
+                getMetricsAggregator().recordSpan(span);
+            }
+            catch {
+                // Non-blocking
+            }
+        }));
+    }
     /**
      * Generate AI response with comprehensive feature support.
      *
@@ -1727,320 +1991,350 @@ Current user's request: ${currentInput}`;
      */
     async generate(optionsOrPrompt) {
         return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, async (generateSpan) => {
-            try {
-                const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
-                // Convert string prompt to full options
-                const options = typeof optionsOrPrompt === "string"
-                    ? { input: { text: optionsOrPrompt } }
-                    : optionsOrPrompt;
-                // Set span attributes for observability
-                generateSpan.setAttribute("neurolink.provider", options.provider || "default");
-                generateSpan.setAttribute("neurolink.model", options.model || "default");
-                generateSpan.setAttribute("neurolink.input_length", typeof optionsOrPrompt === "string"
-                    ? optionsOrPrompt.length
-                    : options.input?.text?.length || 0);
-                generateSpan.setAttribute("neurolink.has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
-                // Validate prompt
-                if (!options.input?.text || typeof options.input.text !== "string") {
-                    throw new Error("Input text is required and must be a non-empty string");
-                }
-                // Check budget limit before making API call
-                if (options.maxBudgetUsd !== undefined &&
-                    options.maxBudgetUsd > 0 &&
-                    this._sessionCostUsd >= options.maxBudgetUsd) {
-                    throw new NeuroLinkError({
-                        code: "SESSION_BUDGET_EXCEEDED",
-                        message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
-                        category: ErrorCategory.VALIDATION,
-                        severity: ErrorSeverity.HIGH,
-                        retriable: false,
-                        context: {
-                            spent: this._sessionCostUsd,
-                            limit: options.maxBudgetUsd,
-                        },
-                    });
-                }
-                // Check if workflow is requested
-                if (options.workflow || options.workflowConfig) {
-                    return await this.generateWithWorkflow(options);
-                }
-                // Check if PPT output mode is requested
-                if (options.output?.mode === "ppt") {
-                    const pptResult = await this.generateWithPPT(options);
-                    generateSpan.setAttribute("neurolink.output_length", pptResult.content?.length ?? 0);
-                    if (pptResult.analytics) {
-                        generateSpan.setAttribute("neurolink.tokens.input", pptResult.analytics.tokenUsage?.input ?? 0);
-                        generateSpan.setAttribute("neurolink.tokens.output", pptResult.analytics.tokenUsage?.output ?? 0);
-                        generateSpan.setAttribute("neurolink.cost", pptResult.analytics.cost ?? 0);
+            // Set metrics trace context for parent-child span linking.
+            // The generation span will be the root (no parentSpanId).
+            // Tool spans will be children of the root span via rootSpanId.
+            const metricsTraceId = crypto.randomUUID().replace(/-/g, "");
+            const metricsRootSpanId = crypto
+                .randomUUID()
+                .replace(/-/g, "")
+                .substring(0, 16);
+            // Scope trace context to this request via AsyncLocalStorage
+            // so concurrent generate/stream calls don't race.
+            return metricsTraceContextStorage.run({ traceId: metricsTraceId, parentSpanId: metricsRootSpanId }, async () => {
+                try {
+                    const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
+                    // Convert string prompt to full options
+                    const options = typeof optionsOrPrompt === "string"
+                        ? { input: { text: optionsOrPrompt } }
+                        : optionsOrPrompt;
+                    // Set span attributes for observability
+                    generateSpan.setAttribute("neurolink.provider", options.provider || "default");
+                    generateSpan.setAttribute("neurolink.model", options.model || "default");
+                    generateSpan.setAttribute("neurolink.input_length", typeof optionsOrPrompt === "string"
+                        ? optionsOrPrompt.length
+                        : options.input?.text?.length || 0);
+                    generateSpan.setAttribute("neurolink.has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
+                    // Validate prompt
+                    if (!options.input?.text ||
+                        typeof options.input.text !== "string") {
+                        throw new Error("Input text is required and must be a non-empty string");
                     }
-                    generateSpan.setStatus({ code: SpanStatusCode.OK });
-                    return pptResult;
-                }
-                // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
-                return await this.setLangfuseContextFromOptions(options, async () => {
-                    if (this.conversationMemoryConfig?.conversationMemory?.mem0Enabled &&
-                        options.context?.userId) {
-                        try {
-                            const mem0 = await this.ensureMem0Ready();
-                            if (!mem0) {
-                                logger.debug("Mem0 not available, continuing without memory retrieval");
-                            }
-                            else {
-                                const memories = await mem0.search(options.input.text, {
-                                    user_id: options.context.userId,
-                                    limit: 5,
-                                });
-                                if (memories && memories.length > 0) {
-                                    // Enhance the input with memory context
-                                    const memoryContext = this.extractMemoryContext(memories);
-                                    options.input.text = this.formatMemoryContext(memoryContext, options.input.text);
-                                }
-                            }
-                        }
-                        catch (error) {
-                            logger.warn("Mem0 memory retrieval failed:", error);
-                        }
+                    // Check budget limit before making API call
+                    if (options.maxBudgetUsd !== undefined &&
+                        options.maxBudgetUsd > 0 &&
+                        this._sessionCostUsd >= options.maxBudgetUsd) {
+                        throw new NeuroLinkError({
+                            code: "SESSION_BUDGET_EXCEEDED",
+                            message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
+                            category: ErrorCategory.VALIDATION,
+                            severity: ErrorSeverity.HIGH,
+                            retriable: false,
+                            context: {
+                                spent: this._sessionCostUsd,
+                                limit: options.maxBudgetUsd,
+                            },
+                        });
                     }
-                    // Memory retrieval
-                    if (this.conversationMemoryConfig?.conversationMemory?.memory
-                        ?.enabled &&
-                        options.context?.userId) {
-                        try {
-                            options.input.text = await this.retrieveMemory(options.input.text, options.context.userId);
-                            logger.debug("Memory retrieval successful");
-                        }
-                        catch (error) {
-                            logger.warn("Memory retrieval failed:", error);
+                    // Check if workflow is requested
+                    if (options.workflow || options.workflowConfig) {
+                        return await this.generateWithWorkflow(options);
+                    }
+                    // Check if PPT output mode is requested
+                    if (options.output?.mode === "ppt") {
+                        const pptResult = await this.generateWithPPT(options);
+                        generateSpan.setAttribute("neurolink.output_length", pptResult.content?.length ?? 0);
+                        if (pptResult.analytics) {
+                            generateSpan.setAttribute("neurolink.tokens.input", pptResult.analytics.tokenUsage?.input ?? 0);
+                            generateSpan.setAttribute("neurolink.tokens.output", pptResult.analytics.tokenUsage?.output ?? 0);
+                            generateSpan.setAttribute("neurolink.cost", pptResult.analytics.cost ?? 0);
                         }
+                        generateSpan.setStatus({ code: SpanStatusCode.OK });
+                        return pptResult;
                     }
-                    const startTime = Date.now();
-                    // Apply orchestration if enabled and no specific provider/model requested
-                    if (this.enableOrchestration &&
-                        !options.provider &&
-                        !options.model) {
-                        try {
-                            const orchestratedOptions = await this.applyOrchestration(options);
-                            logger.debug("Orchestration applied", {
-                                originalProvider: options.provider || "auto",
-                                orchestratedProvider: orchestratedOptions.provider,
-                                orchestratedModel: orchestratedOptions.model,
-                                prompt: options.input.text.substring(0, 100),
-                            });
-                            // Use orchestrated options
-                            Object.assign(options, orchestratedOptions);
+                    // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
+                    return await this.setLangfuseContextFromOptions(options, async () => {
+                        if (this.conversationMemoryConfig?.conversationMemory
+                            ?.mem0Enabled &&
+                            options.context?.userId) {
+                            try {
+                                const mem0 = await this.ensureMem0Ready();
+                                if (!mem0) {
+                                    logger.debug("Mem0 not available, continuing without memory retrieval");
+                                }
+                                else {
+                                    const memories = await mem0.search(options.input.text, {
+                                        user_id: options.context.userId,
+                                        limit: 5,
+                                    });
+                                    if (memories && memories.length > 0) {
+                                        // Enhance the input with memory context
+                                        const memoryContext = this.extractMemoryContext(memories);
+                                        options.input.text = this.formatMemoryContext(memoryContext, options.input.text);
+                                    }
+                                }
+                            }
+                            catch (error) {
+                                logger.warn("Mem0 memory retrieval failed:", error);
+                            }
                         }
-                        catch (error) {
-                            logger.warn("Orchestration failed, continuing with original options", {
-                                error: error instanceof Error ? error.message : String(error),
-                                originalProvider: options.provider || "auto",
-                            });
-                            // Continue with original options if orchestration fails
+                        const startTime = Date.now();
+                        // Apply orchestration if enabled and no specific provider/model requested
+                        if (this.enableOrchestration &&
+                            !options.provider &&
+                            !options.model) {
+                            try {
+                                const orchestratedOptions = await this.applyOrchestration(options);
+                                logger.debug("Orchestration applied", {
+                                    originalProvider: options.provider || "auto",
+                                    orchestratedProvider: orchestratedOptions.provider,
+                                    orchestratedModel: orchestratedOptions.model,
+                                    prompt: options.input.text.substring(0, 100),
+                                });
+                                // Use orchestrated options
+                                Object.assign(options, orchestratedOptions);
+                            }
+                            catch (error) {
+                                logger.warn("Orchestration failed, continuing with original options", {
+                                    error: error instanceof Error
+                                        ? error.message
+                                        : String(error),
+                                    originalProvider: options.provider || "auto",
+                                });
+                                // Continue with original options if orchestration fails
+                            }
                         }
-                    }
-                    // Emit generation start event (NeuroLink format - keep existing)
-                    this.emitter.emit("generation:start", {
-                        provider: options.provider || "auto",
-                        timestamp: startTime,
-                    });
-                    // ADD: Bedrock-compatible response:start event
-                    this.emitter.emit("response:start");
-                    // ADD: Bedrock-compatible message event
-                    this.emitter.emit("message", `Starting ${options.provider || "auto"} text generation...`);
-                    // Process factory configuration
-                    const factoryResult = processFactoryOptions(options);
-                    // Validate factory configuration if present
-                    if (factoryResult.hasFactoryConfig && options.factoryConfig) {
-                        const validation = validateFactoryConfig(options.factoryConfig);
-                        if (!validation.isValid) {
-                            logger.warn("Invalid factory configuration detected", {
-                                errors: validation.errors,
-                            });
-                            // Continue with warning rather than throwing - graceful degradation
+                        // Emit generation start event (NeuroLink format - keep existing)
+                        this.emitter.emit("generation:start", {
+                            provider: options.provider || "auto",
+                            timestamp: startTime,
+                        });
+                        // ADD: Bedrock-compatible response:start event
+                        this.emitter.emit("response:start");
+                        // ADD: Bedrock-compatible message event
+                        this.emitter.emit("message", `Starting ${options.provider || "auto"} text generation...`);
+                        // Process factory configuration
+                        const factoryResult = processFactoryOptions(options);
+                        // Validate factory configuration if present
+                        if (factoryResult.hasFactoryConfig && options.factoryConfig) {
+                            const validation = validateFactoryConfig(options.factoryConfig);
+                            if (!validation.isValid) {
+                                logger.warn("Invalid factory configuration detected", {
+                                    errors: validation.errors,
+                                });
+                                // Continue with warning rather than throwing - graceful degradation
+                            }
                         }
-                    }
-                    // RAG Integration: If rag config is provided, prepare the RAG search tool
-                    if (options.rag?.files?.length) {
-                        try {
-                            const { prepareRAGTool } = await import("./rag/ragIntegration.js");
-                            const ragResult = await prepareRAGTool(options.rag, options.provider);
-                            // Inject the RAG tool into the tools record
-                            if (!options.tools) {
-                                options.tools = {};
+                        // RAG Integration: If rag config is provided, prepare the RAG search tool
+                        if (options.rag?.files?.length) {
+                            try {
+                                const { prepareRAGTool } = await import("./rag/ragIntegration.js");
+                                const ragResult = await prepareRAGTool(options.rag, options.provider);
+                                // Inject the RAG tool into the tools record
+                                if (!options.tools) {
+                                    options.tools = {};
+                                }
+                                options.tools[ragResult.toolName] = ragResult.tool;
+                                // Inject RAG-aware system prompt so the AI uses the RAG tool first
+                                const ragSystemInstruction = [
+                                    `\n\nIMPORTANT: You have a tool called "${ragResult.toolName}" that searches through`,
+                                    `${ragResult.filesLoaded} loaded document(s) containing ${ragResult.chunksIndexed} indexed chunks.`,
+                                    `ALWAYS use the "${ragResult.toolName}" tool FIRST to answer the user's question before using any other tools.`,
+                                    `This tool searches your local knowledge base of pre-loaded documents and is the primary source of truth.`,
+                                    `Do NOT use websearchGrounding or any web search tools when the answer can be found in the loaded documents.`,
+                                ].join(" ");
+                                options.systemPrompt =
+                                    (options.systemPrompt || "") + ragSystemInstruction;
+                                logger.info("[RAG] Tool injected into generate()", {
+                                    toolName: ragResult.toolName,
+                                    filesLoaded: ragResult.filesLoaded,
+                                    chunksIndexed: ragResult.chunksIndexed,
+                                });
+                            }
+                            catch (error) {
+                                logger.warn("[RAG] Failed to prepare RAG tool, continuing without RAG", {
+                                    error: error instanceof Error
+                                        ? error.message
+                                        : String(error),
+                                });
                             }
-                            options.tools[ragResult.toolName] =
-                                ragResult.tool;
-                            // Inject RAG-aware system prompt so the AI uses the RAG tool first
-                            const ragSystemInstruction = [
-                                `\n\nIMPORTANT: You have a tool called "${ragResult.toolName}" that searches through`,
-                                `${ragResult.filesLoaded} loaded document(s) containing ${ragResult.chunksIndexed} indexed chunks.`,
-                                `ALWAYS use the "${ragResult.toolName}" tool FIRST to answer the user's question before using any other tools.`,
-                                `This tool searches your local knowledge base of pre-loaded documents and is the primary source of truth.`,
-                                `Do NOT use websearchGrounding or any web search tools when the answer can be found in the loaded documents.`,
-                            ].join(" ");
-                            options.systemPrompt =
-                                (options.systemPrompt || "") + ragSystemInstruction;
-                            logger.info("[RAG] Tool injected into generate()", {
-                                toolName: ragResult.toolName,
-                                filesLoaded: ragResult.filesLoaded,
-                                chunksIndexed: ragResult.chunksIndexed,
-                            });
                         }
-                        catch (error) {
-                            logger.warn("[RAG] Failed to prepare RAG tool, continuing without RAG", {
-                                error: error instanceof Error ? error.message : String(error),
+                        // 🔧 CRITICAL FIX: Convert to TextGenerationOptions while preserving the input object for multimodal support
+                        const baseOptions = {
+                            prompt: options.input.text,
+                            provider: options.provider,
+                            model: options.model,
+                            temperature: options.temperature,
+                            maxTokens: options.maxTokens,
+                            systemPrompt: options.systemPrompt,
+                            schema: options.schema,
+                            output: options.output,
+                            tools: options.tools, // Includes RAG tools if rag config was provided
+                            disableTools: options.disableTools,
+                            toolFilter: options.toolFilter,
+                            excludeTools: options.excludeTools,
+                            maxSteps: options.maxSteps,
+                            toolChoice: options.toolChoice,
+                            prepareStep: options.prepareStep,
+                            enableAnalytics: options.enableAnalytics,
+                            enableEvaluation: options.enableEvaluation,
+                            context: options.context,
+                            evaluationDomain: options.evaluationDomain,
+                            toolUsageContext: options.toolUsageContext,
+                            input: options.input, // This includes text, images, and content arrays
+                            region: options.region,
+                            tts: options.tts,
+                            fileRegistry: this.fileRegistry,
+                            abortSignal: options.abortSignal,
+                            skipToolPromptInjection: options.skipToolPromptInjection,
+                        };
+                        // Auto-map top-level sessionId/userId to context for convenience
+                        // Tests and users may pass sessionId/userId as top-level options
+                        const extraContext = options;
+                        if (extraContext.sessionId || extraContext.userId) {
+                            baseOptions.context = {
+                                ...baseOptions.context,
+                                ...(extraContext.sessionId &&
+                                    !baseOptions.context?.sessionId
+                                    ? { sessionId: extraContext.sessionId }
+                                    : {}),
+                                ...(extraContext.userId && !baseOptions.context?.userId
+                                    ? { userId: extraContext.userId }
+                                    : {}),
+                            };
+                        }
+                        // Apply factory enhancement using centralized utilities
+                        const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
+                        // Pass conversation memory config if available
+                        if (this.conversationMemory) {
+                            textOptions.conversationMemoryConfig =
+                                this.conversationMemory.config;
+                            // Include original prompt for context summarization
+                            textOptions.originalPrompt = originalPrompt;
+                        }
+                        // Detect and execute domain-specific tools
+                        const { toolResults, enhancedPrompt } = await this.detectAndExecuteTools(textOptions.prompt || options.input.text, factoryResult.domainType);
+                        // Update prompt with tool results if available
+                        if (enhancedPrompt !== textOptions.prompt) {
+                            textOptions.prompt = enhancedPrompt;
+                            logger.debug("Enhanced prompt with tool results", {
+                                originalLength: options.input.text.length,
+                                enhancedLength: enhancedPrompt.length,
+                                toolResults: toolResults.length,
                             });
                         }
-                    }
-                    // 🔧 CRITICAL FIX: Convert to TextGenerationOptions while preserving the input object for multimodal support
-                    const baseOptions = {
-                        prompt: options.input.text,
-                        provider: options.provider,
-                        model: options.model,
-                        temperature: options.temperature,
-                        maxTokens: options.maxTokens,
-                        systemPrompt: options.systemPrompt,
-                        schema: options.schema,
-                        output: options.output,
-                        tools: options.tools, // Includes RAG tools if rag config was provided
-                        disableTools: options.disableTools,
-                        toolFilter: options.toolFilter,
-                        excludeTools: options.excludeTools,
-                        maxSteps: options.maxSteps,
-                        toolChoice: options.toolChoice,
-                        prepareStep: options.prepareStep,
-                        enableAnalytics: options.enableAnalytics,
-                        enableEvaluation: options.enableEvaluation,
-                        context: options.context,
-                        evaluationDomain: options.evaluationDomain,
-                        toolUsageContext: options.toolUsageContext,
-                        input: options.input, // This includes text, images, and content arrays
-                        region: options.region,
-                        tts: options.tts,
-                        fileRegistry: this.fileRegistry,
-                        abortSignal: options.abortSignal,
-                        skipToolPromptInjection: options.skipToolPromptInjection,
-                    };
-                    // Auto-map top-level sessionId/userId to context for convenience
-                    // Tests and users may pass sessionId/userId as top-level options
-                    const extraContext = options;
-                    if (extraContext.sessionId || extraContext.userId) {
-                        baseOptions.context = {
-                            ...baseOptions.context,
-                            ...(extraContext.sessionId && !baseOptions.context?.sessionId
-                                ? { sessionId: extraContext.sessionId }
-                                : {}),
-                            ...(extraContext.userId && !baseOptions.context?.userId
-                                ? { userId: extraContext.userId }
-                                : {}),
+                        // Use redesigned generation logic
+                        const textResult = await this.generateTextInternal(textOptions);
+                        // Emit generation completion event (NeuroLink format - enhanced with content)
+                        this.emitter.emit("generation:end", {
+                            provider: textResult.provider,
+                            responseTime: Date.now() - startTime,
+                            toolsUsed: textResult.toolsUsed,
+                            timestamp: Date.now(),
+                            result: textResult, // Enhanced: include full result
+                            prompt: options.input?.text ||
+                                options.prompt,
+                            temperature: textOptions.temperature,
+                            maxTokens: textOptions.maxTokens,
+                        });
+                        // ADD: Bedrock-compatible response:end event with content
+                        this.emitter.emit("response:end", textResult.content || "");
+                        // ADD: Bedrock-compatible message event
+                        this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
+                        // Convert back to GenerateResult
+                        const generateResult = {
+                            content: textResult.content,
+                            finishReason: textResult.finishReason,
+                            provider: textResult.provider,
+                            model: textResult.model,
+                            usage: textResult.usage
+                                ? {
+                                    input: textResult.usage.input || 0,
+                                    output: textResult.usage.output || 0,
+                                    total: textResult.usage.total || 0,
+                                }
+                                : undefined,
+                            responseTime: textResult.responseTime,
+                            toolsUsed: textResult.toolsUsed,
+                            toolExecutions: transformToolExecutions(textResult.toolExecutions),
+                            enhancedWithTools: textResult.enhancedWithTools,
+                            availableTools: transformAvailableTools(textResult.availableTools),
+                            analytics: textResult.analytics,
+                            // CRITICAL FIX: Include imageOutput for image generation models
+                            imageOutput: textResult.imageOutput,
+                            evaluation: textResult.evaluation
+                                ? {
+                                    ...textResult.evaluation,
+                                    isOffTopic: textResult.evaluation
+                                        .isOffTopic ?? false,
+                                    alertSeverity: textResult.evaluation
+                                        .alertSeverity ?? "none",
+                                    reasoning: textResult.evaluation
+                                        .reasoning ?? "No evaluation provided",
+                                    evaluationModel: textResult.evaluation
+                                        .evaluationModel ?? "unknown",
+                                    evaluationTime: textResult.evaluation
+                                        .evaluationTime ?? Date.now(),
+                                    // Include evaluationDomain from original options
+                                    evaluationDomain: textResult.evaluation
+                                        .evaluationDomain ??
+                                        textOptions.evaluationDomain ??
+                                        factoryResult.domainType,
+                                }
+                                : undefined,
+                            audio: textResult.audio,
+                            video: textResult.video,
+                            ppt: textResult.ppt,
                         };
-                    }
-                    // Apply factory enhancement using centralized utilities
-                    const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
-                    // Pass conversation memory config if available
-                    if (this.conversationMemory) {
-                        textOptions.conversationMemoryConfig =
-                            this.conversationMemory.config;
-                        // Include original prompt for context summarization
-                        textOptions.originalPrompt = originalPrompt;
-                    }
-                    // Detect and execute domain-specific tools
-                    const { toolResults, enhancedPrompt } = await this.detectAndExecuteTools(textOptions.prompt || options.input.text, factoryResult.domainType);
-                    // Update prompt with tool results if available
-                    if (enhancedPrompt !== textOptions.prompt) {
-                        textOptions.prompt = enhancedPrompt;
-                        logger.debug("Enhanced prompt with tool results", {
-                            originalLength: options.input.text.length,
-                            enhancedLength: enhancedPrompt.length,
-                            toolResults: toolResults.length,
+                        // Accumulate session cost for budget tracking
+                        if (generateResult.analytics?.cost &&
+                            generateResult.analytics.cost > 0) {
+                            this._sessionCostUsd += generateResult.analytics.cost;
+                        }
+                        this.scheduleGenerateMem0Storage(options, originalPrompt, generateResult);
+                        // Set completion span attributes
+                        generateSpan.setAttribute("neurolink.output_length", generateResult.content?.length || 0);
+                        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");
+                        generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
+                        generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
+                        generateSpan.setStatus({ code: SpanStatusCode.OK });
+                        return generateResult;
+                    });
+                }
+                catch (error) {
+                    generateSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    // Emit generation:end on error so metrics listeners still record the failure.
+                    // Note: variables declared inside try blocks are not accessible in error
+                    // handlers, so we extract what we can from the original input.
+                    const errProvider = typeof optionsOrPrompt === "object"
+                        ? optionsOrPrompt.provider || "unknown"
+                        : "unknown";
+                    const errModel = typeof optionsOrPrompt === "object"
+                        ? optionsOrPrompt.model || "unknown"
+                        : "unknown";
+                    try {
+                        this.emitter.emit("generation:end", {
+                            provider: errProvider,
+                            model: errModel,
+                            responseTime: 0,
+                            error: error instanceof Error ? error.message : String(error),
+                            success: false,
                         });
                     }
-                    // Use redesigned generation logic
-                    const textResult = await this.generateTextInternal(textOptions);
-                    // Emit generation completion event (NeuroLink format - enhanced with content)
-                    this.emitter.emit("generation:end", {
-                        provider: textResult.provider,
-                        responseTime: Date.now() - startTime,
-                        toolsUsed: textResult.toolsUsed,
-                        timestamp: Date.now(),
-                        result: textResult, // Enhanced: include full result
-                    });
-                    // ADD: Bedrock-compatible response:end event with content
-                    this.emitter.emit("response:end", textResult.content || "");
-                    // ADD: Bedrock-compatible message event
-                    this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
-                    // Convert back to GenerateResult
-                    const generateResult = {
-                        content: textResult.content,
-                        finishReason: textResult.finishReason,
-                        provider: textResult.provider,
-                        model: textResult.model,
-                        usage: textResult.usage
-                            ? {
-                                input: textResult.usage.input || 0,
-                                output: textResult.usage.output || 0,
-                                total: textResult.usage.total || 0,
-                            }
-                            : undefined,
-                        responseTime: textResult.responseTime,
-                        toolsUsed: textResult.toolsUsed,
-                        toolExecutions: transformToolExecutions(textResult.toolExecutions),
-                        enhancedWithTools: textResult.enhancedWithTools,
-                        availableTools: transformAvailableTools(textResult.availableTools),
-                        analytics: textResult.analytics,
-                        // CRITICAL FIX: Include imageOutput for image generation models
-                        imageOutput: textResult.imageOutput,
-                        evaluation: textResult.evaluation
-                            ? {
-                                ...textResult.evaluation,
-                                isOffTopic: textResult.evaluation
-                                    .isOffTopic ?? false,
-                                alertSeverity: textResult.evaluation
-                                    .alertSeverity ??
-                                    "none",
-                                reasoning: textResult.evaluation
-                                    .reasoning ?? "No evaluation provided",
-                                evaluationModel: textResult.evaluation
-                                    .evaluationModel ?? "unknown",
-                                evaluationTime: textResult.evaluation
-                                    .evaluationTime ?? Date.now(),
-                                // Include evaluationDomain from original options
-                                evaluationDomain: textResult.evaluation
-                                    .evaluationDomain ??
-                                    textOptions.evaluationDomain ??
-                                    factoryResult.domainType,
-                            }
-                            : undefined,
-                        audio: textResult.audio,
-                        video: textResult.video,
-                        ppt: textResult.ppt,
-                    };
-                    // Accumulate session cost for budget tracking
-                    if (generateResult.analytics?.cost &&
-                        generateResult.analytics.cost > 0) {
-                        this._sessionCostUsd += generateResult.analytics.cost;
+                    catch (emitError) {
+                        void emitError; // non-blocking — error event emission is best-effort
                     }
-                    this.scheduleGenerateMem0Storage(options, originalPrompt, generateResult);
-                    // Set completion span attributes
-                    generateSpan.setAttribute("neurolink.output_length", generateResult.content?.length || 0);
-                    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");
-                    generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
-                    generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
-                    generateSpan.setStatus({ code: SpanStatusCode.OK });
-                    return generateResult;
-                });
-            }
-            catch (error) {
-                generateSpan.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: error instanceof Error ? error.message : String(error),
-                });
-                throw error;
-            }
-            finally {
-                generateSpan.end();
-            }
+                    throw error;
+                }
+                finally {
+                    generateSpan.end();
+                }
+            }); // end metricsTraceContextStorage.run
         });
     }
     /**
@@ -2409,7 +2703,16 @@ Current user's request: ${currentInput}`;
                                 cacheSavingsPercent: mcpResult.usage.cacheSavingsPercent,
                             }),
                         });
-                        await storeConversationTurn(this.conversationMemory, options, mcpResult, new Date(generateInternalStartTime), requestId);
+                        {
+                            const memStoreStart = Date.now();
+                            try {
+                                await storeConversationTurn(this.conversationMemory, options, mcpResult, new Date(generateInternalStartTime), requestId);
+                                this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "mcp" }, Date.now() - memStoreStart, SpanStatus.OK);
+                            }
+                            catch (memErr) {
+                                this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "mcp" }, Date.now() - memStoreStart, SpanStatus.ERROR, memErr instanceof Error ? memErr.message : String(memErr));
+                            }
+                        }
                         this.emitter.emit("response:end", mcpResult.content || "");
                         internalSpan.setAttribute("neurolink.path", "mcp");
                         internalSpan.setAttribute("neurolink.tokens.input", mcpResult.usage?.input || 0);
@@ -2448,7 +2751,16 @@ Current user's request: ${currentInput}`;
                             cacheSavingsPercent: directResult.usage.cacheSavingsPercent,
                         }),
                     });
-                    await storeConversationTurn(this.conversationMemory, options, directResult, new Date(generateInternalStartTime), requestId);
+                    {
+                        const memStoreStart = Date.now();
+                        try {
+                            await storeConversationTurn(this.conversationMemory, options, directResult, new Date(generateInternalStartTime), requestId);
+                            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "direct" }, Date.now() - memStoreStart, SpanStatus.OK);
+                        }
+                        catch (memErr) {
+                            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "direct" }, Date.now() - memStoreStart, SpanStatus.ERROR, memErr instanceof Error ? memErr.message : String(memErr));
+                        }
+                    }
                     this.emitter.emit("response:end", directResult.content || "");
                     this.emitter.emit("message", `Text generation completed successfully`);
                     internalSpan.setAttribute("neurolink.path", "direct");
@@ -2975,6 +3287,8 @@ Current user's request: ${currentInput}`;
             const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
             this, // Pass SDK instance
             options.region);
+            // Propagate trace context for parent-child span hierarchy
+            provider._traceContext = this._metricsTraceContext;
             // ADD: Emit connection events for all providers (Bedrock-compatible)
             this.emitter.emit("connected");
             this.emitter.emit("message", `${providerName} provider initialized successfully`);
@@ -3039,6 +3353,7 @@ Current user's request: ${currentInput}`;
                 audio: result.audio,
                 video: result.video,
                 ppt: result.ppt,
+                imageOutput: result.imageOutput,
                 // Include analytics and evaluation from BaseProvider
                 analytics: result.analytics,
                 evaluation: result.evaluation,
@@ -3189,6 +3504,8 @@ Current user's request: ${currentInput}`;
                 const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
                 this, // Pass SDK instance
                 options.region);
+                // Propagate trace context for parent-child span hierarchy
+                provider._traceContext = this._metricsTraceContext;
                 // ADD: Emit connection events for successful provider creation (Bedrock-compatible)
                 this.emitter.emit("connected");
                 this.emitter.emit("message", `${providerName} provider initialized successfully`);
@@ -3422,206 +3739,276 @@ Current user's request: ${currentInput}`;
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     async stream(options) {
-        // Manual span lifecycle: the span must stay open until the stream is fully consumed,
-        // NOT when the StreamResult object is returned. withSpan would end the span too early
-        // because streaming results resolve lazily via the async generator.
-        const streamSpan = tracers.sdk.startSpan("neurolink.stream", {
-            kind: SpanKind.INTERNAL,
-            attributes: {
-                [ATTR.NL_PROVIDER]: options.provider || "default",
-                [ATTR.GEN_AI_MODEL]: options.model || "default",
-                [ATTR.NL_INPUT_LENGTH]: options.input?.text?.length || 0,
-                [ATTR.NL_HAS_TOOLS]: !!(options.tools && Object.keys(options.tools).length > 0),
-                [ATTR.NL_STREAM_MODE]: true,
-            },
-        });
-        const spanStartTime = Date.now();
-        try {
-            const startTime = Date.now();
-            const hrTimeStart = process.hrtime.bigint();
-            const streamId = `neurolink-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-            const originalPrompt = options.input.text; // Store the original prompt for memory storage
-            // Inject file registry for lazy on-demand file processing
-            options.fileRegistry = this.fileRegistry;
-            await this.validateStreamInput(options);
-            // Check budget limit before making API call
-            if (options.maxBudgetUsd !== undefined &&
-                options.maxBudgetUsd > 0 &&
-                this._sessionCostUsd >= options.maxBudgetUsd) {
-                throw new NeuroLinkError({
-                    code: "SESSION_BUDGET_EXCEEDED",
-                    message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
-                    category: ErrorCategory.VALIDATION,
-                    severity: ErrorSeverity.HIGH,
-                    retriable: false,
-                    context: {
-                        spent: this._sessionCostUsd,
-                        limit: options.maxBudgetUsd,
-                    },
-                });
-            }
-            this.emitStreamStartEvents(options, startTime);
-            // Check if workflow is requested
-            if (options.workflow || options.workflowConfig) {
-                const result = await this.streamWithWorkflow(options, startTime);
-                streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
-                streamSpan.setStatus({ code: SpanStatusCode.OK });
-                streamSpan.end();
-                return result;
-            }
-            // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
-            return await this.setLangfuseContextFromOptions(options, async () => {
-                try {
-                    // Prepare options: init memory, MCP, Mem0, orchestration, Ollama auto-disable, tool detection
-                    const { enhancedOptions, factoryResult } = await this.prepareStreamOptions(options, streamId, startTime, hrTimeStart);
-                    const { stream: mcpStream, provider: providerName } = await this.createMCPStream(enhancedOptions);
-                    // Update span with resolved provider name
-                    streamSpan.setAttribute(ATTR.NL_PROVIDER, providerName || "unknown");
-                    let accumulatedContent = "";
-                    let chunkCount = 0;
-                    // Set up event capture listeners
-                    const { eventSequence, cleanup: cleanupListeners } = this.setupStreamEventListeners();
-                    const metadata = {
-                        fallbackAttempted: false,
-                        guardrailsBlocked: false,
-                        error: undefined,
-                    };
-                    const self = this;
-                    const streamStartTime = Date.now();
-                    const sessionId = enhancedOptions.context
-                        ?.sessionId;
-                    const processedStream = (async function* () {
-                        let streamError = undefined;
+        // Set metrics trace context for parent-child span linking
+        const metricsTraceId = crypto.randomUUID().replace(/-/g, "");
+        const metricsParentSpanId = crypto
+            .randomUUID()
+            .replace(/-/g, "")
+            .substring(0, 16);
+        // Scope trace context to this request via AsyncLocalStorage
+        // so concurrent generate/stream calls don't race.
+        return metricsTraceContextStorage.run({ traceId: metricsTraceId, parentSpanId: metricsParentSpanId }, async () => {
+            // Manual span lifecycle: the span must stay open until the stream is fully consumed,
+            // NOT when the StreamResult object is returned. withSpan would end the span too early
+            // because streaming results resolve lazily via the async generator.
+            const streamSpan = tracers.sdk.startSpan("neurolink.stream", {
+                kind: SpanKind.INTERNAL,
+                attributes: {
+                    [ATTR.NL_PROVIDER]: options.provider || "default",
+                    [ATTR.GEN_AI_MODEL]: options.model || "default",
+                    [ATTR.NL_INPUT_LENGTH]: options.input?.text?.length || 0,
+                    [ATTR.NL_HAS_TOOLS]: !!(options.tools && Object.keys(options.tools).length > 0),
+                    [ATTR.NL_STREAM_MODE]: true,
+                },
+            });
+            const spanStartTime = Date.now();
+            try {
+                const startTime = Date.now();
+                const hrTimeStart = process.hrtime.bigint();
+                const streamId = `neurolink-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+                const originalPrompt = options.input.text; // Store the original prompt for memory storage
+                // Inject file registry for lazy on-demand file processing
+                options.fileRegistry = this.fileRegistry;
+                await this.validateStreamInput(options);
+                // Check budget limit before making API call
+                if (options.maxBudgetUsd !== undefined &&
+                    options.maxBudgetUsd > 0 &&
+                    this._sessionCostUsd >= options.maxBudgetUsd) {
+                    throw new NeuroLinkError({
+                        code: "SESSION_BUDGET_EXCEEDED",
+                        message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
+                        category: ErrorCategory.VALIDATION,
+                        severity: ErrorSeverity.HIGH,
+                        retriable: false,
+                        context: {
+                            spent: this._sessionCostUsd,
+                            limit: options.maxBudgetUsd,
+                        },
+                    });
+                }
+                this.emitStreamStartEvents(options, startTime);
+                // Check if workflow is requested
+                if (options.workflow || options.workflowConfig) {
+                    const result = await this.streamWithWorkflow(options, startTime);
+                    // Wrap the workflow stream so the span stays open until fully consumed
+                    const originalWorkflowStream = result.stream;
+                    result.stream = (async function* () {
                         try {
-                            for await (const chunk of mcpStream) {
-                                chunkCount++;
-                                if (chunk &&
-                                    "content" in chunk &&
-                                    typeof chunk.content === "string") {
-                                    accumulatedContent += chunk.content;
-                                    self.emitter.emit("response:chunk", chunk.content);
-                                    // Emit stream:chunk event (Observability Solution 8)
-                                    self.emitter.emit("stream:chunk", {
-                                        type: "stream:chunk",
-                                        content: chunk.content,
-                                        metadata: {
-                                            chunkIndex: chunkCount,
-                                            totalLength: accumulatedContent.length,
-                                        },
-                                        timestamp: Date.now(),
-                                    });
-                                }
+                            for await (const chunk of originalWorkflowStream) {
                                 yield chunk;
                             }
-                            if (chunkCount === 0 && !metadata.fallbackAttempted) {
-                                yield* self.handleStreamFallback(metadata, originalPrompt, enhancedOptions, providerName, accumulatedContent, (content) => {
-                                    accumulatedContent += content;
-                                });
-                            }
-                            // Emit stream:complete event (Observability Solution 8)
-                            self.emitter.emit("stream:complete", {
-                                type: "stream:complete",
-                                content: accumulatedContent,
-                                metadata: {
-                                    chunkCount,
-                                    totalLength: accumulatedContent.length,
-                                    durationMs: Date.now() - streamStartTime,
-                                    sessionId,
-                                },
-                                timestamp: Date.now(),
-                            });
+                            streamSpan.setStatus({ code: SpanStatusCode.OK });
                         }
                         catch (error) {
-                            streamError = error;
-                            // Emit stream:error event (Observability Solution 8)
-                            self.emitter.emit("stream:error", {
-                                type: "stream:error",
-                                content: error instanceof Error ? error.message : String(error),
-                                metadata: {
-                                    chunkCount,
-                                    totalLength: accumulatedContent.length,
-                                    durationMs: Date.now() - streamStartTime,
-                                    errorName: error instanceof Error ? error.name : "UnknownError",
-                                    sessionId,
-                                },
-                                timestamp: Date.now(),
+                            streamSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: error instanceof Error ? error.message : String(error),
                             });
                             throw error;
                         }
                         finally {
-                            cleanupListeners();
-                            // Finalize span now that the stream is fully consumed
                             streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
-                            streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
-                            streamSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, metadata.error || streamError ? "error" : "stop");
-                            if (metadata.error || streamError) {
-                                streamSpan.setStatus({
-                                    code: SpanStatusCode.ERROR,
-                                    message: metadata.error ||
-                                        (streamError instanceof Error
-                                            ? streamError.message
-                                            : String(streamError)),
+                            streamSpan.end();
+                        }
+                    })();
+                    return result;
+                }
+                // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
+                return await this.setLangfuseContextFromOptions(options, async () => {
+                    try {
+                        // Prepare options: init memory, MCP, Mem0, orchestration, Ollama auto-disable, tool detection
+                        const { enhancedOptions, factoryResult } = await this.prepareStreamOptions(options, streamId, startTime, hrTimeStart);
+                        const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, analytics: streamAnalytics, } = await this.createMCPStream(enhancedOptions);
+                        // Update span with resolved provider name
+                        streamSpan.setAttribute(ATTR.NL_PROVIDER, providerName || "unknown");
+                        let accumulatedContent = "";
+                        let chunkCount = 0;
+                        // Set up event capture listeners
+                        const { eventSequence, cleanup: cleanupListeners } = this.setupStreamEventListeners();
+                        const metadata = {
+                            fallbackAttempted: false,
+                            guardrailsBlocked: false,
+                            error: undefined,
+                            fallbackProvider: undefined,
+                            fallbackModel: undefined,
+                        };
+                        const self = this;
+                        const streamStartTime = Date.now();
+                        const sessionId = enhancedOptions.context?.sessionId;
+                        const processedStream = (async function* () {
+                            let streamError;
+                            try {
+                                for await (const chunk of mcpStream) {
+                                    chunkCount++;
+                                    if (chunk &&
+                                        "content" in chunk &&
+                                        typeof chunk.content === "string") {
+                                        accumulatedContent += chunk.content;
+                                        self.emitter.emit("response:chunk", chunk.content);
+                                        // Emit stream:chunk event (Observability Solution 8)
+                                        self.emitter.emit("stream:chunk", {
+                                            type: "stream:chunk",
+                                            content: chunk.content,
+                                            metadata: {
+                                                chunkIndex: chunkCount,
+                                                totalLength: accumulatedContent.length,
+                                            },
+                                            timestamp: Date.now(),
+                                        });
+                                    }
+                                    yield chunk;
+                                }
+                                if (chunkCount === 0 && !metadata.fallbackAttempted) {
+                                    yield* self.handleStreamFallback(metadata, originalPrompt, enhancedOptions, providerName, accumulatedContent, (content) => {
+                                        accumulatedContent += content;
+                                    });
+                                }
+                                // Emit stream:complete event (Observability Solution 8)
+                                // When fallback took over, attribute the completion to the
+                                // fallback provider so downstream telemetry reflects reality.
+                                const effectiveProvider = metadata.fallbackProvider ?? providerName;
+                                const effectiveModel = metadata.fallbackModel ??
+                                    streamModel ??
+                                    enhancedOptions.model;
+                                // Resolve analytics promise to get final token usage
+                                let resolvedUsage = streamUsage;
+                                if (!resolvedUsage && streamAnalytics) {
+                                    try {
+                                        const resolved = await Promise.resolve(streamAnalytics);
+                                        if (resolved?.tokenUsage) {
+                                            resolvedUsage = resolved.tokenUsage;
+                                        }
+                                    }
+                                    catch {
+                                        /* non-blocking */
+                                    }
+                                }
+                                self.emitter.emit("stream:complete", {
+                                    type: "stream:complete",
+                                    content: accumulatedContent,
+                                    provider: effectiveProvider,
+                                    model: effectiveModel,
+                                    prompt: enhancedOptions.input?.text ||
+                                        enhancedOptions.prompt,
+                                    metadata: {
+                                        chunkCount,
+                                        totalLength: accumulatedContent.length,
+                                        durationMs: Date.now() - streamStartTime,
+                                        sessionId,
+                                        usage: resolvedUsage,
+                                        ...(metadata.fallbackAttempted && {
+                                            primaryProvider: providerName,
+                                            primaryModel: enhancedOptions.model,
+                                            fallback: true,
+                                        }),
+                                    },
+                                    timestamp: Date.now(),
                                 });
                             }
-                            else {
-                                streamSpan.setStatus({ code: SpanStatusCode.OK });
-                            }
-                            streamSpan.end();
-                            if (accumulatedContent.trim()) {
-                                logger.info(`[NeuroLink.stream] stream() - COMPLETE SUCCESS`, {
+                            catch (error) {
+                                streamError = error;
+                                // Emit stream:error event (Observability Solution 8)
+                                self.emitter.emit("stream:error", {
+                                    type: "stream:error",
+                                    content: error instanceof Error ? error.message : String(error),
                                     provider: providerName,
                                     model: enhancedOptions.model,
-                                    responseTimeMs: Date.now() - startTime,
-                                    contentLength: accumulatedContent.length,
-                                    fallback: metadata.fallbackAttempted,
+                                    metadata: {
+                                        chunkCount,
+                                        totalLength: accumulatedContent.length,
+                                        durationMs: Date.now() - streamStartTime,
+                                        errorName: error instanceof Error ? error.name : "UnknownError",
+                                        sessionId,
+                                    },
+                                    timestamp: Date.now(),
                                 });
+                                throw error;
                             }
-                            await self.storeStreamConversationMemory({
-                                enhancedOptions,
-                                providerName,
-                                originalPrompt,
-                                accumulatedContent,
-                                startTime,
-                                eventSequence,
-                            });
+                            finally {
+                                cleanupListeners();
+                                // Finalize span now that the stream is fully consumed
+                                streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
+                                streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
+                                // When fallback took over, the primary provider's span must
+                                // reflect that it failed — never mark it as successful.
+                                const primaryFailed = !!(metadata.error || streamError);
+                                streamSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, primaryFailed ? "error" : "stop");
+                                if (metadata.fallbackAttempted) {
+                                    streamSpan.setAttribute("neurolink.fallback_triggered", true);
+                                    if (metadata.fallbackProvider) {
+                                        streamSpan.setAttribute("neurolink.fallback_provider", metadata.fallbackProvider);
+                                    }
+                                }
+                                if (primaryFailed) {
+                                    streamSpan.setStatus({
+                                        code: SpanStatusCode.ERROR,
+                                        message: metadata.error ||
+                                            (streamError instanceof Error
+                                                ? streamError.message
+                                                : String(streamError)),
+                                    });
+                                }
+                                else {
+                                    streamSpan.setStatus({ code: SpanStatusCode.OK });
+                                }
+                                streamSpan.end();
+                                if (accumulatedContent.trim()) {
+                                    logger.info(`[NeuroLink.stream] stream() - COMPLETE SUCCESS`, {
+                                        provider: providerName,
+                                        model: enhancedOptions.model,
+                                        responseTimeMs: Date.now() - startTime,
+                                        contentLength: accumulatedContent.length,
+                                        fallback: metadata.fallbackAttempted,
+                                    });
+                                }
+                                await self.storeStreamConversationMemory({
+                                    enhancedOptions,
+                                    providerName,
+                                    originalPrompt,
+                                    accumulatedContent,
+                                    startTime,
+                                    eventSequence,
+                                });
+                            }
+                        })();
+                        const streamResult = await this.processStreamResult(processedStream, enhancedOptions, factoryResult);
+                        const responseTime = Date.now() - startTime;
+                        // Accumulate session cost for budget tracking
+                        if (streamResult.analytics?.cost &&
+                            streamResult.analytics.cost > 0) {
+                            this._sessionCostUsd += streamResult.analytics.cost;
                         }
-                    })();
-                    const streamResult = await this.processStreamResult(processedStream, enhancedOptions, factoryResult);
-                    const responseTime = Date.now() - startTime;
-                    // Accumulate session cost for budget tracking
-                    if (streamResult.analytics?.cost && streamResult.analytics.cost > 0) {
-                        this._sessionCostUsd += streamResult.analytics.cost;
+                        this.emitStreamEndEvents(streamResult);
+                        return this.createStreamResponse(streamResult, processedStream, {
+                            providerName,
+                            options,
+                            startTime,
+                            responseTime,
+                            streamId,
+                            fallback: metadata.fallbackAttempted,
+                            guardrailsBlocked: metadata.guardrailsBlocked,
+                            error: metadata.error,
+                            events: eventSequence,
+                        });
                     }
-                    this.emitStreamEndEvents(streamResult);
-                    return this.createStreamResponse(streamResult, processedStream, {
-                        providerName,
-                        options,
-                        startTime,
-                        responseTime,
-                        streamId,
-                        fallback: metadata.fallbackAttempted,
-                        guardrailsBlocked: metadata.guardrailsBlocked,
-                        error: metadata.error,
-                        events: eventSequence,
-                    });
-                }
-                catch (error) {
-                    return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
+                    catch (error) {
+                        return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
+                    }
+                });
+            }
+            catch (error) {
+                // End span on error before re-throwing
+                streamSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                if (error instanceof Error) {
+                    streamSpan.recordException(error);
                 }
-            });
-        }
-        catch (error) {
-            // End span on error before re-throwing
-            streamSpan.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: error instanceof Error ? error.message : String(error),
-            });
-            if (error instanceof Error) {
-                streamSpan.recordException(error);
+                streamSpan.end();
+                throw error;
             }
-            streamSpan.end();
-            throw error;
-        }
+        }); // end metricsTraceContextStorage.run
     }
     /**
      * Prepare stream options: initialize memory, MCP, Mem0 retrieval, orchestration,
@@ -3828,6 +4215,25 @@ Current user's request: ${currentInput}`;
         metadata.fallbackAttempted = true;
         const errorMsg = "Stream completed with 0 chunks (possible guardrails block)";
         metadata.error = errorMsg;
+        // Record a failed-provider span for the primary provider that returned 0 chunks
+        try {
+            const traceCtx = this._metricsTraceContext;
+            let failedSpan = SpanSerializer.createGenerationSpan({
+                provider: providerName,
+                model: enhancedOptions.model || "unknown",
+                name: `gen_ai.${providerName}.stream.failed`,
+                traceId: traceCtx?.traceId,
+                parentSpanId: traceCtx?.parentSpanId,
+            });
+            failedSpan = SpanSerializer.endSpan(failedSpan, SpanStatus.ERROR);
+            failedSpan.statusMessage = errorMsg;
+            failedSpan.durationMs = 0;
+            this.metricsAggregator.recordSpan(failedSpan);
+            getMetricsAggregator().recordSpan(failedSpan);
+        }
+        catch {
+            /* non-blocking */
+        }
         const fallbackRoute = ModelRouter.getFallbackRoute(originalPrompt || enhancedOptions.input.text || "", {
             provider: providerName,
             model: enhancedOptions.model || "gpt-4o",
@@ -3871,6 +4277,8 @@ Current user's request: ${currentInput}`;
                 throw new Error(`Fallback provider ${fallbackRoute.provider} also returned 0 chunks`);
             }
             // Fallback succeeded - likely guardrails blocked primary
+            metadata.fallbackProvider = fallbackRoute.provider;
+            metadata.fallbackModel = fallbackRoute.model;
             metadata.guardrailsBlocked = true;
         }
         catch (fallbackError) {
@@ -3913,6 +4321,7 @@ Current user's request: ${currentInput}`;
                     model: enhancedOptions.model,
                 };
             }
+            const memStoreStart = Date.now();
             try {
                 await this.conversationMemory.storeConversationTurn({
                     sessionId,
@@ -3926,6 +4335,7 @@ Current user's request: ${currentInput}`;
                     requestId: enhancedOptions.context
                         ?.requestId,
                 });
+                this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                 logger.debug("[NeuroLink.stream] Stored conversation turn with events", {
                     sessionId,
                     eventCount: eventSequence.length,
@@ -3933,6 +4343,7 @@ Current user's request: ${currentInput}`;
                 });
             }
             catch (error) {
+                this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "stream" }, Date.now() - memStoreStart, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
                 logger.warn("Failed to store stream conversation turn", {
                     error: error instanceof Error ? error.message : String(error),
                 });
@@ -4002,6 +4413,8 @@ Current user's request: ${currentInput}`;
         const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
         this, // Pass SDK instance
         options.region);
+        // Propagate trace context for parent-child span hierarchy
+        provider._traceContext = this._metricsTraceContext;
         // Enable tool execution for the provider using BaseProvider method
         provider.setupToolExecutor({
             customTools: this.getCustomTools(),
@@ -4051,7 +4464,13 @@ Current user's request: ${currentInput}`;
             provider: providerName,
             systemPromptPassedLength: enhancedSystemPrompt.length,
         });
-        return { stream: streamResult.stream, provider: providerName };
+        return {
+            stream: streamResult.stream,
+            provider: providerName,
+            usage: streamResult.usage,
+            model: streamResult.model || options.model,
+            analytics: streamResult.analytics,
+        };
     }
     /**
      * Process stream result
@@ -4110,6 +4529,27 @@ 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
+        try {
+            const failedProvider = options.provider || "unknown";
+            const traceCtx = this._metricsTraceContext;
+            let failedSpan = SpanSerializer.createGenerationSpan({
+                provider: failedProvider,
+                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 */
+        }
         const originalPrompt = options.input.text;
         const responseTime = Date.now() - startTime;
         const providerName = await getBestProvider(options.provider);
@@ -4159,6 +4599,7 @@ Current user's request: ${currentInput}`;
                             model: options.model,
                         };
                     }
+                    const memStoreStart = Date.now();
                     try {
                         await self.conversationMemory.storeConversationTurn({
                             sessionId: sessionId || options.context?.sessionId,
@@ -4172,8 +4613,10 @@ Current user's request: ${currentInput}`;
                                 options.context
                                     ?.requestId,
                         });
+                        self.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "fallback-stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                     }
                     catch (error) {
+                        self.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "fallback-stream" }, Date.now() - memStoreStart, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
                         logger.warn("Failed to store fallback stream conversation turn", {
                             error: error instanceof Error ? error.message : String(error),
                         });