@juspay/neurolink 9.10.0 → 9.11.0

package/dist/lib/neurolink.js

@@ -15,12 +15,14 @@ catch {
 }
 import { EventEmitter } from "events";
 import pLimit from "p-limit";
+import { ErrorCategory, ErrorSeverity } from "./constants/enums.js";
 import { CIRCUIT_BREAKER, CIRCUIT_BREAKER_RESET_MS, MEMORY_THRESHOLDS, NANOSECOND_TO_MS_DIVISOR, PERFORMANCE_THRESHOLDS, PROVIDER_TIMEOUTS, RETRY_ATTEMPTS, RETRY_DELAYS, TOOL_TIMEOUTS, } from "./constants/index.js";
 import { checkContextBudget } from "./context/budgetChecker.js";
 import { ContextCompactor, } from "./context/contextCompactor.js";
 import { isContextOverflowError } from "./context/errorDetection.js";
 import { repairToolPairs } from "./context/toolPairRepair.js";
 import { SYSTEM_LIMITS } from "./core/constants.js";
+import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { AIProviderFactory } from "./core/factory.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
 import { FileReferenceRegistry } from "./files/fileReferenceRegistry.js";
@@ -31,10 +33,11 @@ import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import { initializeMem0 } from "./memory/mem0Initializer.js";
+import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { flushOpenTelemetry, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
-import { CircuitBreaker, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
+import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
@@ -171,6 +174,8 @@ export class NeuroLink {
     // Mem0 memory instance and config for conversation context
     mem0Instance;
     mem0Config;
+    // Accumulated cost in USD across all generate() calls on this instance
+    _sessionCostUsd = 0;
     // File Reference Registry for lazy on-demand file processing
     fileRegistry;
     // Cached file tools to avoid redundant createFileTools() calls per generate/stream
@@ -184,11 +189,42 @@ export class NeuroLink {
             options.context !== null) {
             try {
                 const ctx = options.context;
-                if (ctx.userId || ctx.sessionId) {
+                // Trigger context scoping if any meaningful Langfuse field is present
+                if (ctx.userId ||
+                    ctx.sessionId ||
+                    ctx.conversationId ||
+                    ctx.requestId ||
+                    ctx.traceName ||
+                    ctx.metadata) {
+                    // Build customAttributes from top-level metadata string/number/boolean fields
+                    let customAttributes;
+                    if (ctx.metadata && typeof ctx.metadata === "object") {
+                        const metaObj = ctx.metadata;
+                        const attrs = {};
+                        for (const [k, v] of Object.entries(metaObj)) {
+                            if (typeof v === "string" ||
+                                typeof v === "number" ||
+                                typeof v === "boolean") {
+                                attrs[k] = v;
+                            }
+                        }
+                        if (Object.keys(attrs).length > 0) {
+                            customAttributes = attrs;
+                        }
+                    }
                     return await new Promise((resolve, reject) => {
                         setLangfuseContext({
                             userId: typeof ctx.userId === "string" ? ctx.userId : null,
                             sessionId: typeof ctx.sessionId === "string" ? ctx.sessionId : null,
+                            conversationId: typeof ctx.conversationId === "string"
+                                ? ctx.conversationId
+                                : null,
+                            requestId: typeof ctx.requestId === "string" ? ctx.requestId : null,
+                            traceName: typeof ctx.traceName === "string" ? ctx.traceName : null,
+                            metadata: ctx.metadata && typeof ctx.metadata === "object"
+                                ? ctx.metadata
+                                : null,
+                            ...(customAttributes !== undefined && { customAttributes }),
                         }, async () => {
                             try {
                                 const result = await callback();
@@ -315,6 +351,7 @@ export class NeuroLink {
         this.initializeExternalServerManager(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeHITL(config, constructorId, constructorStartTime, constructorHrTimeStart);
         this.registerFileTools();
+        this.registerMemoryRetrievalTools();
         this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
     }
@@ -518,6 +555,104 @@ export class NeuroLink {
             logger.debug(`[NeuroLink] Registered ${Object.keys(fileTools).length} file reference tools`);
         });
     }
+    /**
+     * Register memory retrieval tools that allow the AI to access
+     * conversation history, including full tool outputs.
+     * Only registered when Redis conversation memory is active.
+     */
+    registerMemoryRetrievalTools() {
+        // Check if conversation memory is configured
+        // Memory retrieval tool requires Redis (getSessionRaw) but registration
+        // is deferred — the execute handler checks at runtime whether the actual
+        // memory manager supports getSessionRaw.
+        const memConfig = this.conversationMemoryConfig?.conversationMemory;
+        const hasRedisConfig = !!memConfig?.redisConfig ||
+            (memConfig &&
+                "redis" in memConfig &&
+                !!memConfig.redis) ||
+            process.env.STORAGE_TYPE === "redis";
+        if (!memConfig?.enabled || !hasRedisConfig) {
+            logger.debug("[NeuroLink] Skipping memory retrieval tools — requires Redis conversation memory");
+            return;
+        }
+        // Defer registration until conversation memory is actually initialized
+        // We register a placeholder that will use the lazy-initialized memory manager
+        const self = this;
+        const tools = {
+            retrieve_context: {
+                description: "Retrieve messages from conversation memory. Use this to access full tool " +
+                    "outputs when a result was truncated, review previous assistant responses, " +
+                    "or search through conversation history.",
+                execute: async (params) => {
+                    // Lazy access: conversationMemory is initialized on first generate() call
+                    const memoryManager = self.conversationMemory;
+                    if (!memoryManager || !("getSessionRaw" in memoryManager)) {
+                        return {
+                            success: false,
+                            error: "Memory retrieval not available — Redis memory manager not initialized",
+                            metadata: {
+                                toolName: "retrieve_context",
+                                serverId: "direct",
+                                executionTime: 0,
+                            },
+                        };
+                    }
+                    const actualTools = createMemoryRetrievalTools(memoryManager);
+                    const result = await actualTools.retrieve_context.execute(params, {
+                        toolCallId: "memory-retrieval",
+                        messages: [],
+                    });
+                    // Check if the tool itself reported an error
+                    const hasError = result &&
+                        typeof result === "object" &&
+                        "error" in result &&
+                        !("messages" in result);
+                    const errorMsg = hasError
+                        ? result.error
+                        : undefined;
+                    return {
+                        success: !hasError,
+                        data: result,
+                        ...(errorMsg ? { error: errorMsg } : {}),
+                        metadata: {
+                            toolName: "retrieve_context",
+                            serverId: "direct",
+                            executionTime: 0,
+                        },
+                    };
+                },
+            },
+        };
+        const registrations = Object.entries(tools).map(async ([toolName, toolDef]) => {
+            const toolId = `direct.${toolName}`;
+            const toolInfo = {
+                name: toolName,
+                description: toolDef.description,
+                inputSchema: {},
+                serverId: "direct",
+                category: "built-in",
+            };
+            await this.toolRegistry.registerTool(toolId, toolInfo, {
+                execute: async (params) => {
+                    try {
+                        return await toolDef.execute(params);
+                    }
+                    catch (error) {
+                        return {
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                            metadata: { toolName, serverId: "direct", executionTime: 0 },
+                        };
+                    }
+                },
+                description: toolDef.description,
+                inputSchema: {},
+            });
+        });
+        void Promise.all(registrations).then(() => {
+            logger.info("[NeuroLink] Memory retrieval tools registered");
+        });
+    }
     /** Format memory context for prompt inclusion */
     formatMemoryContext(memoryContext, currentInput) {
         return `Context from previous conversations:
@@ -1451,10 +1586,30 @@ Current user's request: ${currentInput}`;
         if (!options.input?.text || typeof options.input.text !== "string") {
             throw new Error("Input text is required and must be a non-empty string");
         }
+        // Check budget limit before making API call
+        if (options.maxBudgetUsd !== undefined &&
+            options.maxBudgetUsd > 0 &&
+            this._sessionCostUsd >= options.maxBudgetUsd) {
+            throw new NeuroLinkError({
+                code: "SESSION_BUDGET_EXCEEDED",
+                message: `Session budget exceeded: spent $${this._sessionCostUsd.toFixed(4)} of $${options.maxBudgetUsd.toFixed(4)} limit`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    spent: this._sessionCostUsd,
+                    limit: options.maxBudgetUsd,
+                },
+            });
+        }
         // Check if workflow is requested
         if (options.workflow || options.workflowConfig) {
             return await this.generateWithWorkflow(options);
         }
+        // Check if PPT output mode is requested
+        if (options.output?.mode === "ppt") {
+            return await this.generateWithPPT(options);
+        }
         // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
         return await this.setLangfuseContextFromOptions(options, async () => {
             if (this.conversationMemoryConfig?.conversationMemory?.mem0Enabled &&
@@ -1585,6 +1740,20 @@ Current user's request: ${currentInput}`;
                 abortSignal: options.abortSignal,
                 skipToolPromptInjection: options.skipToolPromptInjection,
             };
+            // Auto-map top-level sessionId/userId to context for convenience
+            // Tests and users may pass sessionId/userId as top-level options
+            const extraContext = options;
+            if (extraContext.sessionId || extraContext.userId) {
+                baseOptions.context = {
+                    ...baseOptions.context,
+                    ...(extraContext.sessionId && !baseOptions.context?.sessionId
+                        ? { sessionId: extraContext.sessionId }
+                        : {}),
+                    ...(extraContext.userId && !baseOptions.context?.userId
+                        ? { userId: extraContext.userId }
+                        : {}),
+                };
+            }
             // Apply factory enhancement using centralized utilities
             const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
             // Pass conversation memory config if available
@@ -1664,6 +1833,10 @@ Current user's request: ${currentInput}`;
                 video: textResult.video,
                 ppt: textResult.ppt,
             };
+            // Accumulate session cost for budget tracking
+            if (generateResult.analytics?.cost && generateResult.analytics.cost > 0) {
+                this._sessionCostUsd += generateResult.analytics.cost;
+            }
             this.scheduleGenerateMem0Storage(options, originalPrompt, generateResult);
             return generateResult;
         });
@@ -1691,6 +1864,40 @@ Current user's request: ${currentInput}`;
             });
         }
     }
+    /**
+     * Handle PPT generation mode
+     */
+    async generateWithPPT(options) {
+        const startTime = Date.now();
+        // Dynamic import to avoid circular deps (same pattern as RAG)
+        const { generatePresentation } = await import("./features/ppt/presentationOrchestrator.js");
+        const { extractPPTContext, getEffectivePPTProvider } = await import("./features/ppt/utils.js");
+        // Get provider instance for content planning
+        const requestedProvider = (options.provider || "vertex");
+        const provider = await AIProviderFactory.createProvider(requestedProvider, options.model, true, this);
+        // Resolve effective PPT provider (may auto-select if current is not PPT-compatible)
+        const effectiveProvider = await getEffectivePPTProvider(provider, requestedProvider, options.model || "default", this);
+        // Extract PPT context from options
+        const pptContext = extractPPTContext(options);
+        // Generate the presentation
+        const pptResult = await generatePresentation({
+            context: pptContext,
+            provider: effectiveProvider.provider,
+            providerName: effectiveProvider.providerName,
+            modelName: effectiveProvider.modelName,
+            neurolink: this,
+        });
+        // Map PPT result to GenerateResult
+        return {
+            content: `Presentation generated: ${pptResult.filePath} (${pptResult.totalSlides} slides)`,
+            finishReason: "stop",
+            provider: pptResult.provider || requestedProvider,
+            model: pptResult.model || options.model || "default",
+            usage: undefined,
+            responseTime: Date.now() - startTime,
+            ppt: pptResult,
+        };
+    }
     /**
      * Generate with workflow engine integration
      * Returns both original and processed responses for AB testing
@@ -1957,6 +2164,11 @@ Current user's request: ${currentInput}`;
      */
     async generateTextInternal(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 };
         const generateInternalStartTime = Date.now();
         const generateInternalHrTimeStart = process.hrtime.bigint();
         const functionTag = "NeuroLink.generateTextInternal";
@@ -1972,11 +2184,23 @@ Current user's request: ${currentInput}`;
                     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,
+                    }),
                 });
-                await storeConversationTurn(this.conversationMemory, options, mcpResult, new Date(generateInternalStartTime));
+                await storeConversationTurn(this.conversationMemory, options, mcpResult, new Date(generateInternalStartTime), requestId);
                 this.emitter.emit("response:end", mcpResult.content || "");
                 return mcpResult;
             }
+            if (options.abortSignal?.aborted) {
+                throw new DOMException("The operation was aborted", "AbortError");
+            }
             const directResult = await this.directProviderGeneration(options);
             logger.debug(`[${functionTag}] Direct generation successful`);
             logger.info(`[NeuroLink.generateTextInternal] generate() - COMPLETE SUCCESS`, {
@@ -1985,8 +2209,17 @@ Current user's request: ${currentInput}`;
                 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,
+                }),
             });
