@juspay/neurolink 9.41.0 → 9.42.0

package/dist/lib/neurolink.js

@@ -22,7 +22,7 @@ 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 { ContextCompactor } from "./context/contextCompactor.js";
 import { emergencyContentTruncation } from "./context/emergencyTruncation.js";
 import { getContextOverflowProvider, isContextOverflowError, parseProviderOverflowDetails, } from "./context/errorDetection.js";
 import { ContextBudgetExceededError } from "./context/errors.js";
@@ -44,24 +44,27 @@ import { ToolRouter } from "./mcp/routing/index.js";
 import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 import { inferAnnotations, isSafeToRetry } from "./mcp/toolAnnotations.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
-import { initializeHippocampus, } from "./memory/hippocampusInitializer.js";
+import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
-import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.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 { TaskManager } from "./tasks/taskManager.js";
+import { createTaskTools } from "./tasks/tools/taskTools.js";
 import { ATTR } from "./telemetry/attributes.js";
 import { tracers } from "./telemetry/tracers.js";
+import { CircuitBreakerOpenError } from "./types/circuitBreakerErrors.js";
 import { ConversationMemoryError } from "./types/conversation.js";
-import { AuthenticationError, AuthorizationError, InvalidModelError, } from "./types/errors.js";
-import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.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";
-import { CircuitBreakerOpenError } from "./types/circuitBreakerErrors.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
-import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
+import { createCustomToolServerInfo, detectCategory } from "./utils/mcpDefaults.js";
+import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { getBestProvider } from "./utils/providerUtils.js";
@@ -72,11 +75,8 @@ import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Transformation utilities
 import { extractToolNames, optimizeToolForCollection, transformAvailableTools, transformParamsForLogging, transformToolExecutions, transformToolExecutionsForMCP, transformToolsForMCP, transformToolsToDescriptions, transformToolsToExpectedFormat, } from "./utils/transformationUtils.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
-import { resolveModel } from "./utils/modelAliasResolver.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
-import { TaskManager } from "./tasks/taskManager.js";
-import { createTaskTools } from "./tasks/tools/taskTools.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
  * Returns a human-readable error category based on error message content.
@@ -97,9 +97,7 @@ function classifyMcpErrorMessage(text) {
         lower.includes("access denied")) {
         return "permission_denied";
     }
