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

* refactor: declare the chat context contract

Replace the inferred ReturnType<typeof useChatHelpers> 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 0d4627b387)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16288
This commit is contained in:
Marco Beretta 2026-09-24 16:47:09 +02:00 • committed by Lia
parent 55ca9116a3
commit 07bbbc0d4d
8 changed files with 330 additions and 34 deletions

View file

@ -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);

View file

@ -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) {

View file

@ -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>>,
];

View file

@ -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;
};

View file

@ -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,

View file

@ -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,

View file

@ -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 ||

View file

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