Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
📎 refactor: Move Stream Content and Attachment Handlers Into the Chat Package (#17559)
Marco Beretta393e7aed5f32
diff --git a/client/src/Providers/ChatHostContext.tsx b/client/src/Providers/ChatHostContext.tsxindex ae6778a1a3..266640873e 100644--- a/client/src/Providers/ChatHostContext.tsx+++ b/client/src/Providers/ChatHostContext.tsx@@ -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/useLatestimport { 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,diff --git a/client/src/hooks/SSE/atoms.ts b/client/src/hooks/SSE/atoms.tsindex a1ec8127a1..30ac22a69a 100644--- a/client/src/hooks/SSE/atoms.ts+++ b/client/src/hooks/SSE/atoms.ts@@ -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';diff --git a/client/src/hooks/SSE/useAttachmentHandler.ts b/client/src/hooks/SSE/useAttachmentHandler.tsindex 5501e91936..ae6736a39b 100644--- a/client/src/hooks/SSE/useAttachmentHandler.ts+++ b/client/src/hooks/SSE/useAttachmentHandler.ts@@ -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;+/** 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];+ }+ 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);}- 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 };- }+ if (data.type === Tools.memory && data[Tools.memory]) {+ const memoryArtifact = data[Tools.memory];+ queryClient.setQueryData([QueryKeys.memories], (oldData: MemoriesResponse | undefined) => {+ if (!oldData) {+ return oldData;}- /** 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],- };+ 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);}diff --git a/client/src/hooks/SSE/useContentHandler.ts b/client/src/hooks/SSE/useContentHandler.tsindex 84309bf886..ec17432e9a 100644--- a/client/src/hooks/SSE/useContentHandler.ts+++ b/client/src/hooks/SSE/useContentHandler.ts@@ -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 });}diff --git a/packages/chat/src/react/chat/__tests__/stop.spec.tsx b/packages/chat/src/react/chat/__tests__/stop.spec.tsxindex e5406f1ef6..4f9846ec20 100644--- a/packages/chat/src/react/chat/__tests__/stop.spec.tsx+++ b/packages/chat/src/react/chat/__tests__/stop.spec.tsx@@ -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 }),diff --git a/packages/chat/src/react/chat/helpers.ts b/packages/chat/src/react/chat/helpers.tsindex 7f70c72113..6546fda813 100644--- a/packages/chat/src/react/chat/helpers.ts+++ b/packages/chat/src/react/chat/helpers.ts@@ -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): ChatContracsetFilesLoading,feedbackEnabled,getMappingOptions,- useLiveAttachments,],);}diff --git a/packages/chat/src/react/chat/host.tsx b/packages/chat/src/react/chat/host.tsxindex 9b4111d6c6..9e9684fee2 100644--- a/packages/chat/src/react/chat/host.tsx+++ b/packages/chat/src/react/chat/host.tsx@@ -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}. */diff --git a/packages/chat/src/react/stream/atoms.ts b/packages/chat/src/react/stream/atoms.tsnew file mode 100644index 0000000000..e95336ec39--- /dev/null+++ b/packages/chat/src/react/stream/atoms.ts@@ -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);+}diff --git a/packages/chat/src/react/stream/attachments.ts b/packages/chat/src/react/stream/attachments.tsnew file mode 100644index 0000000000..2c33d1618a--- /dev/null+++ b/packages/chat/src/react/stream/attachments.ts@@ -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],+ };+ });+ };+}diff --git a/packages/chat/src/react/stream/content.ts b/packages/chat/src/react/stream/content.tsnew file mode 100644index 0000000000..7e2fadf7d8--- /dev/null+++ b/packages/chat/src/react/stream/content.ts@@ -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 };+}diff --git a/packages/chat/src/react/stream/index.ts b/packages/chat/src/react/stream/index.tsindex fc609d77b8..3f1e533f71 100644--- a/packages/chat/src/react/stream/index.ts+++ b/packages/chat/src/react/stream/index.ts@@ -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';