From ec3b0efa0bcfeb310404ce834b508f25b2b50a42 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Fri, 30 Oct 2026 00:23:14 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=81=20refactor:=20Move=20the=20Resume?= =?UTF-8?q?=20Helpers=20and=20Their=20State=20Into=20the=20Chat=20Package?= =?UTF-8?q?=20(#17562)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- client/src/Providers/ChatHostContext.tsx | 16 +++- client/src/Providers/StreamHostContext.tsx | 5 ++ .../components/Chat/Messages/Thread/state.ts | 76 ++----------------- client/src/components/Chat/approval/state.ts | 45 ++--------- client/src/data-provider/SSE/queries.ts | 3 +- client/src/data-provider/SSE/queuedTurns.ts | 34 +++------ .../SSE/__tests__/useResumeOnLoad.spec.tsx | 42 +++++----- client/src/hooks/SSE/useResumeOnLoad.ts | 22 +++--- packages/chat/src/core/steer/receipts.ts | 21 +++++ packages/chat/src/react.ts | 2 + packages/chat/src/react/approval.ts | 43 +++++++++++ .../src/react/chat/__tests__/stop.spec.tsx | 4 + packages/chat/src/react/chat/host.tsx | 9 +++ .../react/stream/__tests__/adaptive.spec.tsx | 3 + packages/chat/src/react/stream/host.tsx | 20 ++++- packages/chat/src/react/stream/index.ts | 13 +++- .../src/react/stream/resume}/announcements.ts | 23 +++--- .../chat/src/react/stream/resume}/finished.ts | 48 ++++++------ .../src/react/stream/resume}/successor.ts | 45 ++++++----- .../react/subagents/__tests__/stream.spec.tsx | 3 + packages/chat/src/react/thread.ts | 70 +++++++++++++++++ 21 files changed, 322 insertions(+), 225 deletions(-) create mode 100644 packages/chat/src/react/approval.ts rename {client/src/hooks/SSE => packages/chat/src/react/stream/resume}/announcements.ts (91%) rename {client/src/hooks/SSE => packages/chat/src/react/stream/resume}/finished.ts (80%) rename {client/src/hooks/SSE => packages/chat/src/react/stream/resume}/successor.ts (94%) create mode 100644 packages/chat/src/react/thread.ts diff --git a/client/src/Providers/ChatHostContext.tsx b/client/src/Providers/ChatHostContext.tsx index 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(agentQueuedTurnsQueryKey(conversationId)), }; } diff --git a/client/src/Providers/StreamHostContext.tsx b/client/src/Providers/StreamHostContext.tsx index 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.ts index 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> { - return atom((get) => { - const indexes: Record = {}; - 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 { - 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.ts index 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(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.ts index 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.ts index 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 while diff --git a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx index 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({ - - - - - - - {children} - + + + + + + + + + {children} + + + diff --git a/client/src/hooks/SSE/useResumeOnLoad.ts b/client/src/hooks/SSE/useResumeOnLoad.ts index 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, - useIsSubmitting, - submissionStartFamily, - submissionByIndex, + useChatHost, useSubmission, + useIsSubmitting, + useOwedSuccessor, + settleFinishedRun, + submissionByIndex, + 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.ts index 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.ts index 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.ts new file mode 100644 index 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 = atomFamily( + (_conversationId: string) => atom(null), +); + +/** Whether the composer's review panel is expanded for one conversation. */ +export const approvalPanelOpenFamily: Family = 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.tsx index 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.tsx index 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; + /** 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.tsx index 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.tsx index 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>; }; +/** One of the app's queries as a resume reads it: the data and when it was last fetched. */ +export type ResumeQuery = { + data: Data | undefined; + dataUpdatedAt: number; +}; + /** Everything a resumable stream runs on except how it re-attaches, which the binding owns. */ export type ResumableServices = Omit; @@ -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; + /** + * 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(null); diff --git a/packages/chat/src/react/stream/index.ts b/packages/chat/src/react/stream/index.ts index 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.ts similarity index 91% rename from client/src/hooks/SSE/announcements.ts rename to packages/chat/src/react/stream/resume/announcements.ts index 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.ts similarity index 80% rename from client/src/hooks/SSE/finished.ts rename to packages/chat/src/react/stream/resume/finished.ts index 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; +}; /** * 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; - queryClient: QueryClient; - steers: Pick; + cache: Pick; + 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.ts similarity index 94% rename from client/src/hooks/SSE/successor.ts rename to packages/chat/src/react/stream/resume/successor.ts index 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.tsx index 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.ts new file mode 100644 index 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 = 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> { + return atom((get) => { + const indexes: Record = {}; + 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 { + 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); +}