diff --git a/client/src/hooks/Chat/__tests__/facade.spec.tsx b/client/src/hooks/Chat/__tests__/facade.spec.tsx new file mode 100644 index 0000000000..4b19e0e44d --- /dev/null +++ b/client/src/hooks/Chat/__tests__/facade.spec.tsx @@ -0,0 +1,601 @@ +import React from 'react'; +import { act, renderHook } from '@testing-library/react'; +import { QueryKeys, ContentTypes } from 'librechat-data-provider'; +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import type { TConversation, TMessage, TMessageContentParts } from 'librechat-data-provider'; +import type { ChatContract } from '../contract'; +import { ChatContext } from '~/Providers/ChatContext'; +import { useChat } from '../facade'; + +const userMessage: TMessage = { + messageId: 'user-1', + conversationId: 'convo-1', + parentMessageId: null, + isCreatedByUser: true, + text: 'Hi', +}; + +const initialMessages = [userMessage]; + +const response = (overrides: Partial = {}): TMessage => ({ + messageId: 'response-1', + conversationId: 'convo-1', + parentMessageId: 'user-1', + isCreatedByUser: false, + text: '', + content: [], + ...overrides, +}); + +const createContract = (overrides: Partial = {}): ChatContract => { + const noop = jest.fn(); + return { + index: 0, + conversation: { conversationId: 'convo-1' } as TConversation, + setConversation: noop, + newConversation: noop, + preset: null, + setPreset: noop, + optionSettings: {}, + setOptionSettings: noop, + getMessages: jest.fn(() => initialMessages), + messagesKey: 'convo-1', + setMessages: jest.fn(), + setSiblingIdx: noop, + latestMessageId: 'user-1', + latestMessageDepth: 0, + ask: jest.fn(), + regenerate: jest.fn(), + isSubmitting: false, + setIsSubmitting: noop, + handleRegenerate: noop, + handleContinue: noop, + stopGenerating: jest.fn(() => Promise.resolve()), + handleStopGenerating: noop, + abortScroll: false, + setAbortScroll: noop, + files: new Map(), + setFiles: noop, + filesLoading: false, + setFilesLoading: noop, + showPopover: false, + setShowPopover: noop, + feedbackEnabled: false, + ...overrides, + }; +}; + +/** Renders `useChat` under the real `ChatContext`; `rerender` swaps the contract value. */ +const renderChat = (initial: ChatContract) => { + let contract = initial; + const queryClient = new QueryClient(); + const wrapper = ({ children }: { children: React.ReactNode }) => ( + + {children} + + ); + const view = renderHook(() => useChat(), { wrapper }); + return { + queryClient, + ...view, + update: (next: ChatContract) => { + contract = next; + view.rerender(); + }, + }; +}; + +/** A turn as the contract reports it: the cached messages, the branch tail, and the flag. */ +const turn = (messages: TMessage[], isSubmitting: boolean) => + createContract({ + getMessages: jest.fn(() => messages), + latestMessageId: messages[messages.length - 1]?.messageId, + isSubmitting, + }); + +describe('useChat', () => { + it('views the cached messages as UI messages', () => { + const { result } = renderChat(createContract()); + + expect(result.current.id).toBe('convo-1'); + expect(result.current.messages).toEqual([ + { + id: 'user-1', + role: 'user', + metadata: { conversationId: 'convo-1', parentMessageId: null, contentless: true }, + parts: [{ type: 'text', text: 'Hi' }], + }, + ]); + expect(result.current.status).toBe('ready'); + expect(result.current.error).toBeUndefined(); + }); + + it('applies the client tool outcome rules to tool parts', () => { + const memoryFailure = response({ + content: [ + { + type: ContentTypes.TOOL_CALL, + tool_call: { + id: 'mem-1', + type: 'tool_call', + name: 'set_memory', + args: '{"key":"bad key","value":"x"}', + output: 'Invalid key: bad key', + progress: 1, + }, + }, + ], + }); + const { result } = renderChat(turn([userMessage, memoryFailure], false)); + + expect(result.current.messages[1].parts[0]).toMatchObject({ + type: 'tool-set_memory', + state: 'output-error', + errorText: 'Invalid key: bad key', + }); + }); + + it('reports the chat the messages are read from while the conversation catches up', () => { + const { result } = renderChat(createContract({ messagesKey: 'convo-2' })); + + expect(result.current.id).toBe('convo-2'); + }); + + it('streams once a lane placeholder is filled', () => { + const filled = [ + userMessage, + response({ + content: [ + { type: ContentTypes.TEXT, text: 'Lane one' }, + { type: '' }, + ] as unknown as TMessageContentParts[], + }), + ]; + const { result } = renderChat( + createContract({ + getMessages: jest.fn(() => filled), + latestMessageId: 'response-1', + isSubmitting: true, + }), + ); + + expect(result.current.status).toBe('streaming'); + }); + + it('reports a failed user message at the tail as an error', () => { + const failedUser = { ...userMessage, error: true }; + const { result } = renderChat(turn([failedUser], false)); + + expect(result.current.status).toBe('error'); + expect(result.current.error?.message).toBe(''); + }); + + it('stays submitted while the response holds only placeholder parts', () => { + const placeholder = response({ + content: [ + { type: ContentTypes.TEXT, text: '' }, + { type: '' } as unknown as TMessageContentParts, + ], + }); + const { result } = renderChat(turn([userMessage, placeholder], true)); + + expect(result.current.status).toBe('submitted'); + }); + + it('streams once the response carries a generated file and nothing else', () => { + const withFile = response({ files: [{ file_id: 'file-1' }] as TMessage['files'] }); + const { result } = renderChat(turn([userMessage, withFile], true)); + + expect(result.current.status).toBe('streaming'); + }); + + it('reads the error text of an Assistants error part', () => { + const failed = response({ + content: [{ type: ContentTypes.ERROR, text: { value: 'Run failed' } }], + }); + const { result } = renderChat(turn([userMessage, failed], false)); + + expect(result.current.error?.message).toBe('Run failed'); + }); + + it('reports the error part rather than text the failed response kept', () => { + const failed = response({ + text: 'Partial answer', + content: [ + { type: ContentTypes.TEXT, text: 'Partial answer' }, + { type: ContentTypes.ERROR, error: 'Provider timed out' }, + ] as TMessageContentParts[], + }); + const { result } = renderChat(turn([userMessage, failed], false)); + + expect(result.current.status).toBe('error'); + expect(result.current.error?.message).toBe('Provider timed out'); + }); + + it('reads messages a write the listener never saw replaced', () => { + let messages: TMessage[] = [userMessage]; + const contract = createContract({ getMessages: jest.fn(() => messages) }); + const { result, update } = renderChat(contract); + expect(result.current.messages).toHaveLength(1); + + messages = [userMessage, response({ text: 'Loaded' })]; + update({ ...contract }); + + expect(result.current.messages).toHaveLength(2); + }); + + it('re-reads messages when the message cache is written', () => { + let messages: TMessage[] = [userMessage, response({ text: 'Old' })]; + const contract = createContract({ + getMessages: jest.fn(() => messages), + latestMessageId: 'response-1', + }); + const { result, queryClient } = renderChat(contract); + (contract.setMessages as jest.Mock).mockImplementation((next: TMessage[]) => { + messages = next; + queryClient.setQueryData([QueryKeys.messages, 'convo-1'], next); + }); + + act(() => { + result.current.setMessages((views) => [ + { ...views[0], parts: [{ type: 'text', text: 'Edited' }] }, + views[1], + ]); + }); + + expect(result.current.messages[0].parts).toEqual([{ type: 'text', text: 'Edited' }]); + }); + + it('keeps unchanged message views across a streamed update', () => { + const first = response({ content: [{ type: ContentTypes.TEXT, text: 'Hel' }] }); + const { result, update } = renderChat(turn([userMessage, first], true)); + const userView = result.current.messages[0]; + + update( + turn( + [userMessage, response({ content: [{ type: ContentTypes.TEXT, text: 'Hello' }] })], + true, + ), + ); + + expect(result.current.messages[0]).toBe(userView); + expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hello' }]); + }); + + it('remaps a response whose content the stream replaced in place', () => { + const streaming = response({ content: [{ type: ContentTypes.TEXT, text: 'Hel' }] }); + const messages = [userMessage, streaming]; + const { result, update } = renderChat(turn(messages, true)); + expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hel' }]); + + streaming.content = [{ type: ContentTypes.TEXT, text: 'Hello' }]; + update(turn([...messages], true)); + + expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hello' }]); + }); + + it('follows each stream frame written to the cache with the same message references', () => { + const key = [QueryKeys.messages, 'convo-1']; + const streaming = response({ content: [{ type: ContentTypes.TEXT, text: 'Hel' }] }); + const queryClient = new QueryClient(); + queryClient.setQueryData(key, [userMessage, streaming]); + const contract = createContract({ + getMessages: jest.fn(() => queryClient.getQueryData(key)), + latestMessageId: 'response-1', + isSubmitting: true, + }); + const wrapper = ({ children }: { children: React.ReactNode }) => ( + + {children} + + ); + const { result } = renderHook(() => useChat(), { wrapper }); + const before = queryClient.getQueryData(key); + + act(() => { + streaming.content = [{ type: ContentTypes.TEXT, text: 'Hello' }]; + queryClient.setQueryData(key, [userMessage, streaming]); + }); + + expect(queryClient.getQueryData(key)).toBe(before); + expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hello' }]); + expect(result.current.status).toBe('streaming'); + + const findAll = jest.spyOn(queryClient.getQueryCache(), 'findAll'); + act(() => { + streaming.content = [{ type: ContentTypes.TEXT, text: 'Hello there' }]; + queryClient.setQueryData(key, [userMessage, streaming]); + }); + + expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hello there' }]); + expect(findAll).not.toHaveBeenCalled(); + }); + + it('keeps its messages when another conversation is written', () => { + const key = [QueryKeys.messages, 'convo-1']; + const queryClient = new QueryClient(); + queryClient.setQueryData(key, [userMessage]); + const contract = createContract({ + getMessages: jest.fn(() => queryClient.getQueryData(key)), + }); + const wrapper = ({ children }: { children: React.ReactNode }) => ( + + {children} + + ); + const { result } = renderHook(() => useChat(), { wrapper }); + const before = result.current.messages; + + act(() => { + queryClient.setQueryData([QueryKeys.messages, 'convo-2'], [response()]); + }); + + expect(result.current.messages).toBe(before); + }); + + it('remaps a message whose conversation id was set in place', () => { + const promoted = response({ conversationId: null as unknown as string, text: 'Hi there' }); + const messages = [userMessage, promoted]; + const { result, update } = renderChat(turn(messages, false)); + expect(result.current.messages[1].metadata?.conversationId).toBeNull(); + + promoted.conversationId = 'convo-1'; + update(turn([...messages], false)); + + expect(result.current.messages[1].metadata?.conversationId).toBe('convo-1'); + }); + + it('keeps a stepless call clear of attachments its repeated id owns elsewhere', () => { + const memoryError = { + conversationId: 'convo-1', + messageId: 'response-1', + toolCallId: 'mem-1', + stepId: 'step-old', + type: 'memory', + memory: { type: 'error', key: 'k', value: 'v' }, + } as unknown as NonNullable[number]; + const repeated = response({ + attachments: [memoryError], + content: [ + { + type: ContentTypes.TOOL_CALL, + tool_call: { + id: 'mem-1', + stepId: 'step-old', + type: 'tool_call', + name: 'set_memory', + args: '{}', + output: 'Memory set', + progress: 1, + }, + }, + { + type: ContentTypes.TOOL_CALL, + tool_call: { id: 'mem-1', type: 'tool_call', name: 'set_memory', args: '{}' }, + }, + ], + }); + const { result } = renderChat(turn([userMessage, repeated], true)); + + expect(result.current.messages[1].parts[1]).toMatchObject({ state: 'input-available' }); + }); + + it('joins an inserted message to the conversation under the one before it', () => { + const contract = createContract(); + const { result } = renderChat(contract); + + result.current.setMessages((views) => [ + ...views, + { id: 'note-1', role: 'assistant', parts: [{ type: 'text', text: 'Note' }] }, + ]); + + expect(contract.setMessages).toHaveBeenCalledWith([ + userMessage, + expect.objectContaining({ + messageId: 'note-1', + conversationId: 'convo-1', + parentMessageId: 'user-1', + content: [{ type: ContentTypes.TEXT, text: 'Note' }], + }), + ]); + }); + + it('joins an inserted message that names another chat to the active conversation', () => { + const contract = createContract(); + const { result } = renderChat(contract); + + result.current.setMessages((views) => [ + ...views, + { + id: 'note-1', + role: 'assistant', + metadata: { conversationId: 'convo-2', parentMessageId: 'user-1' }, + parts: [{ type: 'text', text: 'Note' }], + }, + ]); + + expect(contract.setMessages).toHaveBeenCalledWith([ + userMessage, + expect.objectContaining({ messageId: 'note-1', conversationId: 'convo-1' }), + ]); + }); + + it('leaves an inserted message unassigned in a new chat even when it names another', () => { + const contract = createContract({ messagesKey: 'new' }); + const { result } = renderChat(contract); + + result.current.setMessages((views) => [ + ...views, + { + id: 'note-1', + role: 'assistant', + metadata: { conversationId: 'convo-2', parentMessageId: 'user-1' }, + parts: [{ type: 'text', text: 'Note' }], + }, + ]); + + expect(contract.setMessages).toHaveBeenCalledWith([ + userMessage, + expect.objectContaining({ messageId: 'note-1', conversationId: null }), + ]); + }); + + it('keeps a stored message in its conversation when its view names another', () => { + const contract = createContract(); + const { result } = renderChat(contract); + + result.current.setMessages((views) => [ + { ...views[0], metadata: { ...views[0].metadata!, conversationId: 'convo-2' } }, + ]); + + expect(contract.setMessages).toHaveBeenCalledWith([ + expect.objectContaining({ messageId: 'user-1', conversationId: 'convo-1' }), + ]); + }); + + it('parents an appended message to the active branch, not a hidden sibling', () => { + const shown = response({ messageId: 'response-a', text: 'Shown' }); + const hidden = response({ messageId: 'response-b', text: 'Hidden' }); + const branches = [userMessage, shown, hidden]; + const contract = createContract({ + getMessages: jest.fn(() => branches), + latestMessageId: 'response-a', + }); + const { result } = renderChat(contract); + + result.current.setMessages((views) => [ + ...views, + { id: 'note-1', role: 'assistant', parts: [{ type: 'text', text: 'Note' }] }, + { id: 'note-2', role: 'assistant', parts: [{ type: 'text', text: 'Next' }] }, + ]); + + expect(contract.setMessages).toHaveBeenCalledWith( + expect.arrayContaining([ + expect.objectContaining({ messageId: 'note-1', parentMessageId: 'response-a' }), + expect.objectContaining({ messageId: 'note-2', parentMessageId: 'note-1' }), + ]), + ); + }); + + it('walks submit, stream, and finish', () => { + const { result, update } = renderChat(turn([userMessage], false)); + expect(result.current.status).toBe('ready'); + + update(turn([userMessage], true)); + expect(result.current.status).toBe('submitted'); + + update(turn([userMessage, response()], true)); + expect(result.current.status).toBe('submitted'); + + const streaming = response({ content: [{ type: ContentTypes.TEXT, text: 'Hel' }] }); + update(turn([userMessage, streaming], true)); + expect(result.current.status).toBe('streaming'); + expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hel' }]); + + const finished = response({ + text: 'Hello', + content: [{ type: ContentTypes.TEXT, text: 'Hello' }], + }); + update(turn([userMessage, finished], false)); + expect(result.current.status).toBe('ready'); + expect(result.current.error).toBeUndefined(); + }); + + it('returns to ready after an abort', () => { + const streaming = response({ content: [{ type: ContentTypes.TEXT, text: 'Hel' }] }); + const { result, update } = renderChat(turn([userMessage, streaming], true)); + expect(result.current.status).toBe('streaming'); + + const stopped = response({ + unfinished: true, + content: [{ type: ContentTypes.TEXT, text: 'Hel' }], + }); + update(turn([userMessage, stopped], false)); + + expect(result.current.status).toBe('ready'); + expect(result.current.messages[1].metadata?.unfinished).toBe(true); + }); + + it('reports a failed turn as an error', () => { + const failed = response({ error: true, text: 'Rate limited', content: undefined }); + const { result, update } = renderChat(turn([userMessage, failed], false)); + + expect(result.current.status).toBe('error'); + expect(result.current.error).toBeInstanceOf(Error); + expect(result.current.error?.message).toBe('Rate limited'); + + const errorPart = response({ + content: [{ type: ContentTypes.ERROR, error: 'Context too long' }], + }); + update(turn([userMessage, errorPart], false)); + expect(result.current.error?.message).toBe('Context too long'); + }); + + it('keeps the same error while the failed message is unchanged', () => { + const failed = response({ error: true, text: 'Rate limited', content: undefined }); + const { result, update } = renderChat(turn([userMessage, failed], false)); + const first = result.current.error; + + update(turn([userMessage, failed], false)); + + expect(result.current.error).toBe(first); + }); + + it('forwards sendMessage to ask with the same arguments', () => { + const contract = createContract(); + const { result } = renderChat(contract); + + result.current.sendMessage({ text: 'Hello', conversationId: 'convo-1' }, { isEdited: true }); + + expect(contract.ask).toHaveBeenCalledTimes(1); + expect(contract.ask).toHaveBeenCalledWith( + { text: 'Hello', conversationId: 'convo-1' }, + { isEdited: true }, + ); + }); + + it('forwards regenerate for a given message and for the branch tail', () => { + const answered = response({ text: 'Hello' }); + const contract = turn([userMessage, answered], false); + const { result } = renderChat(contract); + + result.current.regenerate(); + result.current.regenerate({ messageId: 'user-1' }); + + expect(contract.regenerate).toHaveBeenNthCalledWith(1, { + messageId: 'response-1', + parentMessageId: 'user-1', + isCreatedByUser: false, + }); + expect(contract.regenerate).toHaveBeenNthCalledWith(2, { + messageId: 'user-1', + parentMessageId: null, + isCreatedByUser: true, + }); + }); + + it('forwards stop to stopGenerating', async () => { + const contract = createContract({ isSubmitting: true }); + const { result } = renderChat(contract); + + await result.current.stop(); + + expect(contract.stopGenerating).toHaveBeenCalledTimes(1); + }); + + it('writes UI messages back onto the stored messages', () => { + const answered = response({ + text: 'Hello', + content: [{ type: ContentTypes.TEXT, text: 'Hello' }], + tokenCount: 3, + }); + const contract = turn([userMessage, answered], false); + const { result } = renderChat(contract); + + result.current.setMessages((messages) => messages.slice(0, 1)); + result.current.setMessages(result.current.messages); + + expect(contract.setMessages).toHaveBeenNthCalledWith(1, [userMessage]); + expect(contract.setMessages).toHaveBeenNthCalledWith(2, [userMessage, answered]); + }); +}); diff --git a/client/src/hooks/Chat/facade.ts b/client/src/hooks/Chat/facade.ts new file mode 100644 index 0000000000..5928a61ba1 --- /dev/null +++ b/client/src/hooks/Chat/facade.ts @@ -0,0 +1,362 @@ +import { useRef, useMemo, useCallback, useSyncExternalStore } from 'react'; +import { hashQueryKey, useQueryClient } from '@tanstack/react-query'; +import { + QueryKeys, + Constants, + ContentTypes, + fromUIMessage, + toUIMessage, +} from 'librechat-data-provider'; +import type { TMessage, UIMessage, TAttachment, UIMappingOptions } from 'librechat-data-provider'; +import type { TAskFunction } from '~/common'; +import { isMemoryFailureOutput } from '~/components/Chat/Messages/Content/Parts/MemoryCall'; +import { getToolMeta } from '~/components/Chat/Messages/Content/outcome'; +import { useChatContext } from '~/Providers/ChatContext'; +import { isEmptyContentPart } from '~/utils/messages'; +import { mapAttachments } from '~/utils/map'; + +/** AI SDK `ChatStatus`. */ +export type ChatStatus = 'submitted' | 'streaming' | 'ready' | 'error'; + +/** + * The `useChat` surface of `@ai-sdk/react@4.0.117` (`UseChatHelpers`), over LibreChat's chat + * contract. Members the contract cannot back (`resumeStream`, `addToolOutput`, `clearError`) + * are left out rather than stubbed. + */ +export type UseChatHelpers = { + /** The conversation the messages are read from (the contract's `messagesKey`); AI SDK's chat id. */ + id: string | undefined; + /** The cached messages as `UIMessage`s, re-read whenever the message cache is written. */ + messages: UIMessage[]; + status: ChatStatus; + /** Set when the latest message is an error; LibreChat reports errors as messages. */ + error: Error | undefined; + /** Submits a turn: the contract's `ask`, called with the same arguments. */ + sendMessage: TAskFunction; + /** Regenerates the response to `messageId`, or the latest message of the branch. */ + regenerate: (options?: { messageId?: string }) => void; + stop: () => Promise; + /** + * Writes messages back to the cache, keeping the stored fields the UI view omits. A message + * with no stored counterpart joins the active conversation under the message before it, or + * under the active branch's tail when the message before it is on another branch, unless its + * metadata names a parent. A message keeps the conversation it is stored under. + */ + setMessages: (messages: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => void; +}; + +type ToolContext = { + content: TMessage['content']; + attachments: TMessage['attachments']; + byToolCall: Record; + /** Step ids each provider tool-call id already owns, for calls that have no step yet. */ + stepIdsById: Map>; +}; + +const toolContexts = new WeakMap(); + +/** + * Built once per message snapshot. The stream reuses a response object across frames and + * replaces its `content` and `attachments` arrays, so both are checked, not only the object. + */ +const getToolContext = (message: TMessage): ToolContext => { + const cached = toolContexts.get(message); + if (cached && cached.content === message.content && cached.attachments === message.attachments) { + return cached; + } + const stepIdsById = new Map>(); + for (const part of message.content ?? []) { + if (part?.type !== ContentTypes.TOOL_CALL) { + continue; + } + const { id, stepId } = (part.tool_call ?? {}) as { id?: string; stepId?: string }; + if (!id || !stepId) { + continue; + } + const owned = stepIdsById.get(id) ?? new Set(); + owned.add(stepId); + stepIdsById.set(id, owned); + } + const context: ToolContext = { + content: message.content, + attachments: message.attachments, + byToolCall: mapAttachments(message.attachments ?? []), + stepIdsById, + }; + toolContexts.set(message, context); + return context; +}; + +type MemoryToolName = Parameters[0]; + +const isMemoryTool = (name: string | undefined): name is MemoryToolName => + name === 'set_memory' || name === 'delete_memory'; + +type StoredToolCall = Parameters>[0]; + +/** + * A memory call's output is its own failure message; a background task's output is only its + * dispatch handle, so its reason stands instead. + */ +const getFailureProse = (toolCall: StoredToolCall, background: boolean) => { + const { name, output } = toolCall as { name?: string; output?: unknown }; + if (background || typeof output !== 'string' || !output) { + return undefined; + } + if (!isMemoryTool(name)) { + return undefined; + } + return isMemoryFailureOutput(name, output) ? output : undefined; +}; + +/** + * The client's own tool outcome rules (`getToolMeta`: memory failure prose, background task + * status attachments), handed to the parts mapping, which reads only markers stored on the call. + * A call with no step yet is scoped away from attachments its repeated provider id's other + * steps own, as `summarizeSpan` does. + */ +const resolveToolFailure: NonNullable = ( + toolCall, + message, +) => { + const context = message ? getToolContext(message) : undefined; + const { id, stepId } = toolCall as { id?: string; stepId?: string }; + const siblingStepIds = stepId == null && id ? context?.stepIdsById.get(id) : undefined; + const meta = getToolMeta( + { type: ContentTypes.TOOL_CALL, tool_call: toolCall }, + context?.byToolCall, + siblingStepIds, + ); + if (meta?.cancelled) { + return 'cancelled'; + } + if (!meta?.failed) { + return undefined; + } + return getFailureProse(toolCall, meta.background != null) ?? 'failed'; +}; + +const mappingOptions: UIMappingOptions = { resolveToolFailure }; + +/** + * Every message field a view is built from, identity and metadata included: a stream frame or a + * new chat's promotion can replace these on the same object. + */ +const viewSourceKeys = [ + 'messageId', + 'isCreatedByUser', + 'conversationId', + 'parentMessageId', + 'content', + 'text', + 'files', + 'attachments', + 'error', + 'unfinished', + 'sender', + 'model', + 'endpoint', + 'createdAt', +] as const; + +type CachedView = { view: UIMessage; source: Pick }; + +const views = new WeakMap(); + +const isSameSource = (cached: CachedView, message: TMessage) => + viewSourceKeys.every((key) => cached.source[key] === message[key]); + +/** + * Cached per message and per snapshot of the fields a view reads: a stream frame that replaces a + * response's content remaps that response, while untouched messages keep their views. + */ +const toView = (message: TMessage) => { + const cached = views.get(message); + if (cached && isSameSource(cached, message)) { + return cached.view; + } + const view = toUIMessage(message, mappingOptions); + const source = {} as CachedView['source']; + for (const key of viewSourceKeys) { + Object.assign(source, { [key]: message[key] }); + } + views.set(message, { view, source }); + return view; +}; + +/** + * Placeholder slots (empty text or think, lane placeholders) are not streamed output. A rerun edit + * seeds its response with the retained prefix, which reads as streamed from the start: the + * contract carries no first-delta signal a restored or replaced run could keep correct. + */ +const hasStreamed = (message: TMessage) => + (message.text?.length ?? 0) > 0 || + (message.files?.length ?? 0) > 0 || + (message.content?.some((part) => part != null && !isEmptyContentPart(part)) ?? false); + +/** + * The error part names the failure; top-level text is only the fallback for legacy error rows, + * and never for a failed user message, whose text is what the user sent. + */ +const getErrorText = (message: TMessage) => { + const part = message.content?.find((item) => item?.type === ContentTypes.ERROR); + if (part?.type !== ContentTypes.ERROR) { + return message.isCreatedByUser ? '' : (message.text ?? ''); + } + const text = typeof part.text === 'string' ? part.text : part.text?.value; + return part.error || text || message.text || ''; +}; + +const isErrorMessage = (message: TMessage) => + message.error === true || + (message.content?.some((part) => part?.type === ContentTypes.ERROR) ?? false); + +/** + * `submitted` until the response for the in-flight turn has content, then `streaming`; once the + * turn ends, `error` when the latest message failed (a user message that never got a response + * included) and `ready` otherwise, a stopped turn included. + * `abortScroll` is a scroll hold rather than an abort flag, so a stop is read from the settled + * message, not from it. + */ +export const getChatStatus = (isSubmitting: boolean, latest: TMessage | undefined): ChatStatus => { + if (isSubmitting) { + return latest && !latest.isCreatedByUser && hasStreamed(latest) ? 'streaming' : 'submitted'; + } + return latest && isErrorMessage(latest) ? 'error' : 'ready'; +}; + +/** Ids on the active branch: the contract's tail and its ancestors. */ +const getActiveBranch = (byId: Map, tailId: string | undefined) => { + const branch = new Set(); + let id: string | null | undefined = tailId; + while (id != null && !branch.has(id)) { + branch.add(id); + id = byId.get(id)?.parentMessageId; + } + return branch; +}; + +/** + * AI SDK `useChat`, read and called through `ChatContext`. It holds no state of its own: + * `messages` is `getMessages()` mapped per message, re-read when the message query cache is + * written, and every action forwards to the contract. + */ +export function useChat(): UseChatHelpers { + const { + conversation, + getMessages, + messagesKey, + setMessages: setStoredMessages, + latestMessageId, + isSubmitting, + ask, + regenerate: regenerateTarget, + stopGenerating, + } = useChatContext(); + + const queryClient = useQueryClient(); + const queryHash = useMemo(() => hashQueryKey([QueryKeys.messages, messagesKey]), [messagesKey]); + const subscribe = useCallback( + (onChange: () => void) => + queryClient.getQueryCache().subscribe((event) => { + if (event.query.queryHash === queryHash) { + onChange(); + } + }), + [queryClient, queryHash], + ); + const snapshot = useRef<{ writes: number; stored?: TMessage[] }>(); + /** + * A stream frame replaces a response's content on the same object, so structural sharing can + * keep the cached array. Every write still counts on the query, so the snapshot is keyed by that + * store-owned count and by the array; a write that lands before the listener subscribes is + * still seen. + */ + const readSnapshot = useCallback(() => { + const stored = getMessages(); + const writes = queryClient.getQueryCache().get(queryHash)?.state.dataUpdateCount ?? 0; + const current = snapshot.current; + if (current?.writes === writes && current.stored === stored) { + return current; + } + snapshot.current = { writes, stored }; + return snapshot.current; + }, [getMessages, queryClient, queryHash]); + const cache = useSyncExternalStore(subscribe, readSnapshot, readSnapshot); + + const { messages, latest } = useMemo(() => { + const list: UIMessage[] = []; + let latestMessage: TMessage | undefined; + for (const message of cache.stored ?? []) { + list.push(toView(message)); + if (message.messageId === latestMessageId) { + latestMessage = message; + } + } + return { messages: list, latest: latestMessage }; + }, [cache, latestMessageId]); + + const chatId = messagesKey || conversation?.conversationId || undefined; + const status = getChatStatus(isSubmitting, latest); + const errorText = status === 'error' && latest ? getErrorText(latest) : undefined; + const error = useMemo( + () => (errorText === undefined ? undefined : new Error(errorText)), + [errorText], + ); + + const regenerate = useCallback( + (options?: { messageId?: string }) => { + const messageId = options?.messageId ?? latestMessageId; + const target = getMessages()?.find((message) => message.messageId === messageId); + regenerateTarget( + target + ? { + messageId: target.messageId, + parentMessageId: target.parentMessageId, + isCreatedByUser: target.isCreatedByUser, + } + : { messageId }, + ); + }, + [getMessages, latestMessageId, regenerateTarget], + ); + + const setMessages = useCallback( + (update: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => { + const current = getMessages() ?? []; + const next = typeof update === 'function' ? update(current.map(toView)) : update; + const byId = new Map(current.map((message) => [message.messageId, message])); + const branch = getActiveBranch(byId, latestMessageId); + const conversationId = chatId === Constants.NEW_CONVO ? null : (chatId ?? null); + let previous: { id: string; joined: boolean } | null = null; + const stored = next.map((view) => { + const base = byId.get(view.id); + const message = fromUIMessage(view, base); + message.conversationId = base ? base.conversationId : conversationId; + if (!base) { + if (view.metadata?.parentMessageId === undefined) { + message.parentMessageId = + previous == null || previous.joined + ? (previous?.id ?? null) + : (latestMessageId ?? null); + } + } + previous = { id: message.messageId, joined: !base || branch.has(message.messageId) }; + return message; + }); + setStoredMessages(stored); + }, + [chatId, getMessages, latestMessageId, setStoredMessages], + ); + + return { + id: chatId, + messages, + status, + error, + sendMessage: ask, + regenerate, + stop: stopGenerating, + setMessages, + }; +}