@juspay/neurolink 9.42.0 → 9.43.0

package/dist/lib/neurolink.js

@@ -22,12 +22,13 @@ 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";
 import { repairToolPairs } from "./context/toolPairRepair.js";
 import { SYSTEM_LIMITS } from "./core/constants.js";
+import { createToolEventPayload } from "./core/toolEvents.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { AIProviderFactory } from "./core/factory.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
@@ -44,9 +45,9 @@ 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";
@@ -56,14 +57,14 @@ 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";
 // 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";
@@ -97,7 +98,9 @@ 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") ||
@@ -154,7 +157,11 @@ 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;
         }
@@ -200,7 +207,8 @@ 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;
@@ -229,14 +237,13 @@ export class NeuroLink {
         // Emit tool end event (NeuroLink format - enhanced with result/error)
         // Serialize error to string for consumer compatibility (event listeners
         // commonly check `typeof event.error === "string"`).
-        this.emitter.emit("tool:end", {
-            toolName,
+        this.emitter.emit("tool:end", createToolEventPayload(toolName, {
             responseTime: Date.now() - startTime,
             success,
             timestamp: Date.now(),
-            result: result, // Enhanced: include actual result
-            error: error ? error.message : undefined, // Emit as string, not Error object
-        });
+            result,
+            error: error ? error.message : undefined,
+        }));
     }
     // Conversation memory support
     conversationMemory;
@@ -263,19 +270,28 @@ 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;
                             }
                         }
@@ -287,10 +303,14 @@ 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 {
@@ -319,6 +339,137 @@ export class NeuroLink {
         }
         return await callback();
     }
