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: Count Core Chat Changes and Let Hosts Replace Its Messages (#17084)
Marco Beretta69606fd6a599
diff --git a/packages/chat/src/core/__tests__/lifecycle.spec.ts b/packages/chat/src/core/__tests__/lifecycle.spec.tsnew file mode 100644index 0000000000..fac11af842--- /dev/null+++ b/packages/chat/src/core/__tests__/lifecycle.spec.ts@@ -0,0 +1,393 @@+import { StepEvents } from 'librechat-data-provider';+import type { TMessage, TPayload, ChatEvent } from 'librechat-data-provider';+import type { ChatStream, ChatStatus, ChatTransport, ChatConnection } from '../types';+import type { ChatState, ChatFinishResult } from '../chat';+import { Chat } from '../chat';++/**+ * The chat lifecycle as a table: every generation state a chat can be in, crossed with every event+ * that can reach it, and the status, connection and completions each pair must produce.+ */++type TestStream = ChatStream & { push(event: ChatEvent): void; closed(): boolean };++const createStream = (meta: { streamId?: string; generationCreatedAt?: number } = {}) => {+ const queued: ChatEvent[] = [];+ let wake: (() => void) | undefined;+ let closed = false;+ const stream: TestStream = {+ ...meta,+ push(event) {+ queued.push(event);+ wake?.();+ },+ close() {+ closed = true;+ wake?.();+ },+ closed: () => closed,+ async *[Symbol.asyncIterator]() {+ while (true) {+ while (queued.length > 0) {+ yield queued.shift() as ChatEvent;+ }+ if (closed) {+ return;+ }+ await new Promise<void>((resolve) => {+ wake = resolve;+ });+ }+ },+ };+ return stream;+};++const userMessage: TMessage = {+ messageId: 'user-1',+ conversationId: 'convo-1',+ parentMessageId: null,+ isCreatedByUser: true,+ text: 'Hi',+};++const placeholder: TMessage = {+ messageId: 'response-1',+ conversationId: 'convo-1',+ parentMessageId: 'user-1',+ isCreatedByUser: false,+ text: '',+ content: [],+};++const payload = { endpoint: 'agents', conversationId: 'convo-1', text: 'Hi' } as TPayload;++const stepEvent: ChatEvent = {+ type: 'step',+ data: { event: StepEvents.ON_MESSAGE_DELTA, data: { id: 'step-1', delta: { content: [] } } },+};++const finalEvent = (data: Partial<Extract<ChatEvent, { type: 'final' }>['data']> = {}) =>+ ({+ type: 'final',+ data: { final: true, requestMessage: userMessage, responseMessage: placeholder, ...data },+ }) as ChatEvent;++const dropEvent = { type: 'error', status: 0, data: 'offline' } as ChatEvent;++const networkError = () => Object.assign(new Error('Network Error'), { code: 'ERR_NETWORK' });++const flush = async () => {+ for (let i = 0; i < 5; i++) {+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ }+};++type Harness = {+ chat: Chat;+ transport: jest.Mocked<ChatTransport>;+ finishes: ChatFinishResult[];+ /** The stream the chat is attached to. */+ stream?: TestStream;+ /** Settles a start or reattachment the state left pending. */+ open?: () => void;+ /** Fails that pending start or reattachment as a request that never got a response. */+ fail?: () => void;+ outcome?: string;+};++const createHarness = (): Harness => {+ let messages: TMessage[] = [];+ const state: ChatState = {+ status: 'ready' as ChatStatus,+ error: undefined,+ connection: 'idle' as ChatConnection,+ get messages() {+ return messages;+ },+ replaceMessages(next) {+ messages = next;+ },+ };+ const finishes: ChatFinishResult[] = [];+ const harness = { finishes } as Harness;+ harness.transport = {+ sendMessages: jest.fn(),+ reconnectToStream: jest.fn(async () => null),+ abort: jest.fn(async () => ({ success: true })),+ } as unknown as jest.Mocked<ChatTransport>;+ harness.chat = new Chat({+ id: 'convo-1',+ state,+ transport: harness.transport,+ prepareRequest: () => ({+ payload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ }),+ onFinish: (result) => finishes.push(result),+ });+ return harness;+};++const send = (h: Harness) => {+ h.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }).then(+ () => undefined,+ () => undefined,+ );+};++/**+ * A request that stays open until the test opens or fails it. It ignores the abort signal, as a+ * transport may, so the chat itself has to let go of a start that answers late.+ */+const pending = <T>(h: Harness, opened: () => T) =>+ new Promise<T>((resolve, reject) => {+ h.open = () => resolve(opened());+ h.fail = () => reject(networkError());+ });++/** Drives a fresh chat into each generation state. */+const states: Record<string, (h: Harness) => Promise<void>> = {+ /** The start request is in flight; no stream yet. */+ starting: async (h) => {+ h.transport.sendMessages.mockImplementation(() =>+ pending(h, () => {+ h.stream = createStream({ streamId: 'convo-1', generationCreatedAt: 100 });+ return { status: 'stream' as const, stream: h.stream };+ }),+ );+ send(h);+ await flush();+ },+ /** Streaming a generation this chat started. */+ attached: async (h) => {+ h.stream = createStream({ streamId: 'convo-1', generationCreatedAt: 100 });+ h.transport.sendMessages.mockResolvedValue({ status: 'stream', stream: h.stream });+ send(h);+ await flush();+ h.stream.push(stepEvent);+ await flush();+ },+ /** The server finished the turn before the chat attached. */+ settled: async (h) => {+ h.transport.sendMessages.mockResolvedValue({+ status: 'settled',+ conversationId: 'convo-1',+ generationProtocolVersion: 2,+ });+ send(h);+ await flush();+ },+ /** The start was answered with a newer generation, whose reattachment is in flight. */+ replacing: async (h) => {+ h.transport.sendMessages.mockResolvedValue({+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ });+ h.transport.reconnectToStream.mockImplementation(() =>+ pending(h, () => {+ h.stream = createStream({ streamId: 'stream-2', generationCreatedAt: 200 });+ return h.stream;+ }),+ );+ send(h);+ await flush();+ },+ /** The start was answered with a newer generation, which the chat reattached to. */+ replaced: async (h) => {+ const stream = createStream({ streamId: 'stream-2', generationCreatedAt: 200 });+ h.stream = stream;+ h.transport.sendMessages.mockResolvedValue({+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ });+ h.transport.reconnectToStream.mockResolvedValue(stream);+ send(h);+ await flush();+ stream.push(stepEvent);+ await flush();+ },+ /** The generation ended with an abort frame. */+ aborted: async (h) => {+ await states.attached(h);+ h.stream?.push({ type: 'abort', data: {} } as ChatEvent);+ await flush();+ h.stream = undefined;+ },+ /** The generation failed with a server error frame. */+ failed: async (h) => {+ await states.attached(h);+ h.stream?.push({ type: 'error', status: 500, data: 'failed' } as ChatEvent);+ await flush();+ h.stream = undefined;+ },+};++const record = (h: Harness, settle: Promise<unknown>) =>+ settle.then(+ () => {+ h.outcome = 'ok';+ },+ (error: Error) => {+ h.outcome = error.message;+ },+ );++/** Every event that can reach a chat. */+const events: Record<string, (h: Harness) => Promise<void>> = {+ streamEnd: async (h) => {+ h.open?.();+ await flush();+ h.stream?.close();+ await flush();+ },+ networkDrop: async (h) => {+ if (h.stream) {+ h.stream.push(dropEvent);+ } else {+ h.fail?.();+ }+ await flush();+ },+ final: async (h) => {+ h.open?.();+ await flush();+ h.stream?.push(finalEvent());+ await flush();+ },+ reconcile: async (h) => {+ h.open?.();+ await flush();+ h.stream?.push(finalEvent({ reconcile: true, reconcileReason: 'terminal_payload_missing' }));+ await flush();+ },+ newTurn: async (h) => {+ const before = h.transport.sendMessages.mock.calls.length;+ h.transport.sendMessages.mockResolvedValue({+ status: 'settled',+ conversationId: 'convo-1',+ generationProtocolVersion: 2,+ });+ await record(h, h.chat.sendMessage({ parts: [{ type: 'text', text: 'Again' }] }));+ h.outcome =+ h.transport.sendMessages.mock.calls.length > before ? `sent:${h.outcome}` : h.outcome;+ await flush();+ },+ clearError: async (h) => {+ h.chat.clearError();+ await flush();+ },+ dispose: async (h) => {+ h.chat.dispose();+ await flush();+ h.outcome = h.stream?.closed() ? 'closed' : 'open';+ },+ /** A start or reattachment that answers after the chat let it go has its stream closed. */+ disposeThenOpen: async (h) => {+ h.chat.dispose();+ await flush();+ h.open?.();+ await flush();+ h.outcome = h.stream?.closed() ? 'closed' : 'open';+ },+};++type Expected = {+ status: ChatStatus;+ connection?: ChatConnection;+ /** How many times `onFinish` ran, over the state and the event together. */+ finishes: number;+ /** Flags of the last `onFinish`. */+ last?: Partial<Pick<ChatFinishResult, 'isAbort' | 'isDisconnect' | 'isError' | 'isSettled'>>;+ /** The message ids the list holds afterwards. */+ messages?: string[];+ /** The event's own result: `ok`, a rejection message fragment, `sent:` for a new turn. */+ outcome?: string;+};++const done = { isAbort: false, isDisconnect: false, isError: false, isSettled: false };+const aborted = { ...done, isAbort: true };+const dropped = { ...done, isError: true, isDisconnect: true };+const failed = { ...done, isError: true };+const settled = { ...done, isSettled: true };+const turn = ['user-1', 'response-1'];++const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [+ ['starting', 'streamEnd', { status: 'error', connection: 'idle', finishes: 1, last: dropped }],+ ['starting', 'networkDrop', { status: 'error', connection: 'idle', finishes: 1, last: dropped }],+ ['starting', 'final', { status: 'ready', connection: 'idle', finishes: 1, last: done }],+ ['starting', 'newTurn', { status: 'submitted', finishes: 0, outcome: 'in flight' }],+ ['starting', 'dispose', { status: 'submitted', connection: 'idle', finishes: 0, messages: turn }],+ ['starting', 'disposeThenOpen', { status: 'submitted', finishes: 0, outcome: 'closed' }],++ ['attached', 'streamEnd', { status: 'error', connection: 'idle', finishes: 1, last: dropped }],+ ['attached', 'networkDrop', { status: 'error', connection: 'idle', finishes: 1, last: dropped }],+ ['attached', 'final', { status: 'ready', connection: 'idle', finishes: 1, last: done }],+ ['attached', 'reconcile', { status: 'ready', finishes: 1, last: settled }],+ ['attached', 'newTurn', { status: 'streaming', finishes: 0, outcome: 'in flight' }],+ ['attached', 'clearError', { status: 'streaming', finishes: 0 }],+ [+ 'attached',+ 'dispose',+ { status: 'streaming', connection: 'idle', finishes: 0, messages: turn, outcome: 'closed' },+ ],++ ['settled', 'newTurn', { status: 'ready', finishes: 2, last: settled, outcome: 'sent:ok' }],+ ['settled', 'dispose', { status: 'ready', connection: 'idle', finishes: 1, messages: turn }],++ ['replacing', 'final', { status: 'ready', connection: 'idle', finishes: 1, last: done }],+ ['replacing', 'reconcile', { status: 'ready', finishes: 1, last: settled }],+ ['replacing', 'streamEnd', { status: 'error', connection: 'idle', finishes: 1, last: dropped }],+ ['replacing', 'networkDrop', { status: 'error', connection: 'idle', finishes: 1, last: dropped }],+ [+ 'replacing',+ 'newTurn',+ { status: 'submitted', connection: 'reconnecting', finishes: 0, outcome: 'in flight' },+ ],+ ['replacing', 'dispose', { status: 'submitted', connection: 'idle', finishes: 0, messages: [] }],+ ['replacing', 'disposeThenOpen', { status: 'submitted', finishes: 0, outcome: 'closed' }],++ ['replaced', 'networkDrop', { status: 'error', finishes: 1, last: dropped }],+ ['replaced', 'streamEnd', { status: 'error', finishes: 1, last: dropped }],+ ['replaced', 'final', { status: 'ready', finishes: 1, last: done }],+ ['replaced', 'newTurn', { status: 'streaming', finishes: 0, outcome: 'in flight' }],+ ['replaced', 'dispose', { status: 'streaming', connection: 'idle', finishes: 0, messages: [] }],++ ['aborted', 'newTurn', { status: 'ready', finishes: 2, last: settled, outcome: 'sent:ok' }],+ ['aborted', 'clearError', { status: 'ready', finishes: 1, last: aborted }],++ ['failed', 'clearError', { status: 'ready', finishes: 1, last: failed }],+ ['failed', 'newTurn', { status: 'ready', finishes: 2, last: settled, outcome: 'sent:ok' }],+ ['failed', 'dispose', { status: 'error', connection: 'idle', finishes: 1, messages: turn }],+];++describe('Chat lifecycle', () => {+ it.each(table)('%s + %s', async (state, event, expected) => {+ const h = createHarness();+ await states[state](h);+ await events[event](h);++ expect(h.chat.status).toBe(expected.status);+ if (expected.connection) {+ expect(h.chat.connection).toBe(expected.connection);+ }+ expect(h.finishes).toHaveLength(expected.finishes);+ if (expected.last) {+ expect(h.finishes[h.finishes.length - 1]).toMatchObject(expected.last);+ }+ if (expected.messages) {+ expect(h.chat.messages.map((message) => message.messageId)).toEqual(expected.messages);+ }+ if (expected.outcome !== undefined) {+ expect(h.outcome).toContain(expected.outcome);+ }+ expect(h.transport.abort).not.toHaveBeenCalled();+ });+});diff --git a/packages/chat/src/core/__tests__/writes.spec.ts b/packages/chat/src/core/__tests__/writes.spec.tsnew file mode 100644index 0000000000..5dbea69510--- /dev/null+++ b/packages/chat/src/core/__tests__/writes.spec.ts@@ -0,0 +1,215 @@+import type { TMessage, TPayload, ChatEvent } from 'librechat-data-provider';+import type { ChatStream, ChatSendResult, ChatTransport } from '../types';+import type { ChatState } from '../chat';+import { Chat } from '../chat';++const earlier: TMessage = {+ messageId: 'earlier-1',+ conversationId: 'convo-1',+ parentMessageId: null,+ isCreatedByUser: true,+ text: 'Earlier',+};++const userMessage: TMessage = { ...earlier, messageId: 'user-1', parentMessageId: 'earlier-1' };++const placeholder: TMessage = {+ messageId: 'response-1',+ conversationId: 'convo-1',+ parentMessageId: 'user-1',+ isCreatedByUser: false,+ text: '',+ content: [],+};++const payload = { endpoint: 'agents', conversationId: 'convo-1', text: 'Hi' } as TPayload;++const flush = async () => {+ for (let i = 0; i < 5; i++) {+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ }+};++const emptyStream = (): ChatStream => ({+ close: () => undefined,+ async *[Symbol.asyncIterator]() {+ yield {+ type: 'final',+ data: { final: true, requestMessage: null, responseMessage: null },+ } as ChatEvent;+ },+});++const createState = (initial: TMessage[]) => {+ let messages = initial;+ const listeners = new Set<() => void>();+ const state: ChatState & { external(next: TMessage[]): void } = {+ status: 'ready',+ error: undefined,+ connection: 'idle',+ get messages() {+ return messages;+ },+ replaceMessages(next) {+ messages = next;+ },+ subscribe(listener) {+ listeners.add(listener);+ return () => listeners.delete(listener);+ },+ /** A write another reader of the same store makes. */+ external(next) {+ messages = next;+ listeners.forEach((listener) => listener());+ },+ };+ return state;+};++const createChat = (state: ChatState, transport: Partial<ChatTransport> = {}) =>+ new Chat({+ id: 'convo-1',+ state,+ transport: {+ sendMessages: jest.fn(),+ reconnectToStream: jest.fn(async () => null),+ abort: jest.fn(),+ ...transport,+ } as ChatTransport,+ prepareRequest: () => ({+ payload,+ messages: (current: TMessage[]) => [...current, userMessage, placeholder],+ responseMessageId: 'response-1',+ }),+ });++describe('Chat.version', () => {+ it('counts a write that keeps the same list', async () => {+ const chat = createChat(createState([earlier]));+ const before = chat.version;++ await chat.setMessages(chat.messages);++ expect(chat.version).toBe(before + 1);+ });++ it('counts a write made to the state outside the chat while it is subscribed', () => {+ const state = createState([earlier]);+ const chat = createChat(state);+ const listener = jest.fn();+ const unsubscribe = chat.subscribe(listener);+ const before = chat.version;++ state.external([{ ...earlier, text: 'Edited' }]);++ expect(chat.version).toBe(before + 1);+ expect(listener).toHaveBeenCalledTimes(1);+ unsubscribe();+ });+});++describe('Chat.setMessages', () => {+ it('replaces the list and notifies subscribers', async () => {+ const chat = createChat(createState([earlier]));+ const listener = jest.fn();+ chat.subscribe(listener);+ const next = [{ ...earlier, text: 'Edited' }];++ await chat.setMessages(next);++ expect(chat.messages).toBe(next);+ expect(listener).toHaveBeenCalledTimes(1);+ });++ it('hands a function the list current when it is written', async () => {+ const chat = createChat(createState([earlier]));+ const first = chat.setMessages((current) => [...current, userMessage]);+ const second = chat.setMessages((current) => [...current, placeholder]);+ await Promise.all([first, second]);++ expect(chat.messages.map((message) => message.messageId)).toEqual([+ 'earlier-1',+ 'user-1',+ 'response-1',+ ]);+ });++ it('writes nothing once the chat is disposed', async () => {+ const state = createState([earlier]);+ const chat = createChat(state);+ chat.dispose();++ await chat.setMessages([]);++ expect(state.messages).toEqual([earlier]);+ });++ it('never runs a function once the chat is disposed, one queued before the disposal included', async () => {+ const state = createState([earlier]);+ const chat = createChat(state);+ const updater = jest.fn((current: TMessage[]) => {+ current[0] = { ...earlier, text: 'Edited' };+ return current;+ });+ /** The first write runs at once; the second waits its turn behind it, past the disposal. */+ const first = chat.setMessages((current) => current);+ const queued = chat.setMessages(updater);+ chat.dispose();+ await Promise.all([first, queued]);+ await chat.setMessages(updater);++ expect(updater).not.toHaveBeenCalled();+ expect(state.messages).toEqual([earlier]);+ });++ it.each([+ [+ 'a row the turn did not touch',+ (current: TMessage[]) =>+ current.map((m) => (m.messageId === 'earlier-1' ? { ...m, text: 'Edited' } : m)),+ ['earlier-1:Edited'],+ ],+ [+ 'a row the turn added',+ (current: TMessage[]) =>+ current.map((m) => (m.messageId === 'response-1' ? { ...m, text: 'Kept' } : m)),+ ['earlier-1:Earlier', 'response-1:Kept'],+ ],+ [+ 'a removal of a row the turn did not touch',+ (current: TMessage[]) => current.filter((m) => m.messageId !== 'earlier-1'),+ [],+ ],+ ])(+ 'keeps its write to %s when the server replaces the start and the turn is undone',+ async (_label, edit, expected) => {+ let answer: ((result: ChatSendResult) => void) | undefined;+ const state = createState([earlier]);+ const chat = createChat(state, {+ sendMessages: jest.fn(+ () =>+ new Promise<ChatSendResult>((resolve) => {+ answer = resolve;+ }),+ ),+ reconnectToStream: jest.fn(async () => emptyStream()),+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.setMessages(edit);++ answer?.({+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ });+ await sent;++ expect(chat.messages.map((message) => `${message.messageId}:${message.text}`)).toEqual(+ expected,+ );+ },+ );+});diff --git a/packages/chat/src/core/chat.ts b/packages/chat/src/core/chat.tsindex b434dad8d4..1df4f71810 100644--- a/packages/chat/src/core/chat.ts+++ b/packages/chat/src/core/chat.ts@@ -557,18 +557,24 @@ export class Chat {private disposed = false;/** Set while the chat writes the state, whose own report of that write the chat announces itself. */private writing = false;+ private revision = 0;/*** The conversation this chat runs under: its id, until the server names the one it created for* a chat started under `new`. Every later turn addresses that one.*/- private conversationId: string;+ private conversation: string;constructor(init: ChatInit) {this.id = init.id;- this.conversationId = init.id;+ this.conversation = init.id;this.init = init;}+ /** The conversation this chat runs under: its id, or the one the server created under `new`. */+ get conversationId(): string {+ return this.conversation;+ }+get status(): ChatStatus {return this.init.state.status;}@@ -585,6 +591,28 @@ export class Chat {return this.init.state.messages;}+ /**+ * Counts the changes reported to subscribers, writes made to the state outside the chat+ * included. A write can keep the same list while a message in it changed, so a snapshot keyed+ * by this sees every write.+ */+ get version(): number {+ return this.revision;+ }++ /**+ * Replaces the message list after the writes already queued. AI SDK: the `messages` setter. A+ * function receives the list current when it is written. The rollback of an optimistic write+ * treats it as it treats any write made after its own.+ */+ setMessages(messages: TMessage[] | ((current: TMessage[]) => TMessage[])): Promise<void> {+ return this.executor.run(() => {+ if (!this.disposed) {+ this.write(typeof messages === 'function' ? messages(this.messages) : messages);+ }+ });+ }+/** Submits a user turn. Rejects while another turn of this chat is in flight. */sendMessage(input: SendMessageInput, options?: ChatRequestOptions): Promise<void> {return this.request({ trigger: 'submit-message', input }, options);@@ -686,7 +714,7 @@ export class Chat {const prepared = await untilAborted(this.init.prepareRequest({...request,- chatId: this.conversationId,+ chatId: this.conversation,messages: this.messages,}),active.controller.signal,@@ -724,7 +752,7 @@ export class Chat {this.init.transport.sendMessages({...options,trigger: request.trigger,- chatId: this.conversationId,+ chatId: this.conversation,messageId: request.messageId,payload: prepared.payload,abortSignal: signal,@@ -955,9 +983,9 @@ export class Chat {if (conversationId &&conversationId !== Constants.NEW_CONVO &&- this.conversationId === Constants.NEW_CONVO+ this.conversation === Constants.NEW_CONVO) {- this.conversationId = conversationId;+ this.conversation = conversationId;}}@@ -1067,6 +1095,7 @@ export class Chat {}private notify(): void {+ this.revision += 1;for (const listener of this.listeners) {try {listener();diff --git a/packages/chat/src/react.ts b/packages/chat/src/react.tsindex 563335abf4..1b25e67969 100644--- a/packages/chat/src/react.ts+++ b/packages/chat/src/react.ts@@ -109,7 +109,11 @@ export {shouldRollbackReveal,buildRevealedMessage,} from './react/steering/useQueuedTurnReveal';+export { useCoreChat } from './react/core';+export { useSnapshot } from './react/snapshot';export { ReactQueryChatState } from './react/state';+export type { Subscribe, SnapshotOptions } from './react/snapshot';+export type { UseCoreChatOptions, CoreChatHelpers } from './react/core';export type { ReactQueryChatStateOptions } from './react/state';export { composerLiftFamily } from './react/lift';export { showSkillsPopoverFamily } from './react/skills';diff --git a/packages/chat/src/react/__tests__/core.spec.tsx b/packages/chat/src/react/__tests__/core.spec.tsxnew file mode 100644index 0000000000..58caee2e72--- /dev/null+++ b/packages/chat/src/react/__tests__/core.spec.tsx@@ -0,0 +1,340 @@+/**+ * @jest-environment jsdom+ */+import { ContentTypes } from 'librechat-data-provider';+import { act, renderHook } from '@testing-library/react';+import type { TMessage, TPayload, ChatEvent, UIMappingOptions } from 'librechat-data-provider';+import type { ChatState, ChatStream, ChatSendResult } from '../../core';+import { useCoreChat } from '../core';+import { Chat } from '../../core';++const createStream = () => {+ const queued: ChatEvent[] = [];+ let wake: (() => void) | undefined;+ let closed = false;+ const stream: ChatStream & { push(event: ChatEvent): void } = {+ push(event) {+ queued.push(event);+ wake?.();+ },+ close() {+ closed = true;+ wake?.();+ },+ async *[Symbol.asyncIterator]() {+ while (true) {+ while (queued.length > 0) {+ yield queued.shift() as ChatEvent;+ }+ if (closed) {+ return;+ }+ await new Promise<void>((resolve) => {+ wake = resolve;+ });+ }+ },+ };+ return stream;+};++const createState = (): ChatState => {+ let messages: TMessage[] = [];+ return {+ status: 'ready',+ error: undefined,+ connection: 'idle',+ get messages() {+ return messages;+ },+ replaceMessages(next) {+ messages = next;+ },+ };+};++const userMessage: TMessage = {+ messageId: 'user-1',+ conversationId: 'convo-1',+ parentMessageId: null,+ isCreatedByUser: true,+ text: 'Hi',+};++const response = (text: string): TMessage => ({+ messageId: 'response-1',+ conversationId: 'convo-1',+ parentMessageId: 'user-1',+ isCreatedByUser: false,+ text,+ content: [{ type: ContentTypes.TEXT, text }],+});++/** Writes the streamed text onto the response, as a host's event reducer does. */+const applyText = (+ event: ChatEvent,+ context: { messages: TMessage[]; write(m: TMessage[]): void },+) => {+ if (event.type === 'text') {+ context.write([userMessage, response(event.data.text ?? '')]);+ }+};++const noRules = (): UIMappingOptions => ({});++const setup = () => {+ const stream = createStream();+ const transport = {+ sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })),+ reconnectToStream: jest.fn(async () => null),+ abort: jest.fn(async () => ({ success: true })),+ };+ const chat = new Chat({+ id: 'convo-1',+ state: createState(),+ transport,+ applyEvent: applyText,+ prepareRequest: () => ({+ payload: { endpoint: 'agents' } as TPayload,+ messages: [userMessage, response('')],+ }),+ });+ return { chat, stream, transport };+};++const flush = () => act(() => new Promise<void>((resolve) => setTimeout(resolve, 0)));++describe('useCoreChat', () => {+ it('renders the turn as UI messages with the status it is in', async () => {+ const { chat, stream } = setup();+ const { result } = renderHook(() => useCoreChat({ chat, getMappingOptions: noRules }));+ expect(result.current.status).toBe('ready');+ expect(result.current.messages).toEqual([]);++ let sent: Promise<void> = Promise.resolve();+ act(() => {+ sent = result.current.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ });+ await flush();+ expect(result.current.status).toBe('submitted');+ expect(result.current.connection).toBe('live');+ expect(result.current.messages.map((message) => message.id)).toEqual(['user-1', 'response-1']);++ stream.push({ type: 'text', data: { message: true, text: 'Hel' } });+ await flush();+ expect(result.current.status).toBe('streaming');+ expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hel' }]);++ stream.push({ type: 'final', data: { final: true } });+ await act(() => sent);+ expect(result.current.status).toBe('ready');+ expect(result.current.connection).toBe('idle');+ expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hel' }]);+ });++ it('throttles message updates but renders a status change at once', async () => {+ jest.useFakeTimers();+ try {+ const { chat, stream } = setup();+ let renders = 0;+ const { result } = renderHook(() => {+ renders += 1;+ return useCoreChat({ chat, getMappingOptions: noRules, throttle: 1000 });+ });+ let sent: Promise<void> = Promise.resolve();+ await act(async () => {+ sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await jest.advanceTimersByTimeAsync(1000);+ });+ stream.push({ type: 'text', data: { message: true, text: 'H' } });+ await act(() => jest.advanceTimersByTimeAsync(0));+ const before = renders;++ stream.push({ type: 'text', data: { message: true, text: 'He' } });+ stream.push({ type: 'text', data: { message: true, text: 'Hel' } });+ await act(() => jest.advanceTimersByTimeAsync(0));+ expect(renders).toBe(before);+ expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'H' }]);++ await act(() => jest.advanceTimersByTimeAsync(1000));+ expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hel' }]);++ stream.push({ type: 'error', data: 'Rate limited' } as ChatEvent);+ await act(async () => {+ await jest.advanceTimersByTimeAsync(0);+ await sent;+ });+ expect(result.current.status).toBe('error');+ expect(result.current.error?.message).toBe('Rate limited');+ } finally {+ jest.useRealTimers();+ }+ });++ it('renders a write that keeps the same list', async () => {+ const { chat } = setup();+ const list = [userMessage, response('Hello')];+ await chat.setMessages(list);+ const { result } = renderHook(() => useCoreChat({ chat, getMappingOptions: noRules }));+ expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Hello' }]);++ list[1] = response('Edited');+ await act(() => chat.setMessages(list));++ expect(result.current.messages[1].parts).toEqual([{ type: 'text', text: 'Edited' }]);+ });++ it('clears an error back to ready', async () => {+ const { chat, stream } = setup();+ const { result } = renderHook(() => useCoreChat({ chat, getMappingOptions: noRules }));++ let sent: Promise<void> = Promise.resolve();+ act(() => {+ sent = result.current.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ });+ stream.push({ type: 'error', data: 'Rate limited' } as ChatEvent);+ await act(() => sent);+ expect(result.current.status).toBe('error');++ act(() => result.current.clearError());+ expect(result.current.status).toBe('ready');+ expect(result.current.error).toBeUndefined();+ });++ it('writes views back onto the stored messages under the active branch', async () => {+ const { chat } = setup();+ const sibling: TMessage = { ...response('Other'), messageId: 'response-2' };+ await chat.setMessages([userMessage, response('Hello'), sibling]);+ const { result } = renderHook(() =>+ useCoreChat({ chat, getMappingOptions: noRules, latestMessageId: 'response-1' }),+ );++ await act(() =>+ result.current.setMessages((views) => [+ ...views,+ { id: 'note-1', role: 'assistant', parts: [{ type: 'text', text: 'Note' }] },+ ]),+ );++ expect(chat.messages[0]).toEqual(userMessage);+ expect(chat.messages[3]).toMatchObject({+ messageId: 'note-1',+ conversationId: 'convo-1',+ parentMessageId: 'response-1',+ });+ expect(result.current.messages).toHaveLength(4);+ });++ it('leaves the rows its edit did not touch to the rollback of a replaced start', async () => {+ const earlier: TMessage = { ...userMessage, messageId: 'earlier-1', text: 'Earlier' };+ const state = createState();+ state.replaceMessages([earlier]);+ let answer: ((result: ChatSendResult) => void) | undefined;+ const chat = new Chat({+ id: 'convo-1',+ state,+ transport: {+ sendMessages: jest.fn(+ () =>+ new Promise<ChatSendResult>((resolve) => {+ answer = resolve;+ }),+ ),+ reconnectToStream: jest.fn(async () => {+ const stream = createStream();+ stream.push({+ type: 'final',+ data: { final: true, requestMessage: null, responseMessage: null },+ } as ChatEvent);+ stream.close();+ return stream;+ }),+ abort: jest.fn(async () => ({ success: true })),+ },+ prepareRequest: () => ({+ payload: { endpoint: 'agents' } as TPayload,+ messages: (current: TMessage[]) => [...current, userMessage, response('')],+ responseMessageId: 'response-1',+ }),+ });+ const { result } = renderHook(() => useCoreChat({ chat, getMappingOptions: noRules }));++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await act(() =>+ result.current.setMessages((views) =>+ views.map((view) =>+ view.id === 'earlier-1' ? { ...view, parts: [{ type: 'text', text: 'Edited' }] } : view,+ ),+ ),+ );+ answer?.({+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ });+ await act(() => sent);++ expect(chat.messages.map((message) => message.messageId)).toEqual(['earlier-1']);+ expect(chat.messages[0]).not.toBe(earlier);+ });++ it('files a message it adds under the conversation the server created for a new chat', async () => {+ const chat = new Chat({+ id: 'new',+ state: createState(),+ transport: {+ sendMessages: jest.fn(async () => ({+ status: 'settled' as const,+ conversationId: 'convo-9',+ generationProtocolVersion: 2,+ })),+ reconnectToStream: jest.fn(async () => null),+ abort: jest.fn(async () => ({ success: true })),+ },+ prepareRequest: () => ({+ payload: { endpoint: 'agents' } as TPayload,+ messages: [{ ...userMessage, conversationId: 'convo-9' }],+ }),+ });+ const { result } = renderHook(() => useCoreChat({ chat, getMappingOptions: noRules }));++ await act(() => chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }));+ await act(() =>+ result.current.setMessages((views) => [+ ...views,+ { id: 'note-1', role: 'assistant', parts: [{ type: 'text', text: 'Note' }] },+ ]),+ );++ expect(chat.conversationId).toBe('convo-9');+ expect(chat.messages[1]).toMatchObject({ messageId: 'note-1', conversationId: 'convo-9' });+ });++ it('applies the host tool rules to tool parts', async () => {+ const { chat } = setup();+ await chat.setMessages([+ userMessage,+ {+ ...response(''),+ content: [+ {+ type: ContentTypes.TOOL_CALL,+ tool_call: { id: 'call-1', name: 'lookup', args: '{}', output: 'nope', progress: 1 },+ },+ ],+ } as TMessage,+ ]);+ const resolveToolFailure = jest.fn(() => 'Lookup failed');+ const getMappingOptions = (): UIMappingOptions => ({ resolveToolFailure });++ const { result } = renderHook(() => useCoreChat({ chat, getMappingOptions }));++ expect(result.current.messages[1].parts[0]).toMatchObject({+ state: 'output-error',+ errorText: 'Lookup failed',+ });+ });+});diff --git a/packages/chat/src/react/chat/messages.ts b/packages/chat/src/react/chat/messages.tsindex 8e698fea19..bacb950e3c 100644--- a/packages/chat/src/react/chat/messages.ts+++ b/packages/chat/src/react/chat/messages.ts@@ -16,13 +16,16 @@ const getActiveBranch = (byId: Map<string, TMessage>, tailId: string | undefined* The stored messages `next` writes back over `current`, keeping the stored fields the UI view* omits. A message with no stored counterpart joins the chat 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.+ * metadata names a parent. A message keeps the conversation it is stored under. A view that is+ * the one `viewOf` gives its stored message keeps that message as is, so rows a write left+ * untouched stay the same objects.*/export const toStoredMessages = (next: UIMessage[],current: TMessage[],latestMessageId: string | undefined,chatId: string | undefined,+ viewOf?: (message: TMessage) => UIMessage,): TMessage[] => {const byId = new Map(current.map((message) => [message.messageId, message]));const branch = getActiveBranch(byId, latestMessageId);@@ -30,6 +33,10 @@ export const toStoredMessages = (let previous: { id: string; joined: boolean } | null = null;return next.map((view) => {const base = byId.get(view.id);+ if (base && viewOf?.(base) === view) {+ previous = { id: base.messageId, joined: branch.has(base.messageId) };+ return base;+ }const message = fromUIMessage(view, base);message.conversationId = base ? base.conversationId : conversationId;if (!base && view.metadata?.parentMessageId === undefined) {diff --git a/packages/chat/src/react/core.ts b/packages/chat/src/react/core.tsnew file mode 100644index 0000000000..d2eaf40fea--- /dev/null+++ b/packages/chat/src/react/core.ts@@ -0,0 +1,112 @@+import { useRef, useMemo, useCallback } from 'react';+import type { TMessage, UIMessage, TAttachment } from 'librechat-data-provider';+import type {+ Chat,+ ChatStatus,+ ChatConnection,+ SendMessageInput,+ ChatRequestOptions,+} from '../core';+import type { ChatViewContract } from './chat/contract';+import { toStoredMessages } from './chat/messages';+import { useSnapshot } from './snapshot';+import { toView } from './chat/views';++export type UseCoreChatOptions = {+ chat: Chat;+ /** The app's tool outcome rules for viewing a message; see `ChatViewContract`. */+ getMappingOptions: ChatViewContract['getMappingOptions'];+ /** Renders message updates at most once per interval, in ms. Status and error render at once. */+ throttle?: number;+ /** Attachments delivered per message id that the message list does not hold yet. */+ liveAttachments?: Record<string, TAttachment[] | undefined>;+ /** The active branch's tail, under which `setMessages` joins new messages. Defaults to the list's tail. */+ latestMessageId?: string;+};++/** AI SDK `UseChatHelpers`, over a core {@link Chat}. */+export type CoreChatHelpers = {+ id: string;+ messages: UIMessage[];+ status: ChatStatus;+ error: Error | undefined;+ connection: ChatConnection;+ sendMessage: (input: SendMessageInput, options?: ChatRequestOptions) => Promise<void>;+ regenerate: (options?: { messageId?: string } & ChatRequestOptions) => Promise<void>;+ continue: (options: { messageId: string } & ChatRequestOptions) => Promise<void>;+ clearError: () => void;+ /** Writes views back onto the stored messages; see `toStoredMessages`. */+ setMessages: (messages: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => Promise<void>;+};++type MessagesSnapshot = { version: number; stored: TMessage[] };++const noLiveAttachments: Record<string, TAttachment[] | undefined> = {};++/**+ * AI SDK `useChat` for a core {@link Chat}, which a host constructs and may share between+ * components (AI SDK: the `chat` option). Messages are viewed through the same per-message cache+ * as `useChat`, and only message updates are throttled, so `ready` never renders beside stale+ * messages.+ */+export function useCoreChat({+ chat,+ getMappingOptions,+ throttle,+ liveAttachments = noLiveAttachments,+ latestMessageId,+}: UseCoreChatOptions): CoreChatHelpers {+ const subscribe = useCallback((listener: () => void) => chat.subscribe(listener), [chat]);+ const snapshot = useRef<MessagesSnapshot>();+ /** Keyed by the chat's change count as well as the list: a write can keep the same array. */+ const readMessages = useCallback(() => {+ const version = chat.version;+ const stored = chat.messages;+ const current = snapshot.current;+ if (current?.version === version && current.stored === stored) {+ return current;+ }+ snapshot.current = { version, stored };+ return snapshot.current;+ }, [chat]);+ const cache = useSnapshot(subscribe, readMessages, { throttle });+ const status = useSnapshot(subscribe, () => chat.status);+ const error = useSnapshot(subscribe, () => chat.error);+ const connection = useSnapshot(subscribe, () => chat.connection);++ const messages = useMemo(+ () =>+ cache.stored.map((message) =>+ toView(message, liveAttachments[message.messageId], getMappingOptions),+ ),+ [cache, liveAttachments, getMappingOptions],+ );++ const setMessages = useCallback<CoreChatHelpers['setMessages']>(+ (update) =>+ chat.setMessages((current) => {+ const viewOf = (message: TMessage) =>+ toView(message, liveAttachments[message.messageId], getMappingOptions);+ const next = typeof update === 'function' ? update(current.map(viewOf)) : update;+ const tail = latestMessageId ?? current[current.length - 1]?.messageId;+ return toStoredMessages(next, current, tail, chat.conversationId, viewOf);+ }),+ [chat, liveAttachments, getMappingOptions, latestMessageId],+ );++ return useMemo(+ () => ({+ id: chat.id,+ messages,+ status,+ error,+ connection,+ sendMessage: (input, options) => chat.sendMessage(input, options),+ regenerate: (options) => chat.regenerate(options),+ continue: (options) => chat.continue(options),+ clearError: () => chat.clearError(),+ setMessages,+ }),+ [chat, messages, status, error, connection, setMessages],+ );+}diff --git a/packages/chat/src/react/snapshot.ts b/packages/chat/src/react/snapshot.tsnew file mode 100644index 0000000000..2e00bb0b0c--- /dev/null+++ b/packages/chat/src/react/snapshot.ts@@ -0,0 +1,67 @@+import { useRef, useEffect, useReducer } from 'react';++export type Subscribe = (listener: () => void) => () => void;++export type SnapshotOptions<T> = {+ /** Renders at most once per interval, in ms, keeping the last change. */+ throttle?: number;+ isEqual?: (previous: T, next: T) => boolean;+};++/** Calls `run` at once, then at most once per `wait` ms, always ending on the last call. */+const throttled = (run: () => void, wait: number) => {+ let timer: ReturnType<typeof setTimeout> | undefined;+ let pending = false;+ const call = () => {+ if (timer) {+ pending = true;+ return;+ }+ run();+ timer = setTimeout(function flush() {+ timer = undefined;+ if (pending) {+ pending = false;+ call();+ }+ }, wait);+ };+ return { call, cancel: () => clearTimeout(timer) };+};++const increment = (count: number) => count + 1;++/**+ * Reads `read()` on every render and re-renders when a reported change makes it differ from what+ * was last rendered. AI SDK: the `useState` snapshot plus effect subscription of `useChat`, which+ * keeps updates out of the synchronous lane `useSyncExternalStore` would put them in. A change+ * that lands between render and subscribe is still caught: the effect checks once on subscribe.+ */+export function useSnapshot<T>(+ subscribe: Subscribe,+ read: () => T,+ { throttle, isEqual = Object.is }: SnapshotOptions<T> = {},+): T {+ const [, render] = useReducer(increment, 0);+ const value = read();+ const latest = useRef({ value, read, isEqual });+ latest.current = { value, read, isEqual };++ useEffect(() => {+ const check = () => {+ const current = latest.current;+ if (!current.isEqual(current.value, current.read())) {+ render();+ }+ };+ const scheduled = throttle ? throttled(check, throttle) : { call: check, cancel: () => {} };+ const unsubscribe = subscribe(scheduled.call);+ check();+ return () => {+ unsubscribe();+ scheduled.cancel();+ };+ }, [subscribe, throttle]);++ return value;+}