🕹️ feat: Queue, Steer, and Interrupt Side-Chat Replies (#18491)

* 🧭 feat: Queue and Steer a Reply From a Side Chat

* 🅿️ fix: Restore Parked Steers When a Side Chat Opens on a Finished Run
This commit is contained in:
Danny Avila 2026-11-19 09:15:27 -05:00 • committed by GitHub
parent 0c540688ef
commit e858e1f528
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 2657 additions and 266 deletions

View file

@ -1,4 +1,4 @@
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';
@ -14,13 +14,21 @@ import {
SIDE_CHAT_PANE,
useUsageHandler,
toResumableUsage,
useOwedSuccessor,
} from '@librechat/chat/react';
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';
@ -30,7 +38,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
@ -42,7 +52,7 @@ function useChat(
endpoint,
agent_id,
}: Pick<TConversation, 'conversationId' | 'endpoint' | 'agent_id'>,
options?: Pick<FollowChatOptions, 'onWithdrawn'>,
options?: SideChatOptions,
): FollowedChat {
const id = conversationId ?? '';
const { token } = useChatSettings().auth;
@ -125,11 +135,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, usage }),
[onAttachment, onSettled, announce, usage],
() => ({ onAttachment, onSettled, announce, usage, steers }),
[onAttachment, onSettled, announce, usage, steers],
);
return useFollowChat({
/**
* 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<number | null>(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],
);
const onRunEnd = useCallback(
(end: FollowedRunEnd) => {
removeActiveJob(queryClient, id);
tellRunEnd?.(end);
},
[id, queryClient, tellRunEnd],
);
const followed = useFollowChat({
id,
transport: generation,
loadMessages,
@ -137,7 +177,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]);
}
/**

View file

@ -1,17 +1,26 @@
import React from 'react';
import { RecoilRoot } from 'recoil';
import { getDefaultStore } from 'jotai';
import { contextSnapshotFamily } from '@librechat/chat/react';
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,
contextSnapshotFamily,
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';
@ -103,9 +112,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<TAgentQueuedTurnReceipt[]>({
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();
@ -115,13 +151,17 @@ const setup = (
<QueryClientProvider client={client}>
<AnnouncerContext.Provider value={announcer}>
<ChatTransportContext.Provider value={harness.transport}>
{children}
<StreamHostProvider host={streamHost}>
<ChatHostProvider host={chatHost}>
<SteerHostProvider host={steerHost}>{children}</SteerHostProvider>
</ChatHostProvider>
</StreamHostProvider>
</ChatTransportContext.Provider>
</AnnouncerContext.Provider>
</QueryClientProvider>
</RecoilRoot>
);
const view = renderHook(() => appSideChatHost.useChat(target), { wrapper });
const view = renderHook(() => appSideChatHost.useChat(target, options), { wrapper });
return { ...view, ...harness, client, announcePolite };
};
@ -329,6 +369,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<Partial<TAgentQueuedTurnReceipt>[]>(
[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<Partial<TAgentQueuedTurnReceipt>[]>(
[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,

View file

@ -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<HTMLButtonElement>(null);
const textAreaRef = useRef<HTMLTextAreaElement>(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}
/>
);
}

View file

@ -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);

View file

@ -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<ActiveJobsResponse>([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<ActiveJobsResponse>([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<ActiveJobsResponse>([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<ActiveJobsResponse>([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],
);
}

View file

@ -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),
);

View file

@ -426,13 +426,15 @@ test('a side chat opened again while its reply runs still has the words written
const reopened = page.getByRole('region', { name: 'Side chat' });
const again = reopened.getByRole('textbox', { name: 'Message input' });
/** Still running, and the words are in the field; they are still there once it ends. */
await expect(reopened.getByRole('button', { name: 'Stop generating' })).toBeVisible({
timeout: 30_000,
});
/**
* Still running, and the words are in the field: with something written, the send control
* is the one that acts on the reply in flight. They are still there once it ends.
*/
const duringRun = reopened.getByTestId('during-run-send-button');
await expect(duringRun).toBeVisible({ timeout: 30_000 });
await expect(again).toHaveValue('picked up where I left it');
await expect(reopened).toContainText('chunk-159', { timeout: 90_000 });
await expect(reopened.getByRole('button', { name: 'Stop generating' })).toHaveCount(0);
await expect(duringRun).toHaveCount(0);
await expect(again).toHaveValue('picked up where I left it');
});

