Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🪝 refactor: Own Ask and Regenerate in the Chat Package (#17540)

Marco Beretta658712c2dfa0
diff --git a/client/src/Providers/ChatHostContext.tsx b/client/src/Providers/ChatHostContext.tsx
index 9003cc3378..9b59205a69 100644
--- a/client/src/Providers/ChatHostContext.tsx
+++ b/client/src/Providers/ChatHostContext.tsx
@@ -9,9 +9,9 @@ import { useLatestMessage, useLatestMessageId } from '~/hooks/Messages/useLatest
import { siblingIdxFamily, siblingKey } from '~/components/Chat/Messages/Thread/state';
import { useChatSettings } from '~/Providers/ChatSettingsContext';
import { messageAttachmentsMapAtom } from '~/hooks/SSE/atoms';
-import useChatFunctions from '~/hooks/Chat/useChatFunctions';
import { getMappingOptions } from '~/hooks/Chat/outcomes';
import { useAbortStreamMutation } from '~/data-provider';
+import useTurnServices from '~/hooks/Chat/services';
import useNewConvo from '~/hooks/useNewConvo';
/** Cache events that add, drop or rewrite a query's data. */
@@ -73,11 +73,11 @@ function useMessageCache(): ChatMessageCache {
}
/** The app's services behind `useChatHelpers`: its pane store, message query cache, turn
- * builder, thread selection, transport and settings. */
+ * services, thread selection, transport and settings. */
export const appChatHost: ChatHost = {
usePaneConversation: (index) => useChatSettings().usePaneConversationState(index),
useNewConversation: (index) => useNewConvo(index).newConversation,
- useTurns: (params) => useChatFunctions(params),
+ useTurnServices,
useLatestMessage: (index, key) => useLatestMessage(index, key),
useLatestMessageId: (index, key) => useLatestMessageId(index, key),
useSetSiblingIdx: (parentMessageId) => useSetAtom(siblingIdxFamily(siblingKey(parentMessageId))),
diff --git a/client/src/hooks/Chat/__tests__/contract.spec.tsx b/client/src/hooks/Chat/__tests__/contract.spec.tsx
index 40f387b76f..3715af6d2b 100644
--- a/client/src/hooks/Chat/__tests__/contract.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/contract.spec.tsx
@@ -28,9 +28,9 @@ jest.mock('~/hooks/Messages/useLatestMessage', () => ({
useLatestMessageId: () => null,
}));
-jest.mock('~/hooks/Chat/useChatFunctions', () => ({
+jest.mock('~/hooks/Chat/services', () => ({
__esModule: true,
- default: () => ({ ask: jest.fn(), regenerate: jest.fn() }),
+ default: () => jest.requireActual('test/turnServices').createTestTurnServices(),
}));
jest.mock('~/hooks/useNewConvo', () => ({
diff --git a/client/src/hooks/Chat/__tests__/feedback.spec.tsx b/client/src/hooks/Chat/__tests__/feedback.spec.tsx
index 1f956a5042..d8acee8622 100644
--- a/client/src/hooks/Chat/__tests__/feedback.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/feedback.spec.tsx
@@ -25,9 +25,9 @@ jest.mock('~/hooks/Messages/useLatestMessage', () => ({
useLatestMessageId: () => null,
}));
-jest.mock('~/hooks/Chat/useChatFunctions', () => ({
+jest.mock('~/hooks/Chat/services', () => ({
__esModule: true,
- default: () => ({ ask: jest.fn(), regenerate: jest.fn() }),
+ default: () => jest.requireActual('test/turnServices').createTestTurnServices(),
}));
jest.mock('~/hooks/useNewConvo', () => ({
diff --git a/client/src/hooks/Chat/__tests__/useChatFunctions.regenerate.spec.tsx b/client/src/hooks/Chat/__tests__/useChatFunctions.regenerate.spec.tsx
index f234cda103..f0b301959f 100644
--- a/client/src/hooks/Chat/__tests__/useChatFunctions.regenerate.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/useChatFunctions.regenerate.spec.tsx
@@ -484,7 +484,7 @@ describe('useChatFunctions ask', () => {
expect(setMessages).not.toHaveBeenCalled();
expect(setSubmission).not.toHaveBeenCalled();
expect(mockLoggerWarn).toHaveBeenCalledWith(
- '[useChatFunctions] Refusing to send before existing conversation history loads',
+ '[useTurns] Refusing to send before existing conversation history loads',
);
});
diff --git a/client/src/hooks/Chat/services.ts b/client/src/hooks/Chat/services.ts
new file mode 100644
index 0000000000..6fdced9656
--- /dev/null
+++ b/client/src/hooks/Chat/services.ts
@@ -0,0 +1,115 @@
+import { useStore } from 'jotai';
+import { useNavigate } from 'react-router-dom';
+import { QueryKeys } from 'librechat-data-provider';
+import { useQueryClient } from '@tanstack/react-query';
+import type { ChatTurnsParams, TurnServices } from '@librechat/chat/react';
+import type { TEndpointsConfig } from 'librechat-data-provider';
+import {
+ logger,
+ requestChatFocus,
+ markPasteSubmitted,
+ bindComposerLaunch,
+ getRouteChatProjectId,
+} from '~/utils';
+import {
+ withSubmittedCodeDecision,
+ resolveSubmittedCodeApprovalMode,
+} from '~/hooks/Agents/codeDecision';
+import { activeUsageResponseIdFamily } from '~/components/Chat/Input/TokenUsage/store';
+import useFocusRegeneratedResponse from '~/hooks/Chat/useFocusRegeneratedResponse';
+import useGetConversation from '~/hooks/Conversations/useGetConversation';
+import useCodeApprovalMode from '~/hooks/Agents/useCodeApprovalMode';
+import useSetFilesToDelete from '~/hooks/Files/useSetFilesToDelete';
+import { useAgentsMapContext } from '~/Providers/AgentsMapContext';
+import { useChatSettings } from '~/Providers/ChatSettingsContext';
+import useCodeWorkspace from '~/hooks/Agents/useCodeWorkspace';
+import useGetSender from '~/hooks/Conversations/useGetSender';
+import { resolveSubmittedReasoning } from './ask/reasoning';
+import { isHistoryRevalidating } from './ask/guards';
+import useUserKey from '~/hooks/Input/useUserKey';
+
+/** The app's side of a pane's turns: its catalogs, router, composer files, code workspace and
+ * logger, for the package's `useTurns`. */
+export default function useTurnServices({
+ index,
+ conversation,
+}: Pick<ChatTurnsParams, 'index' | 'conversation'>): TurnServices {
+ const store = useStore();
+ const navigate = useNavigate();
+ const getSender = useGetSender();
+ const queryClient = useQueryClient();
+ const setFilesToDelete = useSetFilesToDelete();
+ const agentsMap = useAgentsMapContext();
+ const { isTemporary, config, auth, getEphemeralAgent, addedConversation } = useChatSettings();
+ const { getExpiry } = useUserKey(conversation?.endpoint ?? '');
+ const focusResponse = useFocusRegeneratedResponse();
+ const getConversation = useGetConversation(index);
+ const codeWorkspaceState = useCodeWorkspace(conversation, addedConversation);
+ const { modes: codeApprovalModes, selected: fallbackCodeApprovalMode } = useCodeApprovalMode(
+ conversation,
+ addedConversation,
+ codeWorkspaceState.mode,
+ );
+
+ return {
+ logger,
+ isTemporary,
+ user: auth.user,
+ modelSpecs: config.modelSpecs,
+ getEndpointsConfig: () => queryClient.getQueryData<TEndpointsConfig>([QueryKeys.endpoints]),
+ getEphemeralAgent,
+ getSender,
+ getUserKey: getExpiry,
+ getRouteProjectId: getRouteChatProjectId,
+ isHistoryRevalidating: (conversationId) => isHistoryRevalidating(queryClient, conversationId),
+ resolveCode: (submitted) => {
+ const latest = getConversation();
+ const latestApprovalMode = latest?.codeApprovalMode;
+ const workspaceSubmission = codeWorkspaceState.resolveSubmission(
+ latest?.codeWorkspaces ?? submitted?.codeWorkspaces,
+ latest?.codeEnvironmentMode ?? submitted?.codeEnvironmentMode,
+ );
+ if (workspaceSubmission == null) {
+ return null;
+ }
+ const { codeEnvironmentMode, codeWorkspaces } = workspaceSubmission;
+ return {
+ code: {
+ approvalMode: resolveSubmittedCodeApprovalMode({
+ requested: latestApprovalMode,
+ modes: codeApprovalModes,
+ fallback: fallbackCodeApprovalMode,
+ codeEnvironmentMode,
+ }),
+ latestApprovalMode,
+ environmentMode: codeEnvironmentMode,
+ workspaces: codeWorkspaces,
+ },
+ apply: (current) => withSubmittedCodeDecision(current, workspaceSubmission),
+ };
+ },
+ resolveReasoning: ({ endpoint, conversation, endpointsConfig, reasoningOverride }) => {
+ const resolved = resolveSubmittedReasoning({
+ queryClient,
+ agentsMap,
+ endpoint,
+ conversation,
+ endpointsConfig,
+ reasoningOverride,
+ drainedReasoning: true,
+ stagedReasoning: reasoningOverride,
+ });
+ return { reasoningOverride: resolved.reasoningOverride, retryable: resolved.restoreStaged };
+ },
+ openNewChat: (path) => {
+ requestChatFocus();
+ navigate(path);
+ },
+ releaseFiles: (fileIds) => markPasteSubmitted(...fileIds),
+ clearFilesToDelete: () => setFilesToDelete({}),
+ bindResponse: (conversationKey, responseMessageId) =>
+ store.set(activeUsageResponseIdFamily(conversationKey), responseMessageId),
+ focusResponse,
+ bindLaunch: bindComposerLaunch,
+ };
+}
diff --git a/client/src/hooks/Chat/useChatFunctions.ts b/client/src/hooks/Chat/useChatFunctions.ts
index f274518df9..afdc15db02 100644
--- a/client/src/hooks/Chat/useChatFunctions.ts
+++ b/client/src/hooks/Chat/useChatFunctions.ts
@@ -1,59 +1,6 @@
-import { useCallback, useEffect, useRef } from 'react';
-import cloneDeep from 'lodash/cloneDeep';
-import { useStore, useSetAtom } from 'jotai';
-import { useNavigate } from 'react-router-dom';
-import { useQueryClient } from '@tanstack/react-query';
-import { buildTurn, createRegenerate, hasPendingAssistantParent } from '@librechat/chat';
-import {
- Constants,
- QueryKeys,
- EModelEndpoint,
- isAssistantsEndpoint,
-} from 'librechat-data-provider';
-import {
- isSubmittingFamily,
- submissionStartFamily,
- showStopButtonByIndex,
- revealedQueuedTurnFamily,
-} from '@librechat/chat/react';
-import {
- getReasoningStateKey,
- pendingQuotesByConvoId,
- pendingManualSkillsByConvoId,
- pendingReasoningOverrideFamily,
-} from '@librechat/chat/react';
-import type {
- TMessage,
- TSubmission,
- TConversation,
- TEndpointsConfig,
-} from 'librechat-data-provider';
-import type { Dispatch, SetStateAction } from 'react';
-import type { TAskFunction, ExtendedFile } from '~/common';
-import {
- logger,
- requestChatFocus,
- markPasteSubmitted,
- isSubmittableMessage,
- bindComposerLaunch,
- getRouteChatProjectId,
-} from '~/utils';
-import {
- withSubmittedCodeDecision,
- resolveSubmittedCodeApprovalMode,
-} from '~/hooks/Agents/codeDecision';
-import { activeUsageResponseIdFamily } from '~/components/Chat/Input/TokenUsage/store';
-import useFocusRegeneratedResponse from '~/hooks/Chat/useFocusRegeneratedResponse';
-import useGetConversation from '~/hooks/Conversations/useGetConversation';
-import useCodeApprovalMode from '~/hooks/Agents/useCodeApprovalMode';
-import useSetFilesToDelete from '~/hooks/Files/useSetFilesToDelete';
-import { useAgentsMapContext } from '~/Providers/AgentsMapContext';
-import { useChatSettings } from '~/Providers/ChatSettingsContext';
-import useCodeWorkspace from '~/hooks/Agents/useCodeWorkspace';
-import useGetSender from '~/hooks/Conversations/useGetSender';
-import { resolveSubmittedReasoning } from './ask/reasoning';
-import { isHistoryRevalidating } from './ask/guards';
-import useUserKey from '~/hooks/Input/useUserKey';
+import { useTurns } from '@librechat/chat/react';
+import type { ChatTurnsParams } from '@librechat/chat/react';
+import useTurnServices from './services';
export {
getRegenerateTargetResponseMessage,
@@ -61,427 +8,11 @@ export {
getPreliminaryRegenerateResponseMessageId,
} from '@librechat/chat';
+/** The package's `useTurns` over the app's services: what `useChatHelpers` runs for a pane. */
export default function useChatFunctions({
index = 0,
- files,
- setFiles,
- getMessages,
- setMessages,
- isSubmitting,
- latestMessage,
- setSubmission,
- setConversation,
- conversation: immutableConversation,
-}: {
- index?: number;
- isSubmitting: boolean;
- paramId?: string | undefined;
- conversation: TConversation | null;
- latestMessage: TMessage | null;
- getMessages: (conversationId?: string | null) => TMessage[] | undefined;
- setMessages: (messages: TMessage[]) => void;
- files?: Map<string, ExtendedFile>;
- setFiles?: Dispatch<SetStateAction<Map<string, ExtendedFile>>>;
- setSubmission: Dispatch<SetStateAction<TSubmission | null>>;
- /** Supplied by the host that owns the conversation atom, so a send records the decision it
- * established without this hook becoming a second writer of that state. */
- setConversation: Dispatch<SetStateAction<TConversation | null>>;
-}) {
- const navigate = useNavigate();
- const reasoningStore = useStore();
- const getSender = useGetSender();
- const queryClient = useQueryClient();
- const setFilesToDelete = useSetFilesToDelete();
- const agentsMap = useAgentsMapContext();
- const { isTemporary, config, auth, getEphemeralAgent, addedConversation } = useChatSettings();
- const { getExpiry } = useUserKey(immutableConversation?.endpoint ?? '');
- const setIsSubmitting = useSetAtom(isSubmittingFamily(index));
- const setSubmissionStart = useSetAtom(submissionStartFamily(index));
- const setShowStopButton = useSetAtom(showStopButtonByIndex(index));
- const focusRegeneratedResponse = useFocusRegeneratedResponse();
- const jotaiStore = useStore();
- const getConversation = useGetConversation(index);
- const codeWorkspaceState = useCodeWorkspace(immutableConversation, addedConversation);
- const { modes: codeApprovalModes, selected: fallbackCodeApprovalMode } = useCodeApprovalMode(
- immutableConversation,
- addedConversation,
- codeWorkspaceState.mode,
- );
-
- /**
- * `ask` refuses while `isSubmitting`, but that Recoil value only reads true
- * from the next commit onwards: a double Enter or a double click inside one
- * browser task would both pass that check and start two generations. This
- * ref closes the gap synchronously, matching the queue send lock shared by
- * `useSteering` and `useQueueDrain`.
- *
- * Released on every commit that is not submitting rather than only on a
- * `true -> false` transition: a start that never flips `isSubmitting` here
- * (Assistants set it from the SSE handler, and a start that fails outright
- * never sets it at all) would otherwise latch the composer shut for good.
- */
- const askInFlightRef = useRef(false);
- useEffect(() => {
- if (!isSubmitting) {
- askInFlightRef.current = false;
- }
- });
-
- /**
- * Atomically read + reset the per-conversation queue of manually-invoked
- * skills from the `$` popover. Reading and resetting in one synchronous
- * store pass guarantees that if the user selects more skills between here and
- * the next submission, their picks are never silently lost into a reset atom.
- *
- * The `hasValue` guard is defensive: this atom has a synchronous default of
- * `[]` so `.contents` is always the resolved value in practice, but reading
- * `.contents` on a loading/errored loadable yields a Promise/Error, which
- * would make the `string[]` cast unsound.
- */
- const drainPendingManualSkills = useCallback(
- (convoId: string): string[] => {
- const skills = jotaiStore.get(pendingManualSkillsByConvoId(convoId));
- if (skills.length > 0) {
- jotaiStore.set(pendingManualSkillsByConvoId(convoId), []);
- }
- return skills;
- },
- [jotaiStore],
- );
-
- /**
- * Atomically read + reset the per-conversation queue of quoted excerpts the
- * user added via the "Add to chat" selection popup. Mirrors
- * `drainPendingManualSkills`: a single snapshot read + reset so excerpts
- * added between here and submission are never lost into a reset atom.
- */
- const drainPendingQuotes = useCallback(
- (convoId: string): string[] => {
- const quotes = jotaiStore.get(pendingQuotesByConvoId(convoId));
- if (quotes.length > 0) {
- jotaiStore.set(pendingQuotesByConvoId(convoId), []);
- }
- return quotes;
- },
- [jotaiStore],
- );
-
- const drainPendingReasoning = useCallback(
- (stateKey: string): TMessage['reasoningOverride'] => {
- const reasoningAtom = pendingReasoningOverrideFamily(stateKey);
- const reasoningOverride = reasoningStore.get(reasoningAtom);
- if (reasoningOverride != null) {
- reasoningStore.set(reasoningAtom, undefined);
- }
- return reasoningOverride;
- },
- [reasoningStore],
- );
-
- const ask: TAskFunction = (
- {
- text,
- overrideConvoId,
- overrideUserMessageId,
- parentMessageId = null,
- conversationId = null,
- messageId = null,
- },
- {
- editedContent = null,
- editedMessageId = null,
- isRegenerate = false,
- isContinued = false,
- isEdited = false,
- compact = false,
- overrideMessages,
- overrideFiles,
- targetResponseMessageId,
- overrideManualSkills,
- overrideQuotes,
- overrideReasoning,
- addedConvo,
- overrideClientRequestId,
- overrideRecoverySteerId,
- overrideExpectedPredecessorCreatedAt,
- overrideQueuedMessageOrigin,
- } = {},
- ) => {
- text = text.trim();
- /**
- * Attached files make an otherwise empty draft submittable, e.g. replying
- * to an agent that asked for a document upload. When a caller supplies
- * `overrideFiles`, that array is authoritative, even when empty. A text-only
- * App action must not become submittable just because the user has staged
- * a file for a different, unsent composer message.
- */
- const availableFileCount = overrideFiles == null ? (files?.size ?? 0) : overrideFiles.length;
- /** A compaction sends no text: it replays the branch, like a regenerate,
- * with the response placeholder parented onto the leaf. */
- const regenerateShaped = isRegenerate || compact;
- if (
- askInFlightRef.current ||
- !!isSubmitting ||
- jotaiStore.get(revealedQueuedTurnFamily(immutableConversation?.conversationId ?? '')) !=
- null ||
- (!regenerateShaped && !isSubmittableMessage(text, availableFileCount))
- ) {
- return false;
- }
-
- const conversation = cloneDeep(immutableConversation);
- const latestCodeApprovalMode = getConversation()?.codeApprovalMode;
- const latestCodeWorkspaces = getConversation()?.codeWorkspaces ?? conversation?.codeWorkspaces;
- const latestCodeEnvironmentMode =
- getConversation()?.codeEnvironmentMode ?? conversation?.codeEnvironmentMode;
- const workspaceSubmission = codeWorkspaceState.resolveSubmission(
- latestCodeWorkspaces,
- latestCodeEnvironmentMode,
- );
- if (workspaceSubmission == null) {
- logger.warn('[useChatFunctions] Refusing to send without an available code workspace');
- return false;
- }
- const { codeEnvironmentMode, codeWorkspaces } = workspaceSubmission;
- const codeApprovalMode = resolveSubmittedCodeApprovalMode({
- requested: latestCodeApprovalMode,
- modes: codeApprovalModes,
- fallback: fallbackCodeApprovalMode,
- codeEnvironmentMode,
- });
-
- const endpoint = conversation?.endpoint;
- if (endpoint === null) {
- console.error('No endpoint available');
- return false;
- }
-
- conversationId = conversationId ?? conversation?.conversationId ?? null;
- if (conversationId == 'search') {
- console.error('cannot send any message under search view!');
- return false;
- }
-
- const cachedMessages = getMessages(conversationId);
- const isExistingConversation = conversationId != null && conversationId !== Constants.NEW_CONVO;
- if (isExistingConversation && overrideMessages == null && cachedMessages == null) {
- logger.warn('[useChatFunctions] Refusing to send before existing conversation history loads');
- return false;
- }
-
- /**
- * Warm-switch revalidation guard: a navigation invalidates the target's
- * cache and renders it while a background refetch reconciles. Deriving
- * parentMessageId from that cache could fork from an outdated tail, so
- * refuse (composer keeps the text) until the refetch settles, but only
- * when the cache is actually old: a just-streamed cache (fresh
- * `dataUpdatedAt`) is locally authoritative, and gating it would block
- * rapid follow-ups during the post-run reconcile.
- */
- if (isExistingConversation && overrideMessages == null) {
- const isStale = isHistoryRevalidating(queryClient, conversationId);
- if (isStale) {
- logger.warn('[useChatFunctions] Refusing to send while conversation history revalidates');
- return false;
- }
- }
-
- if (isContinued && !latestMessage) {
- console.error('cannot continue AI message without latestMessage!');
- return false;
- }
-
- if (parentMessageId == null && hasPendingAssistantParent(latestMessage)) {
- logger.warn(
- '[useChatFunctions] Refusing to append to a preliminary assistant message',
- latestMessage,
- );
- return false;
- }
-
- setShowStopButton(false);
-
- const ephemeralAgent = getEphemeralAgent(conversationId ?? Constants.NEW_CONVO);
- const endpointsConfig = queryClient.getQueryData<TEndpointsConfig>([QueryKeys.endpoints]);
- /**
- * Manual skill selection resolution:
- * - Explicit `overrideManualSkills` wins (regenerate / save-and-submit
- * pass the original user message's persisted `manualSkills` so the
- * resubmitted turn primes the same skills: the pills are still
- * visible to the user, it would be strange to quietly drop them).
- * - Regenerate / continue / edit without an override → empty, and the
- * compose-time atom is deliberately NOT drained (those flows replay
- * a prior turn, not compose a new one).
- * - Fresh submit → drain the per-convo atom into the message.
- */
- let manualSkills = overrideManualSkills;
- if (manualSkills == null) {
- manualSkills =
- regenerateShaped || isContinued || isEdited
- ? []
- : drainPendingManualSkills(conversationId ?? Constants.NEW_CONVO);
- }
- /**
- * Quoted-excerpt resolution mirrors manual skills, but is skipped entirely
- * for Assistants endpoints: those bypass the `BaseClient` merge, so the
- * quote UI is hidden there and a selection queued on another endpoint must
- * not silently ride along on a fresh submit. The pending atom is left
- * untouched so the queue survives if the user switches back.
- * - Explicit `overrideQuotes` wins (regenerate / resubmit replay the
- * original user message's persisted quotes so the same context is sent).
- * - Regenerate / continue / edit without an override → empty (those flows
- * replay a prior turn; the compose-time atom is left untouched).
- * - Fresh submit → drain the per-convo atom into the message.
- */
- const quotesSupported = !isAssistantsEndpoint(endpoint);
- let quotes: string[] = [];
- if (quotesSupported) {
- if (overrideQuotes != null) {
- quotes = overrideQuotes;
- } else if (!regenerateShaped && !isContinued && !isEdited) {
- quotes = drainPendingQuotes(conversationId ?? Constants.NEW_CONVO);
- }
- }
- let reasoningOverride = overrideReasoning ?? undefined;
- const reasoningStateKey = getReasoningStateKey(conversationId, index);
- const drainedReasoning =
- overrideReasoning === undefined && !regenerateShaped && !isContinued && !isEdited;
- if (drainedReasoning) {
- reasoningOverride = drainPendingReasoning(reasoningStateKey);
- }
- const stagedReasoning = reasoningOverride;
- if (reasoningOverride != null) {
- const resolved = resolveSubmittedReasoning({
- queryClient,
- agentsMap,
- endpoint,
- conversation,
- endpointsConfig,
- reasoningOverride,
- drainedReasoning,
- stagedReasoning,
- });
- reasoningOverride = resolved.reasoningOverride;
- if (resolved.restoreStaged && stagedReasoning != null) {
- reasoningStore.set(pendingReasoningOverrideFamily(reasoningStateKey), stagedReasoning);
- }
- }
-
- const turn = buildTurn({
- text,
- params: { text, overrideConvoId, overrideUserMessageId, parentMessageId, messageId },
- options: {
- editedContent: editedContent ?? undefined,
- editedMessageId,
- isRegenerate,
- isContinued,
- isEdited,
- compact,
- overrideMessages,
- overrideFiles,
- targetResponseMessageId,
- addedConvo,
- overrideClientRequestId,
- overrideRecoverySteerId,
- overrideExpectedPredecessorCreatedAt,
- overrideQueuedMessageOrigin,
- },
- conversationId,
- conversation,
- latestMessage,
- cachedMessages,
- files,
- canClearFiles: setFiles != null,
- routeProjectId: getRouteChatProjectId(),
- endpointsConfig,
- modelSpecs: config.modelSpecs,
- user: auth.user,
- isTemporary,
- ephemeralAgent,
- getSender,
- userKey: endpoint !== EModelEndpoint.agents ? getExpiry() : undefined,
- manualSkills,
- quotes,
- reasoningOverride,
- code: {
- approvalMode: codeApprovalMode,
- latestApprovalMode: latestCodeApprovalMode,
- environmentMode: codeEnvironmentMode,
- workspaces: codeWorkspaces,
- },
- });
- const {
- submission,
- currentMsg,
- initialResponse,
- submissionMessages,
- regenerateShaped: isRegenerateShaped,
- isEditOrContinue,
- newChatPath,
- fileEffects,
- } = turn;
- conversationId = turn.conversationId;
- logger.log('message_state', initialResponse);
-
- if (newChatPath != null) {
- requestChatFocus();
- navigate(newChatPath);
- }
- if (fileEffects != null && setFiles) {
- markPasteSubmitted(...fileEffects.submittedFileIds);
- if (fileEffects.clearComposer) {
- setFiles(new Map());
- setFilesToDelete({});
- }
- }
- if (turn.startsSubmitting) {
- setIsSubmitting(true);
- setShowStopButton(true);
- }
-
- /** Bind before publishing the optimistic tail, not after the first provider
- * event: a waiting request already owns a turn even when no usage exists. */
- jotaiStore.set(
- activeUsageResponseIdFamily(conversationId ?? Constants.NEW_CONVO),
- initialResponse.messageId,
- );
-
- if (isRegenerateShaped) {
- setMessages([...submissionMessages, initialResponse]);
- focusRegeneratedResponse(initialResponse.parentMessageId);
- } else {
- setMessages([...submissionMessages, currentMsg, initialResponse]);
- }
-
- /** Carry the submitted choice through the first saved-chat event instead of re-deriving it
- * from agent defaults. This is optimistic: the SSE error path reconciles an existing chat
- * with its authoritative server decision if admission fails. */
- setConversation((current) =>
- current == null || current.conversationId !== conversation?.conversationId
- ? current
- : withSubmittedCodeDecision(current, workspaceSubmission),
- );
- /** Armed at the point of no return: every refusal above returns before it,
- * so a rejected send never has to unwind the guard, and `ask` runs to
- * completion synchronously, which is the whole window it has to cover. */
- askInFlightRef.current = true;
- setSubmissionStart(Date.now());
- bindComposerLaunch(submission.conversation, index);
- setSubmission(submission);
- logger.dir('message_stream', {
- conversationId,
- messageId: currentMsg.messageId,
- parentMessageId: currentMsg.parentMessageId,
- isEdited: isEditOrContinue,
- isRegenerate: isRegenerateShaped,
- isContinued,
- });
- };
-
- const regenerate = createRegenerate(ask, getMessages);
-
- return {
- ask,
- regenerate,
- };
+ ...params
+}: Omit<ChatTurnsParams, 'index'> & { index?: number }) {
+ const turnsParams = { index, ...params };
+ return useTurns(turnsParams, useTurnServices(turnsParams));
}
diff --git a/client/src/utils/messages.ts b/client/src/utils/messages.ts
index e929b96406..96d498fc59 100644
--- a/client/src/utils/messages.ts
+++ b/client/src/utils/messages.ts
@@ -350,13 +350,7 @@ export const preserveStreamedContentIdentity = (
export const getPartKeyIndex = (part: TMessageContentParts | undefined, idx: number): number =>
part?.streamedIndex ?? idx;
-/**
- * Whether a draft message has enough content to submit: non-whitespace
- * text, or at least one attached file. Lets users send a file without
- * having to type a placeholder message alongside it.
- */
-export const isSubmittableMessage = (text?: string | null, fileCount = 0): boolean =>
- (text ?? '').trim() !== '' || fileCount > 0;
+export { isSubmittableMessage } from '@librechat/chat';
export const markStreamStartFailedMetadata = (
metadata?: TMessage['metadata'],
diff --git a/client/test/turnServices.ts b/client/test/turnServices.ts
new file mode 100644
index 0000000000..93da3f75de
--- /dev/null
+++ b/client/test/turnServices.ts
@@ -0,0 +1,22 @@
+import type { TurnServices } from '@librechat/chat/react';
+
+/** Turn services with no app behind them, for specs that mock `~/hooks/Chat/services` because
+ * they exercise the chat hooks without a router, query client or agent settings. */
+export const createTestTurnServices = (): TurnServices => ({
+ logger: { log: jest.fn(), dir: jest.fn(), warn: jest.fn() },
+ isTemporary: false,
+ getEndpointsConfig: () => undefined,
+ getEphemeralAgent: () => null,
+ getSender: () => 'Assistant',
+ getUserKey: () => undefined,
+ getRouteProjectId: () => null,
+ isHistoryRevalidating: () => false,
+ resolveCode: () => null,
+ resolveReasoning: () => ({ reasoningOverride: undefined, retryable: false }),
+ openNewChat: jest.fn(),
+ releaseFiles: jest.fn(),
+ clearFilesToDelete: jest.fn(),
+ bindResponse: jest.fn(),
+ focusResponse: jest.fn(),
+ bindLaunch: jest.fn(),
+});
diff --git a/packages/chat/src/core/turns/draft.ts b/packages/chat/src/core/turns/draft.ts
new file mode 100644
index 0000000000..3f01a2b02f
--- /dev/null
+++ b/packages/chat/src/core/turns/draft.ts
@@ -0,0 +1,6 @@
+/**
+ * Whether a draft message has enough content to submit: non-whitespace text, or at least one
+ * attached file. Lets users send a file without typing a placeholder message alongside it.
+ */
+export const isSubmittableMessage = (text?: string | null, fileCount = 0): boolean =>
+ (text ?? '').trim() !== '' || fileCount > 0;
diff --git a/packages/chat/src/core/turns/index.ts b/packages/chat/src/core/turns/index.ts
index 2b5e1cf2d3..96baf5c4b9 100644
--- a/packages/chat/src/core/turns/index.ts
+++ b/packages/chat/src/core/turns/index.ts
@@ -1,3 +1,4 @@
export * from './types';
export * from './build';
+export * from './draft';
export * from './regenerate';
diff --git a/packages/chat/src/react/chat/__fixtures__/services.ts b/packages/chat/src/react/chat/__fixtures__/services.ts
new file mode 100644
index 0000000000..bdd94cc09d
--- /dev/null
+++ b/packages/chat/src/react/chat/__fixtures__/services.ts
@@ -0,0 +1,25 @@
+import type { TurnServices } from '../host';
+
+/** Turn services with no app behind them: agents-only, no catalogs, and every effect a spy. */
+export const createTurnServices = (overrides: Partial<TurnServices> = {}): TurnServices => ({
+ logger: { log: jest.fn(), dir: jest.fn(), warn: jest.fn() },
+ isTemporary: false,
+ getEndpointsConfig: () => undefined,
+ getEphemeralAgent: () => null,
+ getSender: () => 'Assistant',
+ getUserKey: () => undefined,
+ getRouteProjectId: () => null,
+ isHistoryRevalidating: () => false,
+ resolveCode: () => ({
+ code: { approvalMode: undefined, environmentMode: undefined, workspaces: undefined },
+ apply: (conversation) => conversation,
+ }),
+ resolveReasoning: ({ reasoningOverride }) => ({ reasoningOverride, retryable: false }),
+ openNewChat: jest.fn(),
+ releaseFiles: jest.fn(),
+ clearFilesToDelete: jest.fn(),
+ bindResponse: jest.fn(),
+ focusResponse: jest.fn(),
+ bindLaunch: jest.fn(),
+ ...overrides,
+});
diff --git a/packages/chat/src/react/chat/__tests__/stop.spec.tsx b/packages/chat/src/react/chat/__tests__/stop.spec.tsx
index 346c85fa65..d0b3ca2c10 100644
--- a/packages/chat/src/react/chat/__tests__/stop.spec.tsx
+++ b/packages/chat/src/react/chat/__tests__/stop.spec.tsx
@@ -20,6 +20,7 @@ import {
drainAfterAbortByIndex,
} from '../../steer/queue';
import { submissionByIndex, clearSubmissions } from '../../submission';
+import { createTurnServices } from '../__fixtures__/services';
import { ChatHostProvider } from '../host';
import { useAbortCleanup } from '../abort';
import useChatHelpers from '../helpers';
@@ -34,7 +35,7 @@ jest.mock('../../steering/useSteerConvert', () => ({
const noop = () => undefined;
const noLiveAttachments = {};
-const turns = { ask: jest.fn(), regenerate: jest.fn() };
+const turnServices = createTurnServices();
const cache: ChatMessageCache = {
read: () => undefined,
write: noop,
@@ -49,7 +50,7 @@ const cache: ChatMessageCache = {
const createHost = (conversation: TConversation | null): ChatHost => ({
usePaneConversation: () => ({ conversation, setConversation: noop }),
useNewConversation: () => noop,
- useTurns: () => turns,
+ useTurnServices: () => turnServices,
useLatestMessage: () => null,
useLatestMessageId: () => null,
useSetSiblingIdx: () => noop,
diff --git a/packages/chat/src/react/chat/__tests__/turns.spec.tsx b/packages/chat/src/react/chat/__tests__/turns.spec.tsx
new file mode 100644
index 0000000000..b086673c8c
--- /dev/null
+++ b/packages/chat/src/react/chat/__tests__/turns.spec.tsx
@@ -0,0 +1,276 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react';
+import { createStore, Provider } from 'jotai';
+import { renderHook } from '@testing-library/react';
+import { Constants, EModelEndpoint } from 'librechat-data-provider';
+import type { TMessage, TSubmission, TConversation } from 'librechat-data-provider';
+import type { ChatTurnsParams, TurnServices } from '../host';
+import type { ExtendedFile } from '../../../core';
+import {
+ getReasoningStateKey,
+ pendingQuotesByConvoId,
+ pendingManualSkillsByConvoId,
+ pendingReasoningOverrideFamily,
+} from '../../composer';
+import { createTurnServices } from '../__fixtures__/services';
+import { isSubmittingFamily } from '../../submission';
+import { useTurns } from '../turns';
+
+const conversationId = 'conversation-1';
+
+const user: TMessage = {
+ messageId: 'user-1',
+ parentMessageId: Constants.NO_PARENT as string,
+ conversationId,
+ text: 'Hello',
+ sender: 'User',
+ isCreatedByUser: true,
+ manualSkills: ['skill-a'],
+ quotes: ['quote-a'],
+};
+
+const response: TMessage = {
+ messageId: 'response-1',
+ parentMessageId: 'user-1',
+ conversationId,
+ text: 'Hi',
+ sender: 'Assistant',
+ isCreatedByUser: false,
+ createdAt: '2026-10-28T00:00:00.000Z',
+};
+
+const agentsConversation: TConversation = {
+ conversationId,
+ endpoint: EModelEndpoint.agents,
+ agent_id: 'agent-1',
+ title: null,
+ createdAt: '2026-10-28T00:00:00.000Z',
+ updatedAt: '2026-10-28T00:00:00.000Z',
+};
+
+const reasoning = { key: 'reasoning_effort', value: 'high' } as NonNullable<
+ TMessage['reasoningOverride']
+>;
+
+function setup({
+ conversation = agentsConversation,
+ messages = [user, response] as TMessage[] | null,
+ latestMessage = response,
+ files = new Map<string, ExtendedFile>(),
+ services = createTurnServices(),
+ isSubmitting = false,
+}: {
+ conversation?: TConversation | null;
+ /** `null` stands for history that has not loaded. */
+ messages?: TMessage[] | null;
+ latestMessage?: TMessage | null;
+ files?: Map<string, ExtendedFile>;
+ services?: TurnServices;
+ isSubmitting?: boolean;
+} = {}) {
+ const store = createStore();
+ let submission: TSubmission | null = null;
+ let current = conversation;
+ const written: TMessage[][] = [];
+ const params: ChatTurnsParams = {
+ index: 0,
+ files,
+ setFiles: jest.fn(),
+ getMessages: () => messages ?? undefined,
+ setMessages: (next) => written.push(next),
+ isSubmitting,
+ conversation,
+ latestMessage,
+ setSubmission: (next) => {
+ submission = typeof next === 'function' ? next(submission) : next;
+ },
+ setConversation: (next) => {
+ current = typeof next === 'function' ? next(current) : next;
+ },
+ };
+ const { result } = renderHook(() => useTurns(params, services), {
+ wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
+ });
+ return {
+ store,
+ params,
+ services,
+ written,
+ turns: result.current,
+ submission: () => submission,
+ conversation: () => current,
+ };
+}
+
+describe('useTurns', () => {
+ it('publishes the turn and marks the pane submitting', () => {
+ const chat = setup();
+
+ expect(chat.turns.ask({ text: ' Next ' })).toBeUndefined();
+
+ const submission = chat.submission();
+ expect(submission?.userMessage).toMatchObject({ text: 'Next', parentMessageId: 'response-1' });
+ expect(chat.written).toHaveLength(1);
+ expect(chat.written[0].map((message) => message.messageId)).toEqual([
+ 'user-1',
+ 'response-1',
+ submission?.userMessage.messageId,
+ submission?.initialResponse?.messageId,
+ ]);
+ expect(chat.store.get(isSubmittingFamily(0))).toBe(true);
+ expect(chat.services.bindResponse).toHaveBeenCalledWith(
+ conversationId,
+ submission?.initialResponse?.messageId,
+ );
+ expect(chat.services.bindLaunch).toHaveBeenCalledWith(submission?.conversation, 0);
+ });
+
+ it('refuses a second send inside the same task', () => {
+ const chat = setup();
+
+ chat.turns.ask({ text: 'first' });
+
+ expect(chat.turns.ask({ text: 'second' })).toBe(false);
+ expect(chat.written).toHaveLength(1);
+ });
+
+ it.each<[string, Parameters<typeof setup>[0]]>([
+ ['while submitting', { isSubmitting: true }],
+ ['before the history loads', { messages: null }],
+ [
+ 'while the history revalidates',
+ { services: createTurnServices({ isHistoryRevalidating: () => true }) },
+ ],
+ ['without a code workspace', { services: createTurnServices({ resolveCode: () => null }) }],
+ [
+ 'onto a preliminary response',
+ { latestMessage: { ...response, messageId: 'pending_', createdAt: undefined } },
+ ],
+ ])('refuses to send %s', (_label, options) => {
+ const chat = setup(options);
+
+ expect(chat.turns.ask({ text: 'Next' })).toBe(false);
+ expect(chat.submission()).toBeNull();
+ expect(chat.written).toHaveLength(0);
+ });
+
+ it('refuses an empty draft but sends attached files alone', () => {
+ const files = new Map<string, ExtendedFile>([
+ ['temp-1', { file_id: 'file-1', temp_file_id: 'temp-1', progress: 1, size: 1 }],
+ ]);
+ expect(setup().turns.ask({ text: ' ' })).toBe(false);
+
+ const chat = setup({ files });
+ chat.turns.ask({ text: '' });
+
+ expect(chat.submission()?.userMessage.files).toEqual([
+ expect.objectContaining({ file_id: 'file-1' }),
+ ]);
+ expect(chat.services.releaseFiles).toHaveBeenCalledWith(['temp-1', 'file-1', 'temp-1']);
+ expect(chat.params.setFiles).toHaveBeenCalledWith(new Map());
+ expect(chat.services.clearFilesToDelete).toHaveBeenCalled();
+ });
+
+ it('drains queued skills, quotes and reasoning into a fresh send', () => {
+ const chat = setup();
+ const reasoningKey = getReasoningStateKey(conversationId, 0);
+ chat.store.set(pendingManualSkillsByConvoId(conversationId), ['skill-b']);
+ chat.store.set(pendingQuotesByConvoId(conversationId), ['quote-b']);
+ chat.store.set(pendingReasoningOverrideFamily(reasoningKey), reasoning);
+
+ chat.turns.ask({ text: 'Next' });
+
+ expect(chat.submission()?.userMessage).toMatchObject({
+ manualSkills: ['skill-b'],
+ quotes: ['quote-b'],
+ reasoningOverride: reasoning,
+ });
+ expect(chat.store.get(pendingManualSkillsByConvoId(conversationId))).toEqual([]);
+ expect(chat.store.get(pendingQuotesByConvoId(conversationId))).toEqual([]);
+ expect(chat.store.get(pendingReasoningOverrideFamily(reasoningKey))).toBeUndefined();
+ });
+
+ it('puts a drained reasoning choice back when the capabilities are not known yet', () => {
+ const chat = setup({
+ services: createTurnServices({
+ resolveReasoning: () => ({ reasoningOverride: undefined, retryable: true }),
+ }),
+ });
+ const reasoningKey = getReasoningStateKey(conversationId, 0);
+ chat.store.set(pendingReasoningOverrideFamily(reasoningKey), reasoning);
+
+ chat.turns.ask({ text: 'Next' });
+
+ expect(chat.submission()?.userMessage.reasoningOverride).toBeUndefined();
+ expect(chat.store.get(pendingReasoningOverrideFamily(reasoningKey))).toEqual(reasoning);
+ });
+
+ it('keeps queued quotes out of an Assistants send', () => {
+ const chat = setup({
+ conversation: {
+ ...agentsConversation,
+ endpoint: EModelEndpoint.assistants,
+ assistant_id: 'a',
+ },
+ });
+ chat.store.set(pendingQuotesByConvoId(conversationId), ['quote-b']);
+
+ chat.turns.ask({ text: 'Next' });
+
+ expect(chat.submission()?.userMessage.quotes).toBeUndefined();
+ expect(chat.store.get(pendingQuotesByConvoId(conversationId))).toEqual(['quote-b']);
+ expect(chat.store.get(isSubmittingFamily(0))).toBe(false);
+ });
+
+ it('opens the new-chat route for a send that starts a chat', () => {
+ const conversation = { ...agentsConversation, conversationId: Constants.NEW_CONVO as string };
+ const chat = setup({
+ conversation,
+ messages: [],
+ latestMessage: null,
+ services: createTurnServices({ getRouteProjectId: () => 'a'.repeat(24) }),
+ });
+
+ chat.turns.ask({ text: 'Hello' });
+
+ expect(chat.services.openNewChat).toHaveBeenCalledWith(`/c/new?projectId=${'a'.repeat(24)}`);
+ expect(chat.submission()?.conversation.chatProjectId).toBe('a'.repeat(24));
+ });
+
+ it('records the submitted code decision on the pane conversation', () => {
+ const chat = setup({
+ services: createTurnServices({
+ resolveCode: () => ({
+ code: { approvalMode: undefined, environmentMode: undefined, workspaces: undefined },
+ apply: (conversation) => ({ ...conversation, title: 'decided' }),
+ }),
+ }),
+ });
+
+ chat.turns.ask({ text: 'Next' });
+
+ expect(chat.conversation()?.title).toBe('decided');
+ });
+
+ it('regenerates a response with the replayed user message and focuses it', () => {
+ const chat = setup();
+ chat.store.set(pendingManualSkillsByConvoId(conversationId), ['queued']);
+
+ chat.turns.regenerate(response);
+
+ expect(chat.submission()).toMatchObject({
+ isRegenerate: true,
+ userMessage: {
+ text: 'Hello',
+ overrideParentMessageId: 'user-1',
+ manualSkills: ['skill-a'],
+ quotes: ['quote-a'],
+ },
+ });
+ expect(chat.written[0].map((message) => message.messageId)).toEqual(['user-1', 'response-1_']);
+ expect(chat.services.focusResponse).toHaveBeenCalledWith('user-1');
+ expect(chat.store.get(pendingManualSkillsByConvoId(conversationId))).toEqual(['queued']);
+ });
+});
diff --git a/packages/chat/src/react/chat/helpers.ts b/packages/chat/src/react/chat/helpers.ts
index 94a47b7c61..7f70c72113 100644
--- a/packages/chat/src/react/chat/helpers.ts
+++ b/packages/chat/src/react/chat/helpers.ts
@@ -9,6 +9,7 @@ import { abortScrollFamily } from '../generation';
import { getMessageCacheIds } from './cache';
import { useStopGenerating } from './stop';
import { useChatHost } from './host';
+import { useTurns } from './turns';
/**
* Builds a pane's chat contract from the app the host supplies: its pane store, message cache,
@@ -67,7 +68,7 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
const setSubmission = useSetAtom(submissionByIndex(index));
- const { ask: _ask, regenerate: _regenerate } = host.useTurns({
+ const turnsParams = {
index,
files,
setFiles,
@@ -78,7 +79,11 @@ export default function useChatHelpers(index = 0, paramId?: string): ChatContrac
latestMessage,
setSubmission,
setConversation,
- });
+ };
+ const { ask: _ask, regenerate: _regenerate } = useTurns(
+ turnsParams,
+ host.useTurnServices(turnsParams),
+ );
const askRef = useRef(_ask);
askRef.current = _ask;
diff --git a/packages/chat/src/react/chat/host.tsx b/packages/chat/src/react/chat/host.tsx
index ba9c3f7afb..f6ccc496a4 100644
--- a/packages/chat/src/react/chat/host.tsx
+++ b/packages/chat/src/react/chat/host.tsx
@@ -1,15 +1,20 @@
import { createContext, useContext } from 'react';
import type {
+ TUser,
TMessage,
+ TModelSpec,
TSubmission,
TAttachment,
TConversation,
TPendingSteer,
+ TEndpointOption,
+ TEphemeralAgent,
+ TEndpointsConfig,
UIMappingOptions,
} from 'librechat-data-provider';
import type { Dispatch, ReactNode, SetStateAction } from 'react';
+import type { BuildTurnInput, ExtendedFile } from '../../core';
import type { ChatContract } from './contract';
-import type { ExtendedFile } from '../../core';
export interface AbortStreamParams {
/** The stream ID to abort (if known) */
@@ -38,11 +43,12 @@ export interface AbortStreamResponse {
pendingSteers?: TPendingSteer[];
}
-/** What the host's turn builder needs to submit and regenerate turns for one pane. */
+/** The pane state `ask` and `regenerate` read and write for one pane. */
export type ChatTurnsParams = {
index: number;
- files: Map<string, ExtendedFile>;
- setFiles: Dispatch<SetStateAction<Map<string, ExtendedFile>>>;
+ files?: Map<string, ExtendedFile>;
+ /** Without it a send leaves the composer's files alone. */
+ setFiles?: Dispatch<SetStateAction<Map<string, ExtendedFile>>>;
getMessages: ChatContract['getMessages'];
setMessages: ChatContract['setMessages'];
isSubmitting: boolean;
@@ -52,6 +58,66 @@ export type ChatTurnsParams = {
setConversation: Dispatch<SetStateAction<TConversation | null>>;
};
+/** The code workspace and approval a send carries, decided by the app's agent settings. */
+export type TurnCodeDecision = {
+ code: BuildTurnInput['code'];
+ /** Records the decision on the pane's conversation once the send is published. */
+ apply: (conversation: TConversation) => TConversation | null;
+};
+
+/** The app's logger; `warn` and `error` may reach the app's telemetry. */
+export type TurnLogger = {
+ log: (...args: unknown[]) => void;
+ dir: (...args: unknown[]) => void;
+ warn: (...args: unknown[]) => void;
+};
+
+/**
+ * What a pane's turns need from the app: its catalogs, routing, composer files, code workspace
+ * and logging. Getters are read when a turn is sent, so they see the app's current state.
+ */
+export type TurnServices = {
+ logger: TurnLogger;
+ isTemporary: boolean;
+ user?: TUser;
+ modelSpecs?: TModelSpec[];
+ getEndpointsConfig: () => TEndpointsConfig | undefined;
+ getEphemeralAgent: (conversationId: string) => TEphemeralAgent | null;
+ /** The response sender label for an endpoint option. */
+ getSender: (endpointOption: TEndpointOption) => string;
+ /** The stored user key expiry of the pane's endpoint, sent with non-agent endpoints. */
+ getUserKey: () => string | undefined;
+ /** The project the route scopes a new chat to. */
+ getRouteProjectId: () => string | null;
+ /** Whether cached history is mid-refetch and old enough that a send could fork from it. */
+ isHistoryRevalidating: (conversationId: string | null) => boolean;
+ /** The send's code decision; `null` refuses the send. */
+ resolveCode: (conversation: TConversation | null) => TurnCodeDecision | null;
+ /**
+ * Checks a request-scoped reasoning override against the endpoint's loaded capabilities. An
+ * unsupported one is dropped; `retryable` says it was refused only because the capabilities
+ * are not known yet.
+ */
+ resolveReasoning: (args: {
+ endpoint?: string | null;
+ conversation: TConversation | null;
+ endpointsConfig?: TEndpointsConfig;
+ reasoningOverride: NonNullable<TMessage['reasoningOverride']>;
+ }) => { reasoningOverride: TMessage['reasoningOverride']; retryable: boolean };
+ /** Moves the pane to the route a new chat starts from. */
+ openNewChat: (path: string) => void;
+ /** Marks composer files as submitted, so draft cleanup keeps them. */
+ releaseFiles: (fileIds: (string | undefined)[]) => void;
+ /** Forgets the files queued for deletion once the composer is cleared. */
+ clearFilesToDelete: () => void;
+ /** Binds the conversation's usage display to the response it is waiting on. */
+ bindResponse: (conversationKey: string, responseMessageId: string) => void;
+ /** Brings a regenerated response into view. */
+ focusResponse: (parentMessageId?: string | null) => void;
+ /** Ties the composer launch to the conversation the submission starts. */
+ bindLaunch: (conversation: TSubmission['conversation'], index: number) => void;
+};
+
/** The conversation a pane shows, and the setter that replaces or updates it. */
export type ChatPaneConversation = {
conversation: TConversation | null;
@@ -84,8 +150,8 @@ export interface ChatHost {
usePaneConversation(index: number): ChatPaneConversation;
/** Starts a fresh conversation in a pane. */
useNewConversation(index: number): ChatContract['newConversation'];
- /** Builds and submits turns: `ask` and `regenerate`. */
- useTurns(params: ChatTurnsParams): Pick<ChatContract, 'ask' | 'regenerate'>;
+ /** What the pane's turns need from the app; see {@link TurnServices}. */
+ useTurnServices(params: ChatTurnsParams): TurnServices;
/** The tail of the branch on screen for the pane, read from the messages cached under `key`. */
useLatestMessage(index: number, key: string): TMessage | null;
/** The id of {@link ChatHost.useLatestMessage}, subscribed on its own. */
diff --git a/packages/chat/src/react/chat/index.ts b/packages/chat/src/react/chat/index.ts
index ad0593b15d..0ca7984ec9 100644
--- a/packages/chat/src/react/chat/index.ts
+++ b/packages/chat/src/react/chat/index.ts
@@ -4,10 +4,14 @@ export { default as useChatHelpers } from './helpers';
export { useAbortCleanup } from './abort';
export { getMessageCacheIds, getMessagesConversationId } from './cache';
export { ChatHostProvider, useChatHost } from './host';
+export { useTurns } from './turns';
export type {
ChatHost,
+ TurnLogger,
+ TurnServices,
ChatTurnsParams,
ChatMessageCache,
+ TurnCodeDecision,
AbortStreamParams,
AbortStreamResponse,
ChatPaneConversation,
diff --git a/packages/chat/src/react/chat/turns.ts b/packages/chat/src/react/chat/turns.ts
new file mode 100644
index 0000000000..26688e4900
--- /dev/null
+++ b/packages/chat/src/react/chat/turns.ts
@@ -0,0 +1,336 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useStore, useSetAtom } from 'jotai';
+import { Constants, EModelEndpoint, isAssistantsEndpoint } from 'librechat-data-provider';
+import type { TMessage } from 'librechat-data-provider';
+import type { TAskFunction, TRegenerateFunction } from '../../core';
+import type { ChatTurnsParams, TurnServices } from './host';
+import {
+ getReasoningStateKey,
+ pendingQuotesByConvoId,
+ pendingManualSkillsByConvoId,
+ pendingReasoningOverrideFamily,
+} from '../composer';
+import {
+ buildTurn,
+ createRegenerate,
+ isSubmittableMessage,
+ hasPendingAssistantParent,
+} from '../../core';
+import { submissionStartFamily, showStopButtonByIndex } from '../generation';
+import { revealedQueuedTurnFamily } from '../steer/atoms';
+import { isSubmittingFamily } from '../submission';
+
+/**
+ * Submits and regenerates turns for one pane: refuses a send the chat cannot take yet, drains
+ * the composer's queued skills, quotes and reasoning, builds the turn and publishes it. The app
+ * supplies only what it owns through `services`: its endpoint and agent catalogs, routing,
+ * composer files, code workspace and logging.
+ */
+export function useTurns(
+ {
+ index,
+ files,
+ setFiles,
+ getMessages,
+ setMessages,
+ isSubmitting,
+ latestMessage,
+ setSubmission,
+ setConversation,
+ conversation: immutableConversation,
+ }: ChatTurnsParams,
+ services: TurnServices,
+): { ask: TAskFunction; regenerate: TRegenerateFunction } {
+ const store = useStore();
+ const setIsSubmitting = useSetAtom(isSubmittingFamily(index));
+ const setSubmissionStart = useSetAtom(submissionStartFamily(index));
+ const setShowStopButton = useSetAtom(showStopButtonByIndex(index));
+ const { logger } = services;
+
+ /**
+ * `ask` refuses while `isSubmitting`, but that value only reads true from the next commit
+ * onwards: a double Enter or a double click inside one browser task would both pass that
+ * check and start two generations. This ref closes the gap synchronously, matching the queue
+ * send lock shared by `useSteering` and `useQueueDrain`.
+ *
+ * Released on every commit that is not submitting rather than only on a `true -> false`
+ * transition: a start that never flips `isSubmitting` here (Assistants set it from the SSE
+ * handler, and a start that fails outright never sets it at all) would otherwise latch the
+ * composer shut for good.
+ */
+ const askInFlightRef = useRef(false);
+ useEffect(() => {
+ if (!isSubmitting) {
+ askInFlightRef.current = false;
+ }
+ });
+
+ /**
+ * Reads and resets one per-conversation composer queue (manual skills, quoted excerpts) in a
+ * single synchronous store pass, so an item queued between here and the submission is never
+ * lost into a reset atom.
+ */
+ const drain = useCallback(
+ (family: typeof pendingQuotesByConvoId, convoId: string): string[] => {
+ const items = store.get(family(convoId));
+ if (items.length > 0) {
+ store.set(family(convoId), []);
+ }
+ return items;
+ },
+ [store],
+ );
+
+ const drainPendingReasoning = useCallback(
+ (stateKey: string): TMessage['reasoningOverride'] => {
+ const reasoningAtom = pendingReasoningOverrideFamily(stateKey);
+ const reasoningOverride = store.get(reasoningAtom);
+ if (reasoningOverride != null) {
+ store.set(reasoningAtom, undefined);
+ }
+ return reasoningOverride;
+ },
+ [store],
+ );
+
+ const ask: TAskFunction = (
+ {
+ text,
+ overrideConvoId,
+ overrideUserMessageId,
+ parentMessageId = null,
+ conversationId = null,
+ messageId = null,
+ },
+ {
+ editedContent = null,
+ editedMessageId = null,
+ isRegenerate = false,
+ isContinued = false,
+ isEdited = false,
+ compact = false,
+ overrideMessages,
+ overrideFiles,
+ targetResponseMessageId,
+ overrideManualSkills,
+ overrideQuotes,
+ overrideReasoning,
+ addedConvo,
+ overrideClientRequestId,
+ overrideRecoverySteerId,
+ overrideExpectedPredecessorCreatedAt,
+ overrideQueuedMessageOrigin,
+ } = {},
+ ) => {
+ text = text.trim();
+ /**
+ * Attached files make an otherwise empty draft submittable, e.g. replying to an agent that
+ * asked for a document upload. When a caller supplies `overrideFiles`, that array is
+ * authoritative, even when empty. A text-only App action must not become submittable just
+ * because the user has staged a file for a different, unsent composer message.
+ */
+ const availableFileCount = overrideFiles == null ? (files?.size ?? 0) : overrideFiles.length;
+ /** A compaction sends no text: it replays the branch, like a regenerate, with the response
+ * placeholder parented onto the leaf. */
+ const regenerateShaped = isRegenerate || compact;
+ if (
+ askInFlightRef.current ||
+ !!isSubmitting ||
+ store.get(revealedQueuedTurnFamily(immutableConversation?.conversationId ?? '')) != null ||
+ (!regenerateShaped && !isSubmittableMessage(text, availableFileCount))
+ ) {
+ return false;
+ }
+
+ /** The builder resolves `promptPrefix` on its copy; the pane's conversation stays as is. */
+ const conversation = immutableConversation == null ? null : { ...immutableConversation };
+ const codeDecision = services.resolveCode(conversation);
+ if (codeDecision == null) {
+ logger.warn('[useTurns] Refusing to send without an available code workspace');
+ return false;
+ }
+
+ const endpoint = conversation?.endpoint;
+ if (endpoint === null) {
+ console.error('No endpoint available');
+ return false;
+ }
+
+ conversationId = conversationId ?? conversation?.conversationId ?? null;
+ if (conversationId == 'search') {
+ console.error('cannot send any message under search view!');
+ return false;
+ }
+
+ const cachedMessages = getMessages(conversationId);
+ const isExistingConversation = conversationId != null && conversationId !== Constants.NEW_CONVO;
+ if (isExistingConversation && overrideMessages == null && cachedMessages == null) {
+ logger.warn('[useTurns] Refusing to send before existing conversation history loads');
+ return false;
+ }
+
+ /**
+ * Warm-switch revalidation guard: a navigation invalidates the target's cache and renders it
+ * while a background refetch reconciles. Deriving parentMessageId from that cache could fork
+ * from an outdated tail, so refuse (the composer keeps the text) until the refetch settles.
+ */
+ if (
+ isExistingConversation &&
+ overrideMessages == null &&
+ services.isHistoryRevalidating(conversationId)
+ ) {
+ logger.warn('[useTurns] Refusing to send while conversation history revalidates');
+ return false;
+ }
+
+ if (isContinued && !latestMessage) {
+ console.error('cannot continue AI message without latestMessage!');
+ return false;
+ }
+
+ if (parentMessageId == null && hasPendingAssistantParent(latestMessage)) {
+ logger.warn(
+ '[useTurns] Refusing to append to a preliminary assistant message',
+ latestMessage,
+ );
+ return false;
+ }
+
+ setShowStopButton(false);
+
+ const convoKey = conversationId ?? Constants.NEW_CONVO;
+ const endpointsConfig = services.getEndpointsConfig();
+ /**
+ * Manual skills: an explicit `overrideManualSkills` wins (regenerate and resubmit replay the
+ * original user message's picks); a regenerate, continue or edit without one sends none and
+ * leaves the compose-time queue alone; a fresh submit drains the queue into the message.
+ */
+ const replaysTurn = regenerateShaped || isContinued || isEdited;
+ const manualSkills =
+ overrideManualSkills ?? (replaysTurn ? [] : drain(pendingManualSkillsByConvoId, convoKey));
+ /**
+ * Quoted excerpts resolve like manual skills, but are skipped entirely for Assistants
+ * endpoints: those bypass the server's quote merge, so the quote UI is hidden there and a
+ * selection queued on another endpoint must not ride along. The queue is left untouched so
+ * it survives a switch back.
+ */
+ let quotes: string[] = [];
+ if (!isAssistantsEndpoint(endpoint)) {
+ quotes = overrideQuotes ?? (replaysTurn ? [] : drain(pendingQuotesByConvoId, convoKey));
+ }
+ let reasoningOverride = overrideReasoning ?? undefined;
+ const reasoningStateKey = getReasoningStateKey(conversationId, index);
+ const drainedReasoning = overrideReasoning === undefined && !replaysTurn;
+ if (drainedReasoning) {
+ reasoningOverride = drainPendingReasoning(reasoningStateKey);
+ }
+ const stagedReasoning = reasoningOverride;
+ if (reasoningOverride != null) {
+ const resolved = services.resolveReasoning({
+ endpoint,
+ conversation,
+ endpointsConfig,
+ reasoningOverride,
+ });
+ reasoningOverride = resolved.reasoningOverride;
+ /** Refused only because the catalog is not loaded yet: put a drained choice back. */
+ if (resolved.retryable && drainedReasoning && stagedReasoning != null) {
+ store.set(pendingReasoningOverrideFamily(reasoningStateKey), stagedReasoning);
+ }
+ }
+
+ const turn = buildTurn({
+ text,
+ params: { text, overrideConvoId, overrideUserMessageId, parentMessageId, messageId },
+ options: {
+ editedContent: editedContent ?? undefined,
+ editedMessageId,
+ isRegenerate,
+ isContinued,
+ isEdited,
+ compact,
+ overrideMessages,
+ overrideFiles,
+ targetResponseMessageId,
+ addedConvo,
+ overrideClientRequestId,
+ overrideRecoverySteerId,
+ overrideExpectedPredecessorCreatedAt,
+ overrideQueuedMessageOrigin,
+ },
+ conversationId,
+ conversation,
+ latestMessage,
+ cachedMessages,
+ files,
+ canClearFiles: setFiles != null,
+ routeProjectId: services.getRouteProjectId(),
+ endpointsConfig,
+ modelSpecs: services.modelSpecs,
+ user: services.user,
+ isTemporary: services.isTemporary,
+ ephemeralAgent: services.getEphemeralAgent(convoKey),
+ getSender: services.getSender,
+ userKey: endpoint !== EModelEndpoint.agents ? services.getUserKey() : undefined,
+ manualSkills,
+ quotes,
+ reasoningOverride,
+ code: codeDecision.code,
+ });
+ const { submission, currentMsg, initialResponse, submissionMessages, fileEffects } = turn;
+ conversationId = turn.conversationId;
+ logger.log('message_state', initialResponse);
+
+ if (turn.newChatPath != null) {
+ services.openNewChat(turn.newChatPath);
+ }
+ if (fileEffects != null && setFiles) {
+ services.releaseFiles(fileEffects.submittedFileIds);
+ if (fileEffects.clearComposer) {
+ setFiles(new Map());
+ services.clearFilesToDelete();
+ }
+ }
+ if (turn.startsSubmitting) {
+ setIsSubmitting(true);
+ setShowStopButton(true);
+ }
+
+ /** Bound before the optimistic tail is published, not after the first provider event: a
+ * waiting request already owns a turn even when no usage exists. */
+ services.bindResponse(conversationId ?? Constants.NEW_CONVO, initialResponse.messageId);
+
+ if (turn.regenerateShaped) {
+ setMessages([...submissionMessages, initialResponse]);
+ services.focusResponse(initialResponse.parentMessageId);
+ } else {
+ setMessages([...submissionMessages, currentMsg, initialResponse]);
+ }
+
+ /** Carries the submitted choice through the first saved-chat event instead of re-deriving
+ * it from agent defaults. Optimistic: the stream's error path reconciles an existing chat
+ * with its authoritative server decision if admission fails. */
+ setConversation((current) =>
+ current == null || current.conversationId !== conversation?.conversationId
+ ? current
+ : codeDecision.apply(current),
+ );
+ /** Armed at the point of no return: every refusal above returns before it, so a rejected
+ * send never has to unwind the guard, and `ask` runs to completion synchronously, which is
+ * the whole window it has to cover. */
+ askInFlightRef.current = true;
+ setSubmissionStart(Date.now());
+ services.bindLaunch(submission.conversation, index);
+ setSubmission(submission);
+ logger.dir('message_stream', {
+ conversationId,
+ messageId: currentMsg.messageId,
+ parentMessageId: currentMsg.parentMessageId,
+ isEdited: turn.isEditOrContinue,
+ isRegenerate: turn.regenerateShaped,
+ isContinued,
+ });
+ };
+
+ return { ask, regenerate: createRegenerate(ask, getMessages) };
+}