@juspay/neurolink 9.41.0 → 9.42.1

package/dist/lib/neurolink.js

@@ -50,18 +50,21 @@ import { getMetricsAggregator, MetricsAggregator, } from "./observability/metric
 import { SpanStatus, SpanType } from "./observability/types/spanTypes.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { flushOpenTelemetry, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
+import { TaskManager } from "./tasks/taskManager.js";
+import { createTaskTools } from "./tasks/tools/taskTools.js";
 import { ATTR } from "./telemetry/attributes.js";
 import { tracers } from "./telemetry/tracers.js";
+import { CircuitBreakerOpenError } from "./types/circuitBreakerErrors.js";
 import { ConversationMemoryError } from "./types/conversation.js";
 import { AuthenticationError, AuthorizationError, InvalidModelError, } from "./types/errors.js";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
 import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
-import { CircuitBreakerOpenError } from "./types/circuitBreakerErrors.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
+import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { getBestProvider } from "./utils/providerUtils.js";
@@ -72,11 +75,8 @@ import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Transformation utilities
 import { extractToolNames, optimizeToolForCollection, transformAvailableTools, transformParamsForLogging, transformToolExecutions, transformToolExecutionsForMCP, transformToolsForMCP, transformToolsToDescriptions, transformToolsToExpectedFormat, } from "./utils/transformationUtils.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
-import { resolveModel } from "./utils/modelAliasResolver.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
-import { TaskManager } from "./tasks/taskManager.js";
-import { createTaskTools } from "./tasks/tools/taskTools.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
  * Returns a human-readable error category based on error message content.
@@ -339,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) {
@@ -2336,426 +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,
-                                        onFinish: options.onFinish,
-                                        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.
@@ -3084,253 +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
@@ -3529,292 +3541,21 @@ Current user's request: ${currentInput}`;
         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
@@ -3843,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)
      */
@@ -4210,360 +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,
+            });
+            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),
             });
-            const spanStartTime = Date.now();
-            // MCP Enhancement: propagate disableToolCache to tool execution
-            this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
+            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 {
-                // 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,
-                        },
-                    });
+                for await (const chunk of originalWorkflowStream) {
+                    yield chunk;
                 }
-                // 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;
+                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)}`);
-                    }
-                    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");
+                        yield chunk;
                     }
-                    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,
-                                    onFinish: options.onFinish,
-                                    onError: options.onError,
-                                    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, analytics: streamAnalytics, } = await this.createMCPStream(enhancedOptions);
-                        // Update span with resolved provider name
-                        streamSpan.setAttribute(ATTR.NL_PROVIDER, providerName || "unknown");
-                        let accumulatedContent = "";
-                        let chunkCount = 0;
-                        // Set up event capture listeners
-                        const { eventSequence, cleanup: cleanupListeners } = this.setupStreamEventListeners();
-                        const metadata = {
-                            fallbackAttempted: false,
-                            guardrailsBlocked: false,
-                            error: undefined,
-                            fallbackProvider: undefined,
-                            fallbackModel: undefined,
-                        };
-                        const self = this;
-                        const streamStartTime = Date.now();
-                        const sessionId = enhancedOptions.context?.sessionId;
-                        const processedStream = (async function* () {
-                            let streamError;
-                            try {
-                                for await (const chunk of mcpStream) {
-                                    chunkCount++;
-                                    if (chunk &&
-                                        "content" in chunk &&
-                                        typeof chunk.content === "string") {
-                                        accumulatedContent += chunk.content;
-                                        self.emitter.emit("response:chunk", chunk.content);
-                                        // Emit stream:chunk event (Observability Solution 8)
-                                        self.emitter.emit("stream:chunk", {
-                                            type: "stream:chunk",
-                                            content: chunk.content,
-                                            metadata: {
-                                                chunkIndex: chunkCount,
-                                                totalLength: accumulatedContent.length,
-                                            },
-                                            timestamp: Date.now(),
-                                        });
-                                    }
-                                    yield chunk;
-                                }
-                                if (chunkCount === 0 && !metadata.fallbackAttempted) {
-                                    yield* self.handleStreamFallback(metadata, originalPrompt, enhancedOptions, providerName, accumulatedContent, (content) => {
-                                        accumulatedContent += content;
-                                    });
-                                }
-                                // Emit stream:complete event (Observability Solution 8)
-                                // When fallback took over, attribute the completion to the
-                                // fallback provider so downstream telemetry reflects reality.
-                                const effectiveProvider = metadata.fallbackProvider ?? providerName;
-                                const effectiveModel = metadata.fallbackModel ??
-                                    streamModel ??
-                                    enhancedOptions.model;
-                                // Resolve analytics promise to get final token usage
-                                let resolvedUsage = streamUsage;
-                                if (!resolvedUsage && streamAnalytics) {
-                                    try {
-                                        const resolved = await Promise.resolve(streamAnalytics);
-                                        if (resolved?.tokenUsage) {
-                                            resolvedUsage = resolved.tokenUsage;
-                                        }
-                                    }
-                                    catch {
-                                        /* non-blocking */
-                                    }
-                                }
-                                self.emitter.emit("stream:complete", {
-                                    type: "stream:complete",
-                                    content: accumulatedContent,
-                                    provider: effectiveProvider,
-                                    model: effectiveModel,
-                                    prompt: enhancedOptions.input?.text ||
-                                        enhancedOptions.prompt,
-                                    metadata: {
-                                        chunkCount,
-                                        totalLength: accumulatedContent.length,
-                                        durationMs: Date.now() - streamStartTime,
-                                        sessionId,
-                                        usage: resolvedUsage,
-                                        ...(metadata.fallbackAttempted && {
-                                            primaryProvider: providerName,
-                                            primaryModel: enhancedOptions.model,
-                                            fallback: true,
-                                        }),
-                                    },
-                                    timestamp: Date.now(),
-                                });
-                            }
-                            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);
-                        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) {
-                        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,
@@ -4745,7 +4704,7 @@ Current user's request: ${currentInput}`;
      * Handle fallback when the primary stream returns 0 chunks.
      * Yields chunks from a fallback provider and updates metadata accordingly.
      */
