perf: send incremental streaming updates via IPC instead of full messages array (#2988)

rules/electron-ipc.md

@@ -100,6 +100,17 @@ queryClient.invalidateQueries({ queryKey: queryKeys.apps.all });
 
 **Adding new keys:** Add entries to the appropriate domain in `queryKeys.ts`. Follow the existing pattern with `all` for the base key and factory functions using object parameters for parameterized keys.
 
+## Streaming chunk optimizations
+
+The `chat:response:chunk` event supports two modes:
+
+1. **Full update** — `messages` field contains the complete messages array. Used for initial message load, post-compaction refresh, and lazy-edit completions.
+2. **Incremental update** — `streamingMessageId` + `streamingContent` fields update only the actively streaming message's content. Used for high-frequency text-delta streaming to avoid serializing the full messages array on every chunk.
+
+When modifying `ChatResponseChunkSchema` or adding new `safeSend("chat:response:chunk", ...)` call sites, decide which mode is appropriate. All frontend consumers (`useStreamChat`, `usePlanImplementation`, `useResolveMergeConflictsWithAI`) must handle both modes.
+
+**Zod schema contract changes:** Making a field optional (e.g., `messages` → `messages.optional()`) causes TypeScript errors in all consumers that assume the field is always present. Search for all destructuring/usage sites and add guards before committing.
+
 ## React + IPC integration pattern
 
 When creating hooks/components that call IPC handlers:

src/hooks/usePlanImplementation.ts

@@ -98,14 +98,39 @@ export function usePlanImplementation() {
             selectedComponents: [],
           },
           {
-            onChunk: ({ messages: updatedMessages }) => {
+            onChunk: ({
+              messages: updatedMessages,
+              streamingMessageId,
+              streamingContent,
+            }) => {
               if (!isMountedRef.current) return;
-              // Update the messages so the UI shows the streaming response
-              setMessagesById((prev) => {
-                const next = new Map(prev);
-                next.set(chatId, updatedMessages);
-                return next;
-              });
+
+              if (updatedMessages) {
+                // Full messages update (initial load, post-compaction, etc.)
+                setMessagesById((prev) => {
+                  const next = new Map(prev);
+                  next.set(chatId, updatedMessages);
+                  return next;
+                });
+              } else if (
+                streamingMessageId !== undefined &&
+                streamingContent !== undefined
+              ) {
+                // Incremental update: only update the streaming message's content
+                setMessagesById((prev) => {
+                  const existingMessages = prev.get(chatId);
+                  if (!existingMessages) return prev;
+
+                  const next = new Map(prev);
+                  const updated = existingMessages.map((msg) =>
+                    msg.id === streamingMessageId
+                      ? { ...msg, content: streamingContent }
+                      : msg,
+                  );
+                  next.set(chatId, updated);
+                  return next;
+                });
+              }
             },
             onEnd: () => {
               if (!isMountedRef.current) return;

src/hooks/useResolveMergeConflictsWithAI.ts

@@ -97,7 +97,7 @@ For each file, review the conflict markers (<<<<<<<, =======, >>>>>>>) and choos
           prompt,
         },
         {
-          onChunk: ({ messages }) => {
+          onChunk: ({ messages, streamingMessageId, streamingContent }) => {
             if (!hasIncrementedStreamCount) {
               setStreamCountById((prev) => {
                 const next = new Map(prev);
@@ -106,11 +106,33 @@ For each file, review the conflict markers (<<<<<<<, =======, >>>>>>>) and choos
               });
               hasIncrementedStreamCount = true;
             }
-            setMessagesById((prev) => {
-              const next = new Map(prev);
-              next.set(newChatId, messages);
-              return next;
-            });
+
+            if (messages) {
+              // Full messages update (initial load, post-compaction, etc.)
+              setMessagesById((prev) => {
+                const next = new Map(prev);
+                next.set(newChatId, messages);
+                return next;
+              });
+            } else if (
+              streamingMessageId !== undefined &&
+              streamingContent !== undefined
+            ) {
+              // Incremental update: only update the streaming message's content
+              setMessagesById((prev) => {
+                const existingMessages = prev.get(newChatId);
+                if (!existingMessages) return prev;
+
+                const next = new Map(prev);
+                const updated = existingMessages.map((msg) =>
+                  msg.id === streamingMessageId
+                    ? { ...msg, content: streamingContent }
+                    : msg,
+                );
+                next.set(newChatId, updated);
+                return next;
+              });
+            }
           },
           onEnd: () => {
             setIsStreamingById((prev) => {

src/hooks/useStreamChat.ts

@@ -172,7 +172,11 @@ export function useStreamChat({
             selectedComponents: selectedComponents ?? [],
           },
           {
-            onChunk: ({ messages: updatedMessages }) => {
+            onChunk: ({
+              messages: updatedMessages,
+              streamingMessageId,
+              streamingContent,
+            }) => {
               if (!hasIncrementedStreamCount) {
                 setStreamCountById((prev) => {
                   const next = new Map(prev);
@@ -182,11 +186,32 @@ export function useStreamChat({
                 hasIncrementedStreamCount = true;
               }
 
-              setMessagesById((prev) => {
-                const next = new Map(prev);
-                next.set(chatId, updatedMessages);
-                return next;
-              });
+              if (updatedMessages) {
+                // Full messages update (initial load, post-compaction, etc.)
+                setMessagesById((prev) => {
+                  const next = new Map(prev);
+                  next.set(chatId, updatedMessages);
+                  return next;
+                });
+              } else if (
+                streamingMessageId !== undefined &&
+                streamingContent !== undefined
+              ) {
+                // Incremental update: only update the streaming message's content
+                setMessagesById((prev) => {
+                  const existingMessages = prev.get(chatId);
+                  if (!existingMessages) return prev;
+
+                  const next = new Map(prev);
+                  const updated = existingMessages.map((msg) =>
+                    msg.id === streamingMessageId
+                      ? { ...msg, content: streamingContent }
+                      : msg,
+                  );
+                  next.set(chatId, updated);
+                  return next;
+                });
+              }
             },
             onEnd: (response: ChatResponseEnd) => {
               // Remove from pending set now that stream is complete

src/ipc/handlers/chat_stream_handlers.ts

@@ -1081,19 +1081,12 @@ This conversation includes one or more image attachments. When the user uploads
             lastDbSaveAt = now;
           }
 
-          // Update the placeholder assistant message content in the messages array
-          const currentMessages = [...updatedChat.messages];
-          if (
-            currentMessages.length > 0 &&
-            currentMessages[currentMessages.length - 1].role === "assistant"
-          ) {
-            currentMessages[currentMessages.length - 1].content = fullResponse;
-          }
-
-          // Update the assistant message in the database
+          // Send incremental update with only the streaming message content
+          // instead of the full messages array to reduce IPC overhead
           safeSend(event.sender, "chat:response:chunk", {
             chatId: req.chatId,
-            messages: currentMessages,
+            streamingMessageId: placeholderAssistantMessage.id,
+            streamingContent: fullResponse,
           });
           return fullResponse;
         };

src/ipc/types/chat.ts

@@ -92,10 +92,18 @@ export type ChatStreamParams = z.infer<typeof ChatStreamParamsSchema>;
 
 /**
  * Schema for chat response chunk event.
+ *
+ * Supports two modes:
+ * 1. Full update: `messages` is set with the complete messages array
+ * 2. Incremental update: `streamingMessageId` + `streamingContent` are set
+ *    to update only the content of a single message being streamed.
+ *    This avoids serializing the entire messages array on every text delta.
  */
 export const ChatResponseChunkSchema = z.object({
   chatId: z.number(),
-  messages: z.array(MessageSchema),
+  messages: z.array(MessageSchema).optional(),
+  streamingMessageId: z.number().optional(),
+  streamingContent: z.string().optional(),
 });
 
 /**

src/pro/main/ipc/handlers/local_agent/local_agent_handler.ts

@@ -375,6 +375,7 @@ export async function handleLocalAgentStream(
           previewContent,
           placeholderMessageId,
           hiddenMessageIdsForStreaming,
+          true, // Full messages: compaction changes message list
         );
       },
       {
@@ -425,6 +426,7 @@ export async function handleLocalAgentStream(
         fullResponse + streamingPreview,
         placeholderMessageId,
         hiddenMessageIdsForStreaming,
+        true, // Full messages: post-compaction refresh
       );
     }
 
@@ -1550,23 +1552,32 @@ function sendResponseChunk(
   fullResponse: string,
   placeholderMessageId: number,
   hiddenMessageIds?: Set<number>,
+  /** When true, sends the full messages array instead of an incremental update */
+  sendFullMessages?: boolean,
 ) {
-  const currentMessages = [...chat.messages].filter(
-    (message) => !hiddenMessageIds?.has(message.id),
-  );
-  // Find the placeholder message by ID rather than assuming it's the last
-  // assistant message. After compaction, a compaction summary message may
-  // exist after the placeholder and we must not overwrite it.
-  const placeholderMsg = currentMessages.find(
-    (m) => m.id === placeholderMessageId,
-  );
-  if (placeholderMsg) {
-    placeholderMsg.content = fullResponse;
+  if (sendFullMessages) {
+    const currentMessages = [...chat.messages].filter(
+      (message) => !hiddenMessageIds?.has(message.id),
+    );
+    const placeholderMsg = currentMessages.find(
+      (m) => m.id === placeholderMessageId,
+    );
+    if (placeholderMsg) {
+      placeholderMsg.content = fullResponse;
+    }
+    safeSend(event.sender, "chat:response:chunk", {
+      chatId,
+      messages: currentMessages,
+    });
+  } else {
+    // Send incremental update with only the streaming message content
+    // to reduce IPC overhead during high-frequency streaming
+    safeSend(event.sender, "chat:response:chunk", {
+      chatId,
+      streamingMessageId: placeholderMessageId,
+      streamingContent: fullResponse,
+    });
   }
-  safeSend(event.sender, "chat:response:chunk", {
-    chatId,
-    messages: currentMessages,
-  });
 }
 
 function getPlanningQuestionnaireErrorFromStep(step: {