🪝 feat: AI SDK-Shaped useChat Facade Over the Chat Contract (#16375)

* feat: expose the messages key and the submitted response on the chat contract

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: keep the submitted response in the chat host instead of reading the submission atom

The contract's initialResponse is now the response ask submitted, held beside
the host's own state and exposed only while the turn is in flight, so a settled
turn and a run restored after a reload report none, and the submission atom
gains no reader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: take the submission ask builds as a value and document the empty messages key

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: scope the submitted response to its chat and promise seeded positions, not identity

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* docs: note that a new chat's submitted response ends at its saved id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: end the submitted response with its turn and note that the stream can continue the last seeded part

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* refactor: drop the submitted response from the chat contract

A run can be restored, replaced or torn down outside ask, so a copy of the
submitted response kept in the host describes the wrong run on those paths. The
contract keeps messagesKey only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* feat: add an AI SDK-shaped useChat facade over the chat contract

useChat reads ChatContext and presents it as @ai-sdk/react@4.0.117 does:
UI-shaped messages, a submitted/streaming/ready/error status derived
from the in-flight flag and the latest message, and sendMessage,
regenerate, stop and setMessages forwarding to the contract. It holds
no state and changes no existing consumer.

* feat: apply the client tool outcome rules in the useChat facade

The parts mapping reads only the markers stored on a tool call; the facade supplies getToolMeta as its resolveToolFailure, so memory failure prose and background task status attachments reach the UI parts view the same way they reach the tool cards.

* fix: make the useChat facade reactive, placeholder-aware and cached per message

messages re-reads getMessages whenever the message query cache is written, through useSyncExternalStore, so setMessages and other cache writes show without an unrelated context update. Views are cached per message reference, so a streamed chunk remaps only the messages it replaced. status ignores placeholder parts through isEmptyContentPart, the error reads an Assistants error part's text, and a message inserted through setMessages joins the active conversation under the message before it.

* fix: remap streamed responses and scope stepless tool calls in the facade

The content handler reuses a response object across frames and replaces its content, so views are cached per message and per snapshot of the fields a view reads rather than by the object alone. The tool outcome resolver passes getToolMeta the step ids a repeated provider id already owns, so a call without a step is not failed by another step's attachment.

* fix: follow in-place stream frames and tolerate empty tool call slots in the facade

The content handler replaces a response's content on the same object, so
structural sharing keeps the cached message array and the external store saw
no change. The snapshot is now keyed by the message cache write count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: catch unobserved cache writes, keep inserts in the active chat and report the error part

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: key the facade snapshot on the active query's own update count

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: use the filters form of findAll for the facade's messages scan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* perf: look up the facade's holder queries once per cached array

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: read the chat id, first delta and active branch from the chat contract

The facade subscribes to the one message query the contract names instead of
matching cached arrays, reports that query's conversation as the chat id, counts
only parts the submitted response was not seeded with as streamed output, and
parents an appended message to the active branch. A memory call's failure prose
is its error text now that the resolver's reason becomes the part's errorText.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: keep inserted messages in the active chat, unassigned in a new one

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: keep stored messages in their conversation and count generated files as streamed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: read seeded parts by position and report failed user tails as errors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* fix: count a continued last seeded part as streamed and remap views on metadata changes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

* refactor: read streaming status from content alone now the contract has no submitted response

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GQdLgSaTheiBFHYnUDgobw

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 0967e16ea2)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16375
This commit is contained in:
Marco Beretta 2026-09-27 16:13:19 +02:00 • committed by Lia
parent 3a73e508fc
commit 4406d34419
2 changed files with 963 additions and 0 deletions

View file

@ -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]);
});
});

View file

@ -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<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,
};
}