+    createMetricsTraceContext() {
+        return {
+            traceId: crypto.randomUUID().replace(/-/g, ""),
+            parentSpanId: crypto.randomUUID().replace(/-/g, "").substring(0, 16),
+        };
+    }
+    enforceSessionBudget(maxBudgetUsd) {
+        if (maxBudgetUsd === undefined ||
+            maxBudgetUsd <= 0 ||
+            this._sessionCostUsd < maxBudgetUsd) {
+            return;
+        }
+        throw new NeuroLinkError({
+            code: "SESSION_BUDGET_EXCEEDED",
+            message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${maxBudgetUsd.toFixed(4)} limit`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: {
+                spent: this._sessionCostUsd,
+                limit: maxBudgetUsd,
+            },
+        });
+    }
+    assertInputText(text, message) {
+        if (!text || typeof text !== "string") {
+            throw new Error(message);
+        }
+    }
+    async applyAuthenticatedRequestContext(options) {
+        if (options.auth?.token) {
+            const { AuthError } = await import("./auth/errors.js");
+            await this.ensureAuthProvider();
+            if (!this.authProvider) {
+                throw AuthError.create("PROVIDER_ERROR", "No auth provider configured. Set auth in constructor or via setAuthProvider() before using auth: { token }.");
+            }
+            let authResult;
+            try {
+                authResult = await withTimeout(this.authProvider.authenticateToken(options.auth.token), 5000, AuthError.create("PROVIDER_ERROR", "Auth token validation timed out after 5000ms"));
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    "feature" in error &&
+                    error.feature === "Auth") {
+                    throw error;
+                }
+                throw AuthError.create("PROVIDER_ERROR", `Auth token validation failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!authResult.valid) {
+                throw AuthError.create("INVALID_TOKEN", authResult.error || "Token validation failed");
+            }
+            if (!authResult.user) {
+                throw AuthError.create("INVALID_TOKEN", "Token validated but no user identity returned");
+            }
+            if (!authResult.user.id) {
+                throw AuthError.create("INVALID_TOKEN", "Token validated but user identity missing required 'id' field");
+            }
+            options.context = {
+                ...(options.context || {}),
+                userId: authResult.user.id,
+                userEmail: authResult.user.email,
+                userRoles: authResult.user.roles,
+            };
+        }
+        if (!options.requestContext) {
+            return;
+        }
+        const tokenDerivedFields = options.auth?.token && this.authProvider
+            ? {
+                userId: options.context?.userId,
+                userEmail: options.context?.userEmail,
+                userRoles: options.context?.userRoles,
+            }
+            : {};
+        options.context = {
+            ...(options.context || {}),
+            ...options.requestContext,
+            ...tokenDerivedFields,
+        };
+    }
+    applyGenerateLifecycleMiddleware(options) {
+        if (!options.onFinish && !options.onError) {
+            return;
+        }
+        options.middleware = {
+            ...options.middleware,
+            middlewareConfig: {
+                ...options.middleware?.middlewareConfig,
+                lifecycle: {
+                    ...options.middleware?.middlewareConfig?.lifecycle,
+                    enabled: true,
+                    config: {
+                        ...options.middleware?.middlewareConfig?.lifecycle?.config,
+                        ...(options.onFinish !== undefined
+                            ? { onFinish: options.onFinish }
+                            : {}),
+                        ...(options.onError !== undefined
+                            ? { onError: options.onError }
+                            : {}),
+                    },
+                },
+            },
+        };
+    }
+    applyStreamLifecycleMiddleware(options) {
+        if (!options.onFinish && !options.onError && !options.onChunk) {
+            return;
+        }
+        options.middleware = {
+            ...options.middleware,
+            middlewareConfig: {
+                ...options.middleware?.middlewareConfig,
+                lifecycle: {
+                    ...options.middleware?.middlewareConfig?.lifecycle,
+                    enabled: true,
+                    config: {
+                        ...options.middleware?.middlewareConfig?.lifecycle?.config,
+                        ...(options.onFinish !== undefined
+                            ? { onFinish: options.onFinish }
+                            : {}),
+                        ...(options.onError !== undefined
+                            ? { onError: options.onError }
+                            : {}),
+                        ...(options.onChunk !== undefined
+                            ? { onChunk: options.onChunk }
+                            : {}),
+                    },
+                },
+            },
+        };
+    }
     initializeMemoryConfig() {
         const memory = this.conversationMemoryConfig?.conversationMemory?.memory;
         if (!memory?.enabled) {
@@ -424,7 +575,9 @@ 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)}`;
@@ -779,7 +932,9 @@ 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");
@@ -810,8 +965,13 @@ 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,
@@ -888,7 +1048,8 @@ 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) {
@@ -904,7 +1065,8 @@ 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()) {
@@ -978,7 +1140,9 @@ 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);
@@ -1137,7 +1301,8 @@ 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",
@@ -1152,7 +1317,9 @@ 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,
@@ -1428,7 +1595,9 @@ 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),
             });
         }
     }
@@ -1553,7 +1722,9 @@ 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
@@ -1689,7 +1860,9 @@ 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
@@ -1740,7 +1913,9 @@ 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 || "";
@@ -1832,7 +2007,8 @@ 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,
@@ -1974,7 +2150,9 @@ 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;
@@ -1993,7 +2171,9 @@ 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) {
@@ -2029,7 +2209,9 @@ 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);
@@ -2068,14 +2250,18 @@ 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
@@ -2092,7 +2278,8 @@ 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, {
@@ -2127,7 +2314,8 @@ 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 {
@@ -2279,398 +2467,313 @@ Current user's request: ${currentInput}`;
      * @since 1.0.0
      */
     async generate(optionsOrPrompt) {
-        return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, async (generateSpan) => {
-            // Set metrics trace context for parent-child span linking.
-            // The generation span will be the root (no parentSpanId).
-            // Tool spans will be children of the root span via rootSpanId.
-            const metricsTraceId = crypto.randomUUID().replace(/-/g, "");
-            const metricsRootSpanId = crypto.randomUUID().replace(/-/g, "").substring(0, 16);
-            // Scope trace context to this request via AsyncLocalStorage
-            // so concurrent generate/stream calls don't race.
-            return metricsTraceContextStorage.run({ traceId: metricsTraceId, parentSpanId: metricsRootSpanId }, async () => {
-                try {
-                    const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
-                    // Convert string prompt to full options
-                    // Shallow-copy caller's object to avoid mutating their original reference
-                    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;
-                    // Set span attributes for observability
-                    generateSpan.setAttribute("neurolink.provider", options.provider || "default");
-                    generateSpan.setAttribute("neurolink.model", options.model || "default");
-                    generateSpan.setAttribute("neurolink.input_length", typeof optionsOrPrompt === "string" ? optionsOrPrompt.length : options.input?.text?.length || 0);
-                    generateSpan.setAttribute("neurolink.has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
-                    // Validate prompt
-                    if (!options.input?.text || typeof options.input.text !== "string") {
-                        throw new Error("Input text is required and must be a non-empty string");
-                    }
-                    // Check budget limit before making API call
-                    if (options.maxBudgetUsd !== undefined &&
-                        options.maxBudgetUsd > 0 &&
-                        this._sessionCostUsd >= options.maxBudgetUsd) {
-                        throw new NeuroLinkError({
-                            code: "SESSION_BUDGET_EXCEEDED",
-                            message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
-                            category: ErrorCategory.VALIDATION,
-                            severity: ErrorSeverity.HIGH,
-                            retriable: false,
-                            context: {
-                                spent: this._sessionCostUsd,
-                                limit: options.maxBudgetUsd,
-                            },
-                        });
-                    }
-                    // Auto-inject lifecycle middleware when callbacks are provided
-                    // (must happen before workflow/PPT early returns so those paths get middleware too)
-                    if (options.onFinish || options.onError) {
-                        options.middleware = {
-                            ...options.middleware,
-                            middlewareConfig: {
-                                ...options.middleware?.middlewareConfig,
-                                lifecycle: {
-                                    ...options.middleware?.middlewareConfig?.lifecycle,
-                                    enabled: true,
-                                    config: {
-                                        ...options.middleware?.middlewareConfig?.lifecycle?.config,
-                                        ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
-                                        ...(options.onError !== undefined ? { onError: options.onError } : {}),
-                                    },
-                                },
-                            },
-                        };
-                    }
-                    // Handle per-call auth token validation
-                    if (options.auth?.token) {
-                        const { AuthError } = await import("./auth/errors.js");
-                        await this.ensureAuthProvider();
-                        if (!this.authProvider) {
-                            throw AuthError.create("PROVIDER_ERROR", "No auth provider configured. Set auth in constructor or via setAuthProvider() before using auth: { token }.");
-                        }
-                        let authResult;
-                        try {
-                            authResult = await withTimeout(this.authProvider.authenticateToken(options.auth.token), 5000, AuthError.create("PROVIDER_ERROR", "Auth token validation timed out after 5000ms"));
-                        }
-                        catch (err) {
-                            // Rethrow auth errors as-is; wrap anything else
-                            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)}`);
-                        }
-                        if (!authResult.valid) {
-                            throw AuthError.create("INVALID_TOKEN", authResult.error || "Token validation failed");
-                        }
-                        // Fail closed: token valid but no user identity is a provider bug
-                        if (!authResult.user) {
-                            throw AuthError.create("INVALID_TOKEN", "Token validated but no user identity returned");
-                        }
-                        if (!authResult.user.id) {
-                            throw AuthError.create("INVALID_TOKEN", "Token validated but user identity missing required 'id' field");
-                        }
-                        // Merge validated user into context
-                        options.context = {
-                            ...(options.context || {}),
-                            userId: authResult.user.id,
-                            userEmail: authResult.user.email,
-                            userRoles: authResult.user.roles,
-                        };
-                    }
-                    // Handle pre-validated requestContext
-                    if (options.requestContext) {
-                        // When auth token was validated, token-derived identity fields
-                        // MUST take precedence over requestContext to prevent privilege escalation.
-                        const tokenDerivedFields = options.auth?.token && this.authProvider
-                            ? {
-                                userId: options.context?.userId,
-                                userEmail: options.context?.userEmail,
-                                userRoles: options.context?.userRoles,
-                            }
-                            : {};
-                        options.context = {
-                            ...(options.context || {}),
-                            ...options.requestContext,
-                            ...tokenDerivedFields,
-                        };
-                    }
-                    // Check if workflow is requested
-                    if (options.workflow || options.workflowConfig) {
-                        return await this.generateWithWorkflow(options);
-                    }
-                    // Check if PPT output mode is requested
-                    if (options.output?.mode === "ppt") {
-                        const pptResult = await this.generateWithPPT(options);
-                        generateSpan.setAttribute("neurolink.output_length", pptResult.content?.length ?? 0);
-                        if (pptResult.analytics) {
-                            generateSpan.setAttribute("neurolink.tokens.input", pptResult.analytics.tokenUsage?.input ?? 0);
-                            generateSpan.setAttribute("neurolink.tokens.output", pptResult.analytics.tokenUsage?.output ?? 0);
-                            generateSpan.setAttribute("neurolink.cost", pptResult.analytics.cost ?? 0);
-                        }
-                        generateSpan.setStatus({ code: SpanStatusCode.OK });
-                        return pptResult;
-                    }
-                    // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
-                    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) {
-                            try {
-                                const orchestratedOptions = await this.applyOrchestration(options);
-                                logger.debug("Orchestration applied", {
-                                    originalProvider: options.provider || "auto",
-                                    orchestratedProvider: orchestratedOptions.provider,
-                                    orchestratedModel: orchestratedOptions.model,
-                                    prompt: options.input.text.substring(0, 100),
-                                });
-                                // Use orchestrated options
-                                Object.assign(options, orchestratedOptions);
-                                // Re-resolve model alias in case orchestration returned an alias
-                                if (orchestratedOptions.model) {
-                                    options.model = resolveModel(options.model, this.modelAliasConfig);
-                                }
-                            }
-                            catch (error) {
-                                logger.warn("Orchestration failed, continuing with original options", {
-                                    error: error instanceof Error ? error.message : String(error),
-                                    originalProvider: options.provider || "auto",
-                                });
-                                // Continue with original options if orchestration fails
-                            }
-                        }
-                        // Emit generation start event (NeuroLink format - keep existing)
-                        this.emitter.emit("generation:start", {
-                            provider: options.provider || "auto",
-                            timestamp: startTime,
-                        });
-                        // ADD: Bedrock-compatible response:start event
-                        this.emitter.emit("response:start");
-                        // ADD: Bedrock-compatible message event
-                        this.emitter.emit("message", `Starting ${options.provider || "auto"} text generation...`);
-                        // Process factory configuration
-                        const factoryResult = processFactoryOptions(options);
-                        // Validate factory configuration if present
-                        if (factoryResult.hasFactoryConfig && options.factoryConfig) {
-                            const validation = validateFactoryConfig(options.factoryConfig);
-                            if (!validation.isValid) {
-                                logger.warn("Invalid factory configuration detected", {
-                                    errors: validation.errors,
-                                });
-                                // Continue with warning rather than throwing - graceful degradation
-                            }
-                        }
-                        // RAG Integration: If rag config is provided, prepare the RAG search tool
-                        if (options.rag?.files?.length) {
-                            try {
-                                const { prepareRAGTool } = await import("./rag/ragIntegration.js");
-                                const ragResult = await prepareRAGTool(options.rag, options.provider);
-                                // Inject the RAG tool into the tools record
-                                if (!options.tools) {
-                                    options.tools = {};
-                                }
-                                options.tools[ragResult.toolName] = ragResult.tool;
-                                // Inject RAG-aware system prompt so the AI uses the RAG tool first
-                                const ragSystemInstruction = [
-                                    `\n\nIMPORTANT: You have a tool called "${ragResult.toolName}" that searches through`,
-                                    `${ragResult.filesLoaded} loaded document(s) containing ${ragResult.chunksIndexed} indexed chunks.`,
-                                    `ALWAYS use the "${ragResult.toolName}" tool FIRST to answer the user's question before using any other tools.`,
-                                    `This tool searches your local knowledge base of pre-loaded documents and is the primary source of truth.`,
-                                    `Do NOT use websearchGrounding or any web search tools when the answer can be found in the loaded documents.`,
-                                ].join(" ");
-                                options.systemPrompt = (options.systemPrompt || "") + ragSystemInstruction;
-                                logger.info("[RAG] Tool injected into generate()", {
-                                    toolName: ragResult.toolName,
-                                    filesLoaded: ragResult.filesLoaded,
-                                    chunksIndexed: ragResult.chunksIndexed,
-                                });
-                            }
-                            catch (error) {
-                                logger.warn("[RAG] Failed to prepare RAG tool, continuing without RAG", {
-                                    error: error instanceof Error ? error.message : String(error),
-                                });
-                            }
-                        }
-                        // Memory retrieval for generate path
-                        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)");
-                            }
-                            catch (error) {
-                                logger.warn("Memory retrieval failed (generate):", error);
-                            }
-                        }
-                        // 🔧 CRITICAL FIX: Convert to TextGenerationOptions while preserving the input object for multimodal support
-                        const baseOptions = {
-                            prompt: options.input.text,
-                            provider: options.provider,
-                            model: options.model,
-                            temperature: options.temperature,
-                            maxTokens: options.maxTokens,
-                            systemPrompt: options.systemPrompt,
-                            schema: options.schema,
-                            output: options.output,
-                            tools: options.tools, // Includes RAG tools if rag config was provided
-                            disableTools: options.disableTools,
-                            toolFilter: options.toolFilter,
-                            excludeTools: options.excludeTools,
-                            maxSteps: options.maxSteps,
-                            toolChoice: options.toolChoice,
-                            prepareStep: options.prepareStep,
-                            enableAnalytics: options.enableAnalytics,
-                            enableEvaluation: options.enableEvaluation,
-                            context: options.context,
-                            evaluationDomain: options.evaluationDomain,
-                            toolUsageContext: options.toolUsageContext,
-                            input: options.input, // This includes text, images, and content arrays
-                            region: options.region,
-                            tts: options.tts,
-                            fileRegistry: this.fileRegistry,
-                            abortSignal: options.abortSignal,
-                            skipToolPromptInjection: options.skipToolPromptInjection,
-                            middleware: options.middleware,
-                            // Pass through conversation messages for task continuation and external callers
-                            conversationMessages: options.conversationMessages,
-                        };
-                        // Auto-map top-level sessionId/userId to context for convenience
-                        // Tests and users may pass sessionId/userId as top-level options
-                        const extraContext = options;
-                        if (extraContext.sessionId || extraContext.userId) {
-                            baseOptions.context = {
-                                ...baseOptions.context,
-                                ...(extraContext.sessionId && !baseOptions.context?.sessionId
-                                    ? { sessionId: extraContext.sessionId }
-                                    : {}),
-                                ...(extraContext.userId && !baseOptions.context?.userId
-                                    ? { userId: extraContext.userId }
-                                    : {}),
-                            };
-                        }
-                        // Apply factory enhancement using centralized utilities
-                        const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
-                        // Pass conversation memory config if available
-                        if (this.conversationMemory) {
-                            textOptions.conversationMemoryConfig = this.conversationMemory.config;
-                            // Include original prompt for context summarization
-                            textOptions.originalPrompt = originalPrompt;
-                        }
-                        // Detect and execute domain-specific tools
-                        const { toolResults, enhancedPrompt } = await this.detectAndExecuteTools(textOptions.prompt || options.input.text, factoryResult.domainType);
-                        // Update prompt with tool results if available
-                        if (enhancedPrompt !== textOptions.prompt) {
-                            textOptions.prompt = enhancedPrompt;
-                            logger.debug("Enhanced prompt with tool results", {
-                                originalLength: options.input.text.length,
-                                enhancedLength: enhancedPrompt.length,
-                                toolResults: toolResults.length,
-                            });
-                        }
-                        const textResult = await this.generateTextInternal(textOptions);
-                        // Emit generation completion event (NeuroLink format - enhanced with content)
-                        this.emitter.emit("generation:end", {
-                            provider: textResult.provider,
-                            responseTime: Date.now() - startTime,
-                            toolsUsed: textResult.toolsUsed,
-                            timestamp: Date.now(),
-                            result: textResult, // Enhanced: include full result
-                            prompt: options.input?.text || options.prompt,
-                            temperature: textOptions.temperature,
-                            maxTokens: textOptions.maxTokens,
-                        });
-                        // ADD: Bedrock-compatible response:end event with content
-                        this.emitter.emit("response:end", textResult.content || "");
-                        // ADD: Bedrock-compatible message event
-                        this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
-                        // Convert back to GenerateResult
-                        const generateResult = {
-                            content: textResult.content,
-                            finishReason: textResult.finishReason,
-                            provider: textResult.provider,
-                            model: textResult.model,
-                            usage: textResult.usage
-                                ? {
-                                    input: textResult.usage.input || 0,
-                                    output: textResult.usage.output || 0,
-                                    total: textResult.usage.total || 0,
-                                }
-                                : undefined,
-                            responseTime: textResult.responseTime,
-                            toolsUsed: textResult.toolsUsed,
-                            toolExecutions: transformToolExecutions(textResult.toolExecutions),
-                            enhancedWithTools: textResult.enhancedWithTools,
-                            availableTools: transformAvailableTools(textResult.availableTools),
-                            analytics: textResult.analytics,
-                            // CRITICAL FIX: Include imageOutput for image generation models
-                            imageOutput: textResult.imageOutput,
-                            evaluation: textResult.evaluation
-                                ? {
-                                    ...textResult.evaluation,
-                                    isOffTopic: textResult.evaluation.isOffTopic ?? false,
-                                    alertSeverity: textResult.evaluation.alertSeverity ?? "none",
-                                    reasoning: textResult.evaluation.reasoning ?? "No evaluation provided",
-                                    evaluationModel: textResult.evaluation.evaluationModel ?? "unknown",
-                                    evaluationTime: textResult.evaluation.evaluationTime ?? Date.now(),
-                                    evaluationDomain: textResult.evaluation.evaluationDomain ??
-                                        textOptions.evaluationDomain ??
-                                        factoryResult.domainType,
-                                }
-                                : undefined,
-                            audio: textResult.audio,
-                            video: textResult.video,
-                            ppt: textResult.ppt,
-                            // NL-007: Copy retry metadata from MCP generation path
-                            ...(textResult.retries && { retries: textResult.retries }),
-                        };
-                        // Accumulate session cost for budget tracking
-                        if (generateResult.analytics?.cost && generateResult.analytics.cost > 0) {
-                            this._sessionCostUsd += generateResult.analytics.cost;
-                        }
-                        this.scheduleGenerateMemoryStorage(options, originalPrompt, generateResult);
-                        // Set completion span attributes
-                        generateSpan.setAttribute("neurolink.output_length", generateResult.content?.length || 0);
-                        generateSpan.setAttribute("neurolink.tokens.input", generateResult.usage?.input || 0);
-                        generateSpan.setAttribute("neurolink.tokens.output", generateResult.usage?.output || 0);
-                        generateSpan.setAttribute("neurolink.finish_reason", generateResult.finishReason || "unknown");
-                        generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
-                        generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
-                        // NL-007: Expose retry count in OTel span
-                        generateSpan.setAttribute("generate.retry_count", generateResult.retries?.count || 0);
-                        generateSpan.setStatus({ code: SpanStatusCode.OK });
-                        return generateResult;
-                    });
+        return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan));
+    }
+    async executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan) {
+        return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeGenerateRequest(optionsOrPrompt, generateSpan));
+    }
+    async executeGenerateRequest(optionsOrPrompt, generateSpan) {
+        try {
+            const { options, originalPrompt } = await this.prepareGenerateRequest(optionsOrPrompt, generateSpan);
+            const earlyResult = await this.maybeHandleEarlyGenerateResult(options, generateSpan);
+            if (earlyResult) {
+                generateSpan.setStatus({ code: SpanStatusCode.OK });
+                return earlyResult;
+            }
+            const result = await this.setLangfuseContextFromOptions(options, () => this.runStandardGenerateRequest(options, originalPrompt, generateSpan));
+            generateSpan.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            generateSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            this.emitGenerateErrorEvent(optionsOrPrompt, error);
+            throw error;
+        }
+        finally {
+            this._disableToolCacheForCurrentRequest = false;
+            generateSpan.end();
+        }
+    }
+    async prepareGenerateRequest(optionsOrPrompt, generateSpan) {
+        const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
+        const options = typeof optionsOrPrompt === "string"
+            ? { input: { text: optionsOrPrompt } }
+            : { ...optionsOrPrompt };
+        options.model = resolveModel(options.model, this.modelAliasConfig);
+        this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
+        generateSpan.setAttribute("neurolink.provider", options.provider || "default");
+        generateSpan.setAttribute("neurolink.model", options.model || "default");
+        generateSpan.setAttribute("neurolink.input_length", typeof optionsOrPrompt === "string"
+            ? optionsOrPrompt.length
+            : options.input?.text?.length || 0);
+        generateSpan.setAttribute("neurolink.has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
+        this.assertInputText(options.input?.text, "Input text is required and must be a non-empty string");
+        this.enforceSessionBudget(options.maxBudgetUsd);
+        this.applyGenerateLifecycleMiddleware(options);
+        await this.applyAuthenticatedRequestContext(options);
+        return { options, originalPrompt };
+    }
+    async maybeHandleEarlyGenerateResult(options, generateSpan) {
+        if (options.workflow || options.workflowConfig) {
+            return this.generateWithWorkflow(options);
+        }
+        if (options.output?.mode !== "ppt") {
+            return null;
+        }
+        const pptResult = await this.generateWithPPT(options);
+        generateSpan.setAttribute("neurolink.output_length", pptResult.content?.length ?? 0);
+        if (pptResult.analytics) {
+            generateSpan.setAttribute("neurolink.tokens.input", pptResult.analytics.tokenUsage?.input ?? 0);
+            generateSpan.setAttribute("neurolink.tokens.output", pptResult.analytics.tokenUsage?.output ?? 0);
+            generateSpan.setAttribute("neurolink.cost", pptResult.analytics.cost ?? 0);
+        }
+        generateSpan.setStatus({ code: SpanStatusCode.OK });
+        return pptResult;
+    }
+    async runStandardGenerateRequest(options, originalPrompt, generateSpan) {
+        const startTime = Date.now();
+        await this.maybeApplyGenerateOrchestration(options);
+        this.emitter.emit("generation:start", {
+            provider: options.provider || "auto",
+            timestamp: startTime,
+        });
+        this.emitter.emit("response:start");
+        this.emitter.emit("message", `Starting ${options.provider || "auto"} text generation...`);
+        const factoryResult = processFactoryOptions(options);
+        if (factoryResult.hasFactoryConfig && options.factoryConfig) {
+            const validation = validateFactoryConfig(options.factoryConfig);
+            if (!validation.isValid) {
+                logger.warn("Invalid factory configuration detected", {
+                    errors: validation.errors,
+                });
+            }
+        }
+        await this.prepareGenerateAugmentations(options);
+        const textOptions = await this.buildGenerateTextOptions(options, originalPrompt, factoryResult);
+        const textResult = await this.generateTextInternal(textOptions);
+        return this.finalizeGenerateRequestResult({
+            generateSpan,
+            options,
+            textOptions,
+            textResult,
+            factoryResult,
+            originalPrompt,
+            startTime,
+        });
+    }
+    async maybeApplyGenerateOrchestration(options) {
+        if (!this.enableOrchestration || options.provider || options.model) {
+            return;
+        }
+        try {
+            const orchestratedOptions = await this.applyOrchestration(options);
+            logger.debug("Orchestration applied", {
+                originalProvider: options.provider || "auto",
+                orchestratedProvider: orchestratedOptions.provider,
+                orchestratedModel: orchestratedOptions.model,
+                prompt: options.input.text.substring(0, 100),
+            });
+            Object.assign(options, orchestratedOptions);
+            if (orchestratedOptions.model) {
+                options.model = resolveModel(options.model, this.modelAliasConfig);
+            }
+        }
+        catch (error) {
+            logger.warn("Orchestration failed, continuing with original options", {
+                error: error instanceof Error ? error.message : String(error),
+                originalProvider: options.provider || "auto",
+            });
+        }
+    }
+    async prepareGenerateAugmentations(options) {
+        if (options.rag?.files?.length) {
+            try {
+                const { prepareRAGTool } = await import("./rag/ragIntegration.js");
+                const ragResult = await prepareRAGTool(options.rag, options.provider);
+                if (!options.tools) {
+                    options.tools = {};
                 }
-                catch (error) {
-                    generateSpan.setStatus({
-                        code: SpanStatusCode.ERROR,
-                        message: error instanceof Error ? error.message : String(error),
-                    });
-                    // Emit generation:end on error so metrics listeners still record the failure.
-                    // Note: variables declared inside try blocks are not accessible in error
-                    // handlers, so we extract what we can from the original input.
-                    const errProvider = typeof optionsOrPrompt === "object"
-                        ? optionsOrPrompt.provider || "unknown"
-                        : "unknown";
-                    const errModel = typeof optionsOrPrompt === "object" ? optionsOrPrompt.model || "unknown" : "unknown";
-                    try {
-                        this.emitter.emit("generation:end", {
-                            provider: errProvider,
-                            model: errModel,
-                            responseTime: 0,
-                            error: error instanceof Error ? error.message : String(error),
-                            success: false,
-                        });
-                    }
-                    catch (emitError) {
-                        void emitError; // non-blocking — error event emission is best-effort
-                    }
-                    throw error;
+                options.tools[ragResult.toolName] =
+                    ragResult.tool;
+                options.systemPrompt =
+                    (options.systemPrompt || "") +
+                        [
+                            `\n\nIMPORTANT: You have a tool called "${ragResult.toolName}" that searches through`,
+                            `${ragResult.filesLoaded} loaded document(s) containing ${ragResult.chunksIndexed} indexed chunks.`,
+                            `ALWAYS use the "${ragResult.toolName}" tool FIRST to answer the user's question before using any other tools.`,
+                            `This tool searches your local knowledge base of pre-loaded documents and is the primary source of truth.`,
+                            `Do NOT use websearchGrounding or any web search tools when the answer can be found in the loaded documents.`,
+                        ].join(" ");
+                logger.info("[RAG] Tool injected into generate()", {
+                    toolName: ragResult.toolName,
+                    filesLoaded: ragResult.filesLoaded,
+                    chunksIndexed: ragResult.chunksIndexed,
+                });
+            }
+            catch (error) {
+                logger.warn("[RAG] Failed to prepare RAG tool, continuing without RAG", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        if (!this.shouldReadMemory(options.memory, options.context?.userId) ||
+            !options.context?.userId) {
+            return;
+        }
+        try {
+            options.input.text = await this.retrieveMemory(options.input.text, options.context.userId, options.memory?.additionalUsers);
+            logger.debug("Memory retrieval successful (generate)");
+        }
+        catch (error) {
+            logger.warn("Memory retrieval failed (generate):", error);
+        }
+    }
+    async buildGenerateTextOptions(options, originalPrompt, factoryResult) {
+        const baseOptions = {
+            prompt: options.input.text,
+            provider: options.provider,
+            model: options.model,
+            temperature: options.temperature,
+            maxTokens: options.maxTokens,
+            systemPrompt: options.systemPrompt,
+            schema: options.schema,
+            output: options.output,
+            tools: options.tools,
+            disableTools: options.disableTools,
+            toolFilter: options.toolFilter,
+            excludeTools: options.excludeTools,
+            maxSteps: options.maxSteps,
+            toolChoice: options.toolChoice,
+            prepareStep: options.prepareStep,
+            enableAnalytics: options.enableAnalytics,
+            enableEvaluation: options.enableEvaluation,
+            context: options.context,
+            evaluationDomain: options.evaluationDomain,
+            toolUsageContext: options.toolUsageContext,
+            input: options.input,
+            region: options.region,
+            tts: options.tts,
+            fileRegistry: this.fileRegistry,
+            abortSignal: options.abortSignal,
+            skipToolPromptInjection: options.skipToolPromptInjection,
+            middleware: options.middleware,
+            conversationMessages: options.conversationMessages,
+        };
+        const extraContext = options;
+        if (extraContext.sessionId || extraContext.userId) {
+            baseOptions.context = {
+                ...baseOptions.context,
+                ...(extraContext.sessionId && !baseOptions.context?.sessionId
+                    ? { sessionId: extraContext.sessionId }
+                    : {}),
+                ...(extraContext.userId && !baseOptions.context?.userId
+                    ? { userId: extraContext.userId }
+                    : {}),
+            };
+        }
+        const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
+        if (this.conversationMemory) {
+            textOptions.conversationMemoryConfig = this.conversationMemory.config;
+            textOptions.originalPrompt = originalPrompt;
+        }
+        const { toolResults, enhancedPrompt } = await this.detectAndExecuteTools(textOptions.prompt || options.input.text, factoryResult.domainType);
+        if (enhancedPrompt !== textOptions.prompt) {
+            textOptions.prompt = enhancedPrompt;
+            logger.debug("Enhanced prompt with tool results", {
+                originalLength: options.input.text.length,
+                enhancedLength: enhancedPrompt.length,
+                toolResults: toolResults.length,
+            });
+        }
+        return textOptions;
+    }
+    finalizeGenerateRequestResult(params) {
+        const { generateSpan, options, textOptions, textResult, factoryResult, originalPrompt, startTime, } = params;
+        this.emitter.emit("generation:end", {
+            provider: textResult.provider,
+            responseTime: Date.now() - startTime,
+            toolsUsed: textResult.toolsUsed,
+            timestamp: Date.now(),
+            result: textResult,
+            prompt: options.input?.text || options.prompt,
+            temperature: textOptions.temperature,
+            maxTokens: textOptions.maxTokens,
+        });
+        this.emitter.emit("response:end", textResult.content || "");
+        this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
+        const generateResult = {
+            content: textResult.content,
+            finishReason: textResult.finishReason,
+            provider: textResult.provider,
+            model: textResult.model,
+            usage: textResult.usage
+                ? {
+                    input: textResult.usage.input || 0,
+                    output: textResult.usage.output || 0,
+                    total: textResult.usage.total || 0,
                 }
-                finally {
-                    this._disableToolCacheForCurrentRequest = false;
-                    generateSpan.end();
+                : undefined,
+            responseTime: textResult.responseTime,
+            toolsUsed: textResult.toolsUsed,
+            toolExecutions: transformToolExecutions(textResult.toolExecutions),
+            enhancedWithTools: textResult.enhancedWithTools,
+            availableTools: transformAvailableTools(textResult.availableTools),
+            analytics: textResult.analytics,
+            imageOutput: textResult.imageOutput,
+            evaluation: textResult.evaluation
+                ? {
+                    ...textResult.evaluation,
+                    isOffTopic: textResult.evaluation.isOffTopic ?? false,
+                    alertSeverity: textResult.evaluation.alertSeverity ?? "none",
+                    reasoning: textResult.evaluation.reasoning ?? "No evaluation provided",
+                    evaluationModel: textResult.evaluation.evaluationModel ?? "unknown",
+                    evaluationTime: textResult.evaluation.evaluationTime ?? Date.now(),
+                    evaluationDomain: textResult.evaluation.evaluationDomain ??
+                        textOptions.evaluationDomain ??
+                        factoryResult.domainType,
                 }
-            }); // end metricsTraceContextStorage.run
-        });
+                : undefined,
+            audio: textResult.audio,
+            video: textResult.video,
+            ppt: textResult.ppt,
+            ...(textResult.retries && { retries: textResult.retries }),
+        };
+        if (generateResult.analytics?.cost && generateResult.analytics.cost > 0) {
+            this._sessionCostUsd += generateResult.analytics.cost;
+        }
+        this.scheduleGenerateMemoryStorage(options, originalPrompt, generateResult);
+        generateSpan.setAttribute("neurolink.output_length", generateResult.content?.length || 0);
+        generateSpan.setAttribute("neurolink.tokens.input", generateResult.usage?.input || 0);
+        generateSpan.setAttribute("neurolink.tokens.output", generateResult.usage?.output || 0);
+        generateSpan.setAttribute("neurolink.finish_reason", generateResult.finishReason || "unknown");
+        generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
+        generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
+        generateSpan.setAttribute("generate.retry_count", generateResult.retries?.count || 0);
+        generateSpan.setStatus({ code: SpanStatusCode.OK });
+        return generateResult;
+    }
+    emitGenerateErrorEvent(optionsOrPrompt, error) {
+        const errProvider = typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt.provider || "unknown"
+            : "unknown";
+        const errModel = typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt.model || "unknown"
+            : "unknown";
+        try {
+            this.emitter.emit("generation:end", {
+                provider: errProvider,
+                model: errModel,
+                responseTime: 0,
+                error: error instanceof Error ? error.message : String(error),
+                success: false,
+            });
+        }
+        catch (emitError) {
+            void emitError;
+        }
     }
     /**
      * Schedule non-blocking memory storage after generate completes.
@@ -2751,8 +2854,11 @@ 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,
@@ -2762,8 +2868,10 @@ 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
                 ? {
@@ -2845,8 +2953,11 @@ 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,
@@ -2970,7 +3081,9 @@ 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
@@ -2989,239 +3102,247 @@ Current user's request: ${currentInput}`;
      * 5. Store conversation turn for future context
      */
     async generateTextInternal(options) {
-        return tracers.sdk.startActiveSpan("neurolink.generateTextInternal", { kind: SpanKind.INTERNAL }, async (internalSpan) => {
-            try {
-                const generateInternalId = `generate-internal-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-                const existingRequestId = options.context?.requestId;
-                const requestId = typeof existingRequestId === "string" && existingRequestId
-                    ? existingRequestId
-                    : `req-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-                options.context = { ...options.context, requestId };
-                const generateInternalStartTime = Date.now();
-                const generateInternalHrTimeStart = process.hrtime.bigint();
-                const functionTag = "NeuroLink.generateTextInternal";
-                // Set span attributes for internal generation
-                internalSpan.setAttribute("neurolink.request_id", requestId);
-                internalSpan.setAttribute("neurolink.has_conversation_memory", !!this.conversationMemory);
-                internalSpan.setAttribute("neurolink.provider", options.provider || "auto");
-                internalSpan.setAttribute("neurolink.model", options.model || "default");
-                this.logGenerateTextInternalStart(generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, options, functionTag);
-                this.emitGenerationStartEvents(options);
-                try {
-                    await this.initializeConversationMemoryForGeneration(generateInternalId, generateInternalStartTime, generateInternalHrTimeStart);
-                    const mcpResult = await this.attemptMCPGeneration(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag);
-                    if (mcpResult) {
-                        logger.info(`[NeuroLink.generateTextInternal] generate() - COMPLETE SUCCESS (MCP path)`, {
-                            provider: mcpResult.provider,
-                            model: mcpResult.model,
-                            responseTimeMs: Date.now() - generateInternalStartTime,
-                            tokensUsed: mcpResult.usage?.total || 0,
-                            toolsUsed: mcpResult.toolsUsed?.length || 0,
-                            ...(mcpResult.usage?.cacheCreationTokens !== undefined && {
-                                cacheCreationTokens: mcpResult.usage.cacheCreationTokens,
-                            }),
-                            ...(mcpResult.usage?.cacheReadTokens !== undefined && {
-                                cacheReadTokens: mcpResult.usage.cacheReadTokens,
-                            }),
-                            ...(mcpResult.usage?.cacheSavingsPercent !== undefined && {
-                                cacheSavingsPercent: mcpResult.usage.cacheSavingsPercent,
-                            }),
-                        });
-                        {
-                            const memStoreStart = Date.now();
-                            try {
-                                await storeConversationTurn(this.conversationMemory, options, mcpResult, new Date(generateInternalStartTime), requestId);
-                                this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "mcp" }, Date.now() - memStoreStart, SpanStatus.OK);
-                            }
-                            catch (memErr) {
-                                this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "mcp" }, Date.now() - memStoreStart, SpanStatus.ERROR, memErr instanceof Error ? memErr.message : String(memErr));
-                            }
-                        }
-                        this.emitter.emit("response:end", mcpResult.content || "");
-                        internalSpan.setAttribute("neurolink.path", "mcp");
-                        internalSpan.setAttribute("neurolink.tokens.input", mcpResult.usage?.input || 0);
-                        internalSpan.setAttribute("neurolink.tokens.output", mcpResult.usage?.output || 0);
-                        internalSpan.setAttribute("neurolink.result_provider", mcpResult.provider || "unknown");
-                        internalSpan.setStatus({ code: SpanStatusCode.OK });
-                        return mcpResult;
-                    }
-                    if (options.abortSignal?.aborted) {
-                        throw new DOMException("The operation was aborted", "AbortError");
-                    }
-                    // Save original messages for smart overflow recovery (Solution 6)
-                    // directProviderGeneration may compact messages; if provider still rejects,
-                    // 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;
-                    }
-                    const directResult = await this.directProviderGeneration(options);
-                    logger.debug(`[${functionTag}] Direct generation successful`);
-                    logger.info(`[NeuroLink.generateTextInternal] generate() - COMPLETE SUCCESS`, {
-                        provider: directResult.provider,
-                        model: directResult.model,
-                        responseTimeMs: Date.now() - generateInternalStartTime,
-                        tokensUsed: directResult.usage?.total || 0,
-                        toolsUsed: directResult.toolsUsed?.length || 0,
-                        ...(directResult.usage?.cacheCreationTokens !== undefined && {
-                            cacheCreationTokens: directResult.usage.cacheCreationTokens,
-                        }),
-                        ...(directResult.usage?.cacheReadTokens !== undefined && {
-                            cacheReadTokens: directResult.usage.cacheReadTokens,
-                        }),
-                        ...(directResult.usage?.cacheSavingsPercent !== undefined && {
-                            cacheSavingsPercent: directResult.usage.cacheSavingsPercent,
-                        }),
-                    });
-                    {
-                        const memStoreStart = Date.now();
-                        try {
-                            await storeConversationTurn(this.conversationMemory, options, directResult, new Date(generateInternalStartTime), requestId);
-                            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "direct" }, Date.now() - memStoreStart, SpanStatus.OK);
-                        }
-                        catch (memErr) {
-                            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "direct" }, Date.now() - memStoreStart, SpanStatus.ERROR, memErr instanceof Error ? memErr.message : String(memErr));
-                        }
-                    }
-                    this.emitter.emit("response:end", directResult.content || "");
-                    this.emitter.emit("message", `Text generation completed successfully`);
-                    internalSpan.setAttribute("neurolink.path", "direct");
-                    internalSpan.setAttribute("neurolink.tokens.input", directResult.usage?.input || 0);
-                    internalSpan.setAttribute("neurolink.tokens.output", directResult.usage?.output || 0);
-                    internalSpan.setAttribute("neurolink.result_provider", directResult.provider || "unknown");
-                    internalSpan.setStatus({ code: SpanStatusCode.OK });
-                    return directResult;
-                }
-                catch (error) {
-                    // Check if this is a context overflow error - attempt recovery
-                    if (isContextOverflowError(error) && this.conversationMemory) {
-                        logger.warn(`[${functionTag}] Context overflow detected by provider, attempting smart recovery`, {
-                            error: error instanceof Error ? error.message : String(error),
-                            overflowProvider: getContextOverflowProvider(error),
-                        });
-                        try {
-                            // 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));
-                            // IMPROVEMENT 3: Calculate precise reduction target
-                            const recoveryBudget = checkContextBudget({
-                                provider: options.provider || "openai",
-                                model: options.model,
-                                maxTokens: options.maxTokens,
-                                currentPrompt: options.prompt,
-                                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;
-                            // 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 compactor = new ContextCompactor({
-                                enableSummarize: false, // Skip LLM call for recovery (speed)
-                                enablePrune: true,
-                                enableDeduplicate: true,
-                                enableTruncate: true,
-                                truncationFraction: Math.min(0.9, requiredReduction + 0.15),
-                            });
-                            const compactionResult = await compactor.compact(originalMessages, compactionTarget, undefined, options.context?.requestId);
-                            if (compactionResult.compacted) {
-                                const repairedResult = repairToolPairs(compactionResult.messages);
-                                // IMPROVEMENT 5: Verify BEFORE retrying
-                                const verifyBudget = checkContextBudget({
-                                    provider: options.provider || "openai",
-                                    model: options.model,
-                                    maxTokens: options.maxTokens,
-                                    systemPrompt: options.systemPrompt,
-                                    currentPrompt: options.prompt,
-                                    conversationMessages: repairedResult.messages,
-                                });
-                                if (!verifyBudget.withinBudget) {
-                                    logger.error(`[${functionTag}] Recovery compaction insufficient, aborting retry`, {
-                                        estimatedTokens: verifyBudget.estimatedInputTokens,
-                                        availableTokens: verifyBudget.availableInputTokens,
-                                    });
-                                    throw new ContextBudgetExceededError(`Context overflow recovery failed. Provider rejected at ~${actualTokens} tokens, ` +
-                                        `recovery compaction achieved ${compactionResult.tokensAfter} tokens ` +
-                                        `but budget is ${budgetTokens} tokens.`, {
-                                        estimatedTokens: compactionResult.tokensAfter,
-                                        availableTokens: budgetTokens,
-                                        stagesUsed: compactionResult.stagesUsed,
-                                        breakdown: verifyBudget.breakdown,
-                                    });
-                                }
-                                logger.info(`[${functionTag}] Smart recovery verified, retrying generation`, {
-                                    tokensSaved: compactionResult.tokensSaved,
-                                    compactionTarget,
-                                    verifiedTokens: verifyBudget.estimatedInputTokens,
-                                    verifiedBudget: verifyBudget.availableInputTokens,
-                                });
-                                // Single verified retry
-                                return await this.directProviderGeneration({
-                                    ...options,
-                                    conversationMessages: repairedResult.messages,
-                                });
-                            }
-                        }
-                        catch (retryError) {
-                            // If the retry error is our own ContextBudgetExceededError, re-throw it
-                            if (retryError instanceof ContextBudgetExceededError) {
-                                throw retryError;
-                            }
-                            logger.error(`[${functionTag}] Recovery attempt failed`, {
-                                error: retryError instanceof Error ? retryError.message : String(retryError),
-                            });
-                        }
-                    }
-                    // If the generation was aborted (e.g., coding task short-circuit via AbortController),
-                    // still store the conversation turn so that:
-                    // 1. The Redis conversation entry is created (if first turn)
-                    // 2. setImmediate triggers generateConversationTitle() for the session
-                    // 3. The caller's syncTitleFromRedis() can find the SDK-generated title
-                    if (isAbortError(error)) {
-                        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",
-                        });
-                        try {
-                            const abortedResult = {
-                                content: "[generation was interrupted]",
-                                provider: options.provider || "unknown",
-                                model: options.model || "unknown",
-                                responseTime: Date.now() - generateInternalStartTime,
-                            };
-                            await withTimeout(storeConversationTurn(this.conversationMemory, options, abortedResult, new Date(generateInternalStartTime), requestId), 5000);
-                        }
-                        catch (storeError) {
-                            logger.warn(`[${functionTag}] Failed to store conversation turn after abort`, {
-                                error: storeError instanceof Error ? storeError.message : String(storeError),
-                            });
-                        }
-                    }
-                    else {
-                        logger.error(`[${functionTag}] All generation methods failed`, {
-                            error: error instanceof Error ? error.message : String(error),
-                        });
-                    }
-                    this.emitter.emit("response:end", "");
-                    this.emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
-                    throw error;
-                }
-            }
-            catch (spanError) {
-                internalSpan.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: spanError instanceof Error ? spanError.message : String(spanError),
+        return tracers.sdk.startActiveSpan("neurolink.generateTextInternal", { kind: SpanKind.INTERNAL }, (internalSpan) => this.executeGenerateTextInternalWithSpan(options, internalSpan));
+    }
+    async executeGenerateTextInternalWithSpan(options, internalSpan) {
+        try {
+            const context = this.initializeGenerateTextInternalContext(options);
+            internalSpan.setAttribute("neurolink.request_id", context.requestId);
+            internalSpan.setAttribute("neurolink.has_conversation_memory", !!this.conversationMemory);
+            internalSpan.setAttribute("neurolink.provider", options.provider || "auto");
+            internalSpan.setAttribute("neurolink.model", options.model || "default");
+            this.logGenerateTextInternalStart(context.generateInternalId, context.generateInternalStartTime, context.generateInternalHrTimeStart, options, context.functionTag);
+            this.emitGenerationStartEvents(options);
+            return await this.runGenerateTextInternalFlow(options, internalSpan, context);
+        }
+        catch (error) {
+            internalSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            internalSpan.end();
+        }
+    }
+    initializeGenerateTextInternalContext(options) {
+        const generateInternalId = `generate-internal-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+        const existingRequestId = options.context?.requestId;
+        const requestId = typeof existingRequestId === "string" && existingRequestId
+            ? existingRequestId
+            : `req-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+        options.context = { ...options.context, requestId };
+        return {
+            generateInternalId,
+            generateInternalStartTime: Date.now(),
+            generateInternalHrTimeStart: process.hrtime.bigint(),
+            functionTag: "NeuroLink.generateTextInternal",
+            requestId,
+        };
+    }
+    async runGenerateTextInternalFlow(options, internalSpan, context) {
+        try {
+            await this.initializeConversationMemoryForGeneration(context.generateInternalId, context.generateInternalStartTime, context.generateInternalHrTimeStart);
+            const mcpResult = await this.attemptMCPGeneration(options, context.generateInternalId, context.generateInternalStartTime, context.generateInternalHrTimeStart, context.functionTag);
+            if (mcpResult) {
+                return this.finalizeGenerateTextInternalResult({
+                    path: "mcp",
+                    result: mcpResult,
+                    options,
+                    internalSpan,
+                    requestId: context.requestId,
+                    startTime: context.generateInternalStartTime,
                 });
-                throw spanError;
             }
-            finally {
-                internalSpan.end();
+            if (options.abortSignal?.aborted) {
+                throw new DOMException("The operation was aborted", "AbortError");
+            }
+            await this.captureOriginalConversationMessagesForRecovery(options);
+            const directResult = await this.directProviderGeneration(options);
+            logger.debug(`[${context.functionTag}] Direct generation successful`);
+            return this.finalizeGenerateTextInternalResult({
+                path: "direct",
+                result: directResult,
+                options,
+                internalSpan,
+                requestId: context.requestId,
+                startTime: context.generateInternalStartTime,
+            });
+        }
+        catch (error) {
+            const recoveredResult = await this.handleGenerateTextInternalFailure(options, context, error);
+            if (recoveredResult) {
+                return recoveredResult;
             }
+            throw error;
+        }
+    }
+    async captureOriginalConversationMessagesForRecovery(options) {
+        if (!this.conversationMemory) {
+            return;
+        }
+        const originalMessages = await getConversationMessages(this.conversationMemory, options);
+        options._originalConversationMessages = originalMessages
+            ? [...originalMessages]
+            : undefined;
+    }
+    async finalizeGenerateTextInternalResult(params) {
+        const { path, result, options, internalSpan, requestId, startTime } = params;
+        logger.info(`[NeuroLink.generateTextInternal] generate() - COMPLETE SUCCESS${path === "mcp" ? " (MCP path)" : ""}`, {
+            provider: result.provider,
+            model: result.model,
+            responseTimeMs: Date.now() - startTime,
+            tokensUsed: result.usage?.total || 0,
+            toolsUsed: result.toolsUsed?.length || 0,
+            ...(result.usage?.cacheCreationTokens !== undefined && {
+                cacheCreationTokens: result.usage.cacheCreationTokens,
+            }),
+            ...(result.usage?.cacheReadTokens !== undefined && {
+                cacheReadTokens: result.usage.cacheReadTokens,
+            }),
+            ...(result.usage?.cacheSavingsPercent !== undefined && {
+                cacheSavingsPercent: result.usage.cacheSavingsPercent,
+            }),
         });
+        const memStoreStart = Date.now();
+        try {
+            await storeConversationTurn(this.conversationMemory, options, result, new Date(startTime), requestId);
+            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": path }, Date.now() - memStoreStart, SpanStatus.OK);
+        }
+        catch (memoryError) {
+            this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": path }, Date.now() - memStoreStart, SpanStatus.ERROR, memoryError instanceof Error
+                ? memoryError.message
+                : String(memoryError));
+        }
+        this.emitter.emit("response:end", result.content || "");
+        if (path === "direct") {
+            this.emitter.emit("message", "Text generation completed successfully");
+        }
+        internalSpan.setAttribute("neurolink.path", path);
+        internalSpan.setAttribute("neurolink.tokens.input", result.usage?.input || 0);
+        internalSpan.setAttribute("neurolink.tokens.output", result.usage?.output || 0);
+        internalSpan.setAttribute("neurolink.result_provider", result.provider || "unknown");
+        internalSpan.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    async handleGenerateTextInternalFailure(options, context, error) {
+        const recoveredResult = await this.tryRecoverGenerateTextOverflow(options, context.functionTag, error);
+        if (recoveredResult) {
+            return recoveredResult;
+        }
+        if (isAbortError(error)) {
+            logger.info(`[${context.functionTag}] Generation aborted — storing conversation turn for title generation`, {
+                hasMemory: !!this.conversationMemory,
+                memoryType: this.conversationMemory?.constructor?.name || "NONE",
+                sessionId: options.context?.sessionId ||
+                    "unknown",
+            });
+            try {
+                const abortedResult = {
+                    content: "[generation was interrupted]",
+                    provider: options.provider || "unknown",
+                    model: options.model || "unknown",
+                    responseTime: Date.now() - context.generateInternalStartTime,
+                };
+                await withTimeout(storeConversationTurn(this.conversationMemory, options, abortedResult, new Date(context.generateInternalStartTime), context.requestId), 5000);
+            }
+            catch (storeError) {
+                logger.warn(`[${context.functionTag}] Failed to store conversation turn after abort`, {
+                    error: storeError instanceof Error
+                        ? storeError.message
+                        : String(storeError),
+                });
+            }
+        }
+        else {
+            logger.error(`[${context.functionTag}] All generation methods failed`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        this.emitter.emit("response:end", "");
+        this.emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
+        return null;
+    }
+    async tryRecoverGenerateTextOverflow(options, functionTag, error) {
+        if (!isContextOverflowError(error) || !this.conversationMemory) {
+            return null;
+        }
+        logger.warn(`[${functionTag}] Context overflow detected by provider, attempting smart recovery`, {
+            error: error instanceof Error ? error.message : String(error),
+            overflowProvider: getContextOverflowProvider(error),
+        });
+        try {
+            const actualOverflow = parseProviderOverflowDetails(error);
+            const originalMessages = options._originalConversationMessages ??
+                (await getConversationMessages(this.conversationMemory, options));
+            const recoveryBudget = checkContextBudget({
+                provider: options.provider || "openai",
+                model: options.model,
+                maxTokens: options.maxTokens,
+                currentPrompt: options.prompt,
+                systemPrompt: options.systemPrompt,
+            });
+            const actualTokens = actualOverflow?.actualTokens ?? recoveryBudget.estimatedInputTokens;
+            const budgetTokens = actualOverflow?.budgetTokens ?? recoveryBudget.availableInputTokens;
+            const compactionTarget = Math.floor(budgetTokens * 0.7);
+            const requiredReduction = actualTokens > 0
+                ? (actualTokens - compactionTarget) / actualTokens
+                : 0.5;
+            const compactor = new ContextCompactor({
+                enableSummarize: false,
+                enablePrune: true,
+                enableDeduplicate: true,
+                enableTruncate: true,
+                truncationFraction: Math.min(0.9, requiredReduction + 0.15),
+            });
+            const compactionResult = await compactor.compact(originalMessages, compactionTarget, undefined, options.context?.requestId);
+            if (!compactionResult.compacted) {
+                return null;
+            }
+            const repairedResult = repairToolPairs(compactionResult.messages);
+            const verifyBudget = checkContextBudget({
+                provider: options.provider || "openai",
+                model: options.model,
+                maxTokens: options.maxTokens,
+                systemPrompt: options.systemPrompt,
+                currentPrompt: options.prompt,
+                conversationMessages: repairedResult.messages,
+            });
+            if (!verifyBudget.withinBudget) {
+                logger.error(`[${functionTag}] Recovery compaction insufficient, aborting retry`, {
+                    estimatedTokens: verifyBudget.estimatedInputTokens,
+                    availableTokens: verifyBudget.availableInputTokens,
+                });
+                throw new ContextBudgetExceededError(`Context overflow recovery failed. Provider rejected at ~${actualTokens} tokens, ` +
+                    `recovery compaction achieved ${compactionResult.tokensAfter} tokens ` +
+                    `but budget is ${budgetTokens} tokens.`, {
+                    estimatedTokens: compactionResult.tokensAfter,
+                    availableTokens: budgetTokens,
+                    stagesUsed: compactionResult.stagesUsed,
+                    breakdown: verifyBudget.breakdown,
+                });
+            }
+            logger.info(`[${functionTag}] Smart recovery verified, retrying generation`, {
+                tokensSaved: compactionResult.tokensSaved,
+                compactionTarget,
+                verifiedTokens: verifyBudget.estimatedInputTokens,
+                verifiedBudget: verifyBudget.availableInputTokens,
+            });
+            return this.directProviderGeneration({
+                ...options,
+                conversationMessages: repairedResult.messages,
+            });
+        }
+        catch (retryError) {
+            if (retryError instanceof ContextBudgetExceededError) {
+                throw retryError;
+            }
+            logger.error(`[${functionTag}] Recovery attempt failed`, {
+                error: retryError instanceof Error ? retryError.message : String(retryError),
+            });
+            return null;
+        }
     }
     /**
      * Log generateTextInternal start with comprehensive analysis
@@ -3294,7 +3415,8 @@ 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;
@@ -3316,7 +3438,9 @@ 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,
@@ -3347,7 +3471,11 @@ 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,
@@ -3366,8 +3494,11 @@ 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;
@@ -3403,288 +3534,28 @@ 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();
         const functionTag = "NeuroLink.tryMCPGeneration";
         try {
-            // Initialize MCP if needed
-            await this.initializeMCP();
-            if (!this.mcpInitialized) {
-                logger.warn(`[NeuroLink] ⚠️ LOG_POINT_T004_MCP_NOT_AVAILABLE`, {
-                    logPoint: "T004_MCP_NOT_AVAILABLE",
-                    tryMCPId,
-                    timestamp: new Date().toISOString(),
-                    elapsedMs: Date.now() - tryMCPStartTime,
-                    elapsedNs: (process.hrtime.bigint() - tryMCPHrTimeStart).toString(),
-                    mcpInitialized: this.mcpInitialized,
-                    mcpComponents: {
-                        hasExternalServerManager: !!this.externalServerManager,
-                        hasToolRegistry: !!this.toolRegistry,
-                        hasProviderRegistry: !!AIProviderFactory,
-                    },
-                    fallbackReason: "MCP_NOT_INITIALIZED",
-                    message: "MCP not available - returning null for fallback to direct generation",
-                });
-                return null; // Skip MCP if not available
-            }
-            // Context creation removed - was never used
-            // Determine 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
-            const { tools: circuitBreakerFilteredTools, unavailableTools } = this.toolRegistry.getAvailableTools(this.toolCircuitBreakers);
-            // Intersect: keep only tools that pass both getAllAvailableTools and circuit breaker filtering
-            const cbFilteredNames = new Set(circuitBreakerFilteredTools.map((t) => t.name));
-            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"));
-            logger.debug("Available tools for AI prompt generation", {
-                toolsCount: availableTools.length,
-                toolNames: availableTools.map((t) => t.name),
-                unavailableToolsCount: unavailableTools.length,
-                unavailableTools: unavailableTools,
-                hasTargetTool: !!targetTool,
-                targetToolDetails: targetTool
-                    ? {
-                        name: targetTool.name,
-                        description: targetTool.description,
-                        server: targetTool.server,
-                    }
-                    : null,
-            });
-            // NL-001: Inject system note about unavailable tools
-            let circuitBreakerNote = "";
-            if (unavailableTools.length > 0) {
-                circuitBreakerNote = `\n\nNOTE: The following tools are temporarily unavailable due to repeated failures: ${unavailableTools.join(", ")}. Do not attempt to call these tools.`;
-            }
-            // Create tool-aware system prompt (skip if skipToolPromptInjection is true)
-            const enhancedSystemPrompt = options.skipToolPromptInjection
-                ? (options.systemPrompt || "") + circuitBreakerNote
-                : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools) + circuitBreakerNote;
-            logger.debug("Tool-aware system prompt created", {
-                requestId,
-                originalPromptLength: options.systemPrompt?.length || 0,
-                enhancedPromptLength: enhancedSystemPrompt.length,
-                skippedToolInjection: !!options.skipToolPromptInjection,
-                enhancedPromptPreview: enhancedSystemPrompt.substring(0, 80) + "...",
-            });
-            logger.debug("[Observability] System prompt metadata", {
-                requestId,
-                systemPromptLength: enhancedSystemPrompt.length,
-                systemPromptHash: enhancedSystemPrompt.length > 0 ? `sha256:${enhancedSystemPrompt.slice(0, 8)}...` : "empty",
-                hasCustomSystemPrompt: !!options.systemPrompt,
-            });
-            // Get conversation messages for context
-            let conversationMessages = await getConversationMessages(this.conversationMemory, options);
-            if (logger.shouldLog("debug")) {
-                try {
-                    logger.debug("[Observability] Conversation history summary", {
-                        requestId,
-                        messageCount: conversationMessages?.length || 0,
-                        messages: conversationMessages?.map((msg, i) => {
-                            let contentLength;
-                            if (typeof msg.content === "string") {
-                                contentLength = msg.content.length;
-                            }
-                            else {
-                                try {
-                                    contentLength = JSON.stringify(msg.content).length;
-                                }
-                                catch {
-                                    contentLength = 0;
-                                }
-                            }
-                            return {
-                                index: i,
-                                role: msg.role,
-                                contentLength,
-                                contentPreview: typeof msg.content === "string" ? msg.content.substring(0, 200) : "[multimodal]",
-                            };
-                        }),
-                    });
-                }
-                catch {
-                    // Ignore serialization errors in debug logging
-                }
-            }
-            logger.debug("[Observability] Available tools for LLM", {
-                requestId,
-                toolCount: availableTools?.length || 0,
-                toolNames: availableTools?.map((t) => t.name) || [],
-            });
-            // Pre-generation budget check
-            const budgetResult = checkContextBudget({
-                provider: providerName,
-                model: options.model,
-                maxTokens: options.maxTokens,
-                systemPrompt: enhancedSystemPrompt,
-                conversationMessages: conversationMessages,
-                currentPrompt: options.prompt,
-                toolDefinitions: availableTools,
-            });
-            logger.info("[TokenBudget] Token breakdown", {
-                requestId,
-                system: budgetResult.breakdown?.systemPrompt || 0,
-                history: budgetResult.breakdown?.conversationHistory || 0,
-                tools: budgetResult.breakdown?.toolDefinitions || 0,
-                currentPrompt: budgetResult.breakdown?.currentPrompt || 0,
-                files: budgetResult.breakdown?.fileAttachments || 0,
-                total: budgetResult.estimatedInputTokens,
-                budget: budgetResult.availableInputTokens,
-                usagePercent: Math.round(budgetResult.usageRatio * 1000) / 10,
-                conversationMessageCount: conversationMessages?.length || 0,
-                shouldCompact: budgetResult.shouldCompact,
-            });
-            const messageCount = conversationMessages?.length || 0;
-            const compactionSessionId = this.getCompactionSessionId(options);
-            if (budgetResult.shouldCompact &&
-                this.conversationMemory &&
-                messageCount > (this.lastCompactionMessageCount.get(compactionSessionId) ?? 0)) {
-                logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
-                    usageRatio: budgetResult.usageRatio,
-                    estimatedTokens: budgetResult.estimatedInputTokens,
-                    availableTokens: budgetResult.availableInputTokens,
-                });
-                const compactor = new ContextCompactor({
-                    provider: providerName,
-                    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) {
-                    const repairedResult = repairToolPairs(compactionResult.messages);
-                    conversationMessages = repairedResult.messages;
-                    this.lastCompactionMessageCount.set(compactionSessionId, conversationMessages.length);
-                    logger.info("[NeuroLink] Context compacted successfully", {
-                        stagesUsed: compactionResult.stagesUsed,
-                        tokensSaved: compactionResult.tokensSaved,
-                    });
-                }
-                // POST-COMPACTION BUDGET RE-CHECK (BUG-003 fix)
-                const postCompactBudget = checkContextBudget({
-                    provider: providerName,
-                    model: options.model,
-                    maxTokens: options.maxTokens,
-                    systemPrompt: enhancedSystemPrompt,
-                    conversationMessages: conversationMessages,
-                    currentPrompt: options.prompt,
-                    toolDefinitions: availableTools,
-                });
-                if (!postCompactBudget.withinBudget) {
-                    const overageRatio = postCompactBudget.usageRatio - 1.0;
-                    logger.warn("[NeuroLink] Post-compaction still over budget, attempting emergency content truncation", {
-                        requestId,
-                        estimatedTokens: postCompactBudget.estimatedInputTokens,
-                        availableTokens: postCompactBudget.availableInputTokens,
-                        overagePercent: Math.round(overageRatio * 100),
-                        stagesUsedInCompaction: compactionResult.stagesUsed,
-                    });
-                    // Emergency: truncate the content of the longest messages
-                    conversationMessages = emergencyContentTruncation(conversationMessages, postCompactBudget.availableInputTokens, postCompactBudget.breakdown, providerName);
-                    // Final check after emergency truncation
-                    const finalBudget = checkContextBudget({
-                        provider: providerName,
-                        model: options.model,
-                        maxTokens: options.maxTokens,
-                        systemPrompt: enhancedSystemPrompt,
-                        conversationMessages: conversationMessages,
-                        currentPrompt: options.prompt,
-                        toolDefinitions: availableTools,
-                    });
-                    if (!finalBudget.withinBudget) {
-                        throw new ContextBudgetExceededError(`Context exceeds model budget after all compaction stages. ` +
-                            `Estimated: ${finalBudget.estimatedInputTokens} tokens, ` +
-                            `Budget: ${finalBudget.availableInputTokens} tokens. ` +
-                            `Conversation is too large to fit in the model's context window.`, {
-                            estimatedTokens: finalBudget.estimatedInputTokens,
-                            availableTokens: finalBudget.availableInputTokens,
-                            stagesUsed: compactionResult.stagesUsed,
-                            breakdown: finalBudget.breakdown,
-                        });
-                    }
-                }
+            const generationContext = await this.prepareMCPGenerationContext(options, requestId, tryMCPId, tryMCPStartTime, tryMCPHrTimeStart);
+            if (!generationContext) {
+                return null;
             }
-            // Create provider and generate (with confidence that context fits)
-            const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
-            this, // Pass SDK instance
-            options.region);
-            // Propagate trace context for parent-child span hierarchy
-            provider.setTraceContext(this._metricsTraceContext);
-            // ADD: Emit connection events for all providers (Bedrock-compatible)
-            this.emitter.emit("connected");
-            this.emitter.emit("message", `${providerName} provider initialized successfully`);
-            // Enable tool execution for the provider using BaseProvider method
-            provider.setupToolExecutor({
-                customTools: this.getCustomTools(),
-                executeTool: (toolName, params) => this.executeTool(toolName, params, {
-                    disableToolCache: options.disableToolCache,
-                }),
-            }, functionTag);
-            logger.debug("[Observability] User input to LLM", {
+            const conversationMessages = await this.ensureMCPGenerationBudget(options, requestId, generationContext.providerName, generationContext.enhancedSystemPrompt, generationContext.availableTools, generationContext.conversationMessages);
+            return this.generateWithMCPProvider({
+                options,
                 requestId,
-                promptPreview: options.prompt?.substring(0, 200),
-                promptLength: options.prompt?.length || 0,
-                model: options.model,
-                maxTokens: options.maxTokens,
-                temperature: options.temperature,
-                maxSteps: options.maxSteps,
-                skipToolPromptInjection: options.skipToolPromptInjection,
-            });
-            const result = await provider.generate({
-                ...options,
-                systemPrompt: enhancedSystemPrompt,
-                conversationMessages, // Inject conversation history
-            });
-            const responseTime = Date.now() - tryMCPStartTime;
-            // Enhanced result validation - consider tool executions as valid results
-            const hasContent = result && result.content && result.content.trim().length > 0;
-            const hasToolExecutions = result && result.toolExecutions && result.toolExecutions.length > 0;
-            // Log detailed result analysis for debugging
-            mcpLogger.debug(`[${functionTag}] Result validation:`, {
-                hasResult: !!result,
-                hasContent,
-                hasToolExecutions,
-                contentLength: result?.content?.length || 0,
-                toolExecutionsCount: result?.toolExecutions?.length || 0,
-                toolsUsedCount: result?.toolsUsed?.length || 0,
-            });
-            // Accept result if it has content OR successful tool executions
-            if (!hasContent && !hasToolExecutions) {
-                mcpLogger.debug(`[${functionTag}] Result rejected: no content and no tool executions`);
-                return null; // Let caller fall back to direct generation
-            }
-            // Transform tool executions with enhanced preservation
-            const transformedToolExecutions = transformToolExecutionsForMCP(result.toolExecutions);
-            // Log transformation results
-            mcpLogger.debug(`[${functionTag}] Tool execution transformation:`, {
-                originalCount: result?.toolExecutions?.length || 0,
-                transformedCount: transformedToolExecutions.length,
-                transformedTools: transformedToolExecutions.map((te) => te.toolName),
+                functionTag,
+                tryMCPStartTime,
+                providerName: generationContext.providerName,
+                availableTools: generationContext.availableTools,
+                enhancedSystemPrompt: generationContext.enhancedSystemPrompt,
+                conversationMessages,
             });
-            // Return enhanced result with preserved tool information
-            return {
-                content: result.content || "", // Ensure content is never undefined
-                provider: providerName,
-                model: result.model,
-                usage: result.usage,
-                responseTime,
-                finishReason: result.finishReason,
-                toolsUsed: result.toolsUsed || [],
-                toolExecutions: transformedToolExecutions,
-                enhancedWithTools: Boolean(hasToolExecutions), // Mark as enhanced if tools were actually used
-                availableTools: transformToolsForMCP(transformToolsToExpectedFormat(availableTools)),
-                audio: result.audio,
-                video: result.video,
-                ppt: result.ppt,
-                imageOutput: result.imageOutput,
-                // Include analytics and evaluation from BaseProvider
-                analytics: result.analytics,
-                evaluation: result.evaluation,
-            };
         }
         catch (error) {
             // Immediately propagate AbortError — never swallow aborted requests
@@ -3713,6 +3584,299 @@ Current user's request: ${currentInput}`;
             return null; // Let caller fall back
         }
     }
+    async prepareMCPGenerationContext(options, requestId, tryMCPId, tryMCPStartTime, tryMCPHrTimeStart) {
+        await this.initializeMCP();
+        if (!this.mcpInitialized) {
+            logger.warn(`[NeuroLink] ⚠️ LOG_POINT_T004_MCP_NOT_AVAILABLE`, {
+                logPoint: "T004_MCP_NOT_AVAILABLE",
+                tryMCPId,
+                timestamp: new Date().toISOString(),
+                elapsedMs: Date.now() - tryMCPStartTime,
+                elapsedNs: (process.hrtime.bigint() - tryMCPHrTimeStart).toString(),
+                mcpInitialized: this.mcpInitialized,
+                mcpComponents: {
+                    hasExternalServerManager: !!this.externalServerManager,
+                    hasToolRegistry: !!this.toolRegistry,
+                    hasProviderRegistry: !!AIProviderFactory,
+                },
+                fallbackReason: "MCP_NOT_INITIALIZED",
+                message: "MCP not available - returning null for fallback to direct generation",
+            });
+            return null;
+        }
+        const providerName = options.provider === "auto" || !options.provider
+            ? await getBestProvider()
+            : options.provider;
+        let availableTools = await this.getAllAvailableTools();
+        const { tools: circuitBreakerFilteredTools, unavailableTools } = this.toolRegistry.getAvailableTools(this.toolCircuitBreakers);
+        const cbFilteredNames = new Set(circuitBreakerFilteredTools.map((tool) => tool.name));
+        availableTools = availableTools.filter((tool) => cbFilteredNames.has(tool.name));
+        availableTools = this.applyToolInfoFiltering(availableTools, options);
+        const targetTool = availableTools.find((tool) => tool.name.includes("SuccessRateSRByTime") ||
+            tool.name.includes("juspay-analytics"));
+        logger.debug("Available tools for AI prompt generation", {
+            toolsCount: availableTools.length,
+            toolNames: availableTools.map((tool) => tool.name),
+            unavailableToolsCount: unavailableTools.length,
+            unavailableTools,
+            hasTargetTool: !!targetTool,
+            targetToolDetails: targetTool
+                ? {
+                    name: targetTool.name,
+                    description: targetTool.description,
+                    server: targetTool.server,
+                }
+                : null,
+        });
+        const circuitBreakerNote = unavailableTools.length > 0
+            ? `\n\nNOTE: The following tools are temporarily unavailable due to repeated failures: ${unavailableTools.join(", ")}. Do not attempt to call these tools.`
+            : "";
+        const enhancedSystemPrompt = options.skipToolPromptInjection
+            ? (options.systemPrompt || "") + circuitBreakerNote
+            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools) +
+                circuitBreakerNote;
+        logger.debug("Tool-aware system prompt created", {
+            requestId,
+            originalPromptLength: options.systemPrompt?.length || 0,
+            enhancedPromptLength: enhancedSystemPrompt.length,
+            skippedToolInjection: !!options.skipToolPromptInjection,
+            enhancedPromptPreview: enhancedSystemPrompt.substring(0, 80) + "...",
+        });
+        logger.debug("[Observability] System prompt metadata", {
+            requestId,
+            systemPromptLength: enhancedSystemPrompt.length,
+            systemPromptHash: enhancedSystemPrompt.length > 0
+                ? `sha256:${enhancedSystemPrompt.slice(0, 8)}...`
+                : "empty",
+            hasCustomSystemPrompt: !!options.systemPrompt,
+        });
+        const conversationMessages = (await getConversationMessages(this.conversationMemory, options));
+        this.logMCPConversationSummary(requestId, conversationMessages);
+        logger.debug("[Observability] Available tools for LLM", {
+            requestId,
+            toolCount: availableTools.length,
+            toolNames: availableTools.map((tool) => tool.name),
+        });
+        return {
+            providerName,
+            availableTools,
+            enhancedSystemPrompt,
+            conversationMessages,
+        };
+    }
+    logMCPConversationSummary(requestId, conversationMessages) {
+        if (!logger.shouldLog("debug")) {
+            return;
+        }
+        try {
+            logger.debug("[Observability] Conversation history summary", {
+                requestId,
+                messageCount: conversationMessages.length,
+                messages: conversationMessages.map((message, index) => {
+                    let contentLength;
+                    if (typeof message.content === "string") {
+                        contentLength = message.content.length;
+                    }
+                    else {
+                        try {
+                            contentLength = JSON.stringify(message.content).length;
+                        }
+                        catch {
+                            contentLength = 0;
+                        }
+                    }
+                    return {
+                        index,
+                        role: message.role,
+                        contentLength,
+                        contentPreview: typeof message.content === "string"
+                            ? message.content.substring(0, 200)
+                            : "[multimodal]",
+                    };
+                }),
+            });
+        }
+        catch {
+            // Ignore serialization errors in debug logging
+        }
+    }
+    async ensureMCPGenerationBudget(options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages) {
+        const budgetResult = checkContextBudget({
+            provider: providerName,
+            model: options.model,
+            maxTokens: options.maxTokens,
+            systemPrompt: enhancedSystemPrompt,
+            conversationMessages: conversationMessages,
+            currentPrompt: options.prompt,
+            toolDefinitions: availableTools,
+        });
+        logger.info("[TokenBudget] Token breakdown", {
+            requestId,
+            system: budgetResult.breakdown?.systemPrompt || 0,
+            history: budgetResult.breakdown?.conversationHistory || 0,
+            tools: budgetResult.breakdown?.toolDefinitions || 0,
+            currentPrompt: budgetResult.breakdown?.currentPrompt || 0,
+            files: budgetResult.breakdown?.fileAttachments || 0,
+            total: budgetResult.estimatedInputTokens,
+            budget: budgetResult.availableInputTokens,
+            usagePercent: Math.round(budgetResult.usageRatio * 1000) / 10,
+            conversationMessageCount: conversationMessages.length,
+            shouldCompact: budgetResult.shouldCompact,
+        });
+        const compactionSessionId = this.getCompactionSessionId(options);
+        const lastCompactionCount = this.lastCompactionMessageCount.get(compactionSessionId) ?? 0;
+        if (!budgetResult.shouldCompact ||
+            !this.conversationMemory ||
+            conversationMessages.length <= lastCompactionCount) {
+            return conversationMessages;
+        }
+        return this.compactMCPConversationForBudget({
+            options,
+            requestId,
+            providerName,
+            enhancedSystemPrompt,
+            availableTools,
+            conversationMessages,
+            availableInputTokens: budgetResult.availableInputTokens,
+            usageRatio: budgetResult.usageRatio,
+            estimatedInputTokens: budgetResult.estimatedInputTokens,
+            compactionSessionId,
+        });
+    }
+    async compactMCPConversationForBudget(context) {
+        const { options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages, availableInputTokens, usageRatio, estimatedInputTokens, compactionSessionId, } = context;
+        logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
+            usageRatio,
+            estimatedTokens: estimatedInputTokens,
+            availableTokens: availableInputTokens,
+        });
+        const compactor = new ContextCompactor({
+            provider: providerName,
+            summarizationProvider: this.conversationMemoryConfig?.conversationMemory
+                ?.summarizationProvider,
+            summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
+        });
+        const compactionResult = await compactor.compact(conversationMessages, availableInputTokens, this.conversationMemoryConfig?.conversationMemory, requestId);
+        let compactedMessages = conversationMessages;
+        if (compactionResult.compacted) {
+            const repairedResult = repairToolPairs(compactionResult.messages);
+            compactedMessages = repairedResult.messages;
+            this.lastCompactionMessageCount.set(compactionSessionId, compactedMessages.length);
+            logger.info("[NeuroLink] Context compacted successfully", {
+                stagesUsed: compactionResult.stagesUsed,
+                tokensSaved: compactionResult.tokensSaved,
+            });
+        }
+        const postCompactBudget = checkContextBudget({
+            provider: providerName,
+            model: options.model,
+            maxTokens: options.maxTokens,
+            systemPrompt: enhancedSystemPrompt,
+            conversationMessages: compactedMessages,
+            currentPrompt: options.prompt,
+            toolDefinitions: availableTools,
+        });
+        if (postCompactBudget.withinBudget) {
+            return compactedMessages;
+        }
+        const overageRatio = postCompactBudget.usageRatio - 1.0;
+        logger.warn("[NeuroLink] Post-compaction still over budget, attempting emergency content truncation", {
+            requestId,
+            estimatedTokens: postCompactBudget.estimatedInputTokens,
+            availableTokens: postCompactBudget.availableInputTokens,
+            overagePercent: Math.round(overageRatio * 100),
+            stagesUsedInCompaction: compactionResult.stagesUsed,
+        });
+        compactedMessages = emergencyContentTruncation(compactedMessages, postCompactBudget.availableInputTokens, postCompactBudget.breakdown, providerName);
+        const finalBudget = checkContextBudget({
+            provider: providerName,
+            model: options.model,
+            maxTokens: options.maxTokens,
+            systemPrompt: enhancedSystemPrompt,
+            conversationMessages: compactedMessages,
+            currentPrompt: options.prompt,
+            toolDefinitions: availableTools,
+        });
+        if (!finalBudget.withinBudget) {
+            throw new ContextBudgetExceededError(`Context exceeds model budget after all compaction stages. ` +
+                `Estimated: ${finalBudget.estimatedInputTokens} tokens, ` +
+                `Budget: ${finalBudget.availableInputTokens} tokens. ` +
+                `Conversation is too large to fit in the model's context window.`, {
+                estimatedTokens: finalBudget.estimatedInputTokens,
+                availableTokens: finalBudget.availableInputTokens,
+                stagesUsed: compactionResult.stagesUsed,
+                breakdown: finalBudget.breakdown,
+            });
+        }
+        return compactedMessages;
+    }
+    async generateWithMCPProvider(context) {
+        const { options, requestId, functionTag, tryMCPStartTime, providerName, availableTools, enhancedSystemPrompt, conversationMessages, } = context;
+        const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, this, options.region);
+        provider.setTraceContext(this._metricsTraceContext);
+        this.emitter.emit("connected");
+        this.emitter.emit("message", `${providerName} provider initialized successfully`);
+        provider.setupToolExecutor({
+            customTools: this.getCustomTools(),
+            executeTool: (toolName, params) => this.executeTool(toolName, params, {
+                disableToolCache: options.disableToolCache,
+            }),
+        }, functionTag);
+        logger.debug("[Observability] User input to LLM", {
+            requestId,
+            promptPreview: options.prompt?.substring(0, 200),
+            promptLength: options.prompt?.length || 0,
+            model: options.model,
+            maxTokens: options.maxTokens,
+            temperature: options.temperature,
+            maxSteps: options.maxSteps,
+            skipToolPromptInjection: options.skipToolPromptInjection,
+        });
+        const result = await provider.generate({
+            ...options,
+            systemPrompt: enhancedSystemPrompt,
+            conversationMessages,
+        });
+        const responseTime = Date.now() - tryMCPStartTime;
+        const hasContent = !!(result?.content && result.content.trim().length > 0);
+        const hasToolExecutions = !!(result?.toolExecutions && result.toolExecutions.length > 0);
+        mcpLogger.debug(`[${functionTag}] Result validation:`, {
+            hasResult: !!result,
+            hasContent,
+            hasToolExecutions,
+            contentLength: result?.content?.length || 0,
+            toolExecutionsCount: result?.toolExecutions?.length || 0,
+            toolsUsedCount: result?.toolsUsed?.length || 0,
+        });
+        if (!hasContent && !hasToolExecutions) {
+            mcpLogger.debug(`[${functionTag}] Result rejected: no content and no tool executions`);
+            return null;
+        }
+        const transformedToolExecutions = transformToolExecutionsForMCP(result.toolExecutions);
+        mcpLogger.debug(`[${functionTag}] Tool execution transformation:`, {
+            originalCount: result?.toolExecutions?.length || 0,
+            transformedCount: transformedToolExecutions.length,
+            transformedTools: transformedToolExecutions.map((te) => te.toolName),
+        });
+        return {
+            content: result.content || "",
+            provider: providerName,
+            model: result.model,
+            usage: result.usage,
+            responseTime,
+            finishReason: result.finishReason,
+            toolsUsed: result.toolsUsed || [],
+            toolExecutions: transformedToolExecutions,
+            enhancedWithTools: Boolean(hasToolExecutions),
+            availableTools: transformToolsForMCP(transformToolsToExpectedFormat(availableTools)),
+            audio: result.audio,
+            video: result.video,
+            ppt: result.ppt,
+            imageOutput: result.imageOutput,
+            analytics: result.analytics,
+            evaluation: result.evaluation,
+        };
+    }
     /**
      * Direct provider generation (no MCP, no recursion)
      */
@@ -3732,12 +3896,18 @@ 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;
@@ -3757,7 +3927,8 @@ 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
@@ -3768,17 +3939,22 @@ 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) {
@@ -3794,7 +3970,9 @@ 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", {
@@ -3810,7 +3988,9 @@ 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. ` +
@@ -4064,367 +4244,285 @@ Current user's request: ${currentInput}`;
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     async stream(options) {
-        // Shallow-copy caller's object to avoid mutating their original reference
-        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);
-        // Scope trace context to this request via AsyncLocalStorage
-        // so concurrent generate/stream calls don't race.
-        return metricsTraceContextStorage.run({ traceId: metricsTraceId, parentSpanId: metricsParentSpanId }, async () => {
-            // Manual span lifecycle: the span must stay open until the stream is fully consumed,
-            // NOT when the StreamResult object is returned. withSpan would end the span too early
-            // because streaming results resolve lazily via the async generator.
-            const streamSpan = tracers.sdk.startSpan("neurolink.stream", {
-                kind: SpanKind.INTERNAL,
-                attributes: {
-                    [ATTR.NL_PROVIDER]: options.provider || "default",
-                    [ATTR.GEN_AI_MODEL]: options.model || "default",
-                    [ATTR.NL_INPUT_LENGTH]: options.input?.text?.length || 0,
-                    [ATTR.NL_HAS_TOOLS]: !!(options.tools && Object.keys(options.tools).length > 0),
-                    [ATTR.NL_STREAM_MODE]: true,
-                },
+        return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeStreamRequest({ ...options }));
+    }
+    async executeStreamRequest(options) {
+        const streamSpan = tracers.sdk.startSpan("neurolink.stream", {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                [ATTR.NL_PROVIDER]: options.provider || "default",
+                [ATTR.GEN_AI_MODEL]: options.model || "default",
+                [ATTR.NL_INPUT_LENGTH]: options.input?.text?.length || 0,
+                [ATTR.NL_HAS_TOOLS]: !!(options.tools && Object.keys(options.tools).length > 0),
+                [ATTR.NL_STREAM_MODE]: true,
+            },
+        });
+        const spanStartTime = Date.now();
+        this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
+        try {
+            options.model = resolveModel(options.model, this.modelAliasConfig);
+            const startTime = Date.now();
+            const hrTimeStart = process.hrtime.bigint();
+            const streamId = `neurolink-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+            const originalPrompt = options.input.text;
+            options.fileRegistry = this.fileRegistry;
+            await this.validateStreamRequestOptions(options, startTime);
+            const workflowResult = await this.maybeHandleWorkflowStreamRequest({
+                options,
+                startTime,
+                streamSpan,
+                spanStartTime,
             });
-            const spanStartTime = Date.now();
-            // MCP Enhancement: propagate disableToolCache to tool execution
-            this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
-            try {
-                // NL-004: Resolve model aliases/deprecations before processing
-                options.model = resolveModel(options.model, this.modelAliasConfig);
-                const startTime = Date.now();
-                const hrTimeStart = process.hrtime.bigint();
-                const streamId = `neurolink-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-                const originalPrompt = options.input.text; // Store the original prompt for memory storage
-                // Inject file registry for lazy on-demand file processing
-                options.fileRegistry = this.fileRegistry;
-                await this.validateStreamInput(options);
-                // Check budget limit before making API call
-                if (options.maxBudgetUsd !== undefined &&
-                    options.maxBudgetUsd > 0 &&
-                    this._sessionCostUsd >= options.maxBudgetUsd) {
-                    throw new NeuroLinkError({
-                        code: "SESSION_BUDGET_EXCEEDED",
-                        message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
-                        category: ErrorCategory.VALIDATION,
-                        severity: ErrorSeverity.HIGH,
-                        retriable: false,
-                        context: {
-                            spent: this._sessionCostUsd,
-                            limit: options.maxBudgetUsd,
-                        },
-                    });
-                }
-                // Handle per-call auth token validation
-                if (options.auth?.token) {
-                    const { AuthError } = await import("./auth/errors.js");
-                    await this.ensureAuthProvider();
-                    if (!this.authProvider) {
-                        throw AuthError.create("PROVIDER_ERROR", "No auth provider configured. Set auth in constructor or via setAuthProvider() before using auth: { token }.");
-                    }
-                    let authResult;
-                    try {
-                        authResult = await withTimeout(this.authProvider.authenticateToken(options.auth.token), 5000, AuthError.create("PROVIDER_ERROR", "Auth token validation timed out after 5000ms"));
-                    }
-                    catch (err) {
-                        // Rethrow auth errors as-is; wrap anything else
-                        if (err instanceof Error && "feature" in err && err.feature === "Auth") {
-                            throw err;
+            if (workflowResult) {
+                return workflowResult;
+            }
+            return this.setLangfuseContextFromOptions(options, () => this.runStandardStreamRequest({
+                options,
+                streamSpan,
+                spanStartTime,
+                startTime,
+                hrTimeStart,
+                streamId,
+                originalPrompt,
+            }));
+        }
+        catch (error) {
+            streamSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            if (error instanceof Error) {
+                streamSpan.recordException(error);
+            }
+            streamSpan.end();
+            throw error;
+        }
+    }
+    async validateStreamRequestOptions(options, startTime) {
+        await this.validateStreamInput(options);
+        this.enforceSessionBudget(options.maxBudgetUsd);
+        await this.applyAuthenticatedRequestContext(options);
+        this.emitStreamStartEvents(options, startTime);
+        this.applyStreamLifecycleMiddleware(options);
+    }
+    async maybeHandleWorkflowStreamRequest(params) {
+        if (!params.options.workflow && !params.options.workflowConfig) {
+            return null;
+        }
+        const result = await this.streamWithWorkflow(params.options, params.startTime);
+        const originalWorkflowStream = result.stream;
+        const self = this;
+        result.stream = (async function* () {
+            try {
+                for await (const chunk of originalWorkflowStream) {
+                    yield chunk;
+                }
+                params.streamSpan.setStatus({ code: SpanStatusCode.OK });
+            }
+            catch (error) {
+                params.streamSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                self._disableToolCacheForCurrentRequest = false;
+                params.streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - params.spanStartTime);
+                params.streamSpan.end();
+            }
+        })();
+        return result;
+    }
+    async runStandardStreamRequest(params) {
+        const { options, streamSpan, spanStartTime, startTime, hrTimeStart, streamId, originalPrompt, } = params;
+        try {
+            const { enhancedOptions, factoryResult } = await this.prepareStreamOptions(options, streamId, startTime, hrTimeStart);
+            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,
+            };
+            streamSpan.setAttribute(ATTR.NL_PROVIDER, providerName || "unknown");
+            let accumulatedContent = "";
+            let chunkCount = 0;
+            const { eventSequence, cleanup: cleanupListeners } = this.setupStreamEventListeners();
+            const metadata = {
+                fallbackAttempted: false,
+                guardrailsBlocked: false,
+                error: undefined,
+                fallbackProvider: undefined,
+                fallbackModel: undefined,
+            };
+            const self = this;
+            const streamStartTime = Date.now();
+            const sessionId = enhancedOptions.context
+                ?.sessionId;
+            const processedStream = (async function* () {
+                let streamError;
+                try {
+                    for await (const chunk of mcpStream) {
+                        chunkCount++;
+                        if (chunk &&
+                            "content" in chunk &&
+                            typeof chunk.content === "string") {
+                            accumulatedContent += chunk.content;
+                            self.emitter.emit("response:chunk", chunk.content);
+                            self.emitter.emit("stream:chunk", {
+                                type: "stream:chunk",
+                                content: chunk.content,
+                                metadata: {
+                                    chunkIndex: chunkCount,
+                                    totalLength: accumulatedContent.length,
+                                },
+                                timestamp: Date.now(),
+                            });
                         }
-                        throw AuthError.create("PROVIDER_ERROR", `Auth token validation failed: ${err instanceof Error ? err.message : String(err)}`);
+                        yield chunk;
                     }
-                    if (!authResult.valid) {
-                        throw AuthError.create("INVALID_TOKEN", authResult.error || "Token validation failed");
-                    }
-                    // Fail closed: token valid but no user identity is a provider bug
-                    if (!authResult.user) {
-                        throw AuthError.create("INVALID_TOKEN", "Token validated but no user identity returned");
-                    }
-                    if (!authResult.user.id) {
-                        throw AuthError.create("INVALID_TOKEN", "Token validated but user identity missing required 'id' field");
+                    if (chunkCount === 0 &&
+                        !metadata.fallbackAttempted &&
+                        !enhancedOptions.disableInternalFallback &&
+                        streamState.toolCalls.length === 0 &&
+                        streamState.toolResults.length === 0) {
+                        yield* self.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, (content) => {
+                            accumulatedContent += content;
+                        });
                     }
-                    // Merge validated user into context
-                    options.context = {
-                        ...(options.context || {}),
-                        userId: authResult.user.id,
-                        userEmail: authResult.user.email,
-                        userRoles: authResult.user.roles,
-                    };
-                }
-                // Handle pre-validated requestContext
-                if (options.requestContext) {
-                    // When auth token was validated, token-derived identity fields
-                    // MUST take precedence over requestContext to prevent privilege escalation.
-                    const tokenDerivedFields = options.auth?.token && this.authProvider
-                        ? {
-                            userId: options.context?.userId,
-                            userEmail: options.context?.userEmail,
-                            userRoles: options.context?.userRoles,
-                        }
-                        : {};
-                    options.context = {
-                        ...(options.context || {}),
-                        ...options.requestContext,
-                        ...tokenDerivedFields,
-                    };
-                }
-                this.emitStreamStartEvents(options, startTime);
-                // Auto-inject lifecycle middleware when callbacks are provided
-                // (must happen before workflow early return so that path gets middleware too)
-                if (options.onFinish || options.onError || options.onChunk) {
-                    options.middleware = {
-                        ...options.middleware,
-                        middlewareConfig: {
-                            ...options.middleware?.middlewareConfig,
-                            lifecycle: {
-                                ...options.middleware?.middlewareConfig?.lifecycle,
-                                enabled: true,
-                                config: {
-                                    ...options.middleware?.middlewareConfig?.lifecycle?.config,
-                                    ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
-                                    ...(options.onError !== undefined ? { onError: options.onError } : {}),
-                                    ...(options.onChunk !== undefined ? { onChunk: options.onChunk } : {}),
-                                },
-                            },
-                        },
-                    };
-                }
-                // Check if workflow is requested
-                if (options.workflow || options.workflowConfig) {
-                    const result = await this.streamWithWorkflow(options, startTime);
-                    // Wrap the workflow stream so the span stays open until fully consumed
-                    const originalWorkflowStream = result.stream;
-                    const selfWorkflow = this;
-                    result.stream = (async function* () {
+                    let resolvedUsage = streamUsage;
+                    if (!resolvedUsage && streamAnalytics) {
                         try {
-                            for await (const chunk of originalWorkflowStream) {
-                                yield chunk;
+                            const resolved = await Promise.resolve(streamAnalytics);
+                            if (resolved?.tokenUsage) {
+                                resolvedUsage = resolved.tokenUsage;
                             }
-                            streamSpan.setStatus({ code: SpanStatusCode.OK });
-                        }
-                        catch (error) {
-                            streamSpan.setStatus({
-                                code: SpanStatusCode.ERROR,
-                                message: error instanceof Error ? error.message : String(error),
-                            });
-                            throw error;
                         }
-                        finally {
-                            selfWorkflow._disableToolCacheForCurrentRequest = false;
-                            streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
-                            streamSpan.end();
+                        catch {
+                            // non-blocking
                         }
-                    })();
-                    return result;
+                    }
+                    self.emitter.emit("stream:complete", {
+                        type: "stream:complete",
+                        content: accumulatedContent,
+                        provider: metadata.fallbackProvider ?? providerName,
+                        model: metadata.fallbackModel ?? streamModel ?? enhancedOptions.model,
+                        prompt: enhancedOptions.input?.text ||
+                            enhancedOptions.prompt,
+                        metadata: {
+                            chunkCount,
+                            totalLength: accumulatedContent.length,
+                            durationMs: Date.now() - streamStartTime,
+                            sessionId,
+                            usage: resolvedUsage,
+                            ...(metadata.fallbackAttempted && {
+                                primaryProvider: providerName,
+                                primaryModel: enhancedOptions.model,
+                                fallback: true,
+                            }),
+                        },
+                        timestamp: Date.now(),
+                    });
                 }
-                // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
-                return await this.setLangfuseContextFromOptions(options, async () => {
-                    try {
-                        // Prepare options: init memory, MCP, 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, 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 = "";
-                        let chunkCount = 0;
-                        // Set up event capture listeners
-                        const { eventSequence, cleanup: cleanupListeners } = this.setupStreamEventListeners();
-                        const metadata = {
-                            fallbackAttempted: false,
-                            guardrailsBlocked: false,
-                            error: undefined,
-                            fallbackProvider: undefined,
-                            fallbackModel: undefined,
-                        };
-                        const self = this;
-                        const streamStartTime = Date.now();
-                        const sessionId = enhancedOptions.context?.sessionId;
-                        const processedStream = (async function* () {
-                            let streamError;
-                            try {
-                                for await (const chunk of mcpStream) {
-                                    chunkCount++;
-                                    if (chunk && "content" in chunk && typeof chunk.content === "string") {
-                                        accumulatedContent += chunk.content;
-                                        self.emitter.emit("response:chunk", chunk.content);
-                                        // Emit stream:chunk event (Observability Solution 8)
-                                        self.emitter.emit("stream:chunk", {
-                                            type: "stream:chunk",
-                                            content: chunk.content,
-                                            metadata: {
-                                                chunkIndex: chunkCount,
-                                                totalLength: accumulatedContent.length,
-                                            },
-                                            timestamp: Date.now(),
-                                        });
-                                    }
-                                    yield chunk;
-                                }
-                                if (chunkCount === 0 &&
-                                    !metadata.fallbackAttempted &&
-                                    !enhancedOptions.disableInternalFallback &&
-                                    streamState.toolCalls.length === 0 &&
-                                    streamState.toolResults.length === 0) {
-                                    yield* self.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, accumulatedContent, (content) => {
-                                        accumulatedContent += content;
-                                    });
-                                }
-                                // Emit stream:complete event (Observability Solution 8)
-                                // When fallback took over, attribute the completion to the
-                                // fallback provider so downstream telemetry reflects reality.
-                                const effectiveProvider = metadata.fallbackProvider ?? providerName;
-                                const effectiveModel = metadata.fallbackModel ?? streamModel ?? enhancedOptions.model;
-                                // Resolve analytics promise to get final token usage
-                                let resolvedUsage = streamUsage;
-                                if (!resolvedUsage && streamAnalytics) {
-                                    try {
-                                        const resolved = await Promise.resolve(streamAnalytics);
-                                        if (resolved?.tokenUsage) {
-                                            resolvedUsage = resolved.tokenUsage;
-                                        }
-                                    }
-                                    catch {
-                                        /* non-blocking */
-                                    }
-                                }
-                                self.emitter.emit("stream:complete", {
-                                    type: "stream:complete",
-                                    content: accumulatedContent,
-                                    provider: effectiveProvider,
-                                    model: effectiveModel,
-                                    prompt: enhancedOptions.input?.text || enhancedOptions.prompt,
-                                    metadata: {
-                                        chunkCount,
-                                        totalLength: accumulatedContent.length,
-                                        durationMs: Date.now() - streamStartTime,
-                                        sessionId,
-                                        usage: resolvedUsage,
-                                        ...(metadata.fallbackAttempted && {
-                                            primaryProvider: providerName,
-                                            primaryModel: enhancedOptions.model,
-                                            fallback: true,
-                                        }),
-                                    },
-                                    timestamp: Date.now(),
-                                });
-                            }
-                            catch (error) {
-                                streamError = error;
-                                // Emit stream:error event (Observability Solution 8)
-                                self.emitter.emit("stream:error", {
-                                    type: "stream:error",
-                                    content: error instanceof Error ? error.message : String(error),
-                                    provider: providerName,
-                                    model: enhancedOptions.model,
-                                    metadata: {
-                                        chunkCount,
-                                        totalLength: accumulatedContent.length,
-                                        durationMs: Date.now() - streamStartTime,
-                                        errorName: error instanceof Error ? error.name : "UnknownError",
-                                        sessionId,
-                                    },
-                                    timestamp: Date.now(),
-                                });
-                                throw error;
-                            }
-                            finally {
-                                self._disableToolCacheForCurrentRequest = false;
-                                cleanupListeners();
-                                // Finalize span now that the stream is fully consumed
-                                streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
-                                streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
-                                // When fallback took over, the primary provider's span must
-                                // reflect that it failed — never mark it as successful.
-                                const primaryFailed = !!(metadata.error || streamError);
-                                streamSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, primaryFailed ? "error" : "stop");
-                                if (metadata.fallbackAttempted) {
-                                    streamSpan.setAttribute("neurolink.fallback_triggered", true);
-                                    if (metadata.fallbackProvider) {
-                                        streamSpan.setAttribute("neurolink.fallback_provider", metadata.fallbackProvider);
-                                    }
-                                }
-                                if (primaryFailed) {
-                                    streamSpan.setStatus({
-                                        code: SpanStatusCode.ERROR,
-                                        message: metadata.error || (streamError instanceof Error ? streamError.message : String(streamError)),
-                                    });
-                                }
-                                else {
-                                    streamSpan.setStatus({ code: SpanStatusCode.OK });
-                                }
-                                streamSpan.end();
-                                if (accumulatedContent.trim()) {
-                                    logger.info(`[NeuroLink.stream] stream() - COMPLETE SUCCESS`, {
-                                        provider: providerName,
-                                        model: enhancedOptions.model,
-                                        responseTimeMs: Date.now() - startTime,
-                                        contentLength: accumulatedContent.length,
-                                        fallback: metadata.fallbackAttempted,
-                                    });
-                                }
-                                await self.storeStreamConversationMemory({
-                                    enhancedOptions,
-                                    providerName,
-                                    originalPrompt,
-                                    accumulatedContent,
-                                    startTime,
-                                    eventSequence,
-                                });
-                            }
-                        })();
-                        const streamResult = await this.processStreamResult(processedStream, enhancedOptions, factoryResult);
-                        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) {
-                            this._sessionCostUsd += streamResult.analytics.cost;
+                catch (error) {
+                    streamError = error;
+                    self.emitter.emit("stream:error", {
+                        type: "stream:error",
+                        content: error instanceof Error ? error.message : String(error),
+                        provider: providerName,
+                        model: enhancedOptions.model,
+                        metadata: {
+                            chunkCount,
+                            totalLength: accumulatedContent.length,
+                            durationMs: Date.now() - streamStartTime,
+                            errorName: error instanceof Error ? error.name : "UnknownError",
+                            sessionId,
+                        },
+                        timestamp: Date.now(),
+                    });
+                    throw error;
+                }
+                finally {
+                    self._disableToolCacheForCurrentRequest = false;
+                    cleanupListeners();
+                    streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
+                    streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
+                    const primaryFailed = !!(metadata.error || streamError);
+                    streamSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, primaryFailed ? "error" : "stop");
+                    if (metadata.fallbackAttempted) {
+                        streamSpan.setAttribute("neurolink.fallback_triggered", true);
+                        if (metadata.fallbackProvider) {
+                            streamSpan.setAttribute("neurolink.fallback_provider", metadata.fallbackProvider);
                         }
-                        this.emitStreamEndEvents(streamResult);
-                        return this.createStreamResponse(streamResult, processedStream, {
-                            providerName,
-                            options,
-                            startTime,
-                            responseTime,
-                            streamId,
-                            fallback: metadata.fallbackAttempted,
-                            guardrailsBlocked: metadata.guardrailsBlocked,
-                            error: metadata.error,
-                            events: eventSequence,
+                    }
+                    if (primaryFailed) {
+                        streamSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: metadata.error ||
+                                (streamError instanceof Error
+                                    ? streamError.message
+                                    : String(streamError)),
                         });
                     }
-                    catch (error) {
-                        if (options.disableInternalFallback) {
-                            throw error;
-                        }
-                        return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
+                    else {
+                        streamSpan.setStatus({ code: SpanStatusCode.OK });
                     }
-                });
-            }
-            catch (error) {
-                // End span on error before re-throwing
-                streamSpan.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: error instanceof Error ? error.message : String(error),
-                });
-                if (error instanceof Error) {
-                    streamSpan.recordException(error);
+                    streamSpan.end();
+                    if (accumulatedContent.trim()) {
+                        logger.info(`[NeuroLink.stream] stream() - COMPLETE SUCCESS`, {
+                            provider: providerName,
+                            model: enhancedOptions.model,
+                            responseTimeMs: Date.now() - startTime,
+                            contentLength: accumulatedContent.length,
+                            fallback: metadata.fallbackAttempted,
+                        });
+                    }
+                    await self.storeStreamConversationMemory({
+                        enhancedOptions,
+                        providerName,
+                        originalPrompt,
+                        accumulatedContent,
+                        startTime,
+                        eventSequence,
+                    });
                 }
-                streamSpan.end();
+            })();
+            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;
+            }
+            if (streamResult.analytics?.cost && streamResult.analytics.cost > 0) {
+                this._sessionCostUsd += streamResult.analytics.cost;
+            }
+            this.emitStreamEndEvents(streamResult);
+            return this.createStreamResponse(streamResult, processedStream, {
+                providerName,
+                options,
+                startTime,
+                responseTime: Date.now() - startTime,
+                streamId,
+                fallback: metadata.fallbackAttempted,
+                guardrailsBlocked: metadata.guardrailsBlocked,
+                error: metadata.error,
+                events: eventSequence,
+            });
+        }
+        catch (error) {
+            if (options.disableInternalFallback) {
                 throw error;
             }
-        }); // end metricsTraceContextStorage.run
+            return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
+        }
     }
     /**
      * Prepare stream options: initialize memory, MCP, retrieval, orchestration,
@@ -4436,7 +4534,8 @@ 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");
@@ -4481,7 +4580,8 @@ 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`,
@@ -4490,7 +4590,8 @@ 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,
@@ -4518,7 +4619,8 @@ 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();
@@ -4560,16 +4662,31 @@ Current user's request: ${currentInput}`;
         };
         const onToolStart = (...args) => {
             const data = args[0];
-            captureEvent("tool:start", data);
+            captureEvent("tool:start", {
+                ...data,
+                toolName: data.toolName ?? data.tool,
+            });
         };
         const onToolEnd = (...args) => {
             const data = args[0];
-            captureEvent("tool:end", data);
-            if (data.result && data.result.uiComponent === true) {
+            const toolName = data.toolName ?? data.tool;
+            const responseTime = data.responseTime ?? data.duration;
+            const success = data.success ?? (data.error !== undefined ? false : undefined);
+            const augmented = {
+                ...data,
+                toolName,
+                ...(responseTime !== undefined ? { responseTime } : {}),
+                ...(success !== undefined ? { success } : {}),
+                ...(data.error !== undefined ? { error: data.error } : {}),
+            };
+            captureEvent("tool:end", augmented);
+            if (augmented.result && augmented.result.uiComponent === true) {
                 captureEvent("ui-component", {
-                    toolName: data.toolName,
-                    componentData: data.result,
+                    toolName,
+                    componentData: augmented.result,
                     timestamp: Date.now(),
+                    ...(success !== undefined ? { success } : {}),
+                    ...(responseTime !== undefined ? { responseTime } : {}),
                 });
             }
         };
@@ -4602,7 +4719,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, streamState, originalPrompt, enhancedOptions, providerName, _accumulatedContent, appendContent) {
+    async *handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, appendContent) {
         metadata.fallbackAttempted = true;
         const errorMsg = "Stream completed with 0 chunks (possible guardrails block)";
         metadata.error = errorMsg;
@@ -4665,18 +4782,23 @@ Current user's request: ${currentInput}`;
             if (fallbackToolCalls.length > 0 || fallbackToolResults.length > 0) {
                 streamState.toolCalls = fallbackToolCalls;
                 streamState.toolResults = fallbackToolResults;
-                streamState.finishReason = fallbackResult.finishReason ?? streamState.finishReason;
+                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 && fallbackToolCalls.length === 0 && fallbackToolResults.length === 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
@@ -4685,7 +4807,9 @@ 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,
@@ -4699,19 +4823,22 @@ 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 = {
@@ -4730,7 +4857,8 @@ 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", {
@@ -4760,7 +4888,8 @@ 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 &&
@@ -4839,10 +4968,12 @@ 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);
@@ -4987,7 +5118,8 @@ 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);
@@ -5011,7 +5143,9 @@ 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);
@@ -5030,9 +5164,12 @@ 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 = {
@@ -5051,7 +5188,8 @@ 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);
                     }
@@ -5287,12 +5425,11 @@ Current user's request: ${currentInput}`;
         this.activeToolExecutions.set(executionId, context);
         this.currentStreamToolExecutions.push(context);
         // Emit event (NeuroLinkEvents format for compatibility)
-        this.emitter.emit("tool:start", {
-            tool: toolName,
+        this.emitter.emit("tool:start", createToolEventPayload(toolName, {
             input,
             timestamp: startTime,
             executionId,
-        });
+        }));
         logger.debug(`tool:start emitted for ${toolName}`, {
             toolName,
             executionId,
@@ -5350,14 +5487,15 @@ Current user's request: ${currentInput}`;
         // Store in history
         this.toolExecutionHistory.push(summary);
         // Emit event (NeuroLinkEvents format for compatibility)
-        this.emitter.emit("tool:end", {
-            tool: toolName,
+        this.emitter.emit("tool:end", createToolEventPayload(toolName, {
             result,
             error,
+            success,
+            responseTime: duration,
             timestamp: endTime,
             duration,
             executionId: finalExecutionId,
-        });
+        }));
         logger.debug(`tool:end emitted for ${toolName}`, {
             toolName,
             executionId: finalExecutionId,
@@ -5460,7 +5598,9 @@ 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,
@@ -5517,7 +5657,9 @@ 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
@@ -5621,7 +5763,8 @@ 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
@@ -5639,10 +5782,14 @@ 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,
@@ -5663,14 +5810,18 @@ 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", {
@@ -5678,7 +5829,8 @@ 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,
                     });
@@ -5706,7 +5858,9 @@ 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()}`,
@@ -5802,361 +5956,345 @@ Current user's request: ${currentInput}`;
      * @returns Tool execution result
      */
     async executeTool(toolName, params = {}, options) {
-        const functionTag = "NeuroLink.executeTool";
-        const executionStartTime = Date.now();
-        // === MCP ENHANCEMENT: RequestBatcher — batch programmatic tool calls ===
-        // LIMITATION: When the request batcher is enabled, per-tool timeout and retry
-        // settings (from registration options or call-site options) are NOT applied.
-        // The batcher uses its own hardcoded defaults for timeout and retry behavior.
-        // Use `bypassBatcher: true` to ensure per-tool timeout/retry is respected.
-        // Additionally, note that executeToolInternal's safe-tool retry logic may still
-        // trigger even when maxRetries is set to 0, since it operates independently.
         if (this.mcpToolBatcher && !options?.bypassBatcher) {
             return this.mcpToolBatcher.execute(toolName, params);
         }
-        // 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";
-        // Compute truncated input size for the span
-        const inputStr = typeof params === "string" ? params : params ? JSON.stringify(params) : "";
-        const inputSize = inputStr.length;
-        const truncatedInput = inputStr.length > 2048 ? inputStr.substring(0, 2048) : inputStr;
+        const executionContext = this.createToolExecutionContext(toolName, params, options);
         return tracers.mcp.startActiveSpan("neurolink.tool.execute", {
             attributes: {
                 "tool.name": toolName,
-                "tool.type": toolType,
-                "tool.input_size": inputSize,
-                "tool.input_preview": truncatedInput,
+                "tool.type": executionContext.toolType,
+                "tool.input_size": executionContext.inputSize,
+                "tool.input_preview": executionContext.truncatedInput,
             },
-        }, async (toolSpan) => {
-            try {
-                // Debug: Log tool execution attempt
-                logger.debug(`[${functionTag}] Tool execution requested:`, {
-                    toolName,
-                    params: isNonNullObject(params) ? transformParamsForLogging(params) : params,
-                    hasExternalManager: !!this.externalServerManager,
-                });
-                // 🔧 PARAMETER TRACE: Log tool execution details for debugging
-                logger.debug(`Tool execution detailed analysis`, {
-                    toolName,
-                    executionStartTime,
-                    paramsAnalysis: {
-                        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,
+        }, (toolSpan) => this.executeToolWithSpan(toolName, params, options, executionContext, toolSpan));
+    }
+    createToolExecutionContext(toolName, params, options) {
+        const externalTool = this.externalServerManager
+            .getAllTools()
+            .find((tool) => tool.name === toolName);
+        const toolType = externalTool
+            ? "mcp"
+            : this.getCustomTools().has(toolName)
+                ? "custom"
+                : "external";
+        const inputStr = typeof params === "string"
+            ? params
+            : params
+                ? JSON.stringify(params)
+                : "";
+        return {
+            functionTag: "NeuroLink.executeTool",
+            executionStartTime: Date.now(),
+            externalTool,
+            toolType,
+            inputSize: inputStr.length,
+            truncatedInput: inputStr.length > 2048 ? inputStr.substring(0, 2048) : inputStr,
+            options,
+        };
+    }
+    async executeToolWithSpan(toolName, params, options, executionContext, toolSpan) {
+        try {
+            const prepared = await this.prepareToolExecutionState(toolName, params, options, executionContext);
+            return await this.runPreparedToolExecution(toolName, params, prepared, executionContext, toolSpan);
+        }
+        catch (outerError) {
+            if (!(outerError instanceof NeuroLinkError)) {
+                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 });
+            }
+            throw outerError;
+        }
+        finally {
+            toolSpan.end();
+        }
+    }
+    async prepareToolExecutionState(toolName, params, options, executionContext) {
+        logger.debug(`[${executionContext.functionTag}] Tool execution requested:`, {
+            toolName,
+            params: isNonNullObject(params)
+                ? transformParamsForLogging(params)
+                : params,
+            hasExternalManager: !!this.externalServerManager,
+        });
+        logger.debug(`Tool execution detailed analysis`, {
+            toolName,
+            executionStartTime: executionContext.executionStartTime,
+            paramsAnalysis: {
+                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,
+            },
+            isTargetTool: toolName === "juspay-analytics_SuccessRateSRByTime",
+            options,
+            hasExternalManager: !!this.externalServerManager,
+        });
+        this.emitter.emit("tool:start", createToolEventPayload(toolName, {
+            timestamp: executionContext.executionStartTime,
+            input: params,
+        }));
+        const toolInfo = this.toolRegistry.getToolInfo(toolName);
+        const finalOptions = {
+            timeout: options?.timeout ??
+                toolInfo?.tool?.timeoutMs ??
+                TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS,
+            maxRetries: options?.maxRetries ??
+                toolInfo?.tool?.maxRetries ??
+                RETRY_ATTEMPTS.DEFAULT,
+            retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS,
+            authContext: options?.authContext,
+            disableToolCache: options?.disableToolCache,
+        };
+        const { MemoryManager } = await import("./utils/performance.js");
+        const startMemory = MemoryManager.getMemoryUsageMB();
+        const breakerServerId = executionContext.externalTool?.serverId ||
+            toolInfo?.tool?.serverId ||
+            "unknown";
+        const breakerKey = `${breakerServerId}.${toolName}`;
+        let circuitBreaker = this.toolCircuitBreakers.get(breakerKey);
+        if (!circuitBreaker) {
+            circuitBreaker = new CircuitBreaker(CIRCUIT_BREAKER.FAILURE_THRESHOLD, CIRCUIT_BREAKER_RESET_MS);
+            this.toolCircuitBreakers.set(breakerKey, circuitBreaker);
+        }
+        let metrics = this.toolExecutionMetrics.get(toolName);
+        if (!metrics) {
+            metrics = {
+                totalExecutions: 0,
+                successfulExecutions: 0,
+                failedExecutions: 0,
+                averageExecutionTime: 0,
+                lastExecutionTime: 0,
+                errorCategories: {},
+            };
+            this.toolExecutionMetrics.set(toolName, metrics);
+        }
+        metrics.totalExecutions++;
+        return {
+            finalOptions,
+            startMemory,
+            circuitBreaker,
+            breakerKey,
+            metrics,
+        };
+    }
+    async runPreparedToolExecution(toolName, params, prepared, executionContext, toolSpan) {
+        try {
+            mcpLogger.debug(`[${executionContext.functionTag}] Executing tool: ${toolName}`, {
+                toolName,
+                params,
+                options: prepared.finalOptions,
+                circuitBreakerState: prepared.circuitBreaker.getState(),
+            });
+            const result = await prepared.circuitBreaker.execute(async () => {
+                return withRetry(async () => withTimeout(this.executeToolInternal(toolName, params, prepared.finalOptions), prepared.finalOptions.timeout, ErrorFactory.toolTimeout(toolName, prepared.finalOptions.timeout)), {
+                    maxAttempts: prepared.finalOptions.maxRetries + 1,
+                    delayMs: prepared.finalOptions.retryDelayMs,
+                    isRetriable: isRetriableError,
+                    onRetry: (attempt, error) => {
+                        mcpLogger.warn(`[${executionContext.functionTag}] Retrying tool execution (attempt ${attempt})`, {
+                            toolName,
+                            error: error.message,
+                            attempt,
+                        });
                     },
-                    isTargetTool: toolName === "juspay-analytics_SuccessRateSRByTime",
-                    options,
-                    hasExternalManager: !!this.externalServerManager,
                 });
-                // Emit tool start event (NeuroLink format - keep existing)
-                this.emitter.emit("tool:start", {
-                    toolName,
-                    timestamp: executionStartTime,
-                    input: params, // Enhanced: add input parameters
+            });
+            return await this.handleSuccessfulToolExecution(toolName, result, prepared, executionContext, toolSpan);
+        }
+        catch (error) {
+            return this.handleFailedToolExecution(toolName, params, error, prepared, executionContext, toolSpan);
+        }
+    }
+    async handleSuccessfulToolExecution(toolName, result, prepared, executionContext, toolSpan) {
+        const executionTime = Date.now() - executionContext.executionStartTime;
+        prepared.metrics.successfulExecutions++;
+        prepared.metrics.lastExecutionTime = executionTime;
+        prepared.metrics.averageExecutionTime =
+            (prepared.metrics.averageExecutionTime *
+                (prepared.metrics.successfulExecutions - 1) +
+                executionTime) /
+                prepared.metrics.successfulExecutions;
+        const { MemoryManager } = await import("./utils/performance.js");
+        const endMemory = MemoryManager.getMemoryUsageMB();
+        const memoryDelta = endMemory.heapUsed - prepared.startMemory.heapUsed;
+        if (memoryDelta > 20) {
+            mcpLogger.warn(`Tool '${toolName}' used excessive memory: ${memoryDelta}MB`, {
+                toolName,
+                memoryDelta,
+                executionTime,
+            });
+        }
+        mcpLogger.debug(`[${executionContext.functionTag}] Tool executed successfully`, {
+            toolName,
+            executionTime,
+            memoryDelta,
+            circuitBreakerState: prepared.circuitBreaker.getState(),
+        });
+        const resultObj = result && typeof result === "object"
+            ? result
+            : undefined;
+        const isToolError = (resultObj && "isError" in resultObj && resultObj.isError === true) ||
+            (resultObj && "success" in resultObj && resultObj.success === false);
+        if (isToolError) {
+            try {
+                await prepared.circuitBreaker.execute(async () => {
+                    throw new Error(`Tool ${toolName} returned isError:true`);
                 });
-                // NL-004: Use composite key (serverId.toolName) to avoid cross-server collisions
-                // Fetch toolInfo early so per-tool timeout is available for finalOptions
-                const toolInfo = this.toolRegistry.getToolInfo(toolName);
-                // Set default options — per-tool values from registration take precedence over global defaults.
-                // When not explicitly set at registration, global defaults are preserved for backward compatibility.
-                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,
-                    retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS,
-                    authContext: options?.authContext,
-                    disableToolCache: options?.disableToolCache,
-                };
-                // Track memory usage for tool execution
-                const { MemoryManager } = await import("./utils/performance.js");
-                const startMemory = MemoryManager.getMemoryUsageMB();
-                const breakerServerId = externalTool?.serverId || toolInfo?.tool?.serverId || "unknown";
-                const breakerKey = `${breakerServerId}.${toolName}`;
-                // Get or create circuit breaker for this tool
-                if (!this.toolCircuitBreakers.has(breakerKey)) {
-                    this.toolCircuitBreakers.set(breakerKey, new CircuitBreaker(CIRCUIT_BREAKER.FAILURE_THRESHOLD, CIRCUIT_BREAKER_RESET_MS));
-                }
-                const circuitBreaker = this.toolCircuitBreakers.get(breakerKey);
-                // Initialize metrics for this tool if not exists
-                if (!this.toolExecutionMetrics.has(toolName)) {
-                    this.toolExecutionMetrics.set(toolName, {
-                        totalExecutions: 0,
-                        successfulExecutions: 0,
-                        failedExecutions: 0,
-                        averageExecutionTime: 0,
-                        lastExecutionTime: 0,
-                        errorCategories: {},
-                    });
-                }
-                const metrics = this.toolExecutionMetrics.get(toolName);
-                if (metrics) {
-                    metrics.totalExecutions++;
-                }
-                try {
-                    mcpLogger.debug(`[${functionTag}] Executing tool: ${toolName}`, {
-                        toolName,
-                        params,
-                        options: finalOptions,
-                        circuitBreakerState: circuitBreaker?.getState(),
-                    });
-                    // Execute with circuit breaker, timeout, and retry logic
-                    if (!circuitBreaker) {
-                        throw new Error(`Circuit breaker not initialized for tool: ${toolName}`);
-                    }
-                    const result = await circuitBreaker.execute(async () => {
-                        return await withRetry(async () => {
-                            return await withTimeout(this.executeToolInternal(toolName, params, finalOptions), finalOptions.timeout, ErrorFactory.toolTimeout(toolName, finalOptions.timeout));
-                        }, {
-                            maxAttempts: finalOptions.maxRetries + 1, // +1 for initial attempt
-                            delayMs: finalOptions.retryDelayMs,
-                            isRetriable: isRetriableError,
-                            onRetry: (attempt, error) => {
-                                mcpLogger.warn(`[${functionTag}] Retrying tool execution (attempt ${attempt})`, {
-                                    toolName,
-                                    error: error.message,
-                                    attempt,
-                                });
-                            },
-                        });
-                    });
-                    // Update success metrics
-                    const executionTime = Date.now() - executionStartTime;
-                    if (metrics) {
-                        metrics.successfulExecutions++;
-                        metrics.lastExecutionTime = executionTime;
-                        metrics.averageExecutionTime =
-                            (metrics.averageExecutionTime * (metrics.successfulExecutions - 1) + executionTime) /
-                                metrics.successfulExecutions;
-                    }
-                    // Track memory usage
-                    const endMemory = MemoryManager.getMemoryUsageMB();
-                    const memoryDelta = endMemory.heapUsed - startMemory.heapUsed;
-                    if (memoryDelta > 20) {
-                        mcpLogger.warn(`Tool '${toolName}' used excessive memory: ${memoryDelta}MB`, {
-                            toolName,
-                            memoryDelta,
-                            executionTime,
-                        });
-                    }
-                    mcpLogger.debug(`[${functionTag}] Tool executed successfully`, {
-                        toolName,
-                        executionTime,
-                        memoryDelta,
-                        circuitBreakerState: circuitBreaker?.getState(),
-                    });
-                    // 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);
-                    // 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
-                    // success inside `circuitBreaker.execute()`. The correct fix is to check `isToolError`
-                    // inside the execute callback and throw before returning, so the breaker never sees
-                    // success. Deferred because moving the check inside the callback requires restructuring
-                    // the retry/timeout wrapper chain and is high-risk for a hot-path change.
-                    if (isToolError && circuitBreaker) {
-                        // Record a failure by executing a rejected promise through the breaker
-                        try {
-                            await circuitBreaker.execute(async () => {
-                                throw new Error(`Tool ${toolName} returned isError:true`);
-                            });
-                        }
-                        catch {
-                            // Expected — we intentionally triggered the failure recording
-                        }
-                        mcpLogger.debug(`[${functionTag}] Circuit breaker failure recorded for isError result`, {
-                            toolName,
-                            circuitBreakerState: circuitBreaker.getState(),
-                            circuitBreakerFailures: circuitBreaker.getFailureCount(),
-                        });
-                    }
-                    // NL-002 + NL-003: Format and capture MCP error results
-                    if (isToolError) {
-                        const resultObj = result;
-                        const contentArr = resultObj.content;
-                        const errorText = contentArr
-                            ?.filter((c) => c.type === "text" && c.text)
-                            .map((c) => c.text)
-                            .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
-                        if (contentArr && Array.isArray(contentArr)) {
-                            const clonedContent = contentArr.map((c) => ({ ...c }));
-                            for (const content of clonedContent) {
-                                if (content.type === "text" && content.text) {
-                                    content.text = prefix + content.text;
-                                    break; // Only prefix the first text content
-                                }
-                            }
-                            resultObj.content = clonedContent;
-                        }
-                        // NL-003: Capture error details in span attributes for telemetry
-                        toolSpan.setAttribute("tool.error.message", errorText.substring(0, 500));
-                        toolSpan.setAttribute("tool.error.category", errorCategory);
-                        toolSpan.setStatus({
-                            code: SpanStatusCode.ERROR,
-                            message: `MCP tool returned isError: ${errorText.substring(0, 200)}`,
-                        });
-                        if (metrics) {
-                            metrics.failedExecutions++;
-                            const prevSuccessful = metrics.successfulExecutions;
-                            metrics.successfulExecutions = Math.max(0, metrics.successfulExecutions - 1);
-                            // Recompute averageExecutionTime: back out this execution's duration
-                            // which was incorrectly included as a success
-                            if (prevSuccessful > 1) {
-                                metrics.averageExecutionTime =
-                                    (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;
-                        }
-                    }
-                    // Emit tool end event AFTER isError check so success flag is correct
-                    this.emitToolEndEvent(toolName, executionStartTime, !isToolError, result);
-                    toolSpan.setAttribute("tool.result.status", isToolError ? "error" : "success");
-                    toolSpan.setAttribute("tool.duration_ms", executionTime);
-                    return result;
-                }
-                catch (error) {
-                    // Update failure metrics
-                    if (metrics) {
-                        metrics.failedExecutions++;
-                    }
-                    const executionTime = Date.now() - executionStartTime;
-                    // Circuit breaker open: return a structured non-retryable isError result
-                    // so the AI model understands the tool is temporarily unavailable.
-                    // Log at warn (not error) since this is expected circuit breaker behavior.
-                    if (error instanceof CircuitBreakerOpenError) {
-                        mcpLogger.warn(`[${functionTag}] Tool blocked by circuit breaker: ${toolName}`, {
-                            toolName,
-                            breakerState: error.breakerState,
-                            retryAfter: error.retryAfter,
-                            retryAfterMs: error.retryAfterMs,
-                            failureCount: error.failureCount,
-                            executionTime,
-                        });
-                        if (metrics) {
-                            const category = ErrorCategory.EXECUTION;
-                            metrics.errorCategories[category] = (metrics.errorCategories[category] || 0) + 1;
-                        }
-                        // Emit tool end event for circuit breaker open
-                        this.emitToolEndEvent(toolName, executionStartTime, false, undefined);
-                        toolSpan.setAttribute("tool.result.status", "circuit_breaker_open");
-                        toolSpan.setAttribute("tool.duration_ms", executionTime);
-                        toolSpan.setAttribute("tool.circuit_breaker.state", error.breakerState);
-                        toolSpan.setAttribute("tool.circuit_breaker.retry_after_ms", error.retryAfterMs);
-                        toolSpan.setAttribute("tool.circuit_breaker.failure_count", error.failureCount);
-                        toolSpan.setStatus({
-                            code: SpanStatusCode.ERROR,
-                            message: `Circuit breaker open for ${toolName}: ${error.message}`,
-                        });
-                        // Return an isError tool result so the AI can inform the user
-                        // instead of throwing, which would cause a generic retry
-                        return {
-                            isError: true,
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `TOOL TEMPORARILY UNAVAILABLE: "${toolName}" has been disabled after ` +
-                                        `${error.failureCount} failures. ` +
-                                        `This is a circuit breaker protection — do NOT retry this tool. ` +
-                                        `It will become available again after ${Math.ceil(error.retryAfterMs / 1000)} seconds ` +
-                                        `(at ${error.retryAfter}). ` +
-                                        `Instead, inform the user that the operation failed and suggest trying again later.`,
-                                },
-                            ],
-                        };
-                    }
-                    // Create structured error
-                    let structuredError;
-                    if (error instanceof NeuroLinkError) {
-                        structuredError = error;
-                    }
-                    else if (error instanceof Error) {
-                        // Categorize the error based on the message
-                        if (error.message.includes("timeout")) {
-                            structuredError = ErrorFactory.toolTimeout(toolName, finalOptions.timeout);
-                        }
-                        else if (error.message.includes("not found")) {
-                            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")) {
-                            structuredError = ErrorFactory.invalidParameters(toolName, error, params);
-                        }
-                        else if (error.message.includes("network") || error.message.includes("connection")) {
-                            structuredError = ErrorFactory.networkError(toolName, error);
-                        }
-                        else {
-                            structuredError = ErrorFactory.toolExecutionFailed(toolName, error);
-                        }
-                    }
-                    else {
-                        structuredError = ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
-                    }
-                    if (metrics) {
-                        const category = structuredError.category || ErrorCategory.EXECUTION;
-                        metrics.errorCategories[category] = (metrics.errorCategories[category] || 0) + 1;
+            }
+            catch {
+                // Expected — intentionally records the failure
+            }
+            mcpLogger.debug(`[${executionContext.functionTag}] Circuit breaker failure recorded for isError result`, {
+                toolName,
+                circuitBreakerState: prepared.circuitBreaker.getState(),
+                circuitBreakerFailures: prepared.circuitBreaker.getFailureCount(),
+            });
+            const contentArr = resultObj?.content;
+            const errorText = contentArr
+                ?.filter((content) => content.type === "text" && content.text)
+                .map((content) => content.text)
+                .join(" ") ||
+                (typeof resultObj?.error === "string"
+                    ? resultObj.error
+                    : "Unknown error");
+            const errorCategory = classifyMcpErrorMessage(errorText);
+            const prefix = `[TOOL_ERROR: ${toolName} failed (${errorCategory})] `;
+            if (resultObj && Array.isArray(contentArr)) {
+                const clonedContent = contentArr.map((content) => ({ ...content }));
+                for (const content of clonedContent) {
+                    if (content.type === "text" && content.text) {
+                        content.text = prefix + content.text;
+                        break;
                     }
-                    // Emit tool end event BEFORE the error event.
-                    // Node.js EventEmitter throws on unhandled 'error' events,
-                    // which would prevent tool:end from being emitted.
-                    this.emitToolEndEvent(toolName, executionStartTime, false, undefined, structuredError);
-                    // Centralized error event emission
-                    this.emitter.emit("error", structuredError);
-                    // Add execution context to structured error
-                    structuredError = new NeuroLinkError({
-                        ...structuredError,
-                        context: {
-                            ...structuredError.context,
-                            executionTime,
-                            params,
-                            options: finalOptions,
-                            circuitBreakerState: circuitBreaker?.getState(),
-                            circuitBreakerFailures: circuitBreaker?.getFailureCount(),
-                            metrics: { ...metrics },
-                        },
-                    });
-                    // Log structured error
-                    logStructuredError(structuredError);
-                    // Record error on span
-                    toolSpan.setAttribute("tool.result.status", "error");
-                    toolSpan.setAttribute("tool.duration_ms", executionTime);
-                    toolSpan.recordException(structuredError);
-                    toolSpan.setStatus({
-                        code: SpanStatusCode.ERROR,
-                        message: structuredError.message,
-                    });
-                    throw structuredError;
                 }
+                resultObj.content = clonedContent;
             }
-            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);
-                    toolSpan.recordException(outerError instanceof Error ? outerError : new Error(errMsg));
-                    toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
-                }
-                throw outerError;
+            toolSpan.setAttribute("tool.error.message", errorText.substring(0, 500));
+            toolSpan.setAttribute("tool.error.category", errorCategory);
+            toolSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: `MCP tool returned isError: ${errorText.substring(0, 200)}`,
+            });
+            prepared.metrics.failedExecutions++;
+            const prevSuccessful = prepared.metrics.successfulExecutions;
+            prepared.metrics.successfulExecutions = Math.max(0, prepared.metrics.successfulExecutions - 1);
+            prepared.metrics.averageExecutionTime =
+                prevSuccessful > 1
+                    ? (prepared.metrics.averageExecutionTime * prevSuccessful -
+                        executionTime) /
+                        (prevSuccessful - 1)
+                    : 0;
+            const mappedCategory = mcpCategoryToErrorCategory(errorCategory);
+            prepared.metrics.errorCategories[mappedCategory] =
+                (prepared.metrics.errorCategories[mappedCategory] || 0) + 1;
+        }
+        this.emitToolEndEvent(toolName, executionContext.executionStartTime, !isToolError, result);
+        toolSpan.setAttribute("tool.result.status", isToolError ? "error" : "success");
+        toolSpan.setAttribute("tool.duration_ms", executionTime);
+        return result;
+    }
+    async handleFailedToolExecution(toolName, params, error, prepared, executionContext, toolSpan) {
+        prepared.metrics.failedExecutions++;
+        const executionTime = Date.now() - executionContext.executionStartTime;
+        if (error instanceof CircuitBreakerOpenError) {
+            mcpLogger.warn(`[${executionContext.functionTag}] Tool blocked by circuit breaker: ${toolName}`, {
+                toolName,
+                breakerState: error.breakerState,
+                retryAfter: error.retryAfter,
+                retryAfterMs: error.retryAfterMs,
+                failureCount: error.failureCount,
+                executionTime,
+            });
+            prepared.metrics.errorCategories[ErrorCategory.EXECUTION] =
+                (prepared.metrics.errorCategories[ErrorCategory.EXECUTION] || 0) + 1;
+            this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined);
+            toolSpan.setAttribute("tool.result.status", "circuit_breaker_open");
+            toolSpan.setAttribute("tool.duration_ms", executionTime);
+            toolSpan.setAttribute("tool.circuit_breaker.state", error.breakerState);
+            toolSpan.setAttribute("tool.circuit_breaker.retry_after_ms", error.retryAfterMs);
+            toolSpan.setAttribute("tool.circuit_breaker.failure_count", error.failureCount);
+            toolSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: `Circuit breaker open for ${toolName}: ${error.message}`,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `TOOL TEMPORARILY UNAVAILABLE: "${toolName}" has been disabled after ` +
+                            `${error.failureCount} failures. ` +
+                            `This is a circuit breaker protection — do NOT retry this tool. ` +
+                            `It will become available again after ${Math.ceil(error.retryAfterMs / 1000)} seconds ` +
+                            `(at ${error.retryAfter}). ` +
+                            `Instead, inform the user that the operation failed and suggest trying again later.`,
+                    },
+                ],
+            };
+        }
+        let structuredError;
+        if (error instanceof NeuroLinkError) {
+            structuredError = error;
+        }
+        else if (error instanceof Error) {
+            if (error.message.includes("timeout")) {
+                structuredError = ErrorFactory.toolTimeout(toolName, prepared.finalOptions.timeout);
             }
-            finally {
-                toolSpan.end();
+            else if (error.message.includes("not found")) {
+                const availableTools = await this.getAllAvailableTools();
+                structuredError = ErrorFactory.toolNotFound(toolName, extractToolNames(availableTools.map((tool) => ({ name: tool.name }))));
+            }
+            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")) {
+                structuredError = ErrorFactory.networkError(toolName, error);
+            }
+            else {
+                structuredError = ErrorFactory.toolExecutionFailed(toolName, error);
             }
+        }
+        else {
+            structuredError = ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
+        }
+        const category = structuredError.category || ErrorCategory.EXECUTION;
+        prepared.metrics.errorCategories[category] =
+            (prepared.metrics.errorCategories[category] || 0) + 1;
+        this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, structuredError);
+        this.emitter.emit("error", structuredError);
+        structuredError = new NeuroLinkError({
+            ...structuredError,
+            context: {
+                ...structuredError.context,
+                executionTime,
+                params,
+                options: prepared.finalOptions,
+                circuitBreakerState: prepared.circuitBreaker.getState(),
+                circuitBreakerFailures: prepared.circuitBreaker.getFailureCount(),
+                metrics: { ...prepared.metrics },
+            },
         });
