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 Error Turn and Title Helpers into Chat Core (#17658)

Marco Beretta06ddf0a2ab39
diff --git a/client/src/common/types.ts b/client/src/common/types.ts
index e699daf10f..1c7166a48a 100644
--- a/client/src/common/types.ts
+++ b/client/src/common/types.ts
@@ -462,25 +462,7 @@ export type TLoginLayoutContext = {
export type ConvoGenerator = (params: NewConversationParams) => void | t.TConversation;
-export type TBaseResData = {
- final?: boolean;
- initial?: boolean;
- previousMessages?: t.TMessage[];
- conversation: t.TConversation;
- conversationId?: string;
- runMessages?: t.TMessage[];
-};
-
-export type TResData = TBaseResData & {
- requestMessage: t.TMessage;
- responseMessage: t.TMessage;
-};
-
-export type TFinalResData = Omit<TBaseResData, 'conversation'> & {
- conversation: Partial<t.TConversation> & Pick<t.TConversation, 'conversationId'>;
- requestMessage?: t.TMessage;
- responseMessage?: t.TMessage;
-};
+export type { TResData, TBaseResData, TFinalResData } from '@librechat/chat';
declare global {
interface Window {
diff --git a/client/src/hooks/SSE/turns.ts b/client/src/hooks/SSE/turns.ts
index 5b503234cb..18f45c1028 100644
--- a/client/src/hooks/SSE/turns.ts
+++ b/client/src/hooks/SSE/turns.ts
@@ -1,243 +1,16 @@
-import { v4 } from 'uuid';
-import { useQueryClient } from '@tanstack/react-query';
-import { responseParentMessageId } from '@librechat/chat';
-import { QueryKeys, ContentTypes, tMessageSchema } from 'librechat-data-provider';
-import type {
- TMessage,
- TConversation,
- EventSubmission,
- TMessageContentParts,
-} from 'librechat-data-provider';
-import type { ConvoTitleState } from '~/utils/convos';
-import type { TResData } from '~/common';
-import {
- hasRealTitle,
- findConvoInAllQueries,
- findManualConvoTitleInAllQueries,
- preserveStreamedContentIdentity,
- isEmptyContentPart,
- getPartKeyIndex,
-} from '~/utils';
-
-const CONNECTION_ERROR_TEXT = 'Error connecting to server, try refreshing the page.';
-
-/**
- * The parts the in-flight response has streamed so far: the transcript's tail (a user row there
- * means no response was placed), without the holes an interrupted stream leaves. Whether anything
- * streamed is judged without the slots that never received content (a comparison run's
- * `type: ''` placeholders, a text or think part opened before its first delta), but once something
- * did, those slots stay: a placeholder is what keeps a comparison lane's layout and attribution
- * when only the other lane produced output. The parts carry the render identity they streamed
- * under, as the final path stamps it, so the settled row does not remount.
- */
-const getStreamedContent = (message?: TMessage): TMessageContentParts[] => {
- if (message == null || message.isCreatedByUser === true) {
- return [];
- }
- const streamed = message.content ?? [];
- const parts = streamed.filter((part): part is TMessageContentParts => part != null);
- if (!parts.some((part) => !isEmptyContentPart(part))) {
- return [];
- }
- return preserveStreamedContentIdentity(streamed, parts) ?? parts;
-};
-
-/** Keys the appended failure past every key the kept parts render under, physical or stamped. */
-const appendErrorPart = (
- content: TMessageContentParts[],
- errorText: string,
-): TMessageContentParts[] => {
- const keyIndex = content.reduce(
- (next, part, idx) => Math.max(next, getPartKeyIndex(part, idx) + 1),
- 0,
- );
- const errorPart: TMessageContentParts = { type: ContentTypes.ERROR, error: errorText };
- return [
- ...content,
- keyIndex === content.length ? errorPart : { ...errorPart, streamedIndex: keyIndex },
- ];
-};
-
-/**
- * A failure that lands after the run has streamed keeps what streamed and takes the failure as
- * one more part, the way the server records a failure inside a run; one that lands before
- * anything streamed is the whole row.
- */
-export const createErrorMessage = ({
- errorMetadata,
- getMessages,
- submission,
- error,
-}: {
- getMessages: () => TMessage[] | undefined;
- errorMetadata?: Partial<TMessage>;
- submission: EventSubmission;
- error?: Error | unknown;
-}): TMessage => {
- const currentMessages = getMessages();
- const latestMessage = currentMessages?.[currentMessages.length - 1];
- const text = submission.initialResponse.text.length > 45 ? submission.initialResponse.text : '';
- const errorText =
- (errorMetadata?.text || text || (error as Error | undefined)?.message) ??
- 'Error cancelling request';
- const streamedContent = getStreamedContent(latestMessage);
- if (latestMessage?.conversationId && latestMessage.messageId && streamedContent.length > 0) {
- /** The row keeps the envelope it streamed under (author, model, icon, creation time) and
- * takes from the failure only what describes the failure: a server payload names `System`
- * as its sender and the schema dates a fresh envelope now, neither of which applies to a
- * response that is merely gaining a part. */
- const errorMessage: TMessage = {
- ...latestMessage,
- ...(errorMetadata?.metadata != null
- ? { metadata: { ...latestMessage.metadata, ...errorMetadata.metadata } }
- : {}),
- error: undefined,
- text: '',
- content: appendErrorPart(streamedContent, errorText),
- };
- const parentMessageId = responseParentMessageId(
- submission.initialResponse,
- submission.userMessage,
- submission.isRegenerate,
- );
- if (parentMessageId && parentMessageId !== errorMessage.parentMessageId) {
- errorMessage.parentMessageId = parentMessageId;
- }
- return errorMessage;
- }
- if (errorMetadata) {
- return errorMetadata as TMessage;
- }
- return tMessageSchema.parse({
- ...submission,
- ...submission.initialResponse,
- text: errorText,
- unfinished: !!text.length,
- error: true,
- }) as TMessage;
-};
-
-export interface ErrorTurn {
- conversationId: string;
- errorResponse: TMessage;
- /** The conversation must be rebuilt: it never learned its id, the transport failed, or the
- * server named a conversation the new-chat route has not navigated to. */
- recover: boolean;
-}
-
-/** Builds the row a failed turn leaves in the transcript and names the conversation it belongs to. */
-type SettledErrorReadState = {
- lastResponseAt: string;
- lastResponseMessageId?: string;
- updatedAt?: string;
-};
-
-/**
- * A persisted terminal error still carries the server's winning reply stamp in its nested
- * conversation snapshot. Pairing the error messages cache object with that stamp before the list
- * update lets `useConversationSeen` acknowledge the reply the user just watched fail, instead of
- * leaving a dot on a conversation they are looking at.
- */
-export const resolveSettledErrorReadState = ({
- data,
- submission,
- conversationId,
-}: {
- data?: TResData;
- submission: EventSubmission;
- conversationId: string;
-}): SettledErrorReadState | undefined => {
- if (submission.isTemporary === true || !data || !conversationId) {
- return undefined;
- }
- const settledConversation = data.conversation;
- const lastResponseAt = settledConversation?.lastResponseAt;
- if (typeof lastResponseAt !== 'string' || lastResponseAt.length === 0) {
- return undefined;
- }
- return {
- lastResponseAt,
- lastResponseMessageId:
- typeof settledConversation.lastResponseMessageId === 'string'
- ? settledConversation.lastResponseMessageId
- : undefined,
- updatedAt:
- typeof settledConversation.updatedAt === 'string' ? settledConversation.updatedAt : undefined,
- };
-};
-
-export const resolveErrorTurn = ({
- data,
- submission,
- getMessages,
- isNewConversationRoute,
-}: {
- data?: TResData;
- submission: EventSubmission;
- getMessages: () => TMessage[] | undefined;
- isNewConversationRoute: boolean;
-}): ErrorTurn => {
- const { userMessage, initialResponse } = submission;
- const parentMessageId = responseParentMessageId(
- initialResponse,
- userMessage,
- submission.isRegenerate,
- );
- const conversationId =
- userMessage.conversationId ?? submission.conversation?.conversationId ?? '';
-
- const parseErrorResponse = (payload: TResData | Partial<TMessage>): TMessage => {
- const metadata = payload['responseMessage'] ?? payload;
- const errorMessage: Partial<TMessage> = {
- ...initialResponse,
- ...metadata,
- error: true,
- parentMessageId,
- };
-
- if (errorMessage.messageId === undefined || errorMessage.messageId === '') {
- errorMessage.messageId = v4();
- }
-
- return tMessageSchema.parse(errorMessage) as TMessage;
- };
- const build = (errorMetadata: TMessage): TMessage =>
- createErrorMessage({ errorMetadata, getMessages, submission });
-
- if (!data) {
- const convoId = conversationId || `_${v4()}`;
- return {
- conversationId: convoId,
- recover: true,
- errorResponse: build(
- parseErrorResponse({ text: CONNECTION_ERROR_TEXT, ...submission, conversationId: convoId }),
- ),
- };
- }
-
- const receivedConvoId = data.conversationId ?? '';
- if (!conversationId && !receivedConvoId) {
- return {
- conversationId: `_${v4()}`,
- recover: true,
- errorResponse: build(parseErrorResponse(data)),
- };
- }
- if (!receivedConvoId) {
- return { conversationId, recover: false, errorResponse: build(parseErrorResponse(data)) };
- }
- return {
- conversationId: receivedConvoId,
- recover: isNewConversationRoute,
- errorResponse: build(
- tMessageSchema.parse({
- ...data,
- error: true,
- parentMessageId,
- }) as TMessage,
- ),
- };
-};
+import { selectConvoTitle } from '@librechat/chat';
+import { QueryKeys } from 'librechat-data-provider';
+import type { TConversation } from 'librechat-data-provider';
+import type { QueryClient } from '@tanstack/react-query';
+import type { ConvoTitleState } from '@librechat/chat';
+import { findConvoInAllQueries, findManualConvoTitleInAllQueries } from '~/utils';
+
+export {
+ createErrorMessage,
+ resolveErrorTurn,
+ resolveSettledErrorReadState,
+} from '@librechat/chat';
+export type { ErrorTurn } from '@librechat/chat';
export const getConvoTitle = ({
queryClient,
@@ -247,7 +20,7 @@ export const getConvoTitle = ({
titleRevision,
authoritative = false,
}: {
- queryClient: ReturnType<typeof useQueryClient>;
+ queryClient: QueryClient;
currentTitle?: string | null;
conversationId?: string | null;
titleSetByUser?: boolean;
@@ -258,24 +31,11 @@ export const getConvoTitle = ({
if (!conversationId) {
return incoming;
}
- const cached = queryClient.getQueryData<TConversation>([QueryKeys.conversation, conversationId]);
- const owned = findManualConvoTitleInAllQueries(queryClient, conversationId, incoming);
- const listed = owned ? undefined : findConvoInAllQueries(queryClient, conversationId);
- let selected = owned;
- if (!selected) {
- if (authoritative && hasRealTitle(incoming.title)) {
- selected = incoming;
- } else if (hasRealTitle(cached?.title)) {
- selected = cached;
- } else if (hasRealTitle(listed?.title)) {
- selected = listed;
- } else {
- selected = incoming;
- }
- }
- return {
- title: selected?.title ?? null,
- titleSetByUser: selected?.titleSetByUser,
- titleRevision: selected?.titleRevision,
- };
+ return selectConvoTitle({
+ incoming,
+ authoritative,
+ cached: queryClient.getQueryData<TConversation>([QueryKeys.conversation, conversationId]),
+ findManual: (state) => findManualConvoTitleInAllQueries(queryClient, conversationId, state),
+ findListed: () => findConvoInAllQueries(queryClient, conversationId),
+ });
};
diff --git a/client/src/hooks/SSE/useEventHandlers.ts b/client/src/hooks/SSE/useEventHandlers.ts
index 22206a9388..e9904857d6 100644
--- a/client/src/hooks/SSE/useEventHandlers.ts
+++ b/client/src/hooks/SSE/useEventHandlers.ts
@@ -1,9 +1,9 @@
import { useCallback, useEffect, useRef } from 'react';
import { useStore, useSetAtom } from 'jotai';
import { QueryKeys } from 'librechat-data-provider';
-import { buildRecoveryPreset } from '@librechat/chat';
import { useQueryClient } from '@tanstack/react-query';
import { useParams, useNavigate, useLocation } from 'react-router-dom';
+import { buildRecoveryPreset, shouldResetSubagentAtomsOnConversationChange } from '@librechat/chat';
import {
useStepHandler,
submissionStartFamily,
@@ -17,7 +17,6 @@ import type { ConvoGenerator } from '~/common';
import useFocusRegeneratedResponse from '~/hooks/Chat/useFocusRegeneratedResponse';
import { useReconcileConversationCodeEnvironmentMutation } from '~/data-provider';
import { getFailedCodeDecisionRequest } from '~/hooks/Agents/codeDecision';
-import { shouldResetSubagentAtomsOnConversationChange } from './cleanup';
import useAttachmentHandler from '~/hooks/SSE/useAttachmentHandler';
import useContentHandler from '~/hooks/SSE/useContentHandler';
import { useApplyAgentTemplate } from '~/hooks/Agents';
diff --git a/client/src/utils/convos.ts b/client/src/utils/convos.ts
index 0e9db68673..6d75ac02f0 100644
--- a/client/src/utils/convos.ts
+++ b/client/src/utils/convos.ts
@@ -13,6 +13,7 @@ import {
import type { TConversation, TMessage, GroupedConversations } from 'librechat-data-provider';
import type { InvalidateQueryFilters } from '@tanstack/react-query';
import type { InfiniteData, Query } from '@tanstack/react-query';
+import type { ConvoTitleState } from '@librechat/chat';
import { isTemporaryConversation } from './conversation';
import { getSessionPrincipal } from './session';
@@ -1466,7 +1467,7 @@ export function findConvoInAllQueries(
)?.convo;
}
-export type ConvoTitleState = Pick<TConversation, 'title' | 'titleSetByUser' | 'titleRevision'>;
+export type { ConvoTitleState };
/** Manual revisions are monotonic even when reply snapshots or request order disagree. */
export function findManualConvoTitleInAllQueries(
diff --git a/client/src/utils/documentTitle.ts b/client/src/utils/documentTitle.ts
index 13ae8be9bf..1939ea4f47 100644
--- a/client/src/utils/documentTitle.ts
+++ b/client/src/utils/documentTitle.ts
@@ -6,8 +6,7 @@ let documentTitleRevision = 0;
export const getDocumentTitleRevision = (): number => documentTitleRevision;
-export const hasRealTitle = (title?: string | null): title is string =>
- title != null && title !== '' && title !== 'New Chat';
+export { hasRealTitle } from '@librechat/chat';
const getAppTitle = (): string => {
try {
diff --git a/client/src/utils/messages.ts b/client/src/utils/messages.ts
index df83431834..9c523925c2 100644
--- a/client/src/utils/messages.ts
+++ b/client/src/utils/messages.ts
@@ -1,22 +1,26 @@
-import { isEmptyContentPart } from '@librechat/chat/react';
import { getBranchSiblingIndexesForTarget } from '@librechat/chat';
import { QueryKeys, Constants, buildTree, ContentTypes } from 'librechat-data-provider';
import {
+ getPartKeyIndex,
+ isEmptyContentPart,
hasStreamStartFailed,
stripStreamedIndexStamps,
createDualMessageContent,
+ preserveStreamedContentIdentity,
STREAM_START_FAILED_METADATA_KEY,
} from '@librechat/chat';
-import type { Agents, TMessage, TMessageContentParts } from 'librechat-data-provider';
+import type { TMessage, TMessageContentParts } from 'librechat-data-provider';
import type { BranchSiblingIndex } from '@librechat/chat';
import type { QueryClient } from '@tanstack/react-query';
import type { LocalizeFunction, TMessageProps } from '~/common';
export {
+ getPartKeyIndex,
isEmptyContentPart,
hasStreamStartFailed,
stripStreamedIndexStamps,
createDualMessageContent,
+ preserveStreamedContentIdentity,
STREAM_START_FAILED_METADATA_KEY,
};
export const TEXT_KEY_DIVIDER = '|||';
@@ -149,159 +153,6 @@ export const getAllContentText = (message?: TMessage | null): string => {
return '';
};
-const getPartTextValue = (value?: string | { value?: string }): string =>
- (typeof value === 'string' ? value : value?.value) ?? '';
-
-const getPartToolCall = (part: TMessageContentParts): Agents.ToolCall | undefined =>
- part.type === ContentTypes.TOOL_CALL
- ? (part[ContentTypes.TOOL_CALL] as Agents.ToolCall | undefined)
- : undefined;
-
-/** 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. */
-const isMutualPrefix = (streamed: string, final: string): boolean =>
- final.startsWith(streamed) || streamed.startsWith(final);
-
-/** Identity match, not equality: the persisted part may carry richer content
- * (flushed text, tool output) than its streamed counterpart, and updating a
- * kept identity in place is exactly the point. Content still has to agree as
- * an extension of what streamed: a filtered run (`hide_sequential_outputs`)
- * omits intermediate parts from the final array, and a type-only match would
- * hand the retained output an omitted intermediate's identity. */
-const isSameStreamedPart = (
- streamed: TMessageContentParts,
- final: TMessageContentParts,
-): boolean => {
- if (streamed.type !== final.type) {
- return false;
- }
- if (streamed.type === ContentTypes.TOOL_CALL) {
- const streamedCall = getPartToolCall(streamed);
- const finalCall = getPartToolCall(final);
- if (streamedCall?.id != null && finalCall?.id != null) {
- return streamedCall.id === finalCall.id;
- }
- if (streamedCall?.name != null && finalCall?.name != null) {
- return streamedCall.name === finalCall.name;
- }
- return true;
- }
- if (streamed.type === ContentTypes.TEXT && final.type === ContentTypes.TEXT) {
- if ((streamed.phase ?? null) !== (final.phase ?? null)) {
- return false;
- }
- return isMutualPrefix(getPartTextValue(streamed.text), getPartTextValue(final.text));
- }
- if (streamed.type === ContentTypes.THINK && final.type === ContentTypes.THINK) {
- return isMutualPrefix(getPartTextValue(streamed.think), getPartTextValue(final.think));
- }
- if (streamed.type === ContentTypes.ACTIVITY_LABEL && final.type === ContentTypes.ACTIVITY_LABEL) {
- if ((streamed.activity_label_type ?? null) !== (final.activity_label_type ?? null)) {
- return false;
- }
- return isMutualPrefix(
- getPartTextValue(streamed.activity_label),
- getPartTextValue(final.activity_label),
- );
- }
- return true;
-};
-
-/**
- * Stamps each part of a final (persisted, compacted) content array with the
- * index it occupied while it streamed, pairing the two arrays in order.
- *
- * The aggregator writes parts at provider-source indexes, so the streamed
- * array is sparse wherever a step produced nothing; persistence compacts the
- * holes away and every later part shifts down. Adopting the compacted array
- * verbatim re-keys every index-derived React identity at the final event —
- * the settled message remounts wholesale, entrance animations replay, and the
- * thread visibly jumps. The stamp (`streamedIndex`) lets renderers keep the
- * streamed key while all coordinate logic uses the compacted positions the
- * server persisted.
- *
- * Pairing is all-or-nothing: a partially stamped array could collide a
- * streamed key with a compacted fallback key. When any final part has no
- * streamed counterpart (server-enriched content), or any substantial streamed
- * part has no final counterpart (a filtered run that dropped intermediate
- * outputs — where in-order pairing could hand a retained part an omitted
- * part's identity), the final array is returned untouched and the message
- * re-keys as before.
- */
-export const preserveStreamedContentIdentity = (
- streamedContent: Array<TMessageContentParts | undefined> | undefined,
- finalContent: TMessage['content'],
-): TMessage['content'] => {
- if (!streamedContent?.length || !finalContent?.length) {
- return finalContent;
- }
-
- let cursor = 0;
- let stamped: TMessageContentParts[] | null = null;
- for (let index = 0; index < finalContent.length; index++) {
- const finalPart = finalContent[index] as TMessageContentParts | undefined;
- if (finalPart == null) {
- return finalContent;
- }
- let matchedIndex = -1;
- let matchedPart: TMessageContentParts | null = null;
- while (cursor < streamedContent.length) {
- const streamedPart = streamedContent[cursor];
- if (streamedPart == null) {
- cursor += 1;
- continue;
- }
- /** An empty streamed slot facing a filled final part was dropped by the
- * compaction — never let it steal the match from the filled streamed
- * part behind it (an empty THINK ahead of the real one, say). */
- if (isEmptyContentPart(streamedPart) && !isEmptyContentPart(finalPart)) {
- cursor += 1;
- continue;
- }
- if (isSameStreamedPart(streamedPart, finalPart)) {
- matchedIndex = cursor;
- matchedPart = streamedPart;
- cursor += 1;
- }
- break;
- }
- if (matchedIndex === -1 || matchedPart == null) {
- return finalContent;
- }
- /** A settled message can be re-delivered by a LATER final event (e.g. an
- * Assistants run resyncing prior turns): both sides arrive compact, but
- * the current parts already carry stamps from their own settle. Carrying
- * them forward keeps their keys stable forever, instead of silently
- * reverting the identity this stamp exists to preserve. */
- const stampIndex = matchedPart.streamedIndex ?? matchedIndex;
- if (stampIndex !== index && stamped == null) {
- stamped = [...finalContent];
- }
- if (stamped != null && stampIndex !== index) {
- stamped[index] = { ...finalPart, streamedIndex: stampIndex };
- }
- }
- /** Leftover substantial streamed parts mean the server REMOVED content
- * (`hide_sequential_outputs`), so every pairing above is suspect — an
- * omitted intermediate that happens to prefix the retained output would
- * have claimed its identity. Only holes and empty slots may remain. */
- for (let rest = cursor; rest < streamedContent.length; rest++) {
- const leftover = streamedContent[rest];
- if (leftover != null && !isEmptyContentPart(leftover)) {
- return finalContent;
- }
- }
- return stamped ?? finalContent;
-};
-
-/** Render-identity index for content-part keys: the streamed position stamped
- * by the final handler survives the sparse→compact swap; everything else keys
- * by the live index. Coordinate logic (edit indexes, phase bounds, cursor)
- * must keep using the live index. */
-export const getPartKeyIndex = (part: TMessageContentParts | undefined, idx: number): number =>
- part?.streamedIndex ?? idx;
-
export { isSubmittableMessage } from '@librechat/chat';
export const markStreamStartFailedMetadata = (
diff --git a/client/src/hooks/SSE/__tests__/cleanup.spec.ts b/packages/chat/src/core/__tests__/reset.spec.ts
similarity index 99%
rename from client/src/hooks/SSE/__tests__/cleanup.spec.ts
rename to packages/chat/src/core/__tests__/reset.spec.ts
index 235d1cabde..7e2379c0b1 100644
--- a/client/src/hooks/SSE/__tests__/cleanup.spec.ts
+++ b/packages/chat/src/core/__tests__/reset.spec.ts
@@ -1,5 +1,5 @@
import { Constants } from 'librechat-data-provider';
-import { shouldResetSubagentAtomsOnConversationChange } from '../cleanup';
+import { shouldResetSubagentAtomsOnConversationChange } from '../turns/reset';
describe('subagent atom cleanup', () => {
it('preserves live subagent atoms when the active new chat receives its saved id', () => {
diff --git a/packages/chat/src/core/__tests__/title.spec.ts b/packages/chat/src/core/__tests__/title.spec.ts
new file mode 100644
index 0000000000..39dd01f68d
--- /dev/null
+++ b/packages/chat/src/core/__tests__/title.spec.ts
@@ -0,0 +1,54 @@
+import type { ConvoTitleState } from '../turns/title';
+import { hasRealTitle, selectConvoTitle } from '../turns/title';
+
+const none = (): ConvoTitleState | undefined => undefined;
+
+describe('selectConvoTitle', () => {
+ it('keeps a title the user set over every other source', () => {
+ const manual = { title: 'Mine', titleSetByUser: true, titleRevision: 3 };
+ const findListed = jest.fn(none);
+ expect(
+ selectConvoTitle({
+ incoming: { title: 'Generated' },
+ authoritative: true,
+ cached: { title: 'Cached' },
+ findManual: () => manual,
+ findListed,
+ }),
+ ).toEqual(manual);
+ expect(findListed).not.toHaveBeenCalled();
+ });
+
+ it('takes an authoritative incoming title over the cached one', () => {
+ expect(
+ selectConvoTitle({
+ incoming: { title: 'Server' },
+ authoritative: true,
+ cached: { title: 'Cached' },
+ findManual: none,
+ findListed: none,
+ }).title,
+ ).toBe('Server');
+ });
+
+ it('falls back from the cached entry to the listed one to the incoming one', () => {
+ const base = { incoming: { title: 'New Chat' }, findManual: none };
+ expect(selectConvoTitle({ ...base, cached: { title: 'Cached' }, findListed: none }).title).toBe(
+ 'Cached',
+ );
+ expect(
+ selectConvoTitle({ ...base, cached: { title: '' }, findListed: () => ({ title: 'Listed' }) })
+ .title,
+ ).toBe('Listed');
+ expect(selectConvoTitle({ ...base, cached: null, findListed: none }).title).toBe('New Chat');
+ });
+});
+
+describe('hasRealTitle', () => {
+ it('rejects empty and placeholder titles', () => {
+ expect(hasRealTitle('Plans')).toBe(true);
+ expect(hasRealTitle('New Chat')).toBe(false);
+ expect(hasRealTitle('')).toBe(false);
+ expect(hasRealTitle(null)).toBe(false);
+ });
+});
diff --git a/packages/chat/src/core/content.ts b/packages/chat/src/core/content.ts
index 0d2be69f5b..9d51c8b1a9 100644
--- a/packages/chat/src/core/content.ts
+++ b/packages/chat/src/core/content.ts
@@ -1,10 +1,12 @@
import {
+ ContentTypes,
isEphemeralAgentId,
getEphemeralSender,
appendAgentIdSuffix,
encodeEphemeralAgentId,
} from 'librechat-data-provider';
import type {
+ Agents,
TMessage,
TConversation,
TEndpointsConfig,
@@ -132,3 +134,175 @@ export const createDualMessageContent = (
// that will be replaced by real content with proper types from the server
return [primaryContent, addedContent] as unknown as TMessageContentParts[];
};
+
+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;
+};
+
+const getPartToolCall = (part: TMessageContentParts): Agents.ToolCall | undefined =>
+ part.type === ContentTypes.TOOL_CALL
+ ? (part[ContentTypes.TOOL_CALL] as Agents.ToolCall | undefined)
+ : undefined;
+
+/** 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. */
+const isMutualPrefix = (streamed: string, final: string): boolean =>
+ final.startsWith(streamed) || streamed.startsWith(final);
+
+/** Identity match, not equality: the persisted part may carry richer content
+ * (flushed text, tool output) than its streamed counterpart, and updating a
+ * kept identity in place is exactly the point. Content still has to agree as
+ * an extension of what streamed: a filtered run (`hide_sequential_outputs`)
+ * omits intermediate parts from the final array, and a type-only match would
+ * hand the retained output an omitted intermediate's identity. */
+const isSameStreamedPart = (
+ streamed: TMessageContentParts,
+ final: TMessageContentParts,
+): boolean => {
+ if (streamed.type !== final.type) {
+ return false;
+ }
+ if (streamed.type === ContentTypes.TOOL_CALL) {
+ const streamedCall = getPartToolCall(streamed);
+ const finalCall = getPartToolCall(final);
+ if (streamedCall?.id != null && finalCall?.id != null) {
+ return streamedCall.id === finalCall.id;
+ }
+ if (streamedCall?.name != null && finalCall?.name != null) {
+ return streamedCall.name === finalCall.name;
+ }
+ return true;
+ }
+ if (streamed.type === ContentTypes.TEXT && final.type === ContentTypes.TEXT) {
+ if ((streamed.phase ?? null) !== (final.phase ?? null)) {
+ return false;
+ }
+ return isMutualPrefix(getPartTextValue(streamed.text), getPartTextValue(final.text));
+ }
+ if (streamed.type === ContentTypes.THINK && final.type === ContentTypes.THINK) {
+ return isMutualPrefix(getPartTextValue(streamed.think), getPartTextValue(final.think));
+ }
+ if (streamed.type === ContentTypes.ACTIVITY_LABEL && final.type === ContentTypes.ACTIVITY_LABEL) {
+ if ((streamed.activity_label_type ?? null) !== (final.activity_label_type ?? null)) {
+ return false;
+ }
+ return isMutualPrefix(
+ getPartTextValue(streamed.activity_label),
+ getPartTextValue(final.activity_label),
+ );
+ }
+ return true;
+};
+
+/**
+ * Stamps each part of a final (persisted, compacted) content array with the
+ * index it occupied while it streamed, pairing the two arrays in order.
+ *
+ * The aggregator writes parts at provider-source indexes, so the streamed
+ * array is sparse wherever a step produced nothing; persistence compacts the
+ * holes away and every later part shifts down. Adopting the compacted array
+ * verbatim re-keys every index-derived React identity at the final event:
+ * the settled message remounts wholesale, entrance animations replay, and the
+ * thread visibly jumps. The stamp (`streamedIndex`) lets renderers keep the
+ * streamed key while all coordinate logic uses the compacted positions the
+ * server persisted.
+ *
+ * Pairing is all-or-nothing: a partially stamped array could collide a
+ * streamed key with a compacted fallback key. When any final part has no
+ * streamed counterpart (server-enriched content), or any substantial streamed
+ * part has no final counterpart (a filtered run that dropped intermediate
+ * outputs, where in-order pairing could hand a retained part an omitted
+ * part's identity), the final array is returned untouched and the message
+ * re-keys as before.
+ */
+export const preserveStreamedContentIdentity = (
+ streamedContent: Array<TMessageContentParts | undefined> | undefined,
+ finalContent: TMessage['content'],
+): TMessage['content'] => {
+ if (!streamedContent?.length || !finalContent?.length) {
+ return finalContent;
+ }
+
+ let cursor = 0;
+ let stamped: TMessageContentParts[] | null = null;
+ for (let index = 0; index < finalContent.length; index++) {
+ const finalPart = finalContent[index] as TMessageContentParts | undefined;
+ if (finalPart == null) {
+ return finalContent;
+ }
+ let matchedIndex = -1;
+ let matchedPart: TMessageContentParts | null = null;
+ while (cursor < streamedContent.length) {
+ const streamedPart = streamedContent[cursor];
+ if (streamedPart == null) {
+ cursor += 1;
+ continue;
+ }
+ /** An empty streamed slot facing a filled final part was dropped by the
+ * compaction; never let it steal the match from the filled streamed
+ * part behind it (an empty THINK ahead of the real one, say). */
+ if (isEmptyContentPart(streamedPart) && !isEmptyContentPart(finalPart)) {
+ cursor += 1;
+ continue;
+ }
+ if (isSameStreamedPart(streamedPart, finalPart)) {
+ matchedIndex = cursor;
+ matchedPart = streamedPart;
+ cursor += 1;
+ }
+ break;
+ }
+ if (matchedIndex === -1 || matchedPart == null) {
+ return finalContent;
+ }
+ /** A settled message can be re-delivered by a LATER final event (e.g. an
+ * Assistants run resyncing prior turns): both sides arrive compact, but
+ * the current parts already carry stamps from their own settle. Carrying
+ * them forward keeps their keys stable forever, instead of silently
+ * reverting the identity this stamp exists to preserve. */
+ const stampIndex = matchedPart.streamedIndex ?? matchedIndex;
+ if (stampIndex !== index && stamped == null) {
+ stamped = [...finalContent];
+ }
+ if (stamped != null && stampIndex !== index) {
+ stamped[index] = { ...finalPart, streamedIndex: stampIndex };
+ }
+ }
+ /** Leftover substantial streamed parts mean the server REMOVED content
+ * (`hide_sequential_outputs`), so every pairing above is suspect: an
+ * omitted intermediate that happens to prefix the retained output would
+ * have claimed its identity. Only holes and empty slots may remain. */
+ for (let rest = cursor; rest < streamedContent.length; rest++) {
+ const leftover = streamedContent[rest];
+ if (leftover != null && !isEmptyContentPart(leftover)) {
+ return finalContent;
+ }
+ }
+ return stamped ?? finalContent;
+};
+
+/** Render-identity index for content-part keys: the streamed position stamped
+ * by the final handler survives the sparse→compact swap; everything else keys
+ * by the live index. Coordinate logic (edit indexes, phase bounds, cursor)
+ * must keep using the live index. */
+export const getPartKeyIndex = (part: TMessageContentParts | undefined, idx: number): number =>
+ part?.streamedIndex ?? idx;
diff --git a/packages/chat/src/core/turns/errors.ts b/packages/chat/src/core/turns/errors.ts
new file mode 100644
index 0000000000..d3c370d5e6
--- /dev/null
+++ b/packages/chat/src/core/turns/errors.ts
@@ -0,0 +1,227 @@
+import { v4 } from 'uuid';
+import { ContentTypes, tMessageSchema } from 'librechat-data-provider';
+import type { TMessage, EventSubmission, TMessageContentParts } from 'librechat-data-provider';
+import type { TResData } from './types';
+import { getPartKeyIndex, isEmptyContentPart, preserveStreamedContentIdentity } from '../content';
+import { responseParentMessageId } from '../resumable/messages';
+
+const CONNECTION_ERROR_TEXT = 'Error connecting to server, try refreshing the page.';
+
+/**
+ * The parts the in-flight response has streamed so far: the transcript's tail (a user row there
+ * means no response was placed), without the holes an interrupted stream leaves. Whether anything
+ * streamed is judged without the slots that never received content (a comparison run's
+ * `type: ''` placeholders, a text or think part opened before its first delta), but once something
+ * did, those slots stay: a placeholder is what keeps a comparison lane's layout and attribution
+ * when only the other lane produced output. The parts carry the render identity they streamed
+ * under, as the final path stamps it, so the settled row does not remount.
+ */
+const getStreamedContent = (message?: TMessage): TMessageContentParts[] => {
+ if (message == null || message.isCreatedByUser === true) {
+ return [];
+ }
+ const streamed = message.content ?? [];
+ const parts = streamed.filter((part): part is TMessageContentParts => part != null);
+ if (!parts.some((part) => !isEmptyContentPart(part))) {
+ return [];
+ }
+ return preserveStreamedContentIdentity(streamed, parts) ?? parts;
+};
+
+/** Keys the appended failure past every key the kept parts render under, physical or stamped. */
+const appendErrorPart = (
+ content: TMessageContentParts[],
+ errorText: string,
+): TMessageContentParts[] => {
+ const keyIndex = content.reduce(
+ (next, part, idx) => Math.max(next, getPartKeyIndex(part, idx) + 1),
+ 0,
+ );
+ const errorPart: TMessageContentParts = { type: ContentTypes.ERROR, error: errorText };
+ return [
+ ...content,
+ keyIndex === content.length ? errorPart : { ...errorPart, streamedIndex: keyIndex },
+ ];
+};
+
+/**
+ * A failure that lands after the run has streamed keeps what streamed and takes the failure as
+ * one more part, the way the server records a failure inside a run; one that lands before
+ * anything streamed is the whole row.
+ */
+export const createErrorMessage = ({
+ errorMetadata,
+ getMessages,
+ submission,
+ error,
+}: {
+ getMessages: () => TMessage[] | undefined;
+ errorMetadata?: Partial<TMessage>;
+ submission: EventSubmission;
+ error?: Error | unknown;
+}): TMessage => {
+ const currentMessages = getMessages();
+ const latestMessage = currentMessages?.[currentMessages.length - 1];
+ const text = submission.initialResponse.text.length > 45 ? submission.initialResponse.text : '';
+ const errorText =
+ (errorMetadata?.text || text || (error as Error | undefined)?.message) ??
+ 'Error cancelling request';
+ const streamedContent = getStreamedContent(latestMessage);
+ if (latestMessage?.conversationId && latestMessage.messageId && streamedContent.length > 0) {
+ /** The row keeps the envelope it streamed under (author, model, icon, creation time) and
+ * takes from the failure only what describes the failure: a server payload names `System`
+ * as its sender and the schema dates a fresh envelope now, neither of which applies to a
+ * response that is merely gaining a part. */
+ const errorMessage: TMessage = {
+ ...latestMessage,
+ ...(errorMetadata?.metadata != null
+ ? { metadata: { ...latestMessage.metadata, ...errorMetadata.metadata } }
+ : {}),
+ error: undefined,
+ text: '',
+ content: appendErrorPart(streamedContent, errorText),
+ };
+ const parentMessageId = responseParentMessageId(
+ submission.initialResponse,
+ submission.userMessage,
+ submission.isRegenerate,
+ );
+ if (parentMessageId && parentMessageId !== errorMessage.parentMessageId) {
+ errorMessage.parentMessageId = parentMessageId;
+ }
+ return errorMessage;
+ }
+ if (errorMetadata) {
+ return errorMetadata as TMessage;
+ }
+ return tMessageSchema.parse({
+ ...submission,
+ ...submission.initialResponse,
+ text: errorText,
+ unfinished: !!text.length,
+ error: true,
+ }) as TMessage;
+};
+
+export interface ErrorTurn {
+ conversationId: string;
+ errorResponse: TMessage;
+ /** The conversation must be rebuilt: it never learned its id, the transport failed, or the
+ * server named a conversation the new-chat route has not navigated to. */
+ recover: boolean;
+}
+
+/** Builds the row a failed turn leaves in the transcript and names the conversation it belongs to. */
+type SettledErrorReadState = {
+ lastResponseAt: string;
+ lastResponseMessageId?: string;
+ updatedAt?: string;
+};
+
+/**
+ * A persisted terminal error still carries the server's winning reply stamp in its nested
+ * conversation snapshot. Pairing the error messages cache object with that stamp before the list
+ * update lets `useConversationSeen` acknowledge the reply the user just watched fail, instead of
+ * leaving a dot on a conversation they are looking at.
+ */
+export const resolveSettledErrorReadState = ({
+ data,
+ submission,
+ conversationId,
+}: {
+ data?: TResData;
+ submission: EventSubmission;
+ conversationId: string;
+}): SettledErrorReadState | undefined => {
+ if (submission.isTemporary === true || !data || !conversationId) {
+ return undefined;
+ }
+ const settledConversation = data.conversation;
+ const lastResponseAt = settledConversation?.lastResponseAt;
+ if (typeof lastResponseAt !== 'string' || lastResponseAt.length === 0) {
+ return undefined;
+ }
+ return {
+ lastResponseAt,
+ lastResponseMessageId:
+ typeof settledConversation.lastResponseMessageId === 'string'
+ ? settledConversation.lastResponseMessageId
+ : undefined,
+ updatedAt:
+ typeof settledConversation.updatedAt === 'string' ? settledConversation.updatedAt : undefined,
+ };
+};
+
+export const resolveErrorTurn = ({
+ data,
+ submission,
+ getMessages,
+ isNewConversationRoute,
+}: {
+ data?: TResData;
+ submission: EventSubmission;
+ getMessages: () => TMessage[] | undefined;
+ isNewConversationRoute: boolean;
+}): ErrorTurn => {
+ const { userMessage, initialResponse } = submission;
+ const parentMessageId = responseParentMessageId(
+ initialResponse,
+ userMessage,
+ submission.isRegenerate,
+ );
+ const conversationId =
+ userMessage.conversationId ?? submission.conversation?.conversationId ?? '';
+
+ const parseErrorResponse = (payload: TResData | Partial<TMessage>): TMessage => {
+ const metadata =
+ ('responseMessage' in payload ? payload.responseMessage : undefined) ?? payload;
+ const errorMessage: Partial<TMessage> = {
+ ...initialResponse,
+ ...metadata,
+ error: true,
+ parentMessageId,
+ };
+
+ if (errorMessage.messageId === undefined || errorMessage.messageId === '') {
+ errorMessage.messageId = v4();
+ }
+
+ return tMessageSchema.parse(errorMessage) as TMessage;
+ };
+ const build = (errorMetadata: TMessage): TMessage =>
+ createErrorMessage({ errorMetadata, getMessages, submission });
+
+ if (!data) {
+ const convoId = conversationId || `_${v4()}`;
+ return {
+ conversationId: convoId,
+ recover: true,
+ errorResponse: build(
+ parseErrorResponse({ text: CONNECTION_ERROR_TEXT, ...submission, conversationId: convoId }),
+ ),
+ };
+ }
+
+ const receivedConvoId = data.conversationId ?? '';
+ if (!conversationId && !receivedConvoId) {
+ return {
+ conversationId: `_${v4()}`,
+ recover: true,
+ errorResponse: build(parseErrorResponse(data)),
+ };
+ }
+ if (!receivedConvoId) {
+ return { conversationId, recover: false, errorResponse: build(parseErrorResponse(data)) };
+ }
+ return {
+ conversationId: receivedConvoId,
+ recover: isNewConversationRoute,
+ errorResponse: build(
+ tMessageSchema.parse({
+ ...data,
+ error: true,
+ parentMessageId,
+ }) as TMessage,
+ ),
+ };
+};
diff --git a/packages/chat/src/core/turns/index.ts b/packages/chat/src/core/turns/index.ts
index 96baf5c4b9..b09aa038a1 100644
--- a/packages/chat/src/core/turns/index.ts
+++ b/packages/chat/src/core/turns/index.ts
@@ -2,3 +2,6 @@ export * from './types';
export * from './build';
export * from './draft';
export * from './regenerate';
+export * from './errors';
+export * from './title';
+export * from './reset';
diff --git a/client/src/hooks/SSE/cleanup.ts b/packages/chat/src/core/turns/reset.ts
similarity index 100%
rename from client/src/hooks/SSE/cleanup.ts
rename to packages/chat/src/core/turns/reset.ts
diff --git a/packages/chat/src/core/turns/title.ts b/packages/chat/src/core/turns/title.ts
new file mode 100644
index 0000000000..4cebddcafa
--- /dev/null
+++ b/packages/chat/src/core/turns/title.ts
@@ -0,0 +1,50 @@
+import type { TConversation } from 'librechat-data-provider';
+
+/** The title fields a conversation carries and a stream reconciles. */
+export type ConvoTitleState = Pick<TConversation, 'title' | 'titleSetByUser' | 'titleRevision'>;
+
+export const hasRealTitle = (title?: string | null): title is string =>
+ title != null && title !== '' && title !== 'New Chat';
+
+/** Where a stream looks for a title the app already holds for the conversation. */
+export type ConvoTitleSources = {
+ /** The conversation's own cached entry. */
+ cached?: ConvoTitleState | null;
+ /** The newest title a user set, across the app's caches and the incoming one. */
+ findManual: (incoming: ConvoTitleState) => ConvoTitleState | undefined;
+ /** The conversation as the app's lists hold it; read only when no user title exists. */
+ findListed: () => ConvoTitleState | undefined;
+};
+
+/**
+ * Picks the title a stream frame settles on: a title the user set wins, then the incoming one when
+ * it is authoritative, then the first real title among the cached entry, the listed entry and the
+ * incoming one.
+ */
+export function selectConvoTitle({
+ incoming,
+ authoritative = false,
+ cached,
+ findManual,
+ findListed,
+}: ConvoTitleSources & { incoming: ConvoTitleState; authoritative?: boolean }): ConvoTitleState {
+ const owned = findManual(incoming);
+ const listed = owned ? undefined : findListed();
+ let selected = owned;
+ if (!selected) {
+ if (authoritative && hasRealTitle(incoming.title)) {
+ selected = incoming;
+ } else if (hasRealTitle(cached?.title)) {
+ selected = cached ?? undefined;
+ } else if (hasRealTitle(listed?.title)) {
+ selected = listed;
+ } else {
+ selected = incoming;
+ }
+ }
+ return {
+ title: selected?.title ?? null,
+ titleSetByUser: selected?.titleSetByUser,
+ titleRevision: selected?.titleRevision,
+ };
+}
diff --git a/packages/chat/src/core/turns/types.ts b/packages/chat/src/core/turns/types.ts
index 47ff178300..f66b4bf926 100644
--- a/packages/chat/src/core/turns/types.ts
+++ b/packages/chat/src/core/turns/types.ts
@@ -85,3 +85,26 @@ export type TRegenerateFunction = (
target: RegenerateTarget,
options?: { addedConvo?: TConversation | null },
) => void;
+
+/** The body a stream handler receives with a turn's messages. */
+export type TBaseResData = {
+ final?: boolean;
+ initial?: boolean;
+ previousMessages?: TMessage[];
+ conversation: TConversation;
+ conversationId?: string;
+ runMessages?: TMessage[];
+};
+
+/** A frame that carries the turn's request and response messages. */
+export type TResData = TBaseResData & {
+ requestMessage: TMessage;
+ responseMessage: TMessage;
+};
+
+/** The final frame, whose conversation may arrive partial. */
+export type TFinalResData = Omit<TBaseResData, 'conversation'> & {
+ conversation: Partial<TConversation> & Pick<TConversation, 'conversationId'>;
+ requestMessage?: TMessage;
+ responseMessage?: TMessage;
+};
diff --git a/packages/chat/src/react/chat/status.ts b/packages/chat/src/react/chat/status.ts
index 40a9a140c1..9e64f03137 100644
--- a/packages/chat/src/react/chat/status.ts
+++ b/packages/chat/src/react/chat/status.ts
@@ -1,28 +1,9 @@
import { ContentTypes } from 'librechat-data-provider';
-import type { Agents, TMessage, TMessageContentParts } from 'librechat-data-provider';
+import type { TMessage } from 'librechat-data-provider';
import type { ChatStatus } from './types';
+import { isEmptyContentPart } from '../../core';
-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;
-};
+export { isEmptyContentPart };
/**
* Placeholder slots (empty text or think, lane placeholders) are not streamed output. A rerun edit