Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🪝 feat: AI SDK-Shaped useChat Facade Over the Chat Contract (#16375)
Marco Beretta4406d34419b2
diff --git a/client/src/hooks/Chat/__tests__/facade.spec.tsx b/client/src/hooks/Chat/__tests__/facade.spec.tsxnew file mode 100644index 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> = {}): TMessage => ({+ messageId: 'response-1',+ conversationId: 'convo-1',+ parentMessageId: 'user-1',+ isCreatedByUser: false,+ text: '',+ content: [],+ ...overrides,+});++const createContract = (overrides: Partial<ChatContract> = {}): 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 }) => (+ <QueryClientProvider client={queryClient}>+ <ChatContext.Provider value={contract}>{children}</ChatContext.Provider>+ </QueryClientProvider>+ );+ 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<TMessage[]>(key)),+ latestMessageId: 'response-1',+ isSubmitting: true,+ });+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <QueryClientProvider client={queryClient}>+ <ChatContext.Provider value={contract}>{children}</ChatContext.Provider>+ </QueryClientProvider>+ );+ const { result } = renderHook(() => useChat(), { wrapper });+ const before = queryClient.getQueryData<TMessage[]>(key);++ act(() => {+ streaming.content = [{ type: ContentTypes.TEXT, text: 'Hello' }];+ queryClient.setQueryData(key, [userMessage, streaming]);+ });++ expect(queryClient.getQueryData<TMessage[]>(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<TMessage[]>(key)),+ });+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <QueryClientProvider client={queryClient}>+ <ChatContext.Provider value={contract}>{children}</ChatContext.Provider>+ </QueryClientProvider>+ );+ 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<TMessage['attachments']>[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.tsnew file mode 100644index 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/[email protected]` (`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<void>;+ /**+ * 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<string, TAttachment[] | undefined>;+ /** Step ids each provider tool-call id already owns, for calls that have no step yet. */+ stepIdsById: Map<string, Set<string>>;+};++const toolContexts = new WeakMap<TMessage, ToolContext>();++/**+ * 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<string, Set<string>>();+ 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<string>();+ 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<typeof isMemoryFailureOutput>[0];++const isMemoryTool = (name: string | undefined): name is MemoryToolName =>+ name === 'set_memory' || name === 'delete_memory';++type StoredToolCall = Parameters<NonNullable<UIMappingOptions['resolveToolFailure']>>[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<UIMappingOptions['resolveToolFailure']> = (+ 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<TMessage, (typeof viewSourceKeys)[number]> };++const views = new WeakMap<TMessage, CachedView>();++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<string, TMessage>, tailId: string | undefined) => {+ const branch = new Set<string>();+ 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,+ };+}