@lobehub/lobehub 2.0.0-next.35 → 2.0.0-next.37

package/src/store/chat/slices/builtinTool/actions/__tests__/localSystem.test.ts

@@ -22,8 +22,8 @@ const mockSet = vi.fn();
 
 const mockStore = {
   internal_triggerLocalFileToolCalling: vi.fn(),
-  internal_updateMessageContent: vi.fn(),
-  internal_updateMessagePluginError: vi.fn(),
+  optimisticUpdateMessageContent: vi.fn(),
+  optimisticUpdateMessagePluginError: vi.fn(),
   set: mockSet,
   toggleLocalFileLoading: vi.fn(),
   updatePluginArguments: vi.fn(),
@@ -58,7 +58,7 @@ describe('localFileSlice', () => {
 
       expect(mockStore.toggleLocalFileLoading).toBeCalledWith('test-id', true);
       expect(mockStore.updatePluginState).toBeCalledWith('test-id', mockState);
-      expect(mockStore.internal_updateMessageContent).toBeCalledWith(
+      expect(mockStore.optimisticUpdateMessageContent).toBeCalledWith(
         'test-id',
         JSON.stringify(mockContent),
       );
@@ -71,7 +71,7 @@ describe('localFileSlice', () => {
 
       await store.internal_triggerLocalFileToolCalling('test-id', mockService);
 
-      expect(mockStore.internal_updateMessagePluginError).toBeCalledWith('test-id', {
+      expect(mockStore.optimisticUpdateMessagePluginError).toBeCalledWith('test-id', {
         body: mockError,
         message: 'test error',
         type: 'PluginServerError',

package/src/store/chat/slices/builtinTool/actions/__tests__/search.test.ts

@@ -30,11 +30,11 @@ describe('search actions', () => {
       activeId: 'session-id',
       activeTopicId: 'topic-id',
       searchLoading: {},
-      internal_updateMessageContent: vi.fn(),
-      internal_updateMessagePluginError: vi.fn(),
+      optimisticUpdateMessageContent: vi.fn(),
+      optimisticUpdateMessagePluginError: vi.fn(),
       updatePluginArguments: vi.fn(),
       updatePluginState: vi.fn(),
-      internal_createMessage: vi.fn(),
+      optimisticCreateMessage: vi.fn(),
       internal_addToolToAssistantMessage: vi.fn(),
       openToolUI: vi.fn(),
     });
@@ -87,7 +87,7 @@ describe('search actions', () => {
         query: 'test query',
       });
       expect(result.current.searchLoading[messageId]).toBe(false);
-      expect(result.current.internal_updateMessageContent).toHaveBeenCalledWith(
+      expect(result.current.optimisticUpdateMessageContent).toHaveBeenCalledWith(
         messageId,
         searchResultsPrompt(expectedContent),
       );
@@ -123,7 +123,7 @@ describe('search actions', () => {
         query: 'test query',
       });
       expect(result.current.searchLoading[messageId]).toBe(false);
-      expect(result.current.internal_updateMessageContent).toHaveBeenCalledWith(
+      expect(result.current.optimisticUpdateMessageContent).toHaveBeenCalledWith(
         messageId,
         searchResultsPrompt([]),
       );
@@ -145,13 +145,13 @@ describe('search actions', () => {
         await search(messageId, query);
       });
 
-      expect(result.current.internal_updateMessagePluginError).toHaveBeenCalledWith(messageId, {
+      expect(result.current.optimisticUpdateMessagePluginError).toHaveBeenCalledWith(messageId, {
         body: error,
         message: 'Search failed',
         type: 'PluginServerError',
       });
       expect(result.current.searchLoading[messageId]).toBe(false);
-      expect(result.current.internal_updateMessageContent).toHaveBeenCalledWith(
+      expect(result.current.optimisticUpdateMessageContent).toHaveBeenCalledWith(
         messageId,
         'Search failed',
       );
@@ -190,7 +190,7 @@ describe('search actions', () => {
         },
       ];
 
-      expect(result.current.internal_updateMessageContent).toHaveBeenCalledWith(
+      expect(result.current.optimisticUpdateMessageContent).toHaveBeenCalledWith(
         messageId,
         crawlResultsPrompt(expectedContent as any),
       );
@@ -216,7 +216,7 @@ describe('search actions', () => {
         await result.current.crawlMultiPages(messageId, { urls: ['https://test.com'] });
       });
 
-      expect(result.current.internal_updateMessageContent).toHaveBeenCalledWith(
+      expect(result.current.optimisticUpdateMessageContent).toHaveBeenCalledWith(
         messageId,
         crawlResultsPrompt(mockResponse.results),
       );
@@ -275,7 +275,7 @@ describe('search actions', () => {
         await saveSearchResult(messageId);
       });
 
-      expect(result.current.internal_createMessage).toHaveBeenCalledWith(
+      expect(result.current.optimisticCreateMessage).toHaveBeenCalledWith(
         expect.objectContaining({
           content: 'test content',
           parentId,
@@ -304,7 +304,7 @@ describe('search actions', () => {
         await saveSearchResult('non-existent-id');
       });
 
-      expect(result.current.internal_createMessage).not.toHaveBeenCalled();
+      expect(result.current.optimisticCreateMessage).not.toHaveBeenCalled();
       expect(result.current.internal_addToolToAssistantMessage).not.toHaveBeenCalled();
     });
   });

package/src/store/chat/slices/builtinTool/actions/interpreter.ts

@@ -11,7 +11,7 @@ import { StateCreator } from 'zustand/vanilla';
 import { useClientDataSWR } from '@/libs/swr';
 import { fileService } from '@/services/file';
 import { pythonService } from '@/services/python';
-import { chatSelectors } from '@/store/chat/selectors';
+import { dbMessageSelectors } from '@/store/chat/selectors';
 import { ChatStore } from '@/store/chat/store';
 import { useFileStore } from '@/store/file';
 import { CodeInterpreterIdentifier } from '@/tools/code-interpreter';
@@ -42,7 +42,7 @@ export const codeInterpreterSlice: StateCreator<
     const {
       toggleInterpreterExecuting,
       updatePluginState,
-      internal_updateMessageContent,
+      optimisticUpdateMessageContent,
       uploadInterpreterFiles,
     } = get();
 
@@ -50,7 +50,7 @@ export const codeInterpreterSlice: StateCreator<
 
     // TODO: 应该只下载 AI 用到的文件
     const files: File[] = [];
-    for (const message of chatSelectors.mainDisplayChats(get())) {
+    for (const message of dbMessageSelectors.dbUserMessages(get())) {
       for (const file of message.fileList ?? []) {
         const blob = await fetch(file.url).then((res) => res.blob());
         files.push(new File([blob], file.name));
@@ -61,7 +61,7 @@ export const codeInterpreterSlice: StateCreator<
       }
       for (const tool of message.tools ?? []) {
         if (tool.identifier === CodeInterpreterIdentifier) {
-          const message = chatSelectors.getMessageByToolCallId(tool.id)(get());
+          const message = dbMessageSelectors.getDbMessageByToolCallId(tool.id)(get());
           if (message?.content) {
             const content = JSON.parse(message.content) as CodeInterpreterResponse;
             for (const file of content.files ?? []) {
@@ -77,10 +77,10 @@ export const codeInterpreterSlice: StateCreator<
     try {
       const result = await pythonService.runPython(params.code, params.packages, files);
       if (result?.files) {
-        await internal_updateMessageContent(id, JSON.stringify(result));
+        await optimisticUpdateMessageContent(id, JSON.stringify(result));
         await uploadInterpreterFiles(id, result.files);
       } else {
-        await internal_updateMessageContent(id, JSON.stringify(result));
+        await optimisticUpdateMessageContent(id, JSON.stringify(result));
       }
     } catch (error) {
       updatePluginState(id, { error });
@@ -105,7 +105,7 @@ export const codeInterpreterSlice: StateCreator<
     id: string,
     updater: (data: CodeInterpreterResponse) => void,
   ) => {
-    const message = chatSelectors.getMessageById(id)(get());
+    const message = dbMessageSelectors.getDbMessageById(id)(get());
     if (!message) return;
 
     const result: CodeInterpreterResponse = JSON.parse(message.content);
@@ -113,7 +113,7 @@ export const codeInterpreterSlice: StateCreator<
 
     const nextResult = produce(result, updater);
 
-    await get().internal_updateMessageContent(id, JSON.stringify(nextResult));
+    await get().optimisticUpdateMessageContent(id, JSON.stringify(nextResult));
   },
 
   uploadInterpreterFiles: async (id: string, files: CodeInterpreterFileItem[]) => {

package/src/store/chat/slices/builtinTool/actions/localSystem.ts

@@ -309,9 +309,9 @@ export const localSystemSlice: StateCreator<
       if (state) {
         await get().updatePluginState(id, state as any);
       }
-      await get().internal_updateMessageContent(id, JSON.stringify(content));
+      await get().optimisticUpdateMessageContent(id, JSON.stringify(content));
     } catch (error) {
-      await get().internal_updateMessagePluginError(id, {
+      await get().optimisticUpdateMessagePluginError(id, {
         body: error,
         message: (error as Error).message,
         type: 'PluginServerError',

package/src/store/chat/slices/builtinTool/actions/search.ts

@@ -43,12 +43,12 @@ export const searchSlice: StateCreator<
   SearchAction
 > = (set, get) => ({
   crawlMultiPages: async (id, params, aiSummary = true) => {
-    const { internal_updateMessageContent } = get();
+    const { optimisticUpdateMessageContent } = get();
     get().toggleSearchLoading(id, true);
     try {
       const { content, success, error, state } = await runtime.crawlMultiPages(params);
 
-      await internal_updateMessageContent(id, content);
+      await optimisticUpdateMessageContent(id, content);
 
       if (success) {
         await get().updatePluginState(id, state);
@@ -67,7 +67,7 @@ export const searchSlice: StateCreator<
       const content = [{ errorMessage: err.message, errorType: err.name }];
 
       const xmlContent = crawlResultsPrompt(content);
-      await internal_updateMessageContent(id, xmlContent);
+      await optimisticUpdateMessageContent(id, xmlContent);
     }
   },
 
@@ -81,7 +81,7 @@ export const searchSlice: StateCreator<
     const message = chatSelectors.getMessageById(id)(get());
     if (!message || !message.plugin) return;
 
-    const { internal_addToolToAssistantMessage, internal_createMessage, openToolUI } = get();
+    const { internal_addToolToAssistantMessage, optimisticCreateMessage, openToolUI } = get();
     // 1. 创建一个新的 tool call message
     const newToolCallId = `tool_call_${nanoid()}`;
 
@@ -108,7 +108,7 @@ export const searchSlice: StateCreator<
 
     const [result] = await Promise.all([
       // 1. 添加 tool message
-      internal_createMessage(toolMessage),
+      optimisticCreateMessage(toolMessage),
       // 2. 将这条 tool call message 插入到 ai 消息的 tools 中
       addToolItem(),
     ]);
@@ -127,7 +127,7 @@ export const searchSlice: StateCreator<
       await get().updatePluginState(id, state);
     } else {
       if ((error as Error).message === SEARCH_SEARXNG_NOT_CONFIG) {
-        await get().internal_updateMessagePluginError(id, {
+        await get().optimisticUpdateMessagePluginError(id, {
           body: {
             provider: 'searxng',
           },
@@ -135,7 +135,7 @@ export const searchSlice: StateCreator<
           type: 'PluginSettingsInvalid',
         });
       } else {
-        await get().internal_updateMessagePluginError(id, {
+        await get().optimisticUpdateMessagePluginError(id, {
           body: error,
           message: (error as Error).message,
           type: 'PluginServerError',
@@ -145,7 +145,7 @@ export const searchSlice: StateCreator<
 
     get().toggleSearchLoading(id, false);
 
-    await get().internal_updateMessageContent(id, content);
+    await get().optimisticUpdateMessageContent(id, content);
 
     // 如果 aiSummary 为 true，则会自动触发总结
     return aiSummary;

package/src/store/chat/slices/message/action.test.ts

@@ -65,17 +65,17 @@ describe('chatMessage actions', () => {
     it('should return early if activeId is undefined', async () => {
       useChatStore.setState({ activeId: undefined });
       const { result } = renderHook(() => useChatStore());
-      const updateInputMessageSpy = vi.spyOn(result.current, 'updateInputMessage');
+      const updateMessageInputSpy = vi.spyOn(result.current, 'updateMessageInput');
 
       await act(async () => {
         await result.current.addAIMessage();
       });
 
       expect(messageService.createMessage).not.toHaveBeenCalled();
-      expect(updateInputMessageSpy).not.toHaveBeenCalled();
+      expect(updateMessageInputSpy).not.toHaveBeenCalled();
     });
 
-    it('should call internal_createMessage with correct parameters', async () => {
+    it('should call optimisticCreateMessage with correct parameters', async () => {
       const inputMessage = 'Test input message';
       useChatStore.setState({ inputMessage });
       const { result } = renderHook(() => useChatStore());
@@ -92,14 +92,14 @@ describe('chatMessage actions', () => {
       });
     });
 
-    it('should call updateInputMessage with empty string', async () => {
+    it('should call updateMessageInput with empty string', async () => {
       const { result } = renderHook(() => useChatStore());
-      const updateInputMessageSpy = vi.spyOn(result.current, 'updateInputMessage');
+      const updateMessageInputSpy = vi.spyOn(result.current, 'updateMessageInput');
       await act(async () => {
         await result.current.addAIMessage();
       });
 
-      expect(updateInputMessageSpy).toHaveBeenCalledWith('');
+      expect(updateMessageInputSpy).toHaveBeenCalledWith('');
     });
   });
 
@@ -107,17 +107,17 @@ describe('chatMessage actions', () => {
     it('should return early if activeId is undefined', async () => {
       useChatStore.setState({ activeId: undefined });
       const { result } = renderHook(() => useChatStore());
-      const updateInputMessageSpy = vi.spyOn(result.current, 'updateInputMessage');
+      const updateMessageInputSpy = vi.spyOn(result.current, 'updateMessageInput');
 
       await act(async () => {
         await result.current.addUserMessage({ message: 'test message' });
       });
 
       expect(messageService.createMessage).not.toHaveBeenCalled();
-      expect(updateInputMessageSpy).not.toHaveBeenCalled();
+      expect(updateMessageInputSpy).not.toHaveBeenCalled();
     });
 
-    it('should call internal_createMessage with correct parameters', async () => {
+    it('should call optimisticCreateMessage with correct parameters', async () => {
       const message = 'Test user message';
       const fileList = ['file-id-1', 'file-id-2'];
       useChatStore.setState({
@@ -140,7 +140,7 @@ describe('chatMessage actions', () => {
       });
     });
 
-    it('should call internal_createMessage with threadId when activeThreadId is set', async () => {
+    it('should call optimisticCreateMessage with threadId when activeThreadId is set', async () => {
       const message = 'Test user message';
       const activeThreadId = 'thread-123';
       useChatStore.setState({
@@ -164,15 +164,15 @@ describe('chatMessage actions', () => {
       });
     });
 
-    it('should call updateInputMessage with empty string', async () => {
+    it('should call updateMessageInput with empty string', async () => {
       const { result } = renderHook(() => useChatStore());
-      const updateInputMessageSpy = vi.spyOn(result.current, 'updateInputMessage');
+      const updateMessageInputSpy = vi.spyOn(result.current, 'updateMessageInput');
 
       await act(async () => {
         await result.current.addUserMessage({ message: 'test' });
       });
 
-      expect(updateInputMessageSpy).toHaveBeenCalledWith('');
+      expect(updateMessageInputSpy).toHaveBeenCalledWith('');
     });
 
     it('should handle message without fileList', async () => {
@@ -265,7 +265,7 @@ describe('chatMessage actions', () => {
       expect(replaceMessagesSpy).toHaveBeenCalledWith(mockMessages);
     });
 
-    it('deleteMessage should remove group message with all children', async () => {
+    it('deleteMessage should remove assistantGroup message with all children', async () => {
       const { result } = renderHook(() => useChatStore());
       const groupMessageId = 'group-message-id';
       const removeMessagesSpy = vi.spyOn(messageService, 'removeMessages');
@@ -285,18 +285,20 @@ describe('chatMessage actions', () => {
           activeTopicId: undefined,
           messagesMap: {
             [messageMapKey('session-id')]: [
-              { id: groupMessageId, role: 'group', content: 'Group message' } as UIChatMessage,
               {
-                id: 'child-1',
-                parentId: groupMessageId,
-                role: 'assistant',
-                content: 'Child 1',
-              } as UIChatMessage,
-              {
-                id: 'child-2',
-                parentId: groupMessageId,
-                role: 'assistant',
-                content: 'Child 2',
+                id: groupMessageId,
+                role: 'assistantGroup',
+                content: '',
+                children: [
+                  {
+                    id: 'child-1',
+                    content: 'Child 1',
+                  },
+                  {
+                    id: 'child-2',
+                    content: 'Child 2',
+                  },
+                ],
               } as UIChatMessage,
               { id: 'other-message', role: 'user', content: 'Other' } as UIChatMessage,
             ],
@@ -334,25 +336,29 @@ describe('chatMessage actions', () => {
           activeTopicId: undefined,
           messagesMap: {
             [messageMapKey('session-id')]: [
-              { id: groupMessageId, role: 'group', content: 'Group message' } as UIChatMessage,
-              {
-                id: 'child-1',
-                parentId: groupMessageId,
-                role: 'assistant',
-                content: 'Child with tools',
-                tools: [{ id: 'tool1' }],
-              } as UIChatMessage,
               {
-                id: 'tool-result-1',
-                tool_call_id: 'tool1',
-                role: 'tool',
-                content: 'Tool result',
-              } as UIChatMessage,
-              {
-                id: 'child-2',
-                parentId: groupMessageId,
-                role: 'assistant',
-                content: 'Child 2',
+                id: groupMessageId,
+                role: 'assistantGroup',
+                content: '',
+                children: [
+                  {
+                    id: 'child-1',
+                    content: 'Child with tools',
+                    tools: [
+                      {
+                        id: 'tool1',
+                        result: {
+                          id: 'tool-result-1',
+                          content: 'Tool result',
+                        },
+                      },
+                    ],
+                  },
+                  {
+                    id: 'child-2',
+                    content: 'Child 2',
+                  },
+                ],
               } as UIChatMessage,
               { id: 'other-message', role: 'user', content: 'Other' } as UIChatMessage,
             ],
@@ -363,7 +369,7 @@ describe('chatMessage actions', () => {
         await result.current.deleteMessage(groupMessageId);
       });
 
-      // Should delete group message + all children + tool results of children
+      // Should delete assistantGroup message + all children + tool results of children
       expect(removeMessagesSpy).toHaveBeenCalledWith(
         [groupMessageId, 'child-1', 'child-2', 'tool-result-1'],
         {
@@ -413,24 +419,29 @@ describe('chatMessage actions', () => {
       const removeMessageSpy = vi.spyOn(messageService, 'removeMessage');
 
       act(() => {
+        const rawMessages = [
+          {
+            id: messageId,
+            role: 'assistant',
+            tools: [{ id: 'tool1' }, { id: 'tool2' }],
+          } as UIChatMessage,
+          {
+            id: '2',
+            parentId: messageId,
+            tool_call_id: 'tool1',
+            role: 'tool',
+          } as UIChatMessage,
+          { id: '3', tool_call_id: 'tool2', role: 'tool' } as UIChatMessage,
+        ];
+
         useChatStore.setState({
           activeId: 'session-id',
           activeTopicId: undefined,
+          dbMessagesMap: {
+            [messageMapKey('session-id')]: rawMessages,
+          },
           messagesMap: {
-            [messageMapKey('session-id')]: [
-              {
-                id: messageId,
-                role: 'assistant',
-                tools: [{ id: 'tool1' }, { id: 'tool2' }],
-              } as UIChatMessage,
-              {
-                id: '2',
-                parentId: messageId,
-                tool_call_id: 'tool1',
-                role: 'tool',
-              } as UIChatMessage,
-              { id: '3', tool_call_id: 'tool2', role: 'tool' } as UIChatMessage,
-            ],
+            [messageMapKey('session-id')]: rawMessages,
           },
         });
       });
@@ -467,12 +478,12 @@ describe('chatMessage actions', () => {
     });
   });
 
-  describe('updateInputMessage', () => {
-    it('updateInputMessage should update the input message state', () => {
+  describe('updateMessageInput', () => {
+    it('updateMessageInput should update the input message state', () => {
       const { result } = renderHook(() => useChatStore());
       const newInputMessage = 'Updated message';
       act(() => {
-        result.current.updateInputMessage(newInputMessage);
+        result.current.updateMessageInput(newInputMessage);
       });
 
       expect(result.current.inputMessage).toEqual(newInputMessage);
@@ -484,7 +495,7 @@ describe('chatMessage actions', () => {
       const { result } = renderHook(() => useChatStore());
 
       act(() => {
-        result.current.updateInputMessage(inputMessage);
+        result.current.updateMessageInput(inputMessage);
       });
 
       expect(result.current.inputMessage).toBe(inputMessage);
@@ -597,15 +608,15 @@ describe('chatMessage actions', () => {
     });
   });
 
-  describe('internal_updateMessageContent', () => {
-    it('should call messageService.internal_updateMessageContent with correct parameters', async () => {
+  describe('optimisticUpdateMessageContent', () => {
+    it('should call messageService.optimisticUpdateMessageContent with correct parameters', async () => {
       const { result } = renderHook(() => useChatStore());
       const messageId = 'message-id';
       const newContent = 'Updated content';
 
       const spy = vi.spyOn(messageService, 'updateMessage');
       await act(async () => {
-        await result.current.internal_updateMessageContent(messageId, newContent);
+        await result.current.optimisticUpdateMessageContent(messageId, newContent);
       });
 
       expect(spy).toHaveBeenCalledWith(
@@ -622,7 +633,7 @@ describe('chatMessage actions', () => {
       const internal_dispatchMessageSpy = vi.spyOn(result.current, 'internal_dispatchMessage');
 
       await act(async () => {
-        await result.current.internal_updateMessageContent(messageId, newContent);
+        await result.current.optimisticUpdateMessageContent(messageId, newContent);
       });
 
       expect(internal_dispatchMessageSpy).toHaveBeenCalledWith({
@@ -638,7 +649,7 @@ describe('chatMessage actions', () => {
       const newContent = 'Updated content';
 
       await act(async () => {
-        await result.current.internal_updateMessageContent(messageId, newContent);
+        await result.current.optimisticUpdateMessageContent(messageId, newContent);
       });
 
       expect(result.current.refreshMessages).toHaveBeenCalled();
@@ -770,7 +781,7 @@ describe('chatMessage actions', () => {
       });
     });
 
-    it('should call internal_updateMessageContent with correct parameters', async () => {
+    it('should call optimisticUpdateMessageContent with correct parameters', async () => {
       const messageId = 'message-id';
       const content = 'Updated content';
       const { result } = renderHook(() => useChatStore());

package/src/store/chat/slices/message/actions/index.ts

@@ -0,0 +1,39 @@
+import { StateCreator } from 'zustand/vanilla';
+
+import { ChatStore } from '@/store/chat/store';
+
+import { MessageInternalsAction, messageInternals } from './internals';
+import { MessageOptimisticUpdateAction, messageOptimisticUpdate } from './optimisticUpdate';
+import { MessagePublicApiAction, messagePublicApi } from './publicApi';
+import { MessageQueryAction, messageQuery } from './query';
+import { MessageRuntimeStateAction, messageRuntimeState } from './runtimeState';
+
+/**
+ * Combined message action interface
+ * Aggregates all message-related actions
+ */
+export interface ChatMessageAction
+  extends MessagePublicApiAction,
+    MessageOptimisticUpdateAction,
+    MessageQueryAction,
+    MessageRuntimeStateAction,
+    MessageInternalsAction {
+  /**/
+}
+
+/**
+ * Combined message action creator
+ * Merges all message action modules
+ */
+export const chatMessage: StateCreator<
+  ChatStore,
+  [['zustand/devtools', never]],
+  [],
+  ChatMessageAction
+> = (...params) => ({
+  ...messagePublicApi(...params),
+  ...messageOptimisticUpdate(...params),
+  ...messageQuery(...params),
+  ...messageRuntimeState(...params),
+  ...messageInternals(...params),
+});

package/src/store/chat/slices/message/actions/internals.ts

@@ -0,0 +1,77 @@
+import { parse } from '@lobechat/conversation-flow';
+import { TraceEventPayloads } from '@lobechat/types';
+import isEqual from 'fast-deep-equal';
+import { StateCreator } from 'zustand/vanilla';
+
+import { traceService } from '@/services/trace';
+import { ChatStore } from '@/store/chat/store';
+
+import { displayMessageSelectors } from '../../../selectors';
+import { messageMapKey } from '../../../utils/messageMapKey';
+import { MessageDispatch, messagesReducer } from '../reducer';
+
+/**
+ * Internal core methods that serve as building blocks for other actions
+ */
+export interface MessageInternalsAction {
+  /**
+   * update message at the frontend
+   * this method will not update messages to database
+   */
+  internal_dispatchMessage: (
+    payload: MessageDispatch,
+    context?: { sessionId: string; topicId?: string | null },
+  ) => void;
+
+  /**
+   * trace message events for analytics
+   */
+  internal_traceMessage: (id: string, payload: TraceEventPayloads) => Promise<void>;
+}
+
+export const messageInternals: StateCreator<
+  ChatStore,
+  [['zustand/devtools', never]],
+  [],
+  MessageInternalsAction
+> = (set, get) => ({
+  // the internal process method of the AI message
+  internal_dispatchMessage: (payload, context) => {
+    const activeId = typeof context !== 'undefined' ? context.sessionId : get().activeId;
+    const topicId = typeof context !== 'undefined' ? context.topicId : get().activeTopicId;
+
+    const messagesKey = messageMapKey(activeId, topicId);
+
+    // Get raw messages from dbMessagesMap and apply reducer
+    const rawMessages = get().dbMessagesMap[messagesKey] || [];
+    const updatedRawMessages = messagesReducer(rawMessages, payload);
+
+    const nextDbMap = { ...get().dbMessagesMap, [messagesKey]: updatedRawMessages };
+
+    if (isEqual(nextDbMap, get().dbMessagesMap)) return;
+
+    // parse to get display messages
+    const { flatList } = parse(updatedRawMessages);
+    const nextDisplayMap = { ...get().messagesMap, [messagesKey]: flatList };
+
+    set({ dbMessagesMap: nextDbMap, messagesMap: nextDisplayMap }, false, {
+      payload,
+      type: `dispatchMessage/${payload.type}`,
+    });
+  },
+
+  internal_traceMessage: async (id, payload) => {
+    // tracing the diff of update
+    const message = displayMessageSelectors.getDisplayMessageById(id)(get());
+    if (!message) return;
+
+    const traceId = message?.traceId;
+    const observationId = message?.observationId;
+
+    if (traceId && message?.role === 'assistant') {
+      traceService
+        .traceEvent({ content: message.content, observationId, traceId, ...payload })
+        .catch();
+    }
+  },
+});