📦 refactor: Move the useChat Facade and ChatContext into the Chat Package (#17445)

* refactor: Move the useChat Facade and ChatContext into @librechat/chat/react

The facade, ChatContext, the chat contract types and the resume request atom now
live in the chat package. The message cache subscription and the app's tool
outcome rules reach the facade through the contract, and useChatHelpers reads
its pane conversation through ChatSettings instead of the app store.

* fix: Key Cached Message Views on the Host's Tool Outcome Rules
This commit is contained in:
Marco Beretta 2026-10-26 22:46:55 +01:00 • committed by GitHub
parent 19ba23e057
commit c1dfd6bc0f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
35 changed files with 1110 additions and 848 deletions

View file

@ -1,11 +1 @@
import { createContext, useContext } from 'react';
import type { ChatContract } from '~/hooks/Chat/contract';
export const ChatContext = createContext<ChatContract | null>(null);
export const useChatContext = () => {
const ctx = useContext(ChatContext);
if (!ctx) {
throw new Error('useChatContext must be used within a ChatContext.Provider');
}
return ctx;
};
export { ChatContext, useChatContext } from '@librechat/chat/react';

View file

@ -1,5 +1,12 @@
import { createContext, useContext } from 'react';
import type { ChatSettings } from '~/hooks/Chat/contract';
import { useState, createContext, useContext } from 'react';
import type { TConversation } from 'librechat-data-provider';
import type { ChatSettings, PaneConversationState } from '~/hooks/Chat/contract';
/** A pane conversation held by the calling chat alone, for renders with no host pane store. */
function useLocalPaneConversation(): PaneConversationState {
const [conversation, setConversation] = useState<TConversation | null>(null);
return { conversation, setConversation };
}
/** Stock values, used when no host supplies settings (isolated renders and tests). */
export const defaultChatSettings: ChatSettings = {
@ -15,6 +22,7 @@ export const defaultChatSettings: ChatSettings = {
auth: {},
getPaneConversations: () => [],
usePaneConversation: () => null,
usePaneConversationState: useLocalPaneConversation,
};
export const ChatSettingsContext = createContext<ChatSettings>(defaultChatSettings);

View file

@ -1,6 +1,12 @@
import { RefObject } from 'react';
import { isEphemeralAgentId } from 'librechat-data-provider';
import type { PaneOptionSettings } from '@librechat/chat/react';
import type {
TOptions,
TAskProps,
TAskFunction,
PaneOptionSettings,
NewConversationParams,
} from '@librechat/chat/react';
import type { UseMutationResult } from '@tanstack/react-query';
import type { ExtendedFile } from '@librechat/chat';
import type * as t from 'librechat-data-provider';
@ -260,74 +266,6 @@ export type TGenButtonProps = {
onClick: TOnClick;
};
export type TAskProps = {
text: string;
overrideConvoId?: string;
overrideUserMessageId?: string;
parentMessageId?: string | null;
conversationId?: string | null;
messageId?: string | null;
clientTimestamp?: string;
};
export type TOptions = {
editedMessageId?: string | null;
editedContent?: t.TEditedContent;
isRegenerate?: boolean;
isContinued?: boolean;
isEdited?: boolean;
/**
* Manual context compaction: a summarize-only turn hung off the branch's
* leaf (`messageId`). Shaped like a regenerate on the client — no new user
* bubble, the response placeholder parents onto the leaf — and sent with
* `compact: true` so the server runs the graph summarize-only.
*/
compact?: boolean;
overrideMessages?: t.TMessage[];
/**
* Authoritative attachment list for this submission: a rerun replays the edited
* message's stored files, and an auto-drained queued message replays the ones taken
* out of the composer when it was queued. Authoritative even when empty, so a drain
* never vacuums up attachments the user staged for their next send.
*/
overrideFiles?: t.TMessage['files'];
/**
* Assistant message being regenerated. Used to derive the optimistic response
* id for non-tail regenerations without accidentally keying the stream to the
* conversation tail.
*/
targetResponseMessageId?: string | null;
/**
* Carry forward a user message's manually-invoked skills when the caller
* is resubmitting / regenerating that same message — the compose-time
* atom has already been drained on the original submit, so without this
* the second turn would run without any manual priming even though the
* pills are still visible on the user bubble.
*/
overrideManualSkills?: string[];
/**
* Carry forward a user message's quoted excerpts when resubmitting /
* regenerating that same message — the compose-time atom is drained on the
* original submit, so without this the second turn would lose the quoted
* context even though the references still show on the user bubble.
*/
overrideQuotes?: string[];
/** Request-scoped reasoning selection for this exact submission. */
overrideReasoning?: t.TReasoningOverride | null;
/** Added conversation for multi-convo feature - sent to server as part of submission payload */
addedConvo?: t.TConversation;
/** Reuse a durable submission identity (terminal steer recovery). */
overrideClientRequestId?: string;
/** Exact parked steer source for a recovery attempt. */
overrideRecoverySteerId?: string;
/** Exact terminal generation observed before an automatic queued start. */
overrideExpectedPredecessorCreatedAt?: number;
/** Client-only exact queue position restored if admission is rejected. */
overrideQueuedMessageOrigin?: unknown;
};
export type TAskFunction = (props: TAskProps, options?: TOptions) => false | void;
/**
* Stable context object passed from non-memo'd wrapper components (Message, MessageContent)
* to memo'd inner components (MessageRender, ContentRender) via props.
@ -510,7 +448,7 @@ export type PromptOption = MentionOption & {
export type TOptionSettings = PaneOptionSettings;
export type { ExtendedFile };
export type { ExtendedFile, TOptions, TAskProps, TAskFunction, NewConversationParams };
export type TLoginLayoutContext = {
startupConfig: t.TStartupConfig | null;
@ -522,15 +460,6 @@ export type TLoginLayoutContext = {
setHeaderText: React.Dispatch<React.SetStateAction<string>>;
};
export type NewConversationParams = {
template?: Partial<t.TConversation>;
preset?: Partial<t.TPreset>;
modelsData?: t.TModelsConfig;
buildDefault?: boolean;
keepAddedConvos?: boolean;
disableParams?: boolean;
};
export type ConvoGenerator = (params: NewConversationParams) => void | t.TConversation;
export type TBaseResData = {

View file

@ -80,7 +80,10 @@ function Harness({
messagesKey: 'new',
latestMessageId: undefined,
latestMessageDepth: undefined,
subscribeMessages: () => () => undefined,
getMessagesRevision: () => 0,
useLiveAttachments: () => ({}),
getMappingOptions: () => ({}),
feedbackEnabled: false,
setMessages: () => undefined,
ask: onAsk,

View file

@ -358,7 +358,10 @@ describe('standard conversation content', () => {
setSiblingIdx: () => undefined,
latestMessageId: undefined,
latestMessageDepth: undefined,
subscribeMessages: () => () => undefined,
getMessagesRevision: () => 0,
useLiveAttachments: () => ({}),
getMappingOptions: () => ({}),
ask: mockParentAsk,
regenerate: () => undefined,
isSubmitting: false,

View file

@ -48,6 +48,10 @@ jest.mock('~/hooks/Chat/useChatHelpers', () => ({
}),
}));
jest.mock('~/hooks/Chat/outcomes', () => ({
getMappingOptions: () => ({}),
}));
jest.mock('~/hooks/SSE', () => ({
useAdaptiveSSE: jest.fn(),
useResumeOnLoad: jest.fn(),

View file

@ -19,10 +19,15 @@ import {
} 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';
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 = () => ({});
const mockAbortMutateAsync = jest.fn();
const mockConvertSteersToQueued = jest.fn();
@ -56,6 +61,8 @@ jest.mock('@librechat/chat/react', () => ({
}));
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) =>
@ -237,12 +244,14 @@ describe('useChatHelpers stopGenerating (abort steer targeting)', () => {
}}
>
<RunEndProbe />
{children}
<ChatSettingsContext.Provider value={paneSettings}>
{children}
</ChatSettingsContext.Provider>
</RecoilRoot>
</QueryClientProvider>
);
return {
...renderHook(() => useChatHelpers(INDEX), { wrapper }),
...renderHook(() => useChatHelpers(INDEX, undefined, noToolOutcomes), { wrapper }),
stoppedSubmission,
setDrainAfterAbort: (value: DrainAfterAbort | false) => setDrainAfterAbort?.(value),
};

View file

@ -8,10 +8,14 @@ import type { MutableSnapshot } from 'recoil';
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 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 }),
@ -40,9 +44,12 @@ jest.mock('@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 };
function createWrapper(
initializeState?: (snapshot: MutableSnapshot) => void,
settings: ChatSettings = defaultChatSettings,
settings: ChatSettings = paneSettings,
) {
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
return function Wrapper({ children }: { children: React.ReactNode }) {
@ -60,7 +67,9 @@ function renderChatHelpers(
paramId?: string,
initializeState?: (snapshot: MutableSnapshot) => void,
) {
return renderHook(() => useChatHelpers(0, paramId), { wrapper: createWrapper(initializeState) });
return renderHook(() => useChatHelpers(0, paramId, noToolOutcomes), {
wrapper: createWrapper(initializeState),
});
}
describe('useChatHelpers contract members', () => {
@ -102,7 +111,7 @@ describe('substitute host config', () => {
const wrapper = createWrapper(undefined, hostSettings);
it('reaches the chat helpers', () => {
const { result } = renderHook(() => useChatHelpers(0), { wrapper });
const { result } = renderHook(() => useChatHelpers(0, undefined, noToolOutcomes), { wrapper });
expect(result.current.feedbackEnabled).toBe(true);
});
@ -124,7 +133,7 @@ describe('substitute host config', () => {
const conversation = { endpoint: 'openAI', spec: 'long' } as TConversation;
const { result } = renderHook(
() => ({
helpers: useChatHelpers(0),
helpers: useChatHelpers(0, undefined, noToolOutcomes),
temporary: useTemporaryChat(),
limits: useTokenLimits(conversation),
}),

View file

@ -1,14 +1,14 @@
import React from 'react';
import { act, render, renderHook } from '@testing-library/react';
import { QueryKeys, Constants, ContentTypes } from 'librechat-data-provider';
import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';
import { useChat, ChatContext, useChatActions, resumeRequestsAtom } from '@librechat/chat/react';
import { QueryClient, QueryClientProvider, useQuery, useQueryClient } from '@tanstack/react-query';
import type { TConversation, TMessage, TMessageContentParts } from 'librechat-data-provider';
import type { ChatContract } from '../contract';
import type { JotaiStore } from 'test/harness';
import { ChatContext } from '~/Providers/ChatContext';
import { useChat, useChatActions } from '../facade';
import { createMessagesSubscription } from '../cache';
import { IsolatedAtomStore } from 'test/harness';
import { resumeRequestsAtom } from '../resume';
import { getMappingOptions } from '../outcomes';
const userMessage: TMessage = {
messageId: 'user-1',
@ -50,7 +50,10 @@ const createContract = (overrides: Partial<ChatContract> = {}): ChatContract =>
setSiblingIdx: noop,
latestMessageId: 'user-1',
latestMessageDepth: 0,
subscribeMessages: () => () => undefined,
getMessagesRevision: () => 0,
useLiveAttachments: () => noLiveAttachments,
getMappingOptions,
ask: jest.fn(),
regenerate: jest.fn(),
isSubmitting: false,
@ -70,6 +73,16 @@ 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],
);
return <ChatContext.Provider value={value}>{children}</ChatContext.Provider>;
}
/** The facade delivers cache writes on a microtask, outside the render that caused them. */
const flushCacheNotify = () => Promise.resolve();
@ -79,7 +92,7 @@ const renderChat = (initial: ChatContract) => {
const queryClient = new QueryClient();
const wrapper = ({ children }: { children: React.ReactNode }) => (
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={contract}>{children}</ChatContext.Provider>
<CachedChat contract={contract}>{children}</CachedChat>
</QueryClientProvider>
);
const view = renderHook(() => useChat(), { wrapper });
@ -295,7 +308,7 @@ describe('useChat', () => {
});
const wrapper = ({ children }: { children: React.ReactNode }) => (
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={contract}>{children}</ChatContext.Provider>
<CachedChat contract={contract}>{children}</CachedChat>
</QueryClientProvider>
);
const { result } = renderHook(() => useChat(), { wrapper });
@ -345,18 +358,18 @@ describe('useChat', () => {
};
const view = render(
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={contract}>
<CachedChat contract={contract}>
<Probe withReader={false} />
</ChatContext.Provider>
</CachedChat>
</QueryClientProvider>,
);
await act(async () => {
view.rerender(
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={contract}>
<CachedChat contract={contract}>
<Probe withReader />
</ChatContext.Provider>
</CachedChat>
</QueryClientProvider>,
);
await flushCacheNotify();
@ -379,7 +392,7 @@ describe('useChat', () => {
});
const wrapper = ({ children }: { children: React.ReactNode }) => (
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={contract}>{children}</ChatContext.Provider>
<CachedChat contract={contract}>{children}</CachedChat>
</QueryClientProvider>
);
const { result } = renderHook(() => useChat(), { wrapper });
@ -747,7 +760,7 @@ describe('useChat', () => {
store.set(resumeRequestsAtom, new Set(['convo-2']));
}}
>
<ChatContext.Provider value={contract}>{children}</ChatContext.Provider>
<CachedChat contract={contract}>{children}</CachedChat>
</IsolatedAtomStore>
</QueryClientProvider>
),
@ -808,7 +821,7 @@ describe('useChatActions', () => {
let renders = 0;
const wrapper = ({ children }: { children: React.ReactNode }) => (
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={contract}>{children}</ChatContext.Provider>
<CachedChat contract={contract}>{children}</CachedChat>
</QueryClientProvider>
);
const view = renderHook(

View file

@ -6,6 +6,9 @@ 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 = () => ({});
let mockStartupConfig: Partial<TStartupConfig> | undefined;
jest.mock('~/data-provider', () => ({
@ -47,7 +50,7 @@ function renderChatHelpers() {
</RecoilRoot>
</QueryClientProvider>
);
return renderHook(() => useChatHelpers(0), { wrapper });
return renderHook(() => useChatHelpers(0, undefined, noToolOutcomes), { wrapper });
}
describe('useChatHelpers feedbackEnabled', () => {

View file

@ -1,11 +1,11 @@
import React from 'react';
import { MemoryRouter } from 'react-router-dom';
import { renderHook } from '@testing-library/react';
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 { useChatActions } from '../facade';
const mockUseChatHelpers = jest.fn();
const mockUseAdaptiveSSE = jest.fn();
@ -46,7 +46,10 @@ const contract: ChatContract = {
setSiblingIdx: noop,
latestMessageId: undefined,
latestMessageDepth: undefined,
subscribeMessages: () => () => undefined,
getMessagesRevision: () => 0,
useLiveAttachments: () => ({}),
getMappingOptions: () => ({}),
ask: jest.fn(),
regenerate: jest.fn(),
isSubmitting: false,

View file

@ -3,6 +3,7 @@ import { MemoryRouter } from 'react-router-dom';
import { useAtomValue, getDefaultStore } from 'jotai';
import { RecoilRoot, useSetRecoilState } from 'recoil';
import { act, renderHook, waitFor } from '@testing-library/react';
import { useChat, resumeRequestsAtom } from '@librechat/chat/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Tools, QueryKeys, ContentTypes, EModelEndpoint, request } from 'librechat-data-provider';
import {
@ -31,16 +32,15 @@ import type { StreamStatusResponse } from '~/data-provider';
import type { ChatContract } from '~/hooks/Chat/contract';
import type { Transport } from '~/hooks/Chat/contract';
import { ChatSettingsContext, defaultChatSettings } from '~/Providers/ChatSettingsContext';
import { usePaneConversation, usePaneConversationState } from '~/routes/ChatSettings';
import { ChatTransportContext } from '~/Providers/ChatTransportContext';
import { ChatContext, useChatContext } from '~/Providers/ChatContext';
import { startupConfigKey } from '~/data-provider/Endpoints/queries';
import { usePaneConversation } from '~/routes/ChatSettings';
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 { resumeRequestsAtom } from '~/hooks/Chat/resume';
import { SteerHostTestProvider } from 'test/steerHost';
import { useChat } from '~/hooks/Chat/facade';
import useSSE from '~/hooks/SSE/useSSE';
import store from '~/store';
@ -94,6 +94,7 @@ function createFakeTransport(overrides: Partial<Transport> = {}) {
const chatSettings = {
...defaultChatSettings,
usePaneConversation,
usePaneConversationState,
auth: { token: 'test-token', isAuthenticated: true },
};
@ -210,7 +211,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');
const helpers: ChatContract = useChatHelpers(0, 'convo-1', getMappingOptions);
return <ChatContext.Provider value={helpers}>{children}</ChatContext.Provider>;
}
@ -310,7 +311,7 @@ describe('chat transport boundary', () => {
it('stops a resumable generation through the host transport', async () => {
const fake = createFakeTransport();
const { result } = renderHook(() => useChatHelpers(0), {
const { result } = renderHook(() => useChatHelpers(0, undefined, getMappingOptions), {
wrapper: createWrapper(fake.transport, seedRun),
});
@ -328,7 +329,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), {
const { result } = renderHook(() => useChatHelpers(0, undefined, getMappingOptions), {
wrapper: createWrapper(fake.transport, seedRun),
});

View file

@ -1,9 +1,11 @@
import React from 'react';
import { getDefaultStore } from 'jotai';
import { ChatContext } from '@librechat/chat/react';
import { ContentTypes } from 'librechat-data-provider';
import { renderHook, act } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import type { TMessage } from 'librechat-data-provider';
import type { ChatContract } from '../contract';
import useCompactConversation, { compactingConversationAtom } from '../useCompactConversation';
const mockAsk = jest.fn();
@ -16,19 +18,6 @@ let mockContext: {
};
let mockLatestMessage: TMessage | null;
/** The hook reads status and submits through the real `useChat` facade over this contract. */
jest.mock('~/Providers/ChatContext', () => ({
useChatContext: () => ({
...mockContext,
ask: mockAsk,
getMessages: () => mockStoredMessages,
messagesKey: mockContext.conversation?.conversationId ?? '',
setMessages: jest.fn(),
latestMessageId: undefined,
regenerate: jest.fn(),
stopGenerating: jest.fn(),
}),
}));
jest.mock('~/hooks/Messages/useLatestMessage', () => ({
useLatestMessage: () => mockLatestMessage,
}));
@ -53,9 +42,26 @@ const leaf = (overrides: Partial<TMessage> = {}): TMessage =>
...overrides,
}) as TMessage;
/** The hook reads status and submits through the real `useChat` facade over this contract. */
const getContract = () =>
({
...mockContext,
ask: mockAsk,
getMessages: () => mockStoredMessages,
messagesKey: mockContext.conversation?.conversationId ?? '',
setMessages: jest.fn(),
subscribeMessages: () => () => undefined,
getMessagesRevision: () => 0,
latestMessageId: undefined,
regenerate: jest.fn(),
stopGenerating: jest.fn(),
}) as unknown as ChatContract;
const queryClient = new QueryClient();
const wrapper = ({ children }: { children: React.ReactNode }) => (
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
<QueryClientProvider client={queryClient}>
<ChatContext.Provider value={getContract()}>{children}</ChatContext.Provider>
</QueryClientProvider>
);
describe('useCompactConversation', () => {

View file

@ -1,4 +1,7 @@
import { Constants } from 'librechat-data-provider';
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 = {
@ -42,3 +45,41 @@ export function getMessageCacheIds({
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,
};
}

View file

@ -1,16 +1,14 @@
import type {
TUser,
TPreset,
TMessage,
TModelSpec,
TAttachment,
RetentionMode,
TConversation,
TEphemeralAgent,
ChatTransport,
ChatTransportRequest,
} from 'librechat-data-provider';
import type { SetStateAction, Dispatch, MouseEvent } from 'react';
import type { NewConversationParams } from '@librechat/chat/react';
import type { SetStateAction, Dispatch } from 'react';
import type { PendingSteer } from '@librechat/chat';
import type {
ArmSteerParams,
@ -24,145 +22,20 @@ import type {
AgentQueuedTurnReceipt,
EnqueueAgentQueuedTurnRequest,
} from '~/data-provider';
import type {
NewConversationParams,
TOptionSettings,
ExtendedFile,
TAskFunction,
Artifact,
PtcTrace,
} from '~/common';
import type { MessagesEditing } from '~/Providers/MessagesViewContext';
import type { Artifact, PtcTrace } 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;
/**
* The conversation key `getMessages()` reads when called without one: the route's id, which
* can run ahead of `conversation` while navigation settles, or `''` before the pane has either.
* AI SDK: the chat `id`.
*/
messagesKey: string;
/** 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;
/**
* Attachments delivered by message id while the message cache holds none of them yet: tool
* artifacts streamed mid-run and previews resolved after it. A hook, so only a caller that
* merges them re-renders when one arrives; stable across renders. AI SDK: the data parts a
* stream writes onto its message.
*/
useLiveAttachments: () => Record<string, TAttachment[] | 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 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;
export type {
ChatContract,
RegenerateTarget,
ChatViewContract,
ChatFilesContract,
ChatAbortContract,
ChatMessagesContract,
NewConversationOptions,
ChatSubmissionContract,
ChatConversationContract,
} from '@librechat/chat/react';
/** Public surface of `useAddedResponse`, served through `AddedChatContext`. */
export type AddedChatContract = {
@ -240,6 +113,15 @@ export type ChatSettings = {
/** A hook, stable across renders: the conversation a pane shows, subscribed so the reader
* re-renders when the pane moves to another conversation. `null` before the pane has one. */
usePaneConversation: (index: string | number) => TConversation | null;
/** A hook, stable across renders: a pane's conversation and its setter, for the chat that
* renders into that pane. Mounting it registers the pane with the app's pane list. */
usePaneConversationState: (index: string | number) => PaneConversationState;
};
/** The conversation a chat pane shows, and the setter that replaces or updates it. */
export type PaneConversationState = {
conversation: TConversation | null;
setConversation: Dispatch<SetStateAction<TConversation | null>>;
};
/** One mounted chat pane and the conversation it shows. */

View file

@ -1,541 +0,0 @@
import { useRef, useMemo, useCallback, useSyncExternalStore } from 'react';
import { useStore } from 'jotai';
import { hashQueryKey, useQueryClient } from '@tanstack/react-query';
import {
QueryKeys,
Constants,
ContentTypes,
fromUIMessage,
toUIMessage,
} from 'librechat-data-provider';
import type {
TMessage,
UIMessage,
UITextPart,
TAttachment,
UIMappingOptions,
UIMessageMetadata,
} from 'librechat-data-provider';
import type { QueryCacheNotifyEvent } from '@tanstack/react-query';
import type { TAskProps, TOptions } from '~/common';
import type { ChatContract } from './contract';
import { isMemoryFailureOutput } from '~/components/Chat/Messages/Content/Parts/MemoryCall';
import { getToolMeta } from '~/components/Chat/Messages/Content/outcome';
import { useChatContext } from '~/Providers/ChatContext';
import { mergeAttachments } from '~/utils/attachments';
import { isEmptyContentPart } from '~/utils/messages';
import { resumeRequestsAtom } from './resume';
import { mapAttachments } from '~/utils/map';
/** AI SDK `ChatStatus`. */
export type ChatStatus = 'submitted' | 'streaming' | 'ready' | 'error';
/**
* A user turn in the AI SDK's `sendMessage` shape: its text parts, plus the message it attaches
* under. It goes to the facade's own chat, as AI SDK `useChat` does, so it names no conversation.
* File parts are left out because the turn takes its files from the composer, not the message.
*/
export type SendMessageInput = {
parts: UITextPart[];
metadata?: Partial<Pick<UIMessageMetadata, 'parentMessageId'>>;
};
/**
* Submits a turn. Takes the contract's `ask` arguments, or a user message in the AI SDK shape,
* which is sent as the `ask` call it describes; `{ text }` is already both.
*/
export type SendMessage = (
message: TAskProps | SendMessageInput,
options?: TOptions,
) => false | void;
/**
* The `useChat` surface of `@ai-sdk/react@4.0.117` (`UseChatHelpers`), over LibreChat's chat
* contract. Members the contract cannot back (`addToolOutput`, `clearError`) are left out rather
* than stubbed.
*/
export type UseChatHelpers = {
/** The conversation the messages are read from (the contract's `messagesKey`); AI SDK's chat id. */
id: string | undefined;
/** The cached messages as `UIMessage`s, re-read whenever the message cache is written. */
messages: UIMessage[];
status: ChatStatus;
/** Set when the latest message is an error; LibreChat reports errors as messages. */
error: Error | undefined;
/** Submits a turn through the contract's `ask`; see {@link SendMessage}. */
sendMessage: SendMessage;
/** Regenerates the response to `messageId`, or the latest message of the branch. */
regenerate: (options?: { messageId?: string }) => void;
stop: () => Promise<void>;
/**
* Reattaches this chat to its running generation, if the server has one. The request is
* answered by the resume-on-load path the chat view mounts for its pane, which checks the
* stream status and attaches through the host transport. It resolves once requested. It does
* nothing for a new chat or one already attached, and a request for a conversation no chat view
* shows waits until one does.
*/
resumeStream: () => Promise<void>;
/**
* Writes messages back to the cache, keeping the stored fields the UI view omits. A message
* with no stored counterpart joins the active conversation under the message before it, or
* under the active branch's tail when the message before it is on another branch, unless its
* metadata names a parent. A message keeps the conversation it is stored under.
*/
setMessages: (messages: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => void;
};
type ToolContext = {
content: TMessage['content'];
attachments: TMessage['attachments'];
live: TAttachment[] | undefined;
byToolCall: Record<string, TAttachment[] | undefined>;
/** Step ids each provider tool-call id already owns, for calls that have no step yet. */
stepIdsById: Map<string, Set<string>>;
};
const toolContexts = new WeakMap<TMessage, ToolContext>();
/**
* Built once per message snapshot and live attachment list. The stream reuses a response object
* across frames and replaces its `content` and `attachments` arrays, so both are checked, not only
* the object. A tool's attachments reach the live list before the message cache holds them.
*/
const getToolContext = (message: TMessage, live: TAttachment[] | undefined): ToolContext => {
const cached = toolContexts.get(message);
if (
cached &&
cached.content === message.content &&
cached.attachments === message.attachments &&
cached.live === live
) {
return cached;
}
const stepIdsById = new Map<string, Set<string>>();
for (const part of message.content ?? []) {
if (part?.type !== ContentTypes.TOOL_CALL) {
continue;
}
const { id, stepId } = (part.tool_call ?? {}) as { id?: string; stepId?: string };
if (!id || !stepId) {
continue;
}
const owned = stepIdsById.get(id) ?? new Set<string>();
owned.add(stepId);
stepIdsById.set(id, owned);
}
const context: ToolContext = {
content: message.content,
attachments: message.attachments,
live,
byToolCall: mapAttachments(mergeAttachments(message.attachments, live)),
stepIdsById,
};
toolContexts.set(message, context);
return context;
};
type MemoryToolName = Parameters<typeof isMemoryFailureOutput>[0];
const isMemoryTool = (name: string | undefined): name is MemoryToolName =>
name === 'set_memory' || name === 'delete_memory';
type StoredToolCall = Parameters<NonNullable<UIMappingOptions['resolveToolFailure']>>[0];
/**
* A memory call's output is its own failure message; a background task's output is only its
* dispatch handle, so its reason stands instead.
*/
const getFailureProse = (toolCall: StoredToolCall, background: boolean) => {
const { name, output } = toolCall as { name?: string; output?: unknown };
if (background || typeof output !== 'string' || !output) {
return undefined;
}
if (!isMemoryTool(name)) {
return undefined;
}
return isMemoryFailureOutput(name, output) ? output : undefined;
};
/**
* The client's own tool outcome rules (`getToolMeta`: memory failure prose, background task
* status attachments), handed to the parts mapping, which reads only markers stored on the call.
* A call with no step yet is scoped away from attachments its repeated provider id's other
* steps own, as `summarizeSpan` does.
*/
const resolveToolFailure = (
toolCall: StoredToolCall,
context: ToolContext | undefined,
): ReturnType<NonNullable<UIMappingOptions['resolveToolFailure']>> => {
const { id, stepId } = toolCall as { id?: string; stepId?: string };
const siblingStepIds = stepId == null && id ? context?.stepIdsById.get(id) : undefined;
const meta = getToolMeta(
{ type: ContentTypes.TOOL_CALL, tool_call: toolCall },
context?.byToolCall,
siblingStepIds,
);
if (meta?.cancelled) {
return 'cancelled';
}
if (!meta?.failed) {
return undefined;
}
return getFailureProse(toolCall, meta.background != null) ?? 'failed';
};
/** Mapping options that resolve a message's tool outcomes against its live attachments too. */
const getMappingOptions = (live: TAttachment[] | undefined): UIMappingOptions => ({
resolveToolFailure: (toolCall, message) =>
resolveToolFailure(toolCall, message ? getToolContext(message, live) : undefined),
});
/**
* Every message field a view is built from, identity and metadata included: a stream frame or a
* new chat's promotion can replace these on the same object.
*/
const viewSourceKeys = [
'messageId',
'isCreatedByUser',
'conversationId',
'parentMessageId',
'content',
'text',
'files',
'attachments',
'error',
'unfinished',
'sender',
'model',
'endpoint',
'createdAt',
] as const;
type CachedView = {
view: UIMessage;
source: Pick<TMessage, (typeof viewSourceKeys)[number]>;
live: TAttachment[] | undefined;
};
const views = new WeakMap<TMessage, CachedView>();
const isSameSource = (cached: CachedView, message: TMessage, live: TAttachment[] | undefined) =>
cached.live === live && viewSourceKeys.every((key) => cached.source[key] === message[key]);
/**
* Cached per message, per snapshot of the fields a view reads and per live attachment list: a
* stream frame that replaces a response's content, or an attachment that arrives for it, remaps
* that response, while untouched messages keep their views.
*/
const toView = (message: TMessage, live: TAttachment[] | undefined) => {
const cached = views.get(message);
if (cached && isSameSource(cached, message, live)) {
return cached.view;
}
const view = toUIMessage(message, getMappingOptions(live));
const source = {} as CachedView['source'];
for (const key of viewSourceKeys) {
Object.assign(source, { [key]: message[key] });
}
views.set(message, { view, source, live });
return view;
};
/**
* Placeholder slots (empty text or think, lane placeholders) are not streamed output. A rerun edit
* seeds its response with the retained prefix, which reads as streamed from the start: the
* contract carries no first-delta signal a restored or replaced run could keep correct.
*/
const hasStreamed = (message: TMessage) =>
(message.text?.length ?? 0) > 0 ||
(message.files?.length ?? 0) > 0 ||
(message.content?.some((part) => part != null && !isEmptyContentPart(part)) ?? false);
/**
* The error part names the failure; top-level text is only the fallback for legacy error rows,
* and never for a failed user message, whose text is what the user sent.
*/
const getErrorText = (message: TMessage) => {
const part = message.content?.find((item) => item?.type === ContentTypes.ERROR);
if (part?.type !== ContentTypes.ERROR) {
return message.isCreatedByUser ? '' : (message.text ?? '');
}
const text = typeof part.text === 'string' ? part.text : part.text?.value;
return part.error || text || message.text || '';
};
const isErrorMessage = (message: TMessage) =>
message.error === true ||
(message.content?.some((part) => part?.type === ContentTypes.ERROR) ?? false);
/**
* `submitted` until the response for the in-flight turn has content, then `streaming`; once the
* turn ends, `error` when the latest message failed (a user message that never got a response
* included) and `ready` otherwise, a stopped turn included.
* `abortScroll` is a scroll hold rather than an abort flag, so a stop is read from the settled
* message, not from it.
*/
export const getChatStatus = (isSubmitting: boolean, latest: TMessage | undefined): ChatStatus => {
if (isSubmitting) {
return latest && !latest.isCreatedByUser && hasStreamed(latest) ? 'streaming' : 'submitted';
}
return latest && isErrorMessage(latest) ? 'error' : 'ready';
};
/** Cache events that add, drop or rewrite a query's data. */
const dataEvents = new Set<QueryCacheNotifyEvent['type']>(['added', 'removed', 'updated']);
/** Ids on the active branch: the contract's tail and its ancestors. */
const getActiveBranch = (byId: Map<string, TMessage>, tailId: string | undefined) => {
const branch = new Set<string>();
let id: string | null | undefined = tailId;
while (id != null && !branch.has(id)) {
branch.add(id);
id = byId.get(id)?.parentMessageId;
}
return branch;
};
/**
* Subscribes to writes of 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.
*/
const useMessagesSubscription = (messagesKey: string) => {
const queryClient = useQueryClient();
const queryHash = useMemo(() => hashQueryKey([QueryKeys.messages, messagesKey]), [messagesKey]);
const subscribe = useCallback(
(onChange: () => void) => {
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();
};
},
[queryClient, queryHash],
);
return { queryClient, queryHash, subscribe };
};
/** Regenerates the response to `messageId`, or the latest message of the branch. */
const useRegenerate = (
getMessages: ChatContract['getMessages'],
latestMessageId: string | undefined,
regenerateTarget: ChatContract['regenerate'],
) =>
useCallback(
(options?: { messageId?: string }) => {
const messageId = options?.messageId ?? latestMessageId;
const target = getMessages()?.find((message) => message.messageId === messageId);
regenerateTarget(
target
? {
messageId: target.messageId,
parentMessageId: target.parentMessageId,
isCreatedByUser: target.isCreatedByUser,
}
: { messageId },
);
},
[getMessages, latestMessageId, regenerateTarget],
);
/** The latest message, searched from the tail, where it almost always is. */
const findLatest = (stored: TMessage[] | undefined, latestMessageId: string | undefined) => {
if (!stored || latestMessageId == null) {
return undefined;
}
for (let i = stored.length - 1; i >= 0; i--) {
if (stored[i].messageId === latestMessageId) {
return stored[i];
}
}
return undefined;
};
/** The `useChat` members that need no message list. */
export type ChatActions = Pick<
UseChatHelpers,
'id' | 'status' | 'sendMessage' | 'regenerate' | 'stop' | 'resumeStream'
>;
/** `ask` arguments for a `sendMessage` call, which may carry an AI SDK user message. */
const toAskProps = (message: TAskProps | SendMessageInput): TAskProps => {
if (!('parts' in message)) {
return message;
}
const { parentMessageId } = message.metadata ?? {};
return {
text: message.parts.map((part) => part.text).join(''),
/** A root message's view carries a `null` parent, which `ask` would read as "append to the
* branch tail"; the turn asked to attach at the root. */
...(parentMessageId !== undefined && {
parentMessageId: parentMessageId ?? Constants.NO_PARENT,
}),
};
};
/** `sendMessage` and `resumeStream` for the chat `id`, shared by `useChat` and `useChatActions`. */
function useTurnActions(ask: ChatContract['ask'], id?: string) {
const jotaiStore = useStore();
const sendMessage = useCallback<SendMessage>(
(message, options) => ask(toAskProps(message), options),
[ask],
);
const resumeStream = useCallback(async () => {
if (!id || id === Constants.NEW_CONVO) {
return;
}
jotaiStore.set(resumeRequestsAtom, (pending) =>
pending.has(id) ? pending : new Set(pending).add(id),
);
}, [id, jotaiStore]);
return { sendMessage, resumeStream };
}
/**
* `useChat` without `messages`, for controls that submit or read status: it re-renders when the
* status changes, not on every stream frame, and never maps the conversation.
*/
export function useChatActions(): ChatActions {
const {
conversation,
getMessages,
messagesKey,
latestMessageId,
isSubmitting,
ask,
regenerate: regenerateTarget,
stopGenerating,
} = useChatContext();
const { subscribe } = useMessagesSubscription(messagesKey);
const readStatus = useCallback(
() => getChatStatus(isSubmitting, findLatest(getMessages(), latestMessageId)),
[getMessages, isSubmitting, latestMessageId],
);
const status = useSyncExternalStore(subscribe, readStatus, readStatus);
const regenerate = useRegenerate(getMessages, latestMessageId, regenerateTarget);
const id = messagesKey || conversation?.conversationId || undefined;
const { sendMessage, resumeStream } = useTurnActions(ask, id);
return useMemo(
() => ({ id, status, sendMessage, regenerate, stop: stopGenerating, resumeStream }),
[id, status, sendMessage, regenerate, stopGenerating, resumeStream],
);
}
/**
* AI SDK `useChat`, read and called through `ChatContext`. It holds no state of its own:
* `messages` is `getMessages()` mapped per message, re-read when the message query cache is
* written, and every action forwards to the contract.
*/
export function useChat(): UseChatHelpers {
const {
conversation,
getMessages,
messagesKey,
setMessages: setStoredMessages,
latestMessageId,
useLiveAttachments,
isSubmitting,
ask,
regenerate: regenerateTarget,
stopGenerating,
} = useChatContext();
const liveAttachments = useLiveAttachments();
const { queryClient, queryHash, subscribe } = useMessagesSubscription(messagesKey);
const snapshot = useRef<{ writes: number; stored?: TMessage[] }>();
/**
* A stream frame replaces a response's content on the same object, so structural sharing can
* keep the cached array. Every write still counts on the query, so the snapshot is keyed by that
* store-owned count and by the array; a write that lands before the listener subscribes is
* still seen.
*/
const readSnapshot = useCallback(() => {
const stored = getMessages();
const writes = queryClient.getQueryCache().get(queryHash)?.state.dataUpdateCount ?? 0;
const current = snapshot.current;
if (current?.writes === writes && current.stored === stored) {
return current;
}
snapshot.current = { writes, stored };
return snapshot.current;
}, [getMessages, queryClient, queryHash]);
const cache = useSyncExternalStore(subscribe, readSnapshot, readSnapshot);
const { messages, latest } = useMemo(() => {
const list: UIMessage[] = [];
let latestMessage: TMessage | undefined;
for (const message of cache.stored ?? []) {
list.push(toView(message, liveAttachments[message.messageId]));
if (message.messageId === latestMessageId) {
latestMessage = message;
}
}
return { messages: list, latest: latestMessage };
}, [cache, latestMessageId, liveAttachments]);
const chatId = messagesKey || conversation?.conversationId || undefined;
const status = getChatStatus(isSubmitting, latest);
const errorText = status === 'error' && latest ? getErrorText(latest) : undefined;
const error = useMemo(
() => (errorText === undefined ? undefined : new Error(errorText)),
[errorText],
);
const regenerate = useRegenerate(getMessages, latestMessageId, regenerateTarget);
const { sendMessage, resumeStream } = useTurnActions(ask, chatId);
const setMessages = useCallback(
(update: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => {
const current = getMessages() ?? [];
const next =
typeof update === 'function'
? update(current.map((message) => toView(message, liveAttachments[message.messageId])))
: update;
const byId = new Map(current.map((message) => [message.messageId, message]));
const branch = getActiveBranch(byId, latestMessageId);
const conversationId = chatId === Constants.NEW_CONVO ? null : (chatId ?? null);
let previous: { id: string; joined: boolean } | null = null;
const stored = next.map((view) => {
const base = byId.get(view.id);
const message = fromUIMessage(view, base);
message.conversationId = base ? base.conversationId : conversationId;
if (!base) {
if (view.metadata?.parentMessageId === undefined) {
message.parentMessageId =
previous == null || previous.joined
? (previous?.id ?? null)
: (latestMessageId ?? null);
}
}
previous = { id: message.messageId, joined: !base || branch.has(message.messageId) };
return message;
});
setStoredMessages(stored);
},
[chatId, getMessages, latestMessageId, liveAttachments, setStoredMessages],
);
return {
id: chatId,
messages,
status,
error,
sendMessage,
regenerate,
stop: stopGenerating,
resumeStream,
setMessages,
};
}

View file

@ -0,0 +1,110 @@
import { ContentTypes } from 'librechat-data-provider';
import type { TMessage, TAttachment, UIMappingOptions } from 'librechat-data-provider';
import { isMemoryFailureOutput } from '~/components/Chat/Messages/Content/Parts/MemoryCall';
import { getToolMeta } from '~/components/Chat/Messages/Content/outcome';
import { mergeAttachments } from '~/utils/attachments';
import { mapAttachments } from '~/utils/map';
type ToolContext = {
content: TMessage['content'];
attachments: TMessage['attachments'];
live: TAttachment[] | undefined;
byToolCall: Record<string, TAttachment[] | undefined>;
/** Step ids each provider tool-call id already owns, for calls that have no step yet. */
stepIdsById: Map<string, Set<string>>;
};
const toolContexts = new WeakMap<TMessage, ToolContext>();
/**
* Built once per message snapshot and live attachment list. The stream reuses a response object
* across frames and replaces its `content` and `attachments` arrays, so both are checked, not only
* the object. A tool's attachments reach the live list before the message cache holds them.
*/
const getToolContext = (message: TMessage, live: TAttachment[] | undefined): ToolContext => {
const cached = toolContexts.get(message);
if (
cached &&
cached.content === message.content &&
cached.attachments === message.attachments &&
cached.live === live
) {
return cached;
}
const stepIdsById = new Map<string, Set<string>>();
for (const part of message.content ?? []) {
if (part?.type !== ContentTypes.TOOL_CALL) {
continue;
}
const { id, stepId } = (part.tool_call ?? {}) as { id?: string; stepId?: string };
if (!id || !stepId) {
continue;
}
const owned = stepIdsById.get(id) ?? new Set<string>();
owned.add(stepId);
stepIdsById.set(id, owned);
}
const context: ToolContext = {
content: message.content,
attachments: message.attachments,
live,
byToolCall: mapAttachments(mergeAttachments(message.attachments, live)),
stepIdsById,
};
toolContexts.set(message, context);
return context;
};
type MemoryToolName = Parameters<typeof isMemoryFailureOutput>[0];
const isMemoryTool = (name: string | undefined): name is MemoryToolName =>
name === 'set_memory' || name === 'delete_memory';
type StoredToolCall = Parameters<NonNullable<UIMappingOptions['resolveToolFailure']>>[0];
/**
* A memory call's output is its own failure message; a background task's output is only its
* dispatch handle, so its reason stands instead.
*/
const getFailureProse = (toolCall: StoredToolCall, background: boolean) => {
const { name, output } = toolCall as { name?: string; output?: unknown };
if (background || typeof output !== 'string' || !output) {
return undefined;
}
if (!isMemoryTool(name)) {
return undefined;
}
return isMemoryFailureOutput(name, output) ? output : undefined;
};
/**
* The client's own tool outcome rules (`getToolMeta`: memory failure prose, background task
* status attachments), handed to the parts mapping, which reads only markers stored on the call.
* A call with no step yet is scoped away from attachments its repeated provider id's other
* steps own, as `summarizeSpan` does.
*/
const resolveToolFailure = (
toolCall: StoredToolCall,
context: ToolContext | undefined,
): ReturnType<NonNullable<UIMappingOptions['resolveToolFailure']>> => {
const { id, stepId } = toolCall as { id?: string; stepId?: string };
const siblingStepIds = stepId == null && id ? context?.stepIdsById.get(id) : undefined;
const meta = getToolMeta(
{ type: ContentTypes.TOOL_CALL, tool_call: toolCall },
context?.byToolCall,
siblingStepIds,
);
if (meta?.cancelled) {
return 'cancelled';
}
if (!meta?.failed) {
return undefined;
}
return getFailureProse(toolCall, meta.background != null) ?? 'failed';
};
/** Mapping options that resolve a message's tool outcomes against its live attachments too. */
export const getMappingOptions = (live: TAttachment[] | undefined): UIMappingOptions => ({
resolveToolFailure: (toolCall, message) =>
resolveToolFailure(toolCall, message ? getToolContext(message, live) : undefined),
});

View file

@ -11,6 +11,7 @@ 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';
/**
@ -29,7 +30,7 @@ export function ChatProvider({
conversationId?: string;
children: ReactNode;
}) {
const chat = useChatHelpers(index, conversationId);
const chat = useChatHelpers(index, conversationId, getMappingOptions);
return <ChatContext.Provider value={chat}>{children}</ChatContext.Provider>;
}
@ -77,7 +78,7 @@ export function ChatSessionProvider({
{ isStreaming: isSubmitting },
);
const chat = useChatHelpers(index, conversationId);
const chat = useChatHelpers(index, conversationId, getMappingOptions);
const rootSubmission = useAtomValue(submissionByIndex(index));
useAdaptiveSSE(rootSubmission, chat, false, index);

View file

@ -23,20 +23,27 @@ 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 { getMessageCacheIds } from './cache';
import { useAbortCleanup } from './abort';
import store from '~/store';
/** The live attachments map the stream and preview polling write. */
const useLiveAttachments = () => useAtomValue(messageAttachmentsMapAtom);
// this to be set somewhere else
export default function useChatHelpers(index = 0, paramId?: string): ChatContract {
/**
* 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);
@ -91,8 +98,8 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
);
const { newConversation } = useNewConvo(index);
const { useCreateConversationAtom } = store;
const { conversation, setConversation } = useCreateConversationAtom(index);
const chatSettings = useChatSettings();
const { conversation, setConversation } = chatSettings.usePaneConversationState(index);
const { conversationId, endpoint, endpointType } = conversation ?? {};
const activeGenerationCreatedAt = useAtomValue(
activeGenerationCreatedAtByConvoId(conversationId ?? Constants.NEW_CONVO),
@ -132,6 +139,11 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
[queryParam, queryClient, conversationId],
);
const { subscribeMessages, getMessagesRevision } = useMemo(
() => createMessagesSubscription(queryClient, queryParam),
[queryClient, queryParam],
);
const getMessages = useCallback(
(targetConversationId?: string | null) => {
return queryClient.getQueryData<TMessage[]>([
@ -393,7 +405,7 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
/** 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 } = useChatSettings().config;
const { feedbackEnabled } = chatSettings.config;
return useMemo(
(): ChatContract => ({
@ -405,6 +417,8 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
getMessages,
messagesKey: queryParam,
setMessages,
subscribeMessages,
getMessagesRevision,
setSiblingIdx,
latestMessageId,
latestMessageDepth,
@ -427,6 +441,7 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
filesLoading,
setFilesLoading,
feedbackEnabled,
getMappingOptions,
}),
[
newConversation,
@ -437,6 +452,8 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
getMessages,
queryParam,
setMessages,
subscribeMessages,
getMessagesRevision,
setSiblingIdx,
latestMessageId,
latestMessageDepth,
@ -458,6 +475,7 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
filesLoading,
setFilesLoading,
feedbackEnabled,
getMappingOptions,
],
);
}

View file

@ -1,9 +1,9 @@
import { useCallback, useEffect, useRef } from 'react';
import { atom, useAtom } from 'jotai';
import { useChatActions } from '@librechat/chat/react';
import { Constants, isCompactedLeaf, isAssistantsEndpoint } from 'librechat-data-provider';
import { useLatestMessage } from '~/hooks/Messages/useLatestMessage';
import { useChatContext } from '~/Providers/ChatContext';
import { useChatActions } from './facade';
/** Conversation whose compaction this client submitted and is still streaming. */
export const compactingConversationAtom = atom<string | null>(null);

View file

@ -1,11 +1,11 @@
import { useRef, useEffect } from 'react';
import { useAtom } from 'jotai';
import { useQueryClient } from '@tanstack/react-query';
import { resumeRequestsAtom } from '@librechat/chat/react';
import { Constants, QueryKeys } from 'librechat-data-provider';
import type { TSubmission } from 'librechat-data-provider';
import type { MutableRefObject } from 'react';
import type { OwedSuccessorState } from './successor';
import { resumeRequestsAtom } from '~/hooks/Chat/resume';
import { streamStatusQueryKey } from '~/data-provider';
/**

View file

@ -3,7 +3,13 @@ import { useAtom } from 'jotai';
import { supportsConversationTitleOwnership } from 'librechat-data-provider';
import { useRecoilState, useRecoilValue, useRecoilCallback, useResetRecoilState } from 'recoil';
import type { ReactNode } from 'react';
import type { ChatAuth, ChatConfig, ChatSettings, PaneConversation } from '~/hooks/Chat/contract';
import type {
ChatAuth,
ChatConfig,
ChatSettings,
PaneConversation,
PaneConversationState,
} from '~/hooks/Chat/contract';
import { ChatTransportContext, defaultChatTransport } from '~/Providers/ChatTransportContext';
import { ChatSettingsContext } from '~/Providers/ChatSettingsContext';
import { duringRunActionAtom } from '~/store/duringRun';
@ -34,6 +40,12 @@ export function usePaneConversation(index: string | number) {
return useRecoilValue(store.conversationByIndex(index));
}
/** A pane's conversation and setter in the app's pane store, registering the pane's key. */
export function usePaneConversationState(index: string | number): PaneConversationState {
const { conversation, setConversation } = store.useCreateConversationAtom(index);
return useMemo(() => ({ conversation, setConversation }), [conversation, setConversation]);
}
/** Supplies the chat's app-global preferences from the app's own settings store, the deployment
* config and signed-in account from the app's queries, and the transport its turns run over. */
export default function ChatSettingsProvider({ children }: { children: ReactNode }) {
@ -80,6 +92,7 @@ export default function ChatSettingsProvider({ children }: { children: ReactNode
auth,
getPaneConversations,
usePaneConversation,
usePaneConversationState,
}),
[
duringRunDefaultAction,

View file

@ -1,3 +1,4 @@
import { isEmptyContentPart } from '@librechat/chat/react';
import { QueryKeys, Constants, buildTree, ContentTypes } from 'librechat-data-provider';
import {
hasStreamStartFailed,
@ -10,6 +11,7 @@ import type { QueryClient } from '@tanstack/react-query';
import type { LocalizeFunction, TMessageProps } from '~/common';
export {
isEmptyContentPart,
hasStreamStartFailed,
stripStreamedIndexStamps,
createDualMessageContent,
@ -203,25 +205,6 @@ const getPartToolCall = (part: TMessageContentParts): Agents.ToolCall | undefine
? (part[ContentTypes.TOOL_CALL] as Agents.ToolCall | undefined)
: undefined;
/** Slots the persistence compaction leaves nothing behind for: the
* dual-message `type: ''` placeholders, text/think parts that never received a
* delta, and tool calls missing their `tool_call` payload. */
export const isEmptyContentPart = (part: TMessageContentParts): boolean => {
if (!part.type) {
return true;
}
if (part.type === ContentTypes.TEXT) {
return getPartTextValue(part.text).length === 0;
}
if (part.type === ContentTypes.THINK) {
return getPartTextValue(part.think).length === 0;
}
if (part.type === ContentTypes.TOOL_CALL) {
return getPartToolCall(part) == null;
}
return false;
};
/** One side extending the other is the same part observed at two moments —
* a flushed tail or a server-side trim — while divergent content is a
* different part that merely shares the type. */

View file

@ -1,4 +1,5 @@
/** React bindings for the core `Chat`: providers and `useChat`. Populated as the hooks move in. */
export * from './react/chat';
export { MessageContext, MessagePartIndex, useMessageContext } from './react/message';
export {
useMessagePartsHost,

View file

@ -0,0 +1,33 @@
import { ContentTypes } from 'librechat-data-provider';
import type { TMessage, UIMappingOptions } from 'librechat-data-provider';
import { toView } from '../views';
const toolCall = (): TMessage => ({
messageId: 'response-1',
conversationId: 'convo-1',
parentMessageId: 'user-1',
isCreatedByUser: false,
text: '',
content: [
{
type: ContentTypes.TOOL_CALL,
tool_call: { id: 'call-1', type: 'tool_call', name: 'search', args: '{}', output: 'x' },
},
],
});
const failed = (): UIMappingOptions => ({ resolveToolFailure: () => 'failed' });
const succeeded = (): UIMappingOptions => ({});
describe('toView', () => {
it('reuses a view only for the tool outcome rules that mapped it', () => {
const message = toolCall();
const first = toView(message, undefined, failed);
expect(toView(message, undefined, failed)).toBe(first);
const other = toView(message, undefined, succeeded);
expect(other).not.toBe(first);
expect(other.parts[0]).not.toEqual(first.parts[0]);
});
});

View file

@ -0,0 +1,99 @@
import { useMemo, useCallback, useSyncExternalStore } from 'react';
import { useStore } from 'jotai';
import { Constants } from 'librechat-data-provider';
import type { ChatActions, SendMessage, UseChatHelpers, SendMessageInput } from './types';
import type { ChatContract, TAskProps } from './contract';
import { getChatStatus, findLatest } from './status';
import { resumeRequestsAtom } from './resume';
import { useChatContext } from './context';
/** Regenerates the response to `messageId`, or the latest message of the branch. */
export const useRegenerate = (
getMessages: ChatContract['getMessages'],
latestMessageId: string | undefined,
regenerateTarget: ChatContract['regenerate'],
): UseChatHelpers['regenerate'] =>
useCallback(
(options?: { messageId?: string }) => {
const messageId = options?.messageId ?? latestMessageId;
const target = getMessages()?.find((message) => message.messageId === messageId);
regenerateTarget(
target
? {
messageId: target.messageId,
parentMessageId: target.parentMessageId,
isCreatedByUser: target.isCreatedByUser,
}
: { messageId },
);
},
[getMessages, latestMessageId, regenerateTarget],
);
/** `ask` arguments for a `sendMessage` call, which may carry an AI SDK user message. */
const toAskProps = (message: TAskProps | SendMessageInput): TAskProps => {
if (!('parts' in message)) {
return message;
}
const { parentMessageId } = message.metadata ?? {};
return {
text: message.parts.map((part) => part.text).join(''),
/** A root message's view carries a `null` parent, which `ask` would read as "append to the
* branch tail"; the turn asked to attach at the root. */
...(parentMessageId !== undefined && {
parentMessageId: parentMessageId ?? Constants.NO_PARENT,
}),
};
};
/** `sendMessage` and `resumeStream` for the chat `id`, shared by `useChat` and `useChatActions`. */
export function useTurnActions(
ask: ChatContract['ask'],
id?: string,
): Pick<ChatActions, 'sendMessage' | 'resumeStream'> {
const jotaiStore = useStore();
const sendMessage = useCallback<SendMessage>(
(message, options) => ask(toAskProps(message), options),
[ask],
);
const resumeStream = useCallback(async () => {
if (!id || id === Constants.NEW_CONVO) {
return;
}
jotaiStore.set(resumeRequestsAtom, (pending) =>
pending.has(id) ? pending : new Set(pending).add(id),
);
}, [id, jotaiStore]);
return { sendMessage, resumeStream };
}
/**
* `useChat` without `messages`, for controls that submit or read status: it re-renders when the
* status changes, not on every stream frame, and never maps the conversation.
*/
export function useChatActions(): ChatActions {
const {
conversation,
getMessages,
messagesKey,
subscribeMessages,
latestMessageId,
isSubmitting,
ask,
regenerate: regenerateTarget,
stopGenerating,
} = useChatContext();
const readStatus = useCallback(
() => getChatStatus(isSubmitting, findLatest(getMessages(), latestMessageId)),
[getMessages, isSubmitting, latestMessageId],
);
const status = useSyncExternalStore(subscribeMessages, readStatus, readStatus);
const regenerate = useRegenerate(getMessages, latestMessageId, regenerateTarget);
const id = messagesKey || conversation?.conversationId || undefined;
const { sendMessage, resumeStream } = useTurnActions(ask, id);
return useMemo(
() => ({ id, status, sendMessage, regenerate, stop: stopGenerating, resumeStream }),
[id, status, sendMessage, regenerate, stopGenerating, resumeStream],
);
}

View file

@ -0,0 +1,101 @@
import { useRef, useMemo, useCallback, useSyncExternalStore } from 'react';
import type { TMessage, UIMessage } from 'librechat-data-provider';
import type { UseChatHelpers } from './types';
import { useRegenerate, useTurnActions } from './actions';
import { getChatStatus, getErrorText } from './status';
import { toStoredMessages } from './messages';
import { useChatContext } from './context';
import { toView } from './views';
/**
* AI SDK `useChat`, read and called through `ChatContext`. It holds no state of its own:
* `messages` is `getMessages()` mapped per message, re-read when the message cache is
* written, and every action forwards to the contract.
*/
export function useChat(): UseChatHelpers {
const {
conversation,
getMessages,
messagesKey,
subscribeMessages,
getMessagesRevision,
setMessages: setStoredMessages,
latestMessageId,
useLiveAttachments,
getMappingOptions,
isSubmitting,
ask,
regenerate: regenerateTarget,
stopGenerating,
} = useChatContext();
const liveAttachments = useLiveAttachments();
const snapshot = useRef<{ writes: number; stored?: TMessage[] }>();
/**
* A stream frame replaces a response's content on the same object, so structural sharing can
* keep the cached array. Every write still counts on the cache, so the snapshot is keyed by that
* count and by the array; a write that lands before the listener subscribes is still seen.
*/
const readSnapshot = useCallback(() => {
const stored = getMessages();
const writes = getMessagesRevision();
const current = snapshot.current;
if (current?.writes === writes && current.stored === stored) {
return current;
}
snapshot.current = { writes, stored };
return snapshot.current;
}, [getMessages, getMessagesRevision]);
const cache = useSyncExternalStore(subscribeMessages, readSnapshot, readSnapshot);
const { messages, latest } = useMemo(() => {
const list: UIMessage[] = [];
let latestMessage: TMessage | undefined;
for (const message of cache.stored ?? []) {
list.push(toView(message, liveAttachments[message.messageId], getMappingOptions));
if (message.messageId === latestMessageId) {
latestMessage = message;
}
}
return { messages: list, latest: latestMessage };
}, [cache, latestMessageId, liveAttachments, getMappingOptions]);
const chatId = messagesKey || conversation?.conversationId || undefined;
const status = getChatStatus(isSubmitting, latest);
const errorText = status === 'error' && latest ? getErrorText(latest) : undefined;
const error = useMemo(
() => (errorText === undefined ? undefined : new Error(errorText)),
[errorText],
);
const regenerate = useRegenerate(getMessages, latestMessageId, regenerateTarget);
const { sendMessage, resumeStream } = useTurnActions(ask, chatId);
const setMessages = useCallback(
(update: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => {
const current = getMessages() ?? [];
const next =
typeof update === 'function'
? update(
current.map((message) =>
toView(message, liveAttachments[message.messageId], getMappingOptions),
),
)
: update;
setStoredMessages(toStoredMessages(next, current, latestMessageId, chatId));
},
[chatId, getMessages, latestMessageId, liveAttachments, getMappingOptions, setStoredMessages],
);
return {
id: chatId,
messages,
status,
error,
sendMessage,
regenerate,
stop: stopGenerating,
resumeStream,
setMessages,
};
}

View file

@ -0,0 +1,14 @@
import { createContext, useContext } from 'react';
import type { Context } from 'react';
import type { ChatContract } from './contract';
/** The chat contract of the nearest pane, served by the host's chat provider. */
export const ChatContext: Context<ChatContract | null> = createContext<ChatContract | null>(null);
export const useChatContext = (): ChatContract => {
const ctx = useContext(ChatContext);
if (!ctx) {
throw new Error('useChatContext must be used within a ChatContext.Provider');
}
return ctx;
};

View file

@ -0,0 +1,240 @@
import type {
TPreset,
TMessage,
TAttachment,
TModelsConfig,
TConversation,
TEditedContent,
UIMappingOptions,
TReasoningOverride,
} from 'librechat-data-provider';
import type { SetStateAction, Dispatch, MouseEvent } from 'react';
import type { PaneOptionSettings } from '../pane';
import type { ExtendedFile } from '../../core';
/** The user turn an `ask` call submits. */
export type TAskProps = {
text: string;
overrideConvoId?: string;
overrideUserMessageId?: string;
parentMessageId?: string | null;
conversationId?: string | null;
messageId?: string | null;
clientTimestamp?: string;
};
/** How an `ask` call submits its turn: an edit, a regenerate, a continue or a compaction. */
export type TOptions = {
editedMessageId?: string | null;
editedContent?: TEditedContent;
isRegenerate?: boolean;
isContinued?: boolean;
isEdited?: boolean;
/**
* Manual context compaction: a summarize-only turn hung off the branch's
* leaf (`messageId`). Shaped like a regenerate on the client (no new user
* bubble, the response placeholder parents onto the leaf) and sent with
* `compact: true` so the server runs the graph summarize-only.
*/
compact?: boolean;
overrideMessages?: TMessage[];
/**
* Authoritative attachment list for this submission: a rerun replays the edited
* message's stored files, and an auto-drained queued message replays the ones taken
* out of the composer when it was queued. Authoritative even when empty, so a drain
* never vacuums up attachments the user staged for their next send.
*/
overrideFiles?: TMessage['files'];
/**
* Assistant message being regenerated. Used to derive the optimistic response
* id for non-tail regenerations without accidentally keying the stream to the
* conversation tail.
*/
targetResponseMessageId?: string | null;
/**
* Carry forward a user message's manually-invoked skills when the caller
* is resubmitting or regenerating that same message: the compose-time
* atom has already been drained on the original submit, so without this
* the second turn would run without any manual priming even though the
* pills are still visible on the user bubble.
*/
overrideManualSkills?: string[];
/**
* Carry forward a user message's quoted excerpts when resubmitting or
* regenerating that same message: the compose-time atom is drained on the
* original submit, so without this the second turn would lose the quoted
* context even though the references still show on the user bubble.
*/
overrideQuotes?: string[];
/** Request-scoped reasoning selection for this exact submission. */
overrideReasoning?: TReasoningOverride | null;
/** Added conversation for multi-convo feature - sent to server as part of submission payload */
addedConvo?: TConversation;
/** Reuse a durable submission identity (terminal steer recovery). */
overrideClientRequestId?: string;
/** Exact parked steer source for a recovery attempt. */
overrideRecoverySteerId?: string;
/** Exact terminal generation observed before an automatic queued start. */
overrideExpectedPredecessorCreatedAt?: number;
/** Client-only exact queue position restored if admission is rejected. */
overrideQueuedMessageOrigin?: unknown;
};
export type TAskFunction = (props: TAskProps, options?: TOptions) => false | void;
/** What a new conversation is built from. */
export type NewConversationParams = {
template?: Partial<TConversation>;
preset?: Partial<TPreset>;
modelsData?: TModelsConfig;
buildDefault?: boolean;
keepAddedConvos?: boolean;
disableParams?: boolean;
};
/** 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: PaneOptionSettings;
/** Replaces the legacy per-pane option toggles. */
setOptionSettings: Dispatch<SetStateAction<PaneOptionSettings>>;
};
/** 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;
/**
* The conversation key `getMessages()` reads when called without one: the route's id, which
* can run ahead of `conversation` while navigation settles, or `''` before the pane has either.
* AI SDK: the chat `id`.
*/
messagesKey: string;
/** Writes the full message list to every cache key this pane reads. AI SDK: `setMessages`. */
setMessages: (messages: TMessage[]) => void;
/**
* Subscribes to writes of the messages cached under `messagesKey` and returns the
* unsubscribe. Only writes that can change the data are delivered, after the current task
* rather than inside the render that caused them. Stable while `messagesKey` is.
*/
subscribeMessages: (onChange: () => void) => () => void;
/**
* How many times the messages cached under `messagesKey` have been written. A stream frame
* can rewrite a message in place and keep the array, so this, not the array, tells one write
* from the next. Stable while `messagesKey` is.
*/
getMessagesRevision: () => number;
/** 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;
/**
* Attachments delivered by message id while the message cache holds none of them yet: tool
* artifacts streamed mid-run and previews resolved after it. A hook, so only a caller that
* merges them re-renders when one arrives; stable across renders. AI SDK: the data parts a
* stream writes onto its message.
*/
useLiveAttachments: () => Record<string, TAttachment[] | 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 message feedback controls are enabled by the startup config. */
feedbackEnabled: boolean;
/**
* The app's tool outcome rules for viewing one message as a `UIMessage`, given the
* attachments that arrived for it outside the message cache. Stable across renders.
*/
getMappingOptions: (live: TAttachment[] | undefined) => UIMappingOptions;
};
/**
* 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;

View file

@ -0,0 +1,27 @@
export { useChat } from './chat';
export { useChatActions } from './actions';
export { getChatStatus, isEmptyContentPart } from './status';
export { ChatContext, useChatContext } from './context';
export { resumeRequestsAtom } from './resume';
export type {
ChatStatus,
ChatActions,
SendMessage,
UseChatHelpers,
SendMessageInput,
} from './types';
export type {
TOptions,
TAskProps,
ChatContract,
TAskFunction,
RegenerateTarget,
ChatViewContract,
ChatFilesContract,
ChatAbortContract,
ChatMessagesContract,
NewConversationParams,
NewConversationOptions,
ChatSubmissionContract,
ChatConversationContract,
} from './contract';

View file

@ -0,0 +1,42 @@
import { Constants, fromUIMessage } from 'librechat-data-provider';
import type { TMessage, UIMessage } from 'librechat-data-provider';
/** Ids on the active branch: the contract's tail and its ancestors. */
const getActiveBranch = (byId: Map<string, TMessage>, tailId: string | undefined) => {
const branch = new Set<string>();
let id: string | null | undefined = tailId;
while (id != null && !branch.has(id)) {
branch.add(id);
id = byId.get(id)?.parentMessageId;
}
return branch;
};
/**
* The stored messages `next` writes back over `current`, keeping the stored fields the UI view
* omits. A message with no stored counterpart joins the chat under the message before it, or
* under the active branch's tail when the message before it is on another branch, unless its
* metadata names a parent. A message keeps the conversation it is stored under.
*/
export const toStoredMessages = (
next: UIMessage[],
current: TMessage[],
latestMessageId: string | undefined,
chatId: string | undefined,
): TMessage[] => {
const byId = new Map(current.map((message) => [message.messageId, message]));
const branch = getActiveBranch(byId, latestMessageId);
const conversationId = chatId === Constants.NEW_CONVO ? null : (chatId ?? null);
let previous: { id: string; joined: boolean } | null = null;
return next.map((view) => {
const base = byId.get(view.id);
const message = fromUIMessage(view, base);
message.conversationId = base ? base.conversationId : conversationId;
if (!base && view.metadata?.parentMessageId === undefined) {
message.parentMessageId =
previous == null || previous.joined ? (previous?.id ?? null) : (latestMessageId ?? null);
}
previous = { id: message.messageId, joined: !base || branch.has(message.messageId) };
return message;
});
};

View file

@ -1,4 +1,5 @@
import { atom } from 'jotai';
import type { PrimitiveAtom } from 'jotai';
/**
* Conversations with an unanswered request to reattach to their running generation (the
@ -7,4 +8,6 @@ import { atom } from 'jotai';
* never builds a second resume path. Entries are consumed, so the set stays as small as the
* requests in flight. Chat-owned, so it lives with the chat rather than in the app store.
*/
export const resumeRequestsAtom = atom<ReadonlySet<string>>(new Set<string>());
export const resumeRequestsAtom: PrimitiveAtom<ReadonlySet<string>> = atom<ReadonlySet<string>>(
new Set<string>(),
);

View file

@ -0,0 +1,82 @@
import { ContentTypes } from 'librechat-data-provider';
import type { Agents, TMessage, TMessageContentParts } from 'librechat-data-provider';
import type { ChatStatus } from './types';
const getPartTextValue = (value?: string | { value?: string }): string =>
(typeof value === 'string' ? value : value?.value) ?? '';
/** Slots the persistence compaction leaves nothing behind for: the
* dual-message `type: ''` placeholders, text/think parts that never received a
* delta, and tool calls missing their `tool_call` payload. */
export const isEmptyContentPart = (part: TMessageContentParts): boolean => {
if (!part.type) {
return true;
}
if (part.type === ContentTypes.TEXT) {
return getPartTextValue(part.text).length === 0;
}
if (part.type === ContentTypes.THINK) {
return getPartTextValue(part.think).length === 0;
}
if (part.type === ContentTypes.TOOL_CALL) {
return (part[ContentTypes.TOOL_CALL] as Agents.ToolCall | undefined) == null;
}
return false;
};
/**
* Placeholder slots (empty text or think, lane placeholders) are not streamed output. A rerun edit
* seeds its response with the retained prefix, which reads as streamed from the start: the
* contract carries no first-delta signal a restored or replaced run could keep correct.
*/
const hasStreamed = (message: TMessage) =>
(message.text?.length ?? 0) > 0 ||
(message.files?.length ?? 0) > 0 ||
(message.content?.some((part) => part != null && !isEmptyContentPart(part)) ?? false);
/**
* The error part names the failure; top-level text is only the fallback for legacy error rows,
* and never for a failed user message, whose text is what the user sent.
*/
export const getErrorText = (message: TMessage): string => {
const part = message.content?.find((item) => item?.type === ContentTypes.ERROR);
if (part?.type !== ContentTypes.ERROR) {
return message.isCreatedByUser ? '' : (message.text ?? '');
}
const text = typeof part.text === 'string' ? part.text : part.text?.value;
return part.error || text || message.text || '';
};
const isErrorMessage = (message: TMessage) =>
message.error === true ||
(message.content?.some((part) => part?.type === ContentTypes.ERROR) ?? false);
/**
* `submitted` until the response for the in-flight turn has content, then `streaming`; once the
* turn ends, `error` when the latest message failed (a user message that never got a response
* included) and `ready` otherwise, a stopped turn included.
* `abortScroll` is a scroll hold rather than an abort flag, so a stop is read from the settled
* message, not from it.
*/
export const getChatStatus = (isSubmitting: boolean, latest: TMessage | undefined): ChatStatus => {
if (isSubmitting) {
return latest && !latest.isCreatedByUser && hasStreamed(latest) ? 'streaming' : 'submitted';
}
return latest && isErrorMessage(latest) ? 'error' : 'ready';
};
/** The latest message, searched from the tail, where it almost always is. */
export const findLatest = (
stored: TMessage[] | undefined,
latestMessageId: string | undefined,
): TMessage | undefined => {
if (!stored || latestMessageId == null) {
return undefined;
}
for (let i = stored.length - 1; i >= 0; i--) {
if (stored[i].messageId === latestMessageId) {
return stored[i];
}
}
return undefined;
};

View file

@ -0,0 +1,65 @@
import type { UIMessage, UITextPart, UIMessageMetadata } from 'librechat-data-provider';
import type { TAskProps, TOptions } from './contract';
/** AI SDK `ChatStatus`. */
export type ChatStatus = 'submitted' | 'streaming' | 'ready' | 'error';
/**
* A user turn in the AI SDK's `sendMessage` shape: its text parts, plus the message it attaches
* under. It goes to the facade's own chat, as AI SDK `useChat` does, so it names no conversation.
* File parts are left out because the turn takes its files from the composer, not the message.
*/
export type SendMessageInput = {
parts: UITextPart[];
metadata?: Partial<Pick<UIMessageMetadata, 'parentMessageId'>>;
};
/**
* Submits a turn. Takes the contract's `ask` arguments, or a user message in the AI SDK shape,
* which is sent as the `ask` call it describes; `{ text }` is already both.
*/
export type SendMessage = (
message: TAskProps | SendMessageInput,
options?: TOptions,
) => false | void;
/**
* The `useChat` surface of `@ai-sdk/react@4.0.117` (`UseChatHelpers`), over LibreChat's chat
* contract. Members the contract cannot back (`addToolOutput`, `clearError`) are left out rather
* than stubbed.
*/
export type UseChatHelpers = {
/** The conversation the messages are read from (the contract's `messagesKey`); AI SDK's chat id. */
id: string | undefined;
/** The cached messages as `UIMessage`s, re-read whenever the message cache is written. */
messages: UIMessage[];
status: ChatStatus;
/** Set when the latest message is an error; LibreChat reports errors as messages. */
error: Error | undefined;
/** Submits a turn through the contract's `ask`; see {@link SendMessage}. */
sendMessage: SendMessage;
/** Regenerates the response to `messageId`, or the latest message of the branch. */
regenerate: (options?: { messageId?: string }) => void;
stop: () => Promise<void>;
/**
* Reattaches this chat to its running generation, if the server has one. The request is
* answered by the resume-on-load path the chat view mounts for its pane, which checks the
* stream status and attaches through the host transport. It resolves once requested. It does
* nothing for a new chat or one already attached, and a request for a conversation no chat view
* shows waits until one does.
*/
resumeStream: () => Promise<void>;
/**
* Writes messages back to the cache, keeping the stored fields the UI view omits. A message
* with no stored counterpart joins the active conversation under the message before it, or
* under the active branch's tail when the message before it is on another branch, unless its
* metadata names a parent. A message keeps the conversation it is stored under.
*/
setMessages: (messages: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => void;
};
/** The `useChat` members that need no message list. */
export type ChatActions = Pick<
UseChatHelpers,
'id' | 'status' | 'sendMessage' | 'regenerate' | 'stop' | 'resumeStream'
>;

View file

@ -0,0 +1,67 @@
import { toUIMessage } from 'librechat-data-provider';
import type { TMessage, UIMessage, TAttachment } from 'librechat-data-provider';
import type { ChatViewContract } from './contract';
/**
* Every message field a view is built from, identity and metadata included: a stream frame or a
* new chat's promotion can replace these on the same object.
*/
const viewSourceKeys = [
'messageId',
'isCreatedByUser',
'conversationId',
'parentMessageId',
'content',
'text',
'files',
'attachments',
'error',
'unfinished',
'sender',
'model',
'endpoint',
'createdAt',
] as const;
type CachedView = {
view: UIMessage;
source: Pick<TMessage, (typeof viewSourceKeys)[number]>;
live: TAttachment[] | undefined;
getMappingOptions: ChatViewContract['getMappingOptions'];
};
const views = new WeakMap<TMessage, CachedView>();
const isSameSource = (
cached: CachedView,
message: TMessage,
live: TAttachment[] | undefined,
getMappingOptions: ChatViewContract['getMappingOptions'],
) =>
cached.live === live &&
cached.getMappingOptions === getMappingOptions &&
viewSourceKeys.every((key) => cached.source[key] === message[key]);
/**
* Cached per message, per snapshot of the fields a view reads and per live attachment list: a
* stream frame that replaces a response's content, or an attachment that arrives for it, remaps
* that response, while untouched messages keep their views. A host with other tool outcome rules
* maps its own view.
*/
export const toView = (
message: TMessage,
live: TAttachment[] | undefined,
getMappingOptions: ChatViewContract['getMappingOptions'],
): UIMessage => {
const cached = views.get(message);
if (cached && isSameSource(cached, message, live, getMappingOptions)) {
return cached.view;
}
const view = toUIMessage(message, getMappingOptions(live));
const source = {} as CachedView['source'];
for (const key of viewSourceKeys) {
Object.assign(source, { [key]: message[key] });
}
views.set(message, { view, source, live, getMappingOptions });
return view;
};