-    if (lower.includes("timeout") ||
-        lower.includes("timed out") ||
-        lower.includes("deadline exceeded")) {
+    if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("deadline exceeded")) {
         return "timeout";
     }
     if (lower.includes("rate limit") ||
@@ -156,11 +154,7 @@ function isNonRetryableProviderError(error) {
     // Check for HTTP status codes on error objects (e.g., from Vercel AI SDK)
     if (error && typeof error === "object") {
         const err = error;
-        const status = typeof err.status === "number"
-            ? err.status
-            : typeof err.statusCode === "number"
-                ? err.statusCode
-                : undefined;
+        const status = typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : undefined;
         if (status && NON_RETRYABLE_HTTP_STATUS_CODES.includes(status)) {
             return true;
         }
@@ -206,8 +200,7 @@ export class NeuroLink {
     lastCompactionMessageCount = new Map();
     /** Extract sessionId from options context for compaction watermark keying */
     getCompactionSessionId(options) {
-        return (options.context
-            ?.sessionId || "__default__");
+        return options.context?.sessionId || "__default__";
     }
     // MCP Enhancement modules - wired into core execution path
     mcpToolResultCache;
@@ -270,28 +263,19 @@ export class NeuroLink {
      * Extract and set Langfuse context from options with proper async scoping
      */
     async setLangfuseContextFromOptions(options, callback) {
-        if (options.context &&
-            typeof options.context === "object" &&
-            options.context !== null) {
+        if (options.context && typeof options.context === "object" && options.context !== null) {
             let callbackExecuted = false;
             try {
                 const ctx = options.context;
                 // Trigger context scoping if any meaningful Langfuse field is present
-                if (ctx.userId ||
-                    ctx.sessionId ||
-                    ctx.conversationId ||
-                    ctx.requestId ||
-                    ctx.traceName ||
-                    ctx.metadata) {
+                if (ctx.userId || ctx.sessionId || ctx.conversationId || ctx.requestId || ctx.traceName || ctx.metadata) {
                     // Build customAttributes from top-level metadata string/number/boolean fields
                     let customAttributes;
                     if (ctx.metadata && typeof ctx.metadata === "object") {
                         const metaObj = ctx.metadata;
                         const attrs = {};
                         for (const [k, v] of Object.entries(metaObj)) {
-                            if (typeof v === "string" ||
-                                typeof v === "number" ||
-                                typeof v === "boolean") {
+                            if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
                                 attrs[k] = v;
                             }
                         }
@@ -303,14 +287,10 @@ export class NeuroLink {
                         setLangfuseContext({
                             userId: typeof ctx.userId === "string" ? ctx.userId : null,
                             sessionId: typeof ctx.sessionId === "string" ? ctx.sessionId : null,
-                            conversationId: typeof ctx.conversationId === "string"
-                                ? ctx.conversationId
-                                : null,
+                            conversationId: typeof ctx.conversationId === "string" ? ctx.conversationId : null,
                             requestId: typeof ctx.requestId === "string" ? ctx.requestId : null,
                             traceName: typeof ctx.traceName === "string" ? ctx.traceName : null,
-                            metadata: ctx.metadata && typeof ctx.metadata === "object"
-                                ? ctx.metadata
-                                : null,
+                            metadata: ctx.metadata && typeof ctx.metadata === "object" ? ctx.metadata : null,
                             ...(customAttributes !== undefined && { customAttributes }),
                         }, async () => {
                             try {
@@ -444,9 +424,7 @@ export class NeuroLink {
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
-        this.toolCacheDuration = cacheDurationEnv
-            ? parseInt(cacheDurationEnv, 10)
-            : 20000;
+        this.toolCacheDuration = cacheDurationEnv ? parseInt(cacheDurationEnv, 10) : 20000;
         const constructorStartTime = Date.now();
         const constructorHrTimeStart = process.hrtime.bigint();
         const constructorId = `neurolink-constructor-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
@@ -801,9 +779,7 @@ export class NeuroLink {
         // memory manager supports getSessionRaw.
         const memConfig = this.conversationMemoryConfig?.conversationMemory;
         const hasRedisConfig = !!memConfig?.redisConfig ||
-            (memConfig &&
-                "redis" in memConfig &&
-                !!memConfig.redis) ||
+            (memConfig && "redis" in memConfig && !!memConfig.redis) ||
             process.env.STORAGE_TYPE === "redis";
         if (!memConfig?.enabled || !hasRedisConfig) {
             logger.debug("[NeuroLink] Skipping memory retrieval tools — requires Redis conversation memory");
@@ -834,13 +810,8 @@ export class NeuroLink {
                         messages: [],
                     });
                     // Check if the tool itself reported an error
-                    const hasError = result &&
-                        typeof result === "object" &&
-                        "error" in result &&
-                        !("messages" in result);
-                    const errorMsg = hasError
-                        ? result.error
-                        : undefined;
+                    const hasError = result && typeof result === "object" && "error" in result && !("messages" in result);
+                    const errorMsg = hasError ? result.error : undefined;
                     return {
                         success: !hasError,
                         data: result,
@@ -917,8 +888,7 @@ Current user's request: ${currentInput}`;
      * Respects both the global memory SDK config and per-call overrides.
      */
     shouldReadMemory(perCallMemory, userId) {
-        if (!this.conversationMemoryConfig?.conversationMemory?.memory?.enabled ||
-            !userId) {
+        if (!this.conversationMemoryConfig?.conversationMemory?.memory?.enabled || !userId) {
             return false;
         }
         if (perCallMemory?.enabled === false) {
@@ -934,8 +904,7 @@ Current user's request: ${currentInput}`;
      * Respects both the global memory SDK config and per-call overrides.
      */
     shouldWriteMemory(perCallMemory, userId, content) {
-        if (!this.conversationMemoryConfig?.conversationMemory?.memory?.enabled ||
-            !userId) {
+        if (!this.conversationMemoryConfig?.conversationMemory?.memory?.enabled || !userId) {
             return false;
         }
         if (!content?.trim()) {
@@ -1009,9 +978,7 @@ Current user's request: ${currentInput}`;
                 const writeOps = [client.add(userId, content)];
                 const writableAdditional = (additionalUsers || []).filter((u) => u.write !== false);
                 for (const user of writableAdditional) {
-                    const addOptions = user.prompt || user.maxWords
-                        ? { prompt: user.prompt, maxWords: user.maxWords }
-                        : undefined;
+                    const addOptions = user.prompt || user.maxWords ? { prompt: user.prompt, maxWords: user.maxWords } : undefined;
                     writeOps.push(client.add(user.userId, content, addOptions));
                 }
                 await Promise.all(writeOps);
@@ -1170,8 +1137,7 @@ Current user's request: ${currentInput}`;
         try {
             const langfuseConfig = this.observabilityConfig?.langfuse;
             // Check if we should use external provider mode - bypass enabled check
-            const useExternalProvider = langfuseConfig?.autoDetectExternalProvider === true ||
-                langfuseConfig?.useExternalTracerProvider === true;
+            const useExternalProvider = langfuseConfig?.autoDetectExternalProvider === true || langfuseConfig?.useExternalTracerProvider === true;
             if (langfuseConfig?.enabled || useExternalProvider) {
                 logger.debug(`[NeuroLink] 📊 LOG_POINT_C019_LANGFUSE_INIT_START`, {
                     logPoint: "C019_LANGFUSE_INIT_START",
@@ -1186,9 +1152,7 @@ Current user's request: ${currentInput}`;
                 initializeOpenTelemetry(langfuseConfig);
                 const healthStatus = getLangfuseHealthStatus();
                 const langfuseInitDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
-                if (healthStatus.initialized &&
-                    healthStatus.hasProcessor &&
-                    healthStatus.isHealthy) {
+                if (healthStatus.initialized && healthStatus.hasProcessor && healthStatus.isHealthy) {
                     logger.debug(`[NeuroLink] ✅ LOG_POINT_C020_LANGFUSE_INIT_SUCCESS`, {
                         logPoint: "C020_LANGFUSE_INIT_SUCCESS",
                         constructorId,
@@ -1464,9 +1428,7 @@ Current user's request: ${currentInput}`;
         }
         catch (configError) {
             mcpLogger.warn("[NeuroLink] MCP configuration loading failed", {
-                error: configError instanceof Error
-                    ? configError.message
-                    : String(configError),
+                error: configError instanceof Error ? configError.message : String(configError),
             });
         }
     }
@@ -1591,9 +1553,7 @@ Current user's request: ${currentInput}`;
                         taskType: classification.type,
                         routedProvider: route.provider,
                         routedModel: route.model,
-                        reason: error instanceof Error
-                            ? error.message
-                            : "Ollama service check failed",
+                        reason: error instanceof Error ? error.message : "Ollama service check failed",
                         orchestrationTime: `${Date.now() - startTime}ms`,
                     });
                     return {}; // Return empty object to preserve existing fallback behavior
@@ -1729,9 +1689,7 @@ Current user's request: ${currentInput}`;
                         taskType: classification.type,
                         routedProvider: route.provider,
                         routedModel: route.model,
-                        reason: error instanceof Error
-                            ? error.message
-                            : "Ollama service check failed",
+                        reason: error instanceof Error ? error.message : "Ollama service check failed",
                         orchestrationTime: `${Date.now() - startTime}ms`,
                     });
                     return {}; // Return empty object to preserve existing fallback behavior
@@ -1782,9 +1740,7 @@ Current user's request: ${currentInput}`;
         const anyOptions = optionsOrPrompt;
         if (anyOptions.messages && anyOptions.messages.length > 0) {
             const lastMessage = anyOptions.messages[anyOptions.messages.length - 1];
-            return typeof lastMessage.content === "string"
-                ? lastMessage.content
-                : JSON.stringify(lastMessage.content);
+            return typeof lastMessage.content === "string" ? lastMessage.content : JSON.stringify(lastMessage.content);
         }
         // Handle input.text format
         return optionsOrPrompt.input?.text || "";
@@ -1876,8 +1832,7 @@ Current user's request: ${currentInput}`;
                     endpoint: otelConfig.endpoint,
                     serviceName: otelConfig.serviceName,
                 }
-                : isOpenTelemetryInitialized() ||
-                    process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+                : isOpenTelemetryInitialized() || process.env.OTEL_EXPORTER_OTLP_ENDPOINT
                     ? {
                         enabled: isOpenTelemetryInitialized(),
                         endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
@@ -2019,9 +1974,7 @@ Current user's request: ${currentInput}`;
                 const result = data.result;
                 const usage = result?.usage;
                 const analytics = result?.analytics;
-                const provider = data.provider ||
-                    result?.provider ||
-                    "unknown";
+                const provider = data.provider || result?.provider || "unknown";
                 const model = result?.model || "unknown";
                 const responseTime = data.responseTime || 0;
                 const traceCtx = this._metricsTraceContext;
@@ -2040,9 +1993,7 @@ Current user's request: ${currentInput}`;
                     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;
+                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) {
@@ -2078,9 +2029,7 @@ Current user's request: ${currentInput}`;
                 const content = result?.content || result?.text;
                 if (content) {
                     span = SpanSerializer.updateAttributes(span, {
-                        output: content.length > 5000
-                            ? content.substring(0, 5000) + "...[truncated]"
-                            : content,
+                        output: content.length > 5000 ? content.substring(0, 5000) + "...[truncated]" : content,
                     });
                 }
                 this.metricsAggregator.recordSpan(span);
@@ -2119,18 +2068,14 @@ Current user's request: ${currentInput}`;
                 if (data.prompt) {
                     const promptStr = String(data.prompt);
                     span = SpanSerializer.updateAttributes(span, {
-                        input: promptStr.length > 5000
-                            ? promptStr.substring(0, 5000) + "...[truncated]"
-                            : promptStr,
+                        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,
+                        output: streamContent.length > 5000 ? streamContent.substring(0, 5000) + "...[truncated]" : streamContent,
                     });
                 }
                 // Enrich stream span with token usage if available
@@ -2147,8 +2092,7 @@ Current user's request: ${currentInput}`;
                         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 outputCost = ((usage.output || 0) / 1_000_000) * pricing.outputPricePerMillion;
                             const totalCost = inputCost + outputCost;
                             if (totalCost > 0) {
                                 span = SpanSerializer.enrichWithCost(span, {
@@ -2183,8 +2127,7 @@ Current user's request: ${currentInput}`;
                 span = SpanSerializer.endSpan(span, success ? SpanStatus.OK : SpanStatus.ERROR);
                 span.durationMs = responseTime;
                 if (!success && data.error) {
-                    span.statusMessage =
-                        data.error.message || String(data.error);
+                    span.statusMessage = data.error.message || String(data.error);
                 }
                 if (data.result) {
                     try {
@@ -2341,10 +2284,7 @@ Current user's request: ${currentInput}`;
             // 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);
+            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 () => {
@@ -2352,24 +2292,18 @@ Current user's request: ${currentInput}`;
                     const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
                     // Convert string prompt to full options
                     // Shallow-copy caller's object to avoid mutating their original reference
-                    const options = typeof optionsOrPrompt === "string"
-                        ? { input: { text: optionsOrPrompt } }
-                        : { ...optionsOrPrompt };
+                    const options = typeof optionsOrPrompt === "string" ? { input: { text: optionsOrPrompt } } : { ...optionsOrPrompt };
                     // NL-004: Resolve model aliases/deprecations before processing
                     options.model = resolveModel(options.model, this.modelAliasConfig);
                     // MCP Enhancement: propagate disableToolCache to tool execution
-                    this._disableToolCacheForCurrentRequest =
-                        !!options.disableToolCache;
+                    this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
                     // 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.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") {
+                    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
@@ -2399,10 +2333,9 @@ Current user's request: ${currentInput}`;
                                     ...options.middleware?.middlewareConfig?.lifecycle,
                                     enabled: true,
                                     config: {
-                                        ...options.middleware?.middlewareConfig?.lifecycle
-                                            ?.config,
-                                        onFinish: options.onFinish,
-                                        onError: options.onError,
+                                        ...options.middleware?.middlewareConfig?.lifecycle?.config,
+                                        ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
+                                        ...(options.onError !== undefined ? { onError: options.onError } : {}),
                                     },
                                 },
                             },
@@ -2421,9 +2354,7 @@ Current user's request: ${currentInput}`;
                         }
                         catch (err) {
                             // Rethrow auth errors as-is; wrap anything else
-                            if (err instanceof Error &&
-                                "feature" in err &&
-                                err.feature === "Auth") {
+                            if (err instanceof Error && "feature" in err && err.feature === "Auth") {
                                 throw err;
                             }
                             throw AuthError.create("PROVIDER_ERROR", `Auth token validation failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -2483,9 +2414,7 @@ Current user's request: ${currentInput}`;
                     return await this.setLangfuseContextFromOptions(options, async () => {
                         const startTime = Date.now();
                         // Apply orchestration if enabled and no specific provider/model requested
-                        if (this.enableOrchestration &&
-                            !options.provider &&
-                            !options.model) {
+                        if (this.enableOrchestration && !options.provider && !options.model) {
                             try {
                                 const orchestratedOptions = await this.applyOrchestration(options);
                                 logger.debug("Orchestration applied", {
@@ -2503,9 +2432,7 @@ Current user's request: ${currentInput}`;
                             }
                             catch (error) {
                                 logger.warn("Orchestration failed, continuing with original options", {
-                                    error: error instanceof Error
-                                        ? error.message
-                                        : String(error),
+                                    error: error instanceof Error ? error.message : String(error),
                                     originalProvider: options.provider || "auto",
                                 });
                                 // Continue with original options if orchestration fails
@@ -2550,8 +2477,7 @@ Current user's request: ${currentInput}`;
                                     `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;
+                                options.systemPrompt = (options.systemPrompt || "") + ragSystemInstruction;
                                 logger.info("[RAG] Tool injected into generate()", {
                                     toolName: ragResult.toolName,
                                     filesLoaded: ragResult.filesLoaded,
@@ -2560,15 +2486,12 @@ Current user's request: ${currentInput}`;
                             }
                             catch (error) {
                                 logger.warn("[RAG] Failed to prepare RAG tool, continuing without RAG", {
-                                    error: error instanceof Error
-                                        ? error.message
-                                        : String(error),
+                                    error: error instanceof Error ? error.message : String(error),
                                 });
                             }
                         }
                         // Memory retrieval for generate path
-                        if (this.shouldReadMemory(options.memory, options.context?.userId) &&
-                            options.context?.userId) {
+                        if (this.shouldReadMemory(options.memory, options.context?.userId) && options.context?.userId) {
                             try {
                                 options.input.text = await this.retrieveMemory(options.input.text, options.context.userId, options.memory?.additionalUsers);
                                 logger.debug("Memory retrieval successful (generate)");
@@ -2615,8 +2538,7 @@ Current user's request: ${currentInput}`;
                         if (extraContext.sessionId || extraContext.userId) {
                             baseOptions.context = {
                                 ...baseOptions.context,
-                                ...(extraContext.sessionId &&
-                                    !baseOptions.context?.sessionId
+                                ...(extraContext.sessionId && !baseOptions.context?.sessionId
                                     ? { sessionId: extraContext.sessionId }
                                     : {}),
                                 ...(extraContext.userId && !baseOptions.context?.userId
@@ -2628,8 +2550,7 @@ Current user's request: ${currentInput}`;
                         const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
                         // Pass conversation memory config if available
                         if (this.conversationMemory) {
-                            textOptions.conversationMemoryConfig =
-                                this.conversationMemory.config;
+                            textOptions.conversationMemoryConfig = this.conversationMemory.config;
                             // Include original prompt for context summarization
                             textOptions.originalPrompt = originalPrompt;
                         }
@@ -2652,8 +2573,7 @@ Current user's request: ${currentInput}`;
                             toolsUsed: textResult.toolsUsed,
                             timestamp: Date.now(),
                             result: textResult, // Enhanced: include full result
-                            prompt: options.input?.text ||
-                                options.prompt,
+                            prompt: options.input?.text || options.prompt,
                             temperature: textOptions.temperature,
                             maxTokens: textOptions.maxTokens,
                         });
@@ -2686,10 +2606,8 @@ Current user's request: ${currentInput}`;
                                 ? {
                                     ...textResult.evaluation,
                                     isOffTopic: textResult.evaluation.isOffTopic ?? false,
-                                    alertSeverity: textResult.evaluation.alertSeverity ??
-                                        "none",
-                                    reasoning: textResult.evaluation.reasoning ??
-                                        "No evaluation provided",
+                                    alertSeverity: textResult.evaluation.alertSeverity ?? "none",
+                                    reasoning: textResult.evaluation.reasoning ?? "No evaluation provided",
                                     evaluationModel: textResult.evaluation.evaluationModel ?? "unknown",
                                     evaluationTime: textResult.evaluation.evaluationTime ?? Date.now(),
                                     evaluationDomain: textResult.evaluation.evaluationDomain ??
@@ -2704,8 +2622,7 @@ Current user's request: ${currentInput}`;
                             ...(textResult.retries && { retries: textResult.retries }),
                         };
                         // Accumulate session cost for budget tracking
-                        if (generateResult.analytics?.cost &&
-                            generateResult.analytics.cost > 0) {
+                        if (generateResult.analytics?.cost && generateResult.analytics.cost > 0) {
                             this._sessionCostUsd += generateResult.analytics.cost;
                         }
                         this.scheduleGenerateMemoryStorage(options, originalPrompt, generateResult);
@@ -2733,9 +2650,7 @@ Current user's request: ${currentInput}`;
                     const errProvider = typeof optionsOrPrompt === "object"
                         ? optionsOrPrompt.provider || "unknown"
                         : "unknown";
-                    const errModel = typeof optionsOrPrompt === "object"
-                        ? optionsOrPrompt.model || "unknown"
-                        : "unknown";
+                    const errModel = typeof optionsOrPrompt === "object" ? optionsOrPrompt.model || "unknown" : "unknown";
                     try {
                         this.emitter.emit("generation:end", {
                             provider: errProvider,
@@ -2836,11 +2751,8 @@ Current user's request: ${currentInput}`;
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
                 role: m.role,
-                content: typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
-            })) ??
-                options.conversationHistory,
+                content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+            })) ?? options.conversationHistory,
             timeout: options.timeout,
             verbose: false,
             metadata: options.context,
@@ -2850,10 +2762,8 @@ Current user's request: ${currentInput}`;
             // Primary output (backward compatible) - use the original best response
             content: workflowResult.content,
             // Provider info from selected response
-            provider: workflowResult.selectedResponse?.provider ||
-                workflowConfig.models[0]?.provider,
-            model: workflowResult.selectedResponse?.model ||
-                workflowConfig.models[0]?.model,
+            provider: workflowResult.selectedResponse?.provider || workflowConfig.models[0]?.provider,
+            model: workflowResult.selectedResponse?.model || workflowConfig.models[0]?.model,
             // Basic usage info
             usage: workflowResult.usage
                 ? {
@@ -2935,11 +2845,8 @@ Current user's request: ${currentInput}`;
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
                 role: m.role,
-                content: typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
-            })) ??
-                options.conversationHistory,
+                content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+            })) ?? options.conversationHistory,
             timeout: options.timeout,
             verbose: false,
             metadata: options.context,
@@ -3063,9 +2970,7 @@ Current user's request: ${currentInput}`;
      */
     async generateText(options) {
         // Validate required parameters for backward compatibility
-        if (!options.prompt ||
-            typeof options.prompt !== "string" ||
-            options.prompt.trim() === "") {
+        if (!options.prompt || typeof options.prompt !== "string" || options.prompt.trim() === "") {
             throw new Error("GenerateText options must include prompt as a non-empty string");
         }
         // NL-004: Resolve model aliases/deprecations before processing
@@ -3148,9 +3053,7 @@ Current user's request: ${currentInput}`;
                     // the catch block needs the originals for a more effective retry
                     if (this.conversationMemory) {
                         const originalMessages = await getConversationMessages(this.conversationMemory, options);
-                        options._originalConversationMessages = originalMessages
-                            ? [...originalMessages]
-                            : undefined;
+                        options._originalConversationMessages = originalMessages ? [...originalMessages] : undefined;
                     }
                     const directResult = await this.directProviderGeneration(options);
                     logger.debug(`[${functionTag}] Direct generation successful`);
@@ -3200,8 +3103,7 @@ Current user's request: ${currentInput}`;
                             // IMPROVEMENT 1: Extract actual token count from provider error if available
                             const actualOverflow = parseProviderOverflowDetails(error);
                             // IMPROVEMENT 2: Use ORIGINAL messages (not already-compacted ones)
-                            const originalMessages = options._originalConversationMessages ??
-                                (await getConversationMessages(this.conversationMemory, options));
+                            const originalMessages = options._originalConversationMessages ?? (await getConversationMessages(this.conversationMemory, options));
                             // IMPROVEMENT 3: Calculate precise reduction target
                             const recoveryBudget = checkContextBudget({
                                 provider: options.provider || "openai",
@@ -3211,16 +3113,12 @@ Current user's request: ${currentInput}`;
                                 systemPrompt: options.systemPrompt,
                             });
                             // Use provider's reported token count if available (more accurate than our estimate)
-                            const actualTokens = actualOverflow?.actualTokens ??
-                                recoveryBudget.estimatedInputTokens;
-                            const budgetTokens = actualOverflow?.budgetTokens ??
-                                recoveryBudget.availableInputTokens;
+                            const actualTokens = actualOverflow?.actualTokens ?? recoveryBudget.estimatedInputTokens;
+                            const budgetTokens = actualOverflow?.budgetTokens ?? recoveryBudget.availableInputTokens;
                             // Target = 70% of budget (aggressive safety margin for recovery)
                             const compactionTarget = Math.floor(budgetTokens * 0.7);
                             // IMPROVEMENT 4: Calculate adaptive truncation fraction from actual numbers
-                            const requiredReduction = actualTokens > 0
-                                ? (actualTokens - compactionTarget) / actualTokens
-                                : 0.5;
+                            const requiredReduction = actualTokens > 0 ? (actualTokens - compactionTarget) / actualTokens : 0.5;
                             const compactor = new ContextCompactor({
                                 enableSummarize: false, // Skip LLM call for recovery (speed)
                                 enablePrune: true,
@@ -3273,9 +3171,7 @@ Current user's request: ${currentInput}`;
                                 throw retryError;
                             }
                             logger.error(`[${functionTag}] Recovery attempt failed`, {
-                                error: retryError instanceof Error
-                                    ? retryError.message
-                                    : String(retryError),
+                                error: retryError instanceof Error ? retryError.message : String(retryError),
                             });
                         }
                     }
@@ -3288,8 +3184,7 @@ Current user's request: ${currentInput}`;
                         logger.info(`[${functionTag}] Generation aborted — storing conversation turn for title generation`, {
                             hasMemory: !!this.conversationMemory,
                             memoryType: this.conversationMemory?.constructor?.name || "NONE",
-                            sessionId: options.context?.sessionId ||
-                                "unknown",
+                            sessionId: options.context?.sessionId || "unknown",
                         });
                         try {
                             const abortedResult = {
@@ -3302,9 +3197,7 @@ Current user's request: ${currentInput}`;
                         }
                         catch (storeError) {
                             logger.warn(`[${functionTag}] Failed to store conversation turn after abort`, {
-                                error: storeError instanceof Error
-                                    ? storeError.message
-                                    : String(storeError),
+                                error: storeError instanceof Error ? storeError.message : String(storeError),
                             });
                         }
                     }
@@ -3321,9 +3214,7 @@ Current user's request: ${currentInput}`;
             catch (spanError) {
                 internalSpan.setStatus({
                     code: SpanStatusCode.ERROR,
-                    message: spanError instanceof Error
-                        ? spanError.message
-                        : String(spanError),
+                    message: spanError instanceof Error ? spanError.message : String(spanError),
                 });
                 throw spanError;
             }
@@ -3403,8 +3294,7 @@ Current user's request: ${currentInput}`;
      * Attempt MCP generation with retry logic
      */
     async attemptMCPGeneration(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag) {
-        if (!options.disableTools &&
-            !(options.tts?.enabled && !options.tts?.useAiResponse)) {
+        if (!options.disableTools && !(options.tts?.enabled && !options.tts?.useAiResponse)) {
             return await this.performMCPGenerationRetries(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag);
         }
         return null;
@@ -3426,9 +3316,7 @@ Current user's request: ${currentInput}`;
             try {
                 logger.debug(`[${functionTag}] Attempting MCP generation (attempt ${attempt}/${maxAttempts})...`);
                 const mcpResult = await this.tryMCPGeneration(options);
-                if (mcpResult &&
-                    (mcpResult.content ||
-                        (mcpResult.toolExecutions && mcpResult.toolExecutions.length > 0))) {
+                if (mcpResult && (mcpResult.content || (mcpResult.toolExecutions && mcpResult.toolExecutions.length > 0))) {
                     logger.debug(`[${functionTag}] MCP generation successful on attempt ${attempt}`, {
                         contentLength: mcpResult.content?.length || 0,
                         toolsUsed: mcpResult.toolsUsed?.length || 0,
@@ -3459,11 +3347,7 @@ Current user's request: ${currentInput}`;
                 // NL-007: Record retry error for observability
                 retryCount++;
                 const errMsg = error instanceof Error ? error.message : String(error);
-                const errCode = error instanceof NeuroLinkError
-                    ? error.code
-                    : error instanceof Error
-                        ? error.name
-                        : "UNKNOWN";
+                const errCode = error instanceof NeuroLinkError ? error.code : error instanceof Error ? error.name : "UNKNOWN";
                 retryErrors.push({ code: errCode, message: errMsg.substring(0, 500) });
                 logger.debug(`[${functionTag}] MCP generation failed on attempt ${attempt}/${maxAttempts}`, {
                     error: errMsg,
@@ -3482,11 +3366,8 @@ Current user's request: ${currentInput}`;
                 const isNonRetryable = isContextOverflowError(error) ||
                     isToolError ||
                     isNonRetryableProviderError(error) ||
-                    (error instanceof Error &&
-                        error.isRetryable ===
-                            false) ||
-                    (error instanceof Error &&
-                        error.statusCode === 400);
+                    (error instanceof Error && error.isRetryable === false) ||
+                    (error instanceof Error && error.statusCode === 400);
                 if (isNonRetryable) {
                     logger.debug(`[${functionTag}] Non-retryable error detected, skipping remaining retries`);
                     break;
@@ -3522,8 +3403,7 @@ Current user's request: ${currentInput}`;
             throw new DOMException("The operation was aborted", "AbortError");
         }
         // 🚀 EXHAUSTIVE LOGGING POINT T001: TRY MCP GENERATION ENTRY
-        const requestId = options.context?.requestId ||
-            "unknown";
+        const requestId = options.context?.requestId || "unknown";
         const tryMCPId = `try-mcp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
         const tryMCPStartTime = Date.now();
         const tryMCPHrTimeStart = process.hrtime.bigint();
@@ -3551,9 +3431,7 @@ Current user's request: ${currentInput}`;
             }
             // Context creation removed - was never used
             // Determine provider
-            const providerName = options.provider === "auto" || !options.provider
-                ? await getBestProvider()
-                : options.provider;
+            const providerName = options.provider === "auto" || !options.provider ? await getBestProvider() : options.provider;
             // Get available tools
             let availableTools = await this.getAllAvailableTools();
             // NL-001: Filter out tools with OPEN circuit breakers
@@ -3563,8 +3441,7 @@ Current user's request: ${currentInput}`;
             availableTools = availableTools.filter((t) => cbFilteredNames.has(t.name));
             // Apply per-call tool filtering for system prompt tool descriptions
             availableTools = this.applyToolInfoFiltering(availableTools, options);
-            const targetTool = availableTools.find((t) => t.name.includes("SuccessRateSRByTime") ||
-                t.name.includes("juspay-analytics"));
+            const targetTool = availableTools.find((t) => t.name.includes("SuccessRateSRByTime") || t.name.includes("juspay-analytics"));
             logger.debug("Available tools for AI prompt generation", {
                 toolsCount: availableTools.length,
                 toolNames: availableTools.map((t) => t.name),
@@ -3598,9 +3475,7 @@ Current user's request: ${currentInput}`;
             logger.debug("[Observability] System prompt metadata", {
                 requestId,
                 systemPromptLength: enhancedSystemPrompt.length,
-                systemPromptHash: enhancedSystemPrompt.length > 0
-                    ? `sha256:${enhancedSystemPrompt.slice(0, 8)}...`
-                    : "empty",
+                systemPromptHash: enhancedSystemPrompt.length > 0 ? `sha256:${enhancedSystemPrompt.slice(0, 8)}...` : "empty",
                 hasCustomSystemPrompt: !!options.systemPrompt,
             });
             // Get conversation messages for context
@@ -3627,9 +3502,7 @@ Current user's request: ${currentInput}`;
                                 index: i,
                                 role: msg.role,
                                 contentLength,
-                                contentPreview: typeof msg.content === "string"
-                                    ? msg.content.substring(0, 200)
-                                    : "[multimodal]",
+                                contentPreview: typeof msg.content === "string" ? msg.content.substring(0, 200) : "[multimodal]",
                             };
                         }),
                     });
@@ -3670,8 +3543,7 @@ Current user's request: ${currentInput}`;
             const compactionSessionId = this.getCompactionSessionId(options);
             if (budgetResult.shouldCompact &&
                 this.conversationMemory &&
-                messageCount >
-                    (this.lastCompactionMessageCount.get(compactionSessionId) ?? 0)) {
+                messageCount > (this.lastCompactionMessageCount.get(compactionSessionId) ?? 0)) {
                 logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
                     usageRatio: budgetResult.usageRatio,
                     estimatedTokens: budgetResult.estimatedInputTokens,
@@ -3679,10 +3551,8 @@ Current user's request: ${currentInput}`;
                 });
                 const compactor = new ContextCompactor({
                     provider: providerName,
-                    summarizationProvider: this.conversationMemoryConfig?.conversationMemory
-                        ?.summarizationProvider,
-                    summarizationModel: this.conversationMemoryConfig?.conversationMemory
-                        ?.summarizationModel,
+                    summarizationProvider: this.conversationMemoryConfig?.conversationMemory?.summarizationProvider,
+                    summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
                 });
                 const compactionResult = await compactor.compact(conversationMessages, budgetResult.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, requestId);
                 if (compactionResult.compacted) {
@@ -3862,18 +3732,12 @@ Current user's request: ${currentInput}`;
         ];
         const requestedProvider = options.provider === "auto" ? undefined : options.provider;
         // Check for orchestrated preferred provider in context
-        const preferredOrchestrated = options.context &&
-            typeof options.context === "object" &&
-            "__orchestratedPreferredProvider" in options.context
-            ? options.context
-                .__orchestratedPreferredProvider
+        const preferredOrchestrated = options.context && typeof options.context === "object" && "__orchestratedPreferredProvider" in options.context
+            ? options.context.__orchestratedPreferredProvider
             : undefined;
         // Build provider list with orchestrated preference first, then fallback to full list
         const tryProviders = preferredOrchestrated
-            ? [
-                preferredOrchestrated,
-                ...providerPriority.filter((p) => p !== preferredOrchestrated),
-            ]
+            ? [preferredOrchestrated, ...providerPriority.filter((p) => p !== preferredOrchestrated)]
             : requestedProvider
                 ? [requestedProvider]
                 : providerPriority;
@@ -3893,8 +3757,7 @@ Current user's request: ${currentInput}`;
                 logger.debug(`[${functionTag}] Attempting provider: ${providerName}`);
                 // Get conversation messages for context (use pre-compacted if provided)
                 const optionsWithMessages = options;
-                let conversationMessages = optionsWithMessages.conversationMessages
-                    ?.length
+                let conversationMessages = optionsWithMessages.conversationMessages?.length
                     ? optionsWithMessages.conversationMessages
                     : await getConversationMessages(this.conversationMemory, options);
                 // Pre-generation budget check
@@ -3905,22 +3768,17 @@ Current user's request: ${currentInput}`;
                     systemPrompt: options.systemPrompt,
                     conversationMessages: conversationMessages,
                     currentPrompt: options.prompt,
-                    toolDefinitions: options.tools
-                        ? Object.values(options.tools)
-                        : undefined,
+                    toolDefinitions: options.tools ? Object.values(options.tools) : undefined,
                 });
                 const dpgMessageCount = conversationMessages?.length || 0;
                 const dpgCompactionSessionId = this.getCompactionSessionId(options);
                 if (budgetCheck.shouldCompact &&
                     this.conversationMemory &&
-                    dpgMessageCount >
-                        (this.lastCompactionMessageCount.get(dpgCompactionSessionId) ?? 0)) {
+                    dpgMessageCount > (this.lastCompactionMessageCount.get(dpgCompactionSessionId) ?? 0)) {
                     const compactor = new ContextCompactor({
                         provider: providerName,
-                        summarizationProvider: this.conversationMemoryConfig?.conversationMemory
-                            ?.summarizationProvider,
-                        summarizationModel: this.conversationMemoryConfig?.conversationMemory
-                            ?.summarizationModel,
+                        summarizationProvider: this.conversationMemoryConfig?.conversationMemory?.summarizationProvider,
+                        summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
                     });
                     const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
                     if (compactionResult.compacted) {
@@ -3936,9 +3794,7 @@ Current user's request: ${currentInput}`;
                         systemPrompt: options.systemPrompt,
                         conversationMessages: conversationMessages,
                         currentPrompt: options.prompt,
-                        toolDefinitions: options.tools
-                            ? Object.values(options.tools)
-                            : undefined,
+                        toolDefinitions: options.tools ? Object.values(options.tools) : undefined,
                     });
                     if (!postCompactBudget.withinBudget) {
                         logger.warn("[NeuroLink] directProviderGeneration: post-compaction still over budget, emergency truncation", {
@@ -3954,9 +3810,7 @@ Current user's request: ${currentInput}`;
                             systemPrompt: options.systemPrompt,
                             conversationMessages: conversationMessages,
                             currentPrompt: options.prompt,
-                            toolDefinitions: options.tools
-                                ? Object.values(options.tools)
-                                : undefined,
+                            toolDefinitions: options.tools ? Object.values(options.tools) : undefined,
                         });
                         if (!finalBudget.withinBudget) {
                             throw new ContextBudgetExceededError(`Context exceeds model budget after all compaction stages. ` +
@@ -4214,10 +4068,7 @@ Current user's request: ${currentInput}`;
         options = { ...options };
         // Set metrics trace context for parent-child span linking
         const metricsTraceId = crypto.randomUUID().replace(/-/g, "");
-        const metricsParentSpanId = crypto
-            .randomUUID()
-            .replace(/-/g, "")
-            .substring(0, 16);
+        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 () => {
@@ -4276,9 +4127,7 @@ Current user's request: ${currentInput}`;
                     }
                     catch (err) {
                         // Rethrow auth errors as-is; wrap anything else
-                        if (err instanceof Error &&
-                            "feature" in err &&
-                            err.feature === "Auth") {
+                        if (err instanceof Error && "feature" in err && err.feature === "Auth") {
                             throw err;
                         }
                         throw AuthError.create("PROVIDER_ERROR", `Auth token validation failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -4331,9 +4180,9 @@ Current user's request: ${currentInput}`;
                                 enabled: true,
                                 config: {
                                     ...options.middleware?.middlewareConfig?.lifecycle?.config,
-                                    onFinish: options.onFinish,
-                                    onError: options.onError,
-                                    onChunk: options.onChunk,
+                                    ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
+                                    ...(options.onError !== undefined ? { onError: options.onError } : {}),
+                                    ...(options.onChunk !== undefined ? { onChunk: options.onChunk } : {}),
                                 },
                             },
                         },
@@ -4372,7 +4221,12 @@ Current user's request: ${currentInput}`;
                     try {
                         // Prepare options: init memory, MCP, 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);
+                        const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, finishReason: streamFinishReason, toolCalls: streamToolCalls, toolResults: streamToolResults, analytics: streamAnalytics, } = await this.createMCPStream(enhancedOptions);
+                        const streamState = {
+                            finishReason: streamFinishReason ?? "stop",
+                            toolCalls: streamToolCalls,
+                            toolResults: streamToolResults,
+                        };
                         // Update span with resolved provider name
                         streamSpan.setAttribute(ATTR.NL_PROVIDER, providerName || "unknown");
                         let accumulatedContent = "";
@@ -4394,9 +4248,7 @@ Current user's request: ${currentInput}`;
                             try {
                                 for await (const chunk of mcpStream) {
                                     chunkCount++;
-                                    if (chunk &&
-                                        "content" in chunk &&
-                                        typeof chunk.content === "string") {
+                                    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)
@@ -4412,8 +4264,12 @@ Current user's request: ${currentInput}`;
                                     }
                                     yield chunk;
                                 }
-                                if (chunkCount === 0 && !metadata.fallbackAttempted) {
-                                    yield* self.handleStreamFallback(metadata, originalPrompt, enhancedOptions, providerName, accumulatedContent, (content) => {
+                                if (chunkCount === 0 &&
+                                    !metadata.fallbackAttempted &&
+                                    !enhancedOptions.disableInternalFallback &&
+                                    streamState.toolCalls.length === 0 &&
+                                    streamState.toolResults.length === 0) {
+                                    yield* self.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, accumulatedContent, (content) => {
                                         accumulatedContent += content;
                                     });
                                 }
@@ -4421,9 +4277,7 @@ Current user's request: ${currentInput}`;
                                 // 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;
+                                const effectiveModel = metadata.fallbackModel ?? streamModel ?? enhancedOptions.model;
                                 // Resolve analytics promise to get final token usage
                                 let resolvedUsage = streamUsage;
                                 if (!resolvedUsage && streamAnalytics) {
@@ -4442,8 +4296,7 @@ Current user's request: ${currentInput}`;
                                     content: accumulatedContent,
                                     provider: effectiveProvider,
                                     model: effectiveModel,
-                                    prompt: enhancedOptions.input?.text ||
-                                        enhancedOptions.prompt,
+                                    prompt: enhancedOptions.input?.text || enhancedOptions.prompt,
                                     metadata: {
                                         chunkCount,
                                         totalLength: accumulatedContent.length,
@@ -4497,10 +4350,7 @@ Current user's request: ${currentInput}`;
                                 if (primaryFailed) {
                                     streamSpan.setStatus({
                                         code: SpanStatusCode.ERROR,
-                                        message: metadata.error ||
-                                            (streamError instanceof Error
-                                                ? streamError.message
-                                                : String(streamError)),
+                                        message: metadata.error || (streamError instanceof Error ? streamError.message : String(streamError)),
                                     });
                                 }
                                 else {
@@ -4527,10 +4377,18 @@ Current user's request: ${currentInput}`;
                             }
                         })();
                         const streamResult = await this.processStreamResult(processedStream, enhancedOptions, factoryResult);
+                        streamResult.finishReason = streamState.finishReason || streamResult.finishReason;
+                        streamResult.toolCalls = streamState.toolCalls;
+                        streamResult.toolResults = streamState.toolResults;
+                        if (!streamResult.usage) {
+                            streamResult.usage = streamUsage;
+                        }
+                        if (!streamResult.analytics) {
+                            streamResult.analytics = streamAnalytics instanceof Promise ? await streamAnalytics : streamAnalytics;
+                        }
                         const responseTime = Date.now() - startTime;
                         // Accumulate session cost for budget tracking
-                        if (streamResult.analytics?.cost &&
-                            streamResult.analytics.cost > 0) {
+                        if (streamResult.analytics?.cost && streamResult.analytics.cost > 0) {
                             this._sessionCostUsd += streamResult.analytics.cost;
                         }
                         this.emitStreamEndEvents(streamResult);
@@ -4547,6 +4405,9 @@ Current user's request: ${currentInput}`;
                         });
                     }
                     catch (error) {
+                        if (options.disableInternalFallback) {
+                            throw error;
+                        }
                         return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
                     }
                 });
@@ -4575,8 +4436,7 @@ Current user's request: ${currentInput}`;
         // Initialize MCP
         await this.initializeMCP();
         // Memory retrieval
-        if (this.shouldReadMemory(options.memory, options.context?.userId) &&
-            options.context?.userId) {
+        if (this.shouldReadMemory(options.memory, options.context?.userId) && options.context?.userId) {
             try {
                 options.input.text = await this.retrieveMemory(options.input.text, options.context.userId, options.memory?.additionalUsers);
                 logger.debug("Memory retrieval successful");
@@ -4621,8 +4481,7 @@ Current user's request: ${currentInput}`;
                 if (!options.tools) {
                     options.tools = {};
                 }
-                options.tools[ragResult.toolName] =
-                    ragResult.tool;
+                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`,
@@ -4631,8 +4490,7 @@ Current user's request: ${currentInput}`;
                     `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;
+                options.systemPrompt = (options.systemPrompt || "") + ragSystemInstruction;
                 logger.info("[RAG] Tool injected into stream()", {
                     toolName: ragResult.toolName,
                     filesLoaded: ragResult.filesLoaded,
@@ -4660,8 +4518,7 @@ Current user's request: ${currentInput}`;
      * Prevents overwhelming smaller models with massive tool descriptions in the system message.
      */
     async autoDisableOllamaStreamTools(options) {
-        if ((options.provider === "ollama" ||
-            options.provider?.toLowerCase().includes("ollama")) &&
+        if ((options.provider === "ollama" || options.provider?.toLowerCase().includes("ollama")) &&
             !options.disableTools) {
             const { ModelConfigurationManager } = await import("./core/modelConfiguration.js");
             const modelConfig = ModelConfigurationManager.getInstance();
@@ -4745,7 +4602,7 @@ Current user's request: ${currentInput}`;
      * Handle fallback when the primary stream returns 0 chunks.
      * Yields chunks from a fallback provider and updates metadata accordingly.
      */
-    async *handleStreamFallback(metadata, originalPrompt, enhancedOptions, providerName, _accumulatedContent, appendContent) {
+    async *handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, _accumulatedContent, appendContent) {
         metadata.fallbackAttempted = true;
         const errorMsg = "Stream completed with 0 chunks (possible guardrails block)";
         metadata.error = errorMsg;
@@ -4803,18 +4660,23 @@ Current user's request: ${currentInput}`;
                 model: fallbackRoute.model,
                 conversationMessages,
             });
+            const fallbackToolCalls = fallbackResult.toolCalls ?? [];
+            const fallbackToolResults = fallbackResult.toolResults ?? [];
+            if (fallbackToolCalls.length > 0 || fallbackToolResults.length > 0) {
+                streamState.toolCalls = fallbackToolCalls;
+                streamState.toolResults = fallbackToolResults;
+                streamState.finishReason = fallbackResult.finishReason ?? streamState.finishReason;
+            }
             let fallbackChunkCount = 0;
             for await (const fallbackChunk of fallbackResult.stream) {
                 fallbackChunkCount++;
-                if (fallbackChunk &&
-                    "content" in fallbackChunk &&
-                    typeof fallbackChunk.content === "string") {
+                if (fallbackChunk && "content" in fallbackChunk && typeof fallbackChunk.content === "string") {
                     appendContent(fallbackChunk.content);
                     this.emitter.emit("response:chunk", fallbackChunk.content);
                 }
                 yield fallbackChunk;
             }
-            if (fallbackChunkCount === 0) {
+            if (fallbackChunkCount === 0 && fallbackToolCalls.length === 0 && fallbackToolResults.length === 0) {
                 throw new Error(`Fallback provider ${fallbackRoute.provider} also returned 0 chunks`);
             }
             // Fallback succeeded - likely guardrails blocked primary
@@ -4823,9 +4685,7 @@ Current user's request: ${currentInput}`;
             metadata.guardrailsBlocked = true;
         }
         catch (fallbackError) {
-            const fallbackErrorMsg = fallbackError instanceof Error
-                ? fallbackError.message
-                : String(fallbackError);
+            const fallbackErrorMsg = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
             metadata.error = `${errorMsg}; Fallback failed: ${fallbackErrorMsg}`;
             logger.error("Fallback provider failed", {
                 fallbackProvider: fallbackRoute.provider,
@@ -4839,22 +4699,19 @@ Current user's request: ${currentInput}`;
      * Handles conversation memory storage in the background.
      */
     async storeStreamConversationMemory(params) {
-        const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, } = params;
+        const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence } = params;
         // Guard: skip storing if no meaningful content was produced (no text AND no tool activity)
         const hasToolEvents = eventSequence.some((e) => e.type === "tool:start" || e.type === "tool:end");
         if (!accumulatedContent.trim() && !hasToolEvents) {
             logger.warn("[NeuroLink.stream] Skipping conversation turn storage — no text content or tool activity", {
-                sessionId: enhancedOptions.context
-                    ?.sessionId,
+                sessionId: enhancedOptions.context?.sessionId,
             });
             return;
         }
         // Store memory after stream consumption is complete
         if (this.conversationMemory && enhancedOptions.context?.sessionId) {
-            const sessionId = enhancedOptions.context
-                ?.sessionId;
-            const userId = enhancedOptions.context
-                ?.userId;
+            const sessionId = enhancedOptions.context?.sessionId;
+            const userId = enhancedOptions.context?.userId;
             let providerDetails;
             if (enhancedOptions.model) {
                 providerDetails = {
@@ -4873,8 +4730,7 @@ Current user's request: ${currentInput}`;
                     providerDetails,
                     enableSummarization: enhancedOptions.enableSummarization,
                     events: eventSequence.length > 0 ? eventSequence : undefined,
-                    requestId: enhancedOptions.context
-                        ?.requestId,
+                    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", {
@@ -4904,8 +4760,7 @@ Current user's request: ${currentInput}`;
             validationStartTimeNs: validationStartTime.toString(),
             message: "Starting comprehensive input validation process",
         });
-        const hasText = typeof options?.input?.text === "string" &&
-            options.input.text.trim().length > 0;
+        const hasText = typeof options?.input?.text === "string" && options.input.text.trim().length > 0;
         // Accept audio when frames are present; sampleRateHz is optional (defaults applied later)
         const hasAudio = !!(options?.input?.audio &&
             options.input.audio.frames &&
@@ -4984,12 +4839,10 @@ Current user's request: ${currentInput}`;
         const streamCompactionSessionId = this.getCompactionSessionId(options);
         if (streamBudget.shouldCompact &&
             (hasCallerConversationHistory || this.conversationMemory) &&
-            streamMessageCount >
-                (this.lastCompactionMessageCount.get(streamCompactionSessionId) ?? 0)) {
+            streamMessageCount > (this.lastCompactionMessageCount.get(streamCompactionSessionId) ?? 0)) {
             const compactor = new ContextCompactor({
                 provider: providerName,
-                summarizationProvider: this.conversationMemoryConfig?.conversationMemory
-                    ?.summarizationProvider,
+                summarizationProvider: this.conversationMemoryConfig?.conversationMemory?.summarizationProvider,
                 summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
             });
             const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
@@ -5059,6 +4912,9 @@ Current user's request: ${currentInput}`;
             provider: providerName,
             usage: streamResult.usage,
             model: streamResult.model || options.model,
+            finishReason: streamResult.finishReason,
+            toolCalls: streamResult.toolCalls ?? [],
+            toolResults: streamResult.toolResults ?? [],
             analytics: streamResult.analytics,
         };
     }
@@ -5131,8 +4987,7 @@ Current user's request: ${currentInput}`;
                 parentSpanId: traceCtx?.parentSpanId,
             });
             failedSpan = SpanSerializer.endSpan(failedSpan, SpanStatus.ERROR);
-            failedSpan.statusMessage =
-                error instanceof Error ? error.message : String(error);
+            failedSpan.statusMessage = error instanceof Error ? error.message : String(error);
             failedSpan.durationMs = Date.now() - startTime;
             this.metricsAggregator.recordSpan(failedSpan);
             getMetricsAggregator().recordSpan(failedSpan);
@@ -5156,9 +5011,7 @@ Current user's request: ${currentInput}`;
         const fallbackProcessedStream = (async function* (self) {
             try {
                 for await (const chunk of fallbackStreamResult.stream) {
-                    if (chunk &&
-                        "content" in chunk &&
-                        typeof chunk.content === "string") {
+                    if (chunk && "content" in chunk && typeof chunk.content === "string") {
                         fallbackAccumulatedContent += chunk.content;
                         // Emit chunk event
                         self.emitter.emit("response:chunk", chunk.content);
@@ -5177,12 +5030,9 @@ Current user's request: ${currentInput}`;
                 }
                 // Store memory after fallback stream consumption is complete
                 // Guard: skip storing if fallback accumulated content is empty
-                if (self.conversationMemory &&
-                    enhancedOptions?.context?.sessionId &&
-                    fallbackAccumulatedContent.trim()) {
+                if (self.conversationMemory && enhancedOptions?.context?.sessionId && fallbackAccumulatedContent.trim()) {
                     const sessionId = enhancedOptions?.context?.sessionId;
-                    const userId = enhancedOptions?.context
-                        ?.userId;
+                    const userId = enhancedOptions?.context?.userId;
                     let providerDetails;
                     if (options.model) {
                         providerDetails = {
@@ -5201,8 +5051,7 @@ Current user's request: ${currentInput}`;
                             providerDetails,
                             enableSummarization: enhancedOptions?.enableSummarization,
                             requestId: enhancedOptions?.context?.requestId ||
-                                options.context
-                                    ?.requestId,
+                                options.context?.requestId,
                         });
                         self.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "fallback-stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                     }
@@ -5601,7 +5450,8 @@ Current user's request: ${currentInput}`;
             // (direct executeTool() or AI SDK generateText() tool calling).
             if (options?.timeout !== undefined &&
                 options.timeout > 0 &&
-                Number.isFinite(options.timeout)) {
+                Number.isFinite(options.timeout) &&
+                typeof convertedTool.execute === "function") {
                 const originalExecute = convertedTool.execute;
                 const toolTimeout = options.timeout;
                 const toolName = name;
@@ -5610,9 +5460,7 @@ Current user's request: ${currentInput}`;
                     // Compose with any parent abortSignal from ToolExecutionOptions
                     const execOptions = args[1];
                     const parentSignal = execOptions?.abortSignal;
-                    const composedSignal = parentSignal
-                        ? AbortSignal.any([parentSignal, timeoutSignal])
-                        : timeoutSignal;
+                    const composedSignal = parentSignal ? AbortSignal.any([parentSignal, timeoutSignal]) : timeoutSignal;
                     // Replace the abortSignal in execution options
                     const augmentedContext = {
                         ...execOptions,
@@ -5623,7 +5471,7 @@ Current user's request: ${currentInput}`;
                         new Promise((_, reject) => {
                             composedSignal.addEventListener("abort", () => {
                                 if (timeoutSignal.aborted) {
-                                    reject(new Error(`Tool '${toolName}' timed out after ${toolTimeout}ms (configured at registration)`));
+                                    reject(ErrorFactory.toolTimeout(toolName, toolTimeout));
                                 }
                                 else {
                                     reject(new DOMException("The operation was aborted", "AbortError"));
@@ -5669,9 +5517,7 @@ Current user's request: ${currentInput}`;
      * @returns Current context or undefined if not set
      */
     getToolContext() {
-        return this.toolExecutionContext
-            ? { ...this.toolExecutionContext }
-            : undefined;
+        return this.toolExecutionContext ? { ...this.toolExecutionContext } : undefined;
     }
     /**
      * Clear the tool execution context
@@ -5775,8 +5621,7 @@ Current user's request: ${currentInput}`;
             typeof this.conversationMemory.updateAgenticLoopReport !== "function") {
             throw new ConversationMemoryError("updateAgenticLoopReport is only supported with Redis conversation memory.", "CONFIG_ERROR");
         }
-        await withTimeout(this
-            .conversationMemory.updateAgenticLoopReport(sessionId, userId, report), 5000);
+        await withTimeout(this.conversationMemory.updateAgenticLoopReport(sessionId, userId, report), 5000);
     }
     /**
      * Get all registered custom tools
@@ -5794,14 +5639,10 @@ Current user's request: ${currentInput}`;
                 description: tool.description,
                 hasParameters: !!tool.parameters,
                 parametersType: typeof tool.parameters,
-                parametersKeys: tool.parameters && typeof tool.parameters === "object"
-                    ? Object.keys(tool.parameters)
-                    : "NOT_OBJECT",
+                parametersKeys: tool.parameters && typeof tool.parameters === "object" ? Object.keys(tool.parameters) : "NOT_OBJECT",
                 hasInputSchema: !!tool.inputSchema,
                 inputSchemaType: typeof tool.inputSchema,
-                inputSchemaKeys: tool.inputSchema && typeof tool.inputSchema === "object"
-                    ? Object.keys(tool.inputSchema)
-                    : "NOT_OBJECT",
+                inputSchemaKeys: tool.inputSchema && typeof tool.inputSchema === "object" ? Object.keys(tool.inputSchema) : "NOT_OBJECT",
                 hasEffectiveSchema: !!effectiveSchema,
                 effectiveSchemaType: typeof effectiveSchema,
                 effectiveSchemaHasProperties: !!effectiveSchema?.properties,
@@ -5822,18 +5663,14 @@ Current user's request: ${currentInput}`;
                 execute: async (params, context) => {
                     // CONTEXT MERGING: Combine all available contexts for maximum information
                     const storedContext = this.toolExecutionContext || {};
-                    const runtimeContext = context && isNonNullObject(context)
-                        ? context
-                        : {};
+                    const runtimeContext = context && isNonNullObject(context) ? context : {};
                     // Merge contexts with runtime context taking precedence
                     // This ensures we have the richest possible context for tool execution
                     const executionContext = {
                         ...storedContext, // Base context from setToolContext (session, tokens, etc.)
                         ...runtimeContext, // Runtime context from AI model (if any)
                         // Ensure we always have at least a sessionId for tracing
-                        sessionId: runtimeContext.sessionId ||
-                            storedContext.sessionId ||
-                            `fallback-${Date.now()}`,
+                        sessionId: runtimeContext.sessionId || storedContext.sessionId || `fallback-${Date.now()}`,
                     };
                     // Enhanced logging for context debugging
                     logger.debug("Tool execution context merged", {
@@ -5841,8 +5678,7 @@ Current user's request: ${currentInput}`;
                         storedContextKeys: Object.keys(storedContext),
                         runtimeContextKeys: Object.keys(runtimeContext),
                         finalContextKeys: Object.keys(executionContext),
-                        hasJuspayToken: !!executionContext
-                            .juspayToken,
+                        hasJuspayToken: !!executionContext.juspayToken,
                         hasShopId: !!executionContext.shopId,
                         sessionId: executionContext.sessionId,
                     });
@@ -5870,9 +5706,7 @@ Current user's request: ${currentInput}`;
                 toolMap.set(toolName, {
                     name: toolName,
                     description: toolDef.description || `File tool: ${toolName}`,
-                    inputSchema: typeof toolParams === "object" && toolParams !== null
-                        ? toolParams
-                        : { type: "object", properties: {} },
+                    inputSchema: typeof toolParams === "object" && toolParams !== null ? toolParams : { type: "object", properties: {} },
                     execute: async (params) => {
                         return await toolDef.execute(params, {
                             toolCallId: `file-tool-${Date.now()}`,
@@ -5983,17 +5817,9 @@ Current user's request: ${currentInput}`;
         // Determine tool type for span attributes
         const externalTools = this.externalServerManager.getAllTools();
         const externalTool = externalTools.find((tool) => tool.name === toolName);
-        const toolType = externalTool
-            ? "mcp"
-            : this.getCustomTools().has(toolName)
-                ? "custom"
-                : "external";
+        const toolType = externalTool ? "mcp" : this.getCustomTools().has(toolName) ? "custom" : "external";
         // Compute truncated input size for the span
-        const inputStr = typeof params === "string"
-            ? params
-            : params
-                ? JSON.stringify(params)
-                : "";
+        const inputStr = typeof params === "string" ? params : params ? JSON.stringify(params) : "";
         const inputSize = inputStr.length;
         const truncatedInput = inputStr.length > 2048 ? inputStr.substring(0, 2048) : inputStr;
         return tracers.mcp.startActiveSpan("neurolink.tool.execute", {
@@ -6008,9 +5834,7 @@ Current user's request: ${currentInput}`;
                 // Debug: Log tool execution attempt
                 logger.debug(`[${functionTag}] Tool execution requested:`, {
                     toolName,
-                    params: isNonNullObject(params)
-                        ? transformParamsForLogging(params)
-                        : params,
+                    params: isNonNullObject(params) ? transformParamsForLogging(params) : params,
                     hasExternalManager: !!this.externalServerManager,
                 });
                 // 🔧 PARAMETER TRACE: Log tool execution details for debugging
@@ -6021,15 +5845,9 @@ Current user's request: ${currentInput}`;
                         type: typeof params,
                         isNull: params === null,
                         isUndefined: params === undefined,
-                        isEmpty: params &&
-                            typeof params === "object" &&
-                            Object.keys(params).length === 0,
-                        keys: params && typeof params === "object"
-                            ? Object.keys(params)
-                            : "NOT_OBJECT",
-                        keysLength: params && typeof params === "object"
-                            ? Object.keys(params).length
-                            : 0,
+                        isEmpty: params && typeof params === "object" && Object.keys(params).length === 0,
+                        keys: params && typeof params === "object" ? Object.keys(params) : "NOT_OBJECT",
+                        keysLength: params && typeof params === "object" ? Object.keys(params).length : 0,
                     },
                     isTargetTool: toolName === "juspay-analytics_SuccessRateSRByTime",
                     options,
@@ -6049,12 +5867,8 @@ Current user's request: ${currentInput}`;
                 const registeredTimeout = toolInfo?.tool?.timeoutMs;
                 const registeredMaxRetries = toolInfo?.tool?.maxRetries;
                 const finalOptions = {
-                    timeout: options?.timeout ??
-                        registeredTimeout ??
-                        TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS,
-                    maxRetries: options?.maxRetries ??
-                        registeredMaxRetries ??
-                        RETRY_ATTEMPTS.DEFAULT,
+                    timeout: options?.timeout ?? registeredTimeout ?? TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS,
+                    maxRetries: options?.maxRetries ?? registeredMaxRetries ?? RETRY_ATTEMPTS.DEFAULT,
                     retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS,
                     authContext: options?.authContext,
                     disableToolCache: options?.disableToolCache,
@@ -6117,9 +5931,7 @@ Current user's request: ${currentInput}`;
                         metrics.successfulExecutions++;
                         metrics.lastExecutionTime = executionTime;
                         metrics.averageExecutionTime =
-                            (metrics.averageExecutionTime *
-                                (metrics.successfulExecutions - 1) +
-                                executionTime) /
+                            (metrics.averageExecutionTime * (metrics.successfulExecutions - 1) + executionTime) /
                                 metrics.successfulExecutions;
                     }
                     // Track memory usage
@@ -6141,15 +5953,9 @@ Current user's request: ${currentInput}`;
                     // Set span success attributes
                     // Check if result has isError flag (MCP tool error result)
                     // Also detect toolRegistry-wrapped errors that return { success: false }
-                    const resultObj = result && typeof result === "object"
-                        ? result
-                        : undefined;
-                    const isToolError = (resultObj &&
-                        "isError" in resultObj &&
-                        resultObj.isError === true) ||
-                        (resultObj &&
-                            "success" in resultObj &&
-                            resultObj.success === false);
+                    const resultObj = result && typeof result === "object" ? result : undefined;
+                    const isToolError = (resultObj && "isError" in resultObj && resultObj.isError === true) ||
+                        (resultObj && "success" in resultObj && resultObj.success === false);
                     // NL-001: Count isError:true results as circuit breaker failures
                     // This ensures tools that return error results (not just thrown errors) are tracked
                     // TODO(NL-009): This records a failure AFTER the circuit breaker already recorded
@@ -6180,10 +5986,7 @@ Current user's request: ${currentInput}`;
                         const errorText = contentArr
                             ?.filter((c) => c.type === "text" && c.text)
                             .map((c) => c.text)
-                            .join(" ") ||
-                            (typeof resultObj.error === "string"
-                                ? resultObj.error
-                                : "Unknown error");
+                            .join(" ") || (typeof resultObj.error === "string" ? resultObj.error : "Unknown error");
                         const errorCategory = classifyMcpErrorMessage(errorText);
                         const prefix = `[TOOL_ERROR: ${toolName} failed (${errorCategory})] `;
                         // NL-002: Clone content array to avoid mutating shared objects, then prefix error
@@ -6212,17 +6015,14 @@ Current user's request: ${currentInput}`;
                             // which was incorrectly included as a success
                             if (prevSuccessful > 1) {
                                 metrics.averageExecutionTime =
-                                    (metrics.averageExecutionTime * prevSuccessful -
-                                        executionTime) /
-                                        (prevSuccessful - 1);
+                                    (metrics.averageExecutionTime * prevSuccessful - executionTime) / (prevSuccessful - 1);
                             }
                             else {
                                 // No remaining successful executions, reset to 0
                                 metrics.averageExecutionTime = 0;
                             }
                             const mappedCategory = mcpCategoryToErrorCategory(errorCategory);
-                            metrics.errorCategories[mappedCategory] =
-                                (metrics.errorCategories[mappedCategory] || 0) + 1;
+                            metrics.errorCategories[mappedCategory] = (metrics.errorCategories[mappedCategory] || 0) + 1;
                         }
                     }
                     // Emit tool end event AFTER isError check so success flag is correct
@@ -6251,8 +6051,7 @@ Current user's request: ${currentInput}`;
                         });
                         if (metrics) {
                             const category = ErrorCategory.EXECUTION;
-                            metrics.errorCategories[category] =
-                                (metrics.errorCategories[category] || 0) + 1;
+                            metrics.errorCategories[category] = (metrics.errorCategories[category] || 0) + 1;
                         }
                         // Emit tool end event for circuit breaker open
                         this.emitToolEndEvent(toolName, executionStartTime, false, undefined);
@@ -6296,12 +6095,10 @@ Current user's request: ${currentInput}`;
                             const availableTools = await this.getAllAvailableTools();
                             structuredError = ErrorFactory.toolNotFound(toolName, extractToolNames(availableTools.map((t) => ({ name: t.name }))));
                         }
-                        else if (error.message.includes("validation") ||
-                            error.message.includes("parameter")) {
+                        else if (error.message.includes("validation") || error.message.includes("parameter")) {
                             structuredError = ErrorFactory.invalidParameters(toolName, error, params);
                         }
-                        else if (error.message.includes("network") ||
-                            error.message.includes("connection")) {
+                        else if (error.message.includes("network") || error.message.includes("connection")) {
                             structuredError = ErrorFactory.networkError(toolName, error);
                         }
                         else {
@@ -6313,8 +6110,7 @@ Current user's request: ${currentInput}`;
                     }
                     if (metrics) {
                         const category = structuredError.category || ErrorCategory.EXECUTION;
-                        metrics.errorCategories[category] =
-                            (metrics.errorCategories[category] || 0) + 1;
+                        metrics.errorCategories[category] = (metrics.errorCategories[category] || 0) + 1;
                     }
                     // Emit tool end event BEFORE the error event.
                     // Node.js EventEmitter throws on unhandled 'error' events,
@@ -6351,9 +6147,7 @@ Current user's request: ${currentInput}`;
             catch (outerError) {
                 // If the error was not already recorded on the span (from inner catch), record it
                 if (!(outerError instanceof NeuroLinkError)) {
-                    const errMsg = outerError instanceof Error
-                        ? outerError.message
-                        : String(outerError);
+                    const errMsg = outerError instanceof Error ? outerError.message : String(outerError);
                     toolSpan.recordException(outerError instanceof Error ? outerError : new Error(errMsg));
                     toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
                 }
@@ -6379,9 +6173,17 @@ Current user's request: ${currentInput}`;
             !options.disableToolCache &&
             !this._disableToolCacheForCurrentRequest &&
             !toolAnnotations?.destructiveHint;
+        const toolResultCache = this.mcpToolResultCache;
         // === MCP ENHANCEMENT: Cache check (before execution) ===
-        if (isCacheEnabled) {
-            const cached = this.mcpToolResultCache.getCachedResult(toolName, params);
+        // Scope cache key by auth context to prevent cross-user cache leaks
+        const cacheParams = options.authContext || this.toolExecutionContext
+            ? {
+                __args: params,
+                __ctx: options.authContext ?? this.toolExecutionContext,
+            }
+            : params;
+        if (isCacheEnabled && toolResultCache) {
+            const cached = toolResultCache.getCachedResult(toolName, cacheParams);
             if (cached !== undefined) {
                 logger.debug(`[${functionTag}] Cache HIT for tool: ${toolName}`);
                 return cached;
@@ -6432,9 +6234,7 @@ Current user's request: ${currentInput}`;
                         inputSchema: {},
                     };
                     const decision = this.mcpToolRouter.route(mcpTool);
-                    externalTool =
-                        matchingTools.find((t) => t.serverId === decision.serverId) ||
-                            matchingTools[0];
+                    externalTool = matchingTools.find((t) => t.serverId === decision.serverId) || matchingTools[0];
                     logger.debug(`[${functionTag}] Router selected server: ${decision.serverId}`, {
                         strategy: decision.strategy,
                         confidence: decision.confidence,
@@ -6490,10 +6290,7 @@ Current user's request: ${currentInput}`;
                 });
                 const result = (await this.toolRegistry.executeTool(toolName, params, context));
                 // Check if result indicates a failure and emit error event
-                if (result &&
-                    typeof result === "object" &&
-                    "success" in result &&
-                    result.success === false) {
+                if (result && typeof result === "object" && "success" in result && result.success === false) {
                     const errorMessage = result.error || "Tool execution failed";
                     const errorToEmit = new Error(errorMessage);
                     this.emitter.emit("error", errorToEmit);
@@ -6515,8 +6312,8 @@ Current user's request: ${currentInput}`;
         try {
             const result = await executeWithMiddleware(executeCore);
             // === MCP ENHANCEMENT: Cache store (after successful execution) ===
-            if (isCacheEnabled && result !== undefined) {
-                this.mcpToolResultCache.cacheResult(toolName, params, result);
+            if (isCacheEnabled && toolResultCache && result !== undefined) {
+                toolResultCache.cacheResult(toolName, cacheParams, result);
                 logger.debug(`[${functionTag}] Cached result for tool: ${toolName}`);
             }
             return result;
@@ -6531,16 +6328,13 @@ Current user's request: ${currentInput}`;
                     execute: async () => ({}),
                 }
                 : undefined;
-            if (toolStubForRetry &&
-                isSafeToRetry(toolStubForRetry) &&
-                error instanceof Error &&
-                isRetriableError(error)) {
+            if (toolStubForRetry && isSafeToRetry(toolStubForRetry) && error instanceof Error && isRetriableError(error)) {
                 logger.debug(`[${functionTag}] Tool ${toolName} is safe to retry, attempting once more`);
                 try {
                     const retryResult = await executeWithMiddleware(executeCore);
                     // Cache the retry result
-                    if (isCacheEnabled && retryResult !== undefined) {
-                        this.mcpToolResultCache.cacheResult(toolName, params, retryResult);
+                    if (isCacheEnabled && toolResultCache && retryResult !== undefined) {
+                        toolResultCache.cacheResult(toolName, cacheParams, retryResult);
                     }
                     return retryResult;
                 }
@@ -6579,8 +6373,7 @@ Current user's request: ${currentInput}`;
     }
     async getAllAvailableTools() {
         // Return from cache if available and not stale
-        if (this.toolCache &&
-            Date.now() - this.toolCache.timestamp < this.toolCacheDuration) {
+        if (this.toolCache && Date.now() - this.toolCache.timestamp < this.toolCacheDuration) {
             logger.debug("Returning available tools from cache");
             return this.toolCache.tools;
         }
@@ -6661,9 +6454,7 @@ Current user's request: ${currentInput}`;
                 if (!allTools.has(tool.name)) {
                     const optimizedTool = optimizeToolForCollection(tool, {
                         category: detectCategory({
-                            existingCategory: typeof tool.metadata?.category === "string"
-                                ? tool.metadata.category
-                                : undefined,
+                            existingCategory: typeof tool.metadata?.category === "string" ? tool.metadata.category : undefined,
                             isExternal: true,
                             serverId: tool.serverId,
                         }),
@@ -6819,9 +6610,7 @@ Current user's request: ${currentInput}`;
                             status: "failed",
                             configured: false,
                             authenticated: false,
-                            error: error instanceof Error
-                                ? error.message
-                                : "Ollama service not running",
+                            error: error instanceof Error ? error.message : "Ollama service not running",
                             responseTime: Date.now() - startTime,
                         };
                     }
@@ -6944,9 +6733,7 @@ Current user's request: ${currentInput}`;
                 inMemoryServerInfos.length +
                 builtInServerInfos.length +
                 autoDiscoveredServerInfos.length;
-            const availableServers = externalStats.connectedServers +
-                inMemoryServerInfos.length +
-                builtInServerInfos.length; // in-memory and built-in always available
+            const availableServers = externalStats.connectedServers + inMemoryServerInfos.length + builtInServerInfos.length; // in-memory and built-in always available
             const totalTools = allTools.length + externalStats.totalTools;
             return {
                 mcpInitialized: this.mcpInitialized,
@@ -7015,8 +6802,7 @@ Current user's request: ${currentInput}`;
             // Test external MCP servers
             const externalServer = this.externalServerManager.getServer(serverId);
             if (externalServer) {
-                return (externalServer.status === "connected" &&
-                    externalServer.client !== null);
+                return externalServer.status === "connected" && externalServer.client !== null;
             }
             return false;
         }
@@ -7136,9 +6922,7 @@ Current user's request: ${currentInput}`;
             metrics[toolName] = {
                 ...toolMetrics,
                 errorCategories: { ...toolMetrics.errorCategories },
-                successRate: toolMetrics.totalExecutions > 0
-                    ? toolMetrics.successfulExecutions / toolMetrics.totalExecutions
-                    : 0,
+                successRate: toolMetrics.totalExecutions > 0 ? toolMetrics.successfulExecutions / toolMetrics.totalExecutions : 0,
             };
         }
         return metrics;
@@ -7158,7 +6942,7 @@ Current user's request: ${currentInput}`;
      */
     getToolCircuitBreakerStatus() {
         const status = {};
-        for (const [toolName, circuitBreaker,] of this.toolCircuitBreakers.entries()) {
+        for (const [toolName, circuitBreaker] of this.toolCircuitBreakers.entries()) {
             status[toolName] = {
                 state: circuitBreaker.getState(),
                 failureCount: circuitBreaker.getFailureCount(),
@@ -7211,8 +6995,7 @@ Current user's request: ${currentInput}`;
                     ? metrics.successfulExecutions / metrics.totalExecutions
                     : 0
                 : 0;
-            const isHealthy = (!circuitBreaker || circuitBreaker.getState() === "closed") &&
-                successRate >= 0.8;
+            const isHealthy = (!circuitBreaker || circuitBreaker.getState() === "closed") && successRate >= 0.8;
             if (isHealthy) {
                 healthyCount++;
             }
@@ -7253,9 +7036,7 @@ Current user's request: ${currentInput}`;
                     successRate,
                     averageExecutionTime: metrics?.averageExecutionTime || 0,
                     lastExecutionTime: metrics?.lastExecutionTime || 0,
-                    errorCategories: metrics?.errorCategories
-                        ? { ...metrics.errorCategories }
-                        : {},
+                    errorCategories: metrics?.errorCategories ? { ...metrics.errorCategories } : {},
                 },
                 circuitBreaker: {
                     state: circuitBreaker?.getState() || "closed",
@@ -7407,8 +7188,7 @@ Current user's request: ${currentInput}`;
      */
     async storeToolExecutions(sessionId, userId, toolCalls, toolResults, currentTime) {
         // Check if tools are not empty
-        const hasToolData = (toolCalls && toolCalls.length > 0) ||
-            (toolResults && toolResults.length > 0);
+        const hasToolData = (toolCalls && toolCalls.length > 0) || (toolResults && toolResults.length > 0);
         if (!hasToolData) {
             logger.debug("Tool execution storage skipped", {
                 hasToolData,
@@ -7418,8 +7198,7 @@ Current user's request: ${currentInput}`;
             return;
         }
         // Type guard to ensure it's Redis conversation memory manager
-        const redisMemory = this
-            .conversationMemory;
+        const redisMemory = this.conversationMemory;
         try {
             await redisMemory.storeToolExecution(sessionId, userId, toolCalls, toolResults, currentTime);
         }
@@ -7438,9 +7217,7 @@ Current user's request: ${currentInput}`;
      */
     isToolExecutionStorageAvailable() {
         const isRedisStorage = process.env.STORAGE_TYPE === "redis";
-        const hasRedisConversationMemory = this.conversationMemory &&
-            this.conversationMemory.constructor.name ===
-                "RedisConversationMemoryManager";
+        const hasRedisConversationMemory = this.conversationMemory && this.conversationMemory.constructor.name === "RedisConversationMemoryManager";
         return !!(isRedisStorage && hasRedisConversationMemory);
     }
     /**
@@ -7959,8 +7736,7 @@ Current user's request: ${currentInput}`;
             return null;
         }
         // Check for explicit annotations set on the tool first
-        const explicitAnnotations = toolInfo.tool
-            .annotations;
+        const explicitAnnotations = toolInfo.tool.annotations;
         // Infer annotations from the tool name/description as fallback
         const inferredAnnotations = inferAnnotations({
             name: toolInfo.tool.name,
@@ -7992,9 +7768,7 @@ Current user's request: ${currentInput}`;
                             const result = await this.externalServerManager.executeTool(tool.serverId, tool.name, params, { timeout: 30000 });
                             mcpLogger.debug(`[NeuroLink] External MCP tool execution result: ${tool.name}`, {
                                 success: !!result,
-                                hasData: !!(result &&
-                                    typeof result === "object" &&
-                                    "content" in result),
+                                hasData: !!(result && typeof result === "object" && "content" in result),
                             });
                             return result;
                         }
@@ -8410,9 +8184,7 @@ Current user's request: ${currentInput}`;
                 logger.debug("[NeuroLink] OpenTelemetry shutdown successfully");
             }
             catch (error) {
-                const err = error instanceof Error
-                    ? error
-                    : new Error(`OpenTelemetry shutdown error: ${String(error)}`);
+                const err = error instanceof Error ? error : new Error(`OpenTelemetry shutdown error: ${String(error)}`);
                 cleanupErrors.push(err);
                 logger.warn("[NeuroLink] Error shutting down OpenTelemetry:", error);
             }
@@ -8424,9 +8196,7 @@ Current user's request: ${currentInput}`;
                     logger.debug("[NeuroLink] External MCP servers shutdown successfully");
                 }
                 catch (error) {
-                    const err = error instanceof Error
-                        ? error
-                        : new Error(`External server shutdown error: ${String(error)}`);
+                    const err = error instanceof Error ? error : new Error(`External server shutdown error: ${String(error)}`);
                     cleanupErrors.push(err);
                     logger.warn("[NeuroLink] Error shutting down external MCP servers:", error);
                 }
@@ -8440,9 +8210,7 @@ Current user's request: ${currentInput}`;
                     logger.debug("[NeuroLink] Event listeners removed successfully");
                 }
                 catch (error) {
-                    const err = error instanceof Error
-                        ? error
-                        : new Error(`Event emitter cleanup error: ${String(error)}`);
+                    const err = error instanceof Error ? error : new Error(`Event emitter cleanup error: ${String(error)}`);
                     cleanupErrors.push(err);
                     logger.warn("[NeuroLink] Error removing event listeners:", error);
                 }
@@ -8455,9 +8223,7 @@ Current user's request: ${currentInput}`;
                     logger.debug("[NeuroLink] Circuit breakers cleared successfully");
                 }
                 catch (error) {
-                    const err = error instanceof Error
-                        ? error
-                        : new Error(`Circuit breaker cleanup error: ${String(error)}`);
+                    const err = error instanceof Error ? error : new Error(`Circuit breaker cleanup error: ${String(error)}`);
                     cleanupErrors.push(err);
                     logger.warn("[NeuroLink] Error clearing circuit breakers:", error);
                 }
@@ -8494,9 +8260,7 @@ Current user's request: ${currentInput}`;
                 logger.debug("[NeuroLink] Maps and caches cleared successfully");
             }
             catch (error) {
-                const err = error instanceof Error
-                    ? error
-                    : new Error(`Cache cleanup error: ${String(error)}`);
+                const err = error instanceof Error ? error : new Error(`Cache cleanup error: ${String(error)}`);
                 cleanupErrors.push(err);
                 logger.warn("[NeuroLink] Error clearing caches:", error);
             }
@@ -8522,9 +8286,7 @@ Current user's request: ${currentInput}`;
                 logger.debug("[NeuroLink] Initialization state reset successfully");
             }
             catch (error) {
-                const err = error instanceof Error
-                    ? error
-                    : new Error(`State reset error: ${String(error)}`);
+                const err = error instanceof Error ? error : new Error(`State reset error: ${String(error)}`);
                 cleanupErrors.push(err);
                 logger.warn("[NeuroLink] Error resetting state:", error);
             }
@@ -8568,11 +8330,8 @@ Current user's request: ${currentInput}`;
         }
         const compactor = new ContextCompactor({
             ...config,
-            summarizationProvider: config?.summarizationProvider ??
-                this.conversationMemoryConfig?.conversationMemory
-                    ?.summarizationProvider,
-            summarizationModel: config?.summarizationModel ??
-                this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
+            summarizationProvider: config?.summarizationProvider ?? this.conversationMemoryConfig?.conversationMemory?.summarizationProvider,
+            summarizationModel: config?.summarizationModel ?? this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
         });
         // Use actual context window to determine target, not arbitrary heuristic
         const budgetInfo = checkContextBudget({
@@ -8641,28 +8400,32 @@ Current user's request: ${currentInput}`;
     async setAuthProvider(config) {
         // Clear any pending lazy-init promise so it does not race with this call.
         this.authInitPromise = undefined;
+        await this.initializeAuthProviderFromConfig(config);
+    }
+    async initializeAuthProviderFromConfig(config) {
+        let provider;
+        let providerType;
         // Duck-type check: direct MastraAuthProvider instance
-        if ("authenticateToken" in config &&
-            typeof config.authenticateToken === "function") {
-            this.authProvider = config;
-            logger.info(`Auth provider set: ${this.authProvider.type}`);
+        if ("authenticateToken" in config && typeof config.authenticateToken === "function") {
+            provider = config;
+            providerType = provider.type;
         }
         else if ("provider" in config) {
-            this.authProvider = config.provider;
-            logger.info(`Auth provider set: ${this.authProvider.type}`);
+            provider = config.provider;
+            providerType = provider.type;
         }
         else {
             const typedConfig = config;
             const { AuthProviderFactory } = await import("./auth/AuthProviderFactory.js");
-            this.authProvider = await AuthProviderFactory.createProvider(typedConfig.type, typedConfig.config);
-            logger.info(`Auth provider created and set: ${typedConfig.type}`);
-        }
-        if (this.authProvider) {
-            this.emitter.emit("auth:provider:set", {
-                type: this.authProvider.type,
-                timestamp: Date.now(),
-            });
+            provider = await AuthProviderFactory.createProvider(typedConfig.type, typedConfig.config);
+            providerType = typedConfig.type;
         }
+        this.authProvider = provider;
+        logger.info(`Auth provider set: ${providerType}`);
+        this.emitter.emit("auth:provider:set", {
+            type: provider.type,
+            timestamp: Date.now(),
+        });
     }
     /**
      * Get the currently configured authentication provider
@@ -8679,14 +8442,17 @@ Current user's request: ${currentInput}`;
         if (this.authProvider || !this.pendingAuthConfig) {
             return;
         }
+        const pendingAuthConfig = this.pendingAuthConfig;
         this.authInitPromise ??= (async () => {
             try {
-                await this.setAuthProvider(this.pendingAuthConfig);
+                await this.initializeAuthProviderFromConfig(pendingAuthConfig);
                 this.pendingAuthConfig = undefined;
             }
-            catch (err) {
-                this.authInitPromise = undefined;
-                throw err;
+            finally {
+                if (this.authInitPromise &&
+                    (this.pendingAuthConfig === undefined || this.pendingAuthConfig === pendingAuthConfig)) {
+                    this.authInitPromise = undefined;
+                }
             }
         })();
         await this.authInitPromise;