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 }); + }); +});