+        logStructuredError(structuredError);
+        toolSpan.setAttribute("tool.result.status", "error");
+        toolSpan.setAttribute("tool.duration_ms", executionTime);
+        toolSpan.recordException(structuredError);
+        toolSpan.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: structuredError.message,
+        });
+        throw structuredError;
     }
     /**
      * Internal tool execution method with MCP enhancements wired in:
@@ -6234,7 +6372,9 @@ 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,
@@ -6290,7 +6430,10 @@ 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);
@@ -6328,7 +6471,10 @@ 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);
@@ -6373,7 +6519,8 @@ 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;
         }
@@ -6454,7 +6601,9 @@ 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,
                         }),
@@ -6610,7 +6759,9 @@ 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,
                         };
                     }
@@ -6733,7 +6884,9 @@ 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,
@@ -6802,7 +6955,8 @@ 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;
         }
@@ -6922,7 +7076,9 @@ 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;
@@ -6942,7 +7098,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(),
@@ -6995,7 +7151,8 @@ 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++;
             }
@@ -7036,7 +7193,9 @@ 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",
@@ -7188,7 +7347,8 @@ 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,
@@ -7198,7 +7358,8 @@ 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);
         }
@@ -7217,7 +7378,9 @@ 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);
     }
     /**
@@ -7736,7 +7899,8 @@ 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,
@@ -7768,7 +7932,9 @@ 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;
                         }
@@ -8184,7 +8350,9 @@ 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);
             }
@@ -8196,7 +8364,9 @@ 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);
                 }
@@ -8210,7 +8380,9 @@ 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);
                 }
@@ -8223,7 +8395,9 @@ 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);
                 }
@@ -8260,7 +8434,9 @@ 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);
             }
@@ -8286,7 +8462,9 @@ 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);
             }
@@ -8330,8 +8508,11 @@ 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({
@@ -8406,7 +8587,8 @@ Current user's request: ${currentInput}`;
         let provider;
         let providerType;
         // Duck-type check: direct MastraAuthProvider instance
-        if ("authenticateToken" in config && typeof config.authenticateToken === "function") {
+        if ("authenticateToken" in config &&
+            typeof config.authenticateToken === "function") {
             provider = config;
             providerType = provider.type;
         }
@@ -8450,7 +8632,8 @@ Current user's request: ${currentInput}`;
             }
             finally {
                 if (this.authInitPromise &&
-                    (this.pendingAuthConfig === undefined || this.pendingAuthConfig === pendingAuthConfig)) {
+                    (this.pendingAuthConfig === undefined ||
+                        this.pendingAuthConfig === pendingAuthConfig)) {
                     this.authInitPromise = undefined;
                 }
             }