-            await storeConversationTurn(this.conversationMemory, options, directResult, new Date(generateInternalStartTime));
+            await storeConversationTurn(this.conversationMemory, options, directResult, new Date(generateInternalStartTime), requestId);
             this.emitter.emit("response:end", directResult.content || "");
             this.emitter.emit("message", `Text generation completed successfully`);
             return directResult;
@@ -2012,7 +2245,7 @@ Current user's request: ${currentInput}`;
                         enableSummarize: false, // Skip LLM call for recovery
                         truncationFraction: 0.75, // Aggressive truncation
                     });
-                    const compactionResult = await compactor.compact(conversationMessages, compactionTarget);
+                    const compactionResult = await compactor.compact(conversationMessages, compactionTarget, undefined, options.context?.requestId);
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
                         logger.info(`[${functionTag}] Aggressive compaction complete, retrying`, {
@@ -2053,7 +2286,7 @@ Current user's request: ${currentInput}`;
                         model: options.model || "unknown",
                         responseTime: Date.now() - generateInternalStartTime,
                     };
-                    await withTimeout(storeConversationTurn(this.conversationMemory, options, abortedResult, new Date(generateInternalStartTime)), 5000);
+                    await withTimeout(storeConversationTurn(this.conversationMemory, options, abortedResult, new Date(generateInternalStartTime), requestId), 5000);
                 }
                 catch (storeError) {
                     logger.warn(`[${functionTag}] Failed to store conversation turn after abort`, {
@@ -2110,7 +2343,22 @@ Current user's request: ${currentInput}`;
                 elapsedNs: (process.hrtime.bigint() - generateInternalHrTimeStart).toString(),
                 message: "Starting conversation memory initialization",
             });
-            await this.conversationMemory.initialize();
+            try {
+                await this.conversationMemory.initialize();
+            }
+            catch (err) {
+                logger.warn("[NEUROLINK] Redis memory init failed, falling back to in-memory", {
+                    error: err instanceof Error ? err.message : String(err),
+                    generateInternalId,
+                });
+                const memCfg = this.conversationMemoryConfig?.conversationMemory;
+                this.conversationMemory = new ConversationMemoryManager({
+                    enabled: true,
+                    maxSessions: memCfg?.maxSessions ?? 100,
+                    maxTurnsPerSession: memCfg?.maxTurnsPerSession ?? 50,
+                });
+                await this.conversationMemory.initialize();
+            }
             const conversationMemoryEndTime = process.hrtime.bigint();
             const conversationMemoryDurationNs = conversationMemoryEndTime - conversationMemoryStartTime;
             logger.debug(`[NeuroLink] ✅ LOG_POINT_G004_CONVERSATION_MEMORY_INIT_SUCCESS`, {
@@ -2142,6 +2390,10 @@ Current user's request: ${currentInput}`;
         const maxMcpRetries = RETRY_ATTEMPTS.QUICK;
         const maxAttempts = maxMcpRetries + 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            if (options.abortSignal?.aborted) {
+                logger.debug(`[${functionTag}] Abort signal already fired before attempt ${attempt}, stopping retries`);
+                throw new DOMException("The operation was aborted", "AbortError");
+            }
             try {
                 logger.debug(`[${functionTag}] Attempting MCP generation (attempt ${attempt}/${maxAttempts})...`);
                 const mcpResult = await this.tryMCPGeneration(options);
@@ -2198,7 +2450,21 @@ Current user's request: ${currentInput}`;
                     logger.debug(`[${functionTag}] All MCP attempts exhausted, falling back to direct generation`);
                     break;
                 }
-                await new Promise((resolve) => setTimeout(resolve, 500));
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, 500);
+                    if (options.abortSignal) {
+                        const onAbort = () => {
+                            clearTimeout(timer);
+                            resolve();
+                        };
+                        options.abortSignal.addEventListener("abort", onAbort, {
+                            once: true,
+                        });
+                    }
+                });
+                if (options.abortSignal?.aborted) {
+                    throw new DOMException("The operation was aborted", "AbortError");
+                }
             }
         }
         return null;
