📡 refactor: Move the Adaptive and Resumable SSE Bindings into the Chat Package (#17452)

useAdaptiveSSE and useResumableSSE now live in the chat package and own the
run, the stream id and how a stream re-attaches. The app supplies the services
a resumable stream runs on and the Assistants stream through a StreamHost,
mounted in Root beside the chat and steer hosts.
This commit is contained in:
Marco Beretta 2026-10-26 22:47:30 +01:00 • committed by GitHub
parent 7e56534c5f
commit fd86359e82
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 256 additions and 92 deletions

View file

@ -0,0 +1,12 @@
import type { StreamHost } from '@librechat/chat/react';
import { useResumableServices } from '~/hooks/SSE/resumable';
import useSSE from '~/hooks/SSE/useSSE';
/** The app's services behind the stream bindings: the resumable stream's handlers, cache and
* transport, and the Assistants stream, which carries its own response. */
export const appStreamHost: StreamHost = {
useResumableServices,
useLegacyStream: useSSE,
};
export { StreamHostProvider, useStreamHost } from '@librechat/chat/react';

View file

@ -2,9 +2,9 @@ import React from 'react';
import { MemoryRouter } from 'react-router-dom';
import { useAtomValue, getDefaultStore } from 'jotai';
import { RecoilRoot, useSetRecoilState } from 'recoil';
import { useChatHelpers } from '@librechat/chat/react';
import { act, renderHook, waitFor } from '@testing-library/react';
import { useChat, resumeRequestsAtom } from '@librechat/chat/react';
import { useChatHelpers, useResumableSSE } from '@librechat/chat/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Tools, QueryKeys, ContentTypes, EModelEndpoint, request } from 'librechat-data-provider';
import {
@ -37,8 +37,8 @@ import { usePaneConversation, usePaneConversationState } from '~/routes/ChatSett
import { ChatTransportContext } from '~/Providers/ChatTransportContext';
import { ChatContext, useChatContext } from '~/Providers/ChatContext';
import { startupConfigKey } from '~/data-provider/Endpoints/queries';
import useResumableSSE from '~/hooks/SSE/useResumableSSE';
import useResumeOnLoad from '~/hooks/SSE/useResumeOnLoad';
import { StreamHostTestProvider } from 'test/streamHost';
import { SteerHostTestProvider } from 'test/steerHost';
import { ChatHostTestProvider } from 'test/chatHost';
import useSSE from '~/hooks/SSE/useSSE';
@ -121,11 +121,13 @@ function createWrapper(
>
<SteerHostTestProvider>
<ChatHostTestProvider>
<ChatSettingsContext.Provider value={chatSettings}>
<ChatTransportContext.Provider value={transport}>
{children}
</ChatTransportContext.Provider>
</ChatSettingsContext.Provider>
<StreamHostTestProvider>
<ChatSettingsContext.Provider value={chatSettings}>
<ChatTransportContext.Provider value={transport}>
{children}
</ChatTransportContext.Provider>
</ChatSettingsContext.Provider>
</StreamHostTestProvider>
</ChatHostTestProvider>
</SteerHostTestProvider>
</RecoilRoot>

View file

@ -1,7 +1,7 @@
import { createElement } from 'react';
import { getDefaultStore } from 'jotai';
import { QueryClient } from '@tanstack/react-query';
import { renderHook, act, waitFor } from '@testing-library/react';
import { renderHook as renderBareHook, act, waitFor } from '@testing-library/react';
import {
Constants,
ContentTypes,
@ -11,6 +11,7 @@ import {
StepTypes,
request,
} from 'librechat-data-provider';
import type { RenderHookOptions, RenderHookResult } from '@testing-library/react';
import type { TMessage, TSubmission } from 'librechat-data-provider';
import type { Query, QueryKey } from '@tanstack/react-query';
import type { ReactNode } from 'react';
@ -312,15 +313,15 @@ jest.mock('librechat-data-provider', () => {
};
});
import useResumableSSE, {
selectLocalSteersForQueue,
ABORT_SWEEP_STATUSES,
} from '~/hooks/SSE/useResumableSSE';
import { selectLocalSteersForQueue, ABORT_SWEEP_STATUSES } from '~/hooks/SSE/resumable';
import { appStreamHost } from '~/Providers/StreamHostContext';
import useSSE from '~/hooks/SSE/useSSE';
import type { PendingSteer } from '@librechat/chat';
import type { Transport } from '~/hooks/Chat/contract';
import { ChatTransportContext, defaultChatTransport } from '~/Providers/ChatTransportContext';
import {
useResumableSSE,
StreamHostProvider,
recoveryDispositionsFamily,
queuedMessagesByConvoId,
stopRequestedByConvoId,
@ -328,6 +329,21 @@ import {
resetQueueFamilies,
} from '@librechat/chat/react';
/** Every hook here renders under the app's stream host, as `Root` mounts it. */
function renderHook<Result, Props>(
callback: (props: Props) => Result,
options?: RenderHookOptions<Props>,
): RenderHookResult<Result, Props> {
const Inner = options?.wrapper;
const wrapper = ({ children }: { children: ReactNode }) =>
createElement(
StreamHostProvider,
{ host: appStreamHost },
Inner ? createElement(Inner, null, children) : children,
);
return renderBareHook(callback, { ...options, wrapper });
}
const CONV_ID = 'conv-abc-123';
type PartialSubmission = {

View file

@ -1,6 +1,5 @@
export { default as useSSE } from './useSSE';
export { default as useResumableSSE } from './useResumableSSE';
export { default as useAdaptiveSSE } from './useAdaptiveSSE';
export { useResumableSSE, useAdaptiveSSE } from '@librechat/chat/react';
export { default as useResumeOnLoad } from './useResumeOnLoad';
export { default as useStepHandler } from './useStepHandler';
export { default as useUsageHandler } from './useUsageHandler';

View file

@ -1,14 +1,7 @@
import { useState, useEffect, useCallback } from 'react';
import {
ResumableRun,
mountSubmission,
releaseSubmission,
documentVisibility,
attachResumableStream,
} from '@librechat/chat';
import type { ResumableHost, ResumableParts } from '@librechat/chat';
import type { TSubmission } from 'librechat-data-provider';
import type { EventHandlerParams } from './useEventHandlers';
import { useCallback } from 'react';
import { documentVisibility } from '@librechat/chat';
import type { ResumableServices, ResumableStreamParams } from '@librechat/chat/react';
import type { ResumableParts } from '@librechat/chat';
import {
logger,
applySteerPart,
@ -28,11 +21,6 @@ import useResumableCache from './cache';
import useResumablePane from './pane';
import useSteerState from './steer';
type ChatHelpers = Pick<
EventHandlerParams,
'setMessages' | 'getMessages' | 'setConversation' | 'setIsSubmitting' | 'newConversation'
>;
/** How the app's message parts place steers and labels onto a response. */
const resumableParts: ResumableParts = {
applySteer: applySteerPart,
@ -47,31 +35,21 @@ const resumableParts: ResumableParts = {
export { ABORT_SWEEP_STATUSES, selectLocalSteersForQueue } from '@librechat/chat';
/**
* Hook for resumable SSE streams.
* Separates generation start (POST) from stream subscription (GET EventSource).
* Supports auto-reconnection with exponential backoff.
*
* Key behavior:
* - 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.
* The services a pane's resumable stream runs on in this app: its query cache, steer chips,
* stream handlers, pane controls, balance refresh and transport. The binding in
* `@librechat/chat/react` owns the run, the stream id and how a stream re-attaches.
*/
export default function useResumableSSE(
submission: TSubmission | null,
chatHelpers: ChatHelpers,
isAddedRequest = false,
runIndex = 0,
) {
const [run] = useState(() => new ResumableRun());
const [streamId, setStreamId] = useState<string | null>(null);
export function useResumableServices({
run,
chat,
runIndex,
isAddedRequest,
setStreamId,
}: ResumableStreamParams): () => ResumableServices {
const { auth, config } = useChatSettings();
const { token, isAuthenticated = false } = auth;
const transport = useChatTransport();
const { setMessages, getMessages, setConversation, setIsSubmitting, newConversation } =
chatHelpers;
const { setMessages, getMessages, setConversation, setIsSubmitting, newConversation } = chat;
const { balanceEnabled = false } = config;
const balanceQuery = useGetUserBalance({ enabled: isAuthenticated && balanceEnabled });
@ -82,7 +60,12 @@ export default function useResumableSSE(
const cache = useResumableCache(getMessages, runIndex);
const steerState = useSteerState();
const steers = useResumableSteers(steerState);
const { events, usage } = useResumableEvents({ run, runIndex, isAddedRequest, chatHelpers });
const { events, usage } = useResumableEvents({
run,
runIndex,
isAddedRequest,
chatHelpers: chat,
});
const { pane, queue } = useResumablePane({
run,
runIndex,
@ -95,12 +78,11 @@ export default function useResumableSSE(
setGenerationEpoch: steerState.updateActiveGenerationCreatedAt,
});
const buildHost = useCallback(
(): ResumableHost => ({
return useCallback(
(): ResumableServices => ({
logger,
visibility: documentVisibility,
fetchStatus: fetchStreamStatus,
subscribe: (next) => attachResumableStream(run, buildHost(), next),
cache,
queue,
pane,
@ -123,18 +105,6 @@ export default function useResumableSSE(
: undefined,
parts: resumableParts,
}),
[run, cache, queue, pane, steers, events, usage, getMessages, setMessages, transport, token],
[cache, queue, pane, steers, events, usage, getMessages, setMessages, transport, token],
);
useEffect(() => {
const host = buildHost();
if (!submission || Object.keys(submission).length === 0) {
releaseSubmission(run, host);
return;
}
return mountSubmission(run, host, submission);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [submission]);
return { streamId };
}

View file

@ -33,6 +33,7 @@ import {
CodeHighlightThrottleContext,
normalizeCodeHighlightThrottleMs,
} from '~/components/Chat/Messages/Content/Parts/useLazyHighlight';
import { StreamHostProvider, appStreamHost } from '~/Providers/StreamHostContext';
import KeyboardShortcutsDialog from '~/components/Nav/KeyboardShortcutsDialog';
import { SteerHostProvider, appSteerHost } from '~/Providers/SteerHostContext';
import { ChatHostProvider, appChatHost } from '~/Providers/ChatHostContext';
@ -271,7 +272,9 @@ export default function Root() {
<ChatSettingsProvider>
<SteerHostProvider host={appSteerHost}>
<ChatHostProvider host={appChatHost}>
<RootLayout />
<StreamHostProvider host={appStreamHost}>
<RootLayout />
</StreamHostProvider>
</ChatHostProvider>
</SteerHostProvider>
</ChatSettingsProvider>

View file

@ -0,0 +1,9 @@
import React from 'react';
import { StreamHostProvider } from '@librechat/chat/react';
import { appStreamHost } from '~/Providers/StreamHostContext';
/** Mounts the app's stream host the way `routes/Root.tsx` does, for specs that render the stream
* hooks outside the app shell. Import it after the spec's module mocks so the host uses them. */
export function StreamHostTestProvider({ children }: { children?: React.ReactNode }) {
return <StreamHostProvider host={appStreamHost}>{children}</StreamHostProvider>;
}

View file

@ -1,5 +1,6 @@
/** React bindings for the core `Chat`: providers and `useChat`. Populated as the hooks move in. */
export * from './react/chat';
export * from './react/stream';
export { MessageContext, MessagePartIndex, useMessageContext } from './react/message';
export {
useMessagePartsHost,

View file

@ -1,12 +1,28 @@
/**
* @jest-environment jsdom
*/
import React from 'react';
import { renderHook } from '@testing-library/react';
import { EModelEndpoint } from 'librechat-data-provider';
import type { TSubmission } from 'librechat-data-provider';
import useResumableSSE from '../useResumableSSE';
import useAdaptiveSSE from '../useAdaptiveSSE';
import useSSE from '../useSSE';
import type { StreamHost } from '../host';
import { StreamHostProvider } from '../host';
import useResumableSSE from '../resumable';
import useAdaptiveSSE from '../adaptive';
jest.mock('../useSSE', () => jest.fn());
jest.mock('../useResumableSSE', () => jest.fn(() => ({ streamId: 'stream' })));
jest.mock('../resumable', () => jest.fn(() => ({ streamId: 'stream' })));
const useLegacyStream = jest.fn();
const host: StreamHost = {
useResumableServices: () => () => {
throw new Error('the resumable binding is replaced in this spec');
},
useLegacyStream,
};
const wrapper = ({ children }: { children: React.ReactNode }) => (
<StreamHostProvider host={host}>{children}</StreamHostProvider>
);
const helpers = {
setMessages: jest.fn(),
@ -30,19 +46,21 @@ it.each([
codeEnvironmentMode: 'attached',
codeWorkspaces: [{ environmentId: 'vm', workspaceId: 'repo' }],
} as TSubmission;
const { rerender } = renderHook(({ value }) => useAdaptiveSSE(value, helpers), {
const { rerender, result } = renderHook(({ value }) => useAdaptiveSSE(value, helpers), {
initialProps: { value: submission as TSubmission | null },
wrapper,
});
expect(useSSE).toHaveBeenLastCalledWith(null, helpers, false, 0);
expect(useLegacyStream).toHaveBeenLastCalledWith(null, helpers, false, 0);
expect(useResumableSSE).toHaveBeenLastCalledWith(submission, helpers, false, 0);
expect(result.current).toEqual({ streamId: 'stream', resumableEnabled: true });
rerender({ value: null });
expect(useSSE).toHaveBeenLastCalledWith(null, helpers, false, 0);
expect(useLegacyStream).toHaveBeenLastCalledWith(null, helpers, false, 0);
},
);
it('preserves the Assistants transport and its server abort endpoint', () => {
const submission = { conversation: { endpoint: EModelEndpoint.assistants } } as TSubmission;
renderHook(() => useAdaptiveSSE(submission, helpers));
expect(useSSE).toHaveBeenLastCalledWith(submission, helpers, false, 0);
renderHook(() => useAdaptiveSSE(submission, helpers), { wrapper });
expect(useLegacyStream).toHaveBeenLastCalledWith(submission, helpers, false, 0);
expect(useResumableSSE).toHaveBeenLastCalledWith(null, helpers, false, 0);
});

View file

@ -1,38 +1,39 @@
import { isAssistantsEndpoint } from 'librechat-data-provider';
import type { TSubmission } from 'librechat-data-provider';
import type { EventHandlerParams } from './useEventHandlers';
import useResumableSSE from './useResumableSSE';
import useSSE from './useSSE';
type ChatHelpers = Pick<
EventHandlerParams,
'setMessages' | 'getMessages' | 'setConversation' | 'setIsSubmitting' | 'newConversation'
>;
import type { StreamChat } from './host';
import useResumableSSE from './resumable';
import { useStreamHost } from './host';
/**
* Adaptive SSE hook that switches between standard and resumable modes.
* Uses resumable streams by default, falls back to standard SSE for assistants endpoints.
* Uses resumable streams by default, falls back to the host's standard SSE for assistants
* endpoints.
*
* Note: Both hooks are always called to comply with React's Rules of Hooks.
* We pass null submission to the inactive one.
*/
export default function useAdaptiveSSE(
submission: TSubmission | null,
chatHelpers: ChatHelpers,
chat: StreamChat,
isAddedRequest = false,
runIndex = 0,
) {
): { streamId: string | null; resumableEnabled: boolean } {
const endpoint = submission?.conversation?.endpoint;
const endpointType = submission?.conversation?.endpointType;
const actualEndpoint = endpointType ?? endpoint;
const isAssistants = isAssistantsEndpoint(actualEndpoint);
const resumableEnabled = !isAssistants;
useSSE(resumableEnabled ? null : submission, chatHelpers, isAddedRequest, runIndex);
useStreamHost().useLegacyStream(
resumableEnabled ? null : submission,
chat,
isAddedRequest,
runIndex,
);
const { streamId } = useResumableSSE(
resumableEnabled ? submission : null,
chatHelpers,
chat,
isAddedRequest,
runIndex,
);

View file

@ -0,0 +1,68 @@
import { createContext, useContext } from 'react';
import type { Dispatch, ReactNode, SetStateAction } from 'react';
import type { TSubmission } from 'librechat-data-provider';
import type { ResumableHost, ResumableRun } from '../../core';
import type { ChatContract } from '../chat/contract';
/** The chat members a stream writes through: the message cache, the pane's conversation and its
* in-flight flag, and the generator a stream calls when the server starts a new chat. */
export type StreamChat = Pick<
ChatContract,
'setMessages' | 'getMessages' | 'setConversation' | 'setIsSubmitting' | 'newConversation'
>;
/** One pane's resumable stream, as the host builds the services it runs on. */
export type ResumableStreamParams = {
run: ResumableRun;
chat: StreamChat;
/** `0` for the main pane, `1` for the added (multi-convo) pane. */
runIndex: number;
isAddedRequest: boolean;
/** Reports the stream the pane is attached to, or `null` once it detaches. */
setStreamId: Dispatch<SetStateAction<string | null>>;
};
/** Everything a resumable stream runs on except how it re-attaches, which the binding owns. */
export type ResumableServices = Omit<ResumableHost, 'subscribe'>;
/**
* What the stream bindings need from the app that hosts them. Members are hooks, called
* unconditionally on every render, so the host can back each one with its own query cache,
* transport and store. A host must stay the same object for the life of the tree it wraps.
*/
export interface StreamHost {
/**
* Builds the services one pane's resumable stream runs on. The returned function is called
* whenever the stream mounts or re-attaches, so each attachment reads the services of the
* latest render; it changes only when they do.
*/
useResumableServices(params: ResumableStreamParams): () => ResumableServices;
/** Streams a turn that carries its own response (Assistants), for `submission` or none. */
useLegacyStream(
submission: TSubmission | null,
chat: StreamChat,
isAddedRequest: boolean,
runIndex: number,
): void;
}
const StreamHostContext = createContext<StreamHost | null>(null);
/** Supplies the host the stream bindings read from. */
export function StreamHostProvider({
host,
children,
}: {
host: StreamHost;
children?: ReactNode;
}): ReactNode {
return <StreamHostContext.Provider value={host}>{children}</StreamHostContext.Provider>;
}
export function useStreamHost(): StreamHost {
const host = useContext(StreamHostContext);
if (host == null) {
throw new Error('The stream hooks need a StreamHostProvider above them.');
}
return host;
}

View file

@ -0,0 +1,4 @@
export { default as useAdaptiveSSE } from './adaptive';
export { default as useResumableSSE } from './resumable';
export { StreamHostProvider, useStreamHost } from './host';
export type { StreamHost, StreamChat, ResumableServices, ResumableStreamParams } from './host';

View file

@ -0,0 +1,61 @@
import { useState, useEffect, useCallback } from 'react';
import type { TSubmission } from 'librechat-data-provider';
import type { ResumableHost } from '../../core';
import type { StreamChat } from './host';
import {
ResumableRun,
mountSubmission,
releaseSubmission,
attachResumableStream,
} from '../../core';
import { useStreamHost } from './host';
/**
* Hook for resumable SSE streams.
* Separates generation start (POST) from stream subscription (GET EventSource).
* Supports auto-reconnection with exponential backoff.
*
* Key behavior:
* - Navigation away does NOT abort the generation (just closes SSE)
* - Only explicit abort (via stop button, then the backend abort endpoint) stops generation
* - Backend emits `done` event with `aborted: true` on abort, handled via finalHandler
*
* The run itself is `mountSubmission` and `attachResumableStream`; the host supplies the
* services it runs on.
*/
export default function useResumableSSE(
submission: TSubmission | null,
chat: StreamChat,
isAddedRequest = false,
runIndex = 0,
): { streamId: string | null } {
const [run] = useState(() => new ResumableRun());
const [streamId, setStreamId] = useState<string | null>(null);
const buildServices = useStreamHost().useResumableServices({
run,
chat,
runIndex,
isAddedRequest,
setStreamId,
});
const buildHost = useCallback(
(): ResumableHost => ({
...buildServices(),
subscribe: (next) => attachResumableStream(run, buildHost(), next),
}),
[run, buildServices],
);
useEffect(() => {
const host = buildHost();
if (!submission || Object.keys(submission).length === 0) {
releaseSubmission(run, host);
return;
}
return mountSubmission(run, host, submission);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [submission]);
return { streamId };
}