From 07bbbc0d4d7aa5ffde777e40ea31c58aa4d38033 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Thu, 24 Sep 2026 16:47:09 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9C=20refactor:=20Declare=20the=20Chat?= =?UTF-8?q?=20Context=20Contract=20(#16288)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor: declare the chat context contract Replace the inferred ReturnType context type with an explicit ChatContract grouped by responsibility, and move the added-chat context shape to AddedChatContract. useChatHelpers and useAddedResponse annotate their memoized value with the contract, and contract.check.ts asserts two-way equality against the hooks each member is forwarded from. * test: cover the chat context behaviors with e2e scenarios * refactor: derive newConversation options from NewConversationParams useNewConvo now takes the contract's NewConversationOptions instead of restating the shared params inline, so there is one definition. * test: skip the added pane scenario where the control is hidden * refactor: type contract setters as React dispatchers Keep the chat contract free of Recoil types, and tighten the regenerate and stop scenarios to assert the regenerated sibling's content and that the stopped reply stays partial after reload. (cherry picked from commit 0d4627b387e463c0eae0b949310a6b29b5dcd861) Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16288 --- client/src/Providers/AddedChatContext.tsx | 12 +- client/src/Providers/ChatContext.tsx | 5 +- client/src/hooks/Chat/contract.check.ts | 37 +++++ client/src/hooks/Chat/contract.ts | 134 ++++++++++++++++ client/src/hooks/Chat/useAddedResponse.ts | 5 +- client/src/hooks/Chat/useChatHelpers.ts | 13 +- client/src/hooks/useNewConvo.ts | 15 +- e2e/specs/mock/scenarios/chat-context.spec.ts | 143 ++++++++++++++++++ 8 files changed, 330 insertions(+), 34 deletions(-) create mode 100644 client/src/hooks/Chat/contract.check.ts create mode 100644 client/src/hooks/Chat/contract.ts create mode 100644 e2e/specs/mock/scenarios/chat-context.spec.ts 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; - generateConversation: ConvoGenerator; -}; - -export const AddedChatContext = createContext({} as TAddedChatContext); +export const AddedChatContext = createContext({} 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; +import type { ChatContract } from '~/hooks/Chat/contract'; -export const ChatContext = createContext(null); +export const ChatContext = createContext(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 = + (() => T extends A ? 1 : 2) extends () => T extends B ? 1 : 2 ? true : false; +type Expect = T; + +type ChatFunctions = ReturnType; + +export type ChatContractChecks = [ + Expect, ChatContract>>, + Expect, ChatContract | null>>, + Expect>, + Expect>, + Expect['newConversation'], ChatContract['newConversation']>>, +]; + +export type AddedChatContractChecks = [ + Expect, AddedChatContract>>, + Expect, 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 +>; + +/** 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>; + /** 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>; + /** Legacy per-pane option toggles (examples, code chat). */ + optionSettings: TOptionSettings; + /** Replaces the legacy per-pane option toggles. */ + setOptionSettings: Dispatch>; +}; + +/** 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) => 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>; + /** Button handler that regenerates the latest response. AI SDK: `regenerate`. */ + handleRegenerate: (e: MouseEvent) => void; + /** Button handler that continues the latest response from where it stopped. */ + handleContinue: (e: MouseEvent) => 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; + /** Button handler around `stopGenerating`. AI SDK: `stop`. */ + handleStopGenerating: (e: MouseEvent) => void; + /** Whether a stop just happened and the view should hold its scroll position. */ + abortScroll: boolean; + /** Sets the post-stop scroll hold. */ + setAbortScroll: Dispatch>; +}; + +/** 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; + /** Replaces the staged attachments. */ + setFiles: Dispatch>>; + /** Whether an attachment is still uploading. */ + filesLoading: boolean; + /** Sets the attachment upload flag. */ + setFilesLoading: Dispatch>; +}; + +/** 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>; + /** 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>; + /** 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; - preset?: Partial; - 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 }); + }); +});