@@ -2207,7 +2473,12 @@ Current user's request: ${currentInput}`;
      * Try MCP-enhanced generation (no fallback recursion)
      */
     async tryMCPGeneration(options) {
+        if (options.abortSignal?.aborted) {
+            throw new DOMException("The operation was aborted", "AbortError");
+        }
         // 🚀 EXHAUSTIVE LOGGING POINT T001: TRY MCP GENERATION ENTRY
+        const requestId = options.context?.requestId ||
+            "unknown";
         const tryMCPId = `try-mcp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
         const tryMCPStartTime = Date.now();
         const tryMCPHrTimeStart = process.hrtime.bigint();
@@ -2261,6 +2532,7 @@ Current user's request: ${currentInput}`;
                 ? options.systemPrompt || ""
                 : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
             logger.debug("Tool-aware system prompt created", {
+                requestId,
                 originalPromptLength: options.systemPrompt?.length || 0,
                 enhancedPromptLength: enhancedSystemPrompt.length,
                 skippedToolInjection: !!options.skipToolPromptInjection,
@@ -2268,6 +2540,44 @@ Current user's request: ${currentInput}`;
             });
             // 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,
@@ -2278,6 +2588,19 @@ Current user's request: ${currentInput}`;
                 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,
+            });
             if (budgetResult.shouldCompact && this.conversationMemory) {
                 logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
                     usageRatio: budgetResult.usageRatio,
@@ -2291,7 +2614,7 @@ Current user's request: ${currentInput}`;
                     summarizationModel: this.conversationMemoryConfig?.conversationMemory
                         ?.summarizationModel,
                 });
