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: 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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;
+}