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: Split useResumableSSE Into Thin Host Bindings (#17133)

Marco Berettadfedc3d8737b
diff --git a/client/src/hooks/SSE/cache.ts b/client/src/hooks/SSE/cache.ts
new file mode 100644
index 0000000000..c8bd965f81
--- /dev/null
+++ b/client/src/hooks/SSE/cache.ts
@@ -0,0 +1,141 @@
+import { useMemo, useCallback } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { Constants, QueryKeys, dataService } from 'librechat-data-provider';
+import {
+ getOptimisticMessages,
+ isInitialNewConversation,
+ hydrateSubmissionMessages,
+ buildOptimisticConversation,
+} from '@librechat/chat';
+import type { TMessage, TSubmission, TConversation } from 'librechat-data-provider';
+import type { ResumableCache } from '@librechat/chat';
+import type { ActiveJobsResponse } from '~/data-provider';
+import {
+ upsertConvoInAllQueries,
+ removeConvoFromAllQueries,
+ invalidateConversationLists,
+} from '~/utils';
+import {
+ queueTitleGeneration,
+ streamStatusQueryKey,
+ fetchConversationMessages,
+} from '~/data-provider';
+import { fetchConvoSnapshot } from '~/utils/convos';
+
+/** The app's query cache, as a resumable run reads and refreshes it. */
+export default function useResumableCache(
+ getMessages: () => TMessage[] | undefined,
+): ResumableCache {
+ const queryClient = useQueryClient();
+
+ /**
+ * Optimistically add a job ID to the active jobs cache.
+ * Called when generation starts.
+ */
+ const addActiveJob = useCallback(
+ (jobId: string) => {
+ queryClient.setQueryData<ActiveJobsResponse>([QueryKeys.activeJobs], (old) => ({
+ activeJobIds: [...new Set([...(old?.activeJobIds ?? []), jobId])],
+ }));
+ },
+ [queryClient],
+ );
+
+ /**
+ * Optimistically remove a job ID from the active jobs cache.
+ * Called when generation completes, aborts, or errors.
+ */
+ const removeActiveJob = useCallback(
+ (jobId: string) => {
+ queryClient.setQueryData<ActiveJobsResponse>([QueryKeys.activeJobs], (old) => ({
+ activeJobIds: (old?.activeJobIds ?? []).filter((id) => id !== jobId),
+ }));
+ },
+ [queryClient],
+ );
+
+ const addOptimisticConversation = useCallback(
+ (conversationId: string, currentSubmission: TSubmission): TSubmission => {
+ if (!isInitialNewConversation(currentSubmission)) {
+ return currentSubmission;
+ }
+
+ const optimisticConversation = buildOptimisticConversation(currentSubmission, conversationId);
+ const optimisticMessages = getOptimisticMessages(
+ currentSubmission,
+ conversationId,
+ getMessages(),
+ );
+
+ queryClient.setQueryData<TConversation>(
+ [QueryKeys.conversation, conversationId],
+ (current) => current ?? optimisticConversation,
+ );
+ queryClient.setQueryData<TMessage[]>(
+ [QueryKeys.messages, conversationId],
+ optimisticMessages,
+ );
+ queryClient.setQueryData<TMessage[]>(
+ [QueryKeys.messages, Constants.NEW_CONVO],
+ optimisticMessages,
+ );
+ upsertConvoInAllQueries(queryClient, optimisticConversation);
+
+ return hydrateSubmissionMessages(currentSubmission, conversationId);
+ },
+ [getMessages, queryClient],
+ );
+
+ return useMemo<ResumableCache>(
+ () => ({
+ invalidateMessages: (conversationId, refetch) =>
+ queryClient.invalidateQueries({
+ queryKey: [QueryKeys.messages, conversationId],
+ refetchType: refetch,
+ }),
+ fetchMessages: (conversationId, fallback) =>
+ queryClient.fetchQuery<TMessage[]>({
+ queryKey: [QueryKeys.messages, conversationId],
+ ...(fallback === true && {
+ // The first stream can finish before CREATED mounts the saved-chat query.
+ queryFn: () => fetchConversationMessages(conversationId),
+ }),
+ }),
+ refreshConversation: (conversationId) =>
+ queryClient.invalidateQueries({
+ queryKey: [QueryKeys.conversation, conversationId],
+ refetchType: 'all',
+ }),
+ refreshConversationLists: () => invalidateConversationLists(queryClient),
+ refreshPinnedConversations: () =>
+ queryClient.invalidateQueries({ queryKey: [QueryKeys.pinnedConversations] }),
+ setStreamStatus: (conversationId, status) =>
+ queryClient.setQueryData(streamStatusQueryKey(conversationId), status),
+ removeStreamStatus: (conversationId) =>
+ queryClient.removeQueries({ queryKey: streamStatusQueryKey(conversationId) }),
+ invalidateStreamStatus: (conversationId) =>
+ queryClient.invalidateQueries({ queryKey: streamStatusQueryKey(conversationId) }),
+ addActiveJob,
+ removeActiveJob,
+ fetchConversation: (conversationId) =>
+ fetchConvoSnapshot(queryClient, conversationId, () =>
+ dataService.getConversationById(conversationId),
+ ),
+ setConversation: (conversationId, conversation) =>
+ queryClient.setQueryData([QueryKeys.conversation, conversationId], conversation),
+ upsertConversation: (conversation) =>
+ upsertConvoInAllQueries(queryClient, conversation, true, 'snapshot'),
+ removeConversation: (conversationId) =>
+ removeConvoFromAllQueries(queryClient, conversationId),
+ getConversation: (conversationId) =>
+ queryClient.getQueryData<TConversation>([QueryKeys.conversation, conversationId]),
+ removeConversationQueries: (conversationId) => {
+ queryClient.removeQueries({ queryKey: [QueryKeys.conversation, conversationId] });
+ queryClient.removeQueries({ queryKey: [QueryKeys.messages, conversationId] });
+ },
+ queueTitleGeneration,
+ addOptimisticConversation,
+ }),
+ [addActiveJob, addOptimisticConversation, queryClient, removeActiveJob],
+ );
+}
diff --git a/client/src/hooks/SSE/events.ts b/client/src/hooks/SSE/events.ts
new file mode 100644
index 0000000000..66a693e184
--- /dev/null
+++ b/client/src/hooks/SSE/events.ts
@@ -0,0 +1,188 @@
+import { useMemo, useState, useCallback } from 'react';
+import { useSetAtom } from 'jotai';
+import { useQueryClient } from '@tanstack/react-query';
+import { getStreamStartFailureText } from '@librechat/chat';
+import { showStopButtonByIndex } from '@librechat/chat/react';
+import type { ResumableRun, ResumableEvents, ResumableUsage } from '@librechat/chat';
+import type { EventSubmission } from 'librechat-data-provider';
+import type { EventHandlerParams } from './useEventHandlers';
+import type { TResData, TFinalResData } from '~/common';
+import { countTrailingOutputChars, markStreamStartFailedMetadata } from '~/utils';
+import { reopenTermsOnRefusal } from '~/utils/terms';
+import useEventHandlers from './useEventHandlers';
+import useUsageHandler from './useUsageHandler';
+import useLocalize from '~/hooks/useLocalize';
+
+const getStreamStartFailureData = (errorData?: unknown, termsRefusalText?: string): TResData =>
+ ({
+ text: termsRefusalText ?? getStreamStartFailureText(errorData),
+ metadata: markStreamStartFailedMetadata(),
+ }) as unknown as TResData;
+
+/**
+ * The handlers that render a resumable stream into the pane (step, final, created, content,
+ * title and attachment events, the error cards) and the usage tracking it feeds.
+ */
+export default function useResumableEvents({
+ run,
+ runIndex,
+ isAddedRequest,
+ chatHelpers,
+}: {
+ run: ResumableRun;
+ runIndex: number;
+ isAddedRequest: boolean;
+ chatHelpers: Pick<
+ EventHandlerParams,
+ 'setMessages' | 'getMessages' | 'setConversation' | 'setIsSubmitting' | 'newConversation'
+ >;
+}): { events: ResumableEvents; usage: ResumableUsage } {
+ const localize = useLocalize();
+ const queryClient = useQueryClient();
+ const [_completed, setCompleted] = useState(new Set());
+ const setShowStopButton = useSetAtom(showStopButtonByIndex(runIndex));
+ const { setMessages, getMessages, setConversation, setIsSubmitting, newConversation } =
+ chatHelpers;
+
+ const {
+ stepHandler: rawStepHandler,
+ finalHandler,
+ errorHandler,
+ clearStepMaps,
+ messageHandler,
+ contentHandler,
+ createdHandler,
+ titleHandler,
+ syncStepMessage,
+ prunePtcTraces,
+ attachmentHandler,
+ resetContentHandler,
+ flushPendingDeltas,
+ } = useEventHandlers({
+ setMessages,
+ getMessages,
+ setCompleted,
+ isAddedRequest,
+ runIndex,
+ setConversation,
+ setIsSubmitting,
+ newConversation,
+ setShowStopButton,
+ });
+
+ /**
+ * Run steps and activity labels must resolve indices in ONE space, and the
+ * resume SYNC boundary that invalidates the edit prefix is owned here, so
+ * this transport stamps its cleared state onto every dispatched
+ * submission. `useStepHandler` reads the flag (alongside the captured
+ * `editPrefixLength`) instead of measuring the live
+ * `initialResponse.content`, which SYNC replaces with the server's
+ * completion-local snapshot.
+ *
+ * Only allocates once the prefix is actually cleared; before that, and on
+ * the non-resumable transport, the submission passes through untouched.
+ */
+ const stepHandler = useCallback(
+ (...[event, submission]: Parameters<typeof rawStepHandler>) => {
+ const eventSubmission = run.editPrefixCleared
+ ? ({ ...submission, editPrefixCleared: true } as EventSubmission)
+ : submission;
+ rawStepHandler(event, eventSubmission);
+ if (eventSubmission.editPrefixFirstPartFolded === true) {
+ run.editPrefixFirstPartFolded = true;
+ }
+ },
+ [rawStepHandler, run],
+ );
+
+ const {
+ bindResponse,
+ contextHandler,
+ usageHandler,
+ tapStream,
+ tapContent,
+ finalizeUsage,
+ backfillUsage,
+ resetLive,
+ seedLive,
+ } = useUsageHandler();
+
+ const events = useMemo<ResumableEvents>(
+ () => ({
+ stepHandler,
+ showStartFailure: (failedSubmission, errorData, reason) => {
+ let text: string | undefined;
+ if (reason === 'recovery_held') {
+ text = localize('com_ui_steer_recovery_held');
+ } else if (reopenTermsOnRefusal(queryClient, errorData)) {
+ text = localize('com_error_terms_not_accepted');
+ }
+ errorHandler({
+ data: getStreamStartFailureData(errorData, text),
+ submission: failedSubmission as EventSubmission,
+ });
+ },
+ finalHandler: (data, finalSubmission) => finalHandler(data as TFinalResData, finalSubmission),
+ createdHandler,
+ attachmentHandler,
+ titleHandler,
+ contentHandler,
+ messageHandler,
+ prunePtcTraces,
+ resetContentHandler,
+ syncStepMessage,
+ clearStepMaps,
+ flushPendingDeltas,
+ resetLive,
+ showError: (text, errorSubmission) =>
+ errorHandler({
+ data: { text } as unknown as Parameters<typeof errorHandler>[0]['data'],
+ submission: errorSubmission as EventSubmission,
+ }),
+ }),
+ [
+ localize,
+ queryClient,
+ stepHandler,
+ finalHandler,
+ errorHandler,
+ createdHandler,
+ attachmentHandler,
+ titleHandler,
+ contentHandler,
+ messageHandler,
+ prunePtcTraces,
+ resetContentHandler,
+ syncStepMessage,
+ clearStepMaps,
+ flushPendingDeltas,
+ resetLive,
+ ],
+ );
+
+ const usage = useMemo<ResumableUsage>(
+ () => ({
+ bindResponse,
+ contextHandler,
+ usageHandler,
+ tapStream,
+ tapContent,
+ finalizeUsage,
+ backfillUsage,
+ seedLiveFromContent: (content, usageSubmission) =>
+ seedLive(countTrailingOutputChars(content), usageSubmission),
+ }),
+ [
+ bindResponse,
+ contextHandler,
+ usageHandler,
+ tapStream,
+ tapContent,
+ finalizeUsage,
+ backfillUsage,
+ seedLive,
+ ],
+ );
+
+ return { events, usage };
+}
diff --git a/client/src/hooks/SSE/pane.ts b/client/src/hooks/SSE/pane.ts
new file mode 100644
index 0000000000..e903b0e2bd
--- /dev/null
+++ b/client/src/hooks/SSE/pane.ts
@@ -0,0 +1,197 @@
+import { useMemo, useCallback } from 'react';
+import { v4 } from 'uuid';
+import { useSetRecoilState } from 'recoil';
+import { useStore, useSetAtom } from 'jotai';
+import { Constants } from 'librechat-data-provider';
+import { isStoppedRun, resolveDetachedRunEnd } from '@librechat/chat';
+import {
+ abortScrollFamily,
+ showStopButtonByIndex,
+ submissionByIndex,
+ runEndByIndex,
+ isDetachedRunManual,
+ detachedRunByConvoId,
+ drainAfterAbortByIndex,
+ stopRequestedByConvoId,
+} from '@librechat/chat/react';
+import type {
+ ResumableRun,
+ ResumablePane,
+ ResumableQueue,
+ DrainAfterAbort,
+ RunEnd,
+} from '@librechat/chat';
+import type { EventHandlerParams } from './useEventHandlers';
+import { pendingApprovalActionFamily } from '~/components/Chat/approval/state';
+import { clearComposerDrafts, resolveRunEndTarget } from '~/utils';
+import store from '~/store';
+
+/**
+ * Reconciliation often crosses async query boundaries. By the time an old
+ * generation settles, this pane may have armed "interrupt & send" for a new
+ * conversation/generation. Recoil applies functional setters against the
+ * latest value, so only consume the exact intent owned by this terminal path.
+ */
+const clearMatchingDrainAfterAbort = (
+ armed: DrainAfterAbort | false,
+ conversationId: string,
+ generationCreatedAt: number,
+): DrainAfterAbort | false =>
+ armed !== false &&
+ armed.conversationId === conversationId &&
+ armed.generationCreatedAt === generationCreatedAt
+ ? false
+ : armed;
+
+const replaceNewConversationUrl = (conversationId: string) => {
+ if (window.location.pathname !== `/c/${Constants.NEW_CONVO}`) {
+ return;
+ }
+
+ window.history.replaceState(
+ window.history.state,
+ '',
+ `/c/${conversationId}${window.location.search}`,
+ );
+};
+
+/**
+ * The pane's controls and run bookkeeping as a resumable run drives them, and the run markers
+ * the queue drain reads for a conversation the pane may leave mid-run.
+ */
+export default function useResumablePane({
+ run,
+ runIndex,
+ isAddedRequest,
+ setStreamId,
+ refreshBalance,
+ setIsSubmitting,
+ setConversation,
+ newConversation,
+ setGenerationEpoch,
+}: Pick<EventHandlerParams, 'setIsSubmitting' | 'setConversation' | 'newConversation'> & {
+ run: ResumableRun;
+ runIndex: number;
+ isAddedRequest: boolean;
+ setStreamId: (streamId: string | null) => void;
+ refreshBalance: () => void;
+ setGenerationEpoch: ResumablePane['setGenerationEpoch'];
+}): { pane: ResumablePane; queue: ResumableQueue } {
+ const jotaiStore = useStore();
+ const setActiveRunId = useSetRecoilState(store.activeRunFamily(runIndex));
+ const setAbortScroll = useSetAtom(abortScrollFamily(runIndex));
+ const setSubmission = useSetAtom(submissionByIndex(runIndex));
+ const setShowStopButton = useSetAtom(showStopButtonByIndex(runIndex));
+
+ const publishRunEnd = useSetAtom(runEndByIndex(runIndex));
+ const setRunEnd = useCallback(
+ (end: RunEnd, options?: { retainDetached?: boolean }) => {
+ run.runEndPublished = true;
+ /** The run's end reached the drain here, so a marker this pane left for the same run is
+ * settled and must not be resolved a second time on a later visit. A provisional end that
+ * cannot drain the queue keeps the marker, so a later read of history can still settle it. */
+ if (end.conversationId != null && options?.retainDetached !== true) {
+ const detachedFamily = detachedRunByConvoId(end.conversationId);
+ const detached = jotaiStore.get(detachedFamily);
+ if (
+ detached != null &&
+ (end.generationCreatedAt == null ||
+ detached.generationCreatedAt === end.generationCreatedAt)
+ ) {
+ jotaiStore.set(detachedFamily, null);
+ }
+ }
+ publishRunEnd(end);
+ },
+ [jotaiStore, publishRunEnd, run],
+ );
+ const setDrainAfterAbort = useSetAtom(drainAfterAbortByIndex(runIndex));
+ const clearDrainAfterAbort = useCallback(
+ (conversationId: string, generationCreatedAt?: number) => {
+ if (generationCreatedAt == null) {
+ return;
+ }
+ setDrainAfterAbort((armed) =>
+ clearMatchingDrainAfterAbort(armed, conversationId, generationCreatedAt),
+ );
+ },
+ [setDrainAfterAbort],
+ );
+
+ const pane = useMemo<ResumablePane>(
+ () => ({
+ setIsSubmitting,
+ setShowStopButton,
+ setSubmission,
+ setStreamId,
+ setGenerationEpoch,
+ setPendingAction: (conversationId, action) =>
+ jotaiStore.set(pendingApprovalActionFamily(conversationId), action),
+ clearComposerDrafts: (conversationId, options) =>
+ clearComposerDrafts(runIndex, conversationId, options),
+ publishRunEnd: setRunEnd,
+ setAbortScroll,
+ setConversation,
+ startNewConversation: newConversation
+ ? () => newConversation({ template: { conversationId: String(Constants.NEW_CONVO) } })
+ : undefined,
+ replaceNewConversationUrl,
+ renewActiveRun: () => setActiveRunId(v4()),
+ runEndTarget: resolveRunEndTarget,
+ clearDrainAfterAbort,
+ refreshBalance,
+ updateConversation: isAddedRequest ? undefined : setConversation,
+ resolveDetachedEnd: (conversationId, messages) => {
+ const detachedRun = jotaiStore.get(detachedRunByConvoId(conversationId));
+ const resolvable =
+ detachedRun != null && !isDetachedRunManual(jotaiStore.get, conversationId, detachedRun);
+ return {
+ resolvable,
+ end:
+ resolvable && messages != null
+ ? resolveDetachedRunEnd(conversationId, detachedRun, messages)
+ : null,
+ };
+ },
+ }),
+ [
+ jotaiStore,
+ runIndex,
+ isAddedRequest,
+ setStreamId,
+ refreshBalance,
+ setIsSubmitting,
+ setConversation,
+ newConversation,
+ setActiveRunId,
+ setAbortScroll,
+ setSubmission,
+ setShowStopButton,
+ setGenerationEpoch,
+ setRunEnd,
+ clearDrainAfterAbort,
+ ],
+ );
+ const queue = useMemo<ResumableQueue>(
+ () => ({
+ clearSupersededMarkers: (conversationId, isSameGeneration) => {
+ const stopFamily = stopRequestedByConvoId(conversationId);
+ const stopped = jotaiStore.get(stopFamily);
+ if (stopped != null && !isSameGeneration(stopped.generationCreatedAt)) {
+ jotaiStore.set(stopFamily, null);
+ }
+ const detachedFamily = detachedRunByConvoId(conversationId);
+ const detached = jotaiStore.get(detachedFamily);
+ if (detached != null && !isSameGeneration(detached.generationCreatedAt)) {
+ jotaiStore.set(detachedFamily, null);
+ }
+ },
+ isStopped: (conversationId, generationCreatedAt) =>
+ isStoppedRun(jotaiStore.get(stopRequestedByConvoId(conversationId)), generationCreatedAt),
+ rememberDetachedRun: (conversationId, detachedRun) =>
+ jotaiStore.set(detachedRunByConvoId(conversationId), detachedRun),
+ }),
+ [jotaiStore],
+ );
+ return { pane, queue };
+}
diff --git a/client/src/hooks/SSE/steers.ts b/client/src/hooks/SSE/steers.ts
new file mode 100644
index 0000000000..433fa8fcf6
--- /dev/null
+++ b/client/src/hooks/SSE/steers.ts
@@ -0,0 +1,77 @@
+import { useMemo, useCallback } from 'react';
+import { useStore, useSetAtom } from 'jotai';
+import { blockRecovery, canRestoreRecovery } from '@librechat/chat';
+import {
+ liveAppliedSteerIdsAtom,
+ recoveryDispositionsFamily,
+ queuedMessagesByConvoId,
+} from '@librechat/chat/react';
+import type { ResumableSteers, QueuedMessageOrigin } from '@librechat/chat';
+import type { TSubmission } from 'librechat-data-provider';
+import type { SteerState } from './steer';
+import { appendAppliedSteerIds, collectAppliedSteerIds, insertQueuedOrigin } from '~/utils';
+
+/**
+ * The pane's steer chips as a resumable run drives them: the chip state itself comes from
+ * `useSteerState`, and this adds the recovery and queue bookkeeping the run reaches through.
+ */
+export default function useResumableSteers(steerState: SteerState): ResumableSteers {
+ const jotaiStore = useStore();
+ const setLiveAppliedSteerIds = useSetAtom(liveAppliedSteerIdsAtom);
+ const {
+ resolveSteerChip,
+ updateSteerChips,
+ seedSteerChips,
+ settleAppliedSteerParts,
+ convertSteersToQueued,
+ convertLocalSteersToQueued,
+ } = steerState;
+
+ const restoreQueuedSubmission = useCallback(
+ (failedSubmission: TSubmission, expectedPredecessorCreatedAt?: number) => {
+ const conversationId = failedSubmission.conversation?.conversationId;
+ const origin = failedSubmission.queuedMessageOrigin as QueuedMessageOrigin | undefined;
+ if (!conversationId || origin == null) {
+ return;
+ }
+ jotaiStore.set(queuedMessagesByConvoId(conversationId), (prev) =>
+ canRestoreRecovery(jotaiStore.get(recoveryDispositionsFamily(conversationId)), origin.item)
+ ? insertQueuedOrigin(prev, origin, expectedPredecessorCreatedAt)
+ : prev,
+ );
+ },
+ [jotaiStore],
+ );
+
+ return useMemo<ResumableSteers>(
+ () => ({
+ resolve: resolveSteerChip,
+ isRecoveryHeld: (conversationId, recoverySteerId) =>
+ jotaiStore.get(recoveryDispositionsFamily(conversationId))[recoverySteerId] != null,
+ blockRecovery: (conversationId, recoverySteerId) =>
+ jotaiStore.set(recoveryDispositionsFamily(conversationId), (previous) =>
+ blockRecovery(previous, recoverySteerId),
+ ),
+ restoreQueued: restoreQueuedSubmission,
+ update: updateSteerChips,
+ markLiveApplied: (steerId) =>
+ setLiveAppliedSteerIds((prev) => appendAppliedSteerIds(prev, [steerId])),
+ seed: seedSteerChips,
+ appliedIds: collectAppliedSteerIds,
+ settleApplied: settleAppliedSteerParts,
+ convertToQueued: convertSteersToQueued,
+ convertLocalToQueued: convertLocalSteersToQueued,
+ }),
+ [
+ jotaiStore,
+ resolveSteerChip,
+ restoreQueuedSubmission,
+ updateSteerChips,
+ setLiveAppliedSteerIds,
+ seedSteerChips,
+ settleAppliedSteerParts,
+ convertSteersToQueued,
+ convertLocalSteersToQueued,
+ ],
+ );
+}
diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts
index ef62bac868..8316994b7d 100644
--- a/client/src/hooks/SSE/useResumableSSE.ts
+++ b/client/src/hooks/SSE/useResumableSSE.ts
@@ -1,135 +1,50 @@
-import { useMemo, useEffect, useState, useRef, useCallback } from 'react';
-import { v4 } from 'uuid';
-import { useSetRecoilState } from 'recoil';
-import { useStore, useSetAtom } from 'jotai';
-import { useQueryClient } from '@tanstack/react-query';
-import { Constants, QueryKeys, dataService } from 'librechat-data-provider';
-import { ABORT_SWEEP_STATUSES, selectLocalSteersForQueue } from '@librechat/chat';
+import { useState, useEffect, useCallback } from 'react';
import {
- resolveDetachedRunEnd,
- isStoppedRun,
- canRestoreRecovery,
- blockRecovery,
-} from '@librechat/chat';
-import {
- submissionByIndex,
- liveAppliedSteerIdsAtom,
- abortScrollFamily,
- showStopButtonByIndex,
-} from '@librechat/chat/react';
-import {
- isDetachedRunManual,
- stopRequestedByConvoId,
- detachedRunByConvoId,
- drainAfterAbortByIndex,
- queuedMessagesByConvoId,
- runEndByIndex,
- recoveryDispositionsFamily,
-} from '@librechat/chat/react';
-import {
- getOptimisticMessages,
- isInitialNewConversation,
- getStreamStartFailureText,
- hydrateSubmissionMessages,
- buildOptimisticConversation,
ResumableRun,
- documentVisibility,
- attachResumableStream,
mountSubmission,
releaseSubmission,
+ documentVisibility,
+ attachResumableStream,
} from '@librechat/chat';
-import type {
- TMessage,
- TSubmission,
- TConversation,
- EventSubmission,
-} from 'librechat-data-provider';
-import type { QueuedMessageOrigin, DrainAfterAbort, RunEnd } from '@librechat/chat';
-import type { ResumableHost, ResumableCache } from '@librechat/chat';
+import type { ResumableHost, ResumableParts } from '@librechat/chat';
+import type { TSubmission } from 'librechat-data-provider';
import type { EventHandlerParams } from './useEventHandlers';
-import type { ActiveJobsResponse } from '~/data-provider';
-import type { TResData, TFinalResData } from '~/common';
import {
logger,
- clearComposerDrafts,
applySteerPart,
- resolveRunEndTarget,
+ applyReasoningLabel,
findSteerMessageIndex,
applyActivityLabelPart,
- applyReasoningLabel,
offsetActivityPhaseBoundary,
findActivityLabelMessageIndex,
findReasoningLabelMessageIndex,
- appendAppliedSteerIds,
- collectAppliedSteerIds,
- removeConvoFromAllQueries,
- upsertConvoInAllQueries,
- invalidateConversationLists,
- countTrailingOutputChars,
- markStreamStartFailedMetadata,
- insertQueuedOrigin,
} from '~/utils';
-import {
- useGetUserBalance,
- fetchStreamStatus,
- useGetStartupConfig,
- queueTitleGeneration,
- streamStatusQueryKey,
- fetchConversationMessages,
-} from '~/data-provider';
-import { pendingApprovalActionFamily } from '~/components/Chat/approval/state';
+import { useGetUserBalance, fetchStreamStatus, useGetStartupConfig } from '~/data-provider';
import { useChatTransport } from '~/Providers/ChatTransportContext';
-import { reopenTermsOnRefusal } from '~/utils/terms';
import { useAuthContext } from '~/hooks/AuthContext';
-import { fetchConvoSnapshot } from '~/utils/convos';
-import useEventHandlers from './useEventHandlers';
-import { useFileMapContext } from '~/Providers';
-import useUsageHandler from './useUsageHandler';
-import useLocalize from '~/hooks/useLocalize';
+import useResumableEvents from './events';
+import useResumableSteers from './steers';
+import useResumableCache from './cache';
+import useResumablePane from './pane';
import useSteerState from './steer';
-import store from '~/store';
type ChatHelpers = Pick<
EventHandlerParams,
'setMessages' | 'getMessages' | 'setConversation' | 'setIsSubmitting' | 'newConversation'
>;
-/**
- * Reconciliation often crosses async query boundaries. By the time an old
- * generation settles, this pane may have armed "interrupt & send" for a new
- * conversation/generation. Recoil applies functional setters against the
- * latest value, so only consume the exact intent owned by this terminal path.
- */
-const clearMatchingDrainAfterAbort = (
- armed: DrainAfterAbort | false,
- conversationId: string,
- generationCreatedAt: number,
-): DrainAfterAbort | false =>
- armed !== false &&
- armed.conversationId === conversationId &&
- armed.generationCreatedAt === generationCreatedAt
- ? false
- : armed;
-
-const getStreamStartFailureData = (errorData?: unknown, termsRefusalText?: string): TResData =>
- ({
- text: termsRefusalText ?? getStreamStartFailureText(errorData),
- metadata: markStreamStartFailedMetadata(),
- }) as unknown as TResData;
-
-const replaceNewConversationUrl = (conversationId: string) => {
- if (window.location.pathname !== `/c/${Constants.NEW_CONVO}`) {
- return;
- }
-
- window.history.replaceState(
- window.history.state,
- '',
- `/c/${conversationId}${window.location.search}`,
- );
+/** How the app's message parts place steers and labels onto a response. */
+const resumableParts: ResumableParts = {
+ applySteer: applySteerPart,
+ findSteerTarget: findSteerMessageIndex,
+ applyActivityLabel: applyActivityLabelPart,
+ findActivityLabelTarget: findActivityLabelMessageIndex,
+ offsetActivityPhaseBoundary,
+ applyReasoningLabel,
+ findReasoningLabelTarget: findReasoningLabelMessageIndex,
};
-export { ABORT_SWEEP_STATUSES, selectLocalSteersForQueue };
+export { ABORT_SWEEP_STATUSES, selectLocalSteersForQueue } from '@librechat/chat';
/**
* Hook for resumable SSE streams.
@@ -140,6 +55,9 @@ export { ABORT_SWEEP_STATUSES, selectLocalSteersForQueue };
* - Navigation away does NOT abort the generation (just closes SSE)
* - Only explicit abort (via stop button → backend abort endpoint) stops generation
* - Backend emits `done` event with `aborted: true` on abort, handled via finalHandler
+ *
+ * The run itself lives in `@librechat/chat` (`mountSubmission`, `attachResumableStream`);
+ * this hook supplies it the app it runs in.
*/
export default function useResumableSSE(
submission: TSubmission | null,
@@ -148,395 +66,50 @@ export default function useResumableSSE(
runIndex = 0,
) {
const [run] = useState(() => new ResumableRun());
- const jotaiStore = useStore();
- const localize = useLocalize();
- const queryClient = useQueryClient();
- const setActiveRunId = useSetRecoilState(store.activeRunFamily(runIndex));
-
+ const [streamId, setStreamId] = useState<string | null>(null);
const { token, isAuthenticated } = useAuthContext();
const transport = useChatTransport();
- const fileMap = useFileMapContext();
- const fileMapRef = useRef(fileMap);
- fileMapRef.current = fileMap;
const { setMessages, getMessages, setConversation, setIsSubmitting, newConversation } =
chatHelpers;
- /**
- * Optimistically add a job ID to the active jobs cache.
- * Called when generation starts.
- */
- const addActiveJob = useCallback(
- (jobId: string) => {
- queryClient.setQueryData<ActiveJobsResponse>([QueryKeys.activeJobs], (old) => ({
- activeJobIds: [...new Set([...(old?.activeJobIds ?? []), jobId])],
- }));
- },
- [queryClient],
- );
-
- /**
- * Optimistically remove a job ID from the active jobs cache.
- * Called when generation completes, aborts, or errors.
- */
- const removeActiveJob = useCallback(
- (jobId: string) => {
- queryClient.setQueryData<ActiveJobsResponse>([QueryKeys.activeJobs], (old) => ({
- activeJobIds: (old?.activeJobIds ?? []).filter((id) => id !== jobId),
- }));
- },
- [queryClient],
- );
-
- const addOptimisticConversation = useCallback(
- (conversationId: string, currentSubmission: TSubmission): TSubmission => {
- if (!isInitialNewConversation(currentSubmission)) {
- return currentSubmission;
- }
-
- const optimisticConversation = buildOptimisticConversation(currentSubmission, conversationId);
- const optimisticMessages = getOptimisticMessages(
- currentSubmission,
- conversationId,
- getMessages(),
- );
-
- queryClient.setQueryData<TConversation>(
- [QueryKeys.conversation, conversationId],
- (current) => current ?? optimisticConversation,
- );
- queryClient.setQueryData<TMessage[]>(
- [QueryKeys.messages, conversationId],
- optimisticMessages,
- );
- queryClient.setQueryData<TMessage[]>(
- [QueryKeys.messages, Constants.NEW_CONVO],
- optimisticMessages,
- );
- upsertConvoInAllQueries(queryClient, optimisticConversation);
-
- return hydrateSubmissionMessages(currentSubmission, conversationId);
- },
- [getMessages, queryClient],
- );
-
- const resumableCache = useMemo<ResumableCache>(
- () => ({
- invalidateMessages: (conversationId, refetch) =>
- queryClient.invalidateQueries({
- queryKey: [QueryKeys.messages, conversationId],
- refetchType: refetch,
- }),
- fetchMessages: (conversationId, fallback) =>
- queryClient.fetchQuery<TMessage[]>({
- queryKey: [QueryKeys.messages, conversationId],
- ...(fallback === true && {
- // The first stream can finish before CREATED mounts the saved-chat query.
- queryFn: () => fetchConversationMessages(conversationId),
- }),
- }),
- refreshConversation: (conversationId) =>
- queryClient.invalidateQueries({
- queryKey: [QueryKeys.conversation, conversationId],
- refetchType: 'all',
- }),
- refreshConversationLists: () => invalidateConversationLists(queryClient),
- refreshPinnedConversations: () =>
- queryClient.invalidateQueries({ queryKey: [QueryKeys.pinnedConversations] }),
- setStreamStatus: (conversationId, status) =>
- queryClient.setQueryData(streamStatusQueryKey(conversationId), status),
- removeStreamStatus: (conversationId) =>
- queryClient.removeQueries({ queryKey: streamStatusQueryKey(conversationId) }),
- invalidateStreamStatus: (conversationId) =>
- queryClient.invalidateQueries({ queryKey: streamStatusQueryKey(conversationId) }),
- addActiveJob,
- removeActiveJob,
- fetchConversation: (conversationId) =>
- fetchConvoSnapshot(queryClient, conversationId, () =>
- dataService.getConversationById(conversationId),
- ),
- setConversation: (conversationId, conversation) =>
- queryClient.setQueryData([QueryKeys.conversation, conversationId], conversation),
- upsertConversation: (conversation) =>
- upsertConvoInAllQueries(queryClient, conversation, true, 'snapshot'),
- removeConversation: (conversationId) =>
- removeConvoFromAllQueries(queryClient, conversationId),
- getConversation: (conversationId) =>
- queryClient.getQueryData<TConversation>([QueryKeys.conversation, conversationId]),
- removeConversationQueries: (conversationId) => {
- queryClient.removeQueries({ queryKey: [QueryKeys.conversation, conversationId] });
- queryClient.removeQueries({ queryKey: [QueryKeys.messages, conversationId] });
- },
- queueTitleGeneration,
- addOptimisticConversation,
- }),
- [addActiveJob, addOptimisticConversation, queryClient, removeActiveJob],
- );
- const [_completed, setCompleted] = useState(new Set());
- const [streamId, setStreamId] = useState<string | null>(null);
- const setAbortScroll = useSetAtom(abortScrollFamily(runIndex));
- const setSubmission = useSetAtom(submissionByIndex(runIndex));
- const setShowStopButton = useSetAtom(showStopButtonByIndex(runIndex));
- const setLiveAppliedSteerIds = useSetAtom(liveAppliedSteerIdsAtom);
-
- const restoreQueuedSubmission = useCallback(
- (failedSubmission: TSubmission, expectedPredecessorCreatedAt?: number) => {
- const conversationId = failedSubmission.conversation?.conversationId;
- const origin = failedSubmission.queuedMessageOrigin as QueuedMessageOrigin | undefined;
- if (!conversationId || origin == null) {
- return;
- }
- jotaiStore.set(queuedMessagesByConvoId(conversationId), (prev) =>
- canRestoreRecovery(jotaiStore.get(recoveryDispositionsFamily(conversationId)), origin.item)
- ? insertQueuedOrigin(prev, origin, expectedPredecessorCreatedAt)
- : prev,
- );
- },
- [jotaiStore],
- );
-
- const {
- resolveSteerChip,
- updateSteerChips,
- seedSteerChips,
- settleAppliedSteerParts,
- convertSteersToQueued,
- convertLocalSteersToQueued,
- updateActiveGenerationCreatedAt,
- } = useSteerState();
-
- const publishRunEnd = useSetAtom(runEndByIndex(runIndex));
- const setRunEnd = useCallback(
- (end: RunEnd, options?: { retainDetached?: boolean }) => {
- run.runEndPublished = true;
- /** The run's end reached the drain here, so a marker this pane left for the same run is
- * settled and must not be resolved a second time on a later visit. A provisional end that
- * cannot drain the queue keeps the marker, so a later read of history can still settle it. */
- if (end.conversationId != null && options?.retainDetached !== true) {
- const detachedFamily = detachedRunByConvoId(end.conversationId);
- const detached = jotaiStore.get(detachedFamily);
- if (
- detached != null &&
- (end.generationCreatedAt == null ||
- detached.generationCreatedAt === end.generationCreatedAt)
- ) {
- jotaiStore.set(detachedFamily, null);
- }
- }
- publishRunEnd(end);
- },
- [jotaiStore, publishRunEnd, run],
- );
- const setDrainAfterAbort = useSetAtom(drainAfterAbortByIndex(runIndex));
- const clearDrainAfterAbort = useCallback(
- (conversationId: string, generationCreatedAt?: number) => {
- if (generationCreatedAt == null) {
- return;
- }
- setDrainAfterAbort((armed) =>
- clearMatchingDrainAfterAbort(armed, conversationId, generationCreatedAt),
- );
- },
- [setDrainAfterAbort],
- );
-
- const {
- stepHandler: rawStepHandler,
- finalHandler,
- errorHandler,
- clearStepMaps,
- messageHandler,
- contentHandler,
- createdHandler,
- titleHandler,
- syncStepMessage,
- prunePtcTraces,
- attachmentHandler,
- resetContentHandler,
- flushPendingDeltas,
- } = useEventHandlers({
- setMessages,
- getMessages,
- setCompleted,
- isAddedRequest,
- runIndex,
- setConversation,
- setIsSubmitting,
- newConversation,
- setShowStopButton,
- });
-
- /**
- * Run steps and activity labels must resolve indices in ONE space, and the
- * resume SYNC boundary that invalidates the edit prefix is owned here, so
- * this transport stamps its cleared state onto every dispatched
- * submission. `useStepHandler` reads the flag (alongside the captured
- * `editPrefixLength`) instead of measuring the live
- * `initialResponse.content`, which SYNC replaces with the server's
- * completion-local snapshot.
- *
- * Only allocates once the prefix is actually cleared; before that, and on
- * the non-resumable transport, the submission passes through untouched.
- */
- const stepHandler = useCallback(
- (...[event, submission]: Parameters<typeof rawStepHandler>) => {
- const eventSubmission = run.editPrefixCleared
- ? ({ ...submission, editPrefixCleared: true } as EventSubmission)
- : submission;
- rawStepHandler(event, eventSubmission);
- if (eventSubmission.editPrefixFirstPartFolded === true) {
- run.editPrefixFirstPartFolded = true;
- }
- },
- [rawStepHandler, run],
- );
-
const { data: startupConfig } = useGetStartupConfig();
const balanceQuery = useGetUserBalance({
enabled: !!isAuthenticated && startupConfig?.balance?.enabled,
});
- const {
- bindResponse,
- contextHandler,
- usageHandler,
- tapStream,
- tapContent,
- finalizeUsage,
- backfillUsage,
- resetLive,
- seedLive,
- } = useUsageHandler();
+ const balanceEnabled = startupConfig?.balance?.enabled ?? false;
+ const refreshBalance = useCallback(() => {
+ balanceEnabled && balanceQuery.refetch();
+ }, [balanceEnabled, balanceQuery]);
+
+ const cache = useResumableCache(getMessages);
+ const steerState = useSteerState();
+ const steers = useResumableSteers(steerState);
+ const { events, usage } = useResumableEvents({ run, runIndex, isAddedRequest, chatHelpers });
+ const { pane, queue } = useResumablePane({
+ run,
+ runIndex,
+ isAddedRequest,
+ setStreamId,
+ refreshBalance,
+ setIsSubmitting,
+ setConversation,
+ newConversation,
+ setGenerationEpoch: steerState.updateActiveGenerationCreatedAt,
+ });
- /**
- * Subscribe to stream via SSE library (supports custom headers)
- * Follows same auth pattern as useSSE
- * @param isResume - If true, adds ?resume=true to trigger sync event from server
- */
const buildHost = useCallback(
(): ResumableHost => ({
logger,
visibility: documentVisibility,
fetchStatus: fetchStreamStatus,
subscribe: (next) => attachResumableStream(run, buildHost(), next),
- cache: resumableCache,
- queue: {
- clearSupersededMarkers: (conversationId, isSameGeneration) => {
- const stopFamily = stopRequestedByConvoId(conversationId);
- const stopped = jotaiStore.get(stopFamily);
- if (stopped != null && !isSameGeneration(stopped.generationCreatedAt)) {
- jotaiStore.set(stopFamily, null);
- }
- const detachedFamily = detachedRunByConvoId(conversationId);
- const detached = jotaiStore.get(detachedFamily);
- if (detached != null && !isSameGeneration(detached.generationCreatedAt)) {
- jotaiStore.set(detachedFamily, null);
- }
- },
- isStopped: (conversationId, generationCreatedAt) =>
- isStoppedRun(jotaiStore.get(stopRequestedByConvoId(conversationId)), generationCreatedAt),
- rememberDetachedRun: (conversationId, detachedRun) =>
- jotaiStore.set(detachedRunByConvoId(conversationId), detachedRun),
- },
- pane: {
- setIsSubmitting,
- setShowStopButton,
- setSubmission,
- setStreamId,
- setGenerationEpoch: updateActiveGenerationCreatedAt,
- setPendingAction: (conversationId, action) =>
- jotaiStore.set(pendingApprovalActionFamily(conversationId), action),
- clearComposerDrafts: (conversationId, options) =>
- clearComposerDrafts(runIndex, conversationId, options),
- publishRunEnd: setRunEnd,
- setAbortScroll,
- setConversation,
- startNewConversation: newConversation
- ? () => newConversation({ template: { conversationId: String(Constants.NEW_CONVO) } })
- : undefined,
- replaceNewConversationUrl,
- renewActiveRun: () => setActiveRunId(v4()),
- runEndTarget: resolveRunEndTarget,
- clearDrainAfterAbort,
- refreshBalance: () => {
- (startupConfig?.balance?.enabled ?? false) && balanceQuery.refetch();
- },
- updateConversation: isAddedRequest ? undefined : setConversation,
- resolveDetachedEnd: (conversationId, messages) => {
- const detachedRun = jotaiStore.get(detachedRunByConvoId(conversationId));
- const resolvable =
- detachedRun != null &&
- !isDetachedRunManual(jotaiStore.get, conversationId, detachedRun);
- return {
- resolvable,
- end:
- resolvable && messages != null
- ? resolveDetachedRunEnd(conversationId, detachedRun, messages)
- : null,
- };
- },
- },
- steers: {
- resolve: resolveSteerChip,
- isRecoveryHeld: (conversationId, recoverySteerId) =>
- jotaiStore.get(recoveryDispositionsFamily(conversationId))[recoverySteerId] != null,
- blockRecovery: (conversationId, recoverySteerId) =>
- jotaiStore.set(recoveryDispositionsFamily(conversationId), (previous) =>
- blockRecovery(previous, recoverySteerId),
- ),
- restoreQueued: restoreQueuedSubmission,
- update: updateSteerChips,
- markLiveApplied: (steerId) =>
- setLiveAppliedSteerIds((prev) => appendAppliedSteerIds(prev, [steerId])),
- seed: seedSteerChips,
- appliedIds: collectAppliedSteerIds,
- settleApplied: settleAppliedSteerParts,
- convertToQueued: convertSteersToQueued,
- convertLocalToQueued: convertLocalSteersToQueued,
- },
- events: {
- stepHandler,
- showStartFailure: (failedSubmission, errorData, reason) => {
- let text: string | undefined;
- if (reason === 'recovery_held') {
- text = localize('com_ui_steer_recovery_held');
- } else if (reopenTermsOnRefusal(queryClient, errorData)) {
- text = localize('com_error_terms_not_accepted');
- }
- errorHandler({
- data: getStreamStartFailureData(errorData, text),
- submission: failedSubmission as EventSubmission,
- });
- },
- finalHandler: (data, finalSubmission) =>
- finalHandler(data as TFinalResData, finalSubmission),
- createdHandler,
- attachmentHandler,
- titleHandler,
- contentHandler,
- messageHandler,
- prunePtcTraces,
- resetContentHandler,
- syncStepMessage,
- clearStepMaps,
- flushPendingDeltas,
- resetLive,
- showError: (text, errorSubmission) =>
- errorHandler({
- data: { text } as unknown as Parameters<typeof errorHandler>[0]['data'],
- submission: errorSubmission as EventSubmission,
- }),
- },
+ cache,
+ queue,
+ pane,
+ steers,
+ events,
+ usage,
messages: { get: getMessages, set: setMessages },
- usage: {
- bindResponse,
- contextHandler,
- usageHandler,
- tapStream,
- tapContent,
- finalizeUsage,
- backfillUsage,
- seedLiveFromContent: (content, usageSubmission) =>
- seedLive(countTrailingOutputChars(content), usageSubmission),
- },
stream: transport.stream({ token }),
start: (request, options) => transport.start(request, options),
exposeDebugControls: import.meta.env.DEV
@@ -550,71 +123,9 @@ export default function useResumableSSE(
debugWindow.__closeClean = closeClean;
}
: undefined,
- parts: {
- applySteer: applySteerPart,
- findSteerTarget: findSteerMessageIndex,
- applyActivityLabel: applyActivityLabelPart,
- findActivityLabelTarget: findActivityLabelMessageIndex,
- offsetActivityPhaseBoundary,
- applyReasoningLabel,
- findReasoningLabelTarget: findReasoningLabelMessageIndex,
- },
+ parts: resumableParts,
}),
- [
- run,
- newConversation,
- localize,
- queryClient,
- restoreQueuedSubmission,
- resumableCache,
- isAddedRequest,
- setConversation,
- runIndex,
- token,
- transport,
- setAbortScroll,
- setActiveRunId,
- setShowStopButton,
- finalHandler,
- createdHandler,
- attachmentHandler,
- titleHandler,
- stepHandler,
- contentHandler,
- resetContentHandler,
- syncStepMessage,
- prunePtcTraces,
- clearStepMaps,
- messageHandler,
- errorHandler,
- flushPendingDeltas,
- setIsSubmitting,
- getMessages,
- setMessages,
- startupConfig?.balance?.enabled,
- balanceQuery,
- bindResponse,
- contextHandler,
- usageHandler,
- tapStream,
- tapContent,
- finalizeUsage,
- backfillUsage,
- resetLive,
- seedLive,
- setRunEnd,
- clearDrainAfterAbort,
- resolveSteerChip,
- setLiveAppliedSteerIds,
- updateSteerChips,
- seedSteerChips,
- settleAppliedSteerParts,
- convertSteersToQueued,
- convertLocalSteersToQueued,
- setSubmission,
- updateActiveGenerationCreatedAt,
- jotaiStore,
- ],
+ [run, cache, queue, pane, steers, events, usage, getMessages, setMessages, transport, token],
);
useEffect(() => {