-    async *handleStreamFallback(metadata, originalPrompt, enhancedOptions, providerName, _accumulatedContent, appendContent) {
+    async *handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, appendContent) {
         metadata.fallbackAttempted = true;
         const errorMsg = "Stream completed with 0 chunks (possible guardrails block)";
         metadata.error = errorMsg;
@@ -4803,6 +4762,14 @@ Current user's request: ${currentInput}`;
                 model: fallbackRoute.model,
                 conversationMessages,
             });
+            const fallbackToolCalls = fallbackResult.toolCalls ?? [];
+            const fallbackToolResults = fallbackResult.toolResults ?? [];
+            if (fallbackToolCalls.length > 0 || fallbackToolResults.length > 0) {
+                streamState.toolCalls = fallbackToolCalls;
+                streamState.toolResults = fallbackToolResults;
+                streamState.finishReason =
+                    fallbackResult.finishReason ?? streamState.finishReason;
+            }
             let fallbackChunkCount = 0;
             for await (const fallbackChunk of fallbackResult.stream) {
                 fallbackChunkCount++;
@@ -4814,7 +4781,9 @@ Current user's request: ${currentInput}`;
                 }
                 yield fallbackChunk;
             }
-            if (fallbackChunkCount === 0) {
+            if (fallbackChunkCount === 0 &&
+                fallbackToolCalls.length === 0 &&
+                fallbackToolResults.length === 0) {
                 throw new Error(`Fallback provider ${fallbackRoute.provider} also returned 0 chunks`);
             }
             // Fallback succeeded - likely guardrails blocked primary
@@ -5059,6 +5028,9 @@ Current user's request: ${currentInput}`;
             provider: providerName,
             usage: streamResult.usage,
             model: streamResult.model || options.model,
+            finishReason: streamResult.finishReason,
+            toolCalls: streamResult.toolCalls ?? [],
+            toolResults: streamResult.toolResults ?? [],
             analytics: streamResult.analytics,
         };
     }
