@juspay/neurolink 9.29.1 → 9.31.0

package/dist/client/core/redisConversationMemoryManager.js

@@ -0,0 +1,1435 @@
+/**
+ * Redis Conversation Memory Manager for NeuroLink
+ * Redis-based implementation of conversation storage with same interface as ConversationMemoryManager
+ */
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../telemetry/tracers.js";
+import { randomUUID } from "crypto";
+import { MESSAGES_PER_TURN } from "../config/conversationMemory.js";
+import { generateToolOutputPreview } from "../context/toolOutputLimits.js";
+import { SummarizationEngine } from "../context/summarizationEngine.js";
+import { NeuroLink } from "../neurolink.js";
+import { ConversationMemoryError } from "../types/conversation.js";
+import { withTimeout } from "../utils/errorHandling.js";
+import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
+import { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
+import { logger } from "../utils/logger.js";
+import { deserializeConversation, getNormalizedConfig, getPooledRedisClient, getSessionKey, getUserSessionsKey, releasePooledRedisClient, scanKeys, serializeConversation, } from "../utils/redis.js";
+const redisTracer = tracers.redis;
+/**
+ * Redis-based implementation of the ConversationMemoryManager
+ * Uses the same interface but stores data in Redis
+ */
+export class RedisConversationMemoryManager {
+    config;
+    isInitialized = false;
+    summarizationEngine = new SummarizationEngine();
+    redisConfig;
+    redisClient = null;
+    /**
+     * Temporary storage for tool execution data to prevent race conditions
+     * Key format: "${sessionId}:${userId}"
+     */
+    pendingToolExecutions = new Map();
+    /**
+     * Track sessions currently generating titles to prevent race conditions
+     * Key format: "${sessionId}:${userId}"
+     */
+    titleGenerationInProgress = new Set();
+    /**
+     * Track sessions currently being summarized to prevent race conditions
+     * Key format: "${sessionId}:${userId}"
+     */
+    summarizationInProgress = new Set();
+    constructor(config, redisConfig = {}) {
+        this.config = config;
+        this.redisConfig = getNormalizedConfig(redisConfig);
+    }
+    /**
+     * Initialize the memory manager with Redis connection
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            logger.debug("[RedisConversationMemoryManager] Already initialized, skipping");
+            return;
+        }
+        await redisTracer.startActiveSpan("neurolink.memory.initialize", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "redis.host": this.redisConfig.host,
+                "redis.port": this.redisConfig.port,
+                "redis.key_prefix": this.redisConfig.keyPrefix,
+            },
+        }, async (span) => {
+            try {
+                logger.debug("[RedisConversationMemoryManager] Initializing with config", {
+                    host: this.redisConfig.host,
+                    port: this.redisConfig.port,
+                    keyPrefix: this.redisConfig.keyPrefix,
+                    ttl: this.redisConfig.ttl,
+                });
+                this.redisClient = await getPooledRedisClient(this.redisConfig);
+                this.isInitialized = true;
+                logger.info("RedisConversationMemoryManager initialized", {
+                    storage: "redis",
+                    host: this.redisConfig.host,
+                    port: this.redisConfig.port,
+                    maxSessions: this.config.maxSessions,
+                    maxTurnsPerSession: this.config.maxTurnsPerSession,
+                });
+                logger.debug("[RedisConversationMemoryManager] Redis client created successfully", {
+                    clientType: this.redisClient?.constructor?.name || "unknown",
+                    isConnected: !!this.redisClient,
+                });
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                logger.error("[RedisConversationMemoryManager] Failed to initialize", {
+                    error: error instanceof Error ? error.message : String(error),
+                    stack: error instanceof Error ? error.stack : undefined,
+                    config: {
+                        host: this.redisConfig.host,
+                        port: this.redisConfig.port,
+                    },
+                });
+                throw new ConversationMemoryError("Failed to initialize Redis conversation memory", "CONFIG_ERROR", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /** Whether this memory manager can persist data (Redis connected and initialized) */
+    get canPersist() {
+        return (this.isInitialized && this.redisClient !== null && this.redisClient.isOpen);
+    }
+    /** Whether Redis client is configured and connected */
+    get isRedisConfigured() {
+        return this.redisClient !== null && this.redisClient.isOpen;
+    }
+    /** Get health status for monitoring */
+    getHealthStatus() {
+        return {
+            initialized: this.isInitialized,
+            connected: this.redisClient?.isOpen ?? false,
+            host: this.redisConfig.host,
+            keyPrefix: this.redisConfig.keyPrefix,
+        };
+    }
+    /**
+     * Get session by ID, reconstructing a SessionMemory from Redis storage.
+     */
+    async getSession(sessionId, userId, requestId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            return undefined;
+        }
+        return redisTracer.startActiveSpan("neurolink.memory.getSession", { kind: SpanKind.CLIENT, attributes: { "session.id": sessionId } }, async (span) => {
+            if (userId) {
+                span.setAttribute("user.id", userId);
+            }
+            try {
+                const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                const conversationData = await this.redisClient.get(redisKey);
+                const conversation = deserializeConversation(conversationData || null);
+                if (!conversation) {
+                    span.setAttribute("session.found", false);
+                    return undefined;
+                }
+                span.setAttribute("session.found", true);
+                // Log session load metadata for observability
+                const blobSizeBytes = conversationData
+                    ? Buffer.byteLength(conversationData, "utf8")
+                    : 0;
+                const messageCount = conversation.messages.length;
+                const hasSummary = !!conversation.summarizedUpToMessageId;
+                const pointerIndex = hasSummary
+                    ? conversation.messages.findIndex((msg) => msg.id === conversation.summarizedUpToMessageId)
+                    : -1;
+                const recentMessageCount = hasSummary && pointerIndex !== -1
+                    ? messageCount - pointerIndex - 1
+                    : messageCount;
+                span.setAttribute("message.count", messageCount);
+                span.setAttribute("blob.size_bytes", blobSizeBytes);
+                logger.info("[ConversationMemory] Session loaded", {
+                    requestId,
+                    sessionId,
+                    blobSizeBytes,
+                    messageCount,
+                    hasSummary,
+                    recentMessageCount,
+                });
+                if (blobSizeBytes > 512 * 1024) {
+                    logger.warn("[ConversationMemory] Large session blob", {
+                        requestId,
+                        sessionId,
+                        blobSizeBytes,
+                        messageCount,
+                    });
+                }
+                return {
+                    sessionId: conversation.sessionId,
+                    userId: conversation.userId,
+                    messages: conversation.messages,
+                    summarizedUpToMessageId: conversation.summarizedUpToMessageId,
+                    summarizedMessage: conversation.summarizedMessage,
+                    tokenThreshold: conversation.tokenThreshold,
+                    lastTokenCount: conversation.lastTokenCount,
+                    lastCountedAt: conversation.lastCountedAt,
+                    lastApiTokenCount: conversation.lastApiTokenCount,
+                    createdAt: new Date(conversation.createdAt).getTime(),
+                    lastActivity: new Date(conversation.updatedAt).getTime(),
+                };
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                logger.error("[RedisConversationMemoryManager] Failed to get session", {
+                    sessionId,
+                    userId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return undefined;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Get raw session data without any filtering or transformation.
+     * Used by the memory retrieval tool and internal APIs that need
+     * access to full message data including unmodified tool outputs.
+     */
+    async getSessionRaw(sessionId, userId) {
+        try {
+            await this.ensureInitialized();
+            if (!this.redisClient) {
+                return null;
+            }
+            const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+            const conversationData = await this.redisClient.get(redisKey);
+            return deserializeConversation(conversationData || null);
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get raw session", {
+                sessionId,
+                userId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Get all sessions for a specific user
+     */
+    async getUserSessions(userId) {
+        // Ensure initialization
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available", { userId });
+            return [];
+        }
+        try {
+            const userSessionsKey = getUserSessionsKey(this.redisConfig, userId);
+            const sessions = await this.redisClient.sMembers(userSessionsKey);
+            return Array.from(sessions).map(String);
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get user sessions", {
+                userId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * Add a session to user's session set (private method)
+     */
+    async addUserSession(userId, sessionId) {
+        if (!this.redisClient || !userId) {
+            return;
+        }
+        try {
+            const userSessionsKey = getUserSessionsKey(this.redisConfig, userId);
+            await this.redisClient.sAdd(userSessionsKey, sessionId);
+            if (this.redisConfig.ttl > 0) {
+                await this.redisClient.expire(userSessionsKey, this.redisConfig.ttl);
+            }
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to add session to user set", {
+                userId,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Remove a session from user's session set (private method)
+     */
+    async removeUserSession(userId, sessionId) {
+        if (!this.redisClient || !userId) {
+            return false;
+        }
+        try {
+            const userSessionsKey = getUserSessionsKey(this.redisConfig, userId);
+            const result = await this.redisClient.sRem(userSessionsKey, sessionId);
+            return Number(result) > 0;
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to remove session from user set", {
+                userId,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Generate current timestamp in ISO format
+     */
+    generateTimestamp() {
+        return new Date().toISOString();
+    }
+    /**
+     * Store tool execution data for a session (temporarily to avoid race conditions)
+     */
+    async storeToolExecution(sessionId, userId, toolCalls, toolResults, currentTime) {
+        logger.debug("[RedisConversationMemoryManager] Storing tool execution temporarily", {
+            sessionId,
+            userId,
+            toolCallsCount: toolCalls?.length || 0,
+            toolResultsCount: toolResults?.length || 0,
+        });
+        try {
+            const normalizedUserId = userId || "randomUser";
+            const pendingKey = `${sessionId}:${normalizedUserId}`;
+            // Store tool execution data temporarily to prevent race conditions
+            const pendingData = {
+                toolCalls: (toolCalls || []).map((call) => ({
+                    ...call,
+                    timestamp: currentTime,
+                })),
+                toolResults: (toolResults || []).map((result) => ({
+                    ...result,
+                    timestamp: currentTime,
+                })),
+                timestamp: Date.now(),
+            };
+            // Check if there's existing pending data and merge
+            const existingData = this.pendingToolExecutions.get(pendingKey);
+            if (existingData) {
+                logger.debug("[RedisConversationMemoryManager] Merging with existing pending tool data", {
+                    sessionId,
+                    existingToolCalls: existingData.toolCalls.length,
+                    existingToolResults: existingData.toolResults.length,
+                    newToolCalls: toolCalls?.length || 0,
+                    newToolResults: toolResults?.length || 0,
+                });
+                // Merge tool calls and results
+                pendingData.toolCalls = [
+                    ...existingData.toolCalls,
+                    ...pendingData.toolCalls,
+                ];
+                pendingData.toolResults = [
+                    ...existingData.toolResults,
+                    ...pendingData.toolResults,
+                ];
+            }
+            this.pendingToolExecutions.set(pendingKey, pendingData);
+            logger.debug("[RedisConversationMemoryManager] Tool execution stored temporarily", {
+                sessionId,
+                userId: normalizedUserId,
+                pendingKey,
+                totalToolCalls: pendingData.toolCalls.length,
+                totalToolResults: pendingData.toolResults.length,
+            });
+            // Clean up stale pending data (older than 5 minutes)
+            this.cleanupStalePendingData();
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to store tool execution temporarily", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Don't throw - tool storage failures shouldn't break generation
+        }
+    }
+    /**
+     * Store a conversation turn for a session
+     */
+    async storeConversationTurn(options) {
+        logger.debug("[RedisConversationMemoryManager] Storing conversation turn", {
+            sessionId: options.sessionId,
+            userId: options.userId,
+        });
+        await this.ensureInitialized();
+        // NLK-GAP-012: Add span for storeTurn CRUD operation
+        return redisTracer.startActiveSpan("neurolink.memory.storeTurn", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "session.id": options.sessionId,
+                ...(options.userId && { "user.id": options.userId }),
+            },
+        }, async (span) => {
+            try {
+                if (!this.redisClient) {
+                    throw new Error("Redis client not initialized");
+                }
+                const redisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId);
+                const conversationData = await this.redisClient.get(redisKey);
+                let conversation = deserializeConversation(conversationData);
+                const currentTime = new Date().toISOString();
+                const normalizedUserId = options.userId || "randomUser";
+                if (!conversation) {
+                    const titleGenerationKey = `${options.sessionId}:${normalizedUserId}`;
+                    // Capture the current Langfuse ALS context before setImmediate,
+                    // which breaks automatic AsyncLocalStorage propagation and would
+                    // otherwise cause orphaned traces in Langfuse.
+                    const generateTitleWithContext = runWithCurrentLangfuseContext(async () => {
+                        if (this.titleGenerationInProgress.has(titleGenerationKey)) {
+                            return;
+                        }
+                        this.titleGenerationInProgress.add(titleGenerationKey);
+                        try {
+                            const title = await this.generateConversationTitle(options.userMessage);
+                            const updatedRedisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId || undefined);
+                            const updatedConversationData = await this.redisClient?.get(updatedRedisKey);
+                            const updatedConversation = deserializeConversation(updatedConversationData || null);
+                            if (updatedConversation) {
+                                updatedConversation.title = title;
+                                updatedConversation.updatedAt = new Date().toISOString();
+                                const serializedData = serializeConversation(updatedConversation);
+                                await this.redisClient?.set(updatedRedisKey, serializedData);
+                                if (this.redisConfig.ttl > 0) {
+                                    await this.redisClient?.expire(updatedRedisKey, this.redisConfig.ttl);
+                                }
+                            }
+                        }
+                        catch (titleError) {
+                            logger.warn("[RedisConversationMemoryManager] Failed to generate conversation title in background", {
+                                sessionId: options.sessionId,
+                                userId: normalizedUserId,
+                                error: titleError instanceof Error
+                                    ? titleError.message
+                                    : String(titleError),
+                            });
+                        }
+                        finally {
+                            this.titleGenerationInProgress.delete(titleGenerationKey);
+                        }
+                    });
+                    setImmediate(generateTitleWithContext);
+                    conversation = {
+                        id: randomUUID(),
+                        title: "New Conversation", // Temporary title until generated
+                        sessionId: options.sessionId,
+                        userId: normalizedUserId,
+                        createdAt: options.startTimeStamp?.toISOString() || currentTime,
+                        updatedAt: options.startTimeStamp?.toISOString() || currentTime,
+                        messages: [],
+                    };
+                }
+                else {
+                    conversation.updatedAt = currentTime;
+                }
+                const tokenThreshold = options.providerDetails
+                    ? getEffectiveTokenThreshold(options.providerDetails.provider, options.providerDetails.model, this.config.tokenThreshold, conversation.tokenThreshold)
+                    : this.config.tokenThreshold || 50000;
+                const userMsg = {
+                    id: randomUUID(),
+                    timestamp: options.startTimeStamp?.toISOString() || this.generateTimestamp(),
+                    role: "user",
+                    content: options.userMessage,
+                };
+                conversation.messages.push(userMsg);
+                await this.flushPendingToolData(conversation, options.sessionId, normalizedUserId);
+                const assistantMsg = {
+                    id: randomUUID(),
+                    timestamp: this.generateTimestamp(),
+                    role: "assistant",
+                    content: options.aiResponse,
+                    events: options.events || undefined,
+                };
+                conversation.messages.push(assistantMsg);
+                // Store API-reported token counts if available
+                if (options.tokenUsage) {
+                    conversation.lastApiTokenCount = options.tokenUsage;
+                }
+                logger.info("[RedisConversationMemoryManager] Added new messages", {
+                    sessionId: conversation.sessionId,
+                    userId: conversation.userId,
+                });
+                // Use per-request enableSummarization with higher priority than instance config
+                const shouldSummarize = options.enableSummarization !== undefined
+                    ? options.enableSummarization
+                    : this.config.enableSummarization;
+                if (shouldSummarize) {
+                    const normalizedUserId = options.userId || "randomUser";
+                    const summarizationKey = `${options.sessionId}:${normalizedUserId}`;
+                    // Only trigger summarization if not already in progress for this session
+                    if (!this.summarizationInProgress.has(summarizationKey)) {
+                        // Capture the current Langfuse ALS context before setImmediate,
+                        // which breaks automatic AsyncLocalStorage propagation and would
+                        // otherwise cause orphaned traces in Langfuse.
+                        const summarizeWithContext = runWithCurrentLangfuseContext(async () => {
+                            try {
+                                await this.checkAndSummarize(conversation, tokenThreshold, options.sessionId, options.userId, options.requestId);
+                            }
+                            catch (error) {
+                                logger.error("Background summarization failed", {
+                                    sessionId: conversation.sessionId,
+                                    error: error instanceof Error ? error.message : String(error),
+                                });
+                            }
+                        });
+                        setImmediate(summarizeWithContext);
+                    }
+                    else {
+                        logger.debug("[RedisConversationMemoryManager] Summarization already in progress, skipping", {
+                            sessionId: options.sessionId,
+                            userId: normalizedUserId,
+                        });
+                    }
+                }
+                const serializedData = serializeConversation(conversation);
+                await this.redisClient.set(redisKey, serializedData);
+                // Log turn storage metadata for observability
+                const blobSizeBytes = Buffer.byteLength(serializedData, "utf8");
+                logger.info("[ConversationMemory] Turn stored", {
+                    requestId: options.requestId,
+                    sessionId: options.sessionId,
+                    blobSizeBytes,
+                    totalMessages: conversation.messages.length,
+                    userMsgChars: options.userMessage.length,
+                    assistantMsgChars: options.aiResponse.length,
+                });
+                if (blobSizeBytes > 512 * 1024) {
+                    logger.warn("[ConversationMemory] Large session blob", {
+                        requestId: options.requestId,
+                        sessionId: options.sessionId,
+                        blobSizeBytes,
+                        messageCount: conversation.messages.length,
+                    });
+                }
+                if (this.redisConfig.ttl > 0) {
+                    await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+                }
+                if (options.userId) {
+                    await this.addUserSession(options.userId, options.sessionId);
+                }
+                span.setAttribute("message.count", conversation.messages.length);
+                span.setStatus({ code: SpanStatusCode.OK });
+                logger.debug("[RedisConversationMemoryManager] Successfully stored conversation turn", {
+                    sessionId: options.sessionId,
+                    totalMessages: conversation.messages.length,
+                    title: conversation.title,
+                });
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                throw new ConversationMemoryError(`Failed to store conversation turn in Redis for session ${options.sessionId}`, "STORAGE_ERROR", {
+                    sessionId: options.sessionId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Check if summarization is needed based on token count
+     */
+    async checkAndSummarize(conversation, threshold, sessionId, userId, requestId) {
+        const normalizedUserId = userId || "randomUser";
+        const summarizationKey = `${sessionId}:${normalizedUserId}`;
+        if (this.summarizationInProgress.has(summarizationKey)) {
+            logger.debug("[RedisConversationMemoryManager] Summarization already in progress, skipping", {
+                sessionId,
+                userId: normalizedUserId,
+            });
+            return;
+        }
+        this.summarizationInProgress.add(summarizationKey);
+        try {
+            const session = {
+                sessionId: conversation.sessionId,
+                userId: conversation.userId,
+                messages: conversation.messages,
+                summarizedUpToMessageId: conversation.summarizedUpToMessageId,
+                summarizedMessage: conversation.summarizedMessage,
+                tokenThreshold: conversation.tokenThreshold,
+                lastTokenCount: conversation.lastTokenCount,
+                lastCountedAt: conversation.lastCountedAt,
+                createdAt: new Date(conversation.createdAt).getTime(),
+                lastActivity: new Date(conversation.updatedAt).getTime(),
+            };
+            const summarized = await this.summarizationEngine.checkAndSummarize(session, threshold, this.config, "[RedisConversationMemoryManager]", requestId);
+            conversation.lastTokenCount = session.lastTokenCount;
+            conversation.lastCountedAt = session.lastCountedAt;
+            if (summarized) {
+                conversation.summarizedUpToMessageId = session.summarizedUpToMessageId;
+                conversation.summarizedMessage = session.summarizedMessage;
+                if (this.redisClient) {
+                    const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                    // Re-read current state to avoid clobbering messages added during summarization
+                    const latestData = await this.redisClient.get(redisKey);
+                    if (latestData) {
+                        const latestConversation = deserializeConversation(latestData);
+                        if (latestConversation) {
+                            // Apply only summarization metadata onto the fresh state
+                            latestConversation.summarizedUpToMessageId =
+                                conversation.summarizedUpToMessageId;
+                            latestConversation.summarizedMessage =
+                                conversation.summarizedMessage;
+                            latestConversation.lastTokenCount = conversation.lastTokenCount;
+                            latestConversation.lastCountedAt = conversation.lastCountedAt;
+                            const freshSerialized = serializeConversation(latestConversation);
+                            await this.redisClient.set(redisKey, freshSerialized);
+                            if (this.redisConfig.ttl > 0) {
+                                await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger.error("Token counting or summarization failed", {
+                sessionId: conversation.sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            this.summarizationInProgress.delete(summarizationKey);
+        }
+    }
+    /**
+     * Build context messages for AI prompt injection (TOKEN-BASED)
+     * Returns messages from pointer onwards (or all if no pointer)
+     * Applies sendToolPreview toggle and hydrates result.result for backward compat
+     */
+    async buildContextMessages(sessionId, userId, enableSummarization, requestId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available in buildContextMessages");
+            return [];
+        }
+        // NLK-GAP-012: Add span for buildContext CRUD operation
+        return redisTracer.startActiveSpan("neurolink.memory.buildContext", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "session.id": sessionId,
+                ...(userId && { "user.id": userId }),
+            },
+        }, async (span) => {
+            try {
+                logger.info("[RedisConversationMemoryManager] Building context messages", {
+                    sessionId,
+                    userId,
+                    method: "buildContextMessages",
+                });
+                const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                const conversationData = await this.redisClient.get(redisKey);
+                const conversation = deserializeConversation(conversationData || null);
+                if (!conversation) {
+                    span.setAttribute("session.found", false);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return [];
+                }
+                const session = {
+                    sessionId: conversation.sessionId,
+                    userId: conversation.userId,
+                    messages: conversation.messages,
+                    summarizedUpToMessageId: conversation.summarizedUpToMessageId,
+                    summarizedMessage: conversation.summarizedMessage,
+                    tokenThreshold: conversation.tokenThreshold,
+                    lastTokenCount: conversation.lastTokenCount,
+                    lastCountedAt: conversation.lastCountedAt,
+                    createdAt: new Date(conversation.createdAt).getTime(),
+                    lastActivity: new Date(conversation.updatedAt).getTime(),
+                };
+                const contextMessages = buildContextFromPointer(session, requestId);
+                const sendToolPreview = this.config?.contextCompaction?.sendToolPreview === true;
+                // Map tool_result messages: apply preview toggle + hydrate result.result
+                const finalMessages = contextMessages.map((msg) => {
+                    if (msg.role !== "tool_result") {
+                        return msg;
+                    }
+                    // Toggle: swap content to preview if enabled AND a preview exists
+                    const content = sendToolPreview && msg.metadata?.toolOutputPreview
+                        ? msg.metadata.toolOutputPreview
+                        : msg.content;
+                    // Hydrate result.result from content for backward compatibility
+                    // (result.result is no longer stored — inferred from content at read time)
+                    let hydratedResult = msg.result;
+                    if (msg.result && msg.result.result === undefined) {
+                        let parsedResult = content;
+                        try {
+                            parsedResult = JSON.parse(content);
+                        }
+                        catch {
+                            /* plain text — use as-is */
+                        }
+                        hydratedResult = { ...msg.result, result: parsedResult };
+                    }
+                    return { ...msg, content, result: hydratedResult };
+                });
+                // Tool messages now have real content and participate in context properly.
+                // The tool output pruner (Stage 1) handles bounding old tool outputs.
+                span.setAttribute("context.message_count", finalMessages.length);
+                span.setStatus({ code: SpanStatusCode.OK });
+                logger.info("[RedisConversationMemoryManager] Retrieved context messages", {
+                    sessionId,
+                    userId,
+                });
+                return finalMessages;
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Get session metadata for a specific user session (optimized for listing)
+     * Fetches only essential metadata without heavy message arrays
+     *
+     * @param userId The user identifier
+     * @param sessionId The session identifier
+     * @returns Session metadata or null if session doesn't exist
+     */
+    async getUserSessionMetadata(userId, sessionId) {
+        logger.debug("[RedisConversationMemoryManager] Getting user session metadata", {
+            userId,
+            sessionId,
+        });
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available", { userId, sessionId });
+            return null;
+        }
+        try {
+            const sessionKey = getSessionKey(this.redisConfig, sessionId, userId);
+            const conversationData = await this.redisClient.get(sessionKey);
+            if (!conversationData) {
+                logger.debug("[RedisConversationMemoryManager] No session data found", {
+                    userId,
+                    sessionId,
+                    sessionKey,
+                });
+                return null;
+            }
+            // Deserialize conversation object but extract only metadata
+            const conversation = deserializeConversation(conversationData);
+            if (conversation) {
+                return {
+                    id: conversation.sessionId,
+                    title: conversation.title,
+                    createdAt: conversation.createdAt,
+                    updatedAt: conversation.updatedAt,
+                    metadata: conversation.additionalMetadata?.agenticLoopReports
+                        ? {
+                            agenticLoopReports: conversation.additionalMetadata.agenticLoopReports,
+                        }
+                        : undefined,
+                };
+            }
+            logger.debug("[RedisConversationMemoryManager] No valid conversation data found", {
+                userId,
+                sessionId,
+                sessionKey,
+            });
+            return null;
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get user session metadata", {
+                userId,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            return null;
+        }
+    }
+    /**
+     * Get conversation history for a specific user session
+     *
+     * @param userId The user identifier
+     * @param sessionId The session identifier
+     * @returns Array of chat messages or null if session doesn't exist
+     */
+    async getUserSessionHistory(userId, sessionId) {
+        logger.debug("[RedisConversationMemoryManager] Getting user session history via getUserSessionObject", {
+            userId,
+            sessionId,
+        });
+        try {
+            const sessionObject = await this.getUserSessionObject(userId, sessionId);
+            if (!sessionObject) {
+                logger.debug("[RedisConversationMemoryManager] No session object found, returning null", {
+                    userId,
+                    sessionId,
+                });
+                return null;
+            }
+            return sessionObject.messages;
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get user session history via getUserSessionObject", {
+                userId,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+                errorName: error instanceof Error ? error.name : "UnknownError",
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            return null;
+        }
+    }
+    /**
+     * Get the complete conversation object for a specific user session
+     *
+     * This method returns the full conversation object including title, metadata,
+     * timestamps, and all chat messages. Unlike getUserSessionHistory() which returns
+     * only the messages array, this method provides the complete conversation context.
+     *
+     * @param userId The user identifier who owns the session
+     * @param sessionId The unique session identifier
+     * @returns Complete conversation object with all data, or null if session doesn't exist
+     */
+    async getUserSessionObject(userId, sessionId) {
+        logger.debug("[RedisConversationMemoryManager] Getting complete user session object", {
+            userId,
+            sessionId,
+            method: "getUserSessionObject",
+        });
+        // Validate input parameters
+        if (!userId || typeof userId !== "string") {
+            logger.warn("[RedisConversationMemoryManager] Invalid userId provided", {
+                userId,
+                sessionId,
+            });
+            return null;
+        }
+        if (!sessionId || typeof sessionId !== "string") {
+            logger.warn("[RedisConversationMemoryManager] Invalid sessionId provided", { userId, sessionId });
+            return null;
+        }
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available for getUserSessionObject", {
+                userId,
+                sessionId,
+            });
+            return null;
+        }
+        try {
+            const sessionKey = getSessionKey(this.redisConfig, sessionId, userId);
+            const conversationData = await this.redisClient.get(sessionKey);
+            if (!conversationData) {
+                logger.debug("[RedisConversationMemoryManager] No conversation data found in Redis", {
+                    userId,
+                    sessionId,
+                    sessionKey,
+                });
+                return null;
+            }
+            // Deserialize the complete conversation object
+            const conversation = deserializeConversation(conversationData);
+            if (!conversation) {
+                logger.debug("[RedisConversationMemoryManager] Failed to deserialize conversation data", {
+                    userId,
+                    sessionId,
+                    sessionKey,
+                    dataLength: conversationData.length,
+                });
+                return null;
+            }
+            // Validate conversation object structure
+            if (!conversation.messages || !Array.isArray(conversation.messages)) {
+                logger.warn("[RedisConversationMemoryManager] Invalid conversation structure - missing messages array", {
+                    userId,
+                    sessionId,
+                    hasMessages: !!conversation.messages,
+                    messagesType: typeof conversation.messages,
+                });
+                return null;
+            }
+            return conversation;
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get complete user session object", {
+                userId,
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+                errorName: error instanceof Error ? error.name : "UnknownError",
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            return null;
+        }
+    }
+    /**
+     * Generate a conversation title from the first user message
+     * Uses AI to create a concise, descriptive title (5-8 words)
+     */
+    async generateConversationTitle(userMessage) {
+        logger.info("[RedisConversationMemoryManager] Generating conversation title", {
+            userMessageLength: userMessage.length,
+            userMessagePreview: userMessage.substring(0, 100),
+        });
+        try {
+            // Create a NeuroLink instance for title generation
+            const titleGenerator = new NeuroLink({
+                conversationMemory: { enabled: false },
+            });
+            const titlePrompt = `Generate a clear, concise, and descriptive title (5–8 words maximum) for a conversation based on the following user message.
+The title must meaningfully reflect the topic or intent of the message.
+Do not output anything unrelated, vague, or generic.
+Do not say you cannot create a title. Always return a valid title.
+
+User message: "${userMessage}"`;
+            const result = await titleGenerator.generate({
+                input: { text: titlePrompt },
+                provider: this.config.summarizationProvider || "vertex",
+                model: this.config.summarizationModel || "gemini-2.5-flash",
+                disableTools: true, // Title generation doesn't need tools — saves ~600 tokens of tool descriptions
+            });
+            // Clean up the generated title
+            let title = result.content?.trim() || "New Conversation";
+            // Remove common prefixes/suffixes that might be added by the AI
+            title = title.replace(/^(Title:|Here's a title:|The title is:)\s*/i, "");
+            title = title.replace(/['"]/g, ""); // Remove quotes
+            title = title.replace(/\.$/, ""); // Remove trailing period
+            if (title.length > 60) {
+                title = title.substring(0, 57) + "...";
+            }
+            if (title.length < 3) {
+                title = "New Conversation";
+            }
+            logger.info("[RedisConversationMemoryManager] Generated conversation title", {
+                originalLength: result.content?.length || 0,
+                cleanedTitle: title,
+                titleLength: title.length,
+            });
+            return title;
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to generate conversation title", {
+                error: error instanceof Error ? error.message : String(error),
+                userMessagePreview: userMessage.substring(0, 100),
+            });
+            // Fallback to a simple title based on the user message
+            const fallbackTitle = userMessage.length > 30
+                ? userMessage.substring(0, 30) + "..."
+                : userMessage || "New Conversation";
+            return fallbackTitle;
+        }
+    }
+    /**
+     * Create summary system message
+     */
+    createSummarySystemMessage(content, summarizesFrom, summarizesTo) {
+        return {
+            id: `summary-${randomUUID()}`,
+            role: "system",
+            content: `Summary of previous conversation turns:\n\n${content}`,
+            timestamp: new Date().toISOString(),
+            metadata: {
+                isSummary: true,
+                summarizesFrom,
+                summarizesTo,
+            },
+        };
+    }
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     */
+    async getSessionMessages(sessionId, userId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            return [];
+        }
+        try {
+            const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+            const conversationData = await this.redisClient.get(redisKey);
+            const conversation = deserializeConversation(conversationData || null);
+            return conversation?.messages ?? [];
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get session messages", {
+                sessionId,
+                userId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * Replace the entire messages array for a session.
+     * The session must already exist in Redis.
+     */
+    async setSessionMessages(sessionId, messages, userId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            throw new ConversationMemoryError("Redis client not initialized", "STORAGE_ERROR", { sessionId });
+        }
+        try {
+            const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+            const conversationData = await this.redisClient.get(redisKey);
+            const conversation = deserializeConversation(conversationData || null);
+            if (!conversation) {
+                throw new ConversationMemoryError(`Session ${sessionId} not found`, "STORAGE_ERROR", { sessionId });
+            }
+            conversation.messages = messages;
+            conversation.updatedAt = new Date().toISOString();
+            // Reset summarization pointers — the old summary no longer applies
+            // to the replaced messages array
+            conversation.summarizedUpToMessageId = undefined;
+            conversation.summarizedMessage = undefined;
+            conversation.lastTokenCount = undefined;
+            conversation.lastCountedAt = undefined;
+            const serializedData = serializeConversation(conversation);
+            await this.redisClient.set(redisKey, serializedData);
+            if (this.redisConfig.ttl > 0) {
+                await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+            }
+            logger.debug("[RedisConversationMemoryManager] Session messages replaced", {
+                sessionId,
+                userId,
+                messageCount: messages.length,
+            });
+        }
+        catch (error) {
+            if (error instanceof ConversationMemoryError) {
+                throw error;
+            }
+            throw new ConversationMemoryError(`Failed to set session messages for session ${sessionId}`, "STORAGE_ERROR", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Close Redis connection
+     */
+    async close() {
+        if (this.redisClient) {
+            await releasePooledRedisClient(this.redisConfig);
+            this.redisClient = null;
+            this.isInitialized = false;
+            logger.info("Redis connection closed");
+        }
+    }
+    /**
+     * Get statistics about conversation storage
+     */
+    async getStats() {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            return { totalSessions: 0, totalTurns: 0 };
+        }
+        // Get all session keys using SCAN instead of KEYS to avoid blocking
+        const pattern = `${this.redisConfig.keyPrefix}*`;
+        const keys = await scanKeys(this.redisClient, pattern);
+        logger.debug("[RedisConversationMemoryManager] Got session keys with SCAN", {
+            pattern,
+            keyCount: keys.length,
+        });
+        // Count messages in each session
+        let totalTurns = 0;
+        for (const key of keys) {
+            const conversationData = await this.redisClient.get(key);
+            const conversation = deserializeConversation(conversationData);
+            if (conversation?.messages) {
+                totalTurns += conversation.messages.length / MESSAGES_PER_TURN;
+            }
+        }
+        return {
+            totalSessions: keys.length,
+            totalTurns,
+        };
+    }
+    /**
+     * Clear a specific session
+     */
+    async clearSession(sessionId, userId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            return false;
+        }
+        // NLK-GAP-012: Add span for clearSession CRUD operation
+        return redisTracer.startActiveSpan("neurolink.memory.clear", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "session.id": sessionId,
+                ...(userId && { "user.id": userId }),
+            },
+        }, async (span) => {
+            try {
+                const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                const result = await this.redisClient.del(redisKey);
+                if (Number(result) > 0) {
+                    // Remove session from user's session set
+                    if (userId) {
+                        await this.removeUserSession(userId, sessionId);
+                    }
+                    span.setAttribute("session.deleted", true);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    logger.info("Redis session cleared", { sessionId });
+                    return true;
+                }
+                span.setAttribute("session.deleted", false);
+                span.setStatus({ code: SpanStatusCode.OK });
+                return false;
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Clear all sessions
+     */
+    async clearAllSessions() {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            return;
+        }
+        const conversationPattern = `${this.redisConfig.keyPrefix}*`;
+        const userSessionsPattern = `${this.redisConfig.userSessionsKeyPrefix}*`;
+        // Use SCAN instead of KEYS to avoid blocking the server
+        const conversationKeys = await scanKeys(this.redisClient, conversationPattern);
+        const userSessionsKeys = await scanKeys(this.redisClient, userSessionsPattern);
+        const allKeys = [...conversationKeys, ...userSessionsKeys];
+        logger.debug("[RedisConversationMemoryManager] Got all keys with SCAN for clearing", {
+            conversationPattern,
+            userSessionsPattern,
+            conversationKeyCount: conversationKeys.length,
+            userSessionsKeyCount: userSessionsKeys.length,
+            totalKeyCount: allKeys.length,
+        });
+        if (allKeys.length > 0) {
+            // Process keys in batches to avoid blocking Redis for too long
+            const batchSize = 100;
+            for (let i = 0; i < allKeys.length; i += batchSize) {
+                const batch = allKeys.slice(i, i + batchSize);
+                await this.redisClient.del(batch);
+                logger.debug("[RedisConversationMemoryManager] Cleared batch of sessions and user mappings", {
+                    batchIndex: Math.floor(i / batchSize) + 1,
+                    batchSize: batch.length,
+                    totalProcessed: i + batch.length,
+                    totalKeys: allKeys.length,
+                });
+            }
+            logger.info("All Redis sessions and user session mappings cleared", {
+                clearedCount: allKeys.length,
+                conversationSessions: conversationKeys.length,
+                userSessionMappings: userSessionsKeys.length,
+            });
+        }
+    }
+    /**
+     * Ensure Redis client is initialized
+     */
+    async ensureInitialized() {
+        logger.debug("[RedisConversationMemoryManager] Ensuring initialization");
+        if (!this.isInitialized) {
+            logger.debug("[RedisConversationMemoryManager] Not initialized, initializing now");
+            await this.initialize();
+        }
+        else {
+            logger.debug("[RedisConversationMemoryManager] Already initialized");
+        }
+    }
+    /**
+     * Get session metadata for all sessions of a user (optimized for listing)
+     * Returns only essential metadata without heavy message arrays
+     *
+     * @param userId The user identifier
+     * @returns Array of session metadata objects
+     */
+    async getUserAllSessionsHistory(userId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available", { userId });
+            return [];
+        }
+        const results = [];
+        try {
+            // Get all session IDs for the user using existing method
+            const sessionIds = await this.getUserSessions(userId);
+            if (sessionIds.length === 0) {
+                return results;
+            }
+            // Fetch metadata for each session using our optimized helper method
+            for (const sessionId of sessionIds) {
+                try {
+                    const metadata = await this.getUserSessionMetadata(userId, sessionId);
+                    if (metadata) {
+                        results.push(metadata);
+                    }
+                    else {
+                        logger.debug("[RedisConversationMemoryManager] Empty or missing session metadata - removing from user history", {
+                            userId,
+                            sessionId,
+                        });
+                        await this.removeUserSession(userId, sessionId);
+                    }
+                }
+                catch (sessionError) {
+                    logger.error("[RedisConversationMemoryManager] Failed to get session metadata", {
+                        userId,
+                        sessionId,
+                        error: sessionError instanceof Error
+                            ? sessionError.message
+                            : String(sessionError),
+                    });
+                }
+            }
+            return results;
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get user all sessions metadata", {
+                userId,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            return results;
+        }
+    }
+    /**
+     * Clean up stale pending tool execution data
+     * Removes data older than 5 minutes to prevent memory leaks
+     */
+    cleanupStalePendingData() {
+        const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+        const keysToDelete = [];
+        for (const [key, data] of this.pendingToolExecutions) {
+            if (data.timestamp < fiveMinutesAgo) {
+                keysToDelete.push(key);
+            }
+        }
+        if (keysToDelete.length > 0) {
+            logger.debug("[RedisConversationMemoryManager] Cleaning up stale pending tool data", {
+                stalePendingKeys: keysToDelete.length,
+                totalPendingKeys: this.pendingToolExecutions.size,
+            });
+            keysToDelete.forEach((key) => this.pendingToolExecutions.delete(key));
+        }
+    }
+    /**
+     * Flush pending tool execution data for a session and merge into conversation
+     */
+    async flushPendingToolData(conversation, sessionId, userId) {
+        const pendingKey = `${sessionId}:${userId}`;
+        const pendingData = this.pendingToolExecutions.get(pendingKey);
+        if (!pendingData) {
+            logger.debug("[RedisConversationMemoryManager] No pending tool data to flush", {
+                sessionId,
+                userId,
+                pendingKey,
+            });
+            return;
+        }
+        logger.debug("[RedisConversationMemoryManager] Flushing pending tool data", {
+            sessionId,
+            userId,
+            toolCallsCount: pendingData.toolCalls.length,
+            toolResultsCount: pendingData.toolResults.length,
+        });
+        try {
+            // Create a mapping from toolCallId to toolName for matching tool results
+            const toolCallMap = new Map();
+            // Create separate messages for tool calls and build the mapping
+            for (const toolCall of pendingData.toolCalls) {
+                const toolCallId = toolCall.toolCallId ?? "";
+                const toolName = toolCall.toolName ?? "";
+                // Store in mapping for tool results
+                toolCallMap.set(toolCallId, toolName);
+                const toolCallMessage = {
+                    id: randomUUID(),
+                    timestamp: toolCall.timestamp?.toISOString() || this.generateTimestamp(),
+                    role: "tool_call",
+                    content: "", // Can be empty for tool calls
+                    tool: toolName,
+                    args: (toolCall.args ||
+                        toolCall.arguments ||
+                        toolCall.parameters ||
+                        {}),
+                };
+                conversation.messages.push(toolCallMessage);
+            }
+            // Create separate messages for tool results using the mapping
+            for (const toolResult of pendingData.toolResults) {
+                const toolCallId = String(toolResult.toolCallId || toolResult.id || "unknown");
+                const toolName = toolCallMap.get(toolCallId) || "unknown";
+                // Serialize the tool result to string for content field
+                let serializedResult;
+                if (typeof toolResult.result === "string") {
+                    serializedResult = toolResult.result;
+                }
+                else if (toolResult.result === undefined ||
+                    toolResult.result === null) {
+                    serializedResult = String(toolResult.result ?? "null");
+                }
+                else {
+                    try {
+                        serializedResult = JSON.stringify(toolResult.result, null, 2);
+                    }
+                    catch (serializeError) {
+                        serializedResult = `[Serialization failed: ${serializeError instanceof Error ? serializeError.message : String(serializeError)}]`;
+                    }
+                }
+                // Generate preview (uses existing config fields that were previously unused)
+                const { preview, truncated, originalSize } = generateToolOutputPreview(serializedResult, {
+                    maxBytes: this.config?.contextCompaction?.maxToolOutputBytes,
+                    maxLines: this.config?.contextCompaction?.maxToolOutputLines,
+                });
+                // Build metadata — only store preview when truncation occurred (no duplication)
+                const metadata = {
+                    truncated,
+                    ...(truncated && { toolOutputPreview: preview }),
+                    ...(truncated && { originalSize }),
+                };
+                // Build result — success/error metadata only, NOT the output data
+                const result = {
+                    success: !toolResult.error,
+                    // result.result intentionally NOT stored — inferred from content at read time
+                    error: toolResult.error ? String(toolResult.error) : undefined,
+                };
+                const toolResultMessage = {
+                    id: randomUUID(),
+                    timestamp: toolResult.timestamp?.toISOString() || this.generateTimestamp(),
+                    role: "tool_result",
+                    content: serializedResult, // Full output (was "")
+                    tool: toolName,
+                    result,
+                    metadata,
+                };
+                conversation.messages.push(toolResultMessage);
+            }
+            logger.debug("[RedisConversationMemoryManager] Successfully flushed pending tool data", {
+                sessionId,
+                userId,
+                toolMessagesAdded: pendingData.toolCalls.length + pendingData.toolResults.length,
+                totalMessages: conversation.messages.length,
+            });
+        }
+        finally {
+            // Always clean up pending data, even on failure, to prevent infinite retry loops
+            this.pendingToolExecutions.delete(pendingKey);
+        }
+    }
+    /**
+     * Update agentic loop report metadata for a conversation session.
+     * Upserts a report entry by reportId — updates existing or adds new.
+     * Follows the read → patch → write pattern (same as title generation).
+     *
+     * @param sessionId The session identifier
+     * @param userId The user identifier (optional)
+     * @param report The report metadata to upsert
+     */
+    async updateAgenticLoopReport(sessionId, userId, report) {
+        logger.debug("[RedisConversationMemoryManager] Updating agentic loop report", {
+            sessionId,
+            userId,
+            reportId: report.reportId,
+            reportType: report.reportType,
+            reportStatus: report.reportStatus,
+        });
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available for report update", { sessionId, userId });
+            return;
+        }
+        try {
+            const redisKey = getSessionKey(this.redisConfig, sessionId, userId || undefined);
+            const conversationData = await withTimeout(this.redisClient.get(redisKey), 5000);
+            if (!conversationData) {
+                logger.warn("[RedisConversationMemoryManager] No conversation found for report update", { sessionId, userId });
+                return;
+            }
+            const conversation = deserializeConversation(conversationData);
+            if (!conversation) {
+                logger.warn("[RedisConversationMemoryManager] Failed to deserialize conversation for report update", { sessionId, userId });
+                return;
+            }
+            // Initialize additionalMetadata and agenticLoopReports if needed
+            if (!conversation.additionalMetadata) {
+                conversation.additionalMetadata = {};
+            }
+            if (!conversation.additionalMetadata.agenticLoopReports) {
+                conversation.additionalMetadata.agenticLoopReports = [];
+            }
+            // Upsert: find existing report by reportId and update, or push new entry
+            const existingIndex = conversation.additionalMetadata.agenticLoopReports.findIndex((r) => r.reportId === report.reportId);
+            if (existingIndex >= 0) {
+                conversation.additionalMetadata.agenticLoopReports[existingIndex] =
+                    report;
+                logger.debug("[RedisConversationMemoryManager] Updated existing agentic loop report", { sessionId, reportId: report.reportId });
+            }
+            else {
+                conversation.additionalMetadata.agenticLoopReports.push(report);
+                logger.debug("[RedisConversationMemoryManager] Added new agentic loop report", { sessionId, reportId: report.reportId });
+            }
+            conversation.updatedAt = new Date().toISOString();
+            // Write back to Redis
+            const serializedData = serializeConversation(conversation);
+            await withTimeout(this.redisClient.set(redisKey, serializedData), 5000);
+            if (this.redisConfig.ttl > 0) {
+                await withTimeout(this.redisClient.expire(redisKey, this.redisConfig.ttl), 5000);
+            }
+            logger.info("[RedisConversationMemoryManager] Successfully updated agentic loop report", {
+                sessionId,
+                userId,
+                reportId: report.reportId,
+                reportStatus: report.reportStatus,
+            });
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to update agentic loop report", {
+                sessionId,
+                userId,
+                reportId: report.reportId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw new ConversationMemoryError("Failed to update agentic loop report", "STORAGE_ERROR", {
+                sessionId,
+                userId,
+                reportId: report.reportId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}