-                const compactionResult = await compactor.compact(conversationMessages, budgetResult.availableInputTokens, this.conversationMemoryConfig?.conversationMemory);
+                const compactionResult = await compactor.compact(conversationMessages, budgetResult.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, requestId);
                 if (compactionResult.compacted) {
                     const repairedResult = repairToolPairs(compactionResult.messages);
                     conversationMessages = repairedResult.messages;
@@ -2313,6 +2636,16 @@ Current user's request: ${currentInput}`;
                 customTools: this.getCustomTools(),
                 executeTool: this.executeTool.bind(this),
             }, 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,
@@ -2434,6 +2767,9 @@ Current user's request: ${currentInput}`;
         let lastError = null;
         // Try each provider in order
         for (const providerName of tryProviders) {
+            if (options.abortSignal?.aborted) {
+                throw new DOMException("The operation was aborted", "AbortError");
+            }
             try {
                 logger.debug(`[${functionTag}] Attempting provider: ${providerName}`);
                 // Get conversation messages for context (use pre-compacted if provided)
@@ -2456,7 +2792,7 @@ Current user's request: ${currentInput}`;
                 });
                 if (budgetCheck.shouldCompact && this.conversationMemory) {
                     const compactor = new ContextCompactor({ provider: providerName });
-                    const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens);
+                    const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens, undefined, options.context?.requestId);
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
                         conversationMessages = repairedResult.messages;
