perf(frontend): message windowing + stable keys in MessagesTab (#819)

## Summary

Addresses UI bogging-down and potential memory pressure caused by
accumulating large numbers of AG-UI events in long-running sessions.

- **Message windowing**: cap the rendered DOM to the last 100 messages
(`MAX_VISIBLE_MESSAGES`). A lightweight "Load earlier messages" button
reveals older history on demand, keeping the number of mounted React
subtrees bounded regardless of session length
- **Scroll position preservation**: `useLayoutEffect` + explicit
`scrollTop` assignment anchors the viewport when loading earlier
messages, overriding browser scroll-anchoring to get deterministic
behavior
- **Stable React keys**: replace `key={sm-${idx}}` (index-based) with
IDs derived from the message itself. Index keys cause React to re-render
every message below an insertion point; stable keys mean only the
changed node is reconciled
- **`handleScroll` guard**: `setIsAtBottom` now uses a functional update
that short-circuits when the boolean value hasn't changed, eliminating
the re-render triggered on every scroll event
- **`streamMessages` useMemo split**: the single O(n) memo that ran on
every text delta is split into `committedStreamMessages` (hierarchy
traversal, runs infrequently) and `streamMessages` (O(1) append, runs on
every `TEXT_MESSAGE_CONTENT` event)

## Jira

https://issues.redhat.com/browse/RHOAIENG-52026

## Test plan

- [ ] Open a session with a large number of messages; confirm only the
latest 100 are rendered (use DevTools Elements panel to count)
- [ ] Click "Load earlier messages"; confirm the viewport stays anchored
to the same content and doesn't jump to the top
- [ ] Verify new streaming messages still auto-scroll when the user is
at the bottom
- [ ] Verify the empty-state placeholder appears for sessions with no
messages
- [ ] Confirm system-message toggle still works with the windowed list
- [ ] React DevTools Profiler: confirm `committedStreamMessages` does
not re-run on `TEXT_MESSAGE_CONTENT` events

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: Gkrumbach07

components/frontend/src/app/projects/[name]/sessions/[sessionName]/page.tsx

@@ -775,8 +775,10 @@ export default function ProjectSessionDetailPage({
     handleWorkflowChange(workflowId);
   };
 
-  // Convert AG-UI messages to display format with hierarchical tool call rendering
-  const streamMessages: Array<MessageObject | ToolUseMessages | HierarchicalToolMessage> = useMemo(() => {
+  // Phase 1: convert committed messages + streaming tool cards into display format.
+  // Does NOT depend on currentMessage / currentReasoning so it skips the full
+  // O(n) traversal during text-streaming deltas (the most frequent event type).
+  const committedStreamMessages: Array<MessageObject | ToolUseMessages | HierarchicalToolMessage> = useMemo(() => {
 
     // Helper function to parse tool arguments
     const parseToolArgs = (args: string | undefined): Record<string, unknown> => {
@@ -1043,33 +1045,6 @@ export default function ProjectSessionDetailPage({
       }
     }
 
-    // Add streaming reasoning if currently reasoning
-    const activeReasoning = aguiState.currentReasoning || aguiState.currentThinking;
-    if (activeReasoning?.content) {
-      result.push({
-        type: "agent_message",
-        content: {
-          type: "reasoning_block",
-          thinking: activeReasoning.content,
-          signature: "",
-        },
-        model: "claude",
-        timestamp: activeReasoning.timestamp || "",
-        streaming: true,
-      } as MessageObject & { streaming?: boolean });
-    }
-
-    // Add streaming message if currently streaming
-    if (aguiState.currentMessage?.content) {
-      result.push({
-        type: "agent_message",
-        content: { type: "text_block", text: aguiState.currentMessage.content },
-        model: "claude",
-        timestamp: aguiState.currentMessage.timestamp || "",
-        streaming: true,
-      } as MessageObject & { streaming?: boolean });
-    }
-
     // Render ALL currently streaming tool calls (supports parallel tool execution)
     // CRITICAL: This renders tools immediately when TOOL_CALL_START arrives,
     // not waiting until TOOL_CALL_END like the allToolCalls map approach does
@@ -1161,12 +1136,48 @@ export default function ProjectSessionDetailPage({
     return result;
   }, [
     aguiState.messages,
+    aguiState.currentToolCall,   // Needed in Phase A to avoid orphaned-child promotion
+    aguiState.pendingToolCalls,  // CRITICAL: Include so UI updates when new tools start
+    aguiState.pendingChildren,   // CRITICAL: Include so UI updates when children finish
+  ]);
+
+  // Phase 2: append streaming text / reasoning bubbles to the committed list.
+  // This is O(1) and is the only memo that re-runs on every TEXT_MESSAGE_CONTENT
+  // or REASONING_MESSAGE_CONTENT delta (the most frequent events during active runs).
+  const streamMessages: Array<MessageObject | ToolUseMessages | HierarchicalToolMessage> = useMemo(() => {
+    const result = [...committedStreamMessages];
+
+    const activeReasoning = aguiState.currentReasoning || aguiState.currentThinking;
+    if (activeReasoning?.content) {
+      result.push({
+        type: "agent_message",
+        content: {
+          type: "reasoning_block",
+          thinking: activeReasoning.content,
+          signature: "",
+        },
+        model: "claude",
+        timestamp: activeReasoning.timestamp || "",
+        streaming: true,
+      } as MessageObject & { streaming?: boolean });
+    }
+
+    if (aguiState.currentMessage?.content) {
+      result.push({
+        type: "agent_message",
+        content: { type: "text_block", text: aguiState.currentMessage.content },
+        model: "claude",
+        timestamp: aguiState.currentMessage.timestamp || "",
+        streaming: true,
+      } as MessageObject & { streaming?: boolean });
+    }
+
+    return result;
+  }, [
+    committedStreamMessages,
     aguiState.currentMessage,
     aguiState.currentReasoning,
     aguiState.currentThinking,
-    aguiState.currentToolCall,
-    aguiState.pendingToolCalls,  // CRITICAL: Include so UI updates when new tools start
-    aguiState.pendingChildren,   // CRITICAL: Include so UI updates when children finish
   ]);
 
   // Check if there are any real messages (user or assistant messages, not just system)

components/frontend/src/components/session/MessagesTab.tsx

@@ -1,18 +1,33 @@
 "use client";
 
-import React, { useState, useRef, useEffect, useMemo } from "react";
+import React, { useState, useRef, useEffect, useMemo, useLayoutEffect, useCallback } from "react";
 import { MessageSquare } from "lucide-react";
 import { StreamMessage } from "@/components/ui/stream-message";
 import { LoadingDots } from "@/components/ui/message";
+import { Button } from "@/components/ui/button";
 import { ChatInputBox } from "@/components/chat/ChatInputBox";
 import { QueuedMessageBubble } from "@/components/chat/QueuedMessageBubble";
-import type { AgenticSession, MessageObject, ToolUseMessages } from "@/types/agentic-session";
+import type { AgenticSession, MessageObject, ToolUseMessages, HierarchicalToolMessage } from "@/types/agentic-session";
 import type { WorkflowMetadata } from "@/app/projects/[name]/sessions/[sessionName]/lib/types";
 import type { QueuedMessageItem } from "@/hooks/use-session-queue";
 
+/** Maximum number of messages rendered at once. Older messages are loaded on demand. */
+const MAX_VISIBLE_MESSAGES = 100;
+
+/** Derive a stable React key for any message variant. */
+function getMessageKey(m: MessageObject | ToolUseMessages | HierarchicalToolMessage, idx: number): string {
+  if ('id' in m && m.id) return m.id;
+  if ('toolUseBlock' in m && m.toolUseBlock?.id) return `tool-${m.toolUseBlock.id}`;
+  // Both MessageObject and HierarchicalToolMessage carry type+timestamp; the `in` guard is sufficient.
+  if ('type' in m && 'timestamp' in m) return `${m.type}-${m.timestamp}-${idx}`;
+  // Last resort: index within the visible window. This key shifts when the window expands
+  // (Load earlier), but only affects messages with no other stable identifier.
+  return `sm-${idx}`;
+}
+
 export type MessagesTabProps = {
   session: AgenticSession;
-  streamMessages: Array<MessageObject | ToolUseMessages>;
+  streamMessages: Array<MessageObject | ToolUseMessages | HierarchicalToolMessage>;
   chatInput: string;
   setChatInput: (v: string) => void;
   onSendChat: () => Promise<void>;
@@ -43,6 +58,12 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
 
   const messagesContainerRef = useRef<HTMLDivElement>(null);
   const [isAtBottom, setIsAtBottom] = useState(true);
+  // How many messages (counting from the end) are currently rendered.
+  const [loadedMessageCount, setLoadedMessageCount] = useState(MAX_VISIBLE_MESSAGES);
+  // Refs for scroll-position preservation when loading earlier messages.
+  const prevScrollHeightRef = useRef(0);
+  const prevScrollTopRef = useRef(0);
+  const preservingScrollRef = useRef(false);
 
   const phase = session?.status?.phase || "";
 
@@ -55,16 +76,25 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
     return true;
   });
 
+  // Only render the latest N messages; older ones are revealed via "Load earlier" button.
+  const visibleMessages = useMemo(() => {
+    if (filteredMessages.length <= loadedMessageCount) return filteredMessages;
+    return filteredMessages.slice(filteredMessages.length - loadedMessageCount);
+  }, [filteredMessages, loadedMessageCount]);
+
+  const hasMoreMessages = filteredMessages.length > loadedMessageCount;
+
   const checkIfAtBottom = () => {
     const container = messagesContainerRef.current;
     if (!container) return true;
     const threshold = 50;
-    const isBottom = container.scrollHeight - container.scrollTop - container.clientHeight < threshold;
-    return isBottom;
+    return container.scrollHeight - container.scrollTop - container.clientHeight < threshold;
   };
 
   const handleScroll = () => {
-    setIsAtBottom(checkIfAtBottom());
+    const bottom = checkIfAtBottom();
+    // Avoid a re-render when the value hasn't changed.
+    setIsAtBottom((prev) => (prev === bottom ? prev : bottom));
   };
 
   const scrollToBottom = () => {
@@ -74,6 +104,32 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
     }
   };
 
+  // Load earlier messages and preserve the user's visual scroll position.
+  const loadEarlierMessages = useCallback(() => {
+    const container = messagesContainerRef.current;
+    if (container) {
+      // Capture BEFORE state update so we have the pre-render values.
+      prevScrollHeightRef.current = container.scrollHeight;
+      prevScrollTopRef.current = container.scrollTop;
+      preservingScrollRef.current = true;
+    }
+    setLoadedMessageCount((prev) => prev + MAX_VISIBLE_MESSAGES);
+  }, []);
+
+  // After React commits the expanded list, forcibly set scrollTop so the
+  // viewport stays anchored to the same content regardless of whether the
+  // browser's native scroll-anchoring has already adjusted it.
+  useLayoutEffect(() => {
+    if (!preservingScrollRef.current) return;
+    preservingScrollRef.current = false;
+    const container = messagesContainerRef.current;
+    if (container) {
+      const scrollDelta = container.scrollHeight - prevScrollHeightRef.current;
+      container.scrollTop = prevScrollTopRef.current + scrollDelta;
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- refs are stable; loadedMessageCount is the intended trigger
+  }, [loadedMessageCount]);
+
   useEffect(() => {
     if (isAtBottom) {
       scrollToBottom();
@@ -137,8 +193,27 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
       >
         {showWelcomeExperience && welcomeExperienceComponent}
 
-        {shouldShowMessages && filteredMessages.map((m, idx) => (
-          <StreamMessage key={`sm-${idx}`} message={m} isNewest={idx === filteredMessages.length - 1} onGoToResults={onGoToResults} agentName={agentName} />
+        {shouldShowMessages && hasMoreMessages && (
+          <div className="flex justify-center py-2">
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={loadEarlierMessages}
+              className="text-xs text-muted-foreground underline underline-offset-2"
+            >
+              Load earlier messages ({filteredMessages.length - loadedMessageCount} hidden)
+            </Button>
+          </div>
+        )}
+
+        {shouldShowMessages && visibleMessages.map((m, idx) => (
+          <StreamMessage
+            key={getMessageKey(m, idx)}
+            message={m}
+            isNewest={idx === visibleMessages.length - 1}
+            onGoToResults={onGoToResults}
+            agentName={agentName}
+          />
         ))}
 
         {/* Queued messages with cancel buttons */}
@@ -176,7 +251,7 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
           </div>
         )}
 
-        {!showWelcomeExperience && !isCreating && filteredMessages.length === 0 && (
+        {!showWelcomeExperience && !isCreating && visibleMessages.length === 0 && (
           <div className="flex flex-col items-center justify-center h-full text-muted-foreground">
             <MessageSquare className="w-8 h-8 mx-auto mb-2 opacity-50" />
             <p className="text-sm">No messages yet</p>