Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔁 refactor: Move the Resume Helpers and Their State Into the Chat Package (#17562)
Marco Berettaec3b0efa0bcf
diff --git a/client/src/Providers/ChatHostContext.tsx b/client/src/Providers/ChatHostContext.tsxindex 266640873e..c13784d475 100644--- a/client/src/Providers/ChatHostContext.tsx+++ b/client/src/Providers/ChatHostContext.tsx@@ -3,11 +3,12 @@ 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';+import type { TMessage, TAgentQueuedTurnReceipt } from 'librechat-data-provider';import type { QueryClient, QueryCacheNotifyEvent } from '@tanstack/react-query';-import type { TMessage } from 'librechat-data-provider';import { useLatestMessage, useLatestMessageId } from '~/hooks/Messages/useLatestMessage';import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/state';import { useAbortStreamMutation, useGetMessagesByConvoId } from '~/data-provider';+import { agentQueuedTurnsQueryKey } from '~/data-provider/SSE/queuedTurns';import { useChatSettings } from '~/Providers/ChatSettingsContext';import { getMappingOptions } from '~/hooks/Chat/outcomes';import useTurnServices from '~/hooks/Chat/services';@@ -64,6 +65,19 @@ export function createMessageCache(queryClient: QueryClient): ChatMessageCache {refetchStreamStatus: (conversationId) => {queryClient.invalidateQueries({ queryKey: ['streamStatus', conversationId] });},+ invalidateMessages: (conversationId) => {+ queryClient.invalidateQueries({ queryKey: [QueryKeys.messages, conversationId] });+ },+ messagesUpdatedAt: (conversationId) =>+ queryClient.getQueryState([QueryKeys.messages, conversationId])?.dataUpdatedAt,+ reloadMessages: async (conversationId) => {+ await queryClient.refetchQueries(+ { queryKey: [QueryKeys.messages, conversationId], exact: true },+ { throwOnError: true },+ );+ },+ readQueuedTurns: (conversationId) =>+ queryClient.getQueryData<TAgentQueuedTurnReceipt[]>(agentQueuedTurnsQueryKey(conversationId)),};}diff --git a/client/src/Providers/StreamHostContext.tsx b/client/src/Providers/StreamHostContext.tsxindex 4200bab719..f062bcae28 100644--- a/client/src/Providers/StreamHostContext.tsx+++ b/client/src/Providers/StreamHostContext.tsx@@ -1,5 +1,6 @@import { useMemo } from 'react';import type { StreamHost } from '@librechat/chat/react';+import { useActiveJobs, useAgentQueuedTurns, extendActiveJobsGrace } from '~/data-provider';import { useChatTransport } from '~/Providers/ChatTransportContext';import { useResumableServices } from '~/hooks/SSE/resumable';import { useAuthContext } from '~/hooks/AuthContext';@@ -21,6 +22,10 @@ export const appStreamHost: StreamHost = {useResumableServices,useLegacyStream: useSSE,useTransport,+ /** Observes the receipts `useSteering` fetches, without competing for the fetch. */+ useQueuedTurnReceipts: (conversationId) => useAgentQueuedTurns(conversationId, false),+ useActiveJobs,+ extendActiveJobsGrace,};export { StreamHostProvider, useStreamHost } from '@librechat/chat/react';diff --git a/client/src/components/Chat/Messages/Thread/state.ts b/client/src/components/Chat/Messages/Thread/state.tsindex 155d7c7673..d8610394dc 100644--- a/client/src/components/Chat/Messages/Thread/state.ts+++ b/client/src/components/Chat/Messages/Thread/state.ts@@ -1,69 +1,7 @@-import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';-import { atom, useStore } from 'jotai';-import { atomFamily } from 'jotai/utils';-import type { Atom } from 'jotai';--/**- * Sibling selection of the message thread: per parent, the REVERSED index of- * the child on display (0 = newest). Feature-owned state, shared by the- * recursive and flat renderers, the share view, and the writers that focus a- * regenerated response, restore a resumed branch, or clear a conversation.- */--/** Recoil keyed `null` and `undefined` parents distinctly from any id; one sentinel keeps that. */-export const NULL_SIBLING_KEY = '__null_parent__';--export const siblingKey = (parentId: string | null | undefined): string =>- parentId ?? NULL_SIBLING_KEY;--export const siblingIdxFamily = atomFamily((_key: string) => atom(0));--/** Read-only atom over the selections of the given parents, for one subscription per consumer. */-export function siblingIndexesAtom(keys: readonly string[]): Atom<Record<string, number>> {- return atom((get) => {- const indexes: Record<string, number> = {};- for (const key of keys) {- indexes[key] = get(siblingIdxFamily(key));- }- return indexes;- });-}--function sameKeys(a: readonly string[], b: readonly string[]): boolean {- if (a === b) {- return true;- }- if (a.length !== b.length) {- return false;- }- for (let i = 0; i < a.length; i += 1) {- if (a[i] !== b[i]) {- return false;- }- }- return true;-}--/**- * Subscribes to the selections of `parentKeys` through one derived atom that- * is only replaced when the KEYS change by content: callers derive the key- * list from the messages cache on every write, and a fresh atom per write- * would hand every consumer a new value object and a render per delta.- * Read through `useSyncExternalStore` so a consumer renders exactly when the- * selection object changes, with no mount-time re-render.- */-export function useSiblingIndexes(parentKeys: readonly string[]): Record<string, number> {- const jotaiStore = useStore();- const stableRef = useRef(parentKeys);- if (!sameKeys(stableRef.current, parentKeys)) {- stableRef.current = parentKeys;- }- const stableKeys = stableRef.current;- const indexesAtom = useMemo(() => siblingIndexesAtom(stableKeys), [stableKeys]);- const subscribe = useCallback(- (onChange: () => void) => jotaiStore.sub(indexesAtom, onChange),- [jotaiStore, indexesAtom],- );- const read = useCallback(() => jotaiStore.get(indexesAtom), [jotaiStore, indexesAtom]);- return useSyncExternalStore(subscribe, read, read);-}+export {+ siblingKey,+ siblingIdxFamily,+ NULL_SIBLING_KEY,+ useSiblingIndexes,+ siblingIndexesAtom,+} from '@librechat/chat/react';diff --git a/client/src/components/Chat/approval/state.ts b/client/src/components/Chat/approval/state.tsindex e21f6ad246..2205e31ed8 100644--- a/client/src/components/Chat/approval/state.ts+++ b/client/src/components/Chat/approval/state.ts@@ -1,40 +1,5 @@-import { atomFamily } from 'jotai/utils';-import { atom, useAtomValue } from 'jotai';-import { Constants } from 'librechat-data-provider';-import type { Agents } from 'librechat-data-provider';--/**- * The server-owned pending action for one conversation.- *- * Kept outside message rendering so the composer and timeline can project the- * same action without making mounted cards the source of truth. This state is- * memory-only: reload hydration comes from the stream status endpoint.- */-export const pendingApprovalActionFamily = atomFamily((_conversationId: string) =>- atom<Agents.PendingAction | null>(null),-);--/** Whether the composer's review panel is expanded for one conversation. */-export const approvalPanelOpenFamily = atomFamily((_conversationId: string) => atom(false));--/**- * True while the composer's review panel is open on this tool-approval action.- * The panel then owns the decisions and the batch submit, and it overlays the- * tail of the thread where the live approval card sits, so the thread card- * steps back to a record of the request until the panel is collapsed.- * Without a conversation there is no composer, so nothing is presented there.- */-export function useComposerPresentsApproval(- conversationId: string | null | undefined,- actionId: string,-): boolean {- const key = conversationId ?? Constants.NEW_CONVO;- const pendingAction = useAtomValue(pendingApprovalActionFamily(key));- const open = useAtomValue(approvalPanelOpenFamily(key));- return (- conversationId != null &&- open &&- pendingAction?.actionId === actionId &&- pendingAction.payload.type === 'tool_approval'- );-}+export {+ approvalPanelOpenFamily,+ pendingApprovalActionFamily,+ useComposerPresentsApproval,+} from '@librechat/chat/react';diff --git a/client/src/data-provider/SSE/queries.ts b/client/src/data-provider/SSE/queries.tsindex 3d866a5e94..f178e1a13b 100644--- a/client/src/data-provider/SSE/queries.ts+++ b/client/src/data-provider/SSE/queries.ts@@ -1,4 +1,5 @@import { useEffect, useMemo, useState } from 'react';+import { ACTIVE_JOBS_SUCCESSOR_GRACE_MS } from '@librechat/chat/react';import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query';import { apiBaseUrl, QueryKeys, request, dataService } from 'librechat-data-provider';import type { TConversation } from 'librechat-data-provider';@@ -236,7 +237,7 @@ export const ACTIVE_JOBS_POLL_MS = 5_000;* moment a successor appears, and with the tab already focused there is no* focus refetch to recover: the pane waits for a reload.*/-export const ACTIVE_JOBS_SUCCESSOR_GRACE_MS = 30_000;+export { ACTIVE_JOBS_SUCCESSOR_GRACE_MS };/** Module-scoped rather than per-observer: this is one shared query, and a* component mounting mid-handover should inherit the grace, not restart it. */diff --git a/client/src/data-provider/SSE/queuedTurns.ts b/client/src/data-provider/SSE/queuedTurns.tsindex acefa6023b..014eaf4f79 100644--- a/client/src/data-provider/SSE/queuedTurns.ts+++ b/client/src/data-provider/SSE/queuedTurns.ts@@ -1,14 +1,22 @@import { useEffect, useRef } from 'react';import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';import { dataService, MutationKeys, QueryKeys } from 'librechat-data-provider';-import { isDefiniteQueuedTurnRejection, isDefiniteQueuedTurnsUnsupported } from '@librechat/chat';+import {+ isQueuedTurnSuccessorOwed,+ isDefiniteQueuedTurnRejection,+ isDefiniteQueuedTurnsUnsupported,+} from '@librechat/chat';import type {TAgentQueuedTurnReceipt,TEnqueueAgentQueuedTurnRequest,} from 'librechat-data-provider';import { useChatTransport } from '~/Providers/ChatTransportContext';-export { isDefiniteQueuedTurnRejection, isDefiniteQueuedTurnsUnsupported };+export {+ isQueuedTurnSuccessorOwed,+ isDefiniteQueuedTurnRejection,+ isDefiniteQueuedTurnsUnsupported,+};export type AgentQueuedTurnReceipt = TAgentQueuedTurnReceipt;export type EnqueueAgentQueuedTurnRequest = TEnqueueAgentQueuedTurnRequest;@@ -65,28 +73,6 @@ export function shouldPollAgentQueuedTurns();}-/**- * Whether the backend owes this conversation a run it will start itself.- *- * Wider than {@link shouldPollAgentQueuedTurns} in exactly one way: `admitted`.- * The receipt poll stops there because there is nothing left to wait for — but- * for a pane that is not attached, `admitted` is the strongest evidence it will- * get that a run exists, and the receipt is dropped from the projection almost- * immediately after (the chip goes, so its id leaves the known set). Anyone- * deciding whether to keep listening for that run must count it.- */-export function isQueuedTurnSuccessorOwed(receipts: unknown): boolean {- return (- Array.isArray(receipts) &&- receipts.some(- (item: AgentQueuedTurnReceipt) =>- item.status === 'queued' ||- item.status === 'admitted' ||- (item.status === 'claimed' && item.failure?.code !== 'ADMISSION_INDETERMINATE'),- )- );-}-/*** `expectsReceipts` keeps the poll alive while the caller still holds a* server-owned row the projection has not settled. A snapshot fetched whilediff --git a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsxindex ea492edaf9..7daa4b3465 100644--- a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx+++ b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx@@ -33,7 +33,9 @@ import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/import { pendingApprovalActionFamily } from '~/components/Chat/approval/state';import { agentQueuedTurnsQueryKey } from '~/data-provider/SSE/queuedTurns';import { usePaneConversation } from '~/routes/ChatSettings';+import { StreamHostTestProvider } from 'test/streamHost';import { SteerHostTestProvider } from 'test/steerHost';+import { ChatHostTestProvider } from 'test/chatHost';import useResumeOnLoad from '../useResumeOnLoad';import store from '~/store';@@ -212,24 +214,28 @@ function renderUseResumeOnLoad({<JotaiProvider store={jotaiStore}><RecoilRoot initializeState={initializeState}><SteerHostTestProvider>- <SubmissionProbe />- <SubmissionStartProbe />- <SiblingIndexProbe />- <PendingSteersProbe />- <QueuedMessagesProbe />- <ChatSettingsContext.Provider- value={{- ...defaultChatSettings,- usePaneConversation,- config: {- ...defaultChatSettings.config,- retentionMode: mockStartupConfig?.interface?.retentionMode,- loaded: mockStartupConfigSettled,- },- }}- >- {children}- </ChatSettingsContext.Provider>+ <ChatHostTestProvider>+ <StreamHostTestProvider>+ <SubmissionProbe />+ <SubmissionStartProbe />+ <SiblingIndexProbe />+ <PendingSteersProbe />+ <QueuedMessagesProbe />+ <ChatSettingsContext.Provider+ value={{+ ...defaultChatSettings,+ usePaneConversation,+ config: {+ ...defaultChatSettings.config,+ retentionMode: mockStartupConfig?.interface?.retentionMode,+ loaded: mockStartupConfigSettled,+ },+ }}+ >+ {children}+ </ChatSettingsContext.Provider>+ </StreamHostTestProvider>+ </ChatHostTestProvider></SteerHostTestProvider></RecoilRoot></JotaiProvider>diff --git a/client/src/hooks/SSE/useResumeOnLoad.ts b/client/src/hooks/SSE/useResumeOnLoad.tsindex 2adfe3ebca..f8f8de037e 100644--- a/client/src/hooks/SSE/useResumeOnLoad.ts+++ b/client/src/hooks/SSE/useResumeOnLoad.ts@@ -1,5 +1,4 @@import { useCallback, useEffect, useRef, useState } from 'react';-import { useQueryClient } from '@tanstack/react-query';import { useStore, useSetAtom, useAtomValue } from 'jotai';import {Constants,@@ -7,11 +6,15 @@ import {isForcedTemporaryRetention,} from 'librechat-data-provider';import {- activeGenerationCreatedAtByConvoId,+ useChatHost,+ useSubmission,useIsSubmitting,- submissionStartFamily,+ useOwedSuccessor,+ settleFinishedRun,submissionByIndex,- useSubmission,+ submissionStartFamily,+ useResumeAnnouncements,+ activeGenerationCreatedAtByConvoId,} from '@librechat/chat/react';import {hasSubmissionUserMessage,@@ -27,10 +30,7 @@ import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/import { pendingApprovalActionFamily } from '~/components/Chat/approval/state';import { useChatSettings } from '~/Providers/ChatSettingsContext';import { getBranchSiblingIndexesForTarget } from '~/utils';-import useResumeAnnouncements from './announcements';import { useStreamStatus } from '~/data-provider';-import { settleFinishedRun } from './finished';-import useOwedSuccessor from './successor';import useSteerState from './steer';/**@@ -51,7 +51,7 @@ export default function useResumeOnLoad(messagesLoaded = true,) {const jotaiStore = useStore();- const queryClient = useQueryClient();+ const cache = useChatHost().useMessageCache();const setSubmission = useSetAtom(submissionByIndex(runIndex));const setSubmissionStart = useSetAtom(submissionStartFamily(runIndex));const currentSubmission = useSubmission(runIndex);@@ -275,7 +275,7 @@ export default function useResumeOnLoad(console.log('[ResumeOnLoad] No active job to resume for:', conversationId);settleFinishedRun({jotaiStore,- queryClient,+ cache,steers: steerState,conversationId,streamStatus,@@ -383,7 +383,7 @@ export default function useResumeOnLoad(streamStatus,streamStatusUpdatedAt,queuedTurnReceipts,- queryClient,+ cache,getMessages,setSubmission,setSubmissionStart,diff --git a/packages/chat/src/core/steer/receipts.ts b/packages/chat/src/core/steer/receipts.tsindex ff296cfd90..6d4ccf2111 100644--- a/packages/chat/src/core/steer/receipts.ts+++ b/packages/chat/src/core/steer/receipts.ts@@ -225,3 +225,24 @@ export function reconcileServerQueuedTurns(});return [...retained, ...projected].sort(compareQueuedMessages);}++/**+ * Whether the backend owes this conversation a run it will start itself.+ *+ * Wider than the receipt poll's own predicate in exactly one way: `admitted`. The receipt poll+ * stops there because there is nothing left to wait for, but for a pane that is not attached,+ * `admitted` is the strongest evidence it will get that a run exists, and the receipt is dropped+ * from the projection almost immediately after (the chip goes, so its id leaves the known set).+ * Anyone deciding whether to keep listening for that run must count it.+ */+export function isQueuedTurnSuccessorOwed(receipts: unknown): boolean {+ return (+ Array.isArray(receipts) &&+ receipts.some(+ (item: AgentQueuedTurnReceipt) =>+ item.status === 'queued' ||+ item.status === 'admitted' ||+ (item.status === 'claimed' && item.failure?.code !== 'ADMISSION_INDETERMINATE'),+ )+ );+}diff --git a/packages/chat/src/react.ts b/packages/chat/src/react.tsindex 0b167974de..dc2bf64158 100644--- a/packages/chat/src/react.ts+++ b/packages/chat/src/react.ts@@ -3,6 +3,8 @@ export * from './react/chat';export * from './react/stream';export * from './react/subagents';export * from './react/usage';+export * from './react/thread';+export * from './react/approval';export { MessageContext, MessagePartIndex, useMessageContext } from './react/message';export {useMessagePartsHost,diff --git a/packages/chat/src/react/approval.ts b/packages/chat/src/react/approval.tsnew file mode 100644index 0000000000..d6a5ce8057--- /dev/null+++ b/packages/chat/src/react/approval.ts@@ -0,0 +1,43 @@+import { atomFamily } from 'jotai/utils';+import { atom, useAtomValue } from 'jotai';+import { Constants } from 'librechat-data-provider';+import type { Agents } from 'librechat-data-provider';+import type { Family } from './steer/family';++/**+ * The server-owned pending action for one conversation.+ *+ * Kept outside message rendering so the composer and timeline can project the+ * same action without making mounted cards the source of truth. This state is+ * memory-only: reload hydration comes from the stream status endpoint.+ */+export const pendingApprovalActionFamily: Family<Agents.PendingAction | null> = atomFamily(+ (_conversationId: string) => atom<Agents.PendingAction | null>(null),+);++/** Whether the composer's review panel is expanded for one conversation. */+export const approvalPanelOpenFamily: Family<boolean> = atomFamily((_conversationId: string) =>+ atom(false),+);++/**+ * True while the composer's review panel is open on this tool-approval action.+ * The panel then owns the decisions and the batch submit, and it overlays the+ * tail of the thread where the live approval card sits, so the thread card+ * steps back to a record of the request until the panel is collapsed.+ * Without a conversation there is no composer, so nothing is presented there.+ */+export function useComposerPresentsApproval(+ conversationId: string | null | undefined,+ actionId: string,+): boolean {+ const key = conversationId ?? Constants.NEW_CONVO;+ const pendingAction = useAtomValue(pendingApprovalActionFamily(key));+ const open = useAtomValue(approvalPanelOpenFamily(key));+ return (+ conversationId != null &&+ open &&+ pendingAction?.actionId === actionId &&+ pendingAction.payload.type === 'tool_approval'+ );+}diff --git a/packages/chat/src/react/chat/__tests__/stop.spec.tsx b/packages/chat/src/react/chat/__tests__/stop.spec.tsxindex 4f9846ec20..d113a80c6b 100644--- a/packages/chat/src/react/chat/__tests__/stop.spec.tsx+++ b/packages/chat/src/react/chat/__tests__/stop.spec.tsx@@ -43,6 +43,10 @@ const cache: ChatMessageCache = {refetchMessages: jest.fn(),refetchActiveJobs: jest.fn(),refetchStreamStatus: jest.fn(),+ invalidateMessages: jest.fn(),+ messagesUpdatedAt: () => undefined,+ reloadMessages: () => Promise.resolve(),+ readQueuedTurns: () => undefined,};/** A host with no app behind it: one fixed pane conversation and the abort under test. */diff --git a/packages/chat/src/react/chat/host.tsx b/packages/chat/src/react/chat/host.tsxindex 9e9684fee2..5197817684 100644--- a/packages/chat/src/react/chat/host.tsx+++ b/packages/chat/src/react/chat/host.tsx@@ -10,6 +10,7 @@ import type {TEndpointOption,TEphemeralAgent,TEndpointsConfig,+ TAgentQueuedTurnReceipt,UIMappingOptions,} from 'librechat-data-provider';import type { Dispatch, ReactNode, SetStateAction } from 'react';@@ -138,6 +139,14 @@ export type ChatMessageCache = {refetchActiveJobs: () => void;/** Marks a conversation's stream status stale. */refetchStreamStatus: (conversationId: string) => void;+ /** Marks a conversation's messages stale; only mounted readers refetch. */+ invalidateMessages: (conversationId: string) => void;+ /** When a conversation's messages were last fetched, if they ever were. */+ messagesUpdatedAt: (conversationId: string) => number | undefined;+ /** Refetches a conversation's messages; rejects when the fetch fails. */+ reloadMessages: (conversationId: string) => Promise<void>;+ /** The server's queued-turn receipts last read for a conversation. */+ readQueuedTurns: (conversationId: string) => TAgentQueuedTurnReceipt[] | undefined;};/** A conversation's messages as the app's data layer loads them. */diff --git a/packages/chat/src/react/stream/__tests__/adaptive.spec.tsx b/packages/chat/src/react/stream/__tests__/adaptive.spec.tsxindex 3689c1e286..d828c94c9d 100644--- a/packages/chat/src/react/stream/__tests__/adaptive.spec.tsx+++ b/packages/chat/src/react/stream/__tests__/adaptive.spec.tsx@@ -19,6 +19,9 @@ const host: StreamHost = {},useLegacyStream,useTransport: () => null,+ useQueuedTurnReceipts: () => ({ data: undefined, dataUpdatedAt: 0 }),+ useActiveJobs: () => ({ data: undefined, dataUpdatedAt: 0 }),+ extendActiveJobsGrace: () => undefined,};const wrapper = ({ children }: { children: React.ReactNode }) => (diff --git a/packages/chat/src/react/stream/host.tsx b/packages/chat/src/react/stream/host.tsxindex ab51f44bd1..ef569a039f 100644--- a/packages/chat/src/react/stream/host.tsx+++ b/packages/chat/src/react/stream/host.tsx@@ -1,5 +1,5 @@import { createContext, useContext } from 'react';-import type { ChatTransport, TSubmission } from 'librechat-data-provider';+import type { ChatTransport, TSubmission, TAgentQueuedTurnReceipt } from 'librechat-data-provider';import type { Dispatch, ReactNode, SetStateAction } from 'react';import type { ResumableHost, ResumableRun } from '../../core';import type { ChatContract } from '../chat/contract';@@ -22,6 +22,12 @@ export type ResumableStreamParams = {setStreamId: Dispatch<SetStateAction<string | null>>;};+/** One of the app's queries as a resume reads it: the data and when it was last fetched. */+export type ResumeQuery<Data> = {+ data: Data | undefined;+ dataUpdatedAt: number;+};+/** Everything a resumable stream runs on except how it re-attaches, which the binding owns. */export type ResumableServices = Omit<ResumableHost, 'subscribe'>;@@ -49,6 +55,18 @@ export interface StreamHost {* turn such as a subagent's activity. Changes when the token does.*/useTransport(): ChatTransport | null;+ /** A conversation's queued-turn receipts, observed from the app's cache without fetching. */+ useQueuedTurnReceipts(conversationId: string): ResumeQuery<TAgentQueuedTurnReceipt[]>;+ /**+ * The signed-in user's active generations. `expectsSuccessor` keeps listening while the+ * caller knows the server owes it a run.+ */+ useActiveJobs(+ enabled: boolean,+ expectsSuccessor: boolean,+ ): ResumeQuery<{ activeJobIds: string[] }>;+ /** Restarts the active-job list's handover window after a run was seen live another way. */+ extendActiveJobsGrace(): void;}const StreamHostContext = createContext<StreamHost | null>(null);diff --git a/packages/chat/src/react/stream/index.ts b/packages/chat/src/react/stream/index.tsindex 3f1e533f71..4ef03784c2 100644--- a/packages/chat/src/react/stream/index.ts+++ b/packages/chat/src/react/stream/index.ts@@ -4,6 +4,11 @@ export { StreamHostProvider, useStreamHost } from './host';export { useStepHandler } from './step';export { useUsageHandler } from './usage';export { useContentHandler } from './content';+export { settleFinishedRun } from './resume/finished';+export { useResumeAnnouncements } from './resume/announcements';+export { useOwedSuccessor, ACTIVE_JOBS_SUCCESSOR_GRACE_MS } from './resume/successor';+export type { FinishedRunSteers } from './resume/finished';+export type { OwedSuccessorState } from './resume/successor';export { useAttachmentHandler } from './attachments';export {activeRunFamily,@@ -17,4 +22,10 @@ export type { UsageHandlers } from './usage';export type { StepHandlers } from './step';export { sandboxStartingByToolCallId } from './sandbox';export { ptcTraceKey, ptcTraceByToolCallId, EMPTY_PTC_TRACE, PTC_TRACE_MAX_ENTRIES } from './ptc';-export type { StreamHost, StreamChat, ResumableServices, ResumableStreamParams } from './host';+export type {+ StreamHost,+ StreamChat,+ ResumeQuery,+ ResumableServices,+ ResumableStreamParams,+} from './host';diff --git a/client/src/hooks/SSE/announcements.ts b/packages/chat/src/react/stream/resume/announcements.tssimilarity index 91%rename from client/src/hooks/SSE/announcements.tsrename to packages/chat/src/react/stream/resume/announcements.tsindex ebd97dd2b6..13b97ef52d 100644--- a/client/src/hooks/SSE/announcements.ts+++ b/packages/chat/src/react/stream/resume/announcements.ts@@ -1,12 +1,11 @@import { useRef, useEffect } from 'react';import { useAtom } from 'jotai';-import { useQueryClient } from '@tanstack/react-query';-import { resumeRequestsAtom } from '@librechat/chat/react';-import { Constants, QueryKeys } from 'librechat-data-provider';+import { Constants } from 'librechat-data-provider';import type { TSubmission } from 'librechat-data-provider';import type { MutableRefObject } from 'react';import type { OwedSuccessorState } from './successor';-import { streamStatusQueryKey } from '~/data-provider';+import { resumeRequestsAtom } from '../../chat/resume';+import { useChatHost } from '../../chat/host';/*** Matches the active-job list's own poll interval: answering an announcement@@ -19,7 +18,7 @@ const ACTIVE_JOB_REARM_INTERVAL_MS = 5_000;* list, an owed queued turn) or when `resumeStream` asks for it, forcing the status and* history reads it is about to make fresh first.*/-export default function useResumeAnnouncements({+export function useResumeAnnouncements({conversationId,resumableEnabled,owed,@@ -44,7 +43,7 @@ export default function useResumeAnnouncements({hasLiveSubmissionForThisConvo: boolean;attachedGenerationCreatedAt: number | null;}): void {- const queryClient = useQueryClient();+ const cache = useChatHost().useMessageCache();const { successorOwed, hasActiveJobForThisConvo, activeJobsUpdatedAt, receiptSignature } = owed;/** Receipt state at the last arm, so history is refetched on a transition* rather than on every heartbeat of an unchanged queued turn. */@@ -110,7 +109,7 @@ export default function useResumeAnnouncements({if (hasActiveSubmissionForThisConvo) {setSubmission(null);}- queryClient.invalidateQueries({ queryKey: streamStatusQueryKey(conversationId) });+ cache.refetchStreamStatus(conversationId);/*** History is refetched only when this arm can actually change what the* pane shows: a run is listed (attachment is imminent and must not be@@ -122,7 +121,7 @@ export default function useResumeAnnouncements({const receiptsTransitioned = lastArmedReceiptSignatureRef.current !== receiptSignature;lastArmedReceiptSignatureRef.current = receiptSignature;if (hasActiveJobForThisConvo || receiptsTransitioned) {- queryClient.invalidateQueries({ queryKey: [QueryKeys.messages, conversationId] });+ cache.invalidateMessages(conversationId);}processedConvoRef.current = null;setExternalRunArm((arm) => arm + 1);@@ -137,7 +136,7 @@ export default function useResumeAnnouncements({activeJobsUpdatedAt,receiptSignature,setSubmission,- queryClient,+ cache,processedConvoRef,answeredActiveJobRef,setExternalRunArm,@@ -171,8 +170,8 @@ export default function useResumeAnnouncements({if (hasActiveSubmissionForThisConvo) {setSubmission(null);}- queryClient.invalidateQueries({ queryKey: streamStatusQueryKey(conversationId) });- queryClient.invalidateQueries({ queryKey: [QueryKeys.messages, conversationId] });+ cache.refetchStreamStatus(conversationId);+ cache.invalidateMessages(conversationId);processedConvoRef.current = null;setExternalRunArm((arm) => arm + 1);}, [@@ -184,7 +183,7 @@ export default function useResumeAnnouncements({hasActiveSubmissionForThisConvo,hasLiveSubmissionForThisConvo,setSubmission,- queryClient,+ cache,processedConvoRef,setExternalRunArm,]);diff --git a/client/src/hooks/SSE/finished.ts b/packages/chat/src/react/stream/resume/finished.tssimilarity index 80%rename from client/src/hooks/SSE/finished.tsrename to packages/chat/src/react/stream/resume/finished.tsindex 4eb1725fa2..a999b1ab21 100644--- a/client/src/hooks/SSE/finished.ts+++ b/packages/chat/src/react/stream/resume/finished.ts@@ -1,18 +1,26 @@-import { QueryKeys } from 'librechat-data-provider';-import { resolveDetachedRunEnd } from '@librechat/chat';+import type { TMessage, TPendingSteer, TAgentQueuedTurnReceipt } from 'librechat-data-provider';+import type { useStore } from 'jotai';+import type { StreamStatusResponse, GenerationProtocolVersion } from '../../../core';+import type useSteerConvert from '../../steering/useSteerConvert';+import type { ChatMessageCache } from '../../chat/host';import {- revealedQueuedTurnFamily,isDetachedRunManual,detachedRunByConvoId,pendingRunEndByConvoId,-} from '@librechat/chat/react';-import type { StreamStatusResponse, GenerationProtocolVersion } from '@librechat/chat';-import type { TMessage, TAgentQueuedTurnReceipt } from 'librechat-data-provider';-import type { QueryClient } from '@tanstack/react-query';-import type { useStore } from 'jotai';-import type { SteerState } from './steer';-import { isQueuedTurnSuccessorOwed } from '~/data-provider';-import { dedupeSteersById } from '~/utils';+} from '../../steer/queue';+import { dedupeSteersById, resolveDetachedRunEnd, isQueuedTurnSuccessorOwed } from '../../../core';+import { revealedQueuedTurnFamily } from '../../steer/atoms';++/** The steer chips a finished run settles. */+export type FinishedRunSteers = {+ seedSteerChips: (+ conversationId: string,+ steers: TPendingSteer[] | undefined,+ generationCreatedAt?: number,+ ) => void;+ settleAppliedSteerParts: (conversationId: string, values: unknown[] | undefined) => void;+ convertSteersToQueued: ReturnType<typeof useSteerConvert>;+};/*** Settles what a run that ended while this pane was away left behind: the reveal guard of a@@ -21,7 +29,7 @@ import { dedupeSteersById } from '~/utils';*/export function settleFinishedRun({jotaiStore,- queryClient,+ cache,steers,conversationId,streamStatus,@@ -31,8 +39,8 @@ export function settleFinishedRun({generationProtocolVersion,}: {jotaiStore: ReturnType<typeof useStore>;- queryClient: QueryClient;- steers: Pick<SteerState, 'seedSteerChips' | 'settleAppliedSteerParts' | 'convertSteersToQueued'>;+ cache: Pick<ChatMessageCache, 'messagesUpdatedAt' | 'reloadMessages'>;+ steers: FinishedRunSteers;conversationId: string;streamStatus: StreamStatusResponse;streamStatusUpdatedAt: number;@@ -45,10 +53,7 @@ export function settleFinishedRun({/** A remounted pane may have missed attachment and the quiet-window* timer. An expired job has no epoch; require a fresh inactive read* after restored history before retiring its surviving handoff guard. */- const historyUpdatedAt = queryClient.getQueryState([- QueryKeys.messages,- conversationId,- ])?.dataUpdatedAt;+ const historyUpdatedAt = cache.messagesUpdatedAt(conversationId);if (pendingReveal != null &&streamStatus.active === false &&@@ -112,11 +117,6 @@ export function settleFinishedRun({if (detachedRun != null && isDetachedRunManual(jotaiStore.get, conversationId, detachedRun)) {jotaiStore.set(detachedFamily, null);} else if (detachedRun != null) {- queryClient- .refetchQueries(- { queryKey: [QueryKeys.messages, conversationId], exact: true },- { throwOnError: true },- )- .then(parkDetachedEnd, () => undefined);+ cache.reloadMessages(conversationId).then(parkDetachedEnd, () => undefined);}}diff --git a/client/src/hooks/SSE/successor.ts b/packages/chat/src/react/stream/resume/successor.tssimilarity index 94%rename from client/src/hooks/SSE/successor.tsrename to packages/chat/src/react/stream/resume/successor.tsindex f097500a3d..17731ed73d 100644--- a/client/src/hooks/SSE/successor.ts+++ b/packages/chat/src/react/stream/resume/successor.ts@@ -1,17 +1,17 @@import { useEffect, useMemo, useState } from 'react';import { useStore } from 'jotai';-import { useQueryClient } from '@tanstack/react-query';-import { Constants, QueryKeys } from 'librechat-data-provider';-import { revealedQueuedTurnFamily } from '@librechat/chat/react';+import { Constants } from 'librechat-data-provider';import type { TAgentQueuedTurnReceipt } from 'librechat-data-provider';-import {- useActiveJobs,- useAgentQueuedTurns,- extendActiveJobsGrace,- isQueuedTurnSuccessorOwed,- ACTIVE_JOBS_SUCCESSOR_GRACE_MS,-} from '~/data-provider';-import { agentQueuedTurnsQueryKey } from '~/data-provider/SSE/queuedTurns';+import { revealedQueuedTurnFamily } from '../../steer/atoms';+import { isQueuedTurnSuccessorOwed } from '../../../core';+import { useChatHost } from '../../chat/host';+import { useStreamHost } from '../host';++/**+ * How long a conversation keeps listening for a run the server owes it after the active-job+ * list empties; the app's active-job poll keeps the same window open.+ */+export const ACTIVE_JOBS_SUCCESSOR_GRACE_MS = 30_000;/** What the pane knows about runs it did not start for the conversation on screen. */export type OwedSuccessorState = {@@ -31,7 +31,7 @@ export type OwedSuccessorState = {* Tracks runs the server owes a conversation (a queued turn it took ownership of, or a job* the active-job list names) until this pane attaches to them or a quiet window expires.*/-export default function useOwedSuccessor({+export function useOwedSuccessor({conversationId,resumableEnabled,attachedGenerationCreatedAt,@@ -43,7 +43,9 @@ export default function useOwedSuccessor({hasLiveSubmissionForThisConvo: boolean;}): OwedSuccessorState {const jotaiStore = useStore();- const queryClient = useQueryClient();+ const streamHost = useStreamHost();+ const { extendActiveJobsGrace } = streamHost;+ const cache = useChatHost().useMessageCache();/*** A run this pane did not start (another tab, another device, a scheduled@@ -79,10 +81,8 @@ export default function useOwedSuccessor({* `enabled: false` observes that cache without competing for it, and an* unpopulated cache simply falls back to the handover window.*/- const { data: queuedTurnReceipts, dataUpdatedAt: queuedTurnsObservedAt } = useAgentQueuedTurns(- conversationId ?? '',- false,- );+ const { data: queuedTurnReceipts, dataUpdatedAt: queuedTurnsObservedAt } =+ streamHost.useQueuedTurnReceipts(conversationId ?? '');/*** Receipts whose successor this pane has already attached to, per turn and* per conversation. An `admitted` receipt stays in the cache for a fetch@@ -171,7 +171,7 @@ export default function useOwedSuccessor({conversationId != null ? (owedSuccessors.get(conversationId) ?? null) : null;const successorOwed =!hasLiveSubmissionForThisConvo && (successorOwedByReceipt || owedSuccessor != null);- const { data: activeJobsData, dataUpdatedAt: activeJobsUpdatedAt } = useActiveJobs(+ const { data: activeJobsData, dataUpdatedAt: activeJobsUpdatedAt } = streamHost.useActiveJobs(resumableEnabled,successorOwed,);@@ -294,6 +294,7 @@ export default function useOwedSuccessor({return next;});}, [+ extendActiveJobsGrace,conversationId,queuedTurnReceipts,owedReceipts,@@ -343,13 +344,11 @@ export default function useOwedSuccessor({if (pendingReveal != null &&Date.parse(pendingReveal.revealedAt) <= latch.quietSince! &&- !isQueuedTurnSuccessorOwed(- queryClient.getQueryData(agentQueuedTurnsQueryKey(owedConversationId)),- )+ !isQueuedTurnSuccessorOwed(cache.readQueuedTurns(owedConversationId))) {jotaiStore.set(revealFamily, null);}- queryClient.invalidateQueries({ queryKey: [QueryKeys.messages, owedConversationId] });+ cache.invalidateMessages(owedConversationId);}, remaining),);}@@ -370,7 +369,7 @@ export default function useOwedSuccessor({clearTimeout(timer);}};- }, [owedSuccessors, owedIsReporting, conversationId, queryClient, jotaiStore]);+ }, [owedSuccessors, owedIsReporting, conversationId, cache, jotaiStore]);return {queuedTurnReceipts,diff --git a/packages/chat/src/react/subagents/__tests__/stream.spec.tsx b/packages/chat/src/react/subagents/__tests__/stream.spec.tsxindex c1dabb1793..e1ca91715e 100644--- a/packages/chat/src/react/subagents/__tests__/stream.spec.tsx+++ b/packages/chat/src/react/subagents/__tests__/stream.spec.tsx@@ -77,6 +77,9 @@ const host: StreamHost = {},useLegacyStream: () => undefined,useTransport: () => transport,+ useQueuedTurnReceipts: () => ({ data: undefined, dataUpdatedAt: 0 }),+ useActiveJobs: () => ({ data: undefined, dataUpdatedAt: 0 }),+ extendActiveJobsGrace: () => undefined,};const transport = createSSETransport({ token: 'token-1' });diff --git a/packages/chat/src/react/thread.ts b/packages/chat/src/react/thread.tsnew file mode 100644index 0000000000..a5e39c143c--- /dev/null+++ b/packages/chat/src/react/thread.ts@@ -0,0 +1,70 @@+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';+import { atom, useStore } from 'jotai';+import { atomFamily } from 'jotai/utils';+import type { Atom } from 'jotai';+import type { Family } from './steer/family';++/**+ * Sibling selection of the message thread: per parent, the REVERSED index of+ * the child on display (0 = newest). Feature-owned state, shared by the+ * recursive and flat renderers, the share view, and the writers that focus a+ * regenerated response, restore a resumed branch, or clear a conversation.+ */++/** Recoil keyed `null` and `undefined` parents distinctly from any id; one sentinel keeps that. */+export const NULL_SIBLING_KEY = '__null_parent__';++export const siblingKey = (parentId: string | null | undefined): string =>+ parentId ?? NULL_SIBLING_KEY;++export const siblingIdxFamily: Family<number> = atomFamily((_key: string) => atom(0));++/** Read-only atom over the selections of the given parents, for one subscription per consumer. */+export function siblingIndexesAtom(keys: readonly string[]): Atom<Record<string, number>> {+ return atom((get) => {+ const indexes: Record<string, number> = {};+ for (const key of keys) {+ indexes[key] = get(siblingIdxFamily(key));+ }+ return indexes;+ });+}++function sameKeys(a: readonly string[], b: readonly string[]): boolean {+ if (a === b) {+ return true;+ }+ if (a.length !== b.length) {+ return false;+ }+ for (let i = 0; i < a.length; i += 1) {+ if (a[i] !== b[i]) {+ return false;+ }+ }+ return true;+}++/**+ * Subscribes to the selections of `parentKeys` through one derived atom that+ * is only replaced when the KEYS change by content: callers derive the key+ * list from the messages cache on every write, and a fresh atom per write+ * would hand every consumer a new value object and a render per delta.+ * Read through `useSyncExternalStore` so a consumer renders exactly when the+ * selection object changes, with no mount-time re-render.+ */+export function useSiblingIndexes(parentKeys: readonly string[]): Record<string, number> {+ const jotaiStore = useStore();+ const stableRef = useRef(parentKeys);+ if (!sameKeys(stableRef.current, parentKeys)) {+ stableRef.current = parentKeys;+ }+ const stableKeys = stableRef.current;+ const indexesAtom = useMemo(() => siblingIndexesAtom(stableKeys), [stableKeys]);+ const subscribe = useCallback(+ (onChange: () => void) => jotaiStore.sub(indexesAtom, onChange),+ [jotaiStore, indexesAtom],+ );+ const read = useCallback(() => jotaiStore.get(indexesAtom), [jotaiStore, indexesAtom]);+ return useSyncExternalStore(subscribe, read, read);+}