@@ -3031,6 +3367,8 @@ Current user's request: ${currentInput}`;
                     providerDetails,
                     enableSummarization: enhancedOptions.enableSummarization,
                     events: eventSequence.length > 0 ? eventSequence : undefined,
+                    requestId: enhancedOptions.context
+                        ?.requestId,
                 });
                 logger.debug("[NeuroLink.stream] Stored conversation turn with events", {
                     sessionId,
@@ -3135,7 +3473,7 @@ Current user's request: ${currentInput}`;
         });
         if (streamBudget.shouldCompact && this.conversationMemory) {
             const compactor = new ContextCompactor({ provider: providerName });
-            const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens);
+            const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens, undefined, options.context?.requestId);
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
                 conversationMessages = repairedResult.messages;
@@ -3269,6 +3607,9 @@ Current user's request: ${currentInput}`;
                             startTimeStamp: new Date(startTime),
                             providerDetails,
                             enableSummarization: enhancedOptions?.enableSummarization,
+                            requestId: enhancedOptions?.context?.requestId ||
+                                options.context
+                                    ?.requestId,
                         });
                     }
                     catch (error) {
@@ -4864,7 +5205,13 @@ Current user's request: ${currentInput}`;
         const initId = `stats-init-${Date.now()}`;
         await this.initializeConversationMemoryForGeneration(initId, Date.now(), process.hrtime.bigint());
         if (!this.conversationMemory) {
-            throw new Error("Conversation memory is not enabled");
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
         }
         return await this.conversationMemory.getStats();
     }