View file

@ -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<string> {
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<typeof startChat>[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<AgentDetail>(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);
}
});

View file

@ -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 = <ContractThread contract={contract} followed={followed} slots={slots} own />;
/** Only an app that hosts the steer hooks has a queue for the reader to fill. */
const queues = useOptionalSteerHost() != null;
const thread = (
<>
{queues && <QueueDrain id={id} index={index} ask={contract.ask} />}
<ContractThread contract={contract} followed={followed} slots={slots} own />
</>
);
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<DrivenThreadProps, 'id' | 'index'> & { ask: ChatContract['ask'] }): null {
const revealQueuedTurn = useQueuedTurnReveal(id, index);
useQueueDrain(index, id, ask, revealQueuedTurn);
return null;
}

View file

@ -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<ChatScreenMessagesSlots>(
() => ({
...followedSlots,
...(own ? ownSlots : followedSlots),
renderThread: (props) => (
<>
<EarlierMessages
@ -105,7 +110,7 @@ export function ContractThread({
),
...slots,
}),
[slots, hasEarlier, isLoadingEarlier, isEarlierError, loadEarlier],
[own, slots, hasEarlier, isLoadingEarlier, isEarlierError, loadEarlier],
);
const messagesHost = useFollowedMessagesHost(own);
return (

View file

@ -6,8 +6,8 @@ import { atom, useAtom, useAtomValue, Provider, createStore } from 'jotai';
import { act, render, screen, waitFor, fireEvent } from '@testing-library/react';
import { Constants, ContentTypes, EModelEndpoint } from 'librechat-data-provider';
import type { TMessage, ChatEvent, TConversation } from 'librechat-data-provider';
import type { ChatStream, ChatTransport, QueuedMessage, ChatSendRequest } from '../../../core';
import type { SideChatHost, SideChatSurfaceProps } from '../../../react/side/host';
import type { ChatStream, ChatTransport, ChatSendRequest } from '../../../core';
import type { SideChat } from '../../../react/side/state';
import type { ChatHost } from '../../../react/chat/host';
import {
@ -20,13 +20,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 { 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';
@ -112,6 +117,8 @@ function UserRow({ text }: { text: string }) {
return <div data-testid="row" data-added={added?.conversationId ?? 'none'}>{`user=${text}`}</div>;
}
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({
@ -168,6 +175,7 @@ function setup({
managed = false,
draft,
Surface,
steers = false,
}: {
chat?: SideChat;
stored?: TMessage[];
@ -176,6 +184,8 @@ function setup({
managed?: boolean;
draft?: string;
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(
@ -245,6 +255,8 @@ function setup({
)
);
}
const within = (panel: React.ReactElement) =>
steers ? <SteerHostProvider host={steerHost}>{panel}</SteerHostProvider> : panel;
const tree = (current: SideChat) => (
<QueryClientProvider client={queryClient}>
<Provider store={store}>
@ -266,14 +278,16 @@ function setup({
<SideChatHostProvider host={sideChatHost}>
<MessagesHostProvider host={messagesHost}>
<MessagePartsHostProvider host={partsHost}>
{managed ? (
<OwnedPanel />
) : (
<SideChatPanel
chat={current}
onClose={onClose}
onHandedTextTaken={() => onHandedTextTaken()}
/>
{within(
managed ? (
<OwnedPanel />
) : (
<SideChatPanel
chat={current}
onClose={onClose}
onHandedTextTaken={() => onHandedTextTaken()}
/>
),
)}
</MessagePartsHostProvider>
</MessagesHostProvider>
@ -380,6 +394,159 @@ 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<typeof setup>): Promise<TMessage> => {
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('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('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;
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));

View file

@ -1,13 +1,20 @@
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 { 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 { useSideChatHost } from '../../react/side/host';
@ -217,7 +224,44 @@ 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(
({ 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, {
onWithdrawn: takeBack,
onGeneration: noteGeneration,
onRunEnd: noteRunEnd,
});
const panelRef = useRef<HTMLDivElement>(null);
/** The pane's conversation is what a turn is built from, so the pane is told which it holds. */

View file

@ -63,6 +63,7 @@ const followedChat = (overrides: Partial<FollowedChat> = {}): FollowedChat => ({
canSend: () => false,
send: () => false,
stop: () => Promise.resolve(),
attach: () => undefined,
...overrides,
});

View file

@ -4768,6 +4768,7 @@ describe('SubagentThreadPanel', () => {
canSend: () => false,
send: () => false,
stop: () => Promise.resolve(),
attach: () => undefined,
...overrides,
});

View file

@ -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<typeof createEventApplier>[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,156 @@ 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<ChatEvent, { type: 'final' }>;
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('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);
const { context: ctx } = createList();
const ending = final('Hi') as Extract<ChatEvent, { type: 'final' }>;
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', () => {

View file

@ -0,0 +1,192 @@
import type { TMessage, TSubmission, TPendingSteer } from 'librechat-data-provider';
import type { FinalSteers } from '../resumable/steers';
import {
settleStoredSteers,
restoreRefusedStart,
settleFinishedSteers,
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'),
seed: log('seed'),
};
return {
calls,
steers: steers as unknown as FinalSteers &
Parameters<typeof restoreRefusedStart>[0] &
Parameters<typeof settleFinishedSteers>[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([]);
});
});
describe('settleFinishedSteers', () => {
const accepted = [
...parked,
{ steerId: 'steer-accepted', text: 'Accepted, not parked yet' },
] as TPendingSteer[];
it('restores what the server parked and what it had only accepted, once each, under the status’s protocol', () => {
const { calls, steers } = record();
settleFinishedSteers(
steers,
'thread-1',
{
generationProtocolVersion: 2,
unrecoveredSteers: parked,
resumeState: { pendingSteers: accepted } as never,
},
stored,
);
expect(calls).toEqual([
['toQueued', 'thread-1', accepted, { generationProtocolVersion: 2 }],
['settle', 'thread-1', stored],
['seed', 'thread-1', []],
]);
});
it('reads a status that names no protocol as the first one, and converts nothing when nothing is left', () => {
const legacy = record();
settleFinishedSteers(legacy.steers, 'thread-1', { unrecoveredSteers: parked }, stored);
expect(legacy.calls[0]).toEqual([
'toQueued',
'thread-1',
parked,
{ generationProtocolVersion: 1 },
]);
const { calls, steers } = record();
settleFinishedSteers(steers, 'thread-1', {}, stored);
expect(calls.map(([name]) => name)).toEqual(['settle', 'seed']);
});
});

View file

@ -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, nameStepResponse } 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<ResumableSteers, 'resolve' | 'markLiveApplied' | 'update' | 'seed'> & 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<ChatEvent, { type: 'abort' | 'error' }>): 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') {
@ -707,6 +747,19 @@ 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);
/**
* 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);
if (submission != null) {
init.usage?.finalizeUsage(event.data, submission);
@ -719,6 +772,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();

View file

@ -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;

View file

@ -3,7 +3,6 @@ import type {
TMessage,
ChatEvent,
TAttachment,
TPendingSteer,
ChatFinalFrame,
EventSubmission,
ChatCreatedFrame,
@ -20,6 +19,7 @@ import { isInitialNewConversation, buildCreatedInitialResponse } from './message
import { isOAuthStepEvent, nameStepResponse } from './events';
import { reconcileGenerationLifecycle } from './reconcile';
import { ABORT_SWEEP_STATUSES } from '../steer/chips';
import { settleFinalSteers } from './steers';
import { handleSync } from './sync';
export function handleOpen({ sub, host }: StreamContext): void {
@ -64,51 +64,7 @@ async function handleFinal(ctx: StreamContext, data: ChatFinalFrame): Promise<vo
run.optimisticStreamIds.has(currentStreamId) ||
isInitialNewConversation(sub.submission),
});
// 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(
host.steers.appliedIds(data.responseMessage ? [data.responseMessage] : []),
);
host.steers.settleApplied(
finalConvoId,
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(
host.steers.adoptPromoted(
finalConvoId,
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.
host.steers.convertToQueued(
finalConvoId,
(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.
host.steers.convertLocalToQueued(finalConvoId);
settleFinalSteers(host.steers, finalConvoId, data, generationProtocolVersion);
let finalHandled = false;
try {
host.events.finalHandler(data, sub.submission as EventSubmission);

View file

@ -21,3 +21,4 @@ export * from './launch';
export * from './mount';
export * from './outcomes';
export * from './settled';
export * from './steers';

View file

@ -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;

View file

@ -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);

View file

@ -0,0 +1,228 @@
import type {
TMessage,
TSubmission,
TPendingSteer,
TPromotedSteer,
ChatFinalFrame,
} from 'librechat-data-provider';
import type { ResumableSteers, StreamStatusResponse } from './host';
import type { GenerationProtocolVersion } from '../protocol';
import type { StartGenerationError } from './start';
import { supportsGenerationProtocolV2, getGenerationProtocolVersion } from '../protocol';
import { dedupeSteersById } from '../steer/steer';
import { getRecoverySteerId } from './start';
/** 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);
}
/**
* 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<StreamStatusResponse, 'resumeState' | 'aggregatedContent' | 'unrecoveredSteers'>;
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<ResumableSteers, 'blockRecovery' | 'restoreQueued'>,
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<ResumableSteers, 'convertToQueued'>,
conversationId: string,
recoverySteerId: string,
status: Pick<StreamStatusResponse, 'active' | 'unrecoveredSteers' | 'generationProtocolVersion'>,
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;
}
/**
* Settles the reader's steers for a conversation found with nothing running: the run they were
* sent to ended while no one was following it.
*
* A terminal drain may have parked acknowledged steers no subscriber received (tab closed, or
* a reload racing the final event); they are restored as queued follow-ups. A pause that
* expired can report the run inactive before the sweeper parks its steers, which then still
* ride `resumeState.pendingSteers`, so both lists are converted, deduplicated by id. They are
* converted under the protocol the status itself speaks: no stream is open to have named one,
* and a parked steer restored without it would never consume its source.
*
* The run is terminal, so any chip still shown as waiting is stale: its steer either applied
* (an inline part in the stored reply) or rode the lists above.
*/
export function settleFinishedSteers(
steers: Pick<ResumableSteers, 'convertToQueued' | 'settleApplied' | 'seed'>,
conversationId: string,
status: Pick<
StreamStatusResponse,
'resumeState' | 'unrecoveredSteers' | 'generationProtocolVersion'
>,
messages: TMessage[] | undefined,
): void {
const leftoverSteers = dedupeSteersById(
status.unrecoveredSteers,
status.resumeState?.pendingSteers,
);
if (conversationId && leftoverSteers.length > 0) {
steers.convertToQueued(conversationId, leftoverSteers, {
generationProtocolVersion: getGenerationProtocolVersion(status),
});
}
steers.settleApplied(conversationId, messages);
steers.seed(conversationId, []);
}

View file

@ -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 {

View file

@ -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';
@ -143,7 +148,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';

View file

@ -62,12 +62,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);
@ -95,11 +96,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;
};
@ -185,6 +186,8 @@ function setup({
beside,
id = conversationId,
store = createStore(),
runs,
harness = createTransport(),
}: {
stored?: TMessage[];
services?: TurnServices;
@ -193,9 +196,12 @@ function setup({
/** The conversation the pane holds, and the pane's store when a spec shares one. */
id?: string;
store?: ReturnType<typeof createStore>;
/** What the caller is told of the conversation's generations. */
runs?: Pick<FollowChatOptions, 'onGeneration' | 'onRunEnd'>;
/** The transport, when a spec sets the server's state before the conversation opens. */
harness?: ReturnType<typeof createTransport>;
} = {}) {
const queryClient = new QueryClient();
const harness = createTransport();
const loadMessages = jest.fn(async () => stored);
const onWithdrawn = jest.fn();
const host: ChatHost = {
@ -229,6 +235,7 @@ function setup({
endpoint: conversation.endpoint,
onWithdrawn,
beside,
...runs,
});
const contract = useDrivenContract({
id,
@ -438,6 +445,569 @@ describe('useDrivenContract', () => {
expect(resetLive).not.toHaveBeenCalled();
});
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 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 });
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' }));
});
});
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<string>()) => {
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<NonNullable<FollowChatOptions['beside']>['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<string, unknown>): ChatEvent =>
({
type: 'final',
data: {
final: true,
reconcile: true,
generationProtocolVersion: 2,
conversation: { conversationId },
...data,
},
}) as ChatEvent;
const refusal = (status: number, data: Record<string, unknown>) =>
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<typeof useDrivenContract> } }) =>
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' };
/** A pause that expired: reported over before the server has parked what it accepted. */
const accepted = { steerId: 'steer-accepted', text: 'Accepted, not parked yet' };
harness.setStatus({
active: false,
generationProtocolVersion: 2,
unrecoveredSteers: [parked],
resumeState: { pendingSteers: [parked, accepted] },
} as ChatStreamStatus);
const { ready } = setup({ beside: { steers }, harness });
await ready();
await settle();
/**
* Both lists, each steer once, under the protocol the status speaks: no stream is open to
* have named one. Then what the stored rows hold is settled, and no chip is left waiting.
*/
const stored = [user, reply('response-1', 'Hi')];
expect(calls).toEqual([
['toQueued', conversationId, [parked, accepted], { generationProtocolVersion: 2 }],
['settle', conversationId, stored],
['seed', conversationId, []],
]);
});
it('restores nothing, and still clears stale chips, when nothing was left behind', async () => {
const { calls, steers } = record();
const { ready } = setup({ beside: { steers } });
await ready();
await settle();
expect(calls.map(([name]) => name)).toEqual(['settle', 'seed']);
});
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();

View file

@ -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<HTMLButtonElement>) => void;
/** Whether a stop just happened and the view should hold its scroll position. */

View file

@ -197,6 +197,7 @@ export function useDrivenContract({ id, followed, index }: DrivenContractOptions
handleContinue,
stopGenerating,
stopsUnnamed: true,
steers: true,
handleStopGenerating,
abortScroll,
setAbortScroll,

View file

@ -3,13 +3,16 @@ import { useQueryClient } from '@tanstack/react-query';
import type { TMessage, ChatEvent, ChatFinalFrame } from 'librechat-data-provider';
import type {
ChatStatus,
ChatStream,
ChatTransport,
SubmittedTurn,
ChatConnection,
AnnounceOptions,
ChatFinishResult,
ResumableSteers,
EventApplierInit,
EventApplierEffect,
GenerationProtocolVersion,
} from '../core';
import {
Chat,
@ -24,6 +27,16 @@ import {
hasPendingAssistantParent,
prepareSubmittedTurn,
describeSubmittedTurn,
getRecoverySteerId,
settleStoredSteers,
settleFinishedSteers,
restoreRefusedStart,
toStartGenerationError,
restoreReleasedSource,
completedResponseMessageId,
GENERATION_PROTOCOL_VERSION,
supportsGenerationProtocolV2,
getPredecessorMismatchStartResponse,
} from '../core';
import { ReactQueryChatState } from './state';
import { useSnapshot } from './snapshot';
@ -70,6 +83,35 @@ 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;
/**
* 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. */
@ -81,7 +123,15 @@ export type FollowedPage = {
type AppliedBeside = Pick<EventApplierInit, 'usage' | 'onAttachment' | 'onTitle' | 'steers'>;
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<AppliedBeside['steers']> &
Pick<ResumableSteers, 'restoreQueued' | 'blockRecovery' | 'isRecoveryHeld'>;
export type FollowBeside = Omit<AppliedBeside, 'steers'> & {
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
@ -121,6 +171,10 @@ const forwardBeside = (read: () => FollowBeside | undefined): Required<AppliedBe
update: (event) => 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),
},
});
@ -176,13 +230,20 @@ export type FollowedChat = {
* conversation, and is not attached to again.
*/
stop: () => Promise<void>;
/**
* 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 = {
id: string;
chat: Chat;
attach: () => Promise<void>;
settle: () => Promise<void>;
settle: () => Promise<boolean>;
loadEarlier: () => Promise<void>;
canSend: FollowedChat['canSend'];
send: FollowedChat['send'];
@ -203,6 +264,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;
};
/**
@ -254,6 +330,8 @@ export function useFollowChat({
onEvent,
onFinish,
onWithdrawn,
onGeneration,
onRunEnd,
}: FollowChatOptions): FollowedChat {
const queryClient = useQueryClient();
const host = useRef({
@ -266,6 +344,8 @@ export function useFollowChat({
onEvent,
onFinish,
onWithdrawn,
onGeneration,
onRunEnd,
});
host.current = {
transport,
@ -277,6 +357,8 @@ export function useFollowChat({
onEvent,
onFinish,
onWithdrawn,
onGeneration,
onRunEnd,
};
const [attempt, setAttempt] = useState(0);
const [entry, setEntry] = useState<Entry>();
@ -315,6 +397,127 @@ 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<void> | 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;
};
/**
* 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();
const finished = current?.finished;
if (current == null || finished == null || finished.isDisconnect === true) {
return;
}
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.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, for a run this chat followed to an end that carried no reply,
* 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): Promise<void> => {
const steers = host.current.beside?.steers;
if (steers == null) {
return;
}
const status = 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. */
let ended: ChatFinalFrame | undefined;
const settled = (): void => {
@ -334,9 +537,61 @@ 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),
});
/**
* 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<void> => {
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 }),
@ -344,15 +599,39 @@ 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<ReturnType<ChatTransport['sendMessages']>>;
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);
}
return sent;
if (answer.status === 'stream') {
note(answer.stream);
}
return answer;
},
reconnectToStream: async (request) => {
const stream = await host.current.transport.reconnectToStream(request);
note(stream);
return stream;
},
reconnectToStream: (request) => host.current.transport.reconnectToStream(request),
abort: (request) => host.current.transport.abort(request),
getStatus: (conversationId) =>
host.current.transport.getStatus?.(conversationId) ?? Promise.resolve({ active: false }),
@ -371,6 +650,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) {
@ -508,9 +792,12 @@ export function useFollowChat({
setUnattached(false);
/** Whether a generation was reached and not lost for good. */
let reached = false;
/** 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 = 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:
@ -537,11 +824,20 @@ export function useFollowChat({
}
reading = true;
await read();
if (last != null && 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 {
attaching = false;
reading = false;
/** Lost, or never read back: nothing is addressed as running any more. */
forget();
if (!stale) {
setFollowing(false);
setUnattached(!reached);
@ -553,15 +849,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<void> => {
/**
* 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<boolean> => {
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;
}
};
@ -586,6 +887,15 @@ 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.
*/
const steers = host.current.beside?.steers;
if (status != null && steers != null) {
settleFinishedSteers(steers, id, status, chat.messages);
}
} catch {
if (!stale) {
@ -632,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);
@ -661,26 +971,57 @@ 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(current, false, turn);
}
await attach();
return;
}
if (!own) {
await settle();
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();
return;
} else {
/**
* It ended with no final frame: it failed, or was stopped before the server kept
* anything of it. Nothing settles what was counted for its reply, so that count is
* dropped here, as main chat drops it, instead of being added to the conversation's
* next reply.
*/
host.current.beside?.usage?.resetLive?.(turn.submission);
}
/**
* It ended with no final frame: it failed, or was stopped before the server kept anything
* of it. Nothing settles what was counted for its reply, so that count is dropped here, as
* main chat drops it, instead of being added to the conversation's next reply.
*/
host.current.beside?.usage?.resetLive?.(turn.submission);
runEnded(current, false, turn);
};
/**
@ -792,6 +1133,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';
@ -813,5 +1156,6 @@ export function useFollowChat({
canSend,
send,
stop,
attach,
};
}

View file

@ -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<FollowChatOptions, 'onWithdrawn' | 'onGeneration' | 'onRunEnd'>;
/** 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. */
@ -51,7 +54,7 @@ export interface SideChatHost {
*/
useChat: (
conversation: Pick<TConversation, 'conversationId' | 'endpoint' | 'agent_id'>,
options?: Pick<FollowChatOptions, 'onWithdrawn'>,
options?: SideChatOptions,
) => FollowedChat;
/** Opens the conversation as the page's main one. */
useOpenConversation: () => (conversation: TConversation) => void;

View file

@ -50,6 +50,12 @@ export interface UseSteeringParams<File extends ComposerFile = ComposerFile> {
/** 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<File extends ComposerFile = ComposerFile>({
consumeDraft: takeComposerDraft,
index,
duringRun = index === 0,
conversationId,
conversation,
addedConversation,
@ -181,8 +188,8 @@ export default function useSteering<File extends ComposerFile = ComposerFile>({
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;

View file

@ -3,12 +3,16 @@ import type { useStore } from 'jotai';
import type { StreamStatusResponse, GenerationProtocolVersion } from '../../../core';
import type useSteerConvert from '../../steering/useSteerConvert';
import type { ChatMessageCache } from '../../chat/host';
import {
resolveDetachedRunEnd,
settleFinishedSteers,
isQueuedTurnSuccessorOwed,
} from '../../../core';
import {
isDetachedRunManual,
detachedRunByConvoId,
pendingRunEndByConvoId,
} from '../../steer/queue';
import { dedupeSteersById, resolveDetachedRunEnd, isQueuedTurnSuccessorOwed } from '../../../core';
import { revealedQueuedTurnFamily } from '../../steer/atoms';
/** The steer chips a finished run settles. */
@ -69,26 +73,16 @@ export function settleFinishedRun({
jotaiStore.set(revealFamily, null);
}
// A terminal drain may have parked acknowledged steers no subscriber
// received (tab closed / reload racing the final event); the status
// claim returns them exactly once; restore as queued follow-up chips.
// An expired pendingAction can report inactive BEFORE the sweeper parks
// the steer queue: those steers still ride resumeState.pendingSteers,
// so convert both lists (id-deduped) before the empty seed clears chips.
const leftoverSteers = dedupeSteersById(
streamStatus.unrecoveredSteers,
streamStatus.resumeState?.pendingSteers,
settleFinishedSteers(
{
convertToQueued: steers.convertSteersToQueued,
settleApplied: steers.settleAppliedSteerParts,
seed: steers.seedSteerChips,
},
conversationId,
{ ...streamStatus, generationProtocolVersion },
getMessages(),
);
if (conversationId && leftoverSteers.length > 0) {
steers.convertSteersToQueued(conversationId, leftoverSteers, {
generationProtocolVersion,
});
}
// The run is terminal, so any remaining local pending chip is stale:
// its steer either applied (inline part in the saved message) or rode
// `unrecoveredSteers` above, the same empty-list reconcile as the resume path.
steers.settleAppliedSteerParts(conversationId, getMessages());
steers.seedSteerChips(conversationId, []);
/** A run this pane stopped watching when the user left has ended on the server, which
* deleted the job. Its persisted response tells how it ended; parking that end lets the
* queue drain send a follow-up queued during the run, as an attached run would have.

View file

@ -33,6 +33,7 @@ const followed = (overrides: Partial<FollowedChat> = {}): FollowedChat => ({
canSend: () => false,
send: () => false,
stop: () => Promise.resolve(),
attach: () => undefined,
...overrides,
});

View file

@ -130,6 +130,7 @@ const opening: FollowedChat = {
canSend: () => false,
send: () => false,
stop: () => Promise.resolve(),
attach: () => undefined,
};
const ThreadFollowsContext: Context<ThreadFollows | undefined> = createContext<