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: Move useChatHelpers and ChatProvider into the Chat Package (#17446)
Marco Beretta7e56534c5f0e
diff --git a/client/src/Providers/ChatHostContext.tsx b/client/src/Providers/ChatHostContext.tsxnew file mode 100644index 0000000000..9003cc3378--- /dev/null+++ b/client/src/Providers/ChatHostContext.tsx@@ -0,0 +1,93 @@+import { useMemo } from 'react';+import { useAtomValue, useSetAtom } from 'jotai';+import { QueryKeys } from 'librechat-data-provider';+import { hashQueryKey, useQueryClient } from '@tanstack/react-query';+import type { QueryClient, QueryCacheNotifyEvent } from '@tanstack/react-query';+import type { ChatHost, ChatMessageCache } from '@librechat/chat/react';+import type { TMessage } from 'librechat-data-provider';+import { useLatestMessage, useLatestMessageId } from '~/hooks/Messages/useLatestMessage';+import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/state';+import { useChatSettings } from '~/Providers/ChatSettingsContext';+import { messageAttachmentsMapAtom } from '~/hooks/SSE/atoms';+import useChatFunctions from '~/hooks/Chat/useChatFunctions';+import { getMappingOptions } from '~/hooks/Chat/outcomes';+import { useAbortStreamMutation } from '~/data-provider';+import useNewConvo from '~/hooks/useNewConvo';++/** Cache events that add, drop or rewrite a query's data. */+const dataEvents = new Set<QueryCacheNotifyEvent['type']>(['added', 'removed', 'updated']);++const messagesHash = (key: string) => hashQueryKey([QueryKeys.messages, key]);++/**+ * The chat's message cache over the app's query cache. A subscription counts only events that+ * can change the data: observers mount inside other components' renders and the cache notifies+ * synchronously, so the change is delivered after the current task instead of inside someone+ * else's render. The revision is the query's own write count, so a write that lands before the+ * listener subscribes is still seen.+ */+export function createMessageCache(queryClient: QueryClient): ChatMessageCache {+ return {+ read: (key) => queryClient.getQueryData<TMessage[]>([QueryKeys.messages, key]),+ write: (key, messages) => {+ queryClient.setQueryData<TMessage[]>([QueryKeys.messages, key], messages);+ },+ subscribe: (key, onChange) => {+ const queryHash = messagesHash(key);+ let active = true;+ const unsubscribe = queryClient.getQueryCache().subscribe((event) => {+ if (event.query.queryHash !== queryHash || !dataEvents.has(event.type)) {+ return;+ }+ queueMicrotask(() => {+ if (active) {+ onChange();+ }+ });+ });+ return () => {+ active = false;+ unsubscribe();+ };+ },+ revision: (key) =>+ queryClient.getQueryCache().get(messagesHash(key))?.state.dataUpdateCount ?? 0,+ refetchMessages: (conversationId) => {+ queryClient.invalidateQueries({+ queryKey: [QueryKeys.messages, conversationId],+ refetchType: 'all',+ });+ },+ refetchActiveJobs: () => {+ queryClient.invalidateQueries({ queryKey: [QueryKeys.activeJobs] });+ },+ refetchStreamStatus: (conversationId) => {+ queryClient.invalidateQueries({ queryKey: ['streamStatus', conversationId] });+ },+ };+}++function useMessageCache(): ChatMessageCache {+ const queryClient = useQueryClient();+ return useMemo(() => createMessageCache(queryClient), [queryClient]);+}++/** The app's services behind `useChatHelpers`: its pane store, message query cache, turn+ * builder, thread selection, transport and settings. */+export const appChatHost: ChatHost = {+ usePaneConversation: (index) => useChatSettings().usePaneConversationState(index),+ useNewConversation: (index) => useNewConvo(index).newConversation,+ useTurns: (params) => useChatFunctions(params),+ useLatestMessage: (index, key) => useLatestMessage(index, key),+ useLatestMessageId: (index, key) => useLatestMessageId(index, key),+ useSetSiblingIdx: (parentMessageId) => useSetAtom(siblingIdxFamily(siblingKey(parentMessageId))),+ /** `mutateAsync` is bound once per observer; the mutation result object is fresh every+ * render and would defeat the contract's memo. */+ useAbortStream: () => useAbortStreamMutation().mutateAsync,+ useMessageCache,+ useLiveAttachments: () => useAtomValue(messageAttachmentsMapAtom),+ useFeedbackEnabled: () => useChatSettings().config.feedbackEnabled,+ getMappingOptions,+};++export { ChatHostProvider, useChatHost } from '@librechat/chat/react';diff --git a/client/src/Providers/__tests__/ChatContext.spec.tsx b/client/src/Providers/__tests__/ChatContext.spec.tsxindex 0ed00bf580..19927a2ff0 100644--- a/client/src/Providers/__tests__/ChatContext.spec.tsx+++ b/client/src/Providers/__tests__/ChatContext.spec.tsx@@ -1,6 +1,7 @@import React from 'react';import { render, screen } from '@testing-library/react';import '@testing-library/jest-dom/extend-expect';+import type { ChatContract } from '~/hooks/Chat/contract';import { ChatContext, useChatContext } from '~/Providers/ChatContext';function TestConsumer() {@@ -18,9 +19,7 @@ describe('ChatContext', () => {});it('provides context value when wrapped in provider', () => {- const mockHelpers = { index: 0 } as ReturnType<- typeof import('~/hooks/Chat/useChatHelpers').default- >;+ const mockHelpers = { index: 0 } as ChatContract;render(<ChatContext.Provider value={mockHelpers}><TestConsumer />diff --git a/client/src/components/Agents/MarketplaceContext.tsx b/client/src/components/Agents/MarketplaceContext.tsxindex 3a46255889..f7cafc46d5 100644--- a/client/src/components/Agents/MarketplaceContext.tsx+++ b/client/src/components/Agents/MarketplaceContext.tsx@@ -1,5 +1,5 @@import React from 'react';-import { ChatProvider } from '~/hooks/Chat/provider';+import { ChatProvider } from '@librechat/chat/react';/*** Minimal marketplace provider that provides only what SidePanel actually needsdiff --git a/client/src/components/Agents/tests/MarketplaceContext.spec.tsx b/client/src/components/Agents/tests/MarketplaceContext.spec.tsxindex d124f8a01b..4c25f5eeba 100644--- a/client/src/components/Agents/tests/MarketplaceContext.spec.tsx+++ b/client/src/components/Agents/tests/MarketplaceContext.spec.tsx@@ -11,10 +11,26 @@ const mockResetNewConversation = jest.fn();const mockUseChatHelpers = jest.fn();-jest.mock('~/hooks/Chat/useChatHelpers', () => ({- __esModule: true,- default: (index?: number, paramId?: string) => mockUseChatHelpers(index, paramId),-}));+/** The provider's contract is the spec's; it records the pane and route it was built for. */+jest.mock('@librechat/chat/react', () => {+ const actual = jest.requireActual('@librechat/chat/react');+ return {+ ...actual,+ ChatProvider: ({+ index = 0,+ conversationId,+ children,+ }: {+ index?: number;+ conversationId?: string;+ children: React.ReactNode;+ }) => (+ <actual.ChatContext.Provider value={mockUseChatHelpers(index, conversationId)}>+ {children}+ </actual.ChatContext.Provider>+ ),+ };+});const chatHelpers = {conversation: {diff --git a/client/src/components/Chat/__tests__/ChatView.spec.tsx b/client/src/components/Chat/__tests__/ChatView.spec.tsxindex 6902c2ef14..76ff80fd2e 100644--- a/client/src/components/Chat/__tests__/ChatView.spec.tsx+++ b/client/src/components/Chat/__tests__/ChatView.spec.tsx@@ -32,6 +32,7 @@ jest.mock('~/data-provider', () => ({*/jest.mock('@librechat/chat/react', () => ({...jest.requireActual('@librechat/chat/react'),+ useChatHelpers: () => ({ conversation: mockConversation() }),useQueueDrain: jest.fn(),useQueuedTurnReveal: jest.fn(),}));@@ -42,11 +43,6 @@ jest.mock('~/hooks', () => ({useScrollbarGutterSeed: jest.fn(),}));-jest.mock('~/hooks/Chat/useChatHelpers', () => ({- __esModule: true,- default: () => ({ conversation: mockConversation() }),-}));-jest.mock('~/hooks/SSE', () => ({useAdaptiveSSE: jest.fn(),useResumeOnLoad: jest.fn(),diff --git a/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx b/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsxindex 3b80a7bbc7..a8892b4b20 100644--- a/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx+++ b/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx@@ -29,6 +29,11 @@ jest.mock('librechat-data-provider', () => ({jest.mock('@librechat/chat/react', () => ({...jest.requireActual('@librechat/chat/react'),+ useChatHelpers: () => ({+ conversation: mockConversation,+ getMessages: jest.fn(),+ ask: jest.fn(),+ }),useQueueDrain: jest.fn(),useQueuedTurnReveal: jest.fn(),}));@@ -39,15 +44,6 @@ jest.mock('~/hooks', () => ({useLocalize: () => (key: string) => key,}));-jest.mock('~/hooks/Chat/useChatHelpers', () => ({- __esModule: true,- default: () => ({- conversation: mockConversation,- getMessages: jest.fn(),- ask: jest.fn(),- }),-}));-jest.mock('~/hooks/Chat/outcomes', () => ({getMappingOptions: () => ({}),}));diff --git a/client/src/components/UnifiedSidebar/UnifiedSidebar.tsx b/client/src/components/UnifiedSidebar/UnifiedSidebar.tsxindex 462ac92ac1..36c88534dd 100644--- a/client/src/components/UnifiedSidebar/UnifiedSidebar.tsx+++ b/client/src/components/UnifiedSidebar/UnifiedSidebar.tsx@@ -1,6 +1,7 @@import { useCallback, useState, useEffect, useRef, memo } from 'react';import { useAtom } from 'jotai';import { useForm } from 'react-hook-form';+import { ChatProvider } from '@librechat/chat/react';import { useLocation, useNavigate } from 'react-router-dom';import { pxToRem, useRemScale, useMediaQuery } from '@librechat/client';import type { ReactNode } from 'react';@@ -25,7 +26,6 @@ import { ChatFormProvider, ActivePanelProvider } from '~/Providers';import useSidebarToggle from '~/hooks/Nav/useSidebarToggle';import useSidebarState from '~/hooks/Nav/useSidebarState';import SidePanelNav from '~/components/SidePanel/Nav';-import { ChatProvider } from '~/hooks/Chat/provider';import { createResizeMeasure } from './resize';import { useLocalize } from '~/hooks';import Sidebar from './Sidebar';diff --git a/client/src/components/UnifiedSidebar/__tests__/drawerPaint.spec.tsx b/client/src/components/UnifiedSidebar/__tests__/drawerPaint.spec.tsxindex 64a896fbf4..ee72f245c0 100644--- a/client/src/components/UnifiedSidebar/__tests__/drawerPaint.spec.tsx+++ b/client/src/components/UnifiedSidebar/__tests__/drawerPaint.spec.tsx@@ -45,7 +45,8 @@ jest.mock('~/hooks', () => ({useShowMarketplace: () => false,}));-jest.mock('~/hooks/Chat/provider', () => ({+jest.mock('@librechat/chat/react', () => ({+ ...jest.requireActual('@librechat/chat/react'),ChatProvider: ({ children }: { children: ReactNode }) => <>{children}</>,}));diff --git a/client/src/data-provider/SSE/mutations.ts b/client/src/data-provider/SSE/mutations.tsindex 20622a08d0..0a133cd20f 100644--- a/client/src/data-provider/SSE/mutations.ts+++ b/client/src/data-provider/SSE/mutations.ts@@ -1,35 +1,11 @@import { useMutation } from '@tanstack/react-query';import { apiBaseUrl, EModelEndpoint } from 'librechat-data-provider';-import type { Agents, TMessage, TEphemeralAgent, TPendingSteer } from 'librechat-data-provider';+import type { AbortStreamParams, AbortStreamResponse } from '@librechat/chat/react';+import type { Agents, TMessage, TEphemeralAgent } from 'librechat-data-provider';import { useChatTransport } from '~/Providers/ChatTransportContext';import { postGenerationRequest } from './protocol';-export interface AbortStreamParams {- /** The stream ID to abort (if known) */- streamId?: string;- /** The conversation ID to abort (backend will look up the job) */- conversationId?: string;- /** Exact generation epoch returned by start/status. Prevents a stale tab- * from aborting a newer turn that reused the conversation-scoped stream id. */- generationCreatedAt?: number;-}--export interface AbortStreamResponse {- generationProtocolVersion?: number;- success: boolean;- aborted?: string;- /** Stop lost to an ordinary terminal transition; no abort FINAL was emitted. */- settled?: boolean;- code?: 'RUN_ALREADY_SETTLED' | string;- streamId?: string;- terminalStatus?: 'complete' | 'error' | 'aborted';- error?: string;- /** The worker stopped, but its terminal state could not be made durable.- * The client must not infer a safe queue-drain boundary from this ACK. */- persistenceFailed?: boolean;- /** Steers that never reached an injection boundary; restored as queued chips. */- pendingSteers?: TPendingSteer[];-}+export type { AbortStreamParams, AbortStreamResponse } from '@librechat/chat/react';/*** Abort an ongoing generation stream.diff --git a/client/src/hooks/Chat/__tests__/contract.spec.tsx b/client/src/hooks/Chat/__tests__/contract.spec.tsxindex 61d3ffca38..40f387b76f 100644--- a/client/src/hooks/Chat/__tests__/contract.spec.tsx+++ b/client/src/hooks/Chat/__tests__/contract.spec.tsx@@ -1,6 +1,7 @@import React from 'react';import { RecoilRoot } from 'recoil';import { renderHook } from '@testing-library/react';+import { useChatHelpers } from '@librechat/chat/react';import { RetentionMode } from 'librechat-data-provider';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';import type { TConversation, TModelSpec } from 'librechat-data-provider';@@ -9,13 +10,11 @@ import type { ChatSettings } from '../contract';import { ChatSettingsContext, defaultChatSettings } from '~/Providers/ChatSettingsContext';import useTemporaryChat from '~/hooks/Conversations/useTemporaryChat';import { usePaneConversationState } from '~/routes/ChatSettings';-import useChatHelpers from '../useChatHelpers';+import { SteerHostTestProvider } from 'test/steerHost';+import { ChatHostTestProvider } from 'test/chatHost';import useTokenLimits from '../useTokenLimits';import store from '~/store';-/** The contract's tool outcome rules are the app's; these specs map no tool parts. */-const noToolOutcomes = () => ({});-/** No `useGetStartupConfig`: a hook that still read the deployment config directly would throw. */jest.mock('~/data-provider', () => ({useTokenConfigQuery: () => ({ data: undefined }),@@ -39,11 +38,6 @@ jest.mock('~/hooks/useNewConvo', () => ({default: () => ({ newConversation: jest.fn() }),}));-jest.mock('@librechat/chat/react', () => ({- ...jest.requireActual('@librechat/chat/react'),- useSteerConvert: () => jest.fn(),-}));-/** The pane conversation comes from the app's pane store, as the host supplies it. */const paneSettings: ChatSettings = { ...defaultChatSettings, usePaneConversationState };@@ -56,7 +50,11 @@ function createWrapper(return (<QueryClientProvider client={queryClient}><RecoilRoot initializeState={initializeState}>- <ChatSettingsContext.Provider value={settings}>{children}</ChatSettingsContext.Provider>+ <ChatSettingsContext.Provider value={settings}>+ <SteerHostTestProvider>+ <ChatHostTestProvider>{children}</ChatHostTestProvider>+ </SteerHostTestProvider>+ </ChatSettingsContext.Provider></RecoilRoot></QueryClientProvider>);@@ -67,7 +65,7 @@ function renderChatHelpers(paramId?: string,initializeState?: (snapshot: MutableSnapshot) => void,) {- return renderHook(() => useChatHelpers(0, paramId, noToolOutcomes), {+ return renderHook(() => useChatHelpers(0, paramId), {wrapper: createWrapper(initializeState),});}@@ -111,7 +109,7 @@ describe('substitute host config', () => {const wrapper = createWrapper(undefined, hostSettings);it('reaches the chat helpers', () => {- const { result } = renderHook(() => useChatHelpers(0, undefined, noToolOutcomes), { wrapper });+ const { result } = renderHook(() => useChatHelpers(0), { wrapper });expect(result.current.feedbackEnabled).toBe(true);});@@ -133,7 +131,7 @@ describe('substitute host config', () => {const conversation = { endpoint: 'openAI', spec: 'long' } as TConversation;const { result } = renderHook(() => ({- helpers: useChatHelpers(0, undefined, noToolOutcomes),+ helpers: useChatHelpers(0),temporary: useTemporaryChat(),limits: useTokenLimits(conversation),}),diff --git a/client/src/hooks/Chat/__tests__/facade.spec.tsx b/client/src/hooks/Chat/__tests__/facade.spec.tsxindex db4eaaa058..a1f4eecd52 100644--- a/client/src/hooks/Chat/__tests__/facade.spec.tsx+++ b/client/src/hooks/Chat/__tests__/facade.spec.tsx@@ -6,7 +6,7 @@ import { QueryClient, QueryClientProvider, useQuery, useQueryClient } from '@tanimport type { TConversation, TMessage, TMessageContentParts } from 'librechat-data-provider';import type { ChatContract } from '../contract';import type { JotaiStore } from 'test/harness';-import { createMessagesSubscription } from '../cache';+import { createMessageCache } from '~/Providers/ChatHostContext';import { IsolatedAtomStore } from 'test/harness';import { getMappingOptions } from '../outcomes';@@ -76,10 +76,14 @@ const createContract = (overrides: Partial<ChatContract> = {}): ChatContract =>/** Serves `contract` subscribed to the provided query cache, as `useChatHelpers` serves it. */function CachedChat({ contract, children }: { contract: ChatContract; children: React.ReactNode }) {const queryClient = useQueryClient();- const value = React.useMemo(- () => ({ ...contract, ...createMessagesSubscription(queryClient, contract.messagesKey) }),- [contract, queryClient],- );+ const value = React.useMemo(() => {+ const cache = createMessageCache(queryClient);+ return {+ ...contract,+ subscribeMessages: (onChange: () => void) => cache.subscribe(contract.messagesKey, onChange),+ getMessagesRevision: () => cache.revision(contract.messagesKey),+ };+ }, [contract, queryClient]);return <ChatContext.Provider value={value}>{children}</ChatContext.Provider>;}diff --git a/client/src/hooks/Chat/__tests__/feedback.spec.tsx b/client/src/hooks/Chat/__tests__/feedback.spec.tsxindex 5d306d1f66..1f956a5042 100644--- a/client/src/hooks/Chat/__tests__/feedback.spec.tsx+++ b/client/src/hooks/Chat/__tests__/feedback.spec.tsx@@ -1,13 +1,12 @@import React from 'react';import { RecoilRoot } from 'recoil';import { renderHook } from '@testing-library/react';+import { useChatHelpers } from '@librechat/chat/react';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';import type { TStartupConfig } from 'librechat-data-provider';import ChatSettingsProvider from '~/routes/ChatSettings';-import useChatHelpers from '../useChatHelpers';--/** The contract's tool outcome rules are the app's; these specs map no tool parts. */-const noToolOutcomes = () => ({});+import { SteerHostTestProvider } from 'test/steerHost';+import { ChatHostTestProvider } from 'test/chatHost';let mockStartupConfig: Partial<TStartupConfig> | undefined;@@ -36,21 +35,20 @@ jest.mock('~/hooks/useNewConvo', () => ({default: () => ({ newConversation: jest.fn() }),}));-jest.mock('@librechat/chat/react', () => ({- ...jest.requireActual('@librechat/chat/react'),- useSteerConvert: () => jest.fn(),-}));-function renderChatHelpers() {const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });const wrapper = ({ children }: { children: React.ReactNode }) => (<QueryClientProvider client={queryClient}><RecoilRoot>- <ChatSettingsProvider>{children}</ChatSettingsProvider>+ <ChatSettingsProvider>+ <SteerHostTestProvider>+ <ChatHostTestProvider>{children}</ChatHostTestProvider>+ </SteerHostTestProvider>+ </ChatSettingsProvider></RecoilRoot></QueryClientProvider>);- return renderHook(() => useChatHelpers(0, undefined, noToolOutcomes), { wrapper });+ return renderHook(() => useChatHelpers(0), { wrapper });}describe('useChatHelpers feedbackEnabled', () => {diff --git a/client/src/hooks/Chat/__tests__/provider.spec.tsx b/client/src/hooks/Chat/__tests__/provider.spec.tsxindex 25e7ff5d08..c8925bf131 100644--- a/client/src/hooks/Chat/__tests__/provider.spec.tsx+++ b/client/src/hooks/Chat/__tests__/provider.spec.tsx@@ -5,7 +5,7 @@ import { useChatActions } from '@librechat/chat/react';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';import type { TConversation } from 'librechat-data-provider';import type { ChatContract } from '../contract';-import { ChatProvider, ChatSessionProvider } from '../provider';+import { ChatSessionProvider } from '../provider';const mockUseChatHelpers = jest.fn();const mockUseAdaptiveSSE = jest.fn();@@ -13,11 +13,6 @@ const mockUseResumeOnLoad = jest.fn();const mockUseQueueDrain = jest.fn();const mockRevealQueuedTurn = jest.fn();-jest.mock('../useChatHelpers', () => ({- __esModule: true,- default: (index?: number, paramId?: string) => mockUseChatHelpers(index, paramId),-}));-jest.mock('~/hooks/SSE', () => ({useAdaptiveSSE: (...args: unknown[]) => mockUseAdaptiveSSE(...args),useResumeOnLoad: (...args: unknown[]) => mockUseResumeOnLoad(...args),@@ -25,6 +20,7 @@ jest.mock('~/hooks/SSE', () => ({jest.mock('@librechat/chat/react', () => ({...jest.requireActual('@librechat/chat/react'),+ useChatHelpers: (index?: number, paramId?: string) => mockUseChatHelpers(index, paramId),useQueuedTurnReveal: () => mockRevealQueuedTurn,useQueueDrain: (...args: unknown[]) => mockUseQueueDrain(...args),}));@@ -67,40 +63,6 @@ const contract: ChatContract = {feedbackEnabled: false,};-const renderUnder = (props: { index?: number; conversationId?: string }) => {- const queryClient = new QueryClient();- return renderHook(() => useChatActions(), {- wrapper: ({ children }) => (- <QueryClientProvider client={queryClient}>- <ChatProvider {...props}>{children}</ChatProvider>- </QueryClientProvider>- ),- });-};--describe('ChatProvider', () => {- beforeEach(() => {- mockUseChatHelpers.mockReset();- mockUseChatHelpers.mockReturnValue(contract);- });-- it('serves the pane contract it builds to the facade below it', async () => {- const { result } = renderUnder({ index: 1, conversationId: 'convo-1' });-- expect(mockUseChatHelpers).toHaveBeenCalledWith(1, 'convo-1');- expect(result.current.id).toBe('convo-1');- expect(result.current.status).toBe('ready');- await result.current.stop();- expect(contract.stopGenerating).toHaveBeenCalledTimes(1);- });-- it('builds the root pane by default', () => {- renderUnder({});-- expect(mockUseChatHelpers).toHaveBeenCalledWith(0, undefined);- });-});-describe('ChatSessionProvider', () => {beforeEach(() => {jest.clearAllMocks();diff --git a/client/src/hooks/Chat/__tests__/transport.spec.tsx b/client/src/hooks/Chat/__tests__/transport.spec.tsxindex 8a83f7f1cf..b9f025a8ff 100644--- a/client/src/hooks/Chat/__tests__/transport.spec.tsx+++ b/client/src/hooks/Chat/__tests__/transport.spec.tsx@@ -2,6 +2,7 @@ import React from 'react';import { MemoryRouter } from 'react-router-dom';import { useAtomValue, getDefaultStore } from 'jotai';import { RecoilRoot, useSetRecoilState } from 'recoil';+import { useChatHelpers } from '@librechat/chat/react';import { act, renderHook, waitFor } from '@testing-library/react';import { useChat, resumeRequestsAtom } from '@librechat/chat/react';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';@@ -38,9 +39,8 @@ import { ChatContext, useChatContext } from '~/Providers/ChatContext';import { startupConfigKey } from '~/data-provider/Endpoints/queries';import useResumableSSE from '~/hooks/SSE/useResumableSSE';import useResumeOnLoad from '~/hooks/SSE/useResumeOnLoad';-import { getMappingOptions } from '~/hooks/Chat/outcomes';-import useChatHelpers from '~/hooks/Chat/useChatHelpers';import { SteerHostTestProvider } from 'test/steerHost';+import { ChatHostTestProvider } from 'test/chatHost';import useSSE from '~/hooks/SSE/useSSE';import store from '~/store';@@ -120,11 +120,13 @@ function createWrapper(}}><SteerHostTestProvider>- <ChatSettingsContext.Provider value={chatSettings}>- <ChatTransportContext.Provider value={transport}>- {children}- </ChatTransportContext.Provider>- </ChatSettingsContext.Provider>+ <ChatHostTestProvider>+ <ChatSettingsContext.Provider value={chatSettings}>+ <ChatTransportContext.Provider value={transport}>+ {children}+ </ChatTransportContext.Provider>+ </ChatSettingsContext.Provider>+ </ChatHostTestProvider></SteerHostTestProvider></RecoilRoot></QueryClientProvider>@@ -211,7 +213,7 @@ const renderSteering = (transport: Transport) =>/** The host builds the pane's chat contract, as the chat view does. */function ChatHost({ children }: { children: React.ReactNode }) {- const helpers: ChatContract = useChatHelpers(0, 'convo-1', getMappingOptions);+ const helpers: ChatContract = useChatHelpers(0, 'convo-1');return <ChatContext.Provider value={helpers}>{children}</ChatContext.Provider>;}@@ -311,7 +313,7 @@ describe('chat transport boundary', () => {it('stops a resumable generation through the host transport', async () => {const fake = createFakeTransport();- const { result } = renderHook(() => useChatHelpers(0, undefined, getMappingOptions), {+ const { result } = renderHook(() => useChatHelpers(0), {wrapper: createWrapper(fake.transport, seedRun),});@@ -329,7 +331,7 @@ describe('chat transport boundary', () => {it('settles a rejected stop without throwing to the caller', async () => {const failure = Object.assign(new Error('Not found'), { response: { status: 404 } });const fake = createFakeTransport({ abort: jest.fn(async () => Promise.reject(failure)) });- const { result } = renderHook(() => useChatHelpers(0, undefined, getMappingOptions), {+ const { result } = renderHook(() => useChatHelpers(0), {wrapper: createWrapper(fake.transport, seedRun),});diff --git a/client/src/hooks/Chat/cache.ts b/client/src/hooks/Chat/cache.tsdeleted file mode 100644index 3361ed5fbf..0000000000--- a/client/src/hooks/Chat/cache.ts+++ /dev/null@@ -1,85 +0,0 @@-import { hashQueryKey } from '@tanstack/react-query';-import { QueryKeys, Constants } from 'librechat-data-provider';-import type { QueryClient, QueryCacheNotifyEvent } from '@tanstack/react-query';-import type { ChatMessagesContract } from '@librechat/chat/react';-import type { TMessage } from 'librechat-data-provider';--type MessageCacheIdsParams = {- queryParam: string;- conversationId?: string | null;- messages: TMessage[];-};--function isConcreteConversationId(conversationId?: string | null): conversationId is string {- return (- !!conversationId &&- conversationId !== Constants.NEW_CONVO &&- conversationId !== Constants.PENDING_CONVO- );-}--export function getMessagesConversationId(messages: TMessage[]): string | undefined {- for (let i = messages.length - 1; i >= 0; i--) {- const conversationId = messages[i]?.conversationId;- if (isConcreteConversationId(conversationId)) {- return conversationId;- }- }-}--export function getMessageCacheIds({- queryParam,- conversationId,- messages,-}: MessageCacheIdsParams): string[] {- const ids = [queryParam];- const messageConversationId = getMessagesConversationId(messages);-- if (queryParam === Constants.NEW_CONVO && isConcreteConversationId(conversationId)) {- ids.push(conversationId);- }-- if (isConcreteConversationId(messageConversationId) && !ids.includes(messageConversationId)) {- ids.push(messageConversationId);- }-- return ids;-}--/** Cache events that add, drop or rewrite a query's data. */-const dataEvents = new Set<QueryCacheNotifyEvent['type']>(['added', 'removed', 'updated']);--/**- * The contract's subscription to one conversation's cached messages. Only events that can- * change the data count: observers mount inside other components' renders and the cache- * notifies synchronously, so the change is delivered after the current task instead of inside- * someone else's render. The revision is the query's own write count, so a write that lands- * before the listener subscribes is still seen.- */-export function createMessagesSubscription(- queryClient: QueryClient,- messagesKey: string,-): Pick<ChatMessagesContract, 'subscribeMessages' | 'getMessagesRevision'> {- const queryHash = hashQueryKey([QueryKeys.messages, messagesKey]);- return {- subscribeMessages: (onChange) => {- let active = true;- const unsubscribe = queryClient.getQueryCache().subscribe((event) => {- if (event.query.queryHash !== queryHash || !dataEvents.has(event.type)) {- return;- }- queueMicrotask(() => {- if (active) {- onChange();- }- });- });- return () => {- active = false;- unsubscribe();- };- },- getMessagesRevision: () =>- queryClient.getQueryCache().get(queryHash)?.state.dataUpdateCount ?? 0,- };-}diff --git a/client/src/hooks/Chat/contract.check.ts b/client/src/hooks/Chat/contract.check.tsindex a95c2dd1bf..1e71b98d0f 100644--- a/client/src/hooks/Chat/contract.check.ts+++ b/client/src/hooks/Chat/contract.check.ts@@ -8,15 +8,16 @@* whose own signatures could otherwise widen or narrow away from the contract, and the context* types consumers read.*/+import type { ChatHost, useChatHelpers } from '@librechat/chat/react';import type { ContextType } from 'react';import type { ChatContract, AddedChatContract, ChatSettings, Transport } from './contract';import type { ChatTransportContext } from '~/Providers/ChatTransportContext';import type { ChatSettingsContext } from '~/Providers/ChatSettingsContext';import type useAddedResponse from '~/hooks/Conversations/useAddedResponse';import type { AddedChatContext } from '~/Providers/AddedChatContext';+import type { appChatHost } from '~/Providers/ChatHostContext';import type { ChatContext } from '~/Providers/ChatContext';import type useChatFunctions from './useChatFunctions';-import type useChatHelpers from './useChatHelpers';import type useNewConvo from '../useNewConvo';type Equal<A, B> =@@ -33,6 +34,9 @@ export type ChatContractChecks = [Expect<Equal<ReturnType<typeof useNewConvo>['newConversation'], ChatContract['newConversation']>>,];+/** The app's host backs every member the chat helpers read, with the signatures they expect. */+export type ChatHostChecks = [Expect<Equal<typeof appChatHost, ChatHost>>];+export type AddedChatContractChecks = [Expect<Equal<ReturnType<typeof useAddedResponse>, AddedChatContract>>,Expect<Equal<ContextType<typeof AddedChatContext>, AddedChatContract>>,diff --git a/client/src/hooks/Chat/index.ts b/client/src/hooks/Chat/index.tsindex 838a4afcd7..f67bfe4eec 100644--- a/client/src/hooks/Chat/index.ts+++ b/client/src/hooks/Chat/index.ts@@ -1,4 +1,4 @@-export { default as useChatHelpers } from './useChatHelpers';+export { useChatHelpers } from '@librechat/chat/react';export { default as useTokenLimits } from './useTokenLimits';export { default as useTokenUsage } from './useTokenUsage';export { default as useChatFunctions } from './useChatFunctions';diff --git a/client/src/hooks/Chat/provider.tsx b/client/src/hooks/Chat/provider.tsxindex 115ffc648d..118dd01fd2 100644--- a/client/src/hooks/Chat/provider.tsx+++ b/client/src/hooks/Chat/provider.tsx@@ -1,7 +1,9 @@import { useAtomValue } from 'jotai';import { Constants } from 'librechat-data-provider';import {+ ChatContext,useQueueDrain,+ useChatHelpers,useIsSubmitting,submissionByIndex,useQueuedTurnReveal,@@ -10,29 +12,6 @@ import type { TMessage } from 'librechat-data-provider';import type { ReactNode } from 'react';import { useAdaptiveSSE, useResumeOnLoad } from '~/hooks/SSE';import { useGetMessagesByConvoId } from '~/data-provider';-import { ChatContext } from '~/Providers/ChatContext';-import { getMappingOptions } from './outcomes';-import useChatHelpers from './useChatHelpers';--/**- * Builds a pane's chat contract and serves it to `useChat`, `useChatActions` and- * `useChatContext` below. A host renders this instead of calling `useChatHelpers` itself, so- * components reach the chat only through the facade and its context.- */-export function ChatProvider({- index = 0,- conversationId,- children,-}: {- /** The pane: `0` is the root pane, `1` the added (multi-convo) pane. */- index?: number;- /** The route's conversation id, which can run ahead of the pane's conversation. */- conversationId?: string;- children: ReactNode;-}) {- const chat = useChatHelpers(index, conversationId, getMappingOptions);- return <ChatContext.Provider value={chat}>{children}</ChatContext.Provider>;-}/** The pane's messages query, as `ChatSessionProvider` hands it to the pane it renders. */export type ChatSessionMessages = {@@ -78,7 +57,7 @@ export function ChatSessionProvider({{ isStreaming: isSubmitting },);- const chat = useChatHelpers(index, conversationId, getMappingOptions);+ const chat = useChatHelpers(index, conversationId);const rootSubmission = useAtomValue(submissionByIndex(index));useAdaptiveSSE(rootSubmission, chat, false, index);diff --git a/client/src/hooks/Chat/useChatHelpers.ts b/client/src/hooks/Chat/useChatHelpers.tsdeleted file mode 100644index e71910165e..0000000000--- a/client/src/hooks/Chat/useChatHelpers.ts+++ /dev/null@@ -1,481 +0,0 @@-import { useCallback, useMemo, useRef, useState } from 'react';-import { useQueryClient } from '@tanstack/react-query';-import { useAtom, useSetAtom, useStore, useAtomValue } from 'jotai';-import { Constants, QueryKeys, isAssistantsEndpoint } from 'librechat-data-provider';-import {- filesFamily,- presetFamily,- optionSettingsFamily,- stopRequestedByConvoId,- drainAfterAbortByIndex,- runEndByIndex,- activeGenerationCreatedAtByConvoId,- activeGenerationProtocolVersionByConvoId,- isSubmittingFamily,- useIsSubmitting,- abortScrollFamily,- submissionByIndex,- useClearSubmissions,- useSteerConvert,-} from '@librechat/chat/react';-import type { TMessage } from 'librechat-data-provider';-import type { ChatContract } from './contract';-import { useLatestMessage, useLatestMessageId } from '~/hooks/Messages/useLatestMessage';-import { useAbortStreamMutation, supportsGenerationProtocolV2 } from '~/data-provider';-import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/state';-import { getMessageCacheIds, createMessagesSubscription } from './cache';-import { useChatSettings } from '~/Providers/ChatSettingsContext';-import { messageAttachmentsMapAtom } from '~/hooks/SSE/atoms';-import useChatFunctions from '~/hooks/Chat/useChatFunctions';-import { resolveAbortSteerTarget } from '~/utils';-import useNewConvo from '~/hooks/useNewConvo';-import { useAbortCleanup } from './abort';--/** The live attachments map the stream and preview polling write. */-const useLiveAttachments = () => useAtomValue(messageAttachmentsMapAtom);--/**- * Builds a pane's chat contract. `getMappingOptions` carries the app's tool outcome rules for- * the facade's message views; the providers pass them so this hook never loads the part- * components those rules live with.- */-export default function useChatHelpers(- index: number,- paramId: string | undefined,- getMappingOptions: ChatContract['getMappingOptions'],-): ChatContract {- const clearAllSubmissions = useClearSubmissions();- const [files, setFiles] = useAtom(filesFamily(index));- const [filesLoading, setFilesLoading] = useState(false);-- const queryClient = useQueryClient();- /** `mutateAsync` is bound once per observer; the mutation result object is- * fresh every render and would defeat the context value memo below. */- const { mutateAsync: abortStream } = useAbortStreamMutation();- const convertSteersToQueued = useSteerConvert();- const { captureSubmission, clearSubmissionsUnlessReplaced } = useAbortCleanup(index);-- /** Async abort responses can settle after this pane has moved to another- * conversation and armed its own interrupt. Clear only the intent owned by- * the request that produced the response. */- const queueStore = useStore();- const clearInterruptDrain = useCallback(- (convoId: string, generationCreatedAt: number) => {- const armed = queueStore.get(drainAfterAbortByIndex(index));- if (- armed !== false &&- armed.conversationId === convoId &&- armed.generationCreatedAt === generationCreatedAt- ) {- queueStore.set(drainAfterAbortByIndex(index), false);- }- },- [index, queueStore],- );-- /** A missing job cannot deliver FINAL, so release its armed interrupt queue. */- const signalInterruptDrain = useCallback(- (convoId: string, generationCreatedAt: number, armedConversationId = convoId) => {- const armed = queueStore.get(drainAfterAbortByIndex(index));- const runEnd = queueStore.get(runEndByIndex(index));- const matchesArm =- armed !== false &&- armed.conversationId === armedConversationId &&- armed.generationCreatedAt === generationCreatedAt;- const alreadySignaled =- runEnd?.conversationId === convoId && runEnd.generationCreatedAt === generationCreatedAt;- if (!matchesArm || alreadySignaled) {- return;- }- queueStore.set(runEndByIndex(index), {- conversationId: convoId,- outcome: 'aborted',- endedAt: Date.now(),- generationCreatedAt,- });- },- [index, queueStore],- );-- const { newConversation } = useNewConvo(index);- const chatSettings = useChatSettings();- const { conversation, setConversation } = chatSettings.usePaneConversationState(index);- const { conversationId, endpoint, endpointType } = conversation ?? {};- const activeGenerationCreatedAt = useAtomValue(- activeGenerationCreatedAtByConvoId(conversationId ?? Constants.NEW_CONVO),- );- const activeGenerationProtocolVersion = useAtomValue(- activeGenerationProtocolVersionByConvoId(conversationId ?? Constants.NEW_CONVO),- );-- /** Use paramId (from URL) as primary source for query key - this must match what ChatView uses- Falling back to conversationId (Recoil) only if paramId is not available */- const queryParam = paramId === 'new' ? paramId : (paramId ?? conversationId ?? '');-- const isSubmitting = useIsSubmitting(index);- const setIsSubmitting = useSetAtom(isSubmittingFamily(index));- const latestMessage = useLatestMessage(index, queryParam);-- const latestMessageId = useLatestMessageId(index, queryParam) ?? undefined;- const latestMessageDepth = latestMessage?.depth;- const latestMessageRef = useRef(latestMessage);- latestMessageRef.current = latestMessage;-- const setSiblingIdx = useSetAtom(- siblingIdxFamily(siblingKey(latestMessage?.parentMessageId ?? null)),- );- /** The setter is rebound whenever the tail's parent changes (every turn); the- * ref keeps `handleContinue` referentially stable so rows do not re-render. */- const setSiblingIdxRef = useRef(setSiblingIdx);- setSiblingIdxRef.current = setSiblingIdx;-- const setMessages = useCallback(- (messages: TMessage[]) => {- const messageCacheIds = getMessageCacheIds({ queryParam, conversationId, messages });- for (const messageCacheId of messageCacheIds) {- queryClient.setQueryData<TMessage[]>([QueryKeys.messages, messageCacheId], messages);- }- },- [queryParam, queryClient, conversationId],- );-- const { subscribeMessages, getMessagesRevision } = useMemo(- () => createMessagesSubscription(queryClient, queryParam),- [queryClient, queryParam],- );-- const getMessages = useCallback(- (targetConversationId?: string | null) => {- return queryClient.getQueryData<TMessage[]>([- QueryKeys.messages,- targetConversationId ?? queryParam,- ]);- },- [queryParam, queryClient],- );-- const setSubmission = useSetAtom(submissionByIndex(index));-- const { ask: _ask, regenerate: _regenerate } = useChatFunctions({- index,- files,- setFiles,- getMessages,- setMessages,- isSubmitting,- conversation,- latestMessage,- setSubmission,- setConversation,- });-- const askRef = useRef(_ask);- askRef.current = _ask;- const ask: typeof _ask = useCallback((...args) => askRef.current(...args), []);-- const regenerateRef = useRef(_regenerate);- regenerateRef.current = _regenerate;- const regenerate: typeof _regenerate = useCallback(- (...args) => regenerateRef.current(...args),- [],- );-- const continueGeneration = useCallback(() => {- const currentLatest = latestMessageRef.current;- if (!currentLatest) {- console.error('Failed to regenerate the message: latestMessage not found.');- return;- }-- const messages = getMessages();-- const parentMessage = messages?.find(- (element) => element.messageId == currentLatest.parentMessageId,- );-- if (parentMessage && parentMessage.isCreatedByUser) {- ask(- { ...parentMessage },- {- isContinued: true,- isRegenerate: true,- isEdited: true,- overrideManualSkills: parentMessage.manualSkills,- overrideQuotes: parentMessage.quotes,- overrideReasoning: parentMessage.reasoningOverride ?? null,- },- );- } else {- console.error(- 'Failed to regenerate the message: parentMessage not found, or not created by user.',- );- }- }, [getMessages, ask]);-- /**- * Stop generation - for non-assistants endpoints, calls abort endpoint first.- * The abort endpoint will cause the backend to emit a `done` event with `aborted: true`,- * which will be handled by the SSE event handler to clean up UI.- * Assistants endpoint has its own abort mechanism via useEventHandlers.abortConversation.- */- const stopGenerating = useCallback(async () => {- const actualEndpoint = endpointType ?? endpoint;- const isAssistants = isAssistantsEndpoint(actualEndpoint);- console.log('[useChatHelpers] stopGenerating called', {- conversationId,- endpoint,- endpointType,- actualEndpoint,- isAssistants,- });-- // For non-assistants endpoints (using resumable streams), call abort endpoint first- if (conversationId && !isAssistants) {- /** Stop is a generation-scoped mutation. `isSubmitting` becomes true- * before the start POST returns, so a stale/missing epoch must make this- * path inert instead of aborting whichever conversation job is current. */- if (activeGenerationCreatedAt == null) {- 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;- // the fallback clear below must not tear down that new run.- const submissionAtAbort = captureSubmission();- const stoppedRun = { generationCreatedAt: activeGenerationCreatedAt };- const stopFamily = stopRequestedByConvoId(conversationId);- queueStore.set(stopFamily, stoppedRun);- try {- console.log('[useChatHelpers] Calling abort mutation for:', conversationId);- const response = await abortStream({- conversationId,- ...(activeGenerationCreatedAt != null && {- generationCreatedAt: activeGenerationCreatedAt,- }),- });- console.log('[useChatHelpers] Abort mutation succeeded');- const canUseV2AbortResponse =- activeGenerationProtocolVersion === 2 && supportsGenerationProtocolV2(response);- /** Conversation-scoped active-job ids cannot be removed optimistically:- * a newer generation may have started while this response was in flight.- * Refetch instead so that replacement remains represented. */- queryClient.invalidateQueries({ queryKey: [QueryKeys.activeJobs] });- if (canUseV2AbortResponse && response?.settled === true) {- /** Natural completion/error won the terminal CAS, so this request did- * not emit an abort FINAL and must not release the abort-drain queue.- * The winning terminal event/status owns reconciliation. A run that- * completed or failed was not stopped, so its persisted outcome may- * still drain; one another Stop already aborted stays stopped. */- clearInterruptDrain(conversationId, activeGenerationCreatedAt);- if (response.terminalStatus !== 'aborted' && queueStore.get(stopFamily) === stoppedRun) {- queueStore.set(stopFamily, null);- }- queryClient.invalidateQueries({- queryKey: [QueryKeys.messages, conversationId],- refetchType: 'all',- });- queryClient.invalidateQueries({ queryKey: ['streamStatus', conversationId] });- return;- }- if (canUseV2AbortResponse && response?.persistenceFailed === true) {- /** The process was interrupted, but neither a durable terminal- * payload nor a trustworthy leftover-steer set exists. Keep the SSE- * submission attached for its reconciliation frame/status retry and- * do not consume the armed interrupt queue against unknown history. */- clearInterruptDrain(conversationId, activeGenerationCreatedAt);- queryClient.invalidateQueries({- queryKey: [QueryKeys.messages, conversationId],- refetchType: 'all',- });- queryClient.invalidateQueries({- queryKey: ['streamStatus', conversationId],- });- return;- }- // 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.- const { chipConvoId, claimConvoId } = resolveAbortSteerTarget({- conversationId,- resolvedId: response?.aborted,- });- /** Keep the submission attached until FINAL/status reconciles history.- * Clearing on the ACK can close SSE during terminal authorization and- * strand the preliminary response as an unsaved follow-up parent.- * Only terminal reconciliation may release the interrupt queue. */- // Restore uninjected steers from the ACK as well as FINAL. Conversion- // dedupes by steer id; `claimParked` reconciles the replayable copy.- if (Array.isArray(response?.pendingSteers)) {- convertSteersToQueued(chipConvoId, response.pendingSteers, {- claimParked: true,- claimConversationId: claimConvoId,- generationProtocolVersion: canUseV2AbortResponse ? 2 : 1,- });- }- } catch (error) {- console.error('[useChatHelpers] Abort failed:', error);- const errorData = (- error as {- response?: { data?: { code?: string; generationProtocolVersion?: unknown } };- } | null- )?.response?.data;- const code = errorData?.code;- if (- code === 'RUN_REPLACED' &&- activeGenerationProtocolVersion === 2 &&- supportsGenerationProtocolV2(errorData)- ) {- // This tab targeted an older generation. Do not emit an abort run-end- // or consume its armed queue against the newer live owner.- queryClient.invalidateQueries({ queryKey: [QueryKeys.activeJobs] });- clearSubmissionsUnlessReplaced(submissionAtAbort);- return;- }- const status = (error as { response?: { status?: number } } | null | undefined)?.response- ?.status;- if (status === 404) {- // A missing job cannot still consume the interrupt follow-up. Release- // the armed queue even if its ordinary terminal frame raced cleanup.- signalInterruptDrain(conversationId, activeGenerationCreatedAt);- clearSubmissionsUnlessReplaced(submissionAtAbort);- return;- }- /** A timeout/5xx is an unknown mutation outcome: the job may still be- * live, or the abort may have committed without its response. Keep the- * attachment and armed queue parked until SSE/status proves a terminal- * boundary; firing it now could replace a still-running generation. */- queryClient.invalidateQueries({ queryKey: [QueryKeys.activeJobs] });- queryClient.invalidateQueries({ queryKey: ['streamStatus', conversationId] });- }- } else {- // For assistants endpoints, just clear submissions (existing behavior)- console.log('[useChatHelpers] Assistants endpoint, just clearing submissions');- clearAllSubmissions();- }- }, [- conversationId,- endpoint,- endpointType,- queueStore,- activeGenerationCreatedAt,- activeGenerationProtocolVersion,- abortStream,- captureSubmission,- convertSteersToQueued,- signalInterruptDrain,- clearSubmissionsUnlessReplaced,- clearAllSubmissions,- queryClient,- clearInterruptDrain,- ]);-- const handleStopGenerating = useCallback(- (e: React.MouseEvent<HTMLButtonElement>) => {- e.preventDefault();- stopGenerating();- },- [stopGenerating],- );-- const handleRegenerate = useCallback(- (e: React.MouseEvent<HTMLButtonElement>) => {- e.preventDefault();- const parentMessageId = latestMessageRef.current?.parentMessageId ?? '';- if (!parentMessageId) {- console.error('Failed to regenerate the message: parentMessageId not found.');- return;- }- regenerate({ parentMessageId });- },- [regenerate],- );-- const handleContinue = useCallback(- (e: React.MouseEvent<HTMLButtonElement>) => {- e.preventDefault();- continueGeneration();- setSiblingIdxRef.current(0);- },- [continueGeneration],- );-- const [preset, setPreset] = useAtom(presetFamily(index));- const [abortScroll, setAbortScroll] = useAtom(abortScrollFamily(index));- const [optionSettings, setOptionSettings] = useAtom(optionSettingsFamily(index));-- /** Read once per chat rather than per message row: message rows never unmount, so a- * per-row settings read would accumulate for the length of the conversation. */- const { feedbackEnabled } = chatSettings.config;-- return useMemo(- (): ChatContract => ({- newConversation,- conversation,- setConversation,- isSubmitting,- setIsSubmitting,- getMessages,- messagesKey: queryParam,- setMessages,- subscribeMessages,- getMessagesRevision,- setSiblingIdx,- latestMessageId,- latestMessageDepth,- useLiveAttachments,- ask,- index,- regenerate,- stopGenerating,- handleStopGenerating,- handleRegenerate,- handleContinue,- abortScroll,- setAbortScroll,- preset,- setPreset,- optionSettings,- setOptionSettings,- files,- setFiles,- filesLoading,- setFilesLoading,- feedbackEnabled,- getMappingOptions,- }),- [- newConversation,- conversation,- setConversation,- isSubmitting,- setIsSubmitting,- getMessages,- queryParam,- setMessages,- subscribeMessages,- getMessagesRevision,- setSiblingIdx,- latestMessageId,- latestMessageDepth,- ask,- index,- regenerate,- stopGenerating,- handleStopGenerating,- handleRegenerate,- handleContinue,- abortScroll,- setAbortScroll,- preset,- setPreset,- optionSettings,- setOptionSettings,- files,- setFiles,- filesLoading,- setFilesLoading,- feedbackEnabled,- getMappingOptions,- ],- );-}diff --git a/client/src/routes/Root.tsx b/client/src/routes/Root.tsxindex ca935e574f..13fef43088 100644--- a/client/src/routes/Root.tsx+++ b/client/src/routes/Root.tsx@@ -35,6 +35,7 @@ import {} from '~/components/Chat/Messages/Content/Parts/useLazyHighlight';import KeyboardShortcutsDialog from '~/components/Nav/KeyboardShortcutsDialog';import { SteerHostProvider, appSteerHost } from '~/Providers/SteerHostContext';+import { ChatHostProvider, appChatHost } from '~/Providers/ChatHostContext';import KeyboardDeleteDialog from '~/components/Nav/KeyboardDeleteDialog';import { useUserTermsQuery, useGetStartupConfig } from '~/data-provider';import { MobileDrawerScrim } from '~/components/UnifiedSidebar/mobile';@@ -269,7 +270,9 @@ export default function Root() {return (<ChatSettingsProvider><SteerHostProvider host={appSteerHost}>- <RootLayout />+ <ChatHostProvider host={appChatHost}>+ <RootLayout />+ </ChatHostProvider></SteerHostProvider></ChatSettingsProvider>);diff --git a/client/src/routes/__tests__/Marketplace.spec.tsx b/client/src/routes/__tests__/Marketplace.spec.tsxindex 43032ee8f2..c3642a4fbc 100644--- a/client/src/routes/__tests__/Marketplace.spec.tsx+++ b/client/src/routes/__tests__/Marketplace.spec.tsx@@ -9,9 +9,9 @@ import MarketplaceRoute from '../Marketplace';const mockClearAllConversations = jest.fn();const mockClearMessagesCache = jest.fn();-jest.mock('~/hooks/Chat/useChatHelpers', () => ({- __esModule: true,- default: jest.fn(() => ({})),+jest.mock('@librechat/chat/react', () => ({+ ...jest.requireActual('@librechat/chat/react'),+ ChatProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,}));jest.mock('~/utils/messages', () => ({diff --git a/client/test/chatHost.tsx b/client/test/chatHost.tsxnew file mode 100644index 0000000000..34249b717d--- /dev/null+++ b/client/test/chatHost.tsx@@ -0,0 +1,9 @@+import React from 'react';+import { ChatHostProvider } from '@librechat/chat/react';+import { appChatHost } from '~/Providers/ChatHostContext';++/** Mounts the app's chat host the way `routes/Root.tsx` does, for specs that render the chat+ * hooks outside the app shell. Import it after the spec's module mocks so the host uses them. */+export function ChatHostTestProvider({ children }: { children?: React.ReactNode }) {+ return <ChatHostProvider host={appChatHost}>{children}</ChatHostProvider>;+}diff --git a/client/src/hooks/Chat/__tests__/cache.spec.ts b/packages/chat/src/react/chat/__tests__/cache.spec.tssimilarity index 100%rename from client/src/hooks/Chat/__tests__/cache.spec.tsrename to packages/chat/src/react/chat/__tests__/cache.spec.tsdiff --git a/client/src/hooks/Chat/__tests__/abort.spec.tsx b/packages/chat/src/react/chat/__tests__/stop.spec.tsxsimilarity index 77%rename from client/src/hooks/Chat/__tests__/abort.spec.tsxrename to packages/chat/src/react/chat/__tests__/stop.spec.tsxindex 1635ad5c21..346c85fa65 100644--- a/client/src/hooks/Chat/__tests__/abort.spec.tsx+++ b/packages/chat/src/react/chat/__tests__/stop.spec.tsx@@ -1,68 +1,66 @@+/**+ * @jest-environment jsdom+ */import React from 'react';-import { RecoilRoot } from 'recoil';import { Constants } from 'librechat-data-provider';import { useAtomValue, useSetAtom, getDefaultStore } from 'jotai';import { act, renderHook, waitFor } from '@testing-library/react';-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';-import {- stopRequestedByConvoId,- drainAfterAbortByIndex,- resetQueueFamilies,- runEndByIndex,-} from '@librechat/chat/react';+import type { TSubmission, TConversation } from 'librechat-data-provider';+import type { DrainAfterAbort, RunEnd } from '../../../core';+import type { ChatHost, ChatMessageCache } from '../host';import {resetSteerFamilies,activeGenerationCreatedAtByConvoId,activeGenerationProtocolVersionByConvoId,- submissionByIndex,- clearSubmissions,-} from '@librechat/chat/react';-import type { TSubmission, TConversation } from 'librechat-data-provider';-import type { DrainAfterAbort, RunEnd } from '@librechat/chat';-import { ChatSettingsContext, defaultChatSettings } from '~/Providers/ChatSettingsContext';-import { usePaneConversationState } from '~/routes/ChatSettings';-import useChatHelpers from '../useChatHelpers';+} from '../../steer/atoms';+import {+ runEndByIndex,+ resetQueueFamilies,+ stopRequestedByConvoId,+ drainAfterAbortByIndex,+} from '../../steer/queue';+import { submissionByIndex, clearSubmissions } from '../../submission';+import { ChatHostProvider } from '../host';import { useAbortCleanup } from '../abort';-import store from '~/store';--/** The contract's tool outcome rules are the app's; these specs map no tool parts. */-const noToolOutcomes = () => ({});+import useChatHelpers from '../helpers';-const mockAbortMutateAsync = jest.fn();+const mockAbortStream = jest.fn();const mockConvertSteersToQueued = jest.fn();-jest.mock('~/data-provider', () => ({- useGetStartupConfig: () => ({ data: undefined }),- useAbortStreamMutation: () => ({ mutateAsync: mockAbortMutateAsync }),- supportsGenerationProtocolV2: (value: unknown) =>- value != null &&- typeof value === 'object' &&- (value as { generationProtocolVersion?: unknown }).generationProtocolVersion === 2,+jest.mock('../../steering/useSteerConvert', () => ({+ __esModule: true,+ default: () => mockConvertSteersToQueued,}));-jest.mock('~/hooks/Messages/useLatestMessage', () => ({+const noop = () => undefined;+const noLiveAttachments = {};+const turns = { ask: jest.fn(), regenerate: jest.fn() };+const cache: ChatMessageCache = {+ read: () => undefined,+ write: noop,+ subscribe: () => noop,+ revision: () => 0,+ refetchMessages: jest.fn(),+ refetchActiveJobs: jest.fn(),+ refetchStreamStatus: jest.fn(),+};++/** A host with no app behind it: one fixed pane conversation and the abort under test. */+const createHost = (conversation: TConversation | null): ChatHost => ({+ usePaneConversation: () => ({ conversation, setConversation: noop }),+ useNewConversation: () => noop,+ useTurns: () => turns,useLatestMessage: () => null,useLatestMessageId: () => null,-}));--jest.mock('~/hooks/Chat/useChatFunctions', () => ({- __esModule: true,- default: () => ({ ask: jest.fn(), regenerate: jest.fn() }),-}));--jest.mock('~/hooks/useNewConvo', () => ({- __esModule: true,- default: () => ({ newConversation: jest.fn() }),-}));--jest.mock('@librechat/chat/react', () => ({- ...jest.requireActual('@librechat/chat/react'),- useSteerConvert: () => mockConvertSteersToQueued,-}));+ useSetSiblingIdx: () => noop,+ useAbortStream: () => mockAbortStream,+ useMessageCache: () => cache,+ useLiveAttachments: () => noLiveAttachments,+ useFeedbackEnabled: () => false,+ getMappingOptions: () => ({}),+});const INDEX = 0;-/** The pane conversation comes from the app's pane store, as the host supplies it. */-const paneSettings = { ...defaultChatSettings, usePaneConversationState };const OTHER_INDEX = 1;const submission = (id: string) =>@@ -94,15 +92,10 @@ function setup() {}const wrapper = ({ children }: { children: React.ReactNode }) => (- <RecoilRoot- initializeState={({ set }) => {- // clearAllSubmissions iterates the registered conversation keys.- set(store.conversationKeysAtom, [INDEX, OTHER_INDEX]);- }}- >+ <><Harness />{children}- </RecoilRoot>+ </>);renderHook(() => null, { wrapper });return { handles, current };@@ -218,40 +211,28 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {setDrainAfterAbort = useSetAtom(drainAfterAbortByIndex(INDEX));return null;}- const queryClient = new QueryClient();+ getDefaultStore().set(submissionByIndex(INDEX), stoppedSubmission);+ /** Arm interrupt & send so the abort response writes the drain signal. */+ getDefaultStore().set(drainAfterAbortByIndex(INDEX), {+ conversationId,+ generationCreatedAt: 41,+ });+ if (generationCreatedAt != null) {+ getDefaultStore().set(+ activeGenerationCreatedAtByConvoId(conversationId),+ generationCreatedAt,+ );+ getDefaultStore().set(activeGenerationProtocolVersionByConvoId(conversationId), 2);+ }+ const host = createHost({ conversationId, endpoint: 'agents' } as TConversation);const wrapper = ({ children }: { children: React.ReactNode }) => (- <QueryClientProvider client={queryClient}>- <RecoilRoot- initializeState={({ set }) => {- set(store.conversationKeysAtom, [INDEX]);- getDefaultStore().set(submissionByIndex(INDEX), stoppedSubmission);- set(store.conversationByIndex(INDEX), {- conversationId,- endpoint: 'agents',- } as TConversation);- // Arm interrupt & send so the abort response writes the drain signal.- getDefaultStore().set(drainAfterAbortByIndex(INDEX), {- conversationId,- generationCreatedAt: 41,- });- if (generationCreatedAt != null) {- getDefaultStore().set(- activeGenerationCreatedAtByConvoId(conversationId),- generationCreatedAt,- );- getDefaultStore().set(activeGenerationProtocolVersionByConvoId(conversationId), 2);- }- }}- >- <RunEndProbe />- <ChatSettingsContext.Provider value={paneSettings}>- {children}- </ChatSettingsContext.Provider>- </RecoilRoot>- </QueryClientProvider>+ <ChatHostProvider host={host}>+ <RunEndProbe />+ {children}+ </ChatHostProvider>);return {- ...renderHook(() => useChatHelpers(INDEX, undefined, noToolOutcomes), { wrapper }),+ ...renderHook(() => useChatHelpers(INDEX), { wrapper }),stoppedSubmission,setDrainAfterAbort: (value: DrainAfterAbort | false) => setDrainAfterAbort?.(value),};@@ -260,7 +241,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {beforeEach(() => {observed.runEnd = null;observed.drainAfterAbort = false;- mockAbortMutateAsync.mockReset();+ mockAbortStream.mockReset();mockConvertSteersToQueued.mockReset();jest.spyOn(console, 'log').mockImplementation(() => undefined);});@@ -272,7 +253,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {it.each([String(Constants.NEW_CONVO), 'convo-held'])('keeps the stopped submission attached for terminal reconciliation in %s',async (conversationId) => {- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: true,aborted: 'convo-resolved',generationProtocolVersion: 2,@@ -291,7 +272,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {it('keeps chips on the new composer while waiting for FINAL to drain', async () => {const pendingSteers = [{ steerId: 's1', text: 'leftover words' }];- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: true,aborted: 'convo-resolved',pendingSteers,@@ -303,7 +284,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {await result.current.stopGenerating();});- expect(mockAbortMutateAsync).toHaveBeenCalledWith({+ expect(mockAbortStream).toHaveBeenCalledWith({conversationId: String(Constants.NEW_CONVO),generationCreatedAt: 41,});@@ -324,7 +305,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {it('prefers the response resolved id over the client-held id for an existing conversation', async () => {const pendingSteers = [{ steerId: 's2', text: 'other leftover' }];- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: true,aborted: 'convo-resolved',pendingSteers,@@ -345,21 +326,21 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('fences abort to the attached generation epoch', async () => {- mockAbortMutateAsync.mockResolvedValue({ success: true, aborted: 'convo-held' });+ mockAbortStream.mockResolvedValue({ success: true, aborted: 'convo-held' });const { result } = setupStop('convo-held', 41);await act(async () => {await result.current.stopGenerating();});- expect(mockAbortMutateAsync).toHaveBeenCalledWith({+ expect(mockAbortStream).toHaveBeenCalledWith({conversationId: 'convo-held',generationCreatedAt: 41,});});it('does not arm a run-end drain when abort targets a replaced generation', async () => {- mockAbortMutateAsync.mockRejectedValue({+ mockAbortStream.mockRejectedValue({response: {status: 409,data: { code: 'RUN_REPLACED', generationProtocolVersion: 2 },@@ -382,7 +363,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {await result.current.stopGenerating();});- expect(mockAbortMutateAsync).not.toHaveBeenCalled();+ expect(mockAbortStream).not.toHaveBeenCalled();expect(mockConvertSteersToQueued).not.toHaveBeenCalled();expect(observed.runEnd).toBeNull();expect(observed.drainAfterAbort).toEqual({@@ -392,7 +373,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('waits for SSE reconciliation when abort persistence fails', async () => {- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: true,aborted: 'convo-held',persistenceFailed: true,@@ -404,7 +385,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {await result.current.stopGenerating();});- expect(mockAbortMutateAsync).toHaveBeenCalledWith({+ expect(mockAbortStream).toHaveBeenCalledWith({conversationId: 'convo-held',generationCreatedAt: 41,});@@ -417,7 +398,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('does not release the abort-drain queue when natural completion already settled the run', async () => {- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: false,settled: true,code: 'RUN_ALREADY_SETTLED',@@ -440,7 +421,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('keeps Stop when another Stop already aborted the run', async () => {- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: false,settled: true,code: 'RUN_ALREADY_SETTLED',@@ -462,7 +443,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {it('does not let a late abort response clear another conversation epoch', async () => {let resolveAbort: ((value: unknown) => void) | undefined;- mockAbortMutateAsync.mockReturnValue(+ mockAbortStream.mockReturnValue(new Promise((resolve) => {resolveAbort = resolve;}),@@ -493,7 +474,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('does not release the armed queue for an unknown abort outcome', async () => {- mockAbortMutateAsync.mockRejectedValue({ response: { status: 503 } });+ mockAbortStream.mockRejectedValue({ response: { status: 503 } });const { result } = setupStop('convo-held');await act(async () => {@@ -509,7 +490,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('releases the armed queue only when abort authoritatively returns 404', async () => {- mockAbortMutateAsync.mockRejectedValue({ response: { status: 404 } });+ mockAbortStream.mockRejectedValue({ response: { status: 404 } });const { result } = setupStop('convo-held');await act(async () => {@@ -524,7 +505,7 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {});it('falls back to the client-held id when the response carries no resolved id', async () => {- mockAbortMutateAsync.mockResolvedValue({+ mockAbortStream.mockResolvedValue({success: true,pendingSteers: [],generationProtocolVersion: 2,diff --git a/client/src/hooks/Chat/abort.ts b/packages/chat/src/react/chat/abort.tssimilarity index 82%rename from client/src/hooks/Chat/abort.tsrename to packages/chat/src/react/chat/abort.tsindex 443e3b5202..3ac71abe33 100644--- a/client/src/hooks/Chat/abort.ts+++ b/packages/chat/src/react/chat/abort.ts@@ -1,7 +1,7 @@import { useCallback } from 'react';import { useStore } from 'jotai';-import { submissionByIndex, useClearSubmissions } from '@librechat/chat/react';import type { TSubmission } from 'librechat-data-provider';+import { submissionByIndex, useClearSubmissions } from '../submission';/*** Identity-guarded post-abort cleanup: the abort HTTP response can resolve@@ -11,7 +11,10 @@ import type { TSubmission } from 'librechat-data-provider';* finalizes empty. Capture the submission before the abort round-trip and* only clear when it is still the current one.*/-export function useAbortCleanup(index: string | number) {+export function useAbortCleanup(index: string | number): {+ captureSubmission: () => TSubmission | null;+ clearSubmissionsUnlessReplaced: (captured: TSubmission | null) => void;+} {const jotaiStore = useStore();const clearAllSubmissions = useClearSubmissions();diff --git a/packages/chat/src/react/chat/cache.ts b/packages/chat/src/react/chat/cache.tsnew file mode 100644index 0000000000..b07ab2398c--- /dev/null+++ b/packages/chat/src/react/chat/cache.ts@@ -0,0 +1,44 @@+import { Constants } from 'librechat-data-provider';+import type { TMessage } from 'librechat-data-provider';++type MessageCacheIdsParams = {+ queryParam: string;+ conversationId?: string | null;+ messages: TMessage[];+};++function isConcreteConversationId(conversationId?: string | null): conversationId is string {+ return (+ !!conversationId &&+ conversationId !== Constants.NEW_CONVO &&+ conversationId !== Constants.PENDING_CONVO+ );+}++export function getMessagesConversationId(messages: TMessage[]): string | undefined {+ for (let i = messages.length - 1; i >= 0; i--) {+ const conversationId = messages[i]?.conversationId;+ if (isConcreteConversationId(conversationId)) {+ return conversationId;+ }+ }+}++export function getMessageCacheIds({+ queryParam,+ conversationId,+ messages,+}: MessageCacheIdsParams): string[] {+ const ids = [queryParam];+ const messageConversationId = getMessagesConversationId(messages);++ if (queryParam === Constants.NEW_CONVO && isConcreteConversationId(conversationId)) {+ ids.push(conversationId);+ }++ if (isConcreteConversationId(messageConversationId) && !ids.includes(messageConversationId)) {+ ids.push(messageConversationId);+ }++ return ids;+}diff --git a/packages/chat/src/react/chat/helpers.ts b/packages/chat/src/react/chat/helpers.tsnew file mode 100644index 0000000000..94a47b7c61--- /dev/null+++ b/packages/chat/src/react/chat/helpers.ts@@ -0,0 +1,239 @@+import { useCallback, useMemo, useRef, useState } from 'react';+import { useAtom, useSetAtom } from 'jotai';+import type { TMessage } from 'librechat-data-provider';+import type { MouseEvent } from 'react';+import type { ChatContract } from './contract';+import { isSubmittingFamily, submissionByIndex, useIsSubmitting } from '../submission';+import { presetFamily, filesFamily, optionSettingsFamily } from '../pane';+import { abortScrollFamily } from '../generation';+import { getMessageCacheIds } from './cache';+import { useStopGenerating } from './stop';+import { useChatHost } from './host';++/**+ * Builds a pane's chat contract from the app the host supplies: its pane store, message cache,+ * turn builder and transport. `paramId` is the route's conversation id, which keys the messages+ * the contract reads ahead of the pane's conversation while navigation settles.+ */+export default function useChatHelpers(index = 0, paramId?: string): ChatContract {+ const host = useChatHost();+ const [files, setFiles] = useAtom(filesFamily(index));+ const [filesLoading, setFilesLoading] = useState(false);++ const cache = host.useMessageCache();+ const newConversation = host.useNewConversation(index);+ const { conversation, setConversation } = host.usePaneConversation(index);+ const conversationId = conversation?.conversationId;++ /** Use paramId (from URL) as primary source for query key - this must match what ChatView uses+ Falling back to conversationId (Recoil) only if paramId is not available */+ const queryParam = paramId === 'new' ? paramId : (paramId ?? conversationId ?? '');++ const isSubmitting = useIsSubmitting(index);+ const setIsSubmitting = useSetAtom(isSubmittingFamily(index));+ const latestMessage = host.useLatestMessage(index, queryParam);++ const latestMessageId = host.useLatestMessageId(index, queryParam) ?? undefined;+ const latestMessageDepth = latestMessage?.depth;+ const latestMessageRef = useRef(latestMessage);+ latestMessageRef.current = latestMessage;++ const setSiblingIdx = host.useSetSiblingIdx(latestMessage?.parentMessageId ?? null);+ /** The setter is rebound whenever the tail's parent changes (every turn); the+ * ref keeps `handleContinue` referentially stable so rows do not re-render. */+ const setSiblingIdxRef = useRef(setSiblingIdx);+ setSiblingIdxRef.current = setSiblingIdx;++ const setMessages = useCallback(+ (messages: TMessage[]) => {+ const messageCacheIds = getMessageCacheIds({ queryParam, conversationId, messages });+ for (const messageCacheId of messageCacheIds) {+ cache.write(messageCacheId, messages);+ }+ },+ [queryParam, cache, conversationId],+ );++ const subscribeMessages = useCallback(+ (onChange: () => void) => cache.subscribe(queryParam, onChange),+ [cache, queryParam],+ );+ const getMessagesRevision = useCallback(() => cache.revision(queryParam), [cache, queryParam]);++ const getMessages = useCallback(+ (targetConversationId?: string | null) => cache.read(targetConversationId ?? queryParam),+ [queryParam, cache],+ );++ const setSubmission = useSetAtom(submissionByIndex(index));++ const { ask: _ask, regenerate: _regenerate } = host.useTurns({+ index,+ files,+ setFiles,+ getMessages,+ setMessages,+ isSubmitting,+ conversation,+ latestMessage,+ setSubmission,+ setConversation,+ });++ const askRef = useRef(_ask);+ askRef.current = _ask;+ const ask: typeof _ask = useCallback((...args) => askRef.current(...args), []);++ const regenerateRef = useRef(_regenerate);+ regenerateRef.current = _regenerate;+ const regenerate: typeof _regenerate = useCallback(+ (...args) => regenerateRef.current(...args),+ [],+ );++ const continueGeneration = useCallback(() => {+ const currentLatest = latestMessageRef.current;+ if (!currentLatest) {+ console.error('Failed to regenerate the message: latestMessage not found.');+ return;+ }++ const messages = getMessages();++ const parentMessage = messages?.find(+ (element) => element.messageId == currentLatest.parentMessageId,+ );++ if (parentMessage && parentMessage.isCreatedByUser) {+ ask(+ { ...parentMessage },+ {+ isContinued: true,+ isRegenerate: true,+ isEdited: true,+ overrideManualSkills: parentMessage.manualSkills,+ overrideQuotes: parentMessage.quotes,+ overrideReasoning: parentMessage.reasoningOverride ?? null,+ },+ );+ } else {+ console.error(+ 'Failed to regenerate the message: parentMessage not found, or not created by user.',+ );+ }+ }, [getMessages, ask]);++ const stopGenerating = useStopGenerating(index, conversation);++ const handleStopGenerating = useCallback(+ (e: MouseEvent<HTMLButtonElement>) => {+ e.preventDefault();+ stopGenerating();+ },+ [stopGenerating],+ );++ const handleRegenerate = useCallback(+ (e: MouseEvent<HTMLButtonElement>) => {+ e.preventDefault();+ const parentMessageId = latestMessageRef.current?.parentMessageId ?? '';+ if (!parentMessageId) {+ console.error('Failed to regenerate the message: parentMessageId not found.');+ return;+ }+ regenerate({ parentMessageId });+ },+ [regenerate],+ );++ const handleContinue = useCallback(+ (e: MouseEvent<HTMLButtonElement>) => {+ e.preventDefault();+ continueGeneration();+ setSiblingIdxRef.current(0);+ },+ [continueGeneration],+ );++ const [preset, setPreset] = useAtom(presetFamily(index));+ const [abortScroll, setAbortScroll] = useAtom(abortScrollFamily(index));+ const [optionSettings, setOptionSettings] = useAtom(optionSettingsFamily(index));++ /** Read once per chat rather than per message row: message rows never unmount, so a+ * per-row settings read would accumulate for the length of the conversation. */+ const feedbackEnabled = host.useFeedbackEnabled();+ const { getMappingOptions, useLiveAttachments } = host;++ return useMemo(+ (): ChatContract => ({+ newConversation,+ conversation,+ setConversation,+ isSubmitting,+ setIsSubmitting,+ getMessages,+ messagesKey: queryParam,+ setMessages,+ subscribeMessages,+ getMessagesRevision,+ setSiblingIdx,+ latestMessageId,+ latestMessageDepth,+ useLiveAttachments,+ ask,+ index,+ regenerate,+ stopGenerating,+ handleStopGenerating,+ handleRegenerate,+ handleContinue,+ abortScroll,+ setAbortScroll,+ preset,+ setPreset,+ optionSettings,+ setOptionSettings,+ files,+ setFiles,+ filesLoading,+ setFilesLoading,+ feedbackEnabled,+ getMappingOptions,+ }),+ [+ newConversation,+ conversation,+ setConversation,+ isSubmitting,+ setIsSubmitting,+ getMessages,+ queryParam,+ setMessages,+ subscribeMessages,+ getMessagesRevision,+ setSiblingIdx,+ latestMessageId,+ latestMessageDepth,+ ask,+ index,+ regenerate,+ stopGenerating,+ handleStopGenerating,+ handleRegenerate,+ handleContinue,+ abortScroll,+ setAbortScroll,+ preset,+ setPreset,+ optionSettings,+ setOptionSettings,+ files,+ setFiles,+ filesLoading,+ setFilesLoading,+ feedbackEnabled,+ getMappingOptions,+ useLiveAttachments,+ ],+ );+}diff --git a/packages/chat/src/react/chat/host.tsx b/packages/chat/src/react/chat/host.tsxnew file mode 100644index 0000000000..ba9c3f7afb--- /dev/null+++ b/packages/chat/src/react/chat/host.tsx@@ -0,0 +1,125 @@+import { createContext, useContext } from 'react';+import type {+ TMessage,+ TSubmission,+ TAttachment,+ TConversation,+ TPendingSteer,+ UIMappingOptions,+} from 'librechat-data-provider';+import type { Dispatch, ReactNode, SetStateAction } from 'react';+import type { ChatContract } from './contract';+import type { ExtendedFile } from '../../core';++export interface AbortStreamParams {+ /** The stream ID to abort (if known) */+ streamId?: string;+ /** The conversation ID to abort (backend will look up the job) */+ conversationId?: string;+ /** Exact generation epoch returned by start/status. Prevents a stale tab+ * from aborting a newer turn that reused the conversation-scoped stream id. */+ generationCreatedAt?: number;+}++export interface AbortStreamResponse {+ generationProtocolVersion?: number;+ success: boolean;+ aborted?: string;+ /** Stop lost to an ordinary terminal transition; no abort FINAL was emitted. */+ settled?: boolean;+ code?: 'RUN_ALREADY_SETTLED' | string;+ streamId?: string;+ terminalStatus?: 'complete' | 'error' | 'aborted';+ error?: string;+ /** The worker stopped, but its terminal state could not be made durable.+ * The client must not infer a safe queue-drain boundary from this ACK. */+ persistenceFailed?: boolean;+ /** Steers that never reached an injection boundary; restored as queued chips. */+ pendingSteers?: TPendingSteer[];+}++/** What the host's turn builder needs to submit and regenerate turns for one pane. */+export type ChatTurnsParams = {+ index: number;+ files: Map<string, ExtendedFile>;+ setFiles: Dispatch<SetStateAction<Map<string, ExtendedFile>>>;+ getMessages: ChatContract['getMessages'];+ setMessages: ChatContract['setMessages'];+ isSubmitting: boolean;+ conversation: TConversation | null;+ latestMessage: TMessage | null;+ setSubmission: Dispatch<SetStateAction<TSubmission | null>>;+ setConversation: Dispatch<SetStateAction<TConversation | null>>;+};++/** The conversation a pane shows, and the setter that replaces or updates it. */+export type ChatPaneConversation = {+ conversation: TConversation | null;+ setConversation: Dispatch<SetStateAction<TConversation | null>>;+};++/** The host's message cache, keyed by conversation id (or the pane's route key). */+export type ChatMessageCache = {+ read: (key: string) => TMessage[] | undefined;+ write: (key: string, messages: TMessage[]) => void;+ /** Subscribes to writes of one key; see {@link ChatContract.subscribeMessages}. */+ subscribe: (key: string, onChange: () => void) => () => void;+ /** How many times one key has been written; see {@link ChatContract.getMessagesRevision}. */+ revision: (key: string) => number;+ /** Marks a conversation's messages stale and refetches them, mounted or not. */+ refetchMessages: (conversationId: string) => void;+ /** Marks the active-jobs list stale. */+ refetchActiveJobs: () => void;+ /** Marks a conversation's stream status stale. */+ refetchStreamStatus: (conversationId: string) => void;+};++/**+ * What `useChatHelpers` needs from the app that hosts it. Members named `use*` are hooks, called+ * unconditionally by the chat hook, so the host can back each one with its own router, query+ * cache or store. A host must stay the same object for the life of the tree it wraps.+ */+export interface ChatHost {+ /** The pane's conversation in the app's pane store; mounting it registers the pane. */+ usePaneConversation(index: number): ChatPaneConversation;+ /** Starts a fresh conversation in a pane. */+ useNewConversation(index: number): ChatContract['newConversation'];+ /** Builds and submits turns: `ask` and `regenerate`. */+ useTurns(params: ChatTurnsParams): Pick<ChatContract, 'ask' | 'regenerate'>;+ /** The tail of the branch on screen for the pane, read from the messages cached under `key`. */+ useLatestMessage(index: number, key: string): TMessage | null;+ /** The id of {@link ChatHost.useLatestMessage}, subscribed on its own. */+ useLatestMessageId(index: number, key: string): string | null;+ /** Selects the visible sibling under a parent message. */+ useSetSiblingIdx(parentMessageId: string | null): (update: SetStateAction<number>) => void;+ /** Stops a resumable generation. */+ useAbortStream(): (params: AbortStreamParams) => Promise<AbortStreamResponse>;+ useMessageCache(): ChatMessageCache;+ /** Attachments delivered by message id ahead of the message cache. Stable across renders. */+ useLiveAttachments(): Record<string, TAttachment[] | undefined>;+ /** Whether message feedback controls are on. */+ useFeedbackEnabled(): boolean;+ /** The app's tool outcome rules for viewing one message; see {@link ChatContract}. */+ getMappingOptions(live: TAttachment[] | undefined): UIMappingOptions;+}++const ChatHostContext = createContext<ChatHost | null>(null);++/** Supplies the host `useChatHelpers` reads from. */+export function ChatHostProvider({+ host,+ children,+}: {+ host: ChatHost;+ children?: ReactNode;+}): ReactNode {+ return <ChatHostContext.Provider value={host}>{children}</ChatHostContext.Provider>;+}++export function useChatHost(): ChatHost {+ const host = useContext(ChatHostContext);+ if (host == null) {+ throw new Error('The chat hooks need a ChatHostProvider above them.');+ }+ return host;+}diff --git a/packages/chat/src/react/chat/index.ts b/packages/chat/src/react/chat/index.tsindex 3980746748..ad0593b15d 100644--- a/packages/chat/src/react/chat/index.ts+++ b/packages/chat/src/react/chat/index.ts@@ -1,4 +1,17 @@export { useChat } from './chat';+export { ChatProvider } from './provider';+export { default as useChatHelpers } from './helpers';+export { useAbortCleanup } from './abort';+export { getMessageCacheIds, getMessagesConversationId } from './cache';+export { ChatHostProvider, useChatHost } from './host';+export type {+ ChatHost,+ ChatTurnsParams,+ ChatMessageCache,+ AbortStreamParams,+ AbortStreamResponse,+ ChatPaneConversation,+} from './host';export { useChatActions } from './actions';export { getChatStatus, isEmptyContentPart } from './status';export { ChatContext, useChatContext } from './context';diff --git a/packages/chat/src/react/chat/provider.tsx b/packages/chat/src/react/chat/provider.tsxnew file mode 100644index 0000000000..2c55ca6afb--- /dev/null+++ b/packages/chat/src/react/chat/provider.tsx@@ -0,0 +1,23 @@+import type { ReactNode } from 'react';+import { ChatContext } from './context';+import useChatHelpers from './helpers';++/**+ * Builds a pane's chat contract and serves it to `useChat`, `useChatActions` and+ * `useChatContext` below. A host renders this instead of calling `useChatHelpers` itself, so+ * components reach the chat only through the facade and its context.+ */+export function ChatProvider({+ index = 0,+ conversationId,+ children,+}: {+ /** The pane: `0` is the root pane, `1` the added (multi-convo) pane. */+ index?: number;+ /** The route's conversation id, which can run ahead of the pane's conversation. */+ conversationId?: string;+ children: ReactNode;+}): ReactNode {+ const chat = useChatHelpers(index, conversationId);+ return <ChatContext.Provider value={chat}>{children}</ChatContext.Provider>;+}diff --git a/packages/chat/src/react/chat/stop.ts b/packages/chat/src/react/chat/stop.tsnew file mode 100644index 0000000000..3be7634ca7--- /dev/null+++ b/packages/chat/src/react/chat/stop.ts@@ -0,0 +1,230 @@+import { useCallback } from 'react';+import { useStore, useAtomValue } from 'jotai';+import { Constants, isAssistantsEndpoint } from 'librechat-data-provider';+import type { TConversation } from 'librechat-data-provider';+import type { ChatContract } from './contract';+import {+ activeGenerationCreatedAtByConvoId,+ activeGenerationProtocolVersionByConvoId,+} from '../steer/atoms';+import { stopRequestedByConvoId, drainAfterAbortByIndex, runEndByIndex } from '../steer/queue';+import { resolveAbortSteerTarget, supportsGenerationProtocolV2 } from '../../core';+import useSteerConvert from '../steering/useSteerConvert';+import { useClearSubmissions } from '../submission';+import { useAbortCleanup } from './abort';+import { useChatHost } from './host';++/**+ * Stops the pane's generation. A resumable run is aborted through the host's transport, and the+ * stream's own terminal event cleans up the view; an Assistants run, which has its own abort+ * path in the stream handlers, only clears the pane's submissions.+ */+export function useStopGenerating(+ index: number,+ conversation: TConversation | null,+): ChatContract['stopGenerating'] {+ const { conversationId, endpoint, endpointType } = conversation ?? {};+ const host = useChatHost();+ const abortStream = host.useAbortStream();+ const cache = host.useMessageCache();+ const clearAllSubmissions = useClearSubmissions();+ const convertSteersToQueued = useSteerConvert();+ const { captureSubmission, clearSubmissionsUnlessReplaced } = useAbortCleanup(index);+ const activeGenerationCreatedAt = useAtomValue(+ activeGenerationCreatedAtByConvoId(conversationId ?? Constants.NEW_CONVO),+ );+ const activeGenerationProtocolVersion = useAtomValue(+ activeGenerationProtocolVersionByConvoId(conversationId ?? Constants.NEW_CONVO),+ );++ /** Async abort responses can settle after this pane has moved to another+ * conversation and armed its own interrupt. Clear only the intent owned by+ * the request that produced the response. */+ const queueStore = useStore();+ const clearInterruptDrain = useCallback(+ (convoId: string, generationCreatedAt: number) => {+ const armed = queueStore.get(drainAfterAbortByIndex(index));+ if (+ armed !== false &&+ armed.conversationId === convoId &&+ armed.generationCreatedAt === generationCreatedAt+ ) {+ queueStore.set(drainAfterAbortByIndex(index), false);+ }+ },+ [index, queueStore],+ );++ /** A missing job cannot deliver FINAL, so release its armed interrupt queue. */+ const signalInterruptDrain = useCallback(+ (convoId: string, generationCreatedAt: number, armedConversationId = convoId) => {+ const armed = queueStore.get(drainAfterAbortByIndex(index));+ const runEnd = queueStore.get(runEndByIndex(index));+ const matchesArm =+ armed !== false &&+ armed.conversationId === armedConversationId &&+ armed.generationCreatedAt === generationCreatedAt;+ const alreadySignaled =+ runEnd?.conversationId === convoId && runEnd.generationCreatedAt === generationCreatedAt;+ if (!matchesArm || alreadySignaled) {+ return;+ }+ queueStore.set(runEndByIndex(index), {+ conversationId: convoId,+ outcome: 'aborted',+ endedAt: Date.now(),+ generationCreatedAt,+ });+ },+ [index, queueStore],+ );++ /**+ * Stop generation - for non-assistants endpoints, calls abort endpoint first.+ * The abort endpoint will cause the backend to emit a `done` event with `aborted: true`,+ * which will be handled by the SSE event handler to clean up UI.+ * Assistants endpoint has its own abort mechanism via useEventHandlers.abortConversation.+ */+ return useCallback(async () => {+ const actualEndpoint = endpointType ?? endpoint;+ const isAssistants = isAssistantsEndpoint(actualEndpoint);+ console.log('[useChatHelpers] stopGenerating called', {+ conversationId,+ endpoint,+ endpointType,+ actualEndpoint,+ isAssistants,+ });++ // For non-assistants endpoints (using resumable streams), call abort endpoint first+ if (conversationId && !isAssistants) {+ /** Stop is a generation-scoped mutation. `isSubmitting` becomes true+ * before the start POST returns, so a stale/missing epoch must make this+ * path inert instead of aborting whichever conversation job is current. */+ if (activeGenerationCreatedAt == null) {+ 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;+ // the fallback clear below must not tear down that new run.+ const submissionAtAbort = captureSubmission();+ const stoppedRun = { generationCreatedAt: activeGenerationCreatedAt };+ const stopFamily = stopRequestedByConvoId(conversationId);+ queueStore.set(stopFamily, stoppedRun);+ try {+ console.log('[useChatHelpers] Calling abort mutation for:', conversationId);+ const response = await abortStream({+ conversationId,+ ...(activeGenerationCreatedAt != null && {+ generationCreatedAt: activeGenerationCreatedAt,+ }),+ });+ console.log('[useChatHelpers] Abort mutation succeeded');+ const canUseV2AbortResponse =+ activeGenerationProtocolVersion === 2 && supportsGenerationProtocolV2(response);+ /** Conversation-scoped active-job ids cannot be removed optimistically:+ * a newer generation may have started while this response was in flight.+ * Refetch instead so that replacement remains represented. */+ cache.refetchActiveJobs();+ if (canUseV2AbortResponse && response?.settled === true) {+ /** Natural completion/error won the terminal CAS, so this request did+ * not emit an abort FINAL and must not release the abort-drain queue.+ * The winning terminal event/status owns reconciliation. A run that+ * completed or failed was not stopped, so its persisted outcome may+ * still drain; one another Stop already aborted stays stopped. */+ clearInterruptDrain(conversationId, activeGenerationCreatedAt);+ if (response.terminalStatus !== 'aborted' && queueStore.get(stopFamily) === stoppedRun) {+ queueStore.set(stopFamily, null);+ }+ cache.refetchMessages(conversationId);+ cache.refetchStreamStatus(conversationId);+ return;+ }+ if (canUseV2AbortResponse && response?.persistenceFailed === true) {+ /** The process was interrupted, but neither a durable terminal+ * payload nor a trustworthy leftover-steer set exists. Keep the SSE+ * submission attached for its reconciliation frame/status retry and+ * do not consume the armed interrupt queue against unknown history. */+ clearInterruptDrain(conversationId, activeGenerationCreatedAt);+ cache.refetchMessages(conversationId);+ cache.refetchStreamStatus(conversationId);+ return;+ }+ // 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.+ const { chipConvoId, claimConvoId } = resolveAbortSteerTarget({+ conversationId,+ resolvedId: response?.aborted,+ });+ /** Keep the submission attached until FINAL/status reconciles history.+ * Clearing on the ACK can close SSE during terminal authorization and+ * strand the preliminary response as an unsaved follow-up parent.+ * Only terminal reconciliation may release the interrupt queue. */+ // Restore uninjected steers from the ACK as well as FINAL. Conversion+ // dedupes by steer id; `claimParked` reconciles the replayable copy.+ if (Array.isArray(response?.pendingSteers)) {+ convertSteersToQueued(chipConvoId, response.pendingSteers, {+ claimParked: true,+ claimConversationId: claimConvoId,+ generationProtocolVersion: canUseV2AbortResponse ? 2 : 1,+ });+ }+ } catch (error) {+ console.error('[useChatHelpers] Abort failed:', error);+ const errorData = (+ error as {+ response?: { data?: { code?: string; generationProtocolVersion?: unknown } };+ } | null+ )?.response?.data;+ const code = errorData?.code;+ if (+ code === 'RUN_REPLACED' &&+ activeGenerationProtocolVersion === 2 &&+ supportsGenerationProtocolV2(errorData)+ ) {+ // This tab targeted an older generation. Do not emit an abort run-end+ // or consume its armed queue against the newer live owner.+ cache.refetchActiveJobs();+ clearSubmissionsUnlessReplaced(submissionAtAbort);+ return;+ }+ const status = (error as { response?: { status?: number } } | null | undefined)?.response+ ?.status;+ if (status === 404) {+ // A missing job cannot still consume the interrupt follow-up. Release+ // the armed queue even if its ordinary terminal frame raced cleanup.+ signalInterruptDrain(conversationId, activeGenerationCreatedAt);+ clearSubmissionsUnlessReplaced(submissionAtAbort);+ return;+ }+ /** A timeout/5xx is an unknown mutation outcome: the job may still be+ * live, or the abort may have committed without its response. Keep the+ * attachment and armed queue parked until SSE/status proves a terminal+ * boundary; firing it now could replace a still-running generation. */+ cache.refetchActiveJobs();+ cache.refetchStreamStatus(conversationId);+ }+ } else {+ // For assistants endpoints, just clear submissions (existing behavior)+ console.log('[useChatHelpers] Assistants endpoint, just clearing submissions');+ clearAllSubmissions();+ }+ }, [+ conversationId,+ endpoint,+ endpointType,+ queueStore,+ activeGenerationCreatedAt,+ activeGenerationProtocolVersion,+ abortStream,+ captureSubmission,+ convertSteersToQueued,+ signalInterruptDrain,+ clearSubmissionsUnlessReplaced,+ clearAllSubmissions,+ cache,+ clearInterruptDrain,+ ]);+}