@@ -5601,7 +5573,8 @@ Current user's request: ${currentInput}`;
             // (direct executeTool() or AI SDK generateText() tool calling).
             if (options?.timeout !== undefined &&
                 options.timeout > 0 &&
-                Number.isFinite(options.timeout)) {
+                Number.isFinite(options.timeout) &&
+                typeof convertedTool.execute === "function") {
                 const originalExecute = convertedTool.execute;
                 const toolTimeout = options.timeout;
                 const toolName = name;
@@ -5623,7 +5596,7 @@ Current user's request: ${currentInput}`;
                         new Promise((_, reject) => {
                             composedSignal.addEventListener("abort", () => {
                                 if (timeoutSignal.aborted) {
-                                    reject(new Error(`Tool '${toolName}' timed out after ${toolTimeout}ms (configured at registration)`));
+                                    reject(ErrorFactory.toolTimeout(toolName, toolTimeout));
                                 }
                                 else {
                                     reject(new DOMException("The operation was aborted", "AbortError"));
@@ -5968,401 +5941,346 @@ 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 executionContext = this.createToolExecutionContext(toolName, params, options);
+        return tracers.mcp.startActiveSpan("neurolink.tool.execute", {
+            attributes: {
+                "tool.name": toolName,
+                "tool.type": executionContext.toolType,
+                "tool.input_size": executionContext.inputSize,
+                "tool.input_preview": executionContext.truncatedInput,
+            },
+        }, (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";
-        // 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;
-        return tracers.mcp.startActiveSpan("neurolink.tool.execute", {
-            attributes: {
-                "tool.name": toolName,
-                "tool.type": toolType,
-                "tool.input_size": inputSize,
-                "tool.input_preview": truncatedInput,
+        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,
             },
-        }, 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,
+            isTargetTool: toolName === "juspay-analytics_SuccessRateSRByTime",
+            options,
+            hasExternalManager: !!this.externalServerManager,
+        });
+        this.emitter.emit("tool:start", {
+            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:
@@ -6379,9 +6297,17 @@ Current user's request: ${currentInput}`;
             !options.disableToolCache &&
             !this._disableToolCacheForCurrentRequest &&
             !toolAnnotations?.destructiveHint;
+        const toolResultCache = this.mcpToolResultCache;
         // === MCP ENHANCEMENT: Cache check (before execution) ===
-        if (isCacheEnabled) {
-            const cached = this.mcpToolResultCache.getCachedResult(toolName, params);
+        // Scope cache key by auth context to prevent cross-user cache leaks
+        const cacheParams = options.authContext || this.toolExecutionContext
+            ? {
+                __args: params,
+                __ctx: options.authContext ?? this.toolExecutionContext,
+            }
+            : params;
+        if (isCacheEnabled && toolResultCache) {
+            const cached = toolResultCache.getCachedResult(toolName, cacheParams);
             if (cached !== undefined) {
                 logger.debug(`[${functionTag}] Cache HIT for tool: ${toolName}`);
                 return cached;
@@ -6515,8 +6441,8 @@ Current user's request: ${currentInput}`;
         try {
             const result = await executeWithMiddleware(executeCore);
             // === MCP ENHANCEMENT: Cache store (after successful execution) ===
-            if (isCacheEnabled && result !== undefined) {
-                this.mcpToolResultCache.cacheResult(toolName, params, result);
+            if (isCacheEnabled && toolResultCache && result !== undefined) {
+                toolResultCache.cacheResult(toolName, cacheParams, result);
                 logger.debug(`[${functionTag}] Cached result for tool: ${toolName}`);
             }
             return result;
@@ -6539,8 +6465,8 @@ Current user's request: ${currentInput}`;
                 try {
                     const retryResult = await executeWithMiddleware(executeCore);
                     // Cache the retry result
-                    if (isCacheEnabled && retryResult !== undefined) {
-                        this.mcpToolResultCache.cacheResult(toolName, params, retryResult);
+                    if (isCacheEnabled && toolResultCache && retryResult !== undefined) {
+                        toolResultCache.cacheResult(toolName, cacheParams, retryResult);
                     }
                     return retryResult;
                 }
@@ -8641,28 +8567,33 @@ Current user's request: ${currentInput}`;
     async setAuthProvider(config) {
         // Clear any pending lazy-init promise so it does not race with this call.
         this.authInitPromise = undefined;
+        await this.initializeAuthProviderFromConfig(config);
+    }
+    async initializeAuthProviderFromConfig(config) {
+        let provider;
+        let providerType;
         // Duck-type check: direct MastraAuthProvider instance
         if ("authenticateToken" in config &&
             typeof config.authenticateToken === "function") {
-            this.authProvider = config;
-            logger.info(`Auth provider set: ${this.authProvider.type}`);
+            provider = config;
+            providerType = provider.type;
         }
         else if ("provider" in config) {
-            this.authProvider = config.provider;
-            logger.info(`Auth provider set: ${this.authProvider.type}`);
+            provider = config.provider;
+            providerType = provider.type;
         }
         else {
             const typedConfig = config;
             const { AuthProviderFactory } = await import("./auth/AuthProviderFactory.js");
-            this.authProvider = await AuthProviderFactory.createProvider(typedConfig.type, typedConfig.config);
-            logger.info(`Auth provider created and set: ${typedConfig.type}`);
-        }
-        if (this.authProvider) {
-            this.emitter.emit("auth:provider:set", {
-                type: this.authProvider.type,
-                timestamp: Date.now(),
-            });
+            provider = await AuthProviderFactory.createProvider(typedConfig.type, typedConfig.config);
+            providerType = typedConfig.type;
         }
+        this.authProvider = provider;
+        logger.info(`Auth provider set: ${providerType}`);
+        this.emitter.emit("auth:provider:set", {
+            type: provider.type,
+            timestamp: Date.now(),
+        });
     }
     /**
      * Get the currently configured authentication provider
@@ -8679,14 +8610,18 @@ Current user's request: ${currentInput}`;
         if (this.authProvider || !this.pendingAuthConfig) {
             return;
         }
+        const pendingAuthConfig = this.pendingAuthConfig;
         this.authInitPromise ??= (async () => {
             try {
-                await this.setAuthProvider(this.pendingAuthConfig);
+                await this.initializeAuthProviderFromConfig(pendingAuthConfig);
                 this.pendingAuthConfig = undefined;
             }
-            catch (err) {
-                this.authInitPromise = undefined;
-                throw err;
+            finally {
+                if (this.authInitPromise &&
+                    (this.pendingAuthConfig === undefined ||
+                        this.pendingAuthConfig === pendingAuthConfig)) {
+                    this.authInitPromise = undefined;
+                }
             }
         })();
         await this.authInitPromise;