Skip to content

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

🪝 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.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> = {}): 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.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/[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,
+ };
+}