@@ -4878,10 +5225,23 @@ Current user's request: ${currentInput}`;
         const initId = `history-init-${Date.now()}`;
         await this.initializeConversationMemoryForGeneration(initId, Date.now(), process.hrtime.bigint());
         if (!this.conversationMemory) {
-            throw new Error("Conversation memory is not enabled");
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
         }
         if (!sessionId || typeof sessionId !== "string") {
-            throw new Error("Session ID must be a non-empty string");
+            throw new NeuroLinkError({
+                code: ERROR_CODES.INVALID_PARAMETERS,
+                message: "Session ID must be a non-empty string",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { sessionId },
+            });
         }
         try {
             // Use the existing buildContextMessages method to get the complete history
@@ -4910,7 +5270,13 @@ Current user's request: ${currentInput}`;
         const initId = `clear-session-init-${Date.now()}`;
         await this.initializeConversationMemoryForGeneration(initId, Date.now(), process.hrtime.bigint());
         if (!this.conversationMemory) {
-            throw new Error("Conversation memory is not enabled");
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
         }
         return await this.conversationMemory.clearSession(sessionId);
     }
@@ -4922,7 +5288,13 @@ Current user's request: ${currentInput}`;
         const initId = `clear-all-init-${Date.now()}`;
         await this.initializeConversationMemoryForGeneration(initId, Date.now(), process.hrtime.bigint());
         if (!this.conversationMemory) {
-            throw new Error("Conversation memory is not enabled");
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
         }
         await this.conversationMemory.clearAllSessions();
     }
@@ -4973,6 +5345,89 @@ Current user's request: ${currentInput}`;
                 "RedisConversationMemoryManager";
         return !!(isRedisStorage && hasRedisConversationMemory);
     }
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     * @param sessionId - The session ID to retrieve messages for
+     * @returns Array of ChatMessage objects, or empty array if session doesn't exist
+     */
+    async getSessionMessages(sessionId, userId) {
+        const initId = `get-msgs-init-${Date.now()}`;
+        await this.initializeConversationMemoryForGeneration(initId, Date.now(), process.hrtime.bigint());
+        if (!this.conversationMemory) {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        if (!sessionId || typeof sessionId !== "string") {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.INVALID_PARAMETERS,
+                message: "Session ID must be a non-empty string",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { sessionId },
+            });
+        }
+        return await this.conversationMemory.getSessionMessages(sessionId, userId);
+    }
+    /**
+     * Replace the entire messages array for a session.
+     * @param sessionId - The session ID to update
+     * @param messages - The new messages array
+     * @param userId - Optional user ID for scoped Redis key lookup
+     */
+    async setSessionMessages(sessionId, messages, userId) {
+        const initId = `set-msgs-init-${Date.now()}`;
+        await this.initializeConversationMemoryForGeneration(initId, Date.now(), process.hrtime.bigint());
+        if (!this.conversationMemory) {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.MISSING_CONFIGURATION,
+                message: "Conversation memory is not enabled",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        if (!sessionId || typeof sessionId !== "string") {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.INVALID_PARAMETERS,
+                message: "Session ID must be a non-empty string",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: { sessionId },
+            });
+        }
+        await this.conversationMemory.setSessionMessages(sessionId, messages, userId);
+    }
+    /**
+     * Modify the last assistant message in a session using a transformer function.
+     * Convenience wrapper around getSessionMessages/setSessionMessages.
+     * @param sessionId - The session ID to modify
+     * @param transformer - Function that receives the last assistant message content and returns the modified content
+     * @param userId - Optional user ID for scoped Redis key lookup
+     * @returns true if a message was modified, false if no assistant message was found
+     */
+    async modifyLastAssistantMessage(sessionId, transformer, userId) {
+        const messages = await this.getSessionMessages(sessionId, userId);
+        // Find the last assistant message (searching from the end)
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "assistant") {
+                messages[i] = {
+                    ...messages[i],
+                    content: transformer(messages[i].content),
+                };
+                await this.setSessionMessages(sessionId, messages, userId);
+                return true;
+            }
+        }
+        return false;
+    }
     // ===== EXTERNAL MCP SERVER METHODS =====
     /**
      * Add an external MCP server