From dda8286ae366c30241bab1641a938100ab733dfc Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Wed, 18 Nov 2026 23:47:44 -0500 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=A7=AD=20feat:=20Queue=20and=20Steer?= =?UTF-8?q?=20a=20Reply=20From=20a=20Side=20Chat?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- client/src/Providers/SideChatHostContext.tsx | 114 +++++- .../__tests__/SideChatHostContext.spec.tsx | 231 +++++++++++- client/src/components/Chat/Input/ChatForm.tsx | 6 + .../hooks/Chat/__tests__/useSteering.spec.tsx | 4 + client/src/hooks/SSE/cache.ts | 48 ++- .../mock/scenarios/side-chat-steering.spec.ts | 352 ++++++++++++++++++ packages/chat/src/components/pane/Driven.tsx | 28 +- .../chat/src/components/pane/Followed.tsx | 21 +- .../components/side/__tests__/panel.spec.tsx | 119 +++++- packages/chat/src/components/side/panel.tsx | 35 +- .../subagents/__tests__/followed.spec.tsx | 1 + .../subagents/__tests__/panel.spec.tsx | 1 + .../chat/src/core/__tests__/apply.spec.ts | 137 ++++++- packages/chat/src/core/apply.ts | 57 ++- packages/chat/src/core/resumable/frames.ts | 48 +-- packages/chat/src/core/resumable/steers.ts | 65 ++++ packages/chat/src/react.ts | 9 +- .../src/react/chat/__tests__/driven.spec.tsx | 156 ++++++++ packages/chat/src/react/chat/contract.ts | 6 + packages/chat/src/react/chat/driven.ts | 1 + packages/chat/src/react/follow.ts | 114 +++++- packages/chat/src/react/side/host.tsx | 5 +- .../chat/src/react/steering/useSteering.ts | 11 +- .../subagents/__tests__/follows.spec.tsx | 1 + packages/chat/src/react/subagents/follows.tsx | 1 + 25 files changed, 1461 insertions(+), 110 deletions(-) create mode 100644 e2e/specs/mock/scenarios/side-chat-steering.spec.ts create mode 100644 packages/chat/src/core/resumable/steers.ts diff --git a/client/src/Providers/SideChatHostContext.tsx b/client/src/Providers/SideChatHostContext.tsx index 5a32abbd567..24a19175410 100644 --- a/client/src/Providers/SideChatHostContext.tsx +++ b/client/src/Providers/SideChatHostContext.tsx @@ -1,20 +1,32 @@ -import { useCallback, useMemo } from 'react'; +import { useRef, useMemo, useState, useEffect, useCallback } from 'react'; import { useStore } from 'jotai'; import { useQueryClient } from '@tanstack/react-query'; import { createGenerationTransport } from '@librechat/chat'; -import { filesFamily, useFollowChat, SIDE_CHAT_PANE } from '@librechat/chat/react'; +import { + filesFamily, + useFollowChat, + SIDE_CHAT_PANE, + useOwedSuccessor, +} from '@librechat/chat/react'; import { dataService, QueryKeys, isAgentsEndpoint, isEphemeralAgentId, } from 'librechat-data-provider'; +import type { + FollowedChat, + SideChatHost, + FollowedRunEnd, + SideChatOptions, + FollowedGeneration, +} from '@librechat/chat/react'; import type { Agent, TMessage, TConversation, ChatFinalFrame } from 'librechat-data-provider'; -import type { FollowedChat, SideChatHost, FollowChatOptions } from '@librechat/chat/react'; import { isTemporaryConversation, proveFetchedReplyByIdentity } from '~/utils'; import { stagedForHandoff, handedComposerFilesFamily } from '~/store/handoff'; import useNavigateToConvo from '~/hooks/Conversations/useNavigateToConvo'; import useAttachmentHandler from '~/hooks/SSE/useAttachmentHandler'; +import { addActiveJob, removeActiveJob } from '~/hooks/SSE/cache'; import { ARTIFACTS_SHEET_MAX_WIDTH } from '~/utils/breakpoints'; import { createConversationCache } from '~/hooks/SSE/services'; import { useConfiguredFooter } from '~/components/Chat/Footer'; @@ -24,7 +36,9 @@ import useScaledMaxWidth from '~/hooks/useScaledMaxWidth'; import { useChatTransport } from './ChatTransportContext'; import { useChatSettings } from './ChatSettingsContext'; import { useLiveAnnouncer } from './AnnouncerContext'; +import useResumableSteers from '~/hooks/SSE/steers'; import { fetchStreamStatus } from '~/data-provider'; +import useSteerState from '~/hooks/SSE/steer'; /** * A conversation of the reader's own as a chat they drive: its messages through the ordinary @@ -36,7 +50,7 @@ function useChat( endpoint, agent_id, }: Pick, - options?: Pick, + options?: SideChatOptions, ): FollowedChat { const id = conversationId ?? ''; const { token } = useChatSettings().auth; @@ -110,11 +124,41 @@ function useChat( ); /** A turn here is said to a screen reader as main chat's is: started, still going, done. */ const { announcePolite: announce } = useLiveAnnouncer(); + /** + * The reader's steers, kept by main chat's own steer state: a steer the run takes resolves + * its chip, the ones still waiting are seeded from what the server holds, and one the run + * never took becomes a queued message when it ends. + */ + const steers = useResumableSteers(useSteerState()); const beside = useMemo( - () => ({ onAttachment, onSettled, announce }), - [onAttachment, onSettled, announce], + () => ({ onAttachment, onSettled, announce, steers }), + [onAttachment, onSettled, announce, steers], + ); + /** + * The generation followed, kept where the app keeps main chat's: listed as running from the + * moment its stream names it, so the list does not announce it as one nobody is following, + * and taken off the list the moment it ends. + */ + const [attached, setAttached] = useState(null); + const { onGeneration: tellGeneration, onRunEnd: tellRunEnd } = options ?? {}; + const onGeneration = useCallback( + (named: FollowedGeneration | null) => { + setAttached(named?.createdAt ?? null); + if (named != null) { + addActiveJob(queryClient, id); + } + tellGeneration?.(named); + }, + [id, queryClient, tellGeneration], ); - return useFollowChat({ + const onRunEnd = useCallback( + (end: FollowedRunEnd) => { + removeActiveJob(queryClient, id); + tellRunEnd?.(end); + }, + [id, queryClient, tellRunEnd], + ); + const followed = useFollowChat({ id, transport: generation, loadMessages, @@ -122,7 +166,63 @@ function useChat( enabled: id !== '', beside, onWithdrawn: options?.onWithdrawn, + onGeneration, + onRunEnd, + }); + useAnnouncedRun(id, attached, followed); + return followed; +} + +/** + * A run the server starts under the conversation without this chat asking for it is followed + * like one it did ask for: the turn the server takes from the reader's queue when a reply ends, + * or a run begun from another tab. Main chat learns of both the same way, from the receipts of + * the queued turns and the list of running generations, and so does this. + * + * Looking costs a status read, and a read of the stored rows when nothing is found. So it looks + * when a look can change what is shown: each time the list is fetched while it names the + * conversation, and when the receipts change (a turn was taken, or dropped) while one is owed. + * A turn that waits long before the server takes it is not looked for on every poll. + */ +function useAnnouncedRun(id: string, attached: number | null, followed: FollowedChat): void { + const { attach } = followed; + const busy = + followed.isLoading || + followed.isFollowing || + followed.status === 'submitted' || + followed.status === 'streaming'; + const { successorOwed, hasActiveJobForThisConvo, activeJobsUpdatedAt, receiptSignature } = + useOwedSuccessor({ + conversationId: id === '' ? undefined : id, + resumableEnabled: id !== '', + attachedGenerationCreatedAt: attached, + hasLiveSubmissionForThisConvo: busy, + }); + const announced = hasActiveJobForThisConvo || successorOwed; + /** What was last acted on while a run stays announced: the receipts, and the list's fetch. */ + const seen = useRef<{ receipts: string | null; listed: number | null }>({ + receipts: null, + listed: null, }); + useEffect(() => { + /** Nothing is decided while a run is in hand: a look ends by leaving this state. */ + if (busy) { + return; + } + if (!announced) { + seen.current = { receipts: null, listed: null }; + return; + } + const moved = seen.current.receipts !== receiptSignature; + const relisted = hasActiveJobForThisConvo && seen.current.listed !== activeJobsUpdatedAt; + seen.current = { + receipts: receiptSignature, + listed: hasActiveJobForThisConvo ? activeJobsUpdatedAt : seen.current.listed, + }; + if (moved || relisted) { + attach(); + } + }, [announced, busy, hasActiveJobForThisConvo, activeJobsUpdatedAt, receiptSignature, attach]); } /** diff --git a/client/src/Providers/__tests__/SideChatHostContext.spec.tsx b/client/src/Providers/__tests__/SideChatHostContext.spec.tsx index 8f715e647cf..0556610d79f 100644 --- a/client/src/Providers/__tests__/SideChatHostContext.spec.tsx +++ b/client/src/Providers/__tests__/SideChatHostContext.spec.tsx @@ -1,15 +1,25 @@ import React from 'react'; import { RecoilRoot } from 'recoil'; +import { getDefaultStore } from 'jotai'; import { act, renderHook, waitFor } from '@testing-library/react'; import { QueryKeys, EModelEndpoint } from 'librechat-data-provider'; -import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { useQuery, QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { + ChatHostProvider, + SteerHostProvider, + StreamHostProvider, + pendingSteersByConvoId, + queuedMessagesByConvoId, +} from '@librechat/chat/react'; import type { TFile, TMessage, ChatEvent, ChatStreamRequest, ChatTransportOptions, + TAgentQueuedTurnReceipt, } from 'librechat-data-provider'; +import type { ChatHost, SteerHost, StreamHost, SideChatOptions } from '@librechat/chat/react'; import type { Transport } from '~/hooks/Chat/contract'; import { findConvoInAllQueries, hasServerFetchedReply, hasLocallyCommittedReply } from '~/utils'; import { ChatTransportContext, defaultChatTransport } from '../ChatTransportContext'; @@ -101,9 +111,36 @@ const listed = (lastResponseAt: string) => { return client; }; +/** + * What tells a chat of runs it did not start, as the app's stream host reads them: the receipts + * of the reader's queued turns and the list of running generations, both from the query cache, + * where a spec puts them. + */ +const RECEIPTS = 'receipts-under-test'; +const streamHost = { + useQueuedTurnReceipts: (conversationId: string) => + useQuery({ + queryKey: [RECEIPTS, conversationId], + enabled: false, + }), + useActiveJobs: () => + useQuery<{ activeJobIds: string[] }>({ queryKey: [QueryKeys.activeJobs], enabled: false }), + extendActiveJobsGrace: () => undefined, +} as unknown as StreamHost; +const chatHost = { + useMessageCache: () => ({ readQueuedTurns: () => [], invalidateMessages: () => undefined }), +} as unknown as ChatHost; + +/** What the steer state reads of its host: the reader's files, and a run's status. */ +const steerHost = { + useFileMap: () => undefined, + useFetchStreamStatus: () => mockStreamStatus, +} as unknown as SteerHost; + const setup = ( target = conversation, client = new QueryClient({ defaultOptions: { queries: { retry: false } } }), + options?: SideChatOptions, ) => { const harness = createTransport(); const announcePolite = jest.fn(); @@ -113,13 +150,17 @@ const setup = ( - {children} + + + {children} + + ); - const view = renderHook(() => appSideChatHost.useChat(target), { wrapper }); + const view = renderHook(() => appSideChatHost.useChat(target, options), { wrapper }); return { ...view, ...harness, client, announcePolite }; }; @@ -327,6 +368,190 @@ describe("the app's side chat host", () => { expect(hasLocallyCommittedReply(client, 'side-conversation', repliedAt)).toBe(true); }); + it('turns a steer the reply never took into the conversation’s next queued message, then says the run ended', async () => { + const store = getDefaultStore(); + const steer = { steerId: 'steer-1', text: 'Also check staging.' }; + store.set(pendingSteersByConvoId('side-conversation'), [ + { ...steer, status: 'pending', createdAt: 1 }, + ]); + store.set(queuedMessagesByConvoId('side-conversation'), []); + mockStreamStatus.mockResolvedValue({ + active: true, + streamId: 'side-conversation', + createdAt: 2000, + generationProtocolVersion: 2, + }); + mockMessages.mockResolvedValue([asked]); + /** What the queue held when the caller was told the run had ended. */ + const queuedAtEnd: string[][] = []; + const onRunEnd = jest.fn(() => + queuedAtEnd.push( + store.get(queuedMessagesByConvoId('side-conversation')).map((item) => item.text), + ), + ); + const onGeneration = jest.fn(); + const { attachments } = setup(conversation, undefined, { onRunEnd, onGeneration }); + await waitFor(() => expect(attachments).toHaveLength(1)); + const emit = (event: ChatEvent) => act(() => attachments[0].options.onEvent(event)); + + emit({ type: 'open' }); + emit({ + type: 'created', + data: { created: true, message: asked, turn: { responseMessageId: 'response-1' } }, + } as ChatEvent); + await waitFor(() => + expect(onGeneration).toHaveBeenLastCalledWith({ createdAt: 2000, protocolVersion: 2 }), + ); + mockStreamStatus.mockResolvedValue({ active: false, generationProtocolVersion: 2 }); + mockMessages.mockResolvedValue([asked, answered]); + emit({ + type: 'final', + data: { + final: true, + generationProtocolVersion: 2, + conversation: { conversationId: 'side-conversation' }, + requestMessage: asked, + responseMessage: answered, + pendingSteers: [steer], + }, + } as ChatEvent); + + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(onRunEnd).toHaveBeenCalledWith( + expect.objectContaining({ outcome: 'completed', generationCreatedAt: 2000 }), + ); + /** Queued before the run is said to have ended, so the drain that follows sends it. */ + expect(queuedAtEnd).toEqual([['Also check staging.']]); + expect(store.get(pendingSteersByConvoId('side-conversation'))).toEqual([]); + }); + + describe('a run it did not start', () => { + const jobs = (client: QueryClient) => + client.getQueryData<{ activeJobIds: string[] }>([QueryKeys.activeJobs])?.activeJobIds; + const finalFrame = { + type: 'final', + data: { + final: true, + conversation: { conversationId: 'side-conversation' }, + requestMessage: asked, + responseMessage: answered, + }, + } as ChatEvent; + /** Opens on a running generation and follows it to its end. */ + const followToEnd = async () => { + mockStreamStatus.mockResolvedValue({ + active: true, + streamId: 'side-conversation', + createdAt: 2000, + generationProtocolVersion: 2, + }); + mockMessages.mockResolvedValue([asked]); + const view = setup(); + await waitFor(() => expect(view.attachments).toHaveLength(1)); + act(() => view.attachments[0].options.onEvent({ type: 'open' })); + /** Listed as running while it is followed, so it is not announced as unattended. */ + await waitFor(() => expect(jobs(view.client)).toEqual(['side-conversation'])); + mockStreamStatus.mockResolvedValue({ active: false }); + mockMessages.mockResolvedValue([asked, answered]); + act(() => view.attachments[0].options.onEvent(finalFrame)); + await waitFor(() => expect(view.result.current.isFollowing).toBe(false)); + /** Off the list as it ends, before the poll would have said so. */ + expect(jobs(view.client)).toEqual([]); + return view; + }; + const settle = () => + act(async () => { + await new Promise((resolve) => setTimeout(resolve, 60)); + }); + + it('is not looked for when a reply ends with nothing owed', async () => { + const { attachments } = await followToEnd(); + const reads = mockMessages.mock.calls.length; + await settle(); + expect(attachments).toHaveLength(1); + expect(mockMessages).toHaveBeenCalledTimes(reads); + }); + + it('is followed when the server takes a turn from the reader’s queue', async () => { + const { attachments, client, result } = await followToEnd(); + /** The server has the turn, and has not started it: nothing to follow yet. */ + mockStreamStatus.mockClear(); + mockStreamStatus.mockResolvedValue({ active: false }); + act(() => + client.setQueryData[]>( + [RECEIPTS, 'side-conversation'], + [{ queuedTurnId: 'turn-1', status: 'queued', expectedPredecessorCreatedAt: 2000 }], + ), + ); + await settle(); + await settle(); + /** Looked for once when the turn became the server's, and not again while it waits. */ + expect(mockStreamStatus).toHaveBeenCalledTimes(1); + expect(attachments).toHaveLength(1); + + /** It starts the turn: the receipt changes, and the generation is there to follow. */ + mockStreamStatus.mockResolvedValue({ + active: true, + streamId: 'side-conversation', + createdAt: 3000, + generationProtocolVersion: 2, + }); + act(() => + client.setQueryData[]>( + [RECEIPTS, 'side-conversation'], + [{ queuedTurnId: 'turn-1', status: 'admitted', effectivePredecessorCreatedAt: 2000 }], + ), + ); + await waitFor(() => expect(attachments).toHaveLength(2)); + act(() => attachments[1].options.onEvent({ type: 'open' })); + await waitFor(() => expect(result.current.isFollowing).toBe(true)); + expect(jobs(client)).toEqual(['side-conversation']); + + /** Following it is the delivery: the same receipt does not send it looking again. */ + mockStreamStatus.mockResolvedValue({ active: false }); + act(() => attachments[1].options.onEvent(finalFrame)); + await waitFor(() => expect(result.current.isFollowing).toBe(false)); + await settle(); + expect(attachments).toHaveLength(2); + }); + + it('is followed when the list of running generations names the conversation', async () => { + const { attachments, client } = await followToEnd(); + mockStreamStatus.mockResolvedValue({ + active: true, + streamId: 'side-conversation', + createdAt: 4000, + generationProtocolVersion: 2, + }); + act(() => + client.setQueryData([QueryKeys.activeJobs], { activeJobIds: ['side-conversation'] }), + ); + await waitFor(() => expect(attachments).toHaveLength(2)); + }); + + it('is looked for once for each time the list names it, not again when a look finds nothing', async () => { + const { attachments, client } = await followToEnd(); + /** The list still names a run that has already ended: one look finds nothing to follow. */ + mockStreamStatus.mockClear(); + mockStreamStatus.mockResolvedValue({ active: false }); + act(() => + client.setQueryData([QueryKeys.activeJobs], { activeJobIds: ['side-conversation'] }), + ); + await settle(); + await settle(); + expect(mockStreamStatus).toHaveBeenCalledTimes(1); + expect(attachments).toHaveLength(1); + + /** Listed again at the next fetch: looked for again, once. */ + act(() => + client.setQueryData([QueryKeys.activeJobs], { activeJobIds: ['side-conversation'] }), + ); + await settle(); + await settle(); + expect(mockStreamStatus).toHaveBeenCalledTimes(2); + }); + }); + it("says a turn through the app's announcer, as main chat's is said", async () => { mockStreamStatus.mockResolvedValue({ active: true, diff --git a/client/src/components/Chat/Input/ChatForm.tsx b/client/src/components/Chat/Input/ChatForm.tsx index 789f1dd36b9..f5a0eaf9f27 100644 --- a/client/src/components/Chat/Input/ChatForm.tsx +++ b/client/src/components/Chat/Input/ChatForm.tsx @@ -140,6 +140,8 @@ interface ChatFormProps { stopGenerating: () => void; /** From ChatContext: the chat stops a reply whether or not its generation has been named. */ stopsUnnamed: boolean; + /** From ChatContext: the chat takes the composer's during-run actions though not main chat. */ + steers: boolean; } const ChatForm = memo(function ChatForm({ @@ -163,6 +165,7 @@ const ChatForm = memo(function ChatForm({ handleStopGenerating, stopGenerating, stopsUnnamed, + steers, }: ChatFormProps) { const submitButtonRef = useRef(null); const textAreaRef = useRef(null); @@ -401,6 +404,7 @@ const ChatForm = memo(function ChatForm({ consumeDraft, addedConversation: addedConvo, index, + duringRun: routed || steers, conversationId, conversation, codeEnvironmentMode: codeWorkspace.mode, @@ -974,6 +978,7 @@ function ChatFormWrapper({ handleStopGenerating, stopGenerating, stopsUnnamed = false, + steers = false, } = useChatContext(); /** @@ -1055,6 +1060,7 @@ function ChatFormWrapper({ handleStopGenerating={stableHandleStop} stopGenerating={stableStop} stopsUnnamed={stopsUnnamed} + steers={steers} /> ); } diff --git a/client/src/hooks/Chat/__tests__/useSteering.spec.tsx b/client/src/hooks/Chat/__tests__/useSteering.spec.tsx index 9d9f554732f..8864b42a938 100644 --- a/client/src/hooks/Chat/__tests__/useSteering.spec.tsx +++ b/client/src/hooks/Chat/__tests__/useSteering.spec.tsx @@ -735,6 +735,10 @@ describe('useSteering', () => { }).result.current.duringRunActive, ).toBe(false); expect(setup({ index: 1 }).result.current.duringRunActive).toBe(false); + /** Another pane's composer joins in only when its chat says it runs these actions. */ + expect(setup({ index: 3, duringRun: false }).result.current.duringRunActive).toBe(false); + expect(setup({ index: 3, duringRun: true }).result.current.duringRunActive).toBe(true); + expect(setup({ duringRun: false }).result.current.duringRunActive).toBe(false); const answerMode = setup({ answerModeActive: true }).result.current; expect(answerMode.duringRunActive).toBe(false); expect(answerMode.pausedOnApproval).toBe(true); diff --git a/client/src/hooks/SSE/cache.ts b/client/src/hooks/SSE/cache.ts index d6fd920c72b..925a4775631 100644 --- a/client/src/hooks/SSE/cache.ts +++ b/client/src/hooks/SSE/cache.ts @@ -8,6 +8,7 @@ import { buildOptimisticConversation, } from '@librechat/chat'; import type { TMessage, TSubmission, TConversation } from 'librechat-data-provider'; +import type { QueryClient } from '@tanstack/react-query'; import type { ResumableCache } from '@librechat/chat'; import type { ActiveJobsResponse } from '~/data-provider'; import { @@ -25,6 +26,20 @@ import { import { transferFileSearchPreference } from '~/hooks/Files/search'; import { fetchConvoSnapshot } from '~/utils/convos'; +/** Lists a generation as running before the active-job poll has seen it. */ +export function addActiveJob(queryClient: QueryClient, jobId: string): void { + queryClient.setQueryData([QueryKeys.activeJobs], (old) => ({ + activeJobIds: [...new Set([...(old?.activeJobIds ?? []), jobId])], + })); +} + +/** Takes a generation that ended off the list before the active-job poll has seen it end. */ +export function removeActiveJob(queryClient: QueryClient, jobId: string): void { + queryClient.setQueryData([QueryKeys.activeJobs], (old) => ({ + activeJobIds: (old?.activeJobIds ?? []).filter((id) => id !== jobId), + })); +} + /** The app's query cache, as a resumable run reads and refreshes it. */ export default function useResumableCache( getMessages: () => TMessage[] | undefined, @@ -32,29 +47,12 @@ export default function useResumableCache( ): ResumableCache { const queryClient = useQueryClient(); - /** - * Optimistically add a job ID to the active jobs cache. - * Called when generation starts. - */ - const addActiveJob = useCallback( - (jobId: string) => { - queryClient.setQueryData([QueryKeys.activeJobs], (old) => ({ - activeJobIds: [...new Set([...(old?.activeJobIds ?? []), jobId])], - })); - }, - [queryClient], - ); + /** Called when generation starts. */ + const addJob = useCallback((jobId: string) => addActiveJob(queryClient, jobId), [queryClient]); - /** - * Optimistically remove a job ID from the active jobs cache. - * Called when generation completes, aborts, or errors. - */ - const removeActiveJob = useCallback( - (jobId: string) => { - queryClient.setQueryData([QueryKeys.activeJobs], (old) => ({ - activeJobIds: (old?.activeJobIds ?? []).filter((id) => id !== jobId), - })); - }, + /** Called when generation completes, aborts, or errors. */ + const removeJob = useCallback( + (jobId: string) => removeActiveJob(queryClient, jobId), [queryClient], ); @@ -130,8 +128,8 @@ export default function useResumableCache( queryClient.removeQueries({ queryKey: streamStatusQueryKey(conversationId) }), invalidateStreamStatus: (conversationId) => queryClient.invalidateQueries({ queryKey: streamStatusQueryKey(conversationId) }), - addActiveJob, - removeActiveJob, + addActiveJob: addJob, + removeActiveJob: removeJob, fetchConversation: (conversationId) => fetchConvoSnapshot(queryClient, conversationId, () => dataService.getConversationById(conversationId), @@ -151,6 +149,6 @@ export default function useResumableCache( queueTitleGeneration, addOptimisticConversation, }), - [addActiveJob, addOptimisticConversation, queryClient, removeActiveJob], + [addJob, addOptimisticConversation, queryClient, removeJob], ); } diff --git a/e2e/specs/mock/scenarios/side-chat-steering.spec.ts b/e2e/specs/mock/scenarios/side-chat-steering.spec.ts new file mode 100644 index 00000000000..45b50657146 --- /dev/null +++ b/e2e/specs/mock/scenarios/side-chat-steering.spec.ts @@ -0,0 +1,352 @@ +import { expect, test } from '@playwright/test'; +import type { Page, Response } from '@playwright/test'; +import type { AgentDetail } from '../agents.helpers'; +import { + replyText, + replyPrompt, + requestJson, + messagesView, + NEW_CHAT_PATH, + MOCK_ENDPOINTS, + getAccessToken, + MOCK_REPLY_TEXT, + conversationRow, + selectMockEndpoint, + sendMessageAndWaitForCompletion, +} from '../helpers'; +import { cleanupAgent, openAgentBuilder, uniqueAgentName } from '../agents.helpers'; +import { openChatHistory } from './sidebar'; + +/** + * What the reader does to a reply in flight in a conversation open beside the chat is what they + * do in main chat: a message queued behind it goes out when it ends, a steer joins it where the + * run takes one and becomes the next message where it does not, an interrupt continues it, and + * a Stop leaves the queue for them to send. All of it is that conversation's: the chat on screen + * gains nothing. + */ +test.use({ viewport: { width: 1440, height: 900 }, isMobile: false, hasTouch: false }); + +/** The endpoint whose runs call a tool, which is where a run takes a steer. */ +const PROVIDER_C = { label: 'Mock Provider C', model: 'mock-model-c' }; +const MCP_SERVER_TITLE = 'E2E Memory'; +const SLOW_REPLY_LAST_CHUNK = 'chunk-159'; + +const uniqueLabel = (prefix: string) => + `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`; + +const isSteer = (response: Response): boolean => + response.request().method() === 'POST' && + new URL(response.url()).pathname === '/api/agents/chat/steer'; + +async function startChat( + page: Page, + label: string, + { + provider = MOCK_ENDPOINTS[0], + tools = false, + agent, + }: { provider?: (typeof MOCK_ENDPOINTS)[number]; tools?: boolean; agent?: string } = {}, +): Promise { + if (agent == null) { + await page.goto(NEW_CHAT_PATH, { timeout: 10_000 }); + await selectMockEndpoint(page, provider); + } else { + /** A saved agent's conversation: its queued turns are the server's to start. */ + const form = await openAgentBuilder(page); + await form.getByRole('combobox', { name: 'Agent', exact: true }).click(); + await page.getByRole('option', { name: agent }).click(); + await expect(form.getByLabel('Agent name')).toHaveValue(agent); + await form.getByRole('button', { name: 'Select Agent' }).click(); + } + if (tools) { + await page.getByRole('button', { name: 'Attach and tools' }).click(); + const server = page + .getByRole('dialog', { name: 'Attach and tools' }) + .getByRole('button', { name: new RegExp(`^${MCP_SERVER_TITLE}\\b`) }); + await server.click(); + await expect(server).toHaveAttribute('aria-pressed', 'true'); + await page.keyboard.press('Escape'); + } + const response = await sendMessageAndWaitForCompletion(page, replyPrompt(label)); + expect(response.ok()).toBeTruthy(); + await expect(messagesView(page).getByText(replyText(label))).toBeVisible(); + return page.url(); +} + +/** Two conversations: the first open beside the second, which stays on screen. */ +async function openBeside( + page: Page, + prefix: string, + earlierChat?: Parameters[2], +) { + const earlier = uniqueLabel(`${prefix}-earlier`); + const earlierUrl = await startChat(page, earlier, earlierChat); + await startChat(page, uniqueLabel(`${prefix}-current`)); + await openChatHistory(page); + const row = conversationRow(page, earlierUrl); + await row.hover(); + await row.getByRole('button', { name: 'Conversation Menu Options' }).click(); + await page.getByRole('menuitem', { name: 'Open beside chat' }).click(); + const sideChat = page.getByRole('region', { name: 'Side chat' }); + await expect(sideChat).toContainText(replyText(earlier), { timeout: 30_000 }); + const side = sideChat.locator('form'); + const field = sideChat.getByRole('textbox', { name: 'Message input' }); + return { + sideChat, + side, + field, + turns: sideChat.locator('.message-render'), + mainTurns: messagesView(page).locator('.message-render'), + queued: sideChat.getByTestId('queued-message-row'), + waiting: sideChat.getByTestId('pending-steers').getByRole('listitem'), + taken: sideChat.locator('[data-testid="steer-part"]:not([data-testid="pending-steers"] *)'), + /** Starts a turn from the side composer. */ + send: async (text: string) => { + await field.click(); + await page.keyboard.type(text); + await page.keyboard.press('Enter'); + }, + /** Writes in the side composer while its reply is being written. */ + write: async (text: string) => { + await field.click(); + await page.keyboard.type(text); + await expect(side.getByTestId('during-run-send-button')).toBeVisible({ timeout: 5_000 }); + }, + }; +} + +/** Enter steers in these scenarios, as in main chat's; Ctrl/Cmd+Enter then queues. */ +test.beforeEach(async ({ page }) => { + await page.addInitScript(() => { + localStorage.setItem('duringRunDefaultAction', JSON.stringify('steer')); + }); +}); + +test('a message queued behind a side chat’s reply is sent when the reply ends @scenario:side-chat-queued-message-follows-the-reply', async ({ + page, +}) => { + test.setTimeout(150_000); + const { sideChat, turns, mainTurns, queued, waiting, send, write } = await openBeside( + page, + 'queue', + ); + const label = uniqueLabel('queued'); + const followUp = `Queued behind the reply ${label}`; + + await send(`E2E_SLOW_REPLY:${label}`); + await expect(sideChat).toContainText('chunk-010', { timeout: 30_000 }); + await write(followUp); + await page.keyboard.press('ControlOrMeta+Enter'); + + /** It waits in the side composer's queue, not in the reply and not in main chat's composer. */ + await expect(queued.filter({ hasText: followUp })).toHaveCount(1); + await expect(page.getByTestId('queued-message-row')).toHaveCount(1); + await expect(waiting).toHaveCount(0); + + /** The reply runs to its end, and the queued message is the conversation's next turn. */ + await expect(queued).toHaveCount(0, { timeout: 90_000 }); + await expect(turns).toHaveCount(6, { timeout: 30_000 }); + await expect(turns.nth(3)).toContainText(SLOW_REPLY_LAST_CHUNK); + await expect(turns.nth(4)).toContainText(followUp); + await expect(turns.nth(4).locator('.user-turn')).toBeVisible(); + await expect(turns.nth(5)).toContainText(MOCK_REPLY_TEXT, { timeout: 30_000 }); + await expect(mainTurns).toHaveCount(2); +}); + +test('a steer sent from a side chat joins its reply where the run takes it @scenario:side-chat-steer-joins-the-reply', async ({ + page, +}) => { + test.setTimeout(180_000); + const { sideChat, side, turns, mainTurns, queued, waiting, taken, send, write } = + await openBeside(page, 'steer', { provider: PROVIDER_C, tools: true }); + const label = uniqueLabel('steered'); + const steer = `Steer into the reply ${label}`; + + /** A preamble, a tool call (where a steer is taken), then the rest of the reply. */ + await send(`E2E_STEER_TOOL_REPLY:${label}`); + await write(steer); + await expect(side.getByTestId('during-run-send-button')).toHaveAttribute( + 'data-during-run-action', + 'steer', + ); + const [accepted] = await Promise.all([ + page.waitForResponse(isSteer, { timeout: 15_000 }), + page.keyboard.press('Enter'), + ]); + expect(accepted.status()).toBe(202); + + /** Shown waiting at the end of the side chat's list until the run takes it. */ + await expect(waiting.filter({ hasText: steer })).toHaveCount(1, { timeout: 10_000 }); + await expect(taken).toHaveCount(0); + + await expect(taken.filter({ hasText: steer })).toHaveCount(1, { timeout: 60_000 }); + await expect(waiting).toHaveCount(0); + await expect(sideChat.getByText(`E2E steer tool reply done ${label}`)).toBeVisible({ + timeout: 60_000, + }); + await expect(sideChat.getByText(`[steers-seen=1] ${steer}`)).toBeVisible({ timeout: 30_000 }); + + /** It stays inside the reply: no turn of its own, nothing left queued, main chat untouched. */ + await expect(turns).toHaveCount(4); + await expect(taken.filter({ hasText: steer })).toHaveCount(1); + await expect(queued).toHaveCount(0); + await expect(mainTurns).toHaveCount(2); +}); + +test('a steer a side chat’s reply never took is sent as its next message @scenario:side-chat-steer-not-taken-follows-the-reply', async ({ + page, +}) => { + test.setTimeout(150_000); + const { sideChat, turns, mainTurns, queued, waiting, taken, send, write } = await openBeside( + page, + 'late', + ); + const label = uniqueLabel('late'); + const steer = `Steer with nowhere to land ${label}`; + + /** A reply with no tool call has no point at which a run takes a steer. */ + await send(`E2E_SLOW_REPLY:${label}`); + await expect(sideChat).toContainText('chunk-010', { timeout: 30_000 }); + await write(steer); + const [accepted] = await Promise.all([ + page.waitForResponse(isSteer, { timeout: 15_000 }), + page.keyboard.press('Enter'), + ]); + expect(accepted.status()).toBe(202); + await expect(waiting.filter({ hasText: steer })).toHaveCount(1, { timeout: 10_000 }); + + /** The reply ends without it, and the words go out as the conversation's next turn. */ + await expect(turns).toHaveCount(6, { timeout: 90_000 }); + await expect(turns.nth(3)).toContainText(SLOW_REPLY_LAST_CHUNK); + await expect(turns.nth(4)).toContainText(steer); + await expect(turns.nth(4).locator('.user-turn')).toBeVisible(); + await expect(turns.nth(5)).toContainText(MOCK_REPLY_TEXT, { timeout: 30_000 }); + await expect(waiting).toHaveCount(0); + await expect(taken).toHaveCount(0); + await expect(queued).toHaveCount(0); + await expect(mainTurns).toHaveCount(2); +}); + +test('an interrupt from a side chat keeps what was written and continues the reply @scenario:side-chat-interrupt-continues-the-reply', async ({ + page, +}) => { + test.setTimeout(150_000); + const { sideChat, turns, mainTurns, queued, taken, send, write } = await openBeside( + page, + 'interrupt', + ); + const label = uniqueLabel('interrupted'); + const words = `Interrupt with this ${label}`; + + await send(`E2E_SLOW_REPLY:${label}`); + await expect(sideChat).toContainText('chunk-010', { timeout: 30_000 }); + await write(words); + await page.keyboard.press('Alt+Enter'); + + await expect(taken.filter({ hasText: words })).toHaveCount(1, { timeout: 30_000 }); + await expect(sideChat.getByText(`[steers-seen=1] ${words}`)).toBeVisible({ timeout: 30_000 }); + await expect(sideChat.getByText(`E2E slow reply continued ${label}`)).toBeVisible({ + timeout: 30_000, + }); + + /** One reply, cut where the interrupt landed and carried on: no turn of its own. */ + await expect(turns).toHaveCount(4); + await expect(sideChat).toContainText('chunk-010'); + await expect(sideChat.getByText(SLOW_REPLY_LAST_CHUNK)).toHaveCount(0); + await expect(queued).toHaveCount(0); + await expect(mainTurns).toHaveCount(2); +}); + +test('stopping a side chat’s reply leaves what was queued behind it for the reader to send @scenario:side-chat-stop-keeps-the-queue', async ({ + page, +}) => { + test.setTimeout(150_000); + const { sideChat, side, turns, queued, send, write } = await openBeside(page, 'stopped'); + const label = uniqueLabel('stopped'); + const followUp = `Queued behind a stop ${label}`; + + await send(`E2E_SLOW_REPLY:${label}`); + await expect(sideChat).toContainText('chunk-010', { timeout: 30_000 }); + await write(followUp); + await page.keyboard.press('ControlOrMeta+Enter'); + await expect(queued.filter({ hasText: followUp })).toHaveCount(1); + + await side.getByRole('button', { name: 'Stop generating' }).click(); + await expect(side.getByRole('button', { name: 'Stop generating' })).toHaveCount(0, { + timeout: 30_000, + }); + + /** A stop is not an end the queue goes out on: the row waits, with its own Send. */ + await expect(sideChat.getByText(SLOW_REPLY_LAST_CHUNK)).toHaveCount(0); + await expect(queued.filter({ hasText: followUp })).toHaveCount(1); + await expect(turns).toHaveCount(4); + + await queued.getByRole('button', { name: 'Send now' }).click(); + await expect(queued).toHaveCount(0, { timeout: 30_000 }); + await expect(turns).toHaveCount(6, { timeout: 30_000 }); + await expect(turns.nth(4)).toContainText(followUp); + await expect(turns.nth(5)).toContainText(MOCK_REPLY_TEXT, { timeout: 30_000 }); +}); + +test('a message queued behind a saved agent’s reply in a side chat is started by the server and followed there @scenario:side-chat-server-queued-turn-is-followed', async ({ + page, +}) => { + test.setTimeout(180_000); + let agentId: string | undefined; + try { + await page.goto(NEW_CHAT_PATH, { timeout: 10_000 }); + const agent = await requestJson(page, { + path: '/api/agents', + token: await getAccessToken(page), + method: 'POST', + body: { + name: uniqueAgentName('E2E Side Queue Agent'), + description: 'Playwright verification of a queued turn in a side chat.', + instructions: 'Follow the deterministic end-to-end request exactly.', + provider: MOCK_ENDPOINTS[0].label, + model: MOCK_ENDPOINTS[0].model, + }, + }); + agentId = agent.id; + const { sideChat, side, turns, mainTurns, queued, send, write } = await openBeside( + page, + 'agent-queue', + { agent: agent.name }, + ); + const label = uniqueLabel('agent-queued'); + const followUp = `Queued for the server ${label}`; + + await send(`E2E_SLOW_REPLY:${label}`); + await expect(sideChat).toContainText('chunk-010', { timeout: 30_000 }); + await write(followUp); + /** The queue of an agent's conversation is kept by the server, which starts the turn. */ + const [enqueued] = await Promise.all([ + page.waitForResponse( + (response) => + response.request().method() === 'POST' && + new URL(response.url()).pathname === '/api/agents/chat/queued-turns', + { timeout: 10_000 }, + ), + page.keyboard.press('ControlOrMeta+Enter'), + ]); + expect(enqueued.ok()).toBeTruthy(); + await expect(queued.filter({ hasText: followUp })).toHaveCount(1); + + /** + * The reply ends, the server starts the queued turn, and the side chat follows a run it did + * not start: the turn and its reply arrive, with one copy of the words and nothing waiting. + */ + await expect(turns).toHaveCount(6, { timeout: 120_000 }); + await expect(turns.nth(3)).toContainText(SLOW_REPLY_LAST_CHUNK); + await expect(turns.nth(4)).toContainText(followUp); + await expect(turns.nth(4).locator('.user-turn')).toBeVisible(); + await expect(turns.nth(5)).toContainText(MOCK_REPLY_TEXT, { timeout: 30_000 }); + await expect(turns.filter({ hasText: followUp })).toHaveCount(1); + await expect(sideChat.getByTestId('pending-turn')).toHaveCount(0); + await expect(queued).toHaveCount(0); + await expect(side.getByRole('button', { name: 'Stop generating' })).toHaveCount(0); + await expect(mainTurns).toHaveCount(2); + } finally { + await cleanupAgent(page, agentId); + } +}); diff --git a/packages/chat/src/components/pane/Driven.tsx b/packages/chat/src/components/pane/Driven.tsx index 57dd69ec288..382e6290387 100644 --- a/packages/chat/src/components/pane/Driven.tsx +++ b/packages/chat/src/components/pane/Driven.tsx @@ -1,6 +1,10 @@ import type { ReactElement } from 'react'; +import type { ChatContract } from '../../react/chat/contract'; import type { ChatScreenMessagesSlots } from './messages'; import type { FollowedChat } from '../../react/follow'; +import useQueuedTurnReveal from '../../react/steering/useQueuedTurnReveal'; +import useQueueDrain from '../../react/steering/useQueueDrain'; +import { useOptionalSteerHost } from '../../react/steer/host'; import { useDrivenContract } from '../../react/chat/driven'; import { ContractThread } from './Followed'; @@ -31,6 +35,28 @@ export default function DrivenThread({ children, }: DrivenThreadProps): ReactElement { const contract = useDrivenContract({ id, followed, index }); - const thread = ; + /** Only an app that hosts the steer hooks has a queue for the reader to fill. */ + const queues = useOptionalSteerHost() != null; + const thread = ( + <> + {queues && } + + + ); return children == null ? thread : children(contract, thread); } + +/** + * What the reader queued behind a run goes out when the run ends, as it does in main chat: the + * pane's run end, which whoever follows the chat publishes, lets the next queued message go + * through the contract's own `ask`. + */ +function QueueDrain({ + id, + index, + ask, +}: Pick & { ask: ChatContract['ask'] }): null { + const revealQueuedTurn = useQueuedTurnReveal(id, index); + useQueueDrain(index, id, ask, revealQueuedTurn); + return null; +} diff --git a/packages/chat/src/components/pane/Followed.tsx b/packages/chat/src/components/pane/Followed.tsx index e128d9fdd17..4a647e3c77e 100644 --- a/packages/chat/src/components/pane/Followed.tsx +++ b/packages/chat/src/components/pane/Followed.tsx @@ -31,7 +31,7 @@ export type FollowedThreadProps = { const none = (): null => null; /** - * A conversation beside the main one has no queued turn of the reader's waiting on it and no + * A conversation the reader only follows has no queued turn of theirs waiting on it and no * steers of theirs, and a surface narrow enough to sit beside a chat has no room for the * navigation rail. */ @@ -41,6 +41,12 @@ const followedSlots: ChatScreenMessagesSlots = { renderNav: none, }; +/** + * One of their own, which they drive, has both: the steers a run has not taken yet and the + * queued turn about to be sent are drawn at the end of its list, as main chat draws them. + */ +const ownSlots: ChatScreenMessagesSlots = { renderNav: none }; + /** The chat's own list, where the page's host would hand a row main chat's. */ const useFollowedMessages: MessagesHost['useGetMessages'] = () => useChatContext().getMessages; const useNoPendingTurn: MessagesHost['useHasPendingTurn'] = () => false; @@ -50,9 +56,9 @@ const useNoAddedConversation: MessagesHost['useGetAddedConvo'] = () => noAddedCo /** * The page's messages host with the members that act on main chat pointed at this one: a row - * reads this chat's list, the reader has no queued turn here, and a rerun here does not take - * the model main chat is being compared with. Reading it marks a conversation seen only when it - * is one of the reader's own (`own`); a thread that is not has no read state of theirs to mark. + * reads this chat's list, and a rerun here does not take the model main chat is being compared + * with. Only a conversation of the reader's own (`own`) has a queued turn of theirs to wait on, + * and read state of theirs to mark when it is read. */ function useFollowedMessagesHost(own: boolean): MessagesHost { const host = useMessagesHost(); @@ -60,9 +66,8 @@ function useFollowedMessagesHost(own: boolean): MessagesHost { () => ({ ...host, useGetMessages: useFollowedMessages, - useHasPendingTurn: useNoPendingTurn, useGetAddedConvo: useNoAddedConversation, - ...(!own && { useSeenSource: useNoSeenSource }), + ...(!own && { useHasPendingTurn: useNoPendingTurn, useSeenSource: useNoSeenSource }), }), [host, own], ); @@ -94,7 +99,7 @@ export function ContractThread({ /** The rows are the package's own, under whatever of the conversation is still to be read. */ const listSlots = useMemo( () => ({ - ...followedSlots, + ...(own ? ownSlots : followedSlots), renderThread: (props) => ( <> {`user=${text}`}; } +const steerHost = createSteerHost(); + /** The page's read state, which a list asks for when reading it can mark a conversation seen. */ const pageSeenSource = jest.fn(() => inertSeenSource); const messagesHost = createMessagesHost({ @@ -157,12 +163,15 @@ function setup({ loadMessages = jest.fn(async () => stored), canSubmit = () => true, Surface, + steers = false, }: { chat?: SideChat; stored?: TMessage[]; loadMessages?: jest.Mock>; canSubmit?: () => boolean; Surface?: SideChatHost['Surface']; + /** Whether the app around the panel hosts the steer hooks, and so keeps a queue. */ + steers?: boolean; } = {}) { const streams: TestStream[] = []; const sendMessages = jest.fn( @@ -209,6 +218,8 @@ function setup({ const handOffComposerText = jest.fn(); const queryClient = new QueryClient(); const store = createStore(); + const within = (panel: React.ReactElement) => + steers ? {panel} : panel; const tree = (current: SideChat) => ( @@ -230,11 +241,13 @@ function setup({ - onHandedTextTaken()} - /> + {within( + onHandedTextTaken()} + />, + )} @@ -252,6 +265,7 @@ function setup({ view.unmount(); return render(tree(chat)); }, + store, streams, sendMessages, abort, @@ -337,6 +351,99 @@ describe('SideChatPanel', () => { ]); }); + describe('with a queue of the reader’s behind a run', () => { + const queued: QueuedMessage = { id: 'queued-1', text: 'And then?', createdAt: 1 }; + /** Sends a turn from the field and returns the message the server would store for it. */ + const start = async ({ + sendMessages, + streams, + }: ReturnType): Promise => { + await waitFor(() => expect(rows()).toHaveLength(2)); + fireEvent.change(field(), { target: { value: 'What changed?' } }); + fireEvent.click(screen.getByTestId('composer-send-button')); + await waitFor(() => expect(streams).toHaveLength(1)); + return { + ...user, + messageId: sendMessages.mock.calls[0][0].payload.messageId as string, + parentMessageId: 'response-1', + text: 'What changed?', + }; + }; + + it('names the running generation for the composer’s controls, and sends the next queued message when it ends', async () => { + const view = setup({ steers: true }); + const { store, streams, sendMessages } = view; + const asked = await start(view); + + /** What a steer, a queued turn and an interrupt address while the reply is written. */ + expect(store.get(activeGenerationCreatedAtByConvoId(conversationId))).toBe(3000); + act(() => store.set(queuedMessagesByConvoId(conversationId), [queued])); + + act(() => { + streams[0].push({ + type: 'created', + data: { created: true, message: asked, turn: { responseMessageId: 'response-2' } }, + } as ChatEvent); + streams[0].push(final(asked, reply('response-2', 'Two fixes.', asked.messageId))); + }); + + await waitFor(() => expect(sendMessages).toHaveBeenCalledTimes(2)); + expect(sendMessages.mock.calls[1][0].payload).toMatchObject({ + conversationId, + text: 'And then?', + parentMessageId: 'response-2', + }); + expect(store.get(queuedMessagesByConvoId(conversationId))).toEqual([]); + }); + + it('keeps the queue for the reader to send when they stopped the run', async () => { + const view = setup({ steers: true }); + const { store, streams, sendMessages, abort } = view; + const asked = await start(view); + act(() => store.set(queuedMessagesByConvoId(conversationId), [queued])); + + fireEvent.click(await screen.findByRole('button', { name: 'Stop generating' })); + await waitFor(() => expect(abort).toHaveBeenCalledTimes(1)); + act(() => { + streams[0].push({ + type: 'final', + data: { + final: true, + aborted: true, + conversation: { conversationId }, + requestMessage: asked, + responseMessage: { + ...reply('response-2', 'Two', asked.messageId), + unfinished: true, + }, + }, + } as ChatEvent); + }); + await waitFor(() => + expect(screen.queryByRole('button', { name: 'Stop generating' })).not.toBeInTheDocument(), + ); + await settle(); + + expect(store.get(activeGenerationCreatedAtByConvoId(conversationId))).toBeNull(); + expect(sendMessages).toHaveBeenCalledTimes(1); + expect(store.get(queuedMessagesByConvoId(conversationId))).toEqual([queued]); + }); + + it('sends nothing of a queue where the app hosts no steer hooks', async () => { + const view = setup(); + const { store, streams, sendMessages } = view; + const asked = await start(view); + act(() => store.set(queuedMessagesByConvoId(conversationId), [queued])); + + act(() => streams[0].push(final(asked, reply('response-2', 'Two fixes.', asked.messageId)))); + await waitFor(() => + expect(screen.queryByRole('button', { name: 'Stop generating' })).not.toBeInTheDocument(), + ); + await settle(); + expect(sendMessages).toHaveBeenCalledTimes(1); + }); + }); + it('settles the reply and takes the next message', async () => { const { streams, sendMessages } = setup(); await waitFor(() => expect(rows()).toHaveLength(2)); diff --git a/packages/chat/src/components/side/panel.tsx b/packages/chat/src/components/side/panel.tsx index 1aff1338e88..3a228cde1ea 100644 --- a/packages/chat/src/components/side/panel.tsx +++ b/packages/chat/src/components/side/panel.tsx @@ -1,15 +1,21 @@ import { useRef, useEffect, useCallback } from 'react'; -import { useAtom } from 'jotai'; +import { useAtom, useStore } from 'jotai'; import { ArrowUpRight, X } from 'lucide-react'; import { cn, Button, Composer, useLocalize, useFocusTrap } from '@librechat/client'; import type { ComposerStopProps, ComposerKeyVerdict } from '@librechat/client'; import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from 'react'; +import type { FollowedGeneration, FollowedRunEnd } from '../../react/follow'; import type { ChatContract } from '../../react/chat/contract'; import type { SideChat } from '../../react/side/state'; import type { SubmittedTurn } from '../../core'; +import { + activeGenerationCreatedAtByConvoId, + activeGenerationProtocolVersionByConvoId, +} from '../../react/steer/atoms'; import { SIDE_CHAT_PANE, sideChatDraftFamily } from '../../react/side/state'; import { useChatSurface } from '../../react/subagents/surface'; import { resolveComposerKeyDown } from '../../core/shortcuts'; +import { runEndByIndex } from '../../react/steer/queue'; import { useSideChatHost } from '../../react/side/host'; import { useChatHost } from '../../react/chat/host'; import DrivenThread from '../pane/Driven'; @@ -173,7 +179,32 @@ export default function SideChatPanel({ }, [setDraft], ); - const followed = host.useChat(chat.conversation, { onWithdrawn: takeBack }); + /** + * The run under this conversation, published where main chat's stream session publishes its + * own: the generation in flight, which a stop or a steer addresses, and each run's end, which + * lets the next queued message go. So the composer's controls for a run in flight work here. + */ + const store = useStore(); + const noteGeneration = useCallback( + (generation: FollowedGeneration | null) => { + store.set(activeGenerationCreatedAtByConvoId(conversationId), generation?.createdAt ?? null); + store.set( + activeGenerationProtocolVersionByConvoId(conversationId), + generation?.protocolVersion ?? 1, + ); + }, + [conversationId, store], + ); + const noteRunEnd = useCallback( + (end: FollowedRunEnd) => + store.set(runEndByIndex(SIDE_CHAT_PANE), { ...end, conversationId, endedAt: Date.now() }), + [conversationId, store], + ); + const followed = host.useChat(chat.conversation, { + onWithdrawn: takeBack, + onGeneration: noteGeneration, + onRunEnd: noteRunEnd, + }); const panelRef = useRef(null); /** The pane's conversation is what a turn is built from, so the pane is told which it holds. */ diff --git a/packages/chat/src/components/subagents/__tests__/followed.spec.tsx b/packages/chat/src/components/subagents/__tests__/followed.spec.tsx index 31a14e7926d..e3fa442f56f 100644 --- a/packages/chat/src/components/subagents/__tests__/followed.spec.tsx +++ b/packages/chat/src/components/subagents/__tests__/followed.spec.tsx @@ -63,6 +63,7 @@ const followedChat = (overrides: Partial = {}): FollowedChat => ({ canSend: () => false, send: () => false, stop: () => Promise.resolve(), + attach: () => undefined, ...overrides, }); diff --git a/packages/chat/src/components/subagents/__tests__/panel.spec.tsx b/packages/chat/src/components/subagents/__tests__/panel.spec.tsx index 356bf238551..64f33dbc11c 100644 --- a/packages/chat/src/components/subagents/__tests__/panel.spec.tsx +++ b/packages/chat/src/components/subagents/__tests__/panel.spec.tsx @@ -4768,6 +4768,7 @@ describe('SubagentThreadPanel', () => { canSend: () => false, send: () => false, stop: () => Promise.resolve(), + attach: () => undefined, ...overrides, }); diff --git a/packages/chat/src/core/__tests__/apply.spec.ts b/packages/chat/src/core/__tests__/apply.spec.ts index 7d22f6c7f4d..fd166301239 100644 --- a/packages/chat/src/core/__tests__/apply.spec.ts +++ b/packages/chat/src/core/__tests__/apply.spec.ts @@ -1122,7 +1122,7 @@ describe('a turn whose shape the server states', () => { describe('state beside the message list', () => { /** Main chat's handlers for that state, recording what they are called with and in what order. */ - const record = () => { + const record = (protocol?: 1 | 2) => { const calls: Array<[string, ...unknown[]]> = []; const log = (name: string, result?: unknown) => @@ -1149,7 +1149,12 @@ describe('state beside the message list', () => { update: log('update'), seed: log('seed'), settleApplied: log('settle'), + appliedIds: log('appliedIds', ['steer-taken']), + adoptPromoted: log('adopt', ['steer-promoted']), + convertToQueued: log('toQueued'), + convertLocalToQueued: log('sweep'), }, + protocol: () => protocol, } as unknown as Parameters[0]; return { calls, init, names: () => calls.map(([name]) => name) }; }; @@ -1199,6 +1204,11 @@ describe('state beside the message list', () => { 'attachment', 'title', 'update', + 'appliedIds', + 'settle', + 'adopt', + 'toQueued', + 'sweep', 'finalize', ]); const turn = expect.objectContaining({ @@ -1211,7 +1221,130 @@ describe('state beside the message list', () => { { data: (attachment as { data: unknown }).data, submission: turn }, ]); expect(calls[5]).toEqual(['title', (title as { data: unknown }).data]); - expect(calls[7]).toEqual(['finalize', (final('Hi') as { data: unknown }).data, turn]); + expect(calls[12]).toEqual(['finalize', (final('Hi') as { data: unknown }).data, turn]); + }); + + it('turns the steers a run never took into queued turns at its final frame, before its usage settles', () => { + const { calls, init } = record(); + const { applyEvent } = createEventApplier(init); + const { context: ctx } = createList(); + const left = { steerId: 'steer-left', text: 'Still waiting' }; + const ending = final('Hi') as Extract; + const frame = { + ...ending, + data: { + ...ending.data, + generationProtocolVersion: 2, + promotedSteers: [{ steerId: 'steer-promoted' }], + pendingSteers: [ + left, + { steerId: 'steer-taken', text: 'In the reply' }, + { steerId: 'server-id', clientSteerId: 'steer-promoted', text: 'Queued by the server' }, + ], + }, + } as ChatEvent; + + applyEvent(created, ctx); + applyEvent(opened('s0', 0), ctx); + applyEvent(frame, ctx); + + const reply = (frame as { data: { responseMessage: unknown } }).data.responseMessage; + const named = calls.filter(([name]) => + ['appliedIds', 'settle', 'adopt', 'toQueued', 'sweep', 'finalize'].includes(name), + ); + expect(named.map(([name]) => name)).toEqual([ + 'appliedIds', + 'settle', + 'adopt', + 'toQueued', + 'sweep', + 'finalize', + ]); + expect(named[1]).toEqual(['settle', 'thread-1', [reply]]); + expect(named[2]).toEqual(['adopt', 'thread-1', [{ steerId: 'steer-promoted' }]]); + /** Only the one neither in the reply nor already a turn of the server's. */ + expect(named[3]).toEqual([ + 'toQueued', + 'thread-1', + [left], + { claimParked: true, generationProtocolVersion: undefined }, + ]); + expect(named[4]).toEqual(['sweep', 'thread-1']); + }); + + it('queues none of a final frame’s steers when neither it nor the generation speaks their protocol', () => { + const { calls, init } = record(); + const { applyEvent } = createEventApplier(init); + const { context: ctx } = createList(); + const ending = final('Hi') as Extract; + + applyEvent(created, ctx); + applyEvent( + { + ...ending, + data: { ...ending.data, pendingSteers: [{ steerId: 'steer-left', text: 'Waiting' }] }, + } as ChatEvent, + ctx, + ); + expect(calls.find(([name]) => name === 'toQueued')?.[2]).toEqual([]); + + /** A generation known to be on the first protocol carries them without the frame's echo. */ + const legacy = record(1); + const second = createEventApplier(legacy.init); + const list = createList(); + second.applyEvent(created, list.context); + second.applyEvent( + { + ...ending, + data: { ...ending.data, pendingSteers: [{ steerId: 'steer-left', text: 'Waiting' }] }, + } as ChatEvent, + list.context, + ); + expect(legacy.calls.find(([name]) => name === 'toQueued')?.slice(2)).toEqual([ + [{ steerId: 'steer-left', text: 'Waiting' }], + { claimParked: true, generationProtocolVersion: 1 }, + ]); + }); + + it('claims the steers an error the server wrote left behind, and moves none for a dropped stream', () => { + const { calls, init } = record(); + const { applyEvent } = createEventApplier(init); + const { context: ctx } = createList(); + const sweeps = () => calls.filter(([name]) => name === 'sweep'); + + applyEvent(created, ctx); + /** A connection that dropped ends nothing: the run goes on, and so do its steers. */ + applyEvent({ type: 'error', status: 0 }, ctx); + applyEvent({ type: 'error', status: 404, data: { message: 'gone' } }, ctx); + expect(sweeps()).toEqual([]); + + /** An error from a server that does not speak the protocol parks nothing to claim. */ + applyEvent({ type: 'error', data: { message: 'failed' } }, ctx); + expect(sweeps()).toEqual([]); + + applyEvent( + { type: 'error', data: { message: 'failed', generationProtocolVersion: 2 } } as ChatEvent, + ctx, + ); + expect(sweeps()).toEqual([ + ['sweep', 'thread-1', { claimParked: true, generationProtocolVersion: undefined }], + ]); + }); + + it('moves only the steers the server refused when the reader closes the stream', () => { + const { calls, init } = record(); + const { applyEvent } = createEventApplier(init); + const { context: ctx } = createList(); + + /** No turn is named yet, so there is no conversation whose steers to move. */ + applyEvent({ type: 'abort' }, ctx); + expect(calls.filter(([name]) => name === 'sweep')).toEqual([]); + + applyEvent(created, ctx); + applyEvent({ type: 'abort' }, ctx); + expect(calls.filter(([name]) => name === 'sweep')).toEqual([ + ['sweep', 'thread-1', { statuses: ['failed'] }], + ]); }); it('rebuilds what a late joiner missed from the snapshot, then applies what it carries', () => { diff --git a/packages/chat/src/core/apply.ts b/packages/chat/src/core/apply.ts index 17b1ee51bb9..507e5263dac 100644 --- a/packages/chat/src/core/apply.ts +++ b/packages/chat/src/core/apply.ts @@ -14,6 +14,8 @@ import type { import type { ResumableUsage, ResumableSteers, ResumableEvents } from './resumable/host'; import type { StepEvent, StepEffect, StepContext } from './reducer'; import type { Placement, PlacementContext } from './parts/place'; +import type { GenerationProtocolVersion } from './protocol'; +import type { FinalSteers } from './resumable/steers'; import type { ChatEventContext } from './chat'; import { reduceStep, @@ -34,6 +36,9 @@ import { buildResumeEventSubmission, buildSubmissionFromResumeState } from './re import { getStepEventId, isOAuthStepEvent } from './resumable/events'; import { buildCreatedInitialResponse } from './resumable/messages'; import { placeResumedResponse } from './resumable/placement'; +import { supportsGenerationProtocolV2 } from './protocol'; +import { settleFinalSteers } from './resumable/steers'; +import { ABORT_SWEEP_STATUSES } from './steer/chips'; import { normalizeFrame } from './transport/frames'; import { getEditPrefix } from './steps/content'; import { withEditedPart } from './content'; @@ -60,10 +65,13 @@ export type EventApplierInit = { usage?: ResumableUsage; onAttachment?: ResumableEvents['attachmentHandler']; onTitle?: ResumableEvents['titleHandler']; - steers?: Pick< - ResumableSteers, - 'resolve' | 'markLiveApplied' | 'update' | 'seed' | 'settleApplied' - >; + steers?: Pick & FinalSteers; + /** + * The protocol version of the generation whose frames are being applied, when the caller + * knows it: what main chat's session reads off its stream. It decides whether the steers a + * terminal frame carries are ones this client may turn into queued turns. + */ + protocol?: () => GenerationProtocolVersion | undefined; /** * The turn this chat sent and drew rows for, while the stream it opened for it runs. The * server stores the turn's message under an id of its own and names that in its `created` @@ -484,6 +492,38 @@ export function createEventApplier(init: EventApplierInit = {}): EventApplier { } }; + /** The conversation whose steers a terminal frame settles: the frame's, else the turn's. */ + const steerTarget = (named?: string | null): string | undefined => { + const target = named ?? submission?.conversation?.conversationId; + return target == null || target === '' ? undefined : target; + }; + + /** + * A run that ends with no final frame leaves the reader's steers where main chat's session + * leaves them. An error the server wrote parks the ones it had accepted, so they are claimed + * as queued turns and a reload cannot bring their chips back. A stream the reader closed may + * still be running on the server, which will take the steers it holds: only the ones it + * refused are moved, so they are not drawn under the next reply. A dropped connection (an + * error with a status) ends nothing, and moves nothing. + */ + const sweep = (event: Extract): void => { + const target = steerTarget(); + if (init.steers == null || target == null) { + return; + } + if (event.type === 'abort') { + init.steers.convertLocalToQueued(target, { statuses: ABORT_SWEEP_STATUSES }); + return; + } + const generationProtocolVersion = init.protocol?.(); + if (event.status != null) { + return; + } + if (generationProtocolVersion === 1 || supportsGenerationProtocolV2(event.data)) { + init.steers.convertLocalToQueued(target, { claimParked: true, generationProtocolVersion }); + } + }; + /** Applies a frame for the state beside the list, or holds it until its turn is named. */ const beside = (frame: BesideFrame): void => { if (frame.type === 'title') { @@ -706,6 +746,14 @@ export function createEventApplier(init: EventApplierInit = {}): EventApplier { ), ); } + /** + * The reader's steers are settled before the list is: one the run never took becomes a + * queued turn here, ahead of whoever is told the run ended and lets the queue go. + */ + const ending = steerTarget(event.data.conversation?.conversationId); + if (init.steers != null && ending != null) { + settleFinalSteers(init.steers, ending, event.data, init.protocol?.()); + } mergeFinalFrame(settledFinal(event.data, submission, ctx.messages), ctx); if (submission != null) { init.usage?.finalizeUsage(event.data, submission); @@ -718,6 +766,7 @@ export function createEventApplier(init: EventApplierInit = {}): EventApplier { } else if (event.type === 'abort' || event.type === 'error') { /** A turn that stops here keeps every token it streamed. */ land(); + sweep(event); } if (init.schedule == null) { land(); diff --git a/packages/chat/src/core/resumable/frames.ts b/packages/chat/src/core/resumable/frames.ts index b83928a2223..cd0b54f45fa 100644 --- a/packages/chat/src/core/resumable/frames.ts +++ b/packages/chat/src/core/resumable/frames.ts @@ -3,7 +3,6 @@ import type { TMessage, ChatEvent, TAttachment, - TPendingSteer, ChatFinalFrame, EventSubmission, ChatCreatedFrame, @@ -19,6 +18,7 @@ import { GENERATION_PROTOCOL_VERSION, supportsGenerationProtocolV2 } from '../pr import { isInitialNewConversation, buildCreatedInitialResponse } from './messages'; import { reconcileGenerationLifecycle } from './reconcile'; import { ABORT_SWEEP_STATUSES } from '../steer/chips'; +import { settleFinalSteers } from './steers'; import { isOAuthStepEvent } from './events'; import { handleSync } from './sync'; @@ -64,51 +64,7 @@ async function handleFinal(ctx: StreamContext, data: ChatFinalFrame): Promise - !settledSteerIds.has(steer.steerId) && - (steer.clientSteerId == null || !settledSteerIds.has(steer.clientSteerId)), - ) - : [], - { - claimParked: true, - generationProtocolVersion, - }, - ); - // A `failed` chip never reached the server, so it never rides - // `data.pendingSteers` above; without this it survives a NORMAL - // completion and renders (with a live Retry) under the NEXT run's - // reply. Idempotent alongside the call above: both dedupe by id. - host.steers.convertLocalToQueued(finalConvoId); + settleFinalSteers(host.steers, finalConvoId, data, generationProtocolVersion); let finalHandled = false; try { host.events.finalHandler(data, sub.submission as EventSubmission); diff --git a/packages/chat/src/core/resumable/steers.ts b/packages/chat/src/core/resumable/steers.ts new file mode 100644 index 00000000000..c37b00345e9 --- /dev/null +++ b/packages/chat/src/core/resumable/steers.ts @@ -0,0 +1,65 @@ +import type { TPendingSteer, ChatFinalFrame } from 'librechat-data-provider'; +import type { GenerationProtocolVersion } from '../protocol'; +import type { ResumableSteers } from './host'; +import { supportsGenerationProtocolV2 } from '../protocol'; + +/** The steer bookkeeping a run's ordinary final frame reaches. */ +export type FinalSteers = Pick< + ResumableSteers, + 'appliedIds' | 'settleApplied' | 'adoptPromoted' | 'convertToQueued' | 'convertLocalToQueued' +>; + +/** + * Settles the reader's steers against the final frame of the run they were sent to, before the + * run's end is published and lets the next queued turn go: main chat's stream session and a core + * `Chat`'s event applier both end a run through here, so a steer is left the same way by both. + */ +export function settleFinalSteers( + steers: FinalSteers, + conversationId: string, + data: ChatFinalFrame, + generationProtocolVersion?: GenerationProtocolVersion, +): void { + // A steer-applied event may still be waiting for its next-frame + // message target when FINAL arrives. Reconcile directly from the + // authoritative final message before converting leftovers so a + // late 202 ACK cannot resurrect (or queue) an already-applied steer. + const finalAppliedSteerIds = new Set( + steers.appliedIds(data.responseMessage ? [data.responseMessage] : []), + ); + steers.settleApplied(conversationId, data.responseMessage ? [data.responseMessage] : undefined); + // Leftovers the server already made durable queued turns are adopted as + // server-owned rows first, so neither conversion below can re-queue them. + const promotedSteerIds = new Set( + steers.adoptPromoted( + conversationId, + Array.isArray(data.promotedSteers) ? data.promotedSteers : [], + ), + ); + const settledSteerIds = new Set([...finalAppliedSteerIds, ...promotedSteerIds]); + // Steers the run never injected ride the final event; convert them + // to queued follow-ups before the run-end signal fires the drain + // (also resets the applied-id set for the finished run). + // `claimParked` reconciles the replayable parked copy of the same + // steers; explicit dismissal or a persisted recovery removes it. + steers.convertToQueued( + conversationId, + (generationProtocolVersion === 1 || supportsGenerationProtocolV2(data)) && + Array.isArray(data.pendingSteers) + ? (data.pendingSteers as TPendingSteer[]).filter( + (steer) => + !settledSteerIds.has(steer.steerId) && + (steer.clientSteerId == null || !settledSteerIds.has(steer.clientSteerId)), + ) + : [], + { + claimParked: true, + generationProtocolVersion, + }, + ); + // A `failed` chip never reached the server, so it never rides + // `data.pendingSteers` above; without this it survives a NORMAL + // completion and renders (with a live Retry) under the NEXT run's + // reply. Idempotent alongside the call above: both dedupe by id. + steers.convertLocalToQueued(conversationId); +} diff --git a/packages/chat/src/react.ts b/packages/chat/src/react.ts index 5f5047a6c89..57716107201 100644 --- a/packages/chat/src/react.ts +++ b/packages/chat/src/react.ts @@ -127,7 +127,12 @@ export { } from './react/steering/useQueuedTurnReveal'; export { useCoreChat } from './react/core'; export { useFollowChat } from './react/follow'; -export type { FollowChatOptions, FollowedChat } from './react/follow'; +export type { + FollowedChat, + FollowedRunEnd, + FollowChatOptions, + FollowedGeneration, +} from './react/follow'; export { useFollowedContract } from './react/chat/followed'; export type { FollowedContractOptions } from './react/chat/followed'; export { useDrivenContract } from './react/chat/driven'; @@ -142,7 +147,7 @@ export { export type { SideChatBeside } from './react/side/state'; export type { SideChat } from './react/side/state'; export { useSideChatHost, SideChatHostProvider } from './react/side/host'; -export type { SideChatHost, SideChatSurfaceProps } from './react/side/host'; +export type { SideChatHost, SideChatOptions, SideChatSurfaceProps } from './react/side/host'; export { useSnapshot } from './react/snapshot'; export { ReactQueryChatState } from './react/state'; export type { Subscribe, SnapshotOptions } from './react/snapshot'; diff --git a/packages/chat/src/react/chat/__tests__/driven.spec.tsx b/packages/chat/src/react/chat/__tests__/driven.spec.tsx index 6bc773e938a..4d40c2fe3d5 100644 --- a/packages/chat/src/react/chat/__tests__/driven.spec.tsx +++ b/packages/chat/src/react/chat/__tests__/driven.spec.tsx @@ -182,6 +182,7 @@ function setup({ beside, id = conversationId, store = createStore(), + runs, }: { stored?: TMessage[]; services?: TurnServices; @@ -190,6 +191,8 @@ function setup({ /** The conversation the pane holds, and the pane's store when a spec shares one. */ id?: string; store?: ReturnType; + /** What the caller is told of the conversation's generations. */ + runs?: Pick; } = {}) { const queryClient = new QueryClient(); const harness = createTransport(); @@ -226,6 +229,7 @@ function setup({ endpoint: conversation.endpoint, onWithdrawn, beside, + ...runs, }); const contract = useDrivenContract({ id, @@ -382,6 +386,158 @@ describe('useDrivenContract', () => { expect(onSettled).toHaveBeenCalledTimes(2); }); + describe('what it says of the generations it follows', () => { + const watch = () => { + const onGeneration = jest.fn(); + const onRunEnd = jest.fn(); + return { onGeneration, onRunEnd, runs: { onGeneration, onRunEnd } }; + }; + + it('names the generation a turn runs under, and how it ended once another turn can be taken', async () => { + const { onGeneration, onRunEnd, runs } = watch(); + const { result, streams, ready } = setup({ runs }); + await ready(); + /** Whether the chat would take a turn at the moment it says the run ended. */ + const free: boolean[] = []; + onRunEnd.mockImplementation(() => free.push(result.current.followed.canSend())); + expect(onGeneration).not.toHaveBeenCalled(); + + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + expect(onGeneration).toHaveBeenLastCalledWith({ createdAt: 3000, protocolVersion: 1 }); + expect(onRunEnd).not.toHaveBeenCalled(); + + const sent = (result.current.contract.getMessages() ?? [])[2]; + act(() => { + streams[0].push(created(sent, 'response-2')); + streams[0].push(final(sent, reply('response-2', 'Answer', sent.messageId))); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + + expect(onRunEnd).toHaveBeenCalledWith({ + outcome: 'completed', + generationCreatedAt: 3000, + responseMessageId: 'response-2', + }); + expect(free).toEqual([true]); + /** No generation is named once it has ended. */ + expect(onGeneration).toHaveBeenLastCalledWith(null); + }); + + it('says a turn failed, and that one stopped before the server kept it was taken back', async () => { + const { onRunEnd, runs } = watch(); + const { result, streams, ready } = setup({ runs }); + await ready(); + + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + act(() => streams[0].push({ type: 'error', data: { message: 'failed' } })); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(onRunEnd).toHaveBeenLastCalledWith( + expect.objectContaining({ outcome: 'error', generationCreatedAt: 3000 }), + ); + + act(() => { + result.current.contract.ask({ text: 'Never mind' }); + }); + await waitFor(() => expect(streams).toHaveLength(2)); + act(() => + streams[1].push({ + type: 'final', + data: { final: true, earlyAbort: true, conversation: { conversationId } }, + } as ChatEvent), + ); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(2)); + expect(onRunEnd).toHaveBeenLastCalledWith( + expect.objectContaining({ outcome: 'aborted', generationCreatedAt: 3000 }), + ); + }); + + it('says nothing ended while a dropped stream is attached to again, then says it once', async () => { + const { onGeneration, onRunEnd, runs } = watch(); + const { result, streams, setStatus, loadMessages, ready } = setup({ runs }); + await ready(); + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + const sent = (result.current.contract.getMessages() ?? [])[2]; + + setStatus({ active: true, streamId: conversationId, createdAt: 3000 }); + act(() => { + streams[0].push(created(sent, 'response-2')); + streams[0].push({ type: 'error', status: 0 }); + }); + await waitFor(() => expect(streams).toHaveLength(2)); + expect(onRunEnd).not.toHaveBeenCalled(); + /** The same generation, still named: its controls stay addressed to it. */ + expect(onGeneration).toHaveBeenLastCalledWith({ createdAt: 3000, protocolVersion: 1 }); + + loadMessages.mockResolvedValue([ + user, + reply('response-1', 'Hi'), + sent, + reply('response-2', 'Whole', sent.messageId), + ]); + setStatus({ active: false }); + act(() => streams[1].push(final(sent, reply('response-2', 'Whole', sent.messageId)))); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(onRunEnd).toHaveBeenCalledWith( + expect.objectContaining({ outcome: 'completed', responseMessageId: 'response-2' }), + ); + await waitFor(() => expect(result.current.contract.isSubmitting).toBe(false)); + expect(onGeneration).toHaveBeenLastCalledWith(null); + }); + + it('leaves a generation named when the chat is let go of while it runs', async () => { + const { onGeneration, onRunEnd, runs } = watch(); + const { streams, setStatus, rerender, unmount, ready } = setup({ runs }); + await ready(); + setStatus({ active: true, streamId: conversationId, createdAt: 2000 }); + rerender({ live: true }); + await waitFor(() => expect(streams).toHaveLength(1)); + await waitFor(() => expect(onGeneration).toHaveBeenCalledTimes(1)); + + /** + * Its stream drops, and the panel closes (or the conversation moves to the main chat) + * while this chat waits to attach again. The run goes on, and whoever shows the + * conversation next addresses it by the same name. + */ + act(() => streams[0].push({ type: 'error', status: 0 })); + await settle(); + unmount(); + await settle(); + + expect(onGeneration).toHaveBeenLastCalledWith({ createdAt: 3000, protocolVersion: 1 }); + expect(onGeneration).not.toHaveBeenCalledWith(null); + expect(onRunEnd).not.toHaveBeenCalled(); + }); + + it('says a generation it did not start ended, once its stored rows are read', async () => { + const { onGeneration, onRunEnd, runs } = watch(); + const { streams, setStatus, loadMessages, rerender, ready } = setup({ runs }); + await ready(); + + setStatus({ active: true, streamId: conversationId, createdAt: 2000 }); + rerender({ live: true }); + await waitFor(() => expect(streams).toHaveLength(1)); + await waitFor(() => + expect(onGeneration).toHaveBeenLastCalledWith({ createdAt: 3000, protocolVersion: 1 }), + ); + + const reads = loadMessages.mock.calls.length; + setStatus({ active: false }); + act(() => streams[0].push(final(user, reply('response-1', 'Hi')))); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(loadMessages.mock.calls.length).toBeGreaterThan(reads); + expect(onRunEnd).toHaveBeenCalledWith(expect.objectContaining({ outcome: 'completed' })); + }); + }); + it("drops the files another conversation left staged in the pane, and keeps this one's", async () => { const staged = new Map([['file-1', { file_id: 'file-1', progress: 1 } as ExtendedFile]]); const first = setup(); diff --git a/packages/chat/src/react/chat/contract.ts b/packages/chat/src/react/chat/contract.ts index a4933c58b71..7a7791bd5d3 100644 --- a/packages/chat/src/react/chat/contract.ts +++ b/packages/chat/src/react/chat/contract.ts @@ -131,6 +131,12 @@ export type ChatAbortContract = { * the former. */ stopsUnnamed?: boolean; + /** + * Whether the chat runs what the composer does to a run in flight: it publishes the generation + * a steer addresses and each run's end, and sends what was queued behind it. Main chat's pane + * does by being the pane with the stream session; another chat says so here. + */ + steers?: boolean; /** Button handler around `stopGenerating`. AI SDK: `stop`. */ handleStopGenerating: (e: MouseEvent) => void; /** Whether a stop just happened and the view should hold its scroll position. */ diff --git a/packages/chat/src/react/chat/driven.ts b/packages/chat/src/react/chat/driven.ts index 515c5f9858b..e94def4fd12 100644 --- a/packages/chat/src/react/chat/driven.ts +++ b/packages/chat/src/react/chat/driven.ts @@ -197,6 +197,7 @@ export function useDrivenContract({ id, followed, index }: DrivenContractOptions handleContinue, stopGenerating, stopsUnnamed: true, + steers: true, handleStopGenerating, abortScroll, setAbortScroll, diff --git a/packages/chat/src/react/follow.ts b/packages/chat/src/react/follow.ts index 90612c832b5..34853e8b551 100644 --- a/packages/chat/src/react/follow.ts +++ b/packages/chat/src/react/follow.ts @@ -3,6 +3,7 @@ import { useQueryClient } from '@tanstack/react-query'; import type { TMessage, ChatEvent, ChatFinalFrame } from 'librechat-data-provider'; import type { ChatStatus, + ChatStream, ChatTransport, SubmittedTurn, ChatConnection, @@ -10,6 +11,7 @@ import type { ChatFinishResult, EventApplierInit, EventApplierEffect, + GenerationProtocolVersion, } from '../core'; import { Chat, @@ -24,6 +26,7 @@ import { hasPendingAssistantParent, prepareSubmittedTurn, describeSubmittedTurn, + GENERATION_PROTOCOL_VERSION, } from '../core'; import { ReactQueryChatState } from './state'; import { useSnapshot } from './snapshot'; @@ -70,6 +73,30 @@ export type FollowChatOptions = { * from the list; its words were the reader's and can be offered back to them. */ onWithdrawn?: (turn: SubmittedTurn) => void; + /** + * The generation under the conversation as its stream names it, and `null` once it is over + * or lost. What addresses it for everything done to a run in flight: a stop, a steer. + */ + onGeneration?: (generation: FollowedGeneration | null) => void; + /** + * A generation ended, and the list is what it left: after the stored rows were read back, or + * with a sent turn's own final frame in. Not for a stream that only dropped. + */ + onRunEnd?: (end: FollowedRunEnd) => void; +}; + +/** A generation as a stream names it. */ +export type FollowedGeneration = { + createdAt: number; + protocolVersion: GenerationProtocolVersion; +}; + +/** How a generation ended. */ +export type FollowedRunEnd = { + outcome: 'completed' | 'aborted' | 'error'; + generationCreatedAt?: number; + /** The reply it left, when it left one. */ + responseMessageId?: string; }; /** One page of stored messages, oldest first. */ @@ -119,6 +146,10 @@ const forwardBeside = (read: () => FollowBeside | undefined): Required read()?.steers?.update(event), seed: (...args) => read()?.steers?.seed(...args), settleApplied: (...args) => read()?.steers?.settleApplied(...args), + appliedIds: (values) => read()?.steers?.appliedIds(values) ?? [], + adoptPromoted: (...args) => read()?.steers?.adoptPromoted(...args) ?? [], + convertToQueued: (...args) => read()?.steers?.convertToQueued(...args), + convertLocalToQueued: (...args) => read()?.steers?.convertLocalToQueued(...args), }, }); @@ -174,6 +205,13 @@ export type FollowedChat = { * conversation, and is not attached to again. */ stop: () => Promise; + /** + * Looks for a generation running under the conversation and follows it to its end, for a + * caller that learned of one this chat did not start: a turn the server took from the + * reader's queue, a run begun elsewhere. Nothing happens while one is already followed; asked + * during a turn sent from here, it looks once that turn is over. + */ + attach: () => void; }; type Entry = { @@ -252,6 +290,8 @@ export function useFollowChat({ onEvent, onFinish, onWithdrawn, + onGeneration, + onRunEnd, }: FollowChatOptions): FollowedChat { const queryClient = useQueryClient(); const host = useRef({ @@ -264,6 +304,8 @@ export function useFollowChat({ onEvent, onFinish, onWithdrawn, + onGeneration, + onRunEnd, }); host.current = { transport, @@ -275,6 +317,8 @@ export function useFollowChat({ onEvent, onFinish, onWithdrawn, + onGeneration, + onRunEnd, }; const [attempt, setAttempt] = useState(0); const [entry, setEntry] = useState(); @@ -313,6 +357,51 @@ export function useFollowChat({ let reads = 0; /** The reader's stop in flight, which the turn it ends waits for instead of reattaching. */ let stopping: Promise | undefined; + /** The generation the stream in hand names, until it ends or is lost. */ + let generation: FollowedGeneration | undefined; + const note = (stream: ChatStream | null | undefined): void => { + if (stream?.generationCreatedAt == null) { + return; + } + generation = { + createdAt: stream.generationCreatedAt, + protocolVersion: + stream.generationProtocolVersion === GENERATION_PROTOCOL_VERSION + ? GENERATION_PROTOCOL_VERSION + : 1, + }; + host.current.onGeneration?.(generation); + }; + /** + * Not said once this chat is let go of: the generation may be running on, and whoever shows + * the conversation next addresses it by the same name. + */ + const forget = (): FollowedGeneration | undefined => { + const known = generation; + generation = undefined; + if (known != null && !stale) { + host.current.onGeneration?.(null); + } + return known; + }; + /** Tells the caller a generation ended, once the list holds what it left. */ + const runEnded = (finished: ChatFinishResult | undefined, withdrawn = false): void => { + const known = forget(); + if (finished == null || finished.isDisconnect === true) { + return; + } + let outcome: FollowedRunEnd['outcome'] = 'completed'; + if (finished.isError === true) { + outcome = 'error'; + } else if (finished.isAbort === true || withdrawn) { + outcome = 'aborted'; + } + host.current.onRunEnd?.({ + outcome, + generationCreatedAt: known?.createdAt, + responseMessageId: finished.message?.messageId, + }); + }; /** The final frame the last generation ended on, until the caller is told the list settled. */ let ended: ChatFinalFrame | undefined; const settled = (): void => { @@ -332,6 +421,7 @@ export function useFollowChat({ host.current.onEffect?.(effect); }, ...forwardBeside(() => host.current.beside), + protocol: () => generation?.protocolVersion, /** Not when the server answered the start with a generation that is not this turn. */ turn: () => (attachment?.foreign === true ? undefined : sent?.submission), }); @@ -348,9 +438,16 @@ export function useFollowChat({ sent.status === 'replaced' || (sent.status === 'stream' && sent.stream.resumed === true); } + if (sent.status === 'stream') { + note(sent.stream); + } return sent; }, - reconnectToStream: (request) => host.current.transport.reconnectToStream(request), + reconnectToStream: async (request) => { + const stream = await host.current.transport.reconnectToStream(request); + note(stream); + return stream; + }, abort: (request) => host.current.transport.abort(request), getStatus: (conversationId) => host.current.transport.getStatus?.(conversationId) ?? Promise.resolve({ active: false }), @@ -506,9 +603,12 @@ export function useFollowChat({ setUnattached(false); /** Whether a generation was reached and not lost for good. */ let reached = false; + /** How the attachment last ended, which is how the generation ended unless it dropped. */ + let last: ChatFinishResult | undefined; try { for (let failures = 0, absences = 0; !stale; ) { const { finished, received } = await follow(); + last = finished; reached ||= received || finished != null; /** * The caller says a run is going and none was found. Its stream may not be open yet: @@ -535,11 +635,14 @@ export function useFollowChat({ } reading = true; await read(); + runEnded(last); } catch { /** The chat reports a stream failure itself; a failed re-read leaves what it streamed. */ } finally { attaching = false; reading = false; + /** Lost, or never read back: nothing is addressed as running any more. */ + forget(); if (!stale) { setFollowing(false); setUnattached(!reached); @@ -661,17 +764,23 @@ export function useFollowChat({ } if (dropped || owed) { owed = false; + /** A turn that ended is over even when another generation is waiting to be followed. */ + if (!dropped) { + runEnded(finished, current.withdrawn); + } await attach(); return; } if (!own) { await settle(); + runEnded(finished, current.withdrawn); return; } /** The turn's own final frame is its result, and the list as it stands is what it left. */ if (ended != null) { settled(); } + runEnded(finished, current.withdrawn); }; /** @@ -783,6 +892,8 @@ export function useFollowChat({ const canSend = current?.canSend ?? refuse; const send = current?.send ?? refuse; const stop = current?.stop ?? idle; + const look = current?.attach; + const attach = useCallback(() => void look?.(), [look]); const tracked = load.id === id && load.attempt === attempt ? load.state : 'loading'; const state = enabled ? tracked : 'ready'; @@ -804,5 +915,6 @@ export function useFollowChat({ canSend, send, stop, + attach, }; } diff --git a/packages/chat/src/react/side/host.tsx b/packages/chat/src/react/side/host.tsx index 8840e66ac91..f8d6f623b18 100644 --- a/packages/chat/src/react/side/host.tsx +++ b/packages/chat/src/react/side/host.tsx @@ -4,6 +4,9 @@ import type { TConversation } from 'librechat-data-provider'; import type { FollowedChat, FollowChatOptions } from '../follow'; import type { ChatContract } from '../chat/contract'; +/** What the panel asks to be told about the conversation's generations. */ +export type SideChatOptions = Pick; + /** What a host's composer for a side chat is given. */ export type SideChatSurfaceProps = { /** The conversation's chat contract: what main chat's composer reads from its own pane. */ @@ -44,7 +47,7 @@ export interface SideChatHost { */ useChat: ( conversation: Pick, - options?: Pick, + options?: SideChatOptions, ) => FollowedChat; /** Opens the conversation as the page's main one. */ useOpenConversation: () => (conversation: TConversation) => void; diff --git a/packages/chat/src/react/steering/useSteering.ts b/packages/chat/src/react/steering/useSteering.ts index 4d9792d0c13..85ac8603e2a 100644 --- a/packages/chat/src/react/steering/useSteering.ts +++ b/packages/chat/src/react/steering/useSteering.ts @@ -50,6 +50,12 @@ export interface UseSteeringParams { /** Consume the actual storage key selected by the composer’s autosave owner. */ consumeDraft: () => void; index: number; + /** + * Whether this composer's chat takes what is done to a run in flight: a steer, a queued + * follow-up, an interrupt. Main chat's does. Any other pane's does only when its chat + * publishes its runs the way main chat's stream session does, and says so here. + */ + duringRun?: boolean; conversationId: string; conversation: TConversation | null; addedConversation?: TConversation | null; @@ -148,6 +154,7 @@ const pickLiveTail = (tail: TMessage | null): { parentMessageId?: string; paused export default function useSteering({ consumeDraft: takeComposerDraft, index, + duringRun = index === 0, conversationId, conversation, addedConversation, @@ -181,8 +188,8 @@ export default function useSteering({ const hasRealConvoId = conversationId != null && conversationId !== '' && conversationId !== Constants.NEW_CONVO; const serverQueueEnabled = isAgentsEndpoint(endpoint) && hasRealConvoId; - /** v1 gates the during-run UI to the primary composer, like the HITL popover. */ - const enabled = steerable && index === 0; + /** The primary composer, and any other whose chat runs the during-run machinery. */ + const enabled = steerable && duringRun; const queueKey = hasRealConvoId ? conversationId : Constants.NEW_CONVO; const reasoningStateKey = getReasoningStateKey(conversationId, index); const sendLockTimeoutMs = queuedSendLockTimeoutMs ?? DEFAULT_QUEUED_SEND_LOCK_TIMEOUT_MS; diff --git a/packages/chat/src/react/subagents/__tests__/follows.spec.tsx b/packages/chat/src/react/subagents/__tests__/follows.spec.tsx index 7ba9e26e255..4d71211bdfd 100644 --- a/packages/chat/src/react/subagents/__tests__/follows.spec.tsx +++ b/packages/chat/src/react/subagents/__tests__/follows.spec.tsx @@ -33,6 +33,7 @@ const followed = (overrides: Partial = {}): FollowedChat => ({ canSend: () => false, send: () => false, stop: () => Promise.resolve(), + attach: () => undefined, ...overrides, }); diff --git a/packages/chat/src/react/subagents/follows.tsx b/packages/chat/src/react/subagents/follows.tsx index b8edaae791c..9e9ac4e5ad6 100644 --- a/packages/chat/src/react/subagents/follows.tsx +++ b/packages/chat/src/react/subagents/follows.tsx @@ -130,6 +130,7 @@ const opening: FollowedChat = { canSend: () => false, send: () => false, stop: () => Promise.resolve(), + attach: () => undefined, }; const ThreadFollowsContext: Context = createContext< From f22862ed10593fe20e16387c1228041624fba0e1 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Wed, 18 Nov 2026 23:58:22 -0500 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=9B=91=20fix:=20Keep=20a=20Side=20Cha?= =?UTF-8?q?t's=20Queue=20When=20a=20Stop=20Ends=20on=20an=20Unfinished=20R?= =?UTF-8?q?eply?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../components/side/__tests__/panel.spec.tsx | 20 +++++++++++++++ .../src/react/chat/__tests__/driven.spec.tsx | 25 +++++++++++++++++++ packages/chat/src/react/follow.ts | 7 +++++- 3 files changed, 51 insertions(+), 1 deletion(-) diff --git a/packages/chat/src/components/side/__tests__/panel.spec.tsx b/packages/chat/src/components/side/__tests__/panel.spec.tsx index e276bd4828c..fe647560d44 100644 --- a/packages/chat/src/components/side/__tests__/panel.spec.tsx +++ b/packages/chat/src/components/side/__tests__/panel.spec.tsx @@ -429,6 +429,26 @@ describe('SideChatPanel', () => { expect(store.get(queuedMessagesByConvoId(conversationId))).toEqual([queued]); }); + it('keeps the queue when the run ends on a reply marked unfinished, with no word of an abort', async () => { + const view = setup({ steers: true }); + const { store, streams, sendMessages } = view; + const asked = await start(view); + act(() => store.set(queuedMessagesByConvoId(conversationId), [queued])); + + act(() => + streams[0].push( + final(asked, { ...reply('response-2', 'Two', asked.messageId), unfinished: true }), + ), + ); + await waitFor(() => + expect(screen.queryByRole('button', { name: 'Stop generating' })).not.toBeInTheDocument(), + ); + await settle(); + + expect(sendMessages).toHaveBeenCalledTimes(1); + expect(store.get(queuedMessagesByConvoId(conversationId))).toEqual([queued]); + }); + it('sends nothing of a queue where the app hosts no steer hooks', async () => { const view = setup(); const { store, streams, sendMessages } = view; diff --git a/packages/chat/src/react/chat/__tests__/driven.spec.tsx b/packages/chat/src/react/chat/__tests__/driven.spec.tsx index 4d40c2fe3d5..39d7f2df984 100644 --- a/packages/chat/src/react/chat/__tests__/driven.spec.tsx +++ b/packages/chat/src/react/chat/__tests__/driven.spec.tsx @@ -457,6 +457,31 @@ describe('useDrivenContract', () => { ); }); + it('says a turn was stopped when its final frame only marks the reply unfinished', async () => { + const { onRunEnd, runs } = watch(); + const { result, streams, ready } = setup({ runs }); + await ready(); + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + const sent = (result.current.contract.getMessages() ?? [])[2]; + + /** What the server sends for a stop that lands just before completion: no `aborted`. */ + act(() => { + streams[0].push(created(sent, 'response-2')); + streams[0].push( + final(sent, { ...reply('response-2', 'Part of an', sent.messageId), unfinished: true }), + ); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(onRunEnd).toHaveBeenCalledWith({ + outcome: 'aborted', + generationCreatedAt: 3000, + responseMessageId: 'response-2', + }); + }); + it('says nothing ended while a dropped stream is attached to again, then says it once', async () => { const { onGeneration, onRunEnd, runs } = watch(); const { result, streams, setStatus, loadMessages, ready } = setup({ runs }); diff --git a/packages/chat/src/react/follow.ts b/packages/chat/src/react/follow.ts index 34853e8b551..2e9166e3f64 100644 --- a/packages/chat/src/react/follow.ts +++ b/packages/chat/src/react/follow.ts @@ -390,10 +390,15 @@ export function useFollowChat({ if (finished == null || finished.isDisconnect === true) { return; } + /** + * A stop that lands just before the run completes can end it on a final frame that marks + * the reply unfinished and says nothing of an abort. It was stopped all the same, and is + * said to be, as main chat's session says it: what is queued behind it is not sent. + */ let outcome: FollowedRunEnd['outcome'] = 'completed'; if (finished.isError === true) { outcome = 'error'; - } else if (finished.isAbort === true || withdrawn) { + } else if (finished.isAbort === true || withdrawn || finished.message?.unfinished === true) { outcome = 'aborted'; } host.current.onRunEnd?.({ From 9fa61aca362111c18f5110602b93f31cbd9ab97b Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Thu, 19 Nov 2026 00:26:55 -0500 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=A7=A9=20fix:=20Settle=20a=20Side=20C?= =?UTF-8?q?hat's=20Steers=20and=20Queue=20When=20a=20Run=20Ends=20Without?= =?UTF-8?q?=20Its=20Reply?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- client/src/hooks/SSE/pane.ts | 33 +- .../components/side/__tests__/panel.spec.tsx | 43 +- packages/chat/src/components/side/panel.tsx | 19 +- .../chat/src/core/__tests__/apply.spec.ts | 26 ++ .../chat/src/core/__tests__/steers.spec.ts | 145 +++++++ packages/chat/src/core/apply.ts | 7 +- packages/chat/src/core/resumable/failure.ts | 19 +- packages/chat/src/core/resumable/index.ts | 1 + packages/chat/src/core/resumable/launch.ts | 47 +-- packages/chat/src/core/resumable/reconcile.ts | 41 +- packages/chat/src/core/resumable/steers.ts | 130 +++++- packages/chat/src/core/steer/drain.ts | 13 + .../src/react/chat/__tests__/driven.spec.tsx | 389 +++++++++++++++++- packages/chat/src/react/follow.ts | 300 ++++++++++++-- 14 files changed, 1061 insertions(+), 152 deletions(-) create mode 100644 packages/chat/src/core/__tests__/steers.spec.ts diff --git a/client/src/hooks/SSE/pane.ts b/client/src/hooks/SSE/pane.ts index 255d951dd38..2768118c748 100644 --- a/client/src/hooks/SSE/pane.ts +++ b/client/src/hooks/SSE/pane.ts @@ -2,7 +2,7 @@ import { useMemo, useCallback } from 'react'; import { v4 } from 'uuid'; import { useStore, useSetAtom } from 'jotai'; import { Constants } from 'librechat-data-provider'; -import { isStoppedRun, resolveDetachedRunEnd } from '@librechat/chat'; +import { isStoppedRun, resolveDetachedRunEnd, clearMatchingDrainAfterAbort } from '@librechat/chat'; import { abortScrollFamily, showStopButtonByIndex, @@ -14,34 +14,11 @@ import { stopRequestedByConvoId, pendingApprovalActionFamily, } from '@librechat/chat/react'; -import type { - ResumableRun, - ResumablePane, - ResumableQueue, - DrainAfterAbort, - RunEnd, -} from '@librechat/chat'; +import type { ResumableRun, ResumablePane, ResumableQueue, RunEnd } from '@librechat/chat'; import type { EventHandlerParams } from '@librechat/chat/react'; import { clearComposerDrafts, resolveRunEndTarget } from '~/utils'; import { activeRunFamily } from './atoms'; -/** - * Reconciliation often crosses async query boundaries. By the time an old - * generation settles, this pane may have armed "interrupt & send" for a new - * conversation/generation. Recoil applies functional setters against the - * latest value, so only consume the exact intent owned by this terminal path. - */ -const clearMatchingDrainAfterAbort = ( - armed: DrainAfterAbort | false, - conversationId: string, - generationCreatedAt: number, -): DrainAfterAbort | false => - armed !== false && - armed.conversationId === conversationId && - armed.generationCreatedAt === generationCreatedAt - ? false - : armed; - const replaceNewConversationUrl = (conversationId: string) => { if (window.location.pathname !== `/c/${Constants.NEW_CONVO}`) { return; @@ -110,6 +87,12 @@ export default function useResumablePane({ if (generationCreatedAt == null) { return; } + /** + * Reconciliation often crosses async query boundaries. By the time an old generation + * settles, this pane may have armed "interrupt & send" for a new conversation or + * generation. A functional setter applies against the latest value, so only the exact + * intent owned by this terminal path is consumed. + */ setDrainAfterAbort((armed) => clearMatchingDrainAfterAbort(armed, conversationId, generationCreatedAt), ); diff --git a/packages/chat/src/components/side/__tests__/panel.spec.tsx b/packages/chat/src/components/side/__tests__/panel.spec.tsx index fe647560d44..1a8e12809b9 100644 --- a/packages/chat/src/components/side/__tests__/panel.spec.tsx +++ b/packages/chat/src/components/side/__tests__/panel.spec.tsx @@ -15,17 +15,18 @@ import { inertSeenSource, MessagesHostProvider, } from '../../../react/messages/host'; +import { drainAfterAbortByIndex, queuedMessagesByConvoId } from '../../../react/steer/queue'; import { activeGenerationCreatedAtByConvoId } from '../../../react/steer/atoms'; import { createTurnServices } from '../../../react/chat/__fixtures__/services'; import { createMessagePartsHost } from '../../../__fixtures__/partsHost'; import { ChatSurfaceProvider } from '../../../react/subagents/provider'; import { createMessagesHost } from '../../../__fixtures__/messagesHost'; -import { queuedMessagesByConvoId } from '../../../react/steer/queue'; import { createSteerHost } from '../../../__fixtures__/steerHost'; import { SideChatHostProvider } from '../../../react/side/host'; import { MessagePartsHostProvider } from '../../../react/host'; import { SteerHostProvider } from '../../../react/steer/host'; import { ChatHostProvider } from '../../../react/chat/host'; +import { SIDE_CHAT_PANE } from '../../../react/side/state'; import { initEnglish } from '../../../__fixtures__/i18n'; import { useFollowChat } from '../../../react/follow'; import SideChatPanel from '../panel'; @@ -449,6 +450,46 @@ describe('SideChatPanel', () => { expect(store.get(queuedMessagesByConvoId(conversationId))).toEqual([queued]); }); + it('takes back the leave to send on a stopped run when the stop could not be saved', async () => { + const view = setup({ steers: true }); + const { store, streams, sendMessages } = view; + const asked = await start(view); + act(() => store.set(queuedMessagesByConvoId(conversationId), [queued])); + /** Interrupt and send: the queue may go even though the run is stopped. */ + act(() => + store.set(drainAfterAbortByIndex(SIDE_CHAT_PANE), { + conversationId, + generationCreatedAt: 3000, + }), + ); + + act(() => { + streams[0].push({ + type: 'created', + data: { created: true, message: asked, turn: { responseMessageId: 'response-2' } }, + } as ChatEvent); + streams[0].push({ + type: 'final', + data: { + final: true, + reconcile: true, + reconcileReason: 'abort_persistence_failed', + terminalStatus: 'aborted', + generationProtocolVersion: 2, + conversation: { conversationId }, + }, + } as ChatEvent); + }); + await waitFor(() => + expect(screen.queryByRole('button', { name: 'Stop generating' })).not.toBeInTheDocument(), + ); + await settle(); + + expect(store.get(drainAfterAbortByIndex(SIDE_CHAT_PANE))).toBe(false); + expect(sendMessages).toHaveBeenCalledTimes(1); + expect(store.get(queuedMessagesByConvoId(conversationId))).toEqual([queued]); + }); + it('sends nothing of a queue where the app hosts no steer hooks', async () => { const view = setup(); const { store, streams, sendMessages } = view; diff --git a/packages/chat/src/components/side/panel.tsx b/packages/chat/src/components/side/panel.tsx index 3a228cde1ea..c5b7206eca3 100644 --- a/packages/chat/src/components/side/panel.tsx +++ b/packages/chat/src/components/side/panel.tsx @@ -12,10 +12,11 @@ import { activeGenerationCreatedAtByConvoId, activeGenerationProtocolVersionByConvoId, } from '../../react/steer/atoms'; +import { runEndByIndex, drainAfterAbortByIndex } from '../../react/steer/queue'; import { SIDE_CHAT_PANE, sideChatDraftFamily } from '../../react/side/state'; +import { clearMatchingDrainAfterAbort } from '../../core/steer/drain'; import { useChatSurface } from '../../react/subagents/surface'; import { resolveComposerKeyDown } from '../../core/shortcuts'; -import { runEndByIndex } from '../../react/steer/queue'; import { useSideChatHost } from '../../react/side/host'; import { useChatHost } from '../../react/chat/host'; import DrivenThread from '../pane/Driven'; @@ -196,8 +197,20 @@ export default function SideChatPanel({ [conversationId, store], ); const noteRunEnd = useCallback( - (end: FollowedRunEnd) => - store.set(runEndByIndex(SIDE_CHAT_PANE), { ...end, conversationId, endedAt: Date.now() }), + ({ reconcileReason, ...end }: FollowedRunEnd) => { + /** + * Interrupt and send lets the queue go even on a stopped run. A run whose stop could not + * be saved has not been proven stopped, so that leave is taken back before the end is + * published; the queued words stay for the reader to send. + */ + if (reconcileReason === 'abort_persistence_failed' && end.generationCreatedAt != null) { + const { generationCreatedAt } = end; + store.set(drainAfterAbortByIndex(SIDE_CHAT_PANE), (armed) => + clearMatchingDrainAfterAbort(armed, conversationId, generationCreatedAt), + ); + } + store.set(runEndByIndex(SIDE_CHAT_PANE), { ...end, conversationId, endedAt: Date.now() }); + }, [conversationId, store], ); const followed = host.useChat(chat.conversation, { diff --git a/packages/chat/src/core/__tests__/apply.spec.ts b/packages/chat/src/core/__tests__/apply.spec.ts index fd166301239..5f9555a1b39 100644 --- a/packages/chat/src/core/__tests__/apply.spec.ts +++ b/packages/chat/src/core/__tests__/apply.spec.ts @@ -1272,6 +1272,32 @@ describe('state beside the message list', () => { expect(named[4]).toEqual(['sweep', 'thread-1']); }); + it('settles no steers on a frame that only says the run is over, which whoever reads the stored rows does', () => { + const { calls, init } = record(); + const { applyEvent } = createEventApplier(init); + const { context: ctx } = createList(); + + applyEvent(created, ctx); + applyEvent( + { + type: 'final', + data: { + final: true, + reconcile: true, + reconcileReason: 'terminal_payload_missing', + terminalStatus: 'complete', + generationProtocolVersion: 2, + conversation: { conversationId: 'thread-1' }, + pendingSteers: [{ steerId: 'steer-left', text: 'Waiting' }], + }, + } as ChatEvent, + ctx, + ); + + const settling = ['appliedIds', 'settle', 'adopt', 'toQueued', 'sweep']; + expect(calls.filter(([name]) => settling.includes(name))).toEqual([]); + }); + it('queues none of a final frame’s steers when neither it nor the generation speaks their protocol', () => { const { calls, init } = record(); const { applyEvent } = createEventApplier(init); diff --git a/packages/chat/src/core/__tests__/steers.spec.ts b/packages/chat/src/core/__tests__/steers.spec.ts new file mode 100644 index 00000000000..1e20d5ca7c9 --- /dev/null +++ b/packages/chat/src/core/__tests__/steers.spec.ts @@ -0,0 +1,145 @@ +import type { TMessage, TSubmission, TPendingSteer } from 'librechat-data-provider'; +import type { FinalSteers } from '../resumable/steers'; +import { + settleStoredSteers, + restoreRefusedStart, + restoreReleasedSource, +} from '../resumable/steers'; + +/** The steer bookkeeping, recording what it is called with and in what order. */ +const record = () => { + const calls: Array<[string, ...unknown[]]> = []; + const log = + (name: string, result?: unknown) => + (...args: unknown[]): unknown => { + calls.push([name, ...args]); + return result; + }; + const steers = { + appliedIds: log('appliedIds', ['steer-taken']), + settleApplied: log('settle'), + adoptPromoted: log('adopt', ['steer-promoted']), + convertToQueued: log('toQueued'), + convertLocalToQueued: log('sweep'), + blockRecovery: log('block'), + restoreQueued: log('restore'), + }; + return { + calls, + steers: steers as unknown as FinalSteers & Parameters[0], + }; +}; + +const stored = [{ messageId: 'reply-1', conversationId: 'thread-1' }] as TMessage[]; +const parked: TPendingSteer[] = [ + { steerId: 'steer-parked', clientSteerId: 'local-parked', text: 'Parked by the server' }, +] as TPendingSteer[]; + +describe('settleStoredSteers', () => { + it('settles what the rows and the status hold, restores what the server parked, then sweeps the rest', () => { + const { calls, steers } = record(); + const streamed = [{ type: 'text', text: 'So far' }]; + + settleStoredSteers(steers, 'thread-1', { + messages: stored, + status: { aggregatedContent: streamed, unrecoveredSteers: parked }, + promoted: [{ steerId: 'steer-promoted' }] as never, + recoverySteerId: 'steer-recovered', + generationProtocolVersion: 2, + }); + + expect(calls).toEqual([ + ['appliedIds', [...stored, ...streamed]], + ['settle', 'thread-1', [...stored, ...streamed]], + ['adopt', 'thread-1', [{ steerId: 'steer-promoted' }]], + ['toQueued', 'thread-1', parked, { allowPreviouslyConvertedIds: ['steer-recovered'] }], + [ + 'sweep', + 'thread-1', + { + excludeSteerIds: new Set([ + 'steer-taken', + 'steer-promoted', + 'steer-parked', + 'local-parked', + ]), + generationProtocolVersion: 2, + }, + ], + ]); + }); + + it('sweeps nothing when the stored rows could not be read: their absence proves nothing', () => { + const { calls, steers } = record(); + + settleStoredSteers(steers, 'thread-1', { messages: undefined }); + + expect(calls.map(([name]) => name)).toEqual(['appliedIds', 'settle', 'adopt']); + }); +}); + +describe('restoreRefusedStart', () => { + const submission = { + conversation: { conversationId: 'thread-1' }, + recoverySteerId: 'steer-recovered', + } as unknown as TSubmission; + + it('puts the queue row back for a refusal, and nothing for a failure that may have started the turn', () => { + const { calls, steers } = record(); + + expect(restoreRefusedStart(steers, submission, { response: { status: 403, data: {} } })).toBe( + true, + ); + expect(calls).toEqual([['restore', submission]]); + + calls.length = 0; + expect(restoreRefusedStart(steers, submission, { response: { status: 502 } })).toBe(false); + expect(restoreRefusedStart(steers, submission, { code: 'ERR_NETWORK' })).toBe(false); + expect(restoreRefusedStart(steers, submission, undefined)).toBe(false); + expect(calls).toEqual([]); + }); + + it.each(['RECOVERY_PAYLOAD_MISMATCH', 'INVALID_RECOVERY_REQUEST'])( + 'bars a recovery the server rejected as such (%s) before the row goes back', + (code) => { + const { calls, steers } = record(); + + restoreRefusedStart(steers, submission, { response: { status: 409, data: { code } } }); + + expect(calls).toEqual([ + ['block', 'thread-1', 'steer-recovered'], + ['restore', submission], + ]); + }, + ); +}); + +describe('restoreReleasedSource', () => { + const released = { active: false, generationProtocolVersion: 2, unrecoveredSteers: parked }; + + it('puts a parked steer back in the queue when the server has let go of it again', () => { + const { calls, steers } = record(); + + expect(restoreReleasedSource(steers, 'thread-1', 'steer-parked', released, 2)).toBe(true); + + expect(calls).toEqual([ + [ + 'toQueued', + 'thread-1', + parked, + { generationProtocolVersion: 2, allowPreviouslyConvertedIds: ['steer-parked'] }, + ], + ]); + }); + + it.each([ + ['a generation is still running', { ...released, active: true }], + ['the status does not speak the protocol', { ...released, generationProtocolVersion: 1 }], + ['the server parked another steer, not this one', { ...released, unrecoveredSteers: [] }], + ])('puts nothing back when %s', (_case, status) => { + const { calls, steers } = record(); + + expect(restoreReleasedSource(steers, 'thread-1', 'steer-parked', status, 2)).toBe(false); + expect(calls).toEqual([]); + }); +}); diff --git a/packages/chat/src/core/apply.ts b/packages/chat/src/core/apply.ts index 507e5263dac..b222587f8c0 100644 --- a/packages/chat/src/core/apply.ts +++ b/packages/chat/src/core/apply.ts @@ -751,7 +751,12 @@ export function createEventApplier(init: EventApplierInit = {}): EventApplier { * queued turn here, ahead of whoever is told the run ended and lets the queue go. */ const ending = steerTarget(event.data.conversation?.conversationId); - if (init.steers != null && ending != null) { + /** + * Not for a frame that only says the run is over and carries none of it: no reply in it + * says which steers the run took, so one it took would be queued to be sent again. Those + * are settled against the stored rows, by whoever reads them. + */ + if (init.steers != null && ending != null && event.data.reconcile !== true) { settleFinalSteers(init.steers, ending, event.data, init.protocol?.()); } mergeFinalFrame(settledFinal(event.data, submission, ctx.messages), ctx); diff --git a/packages/chat/src/core/resumable/failure.ts b/packages/chat/src/core/resumable/failure.ts index c423df933d2..9ecc442fec7 100644 --- a/packages/chat/src/core/resumable/failure.ts +++ b/packages/chat/src/core/resumable/failure.ts @@ -10,6 +10,7 @@ import { import { GENERATION_PROTOCOL_VERSION, supportsGenerationProtocolV2 } from '../protocol'; import { MAX_RETRIES, getReconnectDelay, getRecoverySteerId } from './start'; import { settleAfterRetryCeiling } from './ceiling'; +import { restoreReleasedSource } from './steers'; import { recoverMissingStream } from './missing'; /** @@ -83,19 +84,13 @@ async function handleServedError( if (!sub.isCurrent()) { return; } - const releasedSource = terminalStatus.unrecoveredSteers?.find( - (steer) => steer.steerId === recoverySteerId, + restoreReleasedSource( + host.steers, + recoveryConvoId, + recoverySteerId, + terminalStatus, + generationProtocolVersion, ); - if ( - terminalStatus.active === false && - supportsGenerationProtocolV2(terminalStatus) && - releasedSource != null - ) { - host.steers.convertToQueued(recoveryConvoId, [releasedSource], { - generationProtocolVersion, - allowPreviouslyConvertedIds: [recoverySteerId], - }); - } } catch (error) { if (!sub.isCurrent()) { return; diff --git a/packages/chat/src/core/resumable/index.ts b/packages/chat/src/core/resumable/index.ts index accfe6816b5..63b522ebc62 100644 --- a/packages/chat/src/core/resumable/index.ts +++ b/packages/chat/src/core/resumable/index.ts @@ -21,3 +21,4 @@ export * from './launch'; export * from './mount'; export * from './outcomes'; export * from './settled'; +export * from './steers'; diff --git a/packages/chat/src/core/resumable/launch.ts b/packages/chat/src/core/resumable/launch.ts index e94b205b688..846c7147120 100644 --- a/packages/chat/src/core/resumable/launch.ts +++ b/packages/chat/src/core/resumable/launch.ts @@ -21,11 +21,8 @@ import { getPredecessorMismatchStartResponse, START_GENERATION_READINESS_TIMEOUT_MS, } from './start'; -import { - GENERATION_PROTOCOL_VERSION, - getGenerationProtocolVersion, - supportsGenerationProtocolV2, -} from '../protocol'; +import { GENERATION_PROTOCOL_VERSION, getGenerationProtocolVersion } from '../protocol'; +import { restoreRefusedStart, restoreReleasedSource } from './steers'; /** * Starts a generation (the POST that returns the stream to attach to) through the host @@ -198,24 +195,10 @@ export async function startGeneration( const startError = toStartGenerationError(lastError); const errorData = startError?.response?.data; - const responseStatus = startError?.response?.status; - if (responseStatus != null && responseStatus >= 400 && responseStatus < 500) { - const recoverySteerId = getRecoverySteerId(currentSubmission); - const conversationId = currentSubmission.conversation?.conversationId; - const recoveryRejected = - errorData != null && - typeof errorData === 'object' && - 'code' in errorData && - (errorData.code === 'RECOVERY_PAYLOAD_MISMATCH' || - errorData.code === 'INVALID_RECOVERY_REQUEST'); - if (recoveryRejected && recoverySteerId != null && conversationId) { - host.steers.blockRecovery(conversationId, recoverySteerId); - } - // The server rejected admission before exposing a generation. Restore - // the exact queue row/position; ambiguous transport/5xx outcomes must - // first reconcile durable state instead of risking a duplicate start. - host.steers.restoreQueued(currentSubmission); - } else { + // The server rejected admission before exposing a generation. Restore + // the exact queue row/position; ambiguous transport/5xx outcomes must + // first reconcile durable state instead of risking a duplicate start. + if (!restoreRefusedStart(host.steers, currentSubmission, startError)) { const recoverySteerId = getRecoverySteerId(currentSubmission); const recoveryConvoId = currentSubmission.conversation?.conversationId; if (recoverySteerId != null && recoveryConvoId) { @@ -224,19 +207,13 @@ export async function startGeneration( if (signal?.aborted) { return null; } - const releasedSource = status.unrecoveredSteers?.find( - (steer) => steer.steerId === recoverySteerId, + restoreReleasedSource( + host.steers, + recoveryConvoId, + recoverySteerId, + status, + GENERATION_PROTOCOL_VERSION, ); - if ( - status.active === false && - supportsGenerationProtocolV2(status) && - releasedSource != null - ) { - host.steers.convertToQueued(recoveryConvoId, [releasedSource], { - generationProtocolVersion: GENERATION_PROTOCOL_VERSION, - allowPreviouslyConvertedIds: [recoverySteerId], - }); - } } catch (error) { if (signal?.aborted) { return null; diff --git a/packages/chat/src/core/resumable/reconcile.ts b/packages/chat/src/core/resumable/reconcile.ts index 2b85bc4f79e..62700968dc2 100644 --- a/packages/chat/src/core/resumable/reconcile.ts +++ b/packages/chat/src/core/resumable/reconcile.ts @@ -9,6 +9,7 @@ import { } from './terminal'; import { completedResponseMessageId, isInitialNewConversation } from './messages'; import { supportsGenerationProtocolV2 } from '../protocol'; +import { settleStoredSteers } from './steers'; import { getRecoverySteerId } from './start'; /** A synthesized lifecycle frame: the run ended without an ordinary final payload. */ @@ -159,39 +160,13 @@ export async function reconcileGenerationLifecycle( return; } - const authoritativeValues = [ - ...(persistedMessages ?? []), - ...(status?.resumeState?.aggregatedContent ?? status?.aggregatedContent ?? []), - ]; - const reconciledIds = new Set(host.steers.appliedIds(authoritativeValues)); - host.steers.settleApplied(reconciliationConvoId, authoritativeValues); - for (const id of host.steers.adoptPromoted( - reconciliationConvoId, - Array.isArray(event.promotedSteers) ? event.promotedSteers : [], - )) { - reconciledIds.add(id); - } - const unrecovered = status?.unrecoveredSteers ?? []; - if (unrecovered.length > 0) { - const recoverySteerId = getRecoverySteerId(sub.submission); - host.steers.convertToQueued(reconciliationConvoId, unrecovered, { - ...(recoverySteerId != null && { - allowPreviouslyConvertedIds: [recoverySteerId], - }), - }); - for (const steer of unrecovered) { - reconciledIds.add(steer.steerId); - if (steer.clientSteerId) { - reconciledIds.add(steer.clientSteerId); - } - } - } - if (persistedMessages) { - host.steers.convertLocalToQueued(reconciliationConvoId, { - excludeSteerIds: reconciledIds, - generationProtocolVersion, - }); - } + settleStoredSteers(host.steers, reconciliationConvoId, { + messages: persistedMessages, + status, + promoted: event.promotedSteers, + recoverySteerId: getRecoverySteerId(sub.submission), + generationProtocolVersion, + }); host.events.resetLive(sub.liveSubmission()); host.cache.removeActiveJob(currentStreamId); diff --git a/packages/chat/src/core/resumable/steers.ts b/packages/chat/src/core/resumable/steers.ts index c37b00345e9..e60c245ea5a 100644 --- a/packages/chat/src/core/resumable/steers.ts +++ b/packages/chat/src/core/resumable/steers.ts @@ -1,7 +1,15 @@ -import type { TPendingSteer, ChatFinalFrame } from 'librechat-data-provider'; +import type { + TMessage, + TSubmission, + TPendingSteer, + TPromotedSteer, + ChatFinalFrame, +} from 'librechat-data-provider'; +import type { ResumableSteers, StreamStatusResponse } from './host'; import type { GenerationProtocolVersion } from '../protocol'; -import type { ResumableSteers } from './host'; +import type { StartGenerationError } from './start'; import { supportsGenerationProtocolV2 } from '../protocol'; +import { getRecoverySteerId } from './start'; /** The steer bookkeeping a run's ordinary final frame reaches. */ export type FinalSteers = Pick< @@ -63,3 +71,121 @@ export function settleFinalSteers( // reply. Idempotent alongside the call above: both dedupe by id. steers.convertLocalToQueued(conversationId); } + +/** + * Settles the reader's steers for a run that ended with no payload to settle them against: a + * control frame that only says the run is over, or a stream that was gone. The stored rows and + * the run's last status are then the authority. A steer they hold as applied is settled, one + * the server made a queued turn is adopted, one it parked is restored as a queued follow-up, + * and only then are the chips still left swept into the queue, so a steer the run took is not + * sent again as a new turn. Without the stored rows nothing is swept: their absence proves + * nothing about what the run took. + */ +export function settleStoredSteers( + steers: FinalSteers, + conversationId: string, + { + messages, + status, + promoted, + recoverySteerId, + generationProtocolVersion, + }: { + /** The conversation's stored rows, when they could be read. */ + messages: TMessage[] | undefined; + status?: Pick; + promoted?: TPromotedSteer[]; + /** The parked steer the ended turn was itself a recovery of. */ + recoverySteerId?: string | null; + generationProtocolVersion?: GenerationProtocolVersion; + }, +): void { + const authoritativeValues = [ + ...(messages ?? []), + ...(status?.resumeState?.aggregatedContent ?? status?.aggregatedContent ?? []), + ]; + const reconciledIds = new Set(steers.appliedIds(authoritativeValues)); + steers.settleApplied(conversationId, authoritativeValues); + for (const id of steers.adoptPromoted(conversationId, Array.isArray(promoted) ? promoted : [])) { + reconciledIds.add(id); + } + const unrecovered = status?.unrecoveredSteers ?? []; + if (unrecovered.length > 0) { + steers.convertToQueued(conversationId, unrecovered, { + ...(recoverySteerId != null && { + allowPreviouslyConvertedIds: [recoverySteerId], + }), + }); + for (const steer of unrecovered) { + reconciledIds.add(steer.steerId); + if (steer.clientSteerId) { + reconciledIds.add(steer.clientSteerId); + } + } + } + if (messages) { + steers.convertLocalToQueued(conversationId, { + excludeSteerIds: reconciledIds, + generationProtocolVersion, + }); + } +} + +/** + * What a start the server refused leaves of the queued turn it was for. The server rejected + * admission before exposing a generation, so the exact queue row goes back in its position; a + * recovery it rejected as such is first barred from being restored again. Only for a response + * that is a refusal (4xx): a transport failure or a 5xx may have started the turn, and putting + * the row back then risks sending it twice. + */ +export function restoreRefusedStart( + steers: Pick, + submission: TSubmission, + error: StartGenerationError | undefined, +): boolean { + const responseStatus = error?.response?.status; + if (responseStatus == null || responseStatus < 400 || responseStatus >= 500) { + return false; + } + const errorData = error?.response?.data; + const recoverySteerId = getRecoverySteerId(submission); + const conversationId = submission.conversation?.conversationId; + const recoveryRejected = + errorData != null && + typeof errorData === 'object' && + 'code' in errorData && + (errorData.code === 'RECOVERY_PAYLOAD_MISMATCH' || + errorData.code === 'INVALID_RECOVERY_REQUEST'); + if (recoveryRejected && recoverySteerId != null && conversationId) { + steers.blockRecovery(conversationId, recoverySteerId); + } + steers.restoreQueued(submission); + return true; +} + +/** + * A turn that replays a parked steer ended without the server keeping it. If the server has + * let go of that steer again (it is back among the ones it parked, and nothing is running), + * the steer returns to the queue as the reader's to send. Read from a status taken after the + * end was observed: one taken earlier could name a parked copy the turn went on to commit, and + * would then authorize sending it twice. + */ +export function restoreReleasedSource( + steers: Pick, + conversationId: string, + recoverySteerId: string, + status: Pick, + generationProtocolVersion: GenerationProtocolVersion, +): boolean { + const releasedSource = status.unrecoveredSteers?.find( + (steer) => steer.steerId === recoverySteerId, + ); + if (status.active !== false || !supportsGenerationProtocolV2(status) || releasedSource == null) { + return false; + } + steers.convertToQueued(conversationId, [releasedSource], { + generationProtocolVersion, + allowPreviouslyConvertedIds: [recoverySteerId], + }); + return true; +} diff --git a/packages/chat/src/core/steer/drain.ts b/packages/chat/src/core/steer/drain.ts index e520751f95c..927f66228db 100644 --- a/packages/chat/src/core/steer/drain.ts +++ b/packages/chat/src/core/steer/drain.ts @@ -53,6 +53,19 @@ export function matchesInterruptArm(armed: DrainAfterAbort | false, end: RunEnd) return sameConversation && armed.generationCreatedAt === end.generationCreatedAt; } +/** The interrupt intent with the one armed for this exact generation taken back, if it is. */ +export function clearMatchingDrainAfterAbort( + armed: DrainAfterAbort | false, + conversationId: string, + generationCreatedAt: number, +): DrainAfterAbort | false { + return armed !== false && + armed.conversationId === conversationId && + armed.generationCreatedAt === generationCreatedAt + ? false + : armed; +} + /** A run end parked under its own conversation, carrying any interrupt intent * armed for it so another run on the same pane can neither consume nor clear it. */ export function parkRunEnd(end: RunEnd, interruptArmed: boolean): RunEnd { diff --git a/packages/chat/src/react/chat/__tests__/driven.spec.tsx b/packages/chat/src/react/chat/__tests__/driven.spec.tsx index 39d7f2df984..b3c6f0b15bd 100644 --- a/packages/chat/src/react/chat/__tests__/driven.spec.tsx +++ b/packages/chat/src/react/chat/__tests__/driven.spec.tsx @@ -59,12 +59,13 @@ const conversation: TConversation = { type TestStream = ChatStream & { push(event: ChatEvent): void; closed: boolean }; -const createStream = (): TestStream => { +const createStream = (generationProtocolVersion?: number): TestStream => { const queued: ChatEvent[] = []; let wake: (() => void) | undefined; const stream: TestStream = { streamId: conversationId, generationCreatedAt: 3000, + generationProtocolVersion, closed: false, push(event) { queued.push(event); @@ -92,11 +93,11 @@ const createStream = (): TestStream => { }; /** A transport that can start a generation: every send and every attachment opens a stream. */ -const createTransport = () => { +const createTransport = (generationProtocolVersion?: number) => { const streams: TestStream[] = []; let status: ChatStreamStatus = { active: false }; const open = (): TestStream => { - const stream = createStream(); + const stream = createStream(generationProtocolVersion); streams.push(stream); return stream; }; @@ -183,6 +184,7 @@ function setup({ id = conversationId, store = createStore(), runs, + harness = createTransport(), }: { stored?: TMessage[]; services?: TurnServices; @@ -193,9 +195,10 @@ function setup({ store?: ReturnType; /** What the caller is told of the conversation's generations. */ runs?: Pick; + /** The transport, when a spec sets the server's state before the conversation opens. */ + harness?: ReturnType; } = {}) { const queryClient = new QueryClient(); - const harness = createTransport(); const loadMessages = jest.fn(async () => stored); const onWithdrawn = jest.fn(); const host: ChatHost = { @@ -563,6 +566,384 @@ describe('useDrivenContract', () => { }); }); + describe('the reader’s steers and queue when a run ends without its reply', () => { + /** Main chat's steer bookkeeping, recording what it is called with and in what order. */ + const record = (held = new Set()) => { + const calls: Array<[string, ...unknown[]]> = []; + const log = + (name: string, result?: unknown) => + (...args: unknown[]): unknown => { + calls.push([name, ...args]); + return result; + }; + const steers = { + resolve: log('resolve', []), + markLiveApplied: log('markLive'), + update: log('update'), + seed: log('seed'), + settleApplied: log('settle'), + appliedIds: log('appliedIds', ['steer-taken']), + adoptPromoted: log('adopt', ['steer-promoted']), + convertToQueued: log('toQueued'), + convertLocalToQueued: log('sweep'), + restoreQueued: log('restore'), + blockRecovery: log('block'), + isRecoveryHeld: (...args: unknown[]) => { + calls.push(['held?', ...args]); + return held.has(args[1] as string); + }, + } as unknown as NonNullable['steers']>; + return { calls, steers, named: (name: string) => calls.filter(([call]) => call === name) }; + }; + const watch = () => { + const onGeneration = jest.fn(); + const onRunEnd = jest.fn(); + return { onGeneration, onRunEnd, runs: { onGeneration, onRunEnd } }; + }; + /** A frame that only says the run is over: none of its messages, and why. */ + const control = (data: Record): ChatEvent => + ({ + type: 'final', + data: { + final: true, + reconcile: true, + generationProtocolVersion: 2, + conversation: { conversationId }, + ...data, + }, + }) as ChatEvent; + const refusal = (status: number, data: Record) => + Object.assign(new Error(`Request failed with status code ${status}`), { + response: { status, data, headers: {} }, + }); + + it('settles steers against the rows it reads, not against a frame that carries none', async () => { + const { calls, steers, named } = record(); + const { onRunEnd, runs } = watch(); + const { result, streams, loadMessages, ready } = setup({ beside: { steers }, runs }); + await ready(); + calls.length = 0; + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + const sent = (result.current.contract.getMessages() ?? [])[2]; + const stored = [ + user, + reply('response-1', 'Hi'), + sent, + reply('response-2', 'Whole', sent.messageId), + ]; + loadMessages.mockResolvedValue(stored); + + act(() => { + streams[0].push(created(sent, 'response-2')); + streams[0].push( + control({ + reconcileReason: 'terminal_payload_missing', + terminalStatus: 'complete', + promotedSteers: [{ steerId: 'steer-promoted' }], + }), + ); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + + /** Nothing was swept on the frame's word; the stored rows decided, once read. */ + expect(loadMessages).toHaveBeenCalledTimes(2); + expect(named('toQueued')).toEqual([]); + expect(calls.map(([name]) => name)).toEqual(['appliedIds', 'settle', 'adopt', 'sweep']); + expect(calls[0][1]).toEqual(stored); + expect(calls[1]).toEqual(['settle', conversationId, stored]); + expect(calls[2]).toEqual(['adopt', conversationId, [{ steerId: 'steer-promoted' }]]); + expect(calls[3]).toEqual([ + 'sweep', + conversationId, + { + excludeSteerIds: new Set(['steer-taken', 'steer-promoted']), + generationProtocolVersion: 1, + }, + ]); + /** The server says it completed, and the reply the rows hold is the one it left. */ + expect(onRunEnd).toHaveBeenCalledWith({ + outcome: 'completed', + generationCreatedAt: 3000, + responseMessageId: 'response-2', + reconcileReason: 'terminal_payload_missing', + }); + }); + + it('sweeps nothing after such a frame while another generation is already running', async () => { + const { calls, steers } = record(); + const { onRunEnd, runs } = watch(); + const { result, streams, setStatus, ready } = setup({ beside: { steers }, runs }); + await ready(); + calls.length = 0; + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + const sent = (result.current.contract.getMessages() ?? [])[2]; + + /** The server has started the next turn itself: its frames settle the steers. */ + setStatus({ active: true, streamId: conversationId, createdAt: 6000 }); + act(() => { + streams[0].push(created(sent, 'response-2')); + streams[0].push( + control({ reconcileReason: 'terminal_payload_missing', terminalStatus: 'complete' }), + ); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + + expect(calls).toEqual([]); + }); + + it('says a run whose stop could not be saved was stopped, and why', async () => { + const { steers } = record(); + const { onRunEnd, runs } = watch(); + const { result, streams, ready } = setup({ beside: { steers }, runs }); + await ready(); + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(streams).toHaveLength(1)); + const sent = (result.current.contract.getMessages() ?? [])[2]; + + act(() => { + streams[0].push(created(sent, 'response-2')); + streams[0].push( + control({ reconcileReason: 'abort_persistence_failed', terminalStatus: 'aborted' }), + ); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(onRunEnd).toHaveBeenCalledWith({ + outcome: 'aborted', + generationCreatedAt: 3000, + responseMessageId: undefined, + reconcileReason: 'abort_persistence_failed', + }); + }); + + it('says a start the server answered as already settled was not a completed run', async () => { + const { onRunEnd, runs } = watch(); + const { result, sendMessages, ready } = setup({ runs }); + await ready(); + sendMessages.mockResolvedValueOnce({ + status: 'settled', + conversationId, + generationProtocolVersion: 2, + }); + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(onRunEnd).toHaveBeenCalledWith(expect.objectContaining({ outcome: 'aborted' })); + }); + + it('puts a turn back in the queue when the server refuses its start, and not when it may have started', async () => { + const { calls, steers, named } = record(); + const { onRunEnd, runs } = watch(); + const { result, sendMessages, ready } = setup({ beside: { steers }, runs }); + await ready(); + calls.length = 0; + + sendMessages.mockRejectedValueOnce(refusal(403, { message: 'Not allowed' })); + act(() => { + result.current.contract.ask({ text: 'Next question' }); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(named('restore')).toHaveLength(1); + expect(named('restore')[0][1]).toMatchObject({ userMessage: { text: 'Next question' } }); + expect(named('block')).toEqual([]); + /** The refusal is the turn's reply, and nothing queued behind it is sent on its account. */ + expect(onRunEnd).toHaveBeenCalledWith(expect.objectContaining({ outcome: 'error' })); + + /** A failure that may have started the turn puts nothing back: it could be sent twice. */ + sendMessages.mockRejectedValueOnce(refusal(502, { message: 'Bad gateway' })); + act(() => { + result.current.contract.ask({ text: 'Again' }); + }); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(2)); + expect(named('restore')).toHaveLength(1); + }); + + it('leaves nothing of a turn another generation got ahead of, and follows that generation', async () => { + const { calls, steers, named } = record(); + const { onRunEnd, runs } = watch(); + const { result, sendMessages, streams, setStatus, onWithdrawn, ready } = setup({ + beside: { steers }, + runs, + }); + await ready(); + calls.length = 0; + + /** The place this turn was queued for was taken by a generation started elsewhere. */ + setStatus({ active: true, streamId: conversationId, createdAt: 5000 }); + sendMessages.mockRejectedValueOnce( + refusal(409, { + status: 'predecessor_mismatch', + code: 'GENERATION_PREDECESSOR_MISMATCH', + streamId: conversationId, + conversationId, + generationCreatedAt: 5000, + active: true, + }), + ); + act(() => { + result.current.contract.ask({ text: 'Queued follow-up' }); + }); + + /** Back in the queue behind the winner, which is the generation now followed. */ + await waitFor(() => expect(streams).toHaveLength(1)); + expect(named('restore')).toHaveLength(1); + expect(named('restore')[0].slice(1)).toEqual([ + expect.objectContaining({ + userMessage: expect.objectContaining({ text: 'Queued follow-up' }), + }), + 5000, + ]); + /** Neither its message nor a failure stays in the list, and no run is said to have ended. */ + expect(ids(result.current.contract.getMessages())).toEqual(['user-1', 'response-1']); + expect(result.current.followed.error).toBeUndefined(); + expect(onRunEnd).not.toHaveBeenCalled(); + /** The words are in the queue, so they are not also handed back to the composer. */ + expect(onWithdrawn).not.toHaveBeenCalled(); + }); + + describe('for a turn that replays a steer the server had parked', () => { + /** A turn from the reader's queue that is the recovery of the parked steer `steer-parked`. */ + const replay = (result: { current: { contract: ReturnType } }) => + act(() => { + result.current.contract.ask( + { text: 'Parked by the server' }, + { overrideRecoverySteerId: 'steer-parked' }, + ); + }); + const source = [{ steerId: 'steer-parked', text: 'Parked by the server' }]; + const letGo = { + active: false, + generationProtocolVersion: 2, + unrecoveredSteers: source, + } as ChatStreamStatus; + + it('sends nothing when the reader has already dealt with that steer', async () => { + const { steers, named } = record(new Set(['steer-parked'])); + const { onRunEnd, runs } = watch(); + const { result, sendMessages, ready } = setup({ beside: { steers }, runs }); + await ready(); + + replay(result); + await waitFor(() => expect(named('restore')).toHaveLength(1)); + await settle(); + + expect(named('held?')).toEqual([['held?', conversationId, 'steer-parked']]); + expect(sendMessages).not.toHaveBeenCalled(); + expect(ids(result.current.contract.getMessages())).toEqual(['user-1', 'response-1']); + expect(result.current.followed.error).toBeUndefined(); + expect(onRunEnd).not.toHaveBeenCalled(); + }); + + it('puts the steer back when a start that may have run turns out not to have kept it', async () => { + const { steers, named } = record(); + const { onRunEnd, runs } = watch(); + const { result, sendMessages, setStatus, ready } = setup({ beside: { steers }, runs }); + await ready(); + setStatus(letGo); + sendMessages.mockRejectedValueOnce(refusal(502, { message: 'Bad gateway' })); + + replay(result); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + + /** Not as a refused start, which it was not, but on the server's word after the end. */ + expect(named('restore')).toEqual([]); + expect(named('toQueued')).toEqual([ + [ + 'toQueued', + conversationId, + source, + { generationProtocolVersion: 2, allowPreviouslyConvertedIds: ['steer-parked'] }, + ], + ]); + }); + + it('puts the steer back when its stream reports the failure, and not for a turn that replays none', async () => { + const { calls, steers, named } = record(); + const { onRunEnd, runs } = watch(); + const harness = createTransport(2); + const { result, streams, ready } = setup({ beside: { steers }, runs, harness }); + await ready(); + harness.setStatus(letGo); + const failure = { + type: 'error', + data: { message: 'failed', generationProtocolVersion: 2 }, + } as ChatEvent; + + replay(result); + await waitFor(() => expect(streams).toHaveLength(1)); + act(() => streams[0].push(failure)); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(1)); + expect(named('toQueued')).toHaveLength(1); + expect(named('toQueued')[0][2]).toEqual(source); + + calls.length = 0; + act(() => { + result.current.contract.ask({ text: 'An ordinary turn' }); + }); + await waitFor(() => expect(streams).toHaveLength(2)); + act(() => streams[1].push(failure)); + await waitFor(() => expect(onRunEnd).toHaveBeenCalledTimes(2)); + expect(named('toQueued')).toEqual([]); + }); + }); + + it('settles steers left waiting by a run that ended while the conversation was not open', async () => { + const { calls, steers } = record(); + const harness = createTransport(); + const parked = [{ steerId: 'steer-parked', text: 'Parked by the server' }]; + harness.setStatus({ active: false, unrecoveredSteers: parked } as ChatStreamStatus); + const { ready } = setup({ beside: { steers }, harness }); + await ready(); + await settle(); + + const stored = [user, reply('response-1', 'Hi')]; + expect(calls.map(([name]) => name)).toEqual([ + 'appliedIds', + 'settle', + 'adopt', + 'toQueued', + 'sweep', + ]); + expect(calls[1]).toEqual(['settle', conversationId, stored]); + expect(calls[3]).toEqual(['toQueued', conversationId, parked, {}]); + expect(calls[4]).toEqual([ + 'sweep', + conversationId, + { + excludeSteerIds: new Set(['steer-taken', 'steer-promoted', 'steer-parked']), + generationProtocolVersion: undefined, + }, + ]); + }); + + it('settles nothing from stored rows while a generation is running, or after one that ended on its reply', async () => { + const running = record(); + const harness = createTransport(); + harness.setStatus({ active: true, streamId: conversationId, createdAt: 2000 }); + const attached = setup({ beside: { steers: running.steers }, harness }); + await attached.ready(); + await waitFor(() => expect(attached.streams).toHaveLength(1)); + await settle(); + /** Its own frames settle them: nothing is swept on the strength of rows mid-run. */ + expect(running.named('sweep')).toEqual([]); + + /** It ends on a final frame with the reply in it, which settles them as it is applied. */ + harness.setStatus({ active: false }); + act(() => attached.streams[0].push(final(user, reply('response-1', 'Hi')))); + await waitFor(() => expect(attached.result.current.followed.isFollowing).toBe(false)); + await settle(); + expect(running.named('sweep')).toEqual([['sweep', conversationId]]); + }); + }); + it("drops the files another conversation left staged in the pane, and keeps this one's", async () => { const staged = new Map([['file-1', { file_id: 'file-1', progress: 1 } as ExtendedFile]]); const first = setup(); diff --git a/packages/chat/src/react/follow.ts b/packages/chat/src/react/follow.ts index 2e9166e3f64..a7f3d1b3f5f 100644 --- a/packages/chat/src/react/follow.ts +++ b/packages/chat/src/react/follow.ts @@ -4,11 +4,13 @@ import type { TMessage, ChatEvent, ChatFinalFrame } from 'librechat-data-provide import type { ChatStatus, ChatStream, + ChatStreamStatus, ChatTransport, SubmittedTurn, ChatConnection, AnnounceOptions, ChatFinishResult, + ResumableSteers, EventApplierInit, EventApplierEffect, GenerationProtocolVersion, @@ -26,7 +28,15 @@ import { hasPendingAssistantParent, prepareSubmittedTurn, describeSubmittedTurn, + getRecoverySteerId, + settleStoredSteers, + restoreRefusedStart, + toStartGenerationError, + restoreReleasedSource, + completedResponseMessageId, GENERATION_PROTOCOL_VERSION, + supportsGenerationProtocolV2, + getPredecessorMismatchStartResponse, } from '../core'; import { ReactQueryChatState } from './state'; import { useSnapshot } from './snapshot'; @@ -97,6 +107,11 @@ export type FollowedRunEnd = { generationCreatedAt?: number; /** The reply it left, when it left one. */ responseMessageId?: string; + /** + * Why the run ended on a frame that carried none of it. `abort_persistence_failed` says the + * stop was not saved, so nothing queued behind the run may be sent on the strength of it. + */ + reconcileReason?: ChatFinalFrame['reconcileReason']; }; /** One page of stored messages, oldest first. */ @@ -108,7 +123,15 @@ export type FollowedPage = { type AppliedBeside = Pick; -export type FollowBeside = AppliedBeside & { +/** + * Main chat's steer bookkeeping as a followed chat reaches it: what the event applier calls for + * the frames it applies, and what a queued turn needs when its start is refused. + */ +type FollowedSteers = NonNullable & + Pick; + +export type FollowBeside = Omit & { + steers?: FollowedSteers; /** * The list now holds what the server stores of the conversation: its stored rows were just * read, or a turn sent from here ended on its own final frame. `final` is the frame the last @@ -218,7 +241,7 @@ type Entry = { id: string; chat: Chat; attach: () => Promise; - settle: () => Promise; + settle: () => Promise; loadEarlier: () => Promise; canSend: FollowedChat['canSend']; send: FollowedChat['send']; @@ -239,6 +262,21 @@ type Attachment = { received: boolean; foreign?: boolean; withdrawn?: boolean; + /** The final frame it ended on, whether or not that frame carried the run's messages. */ + terminal?: ChatFinalFrame; + /** + * It ended on an error the server wrote into the stream; `negotiated` says that error spoke + * the generation protocol whose parked steers this client may restore. + */ + failure?: { negotiated: boolean }; + /** + * For a turn sent from here that was never admitted, so nothing of it stays in the list: + * `behind` when another generation had taken the place it was queued for, which is then the + * one to follow; `held` when it would have replayed a steer the reader had already dealt with. + */ + displaced?: 'behind' | 'held'; + /** For a turn sent from here: its start failed in a way that may still have started it. */ + unanswered?: boolean; }; /** @@ -384,27 +422,101 @@ export function useFollowChat({ } return known; }; - /** Tells the caller a generation ended, once the list holds what it left. */ - const runEnded = (finished: ChatFinishResult | undefined, withdrawn = false): void => { + /** + * How a generation ended, as main chat's stream session says it, since it decides whether + * what is queued behind the run is sent. A run that ended on a frame carrying none of it + * completed only if the server says so and its stored rows were read; a start the server + * answered as already settled is not a completion of this turn. A stop that lands just + * before the run completes can end it on a reply marked unfinished with no word of an + * abort: it was stopped all the same. + */ + const outcomeOf = (current: Attachment, read: boolean): FollowedRunEnd['outcome'] => { + const { finished, terminal, withdrawn } = current; + if (finished?.isError === true) { + return 'error'; + } + if (finished?.isSettled === true) { + if (terminal?.terminalStatus === 'complete') { + return read ? 'completed' : 'error'; + } + return 'aborted'; + } + if ( + finished?.isAbort === true || + withdrawn === true || + finished?.message?.unfinished === true + ) { + return 'aborted'; + } + return 'completed'; + }; + /** + * Tells the caller a generation ended, once the list holds what it left. `read` says the + * stored rows were read since it ended, and `turn` is the turn sent from here, if it was one. + */ + const runEnded = ( + current: Attachment | undefined, + read: boolean, + turn?: SubmittedTurn, + ): void => { const known = forget(); - if (finished == null || finished.isDisconnect === true) { + const finished = current?.finished; + if (current == null || finished == null || finished.isDisconnect === true) { return; } - /** - * A stop that lands just before the run completes can end it on a final frame that marks - * the reply unfinished and says nothing of an abort. It was stopped all the same, and is - * said to be, as main chat's session says it: what is queued behind it is not sent. - */ - let outcome: FollowedRunEnd['outcome'] = 'completed'; - if (finished.isError === true) { - outcome = 'error'; - } else if (finished.isAbort === true || withdrawn || finished.message?.unfinished === true) { - outcome = 'aborted'; - } + const outcome = outcomeOf(current, read); + /** A run with no reply of its own in hand is named by the reply the stored rows hold. */ + const responseMessageId = + finished.isSettled === true + ? completedResponseMessageId( + outcome === 'completed' ? chat.messages : undefined, + turn?.submission.userMessage?.messageId ?? + current.terminal?.requestMessage?.messageId, + turn?.submission.initialResponse?.messageId ?? finished.message?.messageId, + ) + : finished.message?.messageId; host.current.onRunEnd?.({ outcome, generationCreatedAt: known?.createdAt, - responseMessageId: finished.message?.messageId, + responseMessageId, + ...(finished.reconcileReason != null && { reconcileReason: finished.reconcileReason }), + }); + }; + /** + * Whether the run's steers are still to be settled against the stored rows: it ended, and + * on nothing that carried its reply. A final frame with the reply in it settled them when + * it was applied, and so did an error the server wrote. + */ + const unsettled = (current: Attachment | undefined): boolean => + current?.finished != null && + current.finished.isDisconnect !== true && + current.failure == null && + (current.terminal == null || current.terminal.reconcile === true); + /** + * Settles the reader's steers against the rows just read and the run's last status. Nothing + * while a generation is running under the conversation: its own frames settle them. + */ + const settleSteers = async ( + current?: Attachment, + turn?: SubmittedTurn, + known?: ChatStreamStatus, + ): Promise => { + const steers = host.current.beside?.steers; + if (steers == null) { + return; + } + const status = + known ?? + (await Promise.resolve(host.current.transport.getStatus?.(id)).catch(() => undefined)); + if (stale || status?.active === true) { + return; + } + settleStoredSteers(steers, id, { + messages: chat.messages, + status, + promoted: current?.terminal?.promotedSteers, + recoverySteerId: turn == null ? null : getRecoverySteerId(turn.submission), + generationProtocolVersion: generation?.protocolVersion, }); }; /** The final frame the last generation ended on, until the caller is told the list settled. */ @@ -430,6 +542,57 @@ export function useFollowChat({ /** Not when the server answered the start with a generation that is not this turn. */ turn: () => (attachment?.foreign === true ? undefined : sent?.submission), }); + /** + * A start the server refused leaves a turn taken from the reader's queue where main chat + * leaves it: back in the queue, in its place. A turn another generation got ahead of (the + * place it was queued for was taken) was never admitted, so it goes back behind the + * generation that won, and is marked so that nothing of it stays in the list. + */ + const refused = ( + turn: SubmittedTurn | undefined, + current: Attachment | undefined, + error: unknown, + ): void => { + const steers = host.current.beside?.steers; + if (turn == null || steers == null) { + return; + } + const winner = getPredecessorMismatchStartResponse(error); + if (winner != null) { + steers.restoreQueued(turn.submission, winner.generationCreatedAt); + if (current != null) { + current.displaced = 'behind'; + } + return; + } + const restored = restoreRefusedStart(steers, turn.submission, toStartGenerationError(error)); + if (!restored && current != null) { + current.unanswered = true; + } + }; + /** + * A turn that replays a parked steer ended without the server keeping it: its start failed + * in a way that may have started it, or the stream reported the failure. Only a status + * read now, after that end, can say the server let the steer go again, and so put it back. + */ + const recoverSource = async (turn: SubmittedTurn, current: Attachment): Promise => { + const steers = host.current.beside?.steers; + const recoverySteerId = getRecoverySteerId(turn.submission); + const ended = + current.unanswered === true || + (current.failure?.negotiated === true && + generation?.protocolVersion === GENERATION_PROTOCOL_VERSION); + if (steers == null || recoverySteerId == null || !ended) { + return; + } + const status = await Promise.resolve(host.current.transport.getStatus?.(id)).catch( + () => undefined, + ); + if (stale || status == null) { + return; + } + restoreReleasedSource(steers, id, recoverySteerId, status, GENERATION_PROTOCOL_VERSION); + }; const chat = new Chat({ id, state: new ReactQueryChatState({ queryClient, key: id }), @@ -437,16 +600,33 @@ export function useFollowChat({ transport: { sendMessages: async (request) => { const turn = attachment; - const sent = await host.current.transport.sendMessages(request); + const asked = sent; + const steers = host.current.beside?.steers; + const replayed = asked == null ? null : getRecoverySteerId(asked.submission); + if (asked != null && replayed != null && steers?.isRecoveryHeld(id, replayed) === true) { + /** The reader removed or changed the steer this turn would replay: it is not sent. */ + steers.restoreQueued(asked.submission); + if (turn != null) { + turn.displaced = 'held'; + } + throw new Error('The steer this turn would replay is no longer the reader’s to send'); + } + let answer: Awaited>; + try { + answer = await host.current.transport.sendMessages(request); + } catch (error) { + refused(asked, turn, error); + throw error; + } if (turn != null) { turn.foreign = - sent.status === 'replaced' || - (sent.status === 'stream' && sent.stream.resumed === true); + answer.status === 'replaced' || + (answer.status === 'stream' && answer.stream.resumed === true); } - if (sent.status === 'stream') { - note(sent.stream); + if (answer.status === 'stream') { + note(answer.stream); } - return sent; + return answer; }, reconnectToStream: async (request) => { const stream = await host.current.transport.reconnectToStream(request); @@ -471,6 +651,11 @@ export function useFollowChat({ if (attachment != null && event.type !== 'error') { attachment.received = true; } + if (attachment != null && event.type === 'final') { + attachment.terminal = event.data; + } else if (attachment != null && event.type === 'error' && event.status == null) { + attachment.failure = { negotiated: supportsGenerationProtocolV2(event.data) }; + } if (event.type === 'final' && event.data.earlyAbort === true) { /** Stopped before the server kept anything of it: there is no reply it ended on. */ if (attachment != null) { @@ -608,12 +793,12 @@ export function useFollowChat({ setUnattached(false); /** Whether a generation was reached and not lost for good. */ let reached = false; - /** How the attachment last ended, which is how the generation ended unless it dropped. */ - let last: ChatFinishResult | undefined; + /** The last attachment, whose end is the generation's unless it dropped. */ + let last: Attachment | undefined; try { for (let failures = 0, absences = 0; !stale; ) { - const { finished, received } = await follow(); - last = finished; + last = await follow(); + const { finished, received } = last; reached ||= received || finished != null; /** * The caller says a run is going and none was found. Its stream may not be open yet: @@ -640,7 +825,13 @@ export function useFollowChat({ } reading = true; await read(); - runEnded(last); + if (unsettled(last)) { + await settleSteers(last); + } + if (stale) { + return; + } + runEnded(last, true); } catch { /** The chat reports a stream failure itself; a failed re-read leaves what it streamed. */ } finally { @@ -659,15 +850,20 @@ export function useFollowChat({ } }; - /** The caller saw the run end. A stream still open reads the stored rows itself when it ends. */ - const settle = async (): Promise => { + /** + * The caller saw the run end. A stream still open reads the stored rows itself when it ends. + * Says whether the rows were read. + */ + const settle = async (): Promise => { if (stale || !loaded || attaching || driving) { - return; + return false; } try { await read(); + return true; } catch { /** What is shown stays; the next open reads again. */ + return false; } }; @@ -692,6 +888,14 @@ export function useFollowChat({ */ if (status === 'unknown' || status?.active === true || host.current.live) { await attach(); + return; + } + /** + * Nothing is running, so a steer still shown as waiting is waiting on a run that ended + * while this conversation was not open: it is settled against what that run left. + */ + if (status != null) { + await settleSteers(undefined, undefined, status); } } catch { if (!stale) { @@ -738,7 +942,7 @@ export function useFollowChat({ } if (!stale && own) { let completed: TMessage[] | undefined; - if (current.withdrawn === true) { + if (current.withdrawn === true || current.displaced != null) { completed = withdrawnTurnMessages(turn, chat.messages); } else if (finished?.isError === true) { completed = failedTurnMessages(turn, chat.messages, chat.error); @@ -767,25 +971,49 @@ export function useFollowChat({ if (stale) { return; } + if (current.displaced != null) { + /** + * The turn was never admitted, and where it belongs it is back in the reader's queue. + * No run is said to have ended: that would send it again at once. When another + * generation took its place, that generation is followed to its end. + */ + chat.clearError(); + forget(); + if (current.displaced === 'behind' || owed) { + owed = false; + await attach(); + } + return; + } + await recoverSource(turn, current); + if (stale) { + return; + } if (dropped || owed) { owed = false; /** A turn that ended is over even when another generation is waiting to be followed. */ if (!dropped) { - runEnded(finished, current.withdrawn); + runEnded(current, false, turn); } await attach(); return; } if (!own) { - await settle(); - runEnded(finished, current.withdrawn); + const read = await settle(); + if (read && unsettled(current)) { + await settleSteers(current, turn); + } + if (stale) { + return; + } + runEnded(current, read, turn); return; } /** The turn's own final frame is its result, and the list as it stands is what it left. */ if (ended != null) { settled(); } - runEnded(finished, current.withdrawn); + runEnded(current, false, turn); }; /**