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 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.tsx
index 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/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,
diff --git a/client/src/hooks/SSE/atoms.ts b/client/src/hooks/SSE/atoms.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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): ChatContrac
setFilesLoading,
feedbackEnabled,
getMappingOptions,
- useLiveAttachments,
],
);
}
diff --git a/packages/chat/src/react/chat/host.tsx b/packages/chat/src/react/chat/host.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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';