Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

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

Marco Berettac1dfd6bc0fbb
diff --git a/client/src/Providers/ChatContext.tsx b/client/src/Providers/ChatContext.tsx
index ffe12407c8..cbca044f41 100644
--- a/client/src/Providers/ChatContext.tsx
+++ b/client/src/Providers/ChatContext.tsx
@@ -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';
diff --git a/client/src/Providers/ChatSettingsContext.tsx b/client/src/Providers/ChatSettingsContext.tsx
index 6a33a29821..24f78c7261 100644
--- a/client/src/Providers/ChatSettingsContext.tsx
+++ b/client/src/Providers/ChatSettingsContext.tsx
@@ -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);
diff --git a/client/src/common/types.ts b/client/src/common/types.ts
index f03493d51a..b50ccc7b96 100644
--- a/client/src/common/types.ts
+++ b/client/src/common/types.ts
@@ -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 = {
diff --git a/client/src/components/Chat/Input/__tests__/ChatForm.queryParams.spec.tsx b/client/src/components/Chat/Input/__tests__/ChatForm.queryParams.spec.tsx
index c99187df1b..5d9a4f9e2d 100644
--- a/client/src/components/Chat/Input/__tests__/ChatForm.queryParams.spec.tsx
+++ b/client/src/components/Chat/Input/__tests__/ChatForm.queryParams.spec.tsx
@@ -80,7 +80,10 @@ function Harness({
messagesKey: 'new',
latestMessageId: undefined,
latestMessageDepth: undefined,
+ subscribeMessages: () => () => undefined,
+ getMessagesRevision: () => 0,
useLiveAttachments: () => ({}),
+ getMappingOptions: () => ({}),
feedbackEnabled: false,
setMessages: () => undefined,
ask: onAsk,
diff --git a/client/src/components/Chat/Subagents/SubagentConversation.test.tsx b/client/src/components/Chat/Subagents/SubagentConversation.test.tsx
index 7e1f7571c4..ee9ff02699 100644
--- a/client/src/components/Chat/Subagents/SubagentConversation.test.tsx
+++ b/client/src/components/Chat/Subagents/SubagentConversation.test.tsx
@@ -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,
diff --git a/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx b/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx
index 8affd7f2f5..3b80a7bbc7 100644
--- a/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx
+++ b/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx
@@ -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(),
diff --git a/client/src/hooks/Chat/__tests__/abort.spec.tsx b/client/src/hooks/Chat/__tests__/abort.spec.tsx
index 5e2c063ca2..1635ad5c21 100644
--- a/client/src/hooks/Chat/__tests__/abort.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/abort.spec.tsx
@@ -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),
};
diff --git a/client/src/hooks/Chat/__tests__/contract.spec.tsx b/client/src/hooks/Chat/__tests__/contract.spec.tsx
index 98447f19cd..61d3ffca38 100644
--- a/client/src/hooks/Chat/__tests__/contract.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/contract.spec.tsx
@@ -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),
}),
diff --git a/client/src/hooks/Chat/__tests__/facade.spec.tsx b/client/src/hooks/Chat/__tests__/facade.spec.tsx
index 186dc4e79d..db4eaaa058 100644
--- a/client/src/hooks/Chat/__tests__/facade.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/facade.spec.tsx
@@ -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(
diff --git a/client/src/hooks/Chat/__tests__/feedback.spec.tsx b/client/src/hooks/Chat/__tests__/feedback.spec.tsx
index 1671fd9729..5d306d1f66 100644
--- a/client/src/hooks/Chat/__tests__/feedback.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/feedback.spec.tsx
@@ -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', () => {
diff --git a/client/src/hooks/Chat/__tests__/provider.spec.tsx b/client/src/hooks/Chat/__tests__/provider.spec.tsx
index ea3d16c08d..25e7ff5d08 100644
--- a/client/src/hooks/Chat/__tests__/provider.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/provider.spec.tsx
@@ -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,
diff --git a/client/src/hooks/Chat/__tests__/transport.spec.tsx b/client/src/hooks/Chat/__tests__/transport.spec.tsx
index f611e612b0..8a83f7f1cf 100644
--- a/client/src/hooks/Chat/__tests__/transport.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/transport.spec.tsx
@@ -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),
});
diff --git a/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx b/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx
index aef6500bc8..bb41bf5341 100644
--- a/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx
@@ -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', () => {
diff --git a/client/src/hooks/Chat/cache.ts b/client/src/hooks/Chat/cache.ts
index b07ab2398c..3361ed5fbf 100644
--- a/client/src/hooks/Chat/cache.ts
+++ b/client/src/hooks/Chat/cache.ts
@@ -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,
+ };
+}
diff --git a/client/src/hooks/Chat/contract.ts b/client/src/hooks/Chat/contract.ts
index 20b73dd2d9..90d07dd308 100644
--- a/client/src/hooks/Chat/contract.ts
+++ b/client/src/hooks/Chat/contract.ts
@@ -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. */
diff --git a/client/src/hooks/Chat/facade.ts b/client/src/hooks/Chat/facade.ts
deleted file mode 100644
index 67560b2ec2..0000000000
--- a/client/src/hooks/Chat/facade.ts
+++ /dev/null
@@ -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/[email protected]` (`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,
- };
-}
diff --git a/client/src/hooks/Chat/outcomes.ts b/client/src/hooks/Chat/outcomes.ts
new file mode 100644
index 0000000000..0e3106b8ca
--- /dev/null
+++ b/client/src/hooks/Chat/outcomes.ts
@@ -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),
+});
diff --git a/client/src/hooks/Chat/provider.tsx b/client/src/hooks/Chat/provider.tsx
index 8213665045..115ffc648d 100644
--- a/client/src/hooks/Chat/provider.tsx
+++ b/client/src/hooks/Chat/provider.tsx
@@ -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);
diff --git a/client/src/hooks/Chat/useChatHelpers.ts b/client/src/hooks/Chat/useChatHelpers.ts
index e32ad1765d..e71910165e 100644
--- a/client/src/hooks/Chat/useChatHelpers.ts
+++ b/client/src/hooks/Chat/useChatHelpers.ts
@@ -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,
],
);
}
diff --git a/client/src/hooks/Chat/useCompactConversation.ts b/client/src/hooks/Chat/useCompactConversation.ts
index 80afaaf4ca..d4804f8c70 100644
--- a/client/src/hooks/Chat/useCompactConversation.ts
+++ b/client/src/hooks/Chat/useCompactConversation.ts
@@ -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);
diff --git a/client/src/hooks/SSE/announcements.ts b/client/src/hooks/SSE/announcements.ts
index 495dbcbc62..ebd97dd2b6 100644
--- a/client/src/hooks/SSE/announcements.ts
+++ b/client/src/hooks/SSE/announcements.ts
@@ -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';
/**
diff --git a/client/src/routes/ChatSettings.tsx b/client/src/routes/ChatSettings.tsx
index 1b6880bd7e..9553e7a702 100644
--- a/client/src/routes/ChatSettings.tsx
+++ b/client/src/routes/ChatSettings.tsx
@@ -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,
diff --git a/client/src/utils/messages.ts b/client/src/utils/messages.ts
index 55794853ee..e929b96406 100644
--- a/client/src/utils/messages.ts
+++ b/client/src/utils/messages.ts
@@ -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. */
diff --git a/packages/chat/src/react.ts b/packages/chat/src/react.ts
index 696138e30a..ad847f02b3 100644
--- a/packages/chat/src/react.ts
+++ b/packages/chat/src/react.ts
@@ -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,
diff --git a/packages/chat/src/react/chat/__tests__/views.spec.ts b/packages/chat/src/react/chat/__tests__/views.spec.ts
new file mode 100644
index 0000000000..6f667ae8d3
--- /dev/null
+++ b/packages/chat/src/react/chat/__tests__/views.spec.ts
@@ -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]);
+ });
+});
diff --git a/packages/chat/src/react/chat/actions.ts b/packages/chat/src/react/chat/actions.ts
new file mode 100644
index 0000000000..fcbc2294ec
--- /dev/null
+++ b/packages/chat/src/react/chat/actions.ts
@@ -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],
+ );
+}
diff --git a/packages/chat/src/react/chat/chat.ts b/packages/chat/src/react/chat/chat.ts
new file mode 100644
index 0000000000..c553b02bf1
--- /dev/null
+++ b/packages/chat/src/react/chat/chat.ts
@@ -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,
+ };
+}
diff --git a/packages/chat/src/react/chat/context.ts b/packages/chat/src/react/chat/context.ts
new file mode 100644
index 0000000000..2e0dfdd548
--- /dev/null
+++ b/packages/chat/src/react/chat/context.ts
@@ -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;
+};
diff --git a/packages/chat/src/react/chat/contract.ts b/packages/chat/src/react/chat/contract.ts
new file mode 100644
index 0000000000..c51dc38692
--- /dev/null
+++ b/packages/chat/src/react/chat/contract.ts
@@ -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;
diff --git a/packages/chat/src/react/chat/index.ts b/packages/chat/src/react/chat/index.ts
new file mode 100644
index 0000000000..3980746748
--- /dev/null
+++ b/packages/chat/src/react/chat/index.ts
@@ -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';
diff --git a/packages/chat/src/react/chat/messages.ts b/packages/chat/src/react/chat/messages.ts
new file mode 100644
index 0000000000..8e698fea19
--- /dev/null
+++ b/packages/chat/src/react/chat/messages.ts
@@ -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;
+ });
+};
diff --git a/client/src/hooks/Chat/resume.ts b/packages/chat/src/react/chat/resume.ts
similarity index 75%
rename from client/src/hooks/Chat/resume.ts
rename to packages/chat/src/react/chat/resume.ts
index ca50ad3d17..b2f9eb9e08 100644
--- a/client/src/hooks/Chat/resume.ts
+++ b/packages/chat/src/react/chat/resume.ts
@@ -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>(),
+);
diff --git a/packages/chat/src/react/chat/status.ts b/packages/chat/src/react/chat/status.ts
new file mode 100644
index 0000000000..40a9a140c1
--- /dev/null
+++ b/packages/chat/src/react/chat/status.ts
@@ -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;
+};
diff --git a/packages/chat/src/react/chat/types.ts b/packages/chat/src/react/chat/types.ts
new file mode 100644
index 0000000000..fd52f8b9e9
--- /dev/null
+++ b/packages/chat/src/react/chat/types.ts
@@ -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/[email protected]` (`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'
+>;
diff --git a/packages/chat/src/react/chat/views.ts b/packages/chat/src/react/chat/views.ts
new file mode 100644
index 0000000000..9076e3e6c5
--- /dev/null
+++ b/packages/chat/src/react/chat/views.ts
@@ -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;
+};