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

📜 refactor: Declare the Chat Context Contract (#16288)

Marco Beretta07bbbc0d4d7a
diff --git a/client/src/Providers/AddedChatContext.tsx b/client/src/Providers/AddedChatContext.tsx
index a19aee8746..bc2e6c97a4 100644
--- a/client/src/Providers/AddedChatContext.tsx
+++ b/client/src/Providers/AddedChatContext.tsx
@@ -1,13 +1,5 @@
import { createContext, useContext } from 'react';
-import type { TConversation } from 'librechat-data-provider';
-import type { SetterOrUpdater } from 'recoil';
-import type { ConvoGenerator } from '~/common';
+import type { AddedChatContract } from '~/hooks/Chat/contract';
-type TAddedChatContext = {
- conversation: TConversation | null;
- setConversation: SetterOrUpdater<TConversation | null>;
- generateConversation: ConvoGenerator;
-};
-
-export const AddedChatContext = createContext<TAddedChatContext>({} as TAddedChatContext);
+export const AddedChatContext = createContext<AddedChatContract>({} as AddedChatContract);
export const useAddedChatContext = () => useContext(AddedChatContext);
diff --git a/client/src/Providers/ChatContext.tsx b/client/src/Providers/ChatContext.tsx
index 8af75f90c0..ffe12407c8 100644
--- a/client/src/Providers/ChatContext.tsx
+++ b/client/src/Providers/ChatContext.tsx
@@ -1,8 +1,7 @@
import { createContext, useContext } from 'react';
-import useChatHelpers from '~/hooks/Chat/useChatHelpers';
-type TChatContext = ReturnType<typeof useChatHelpers>;
+import type { ChatContract } from '~/hooks/Chat/contract';
-export const ChatContext = createContext<TChatContext | null>(null);
+export const ChatContext = createContext<ChatContract | null>(null);
export const useChatContext = () => {
const ctx = useContext(ChatContext);
if (!ctx) {
diff --git a/client/src/hooks/Chat/contract.check.ts b/client/src/hooks/Chat/contract.check.ts
new file mode 100644
index 0000000000..99e20ed9dd
--- /dev/null
+++ b/client/src/hooks/Chat/contract.check.ts
@@ -0,0 +1,37 @@
+/**
+ * Compile-time proof that the chat contract matches what backs it. Nothing here runs; a
+ * drift in either direction fails `npm run typecheck`.
+ *
+ * The hooks annotate their memoized value with the contract, so a member added to or dropped
+ * from an implementation without the contract (or the reverse) is already an excess or missing
+ * property error there. These assertions cover the rest: the members forwarded from other hooks,
+ * whose own signatures could otherwise widen or narrow away from the contract, and the context
+ * types consumers read.
+ */
+import type { ContextType } from 'react';
+import type { AddedChatContext } from '~/Providers/AddedChatContext';
+import type { ChatContract, AddedChatContract } from './contract';
+import type { ChatContext } from '~/Providers/ChatContext';
+import type useAddedResponse from './useAddedResponse';
+import type useChatFunctions from './useChatFunctions';
+import type useChatHelpers from './useChatHelpers';
+import type useNewConvo from '../useNewConvo';
+
+type Equal<A, B> =
+ (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Expect<T extends true> = T;
+
+type ChatFunctions = ReturnType<typeof useChatFunctions>;
+
+export type ChatContractChecks = [
+ Expect<Equal<ReturnType<typeof useChatHelpers>, ChatContract>>,
+ Expect<Equal<ContextType<typeof ChatContext>, ChatContract | null>>,
+ Expect<Equal<ChatFunctions['ask'], ChatContract['ask']>>,
+ Expect<Equal<ChatFunctions['regenerate'], ChatContract['regenerate']>>,
+ Expect<Equal<ReturnType<typeof useNewConvo>['newConversation'], ChatContract['newConversation']>>,
+];
+
+export type AddedChatContractChecks = [
+ Expect<Equal<ReturnType<typeof useAddedResponse>, AddedChatContract>>,
+ Expect<Equal<ContextType<typeof AddedChatContext>, AddedChatContract>>,
+];
diff --git a/client/src/hooks/Chat/contract.ts b/client/src/hooks/Chat/contract.ts
new file mode 100644
index 0000000000..bbf7a3277f
--- /dev/null
+++ b/client/src/hooks/Chat/contract.ts
@@ -0,0 +1,134 @@
+import type { TConversation, TMessage, TPreset } from 'librechat-data-provider';
+import type { SetStateAction, Dispatch, MouseEvent } from 'react';
+import type { NewConversationParams, TOptionSettings, ExtendedFile, TAskFunction } from '~/common';
+
+/** Options accepted by {@link ChatConversationContract.newConversation}: the shared params plus
+ * the two flags only the root pane's generator honors. */
+export type NewConversationOptions = NewConversationParams & {
+ /** Skips focusing the composer after the new conversation renders. */
+ disableFocus?: boolean;
+ /** Set when the call re-renders a composer an earlier call already opened, such as agent
+ * metadata arriving late. The user never left that composer, so its draft identity and its
+ * in-flight attachments outlive the refresh. */
+ keepComposerState?: boolean;
+};
+
+/** Target of a regenerate: a response to redo, or the user message whose response to redo. */
+export type RegenerateTarget = Partial<
+ Pick<TMessage, 'messageId' | 'parentMessageId' | 'isCreatedByUser'>
+>;
+
+/** Conversation identity and the per-pane settings attached to it. */
+export type ChatConversationContract = {
+ /** The pane this chat renders into; `0` is the root pane, `1` the added (multi-convo) pane. */
+ index: number;
+ /** The active conversation for this pane, or `null` before one is created. */
+ conversation: TConversation | null;
+ /** Replaces or updates the active conversation for this pane. */
+ setConversation: Dispatch<SetStateAction<TConversation | null>>;
+ /** Starts a fresh conversation in this pane from a template and/or preset. */
+ newConversation: (options?: NewConversationOptions) => void;
+ /** The preset applied to this pane, if any. */
+ preset: TPreset | null;
+ /** Replaces the preset applied to this pane. */
+ setPreset: Dispatch<SetStateAction<TPreset | null>>;
+ /** Legacy per-pane option toggles (examples, code chat). */
+ optionSettings: TOptionSettings;
+ /** Replaces the legacy per-pane option toggles. */
+ setOptionSettings: Dispatch<SetStateAction<TOptionSettings>>;
+};
+
+/** The message tree as cached for this conversation. AI SDK: `messages` / `setMessages`. */
+export type ChatMessagesContract = {
+ /**
+ * Reads the cached message list for this pane's conversation, or for `targetConversationId`.
+ * AI SDK: `messages`, read on demand instead of subscribed.
+ */
+ getMessages: (targetConversationId?: string | null) => TMessage[] | undefined;
+ /** Writes the full message list to every cache key this pane reads. AI SDK: `setMessages`. */
+ setMessages: (messages: TMessage[]) => void;
+ /** Selects the visible sibling under the latest message's parent. */
+ setSiblingIdx: (update: SetStateAction<number>) => void;
+ /** Id of the tail of the active branch, if loaded. */
+ latestMessageId: string | undefined;
+ /** Depth of the tail of the active branch, if loaded. */
+ latestMessageDepth: number | undefined;
+};
+
+/** Sending, regenerating and continuing turns. AI SDK: `sendMessage` / `regenerate` / `status`. */
+export type ChatSubmissionContract = {
+ /** Submits a user turn (or an edit, continue or compaction of one). AI SDK: `sendMessage`. */
+ ask: TAskFunction;
+ /** Re-runs the response to a message on the current branch. AI SDK: `regenerate`. */
+ regenerate: (target: RegenerateTarget, options?: { addedConvo?: TConversation | null }) => void;
+ /**
+ * Whether a turn is in flight for this pane. AI SDK: `status`, collapsed to
+ * `submitted | streaming` (true) versus `ready | error` (false).
+ */
+ isSubmitting: boolean;
+ /** Sets the in-flight flag for this pane. */
+ setIsSubmitting: Dispatch<SetStateAction<boolean>>;
+ /** Button handler that regenerates the latest response. AI SDK: `regenerate`. */
+ handleRegenerate: (e: MouseEvent<HTMLButtonElement>) => void;
+ /** Button handler that continues the latest response from where it stopped. */
+ handleContinue: (e: MouseEvent<HTMLButtonElement>) => void;
+};
+
+/** Stopping an in-flight turn. AI SDK: `stop`. */
+export type ChatAbortContract = {
+ /** Aborts the in-flight generation for this pane's conversation. AI SDK: `stop`. */
+ stopGenerating: () => Promise<void>;
+ /** Button handler around `stopGenerating`. AI SDK: `stop`. */
+ handleStopGenerating: (e: MouseEvent<HTMLButtonElement>) => void;
+ /** Whether a stop just happened and the view should hold its scroll position. */
+ abortScroll: boolean;
+ /** Sets the post-stop scroll hold. */
+ setAbortScroll: Dispatch<SetStateAction<boolean>>;
+};
+
+/** Composer attachments for this pane. AI SDK: the `files` option of `sendMessage`. */
+export type ChatFilesContract = {
+ /** Attachments staged in the composer, keyed by file id. */
+ files: Map<string, ExtendedFile>;
+ /** Replaces the staged attachments. */
+ setFiles: Dispatch<SetStateAction<Map<string, ExtendedFile>>>;
+ /** Whether an attachment is still uploading. */
+ filesLoading: boolean;
+ /** Sets the attachment upload flag. */
+ setFilesLoading: Dispatch<SetStateAction<boolean>>;
+};
+
+/** Chat-scoped view state that has no AI SDK counterpart. */
+export type ChatViewContract = {
+ /** Whether the pane's settings popover is open. */
+ showPopover: boolean;
+ /** Opens or closes the pane's settings popover. */
+ setShowPopover: Dispatch<SetStateAction<boolean>>;
+ /** Whether message feedback controls are enabled by the startup config. */
+ feedbackEnabled: boolean;
+};
+
+/**
+ * Public surface of `useChatHelpers`, served through `ChatContext`.
+ *
+ * Queue and steering are not part of it: they live in `useQueueDrain`, `useSteering` and
+ * the SSE handlers, and reach the composer directly rather than through this context.
+ * AI SDK `error` has no member here either; errors arrive as message content.
+ * Setters are typed as React dispatchers, so the contract names no state library.
+ */
+export type ChatContract = ChatConversationContract &
+ ChatMessagesContract &
+ ChatSubmissionContract &
+ ChatAbortContract &
+ ChatFilesContract &
+ ChatViewContract;
+
+/** Public surface of `useAddedResponse`, served through `AddedChatContext`. */
+export type AddedChatContract = {
+ /** The added pane's conversation, or `null` when multi-convo is off. */
+ conversation: TConversation | null;
+ /** Replaces or updates the added pane's conversation. */
+ setConversation: Dispatch<SetStateAction<TConversation | null>>;
+ /** Builds and stores a conversation for the added pane from a template and/or preset. */
+ generateConversation: (params?: NewConversationParams) => TConversation;
+};
diff --git a/client/src/hooks/Chat/useAddedResponse.ts b/client/src/hooks/Chat/useAddedResponse.ts
index f668ce775c..8f7c696b50 100644
--- a/client/src/hooks/Chat/useAddedResponse.ts
+++ b/client/src/hooks/Chat/useAddedResponse.ts
@@ -9,6 +9,7 @@ import {
} from 'librechat-data-provider';
import type { TEndpointsConfig, EModelEndpoint, TConversation } from 'librechat-data-provider';
import type { AssistantListItem, NewConversationParams } from '~/common';
+import type { AddedChatContract } from './contract';
import useAssistantListMap from '~/hooks/Assistants/useAssistantListMap';
import { buildDefaultConvo, getDefaultEndpoint } from '~/utils';
import { useGetEndpointsQuery } from '~/data-provider';
@@ -22,7 +23,7 @@ const ADDED_INDEX = 1;
* Provides just the conversation state and a function to generate a new conversation,
* mirroring the pattern from useNewConvo.
*/
-export default function useAddedResponse() {
+export default function useAddedResponse(): AddedChatContract {
const modelsQuery = useGetModelsQuery();
const assistantsListMap = useAssistantListMap();
const rootConvo = useRecoilValue(store.conversationByKeySelector(0));
@@ -123,7 +124,7 @@ export default function useAddedResponse() {
);
return useMemo(
- () => ({
+ (): AddedChatContract => ({
conversation,
setConversation,
generateConversation,
diff --git a/client/src/hooks/Chat/useChatHelpers.ts b/client/src/hooks/Chat/useChatHelpers.ts
index 450a79b189..159ca4c113 100644
--- a/client/src/hooks/Chat/useChatHelpers.ts
+++ b/client/src/hooks/Chat/useChatHelpers.ts
@@ -4,6 +4,7 @@ import { useQueryClient } from '@tanstack/react-query';
import { Constants, QueryKeys, isAssistantsEndpoint } from 'librechat-data-provider';
import { useRecoilState, useRecoilValue, useSetRecoilState, useRecoilCallback } from 'recoil';
import type { TMessage } from 'librechat-data-provider';
+import type { ChatContract } from './contract';
import {
useGetStartupConfig,
useAbortStreamMutation,
@@ -20,7 +21,7 @@ import { useAbortCleanup } from './abort';
import store from '~/store';
// this to be set somewhere else
-export default function useChatHelpers(index = 0, paramId?: string) {
+export default function useChatHelpers(index = 0, paramId?: string): ChatContract {
const clearAllSubmissions = store.useClearSubmissionState();
const [files, setFiles] = useRecoilState(store.filesByIndex(index));
const [filesLoading, setFilesLoading] = useState(false);
@@ -57,7 +58,7 @@ export default function useChatHelpers(index = 0, paramId?: string) {
* interrupt flag is armed and no run-end has landed yet, write it here from
* the abort response so the queued follow-up still auto-sends. If the SSE
* final DOES arrive later, its signal finds the flag already consumed and
- * an `aborted` outcome drains nothing — no double fire.
+ * an `aborted` outcome drains nothing, so there is no double fire.
*/
const signalInterruptDrain = useRecoilCallback(
({ snapshot, set }) =>
@@ -227,7 +228,7 @@ export default function useChatHelpers(index = 0, paramId?: string) {
return;
}
// The aborted run's final SSE can land (and the interrupt drain can
- // start the NEXT submission) while the abort response is in flight —
+ // start the NEXT submission) while the abort response is in flight;
// the fallback clear below must not tear down that new run.
const submissionAtAbort = captureSubmission();
try {
@@ -273,7 +274,7 @@ export default function useChatHelpers(index = 0, paramId?: string) {
});
return;
}
- // The response's `aborted` field is the RESOLVED job id — authoritative
+ // The response's `aborted` field is the RESOLVED job id, authoritative
// when this turn still holds the `new` placeholder. Chips and the drain
// signal land where the mounted composer's queue machinery looks, while
// the parked-copy claim uses the resolved id the server keyed it under.
@@ -282,7 +283,7 @@ export default function useChatHelpers(index = 0, paramId?: string) {
resolvedId: response?.aborted,
});
// Steers the run never injected ride the abort response. Consume them
- // here as well as on the SSE final event — clearing submissions below
+ // here as well as on the SSE final event: clearing submissions below
// can close the stream before that event lands, and conversion
// dedupes by steer id so double delivery is a no-op. `claimParked`
// reconciles the replayable parked copy if the final raced this response.
@@ -396,7 +397,7 @@ export default function useChatHelpers(index = 0, paramId?: string) {
const feedbackEnabled = startupConfig != null && startupConfig.interface?.feedback !== false;
return useMemo(
- () => ({
+ (): ChatContract => ({
newConversation,
conversation,
setConversation,
diff --git a/client/src/hooks/useNewConvo.ts b/client/src/hooks/useNewConvo.ts
index 05ad4a9b12..65b82ee52e 100644
--- a/client/src/hooks/useNewConvo.ts
+++ b/client/src/hooks/useNewConvo.ts
@@ -23,6 +23,7 @@ import type {
TConversation,
TEndpointsConfig,
} from 'librechat-data-provider';
+import type { NewConversationOptions } from './Chat/contract';
import type { AssistantListItem } from '~/common';
import {
updateLastSelectedModel,
@@ -328,19 +329,7 @@ const useNewConvo = (index = 0) => {
keepAddedConvos = false,
keepComposerState = false,
disableParams,
- }: {
- template?: Partial<TConversation>;
- preset?: Partial<TPreset>;
- modelsData?: TModelsConfig;
- buildDefault?: boolean;
- disableFocus?: boolean;
- keepAddedConvos?: boolean;
- /** Set when the call re-renders a composer an earlier call already opened, such as agent
- * metadata arriving late. The user never left that composer, so its draft identity and its
- * in-flight attachments outlive the refresh. */
- keepComposerState?: boolean;
- disableParams?: boolean;
- } = {}) {
+ }: NewConversationOptions = {}) {
const nextConversationId = _template.conversationId ?? '';
const keepsExistingDraft =
keepComposerState ||
diff --git a/e2e/specs/mock/scenarios/chat-context.spec.ts b/e2e/specs/mock/scenarios/chat-context.spec.ts
new file mode 100644
index 0000000000..863820b799
--- /dev/null
+++ b/e2e/specs/mock/scenarios/chat-context.spec.ts
@@ -0,0 +1,143 @@
+import { expect, test } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import {
+ sendMessageAndWaitForCompletion,
+ selectMockEndpoint,
+ isAgentsStream,
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ messagesView,
+ replyPrompt,
+ sendMessage,
+ replyText,
+} from '../helpers';
+
+/**
+ * Every control here reads its handlers and state from `ChatContext` (or
+ * `AddedChatContext` for the second pane), so these are the behaviors the
+ * declared chat contract has to keep serving.
+ */
+
+const uniqueLabel = (prefix: string) =>
+ `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+const stopButton = (page: Page) => page.getByRole('button', { name: 'Stop generating' });
+const messageRows = (page: Page) => messagesView(page).locator('.message-render');
+
+async function openMockChat(page: Page) {
+ await page.goto(NEW_CHAT_PATH, { timeout: 10_000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+}
+
+test.describe('chat context', () => {
+ test('streams the reply to a sent message and keeps it after reload @scenario:sent-message-streams-a-reply-that-survives-reload', async ({
+ page,
+ }) => {
+ test.setTimeout(60_000);
+ const label = uniqueLabel('send');
+ await openMockChat(page);
+
+ const response = await sendMessageAndWaitForCompletion(page, replyPrompt(label));
+ expect(response.ok()).toBeTruthy();
+ await expect(messageRows(page).last().locator('.message-content')).toHaveText(
+ replyText(label),
+ { timeout: 30_000 },
+ );
+ await expect(stopButton(page)).toBeHidden({ timeout: 30_000 });
+
+ await page.reload({ timeout: 10_000 });
+ await expect(messageRows(page)).toHaveCount(2, { timeout: 30_000 });
+ await expect(messageRows(page).last().locator('.message-content')).toHaveText(
+ replyText(label),
+ { timeout: 30_000 },
+ );
+ });
+
+ test('regenerating the latest response adds a sibling the user can page between @scenario:regenerate-adds-a-sibling-response', async ({
+ page,
+ }) => {
+ test.setTimeout(90_000);
+ const label = uniqueLabel('regen');
+ await openMockChat(page);
+
+ const response = await sendMessageAndWaitForCompletion(page, replyPrompt(label));
+ expect(response.ok()).toBeTruthy();
+ const assistant = messageRows(page).last();
+ await expect(assistant.locator('.message-content')).toHaveText(replyText(label), {
+ timeout: 30_000,
+ });
+
+ await assistant.hover();
+ const [regenerated] = await Promise.all([
+ page.waitForResponse(isAgentsStream, { timeout: 30_000 }),
+ assistant.getByRole('button', { name: 'Regenerate', exact: true }).last().click(),
+ ]);
+ expect(regenerated.ok()).toBeTruthy();
+
+ await expect(page.getByText('2 / 2')).toBeVisible({ timeout: 30_000 });
+ await expect(stopButton(page)).toBeHidden({ timeout: 30_000 });
+ await expect(messageRows(page).last().locator('.message-content')).toHaveText(
+ replyText(label),
+ { timeout: 30_000 },
+ );
+ await page.getByRole('button', { name: 'Previous sibling message' }).click();
+ await expect(page.getByText('1 / 2')).toBeVisible();
+ await expect(messageRows(page).last().locator('.message-content')).toHaveText(replyText(label));
+ });
+
+ test('stopping a streaming reply keeps the partial response after reload @scenario:stop-keeps-the-partial-response', async ({
+ page,
+ }) => {
+ test.setTimeout(90_000);
+ const label = uniqueLabel('stop');
+ await openMockChat(page);
+
+ const run = await sendMessage(page, `E2E_SLOW_REPLY:${label}`);
+ expect(run.ok()).toBeTruthy();
+ await expect(messagesView(page).getByText('chunk-010')).toBeVisible({ timeout: 15_000 });
+
+ const [abort] = await Promise.all([
+ page.waitForResponse(
+ (response) =>
+ response.request().method() === 'POST' &&
+ response.url().includes('/api/agents/chat/abort'),
+ { timeout: 30_000 },
+ ),
+ stopButton(page).click(),
+ ]);
+ expect(abort.ok()).toBeTruthy();
+ await expect(stopButton(page)).toBeHidden({ timeout: 30_000 });
+
+ const partial = messageRows(page).last().locator('.message-content');
+ await expect(partial).toContainText(`E2E slow reply ${label}`);
+ await expect(partial).not.toContainText('chunk-159');
+
+ await page.reload({ timeout: 10_000 });
+ await expect(messageRows(page).last().locator('.message-content')).toContainText(
+ `E2E slow reply ${label}`,
+ { timeout: 30_000 },
+ );
+ await expect(messageRows(page).last().locator('.message-content')).not.toContainText(
+ 'chunk-159',
+ );
+ });
+
+ test('a second conversation pane streams its own reply to the same message @scenario:added-conversation-streams-alongside-the-main-reply', async ({
+ page,
+ }) => {
+ const width = page.viewportSize()?.width ?? 0;
+ test.skip(width < 768, 'the multi-conversation control is hidden below md');
+ test.setTimeout(90_000);
+ const label = uniqueLabel('added');
+ await openMockChat(page);
+
+ await page.getByTestId('add-multi-convo-button').click();
+ const run = await sendMessage(page, replyPrompt(label));
+ expect(run.ok()).toBeTruthy();
+
+ await expect(messagesView(page).getByText(replyText(label), { exact: true })).toHaveCount(2, {
+ timeout: 30_000,
+ });
+ await expect(stopButton(page)).toBeHidden({ timeout: 30_000 });
+ });
+});