📎 refactor: Move Stream Content and Attachment Handlers Into the Chat Package (#17559)

This commit is contained in:
Marco Beretta 2026-10-30 00:22:53 +01:00 • committed by GitHub
parent a493b1a3d7
commit 393e7aed5f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 391 additions and 325 deletions

View file

@ -1,5 +1,5 @@
import { useMemo } from 'react';
import { useAtomValue, useSetAtom } from 'jotai';
import { useSetAtom } from 'jotai';
import { Constants, QueryKeys } from 'librechat-data-provider';
import { hashQueryKey, useQueryClient } from '@tanstack/react-query';
import type { ChatHost, ChatMessageCache, ChatMessagesQuery } from '@librechat/chat/react';
@ -9,7 +9,6 @@ import { useLatestMessage, useLatestMessageId } from '~/hooks/Messages/useLatest
import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/state';
import { useAbortStreamMutation, useGetMessagesByConvoId } from '~/data-provider';
import { useChatSettings } from '~/Providers/ChatSettingsContext';
import { messageAttachmentsMapAtom } from '~/hooks/SSE/atoms';
import { getMappingOptions } from '~/hooks/Chat/outcomes';
import useTurnServices from '~/hooks/Chat/services';
import { useResumeOnLoad } from '~/hooks/SSE';
@ -108,7 +107,6 @@ export const appChatHost: ChatHost = {
* render and would defeat the contract's memo. */
useAbortStream: () => useAbortStreamMutation().mutateAsync,
useMessageCache,
useLiveAttachments: () => useAtomValue(messageAttachmentsMapAtom),
useFeedbackEnabled: () => useChatSettings().config.feedbackEnabled,
getMappingOptions,
useMessages,

View file

@ -1,41 +1,5 @@
import { atom } from 'jotai';
import { atomFamily } from 'jotai/utils';
import type { TAttachment } from 'librechat-data-provider';
/** The run the pane at this index is displaying, renewed by every `created` or resume `sync`;
* audio autoplay keys "already played" on it. */
export const activeRunFamily = atomFamily((_index: string | number | null) =>
atom<string | null>(null),
);
/** Attachments that arrived while a message streamed, by message id, ahead of the saved copy. */
export const messageAttachmentsMapAtom = atom<Record<string, TAttachment[] | undefined>>({});
/** The streamed attachments that belong to one conversation, by message id. */
export const conversationAttachmentsFamily = atomFamily((conversationId: string | undefined) =>
atom((get) => {
if (!conversationId) {
return {};
}
const attachmentsMap = get(messageAttachmentsMapAtom);
const result: Record<string, TAttachment[]> = {};
// Filter to only include attachments for this conversation
Object.entries(attachmentsMap).forEach(([messageId, attachments]) => {
if (!attachments || attachments.length === 0) {
return;
}
const relevantAttachments = attachments.filter(
(attachment) => attachment.conversationId === conversationId,
);
if (relevantAttachments.length > 0) {
result[messageId] = relevantAttachments;
}
});
return result;
}),
);
export {
activeRunFamily,
messageAttachmentsMapAtom,
conversationAttachmentsFamily,
} from '@librechat/chat/react';

View file

@ -1,189 +1,57 @@
import { useSetAtom } from 'jotai';
import { useCallback } from 'react';
import { QueryKeys, Tools } from 'librechat-data-provider';
import type {
MemoriesResponse,
EventSubmission,
TAttachment,
TFile,
} from 'librechat-data-provider';
import { useAttachmentHandler as useStreamAttachments } from '@librechat/chat/react';
import type { TFile, TAttachment, MemoriesResponse } from 'librechat-data-provider';
import type { AttachmentHandler } from '@librechat/chat/react';
import type { QueryClient } from '@tanstack/react-query';
import { messageAttachmentsMapAtom } from '~/hooks/SSE/atoms';
import { invalidateRecentFiles } from '~/utils/files';
import { handleMemoryArtifact } from '~/utils/memory';
/** Identity of a re-emitted web-search snapshot: its tool call, turn, agent,
* and host step. Scoped to `web_search` because that is the flow whose server
* helper rebuilds and rewrites the whole payload on each highlight. The
* provider reuses ids such as `call_0` across turns and the host can reuse a
* turn number within one message, so the SDK step is part of the identity. */
const searchSnapshotKeyOf = (attachment: TAttachment): string | undefined => {
if (attachment.type !== Tools.web_search) {
return undefined;
}
const toolCallId = (attachment as { toolCallId?: string }).toolCallId;
if (!toolCallId) {
return undefined;
}
const agentId = (attachment as { agentId?: string }).agentId ?? '';
const turn = attachment[Tools.web_search]?.turn;
const stepId = attachment.stepId ?? '';
return `${Tools.web_search}:${agentId}:${toolCallId}:${turn ?? 0}:${stepId}`;
};
export default function useAttachmentHandler(queryClient?: QueryClient) {
const setAttachmentsMap = useSetAtom(messageAttachmentsMapAtom);
return ({ data }: { data: TAttachment; submission: EventSubmission }) => {
const { messageId } = data;
const fileId = (data as Partial<TFile>).file_id;
const fileData = data as TFile;
if (
queryClient &&
fileData?.file_id &&
fileData?.filepath &&
!fileData.filepath.includes('/api/files')
) {
queryClient.setQueryData([QueryKeys.files], (oldData: TFile[] | undefined) => {
if (!oldData) {
return [fileData];
}
const existingIndex = oldData.findIndex((file) => file.file_id === fileData.file_id);
if (existingIndex > -1) {
const updated = [...oldData];
updated[existingIndex] = { ...oldData[existingIndex], ...fileData };
return updated;
}
return [fileData, ...oldData];
});
invalidateRecentFiles(queryClient);
}
if (queryClient && data.type === Tools.memory && data[Tools.memory]) {
const memoryArtifact = data[Tools.memory];
queryClient.setQueryData([QueryKeys.memories], (oldData: MemoriesResponse | undefined) => {
if (!oldData) {
return oldData;
}
return handleMemoryArtifact({ memoryArtifact, currentData: oldData }) || oldData;
});
}
/* Cross-turn filename reuse keeps the same `file_id` across runs.
* If a prior turn left `[QueryKeys.filePreview, file_id]` cached at
* `status: 'ready'`, a new pending attachment would mount against
* that stale cache and `useFilePreview`'s `refetchInterval` (which
* only polls on `pending`) would never start. Drop the cache entry
* entirely so a fresh mount has nothing to read and must fetch.
*
* `removeQueries` (vs the earlier `invalidateQueries`) is the
* stronger fix: invalidate only marks data stale, but
* `refetchOnMount: false` was masking that — the new observer
* read the stale 'ready' value and `refetchInterval` shut polling
* off before it ever started. (Codex P1 round-3 review on
* PR #12957.) */
if (queryClient && fileId) {
queryClient.removeQueries([QueryKeys.filePreview, fileId]);
}
setAttachmentsMap((prevMap) => {
const messageAttachments =
(prevMap as Record<string, TAttachment[] | undefined>)[messageId] || [];
/* Upsert by `file_id` (falling back to `filepath` for keyed entries
* without one, e.g. code download fallbacks a background poll
* re-emits), SCOPED by toolCallId — sibling code calls can share a
* claimed file_id for the same filename, and each card anchors its
* own attachment. The deferred-preview flow emits the same
* attachment twice: first with `status: 'pending'` and `text:
* null`, then again with `status: 'ready'` (and text/textFormat) or
* `'failed'` (with previewError). The second event must merge over
* the first in place — appending would render the artifact card
* twice, once stuck pending and once resolved. Attachments with no
* file key (lightweight types like web_search / file_search
* citations) keep the legacy append behavior. */
const fileKeyOf = (a: TAttachment): string | undefined => {
const { file_id, filepath } = a as Partial<TFile>;
return file_id ?? filepath;
};
const agentIdOf = (a: TAttachment): string | undefined => (a as { agentId?: string }).agentId;
const upsertKey = fileKeyOf(data);
const incomingToolCallId = (data as { toolCallId?: string }).toolCallId;
const incomingAgentId = agentIdOf(data);
if (upsertKey) {
/** A missing toolCallId on either side is a wildcard (deferred-preview
* updates emit bare `{file_id, status}` payloads); only DISTINCT
* toolCallIds keep entries separate — sibling code calls can share a
* claimed file_id and each card anchors its own attachment. The same
* wildcard applies to agentId: handoff agents can repeat provider
* tool ids (`call_0`) AND share a claimed file_id, so distinct
* non-null agentIds must stay separate entries or the second agent's
* event would merge over (and re-badge) the first's. */
const existingIndex = messageAttachments.findIndex((a) => {
if (fileKeyOf(a) !== upsertKey) {
return false;
}
const existingToolCallId = (a as { toolCallId?: string }).toolCallId;
if (
existingToolCallId != null &&
incomingToolCallId != null &&
existingToolCallId !== incomingToolCallId
) {
return false;
}
const existingAgentId = agentIdOf(a);
return (
existingAgentId == null ||
incomingAgentId == null ||
existingAgentId === incomingAgentId
);
});
if (existingIndex > -1) {
const existing = messageAttachments[existingIndex] as Partial<TFile>;
const incoming = data as Partial<TFile>;
const next = { ...existing, ...data } as TAttachment;
/* Don't let a phase-1 replay (finalHandler iterates
* `responseMessage.attachments`, which is the immediate-persist
* snapshot at status:pending) regress a record a deferred
* update has already moved to ready/failed. Pin the terminal
* lifecycle fields when the merge would downgrade. */
if (
(existing.status === 'ready' || existing.status === 'failed') &&
incoming.status === 'pending'
) {
(next as Partial<TFile>).status = existing.status;
(next as Partial<TFile>).text = existing.text;
(next as Partial<TFile>).textFormat = existing.textFormat;
(next as Partial<TFile>).previewError = existing.previewError;
}
const merged = [...messageAttachments];
merged[existingIndex] = next;
return { ...prevMap, [messageId]: merged };
}
/** Keeps the app's file, memory and preview caches in step with a streamed attachment. */
function updateAttachmentCaches(queryClient: QueryClient, data: TAttachment): void {
const fileId = (data as Partial<TFile>).file_id;
const fileData = data as TFile;
if (fileData?.file_id && fileData?.filepath && !fileData.filepath.includes('/api/files')) {
queryClient.setQueryData([QueryKeys.files], (oldData: TFile[] | undefined) => {
if (!oldData) {
return [fileData];
}
/** Search attachments are full snapshots rather than deltas: the server
* re-emits the entire payload after every highlight update, keeping the
* same type, toolCallId and turn. They carry no `file_id`, so the upsert
* above never saw them and each snapshot was appended, stacking one copy
* of every image, product and place per update. Replace the previous
* snapshot in place; a wholesale swap is right because the incoming
* payload is complete. */
const searchSnapshotKey = searchSnapshotKeyOf(data);
if (searchSnapshotKey) {
const existingIndex = messageAttachments.findIndex(
(a) => searchSnapshotKeyOf(a) === searchSnapshotKey,
);
if (existingIndex > -1) {
const merged = [...messageAttachments];
merged[existingIndex] = data;
return { ...prevMap, [messageId]: merged };
}
const existingIndex = oldData.findIndex((file) => file.file_id === fileData.file_id);
if (existingIndex > -1) {
const updated = [...oldData];
updated[existingIndex] = { ...oldData[existingIndex], ...fileData };
return updated;
}
return {
...prevMap,
[messageId]: [...messageAttachments, data],
};
return [fileData, ...oldData];
});
};
invalidateRecentFiles(queryClient);
}
if (data.type === Tools.memory && data[Tools.memory]) {
const memoryArtifact = data[Tools.memory];
queryClient.setQueryData([QueryKeys.memories], (oldData: MemoriesResponse | undefined) => {
if (!oldData) {
return oldData;
}
return handleMemoryArtifact({ memoryArtifact, currentData: oldData }) || oldData;
});
}
/* Cross-turn filename reuse keeps the same `file_id` across runs. If a prior turn left
* `[QueryKeys.filePreview, file_id]` cached at `status: 'ready'`, a new pending attachment
* would mount against that stale cache and `useFilePreview`'s `refetchInterval` (which only
* polls on `pending`) would never start. Removing the entry, rather than invalidating it,
* leaves a fresh mount nothing to read, so it must fetch. */
if (fileId) {
queryClient.removeQueries([QueryKeys.filePreview, fileId]);
}
}
/** The package's streamed attachment handler, with the app's caches kept in step. */
export default function useAttachmentHandler(queryClient?: QueryClient): AttachmentHandler {
const onAttachment = useCallback(
(data: TAttachment) => queryClient && updateAttachmentCaches(queryClient, data),
[queryClient],
);
return useStreamAttachments(onAttachment);
}

View file

@ -1,103 +1,22 @@
import { useCallback, useMemo } from 'react';
import { ContentTypes } from 'librechat-data-provider';
import { useCallback } from 'react';
import { useQueryClient } from '@tanstack/react-query';
import type {
Text,
TMessage,
ImageFile,
ContentPart,
PartMetadata,
ChatContentFrame,
EventSubmission,
TMessageContentParts,
} from 'librechat-data-provider';
import { useContentHandler as useStreamContent } from '@librechat/chat/react';
import type { TMessage, ImageFile, PartMetadata } from 'librechat-data-provider';
import type { ContentHandlers } from '@librechat/chat/react';
import { addFileToCache } from '~/utils';
type TUseContentHandler = {
/** The package's content-frame handler, caching streamed image files in the app's file list. */
export default function useContentHandler({
setMessages,
getMessages,
}: {
setMessages: (messages: TMessage[]) => void;
getMessages: () => TMessage[] | undefined;
};
type TContentHandler = {
data: ChatContentFrame;
submission: EventSubmission;
};
export default function useContentHandler({ setMessages, getMessages }: TUseContentHandler) {
}): ContentHandlers {
const queryClient = useQueryClient();
const messageMap = useMemo(() => new Map<string, TMessage>(), []);
/** Reset the message map - call this after sync to prevent stale state from overwriting synced content */
const resetMessageMap = useCallback(() => {
messageMap.clear();
}, [messageMap]);
const handler = useCallback(
({ data, submission }: TContentHandler) => {
const { type, messageId, thread_id, conversationId, index } = data;
const _messages = getMessages() ?? [];
const messages: TMessage[] = [];
let existingMessage: TMessage | undefined;
for (const msg of _messages) {
if (msg.messageId === messageId) {
existingMessage ??= msg;
continue;
}
messages.push(
thread_id == null || msg.thread_id === thread_id ? msg : { ...msg, thread_id },
);
}
const userMessage = messages[messages.length - 1] as TMessage | undefined;
const { initialResponse } = submission;
let response = messageMap.get(messageId);
if (!response) {
const responseBase = existingMessage ?? (initialResponse as TMessage);
const responseThreadId =
thread_id ?? responseBase.thread_id ?? (initialResponse as TMessage).thread_id;
response = {
...responseBase,
parentMessageId: userMessage?.messageId ?? '',
conversationId,
messageId,
...(responseThreadId != null ? { thread_id: responseThreadId } : {}),
};
messageMap.set(messageId, response);
}
// TODO: handle streaming for non-text
const textPart: Text | string | undefined = data[ContentTypes.TEXT];
const part: ContentPart =
textPart != null && typeof textPart === 'string' ? { value: textPart } : data[type];
if (type === ContentTypes.IMAGE_FILE) {
addFileToCache(queryClient, part as ImageFile & PartMetadata);
}
/* spreading the content array to avoid mutation */
response.content = [...(response.content ?? [])];
response.content[index] = { type, [type]: part } as TMessageContentParts;
const lastContentPart = response.content[response.content.length - 1];
const initialContentPart = initialResponse.content?.[0];
if (
type !== ContentTypes.TEXT &&
initialContentPart != null &&
lastContentPart != null &&
((lastContentPart.type === ContentTypes.TOOL_CALL &&
lastContentPart[ContentTypes.TOOL_CALL]?.progress === 1) ||
lastContentPart.type === ContentTypes.IMAGE_FILE)
) {
response.content.push(initialContentPart);
}
setMessages([...messages, response]);
},
[queryClient, getMessages, messageMap, setMessages],
const onImageFile = useCallback(
(file: ImageFile & PartMetadata) => addFileToCache(queryClient, file),
[queryClient],
);
return { contentHandler: handler, resetContentHandler: resetMessageMap };
return useStreamContent({ setMessages, getMessages, onImageFile });
}

View file

@ -34,7 +34,6 @@ jest.mock('../../steering/useSteerConvert', () => ({
}));
const noop = () => undefined;
const noLiveAttachments = {};
const turnServices = createTurnServices();
const cache: ChatMessageCache = {
read: () => undefined,
@ -56,7 +55,6 @@ const createHost = (conversation: TConversation | null): ChatHost => ({
useSetSiblingIdx: () => noop,
useAbortStream: () => mockAbortStream,
useMessageCache: () => cache,
useLiveAttachments: () => noLiveAttachments,
useFeedbackEnabled: () => false,
getMappingOptions: () => ({}),
useMessages: () => ({ messages: null, isLoading: false, isFetching: false }),

View file

@ -5,6 +5,7 @@ import type { MouseEvent } from 'react';
import type { ChatContract } from './contract';
import { isSubmittingFamily, submissionByIndex, useIsSubmitting } from '../submission';
import { presetFamily, filesFamily, optionSettingsFamily } from '../pane';
import { useLiveAttachments } from '../stream/atoms';
import { abortScrollFamily } from '../generation';
import { getMessageCacheIds } from './cache';
import { useStopGenerating } from './stop';
@ -167,7 +168,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 = host.useFeedbackEnabled();
const { getMappingOptions, useLiveAttachments } = host;
const { getMappingOptions } = host;
return useMemo(
(): ChatContract => ({
@ -238,7 +239,6 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
setFilesLoading,
feedbackEnabled,
getMappingOptions,
useLiveAttachments,
],
);
}

View file

@ -179,8 +179,6 @@ export interface ChatHost {
/** Stops a resumable generation. */
useAbortStream(): (params: AbortStreamParams) => Promise<AbortStreamResponse>;
useMessageCache(): ChatMessageCache;
/** Attachments delivered by message id ahead of the message cache. Stable across renders. */
useLiveAttachments(): Record<string, TAttachment[] | undefined>;
/** Whether message feedback controls are on. */
useFeedbackEnabled(): boolean;
/** The app's tool outcome rules for viewing one message; see {@link ChatContract}. */

View file

@ -0,0 +1,55 @@
import { atomFamily } from 'jotai/utils';
import { atom, useAtomValue } from 'jotai';
import type { TAttachment } from 'librechat-data-provider';
import type { Atom, PrimitiveAtom } from 'jotai';
import type { Family } from '../steer/family';
/** The run the pane at this index is displaying, renewed by every `created` or resume `sync`;
* audio autoplay keys "already played" on it. */
export const activeRunFamily: Family<
string | null,
PrimitiveAtom<string | null>,
string | number | null
> = atomFamily((_index: string | number | null) => atom<string | null>(null));
/** Attachments that arrived while a message streamed, by message id, ahead of the saved copy. */
export const messageAttachmentsMapAtom: PrimitiveAtom<Record<string, TAttachment[] | undefined>> =
atom<Record<string, TAttachment[] | undefined>>({});
/** The streamed attachments that belong to one conversation, by message id. */
export const conversationAttachmentsFamily: Family<
Record<string, TAttachment[]>,
Atom<Record<string, TAttachment[]>>,
string | undefined
> = atomFamily((conversationId: string | undefined) =>
atom((get) => {
if (!conversationId) {
return {};
}
const attachmentsMap = get(messageAttachmentsMapAtom);
const result: Record<string, TAttachment[]> = {};
// Filter to only include attachments for this conversation
Object.entries(attachmentsMap).forEach(([messageId, attachments]) => {
if (!attachments || attachments.length === 0) {
return;
}
const relevantAttachments = attachments.filter(
(attachment) => attachment.conversationId === conversationId,
);
if (relevantAttachments.length > 0) {
result[messageId] = relevantAttachments;
}
});
return result;
}),
);
/** Attachments delivered by message id ahead of the message cache. */
export function useLiveAttachments(): Record<string, TAttachment[] | undefined> {
return useAtomValue(messageAttachmentsMapAtom);
}

View file

@ -0,0 +1,141 @@
import { useSetAtom } from 'jotai';
import { Tools } from 'librechat-data-provider';
import type { EventSubmission, TAttachment, TFile } from 'librechat-data-provider';
import { messageAttachmentsMapAtom } from './atoms';
/** Identity of a re-emitted web-search snapshot: its tool call, turn, agent,
* and host step. Scoped to `web_search` because that is the flow whose server
* helper rebuilds and rewrites the whole payload on each highlight. The
* provider reuses ids such as `call_0` across turns and the host can reuse a
* turn number within one message, so the SDK step is part of the identity. */
const searchSnapshotKeyOf = (attachment: TAttachment): string | undefined => {
if (attachment.type !== Tools.web_search) {
return undefined;
}
const toolCallId = (attachment as { toolCallId?: string }).toolCallId;
if (!toolCallId) {
return undefined;
}
const agentId = (attachment as { agentId?: string }).agentId ?? '';
const turn = attachment[Tools.web_search]?.turn;
const stepId = attachment.stepId ?? '';
return `${Tools.web_search}:${agentId}:${toolCallId}:${turn ?? 0}:${stepId}`;
};
/** Applies one streamed attachment event. */
export type AttachmentHandler = (event: { data: TAttachment; submission: EventSubmission }) => void;
/**
* Collects attachments that arrive while a message streams, by message id, ahead of the saved
* copy. `onAttachment` lets the host update its own caches (file lists, memories, previews) for
* each event before it is merged.
*/
export function useAttachmentHandler(
onAttachment?: (attachment: TAttachment) => void,
): AttachmentHandler {
const setAttachmentsMap = useSetAtom(messageAttachmentsMapAtom);
return ({ data }) => {
const { messageId } = data;
onAttachment?.(data);
setAttachmentsMap((prevMap) => {
const messageAttachments =
(prevMap as Record<string, TAttachment[] | undefined>)[messageId] || [];
/* Upsert by `file_id` (falling back to `filepath` for keyed entries
* without one, e.g. code download fallbacks a background poll
* re-emits), SCOPED by toolCallId: sibling code calls can share a
* claimed file_id for the same filename, and each card anchors its
* own attachment. The deferred-preview flow emits the same
* attachment twice: first with `status: 'pending'` and `text:
* null`, then again with `status: 'ready'` (and text/textFormat) or
* `'failed'` (with previewError). The second event must merge over
* the first in place; appending would render the artifact card
* twice, once stuck pending and once resolved. Attachments with no
* file key (lightweight types like web_search / file_search
* citations) keep the legacy append behavior. */
const fileKeyOf = (a: TAttachment): string | undefined => {
const { file_id, filepath } = a as Partial<TFile>;
return file_id ?? filepath;
};
const agentIdOf = (a: TAttachment): string | undefined => (a as { agentId?: string }).agentId;
const upsertKey = fileKeyOf(data);
const incomingToolCallId = (data as { toolCallId?: string }).toolCallId;
const incomingAgentId = agentIdOf(data);
if (upsertKey) {
/** A missing toolCallId on either side is a wildcard (deferred-preview
* updates emit bare `{file_id, status}` payloads); only DISTINCT
* toolCallIds keep entries separate: sibling code calls can share a
* claimed file_id and each card anchors its own attachment. The same
* wildcard applies to agentId: handoff agents can repeat provider
* tool ids (`call_0`) AND share a claimed file_id, so distinct
* non-null agentIds must stay separate entries or the second agent's
* event would merge over (and re-badge) the first's. */
const existingIndex = messageAttachments.findIndex((a) => {
if (fileKeyOf(a) !== upsertKey) {
return false;
}
const existingToolCallId = (a as { toolCallId?: string }).toolCallId;
if (
existingToolCallId != null &&
incomingToolCallId != null &&
existingToolCallId !== incomingToolCallId
) {
return false;
}
const existingAgentId = agentIdOf(a);
return (
existingAgentId == null ||
incomingAgentId == null ||
existingAgentId === incomingAgentId
);
});
if (existingIndex > -1) {
const existing = messageAttachments[existingIndex] as Partial<TFile>;
const incoming = data as Partial<TFile>;
const next = { ...existing, ...data } as TAttachment;
/* Don't let a phase-1 replay (finalHandler iterates
* `responseMessage.attachments`, which is the immediate-persist
* snapshot at status:pending) regress a record a deferred
* update has already moved to ready/failed. Pin the terminal
* lifecycle fields when the merge would downgrade. */
if (
(existing.status === 'ready' || existing.status === 'failed') &&
incoming.status === 'pending'
) {
(next as Partial<TFile>).status = existing.status;
(next as Partial<TFile>).text = existing.text;
(next as Partial<TFile>).textFormat = existing.textFormat;
(next as Partial<TFile>).previewError = existing.previewError;
}
const merged = [...messageAttachments];
merged[existingIndex] = next;
return { ...prevMap, [messageId]: merged };
}
}
/** Search attachments are full snapshots rather than deltas: the server
* re-emits the entire payload after every highlight update, keeping the
* same type, toolCallId and turn. They carry no `file_id`, so the upsert
* above never saw them and each snapshot was appended, stacking one copy
* of every image, product and place per update. Replace the previous
* snapshot in place; a wholesale swap is right because the incoming
* payload is complete. */
const searchSnapshotKey = searchSnapshotKeyOf(data);
if (searchSnapshotKey) {
const existingIndex = messageAttachments.findIndex(
(a) => searchSnapshotKeyOf(a) === searchSnapshotKey,
);
if (existingIndex > -1) {
const merged = [...messageAttachments];
merged[existingIndex] = data;
return { ...prevMap, [messageId]: merged };
}
}
return {
...prevMap,
[messageId]: [...messageAttachments, data],
};
});
};
}

View file

@ -0,0 +1,115 @@
import { useCallback, useMemo } from 'react';
import { ContentTypes } from 'librechat-data-provider';
import type {
Text,
TMessage,
ImageFile,
ContentPart,
PartMetadata,
ChatContentFrame,
EventSubmission,
TMessageContentParts,
} from 'librechat-data-provider';
type TUseContentHandler = {
setMessages: (messages: TMessage[]) => void;
getMessages: () => TMessage[] | undefined;
/** Lets the host cache an image file a content frame carries. */
onImageFile?: (file: ImageFile & PartMetadata) => void;
};
type TContentHandler = {
data: ChatContentFrame;
submission: EventSubmission;
};
/** Applies the Assistants stream's content frames to the response they belong to. */
export type ContentHandlers = {
contentHandler: (event: TContentHandler) => void;
/** Call after a sync so stale responses cannot overwrite the synced content. */
resetContentHandler: () => void;
};
export function useContentHandler({
setMessages,
getMessages,
onImageFile,
}: TUseContentHandler): ContentHandlers {
const messageMap = useMemo(() => new Map<string, TMessage>(), []);
/** Reset the message map - call this after sync to prevent stale state from overwriting synced content */
const resetMessageMap = useCallback(() => {
messageMap.clear();
}, [messageMap]);
const handler = useCallback(
({ data, submission }: TContentHandler) => {
const { type, messageId, thread_id, conversationId, index } = data;
const _messages = getMessages() ?? [];
const messages: TMessage[] = [];
let existingMessage: TMessage | undefined;
for (const msg of _messages) {
if (msg.messageId === messageId) {
existingMessage ??= msg;
continue;
}
messages.push(
thread_id == null || msg.thread_id === thread_id ? msg : { ...msg, thread_id },
);
}
const userMessage = messages[messages.length - 1] as TMessage | undefined;
const { initialResponse } = submission;
let response = messageMap.get(messageId);
if (!response) {
const responseBase = existingMessage ?? (initialResponse as TMessage);
const responseThreadId =
thread_id ?? responseBase.thread_id ?? (initialResponse as TMessage).thread_id;
response = {
...responseBase,
parentMessageId: userMessage?.messageId ?? '',
conversationId,
messageId,
...(responseThreadId != null ? { thread_id: responseThreadId } : {}),
};
messageMap.set(messageId, response);
}
// TODO: handle streaming for non-text
/** A frame carries its part under its own type's key, e.g. `text` for a text frame. */
const parts = data as Partial<Record<ContentTypes, Text | ContentPart | string>>;
const textPart = parts[ContentTypes.TEXT];
const part = (
textPart != null && typeof textPart === 'string' ? { value: textPart } : parts[type]
) as ContentPart;
if (type === ContentTypes.IMAGE_FILE) {
onImageFile?.(part as ImageFile & PartMetadata);
}
/* spreading the content array to avoid mutation */
response.content = [...(response.content ?? [])];
response.content[index] = { type, [type]: part } as TMessageContentParts;
const lastContentPart = response.content[response.content.length - 1];
const initialContentPart = initialResponse.content?.[0];
if (
type !== ContentTypes.TEXT &&
initialContentPart != null &&
lastContentPart != null &&
((lastContentPart.type === ContentTypes.TOOL_CALL &&
lastContentPart[ContentTypes.TOOL_CALL]?.progress === 1) ||
lastContentPart.type === ContentTypes.IMAGE_FILE)
) {
response.content.push(initialContentPart);
}
setMessages([...messages, response]);
},
[getMessages, messageMap, setMessages, onImageFile],
);
return { contentHandler: handler, resetContentHandler: resetMessageMap };
}

View file

@ -3,6 +3,16 @@ export { default as useResumableSSE } from './resumable';
export { StreamHostProvider, useStreamHost } from './host';
export { useStepHandler } from './step';
export { useUsageHandler } from './usage';
export { useContentHandler } from './content';
export { useAttachmentHandler } from './attachments';
export {
activeRunFamily,
useLiveAttachments,
messageAttachmentsMapAtom,
conversationAttachmentsFamily,
} from './atoms';
export type { ContentHandlers } from './content';
export type { AttachmentHandler } from './attachments';
export type { UsageHandlers } from './usage';
export type { StepHandlers } from './step';
export { sandboxStartingByToolCallId } from './sandbox';