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
📜 refactor: Declare the Chat Context Contract (#16288)
Marco Beretta07bbbc0d4d7a
diff --git a/client/src/Providers/AddedChatContext.tsx b/client/src/Providers/AddedChatContext.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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 });+ });+});