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: Move the Steer POST into useSubmitSteer with Core Helpers (#17124)

Marco Berettac6dac4b508b1
diff --git a/client/src/hooks/Chat/steering/submit.ts b/client/src/hooks/Chat/steering/submit.ts
new file mode 100644
index 0000000000..fcc2ce08a5
--- /dev/null
+++ b/client/src/hooks/Chat/steering/submit.ts
@@ -0,0 +1,445 @@
+import { useCallback, useRef } from 'react';
+import { v4 } from 'uuid';
+import { useToastContext } from '@librechat/client';
+import {
+ steerAttemptChip,
+ routeSteerFailure,
+ carriedSteerContext,
+ createSteerDispatch,
+ supportsGenerationProtocolV2,
+} from '@librechat/chat';
+import type {
+ SteerAttempt,
+ PendingSteer,
+ SubmitSteerOptions,
+ QueuedMessageOrigin,
+ QueuedMessageContext,
+ GenerationProtocolVersion,
+} from '@librechat/chat';
+import type { TMessage } from 'librechat-data-provider';
+import type { MutableRefObject } from 'react';
+import type { QueueEnqueue } from './enqueue';
+import type { SteerChips } from './chips';
+import type { QueueRows } from './rows';
+import { useCancelSteerMutation, useSteerMessageMutation } from '~/data-provider';
+import { useSteerRehome } from '~/hooks/Chat/useSteerCancel';
+import useSteerConvert from '~/hooks/Chat/useSteerConvert';
+import useLocalize from '~/hooks/useLocalize';
+
+export type SubmitSteer = (
+ text: string,
+ steerFiles?: TMessage['files'],
+ context?: QueuedMessageContext,
+ opts?: SubmitSteerOptions,
+) => boolean;
+
+/** The steer POST and everything its response can mean for the words it carried. */
+export default function useSubmitSteer({
+ conversationId,
+ hasRealConvoId,
+ activeGenerationCreatedAt,
+ activeGenerationProtocolVersion,
+ visibleConversationRef,
+ isSubmittingRef,
+ sendNow,
+ chips,
+ rows,
+ enqueue,
+}: {
+ conversationId: string;
+ hasRealConvoId: boolean;
+ activeGenerationCreatedAt: number | null;
+ activeGenerationProtocolVersion: GenerationProtocolVersion;
+ visibleConversationRef: MutableRefObject<string>;
+ isSubmittingRef: MutableRefObject<boolean>;
+ sendNow: (
+ text: string,
+ files?: TMessage['files'],
+ context?: QueuedMessageContext,
+ ) => false | void;
+ chips: SteerChips;
+ rows: Pick<QueueRows, 'restoreQueued' | 'rewakeDrain' | 'registerQueuedOrigin'>;
+ enqueue: QueueEnqueue['enqueue'];
+}): SubmitSteer {
+ const localize = useLocalize();
+ const { showToast } = useToastContext();
+ const convertSteersToQueued = useSteerConvert();
+ /* The single boundary a steer's words return through, wherever the cancel
+ that reclaimed them was decided. */
+ const rehomeSteer = useSteerRehome(conversationId);
+ /** `mutate` is a stable callback; the mutation result objects are fresh
+ * every render and would defeat the memoized return value of the caller. */
+ const { mutate: steerMessage } = useSteerMessageMutation();
+ const { mutateAsync: cancelSteer } = useCancelSteerMutation();
+ const dispatchRef = useRef(createSteerDispatch());
+ const {
+ upsertSteerChip,
+ replaceSteerChip,
+ acknowledgeSteer,
+ settleReceiptReplay,
+ reclaimRejectedChipQuotes,
+ isSteerAcceptedOrSettled,
+ hasPendingSteerCancel,
+ clearPendingSteerCancel,
+ } = chips;
+ const { restoreQueued, rewakeDrain, registerQueuedOrigin } = rows;
+
+ /** Restore a server-owned steer as the same queued follow-up and wake a
+ * drain whose one-shot completion signal may already have been consumed
+ * while the recovery request was in flight. Shared by reclaim and durable
+ * receipt replay so neither round-trip can strand accepted words. */
+ const queueRecoveredSteer = useCallback(
+ (steer: PendingSteer) => {
+ convertSteersToQueued(
+ conversationId,
+ [
+ {
+ steerId: steer.steerId,
+ ...(steer.clientSteerId && { clientSteerId: steer.clientSteerId }),
+ text: steer.text,
+ createdAt: steer.createdAt,
+ ...(steer.files && steer.files.length > 0 && { files: steer.files }),
+ ...carriedSteerContext(steer),
+ ...(steer.queuedOrigin && { queuedOrigin: steer.queuedOrigin }),
+ },
+ ],
+ {
+ /** A durable receipt belongs to the generation that produced it. The
+ * visible conversation may already advertise a replacement/legacy
+ * generation by the time this late ACK lands, but that must not strip
+ * the receipt-bound recovery identity from the queued item. */
+ generationProtocolVersion: steer.generationProtocolVersion,
+ },
+ );
+ rewakeDrain(conversationId);
+ },
+ [conversationId, convertSteersToQueued, rewakeDrain],
+ );
+
+ /** POSTs a steer (text + files + quotes; the server merges the quotes into
+ * the model-bound turn at the injection boundary). `context` doubles as the
+ * RESTORE payload: every degradation path threads it back into the
+ * requeue/send fallback so the item's quotes and manual skills survive.
+ * Skill picks never ride the POST; they configure a NEW turn's run, so a
+ * queued-origin steer only carries them for restoration. */
+ return useCallback(
+ (
+ text: string,
+ steerFiles?: TMessage['files'],
+ context?: QueuedMessageContext,
+ opts?: SubmitSteerOptions,
+ ): boolean => {
+ const trimmed = text.trim();
+ if (trimmed.length === 0 || !hasRealConvoId) {
+ return false;
+ }
+ const preempt = opts?.preempt === true;
+ const targetGenerationCreatedAt =
+ opts?.generationCreatedAt ?? activeGenerationCreatedAt ?? undefined;
+ if (targetGenerationCreatedAt == null) {
+ return false;
+ }
+ const files = steerFiles && steerFiles.length > 0 ? steerFiles : undefined;
+ const localId = opts?.clientSteerId ?? `local-${v4()}`;
+ /** The true submission time, carried through the ACK and failure chips so
+ * a later conversion sorts this steer by when it was SENT, not when its
+ * 202 landed; otherwise a draft queued during the round-trip would drain
+ * ahead of a steer submitted before it. */
+ const createdAt = opts?.createdAt ?? Date.now();
+ /** Rides every chip state so a terminal conversion (late ACK, run-end
+ * leftover report) can restore the queued item's full context. */
+ const attempt: SteerAttempt = {
+ localId,
+ text: trimmed,
+ createdAt,
+ files,
+ generationCreatedAt: targetGenerationCreatedAt,
+ generationProtocolVersion:
+ opts?.generationProtocolVersion ?? activeGenerationProtocolVersion,
+ queuedOrigin: opts?.queuedOrigin,
+ carried: carriedSteerContext(context),
+ };
+ const { carried, generationProtocolVersion } = attempt;
+ /** If the steer loses its race with run finalization, its normal-send
+ * fallback must still be tied to the generation it targeted. Otherwise
+ * a newer run started by another tab can be replaced by this stale
+ * fallback. Every fallback also carries a queue origin: an existing row
+ * keeps its exact logical slot, while a composer-origin steer gets a
+ * stable synthetic row so a predecessor 409 cannot discard its text or
+ * files when the newer run wins. */
+ const fallbackOrigin: QueuedMessageOrigin = opts?.queuedOrigin ?? {
+ item: {
+ id: localId,
+ text: trimmed,
+ createdAt,
+ expectedPredecessorCreatedAt: targetGenerationCreatedAt,
+ ...(files && { files }),
+ ...carried,
+ ...(context?.clientRequestId && {
+ clientRequestId: context.clientRequestId,
+ }),
+ ...(context?.recoverySteerId && {
+ recoverySteerId: context.recoverySteerId,
+ }),
+ },
+ beforeIds: [],
+ afterIds: [],
+ };
+ const fallbackContext: QueuedMessageContext = {
+ ...context,
+ expectedPredecessorCreatedAt: targetGenerationCreatedAt,
+ queuedMessageOrigin: fallbackOrigin,
+ };
+ /** A queued-origin attempt must be reversible as the same queue item,
+ * not merely reproducible from its text. This preserves its identity,
+ * timestamp, priority, future fields, and original array position. */
+ const restoreRejectedSteer = () => {
+ if (opts?.queuedOrigin != null) {
+ restoreQueued(opts.queuedOrigin);
+ } else {
+ enqueue(trimmed, { id: localId, createdAt, files, ...context });
+ }
+ rewakeDrain(conversationId);
+ };
+ /** The words go out as a new turn when the visible pane is free, and back
+ * into the queue when it is not or the send is refused. */
+ const sendOrRestore = () => {
+ if (sendNow(trimmed, files ?? [], fallbackContext) === false) {
+ restoreRejectedSteer();
+ }
+ };
+ if (opts?.queuedOrigin != null) {
+ registerQueuedOrigin(opts.queuedOrigin);
+ }
+ upsertSteerChip(
+ conversationId,
+ steerAttemptChip(attempt, {
+ steerId: localId,
+ status: 'sending',
+ ...(preempt && { preempt: true }),
+ }),
+ );
+ dispatchRef.current(conversationId, (settleDispatch) => {
+ steerMessage(
+ {
+ conversationId,
+ clientSteerId: localId,
+ text: trimmed,
+ ...(files && { files }),
+ ...(carried.quotes && { quotes: carried.quotes }),
+ ...(preempt && { preempt }),
+ generationCreatedAt: targetGenerationCreatedAt,
+ },
+ {
+ onSuccess: (response) => {
+ try {
+ /** The server's own record of this steer, as every later state names it. */
+ const accepted = (extra?: Partial<PendingSteer>) =>
+ steerAttemptChip(attempt, {
+ steerId: response.steerId,
+ clientSteerId: localId,
+ status: 'pending',
+ ...extra,
+ });
+ const acceptResponse = () => {
+ /** A 202 without the echo means a pre-quotes replica queued
+ * the words without their excerpts. The quotes are NOT
+ * re-staged here: the steer has not injected yet, so they
+ * stay carried on the pending chip: a quote-less applied
+ * event re-stages them at the actual loss, and a terminal
+ * leftover conversion carries them onto the recovered row
+ * instead (its normal send delivers quotes on any server).
+ * Only a settled replay (an already-injected steer with no
+ * future event to re-home the chip) reclaims immediately. */
+ const quotesRejected = carried.quotes != null && response.quotesAccepted !== true;
+ const canUseV2Receipt =
+ generationProtocolVersion === 2 && supportsGenerationProtocolV2(response);
+ if (canUseV2Receipt && response.settled === true) {
+ if (response.leftover === true) {
+ queueRecoveredSteer(accepted());
+ } else {
+ if (quotesRejected) {
+ reclaimRejectedChipQuotes(conversationId, [localId, response.steerId]);
+ }
+ settleReceiptReplay(conversationId, localId, response.steerId);
+ }
+ return;
+ }
+ /** Unsupported runs retain the words as Steer, but never silently
+ * claim to have requested tool cancellation. */
+ if (
+ preempt &&
+ response.preempt !== true &&
+ visibleConversationRef.current === conversationId
+ ) {
+ showToast({
+ message: localize('com_ui_steer_preempt_unsupported'),
+ status: 'warning',
+ });
+ }
+ const acknowledged = accepted({
+ ...(response.preempt === true && { preempt: true }),
+ ...(response.preemptRevision != null && {
+ preemptRevision: response.preemptRevision,
+ }),
+ });
+ if (acknowledgeSteer(conversationId, localId, acknowledged)) {
+ /** Terminal conversion re-homes the words as a queued
+ * follow-up that sends via `ask`; the carried quotes ride
+ * it there, so nothing is re-staged. */
+ queueRecoveredSteer(acknowledged);
+ }
+ };
+ if (hasPendingSteerCancel(conversationId, localId)) {
+ void cancelSteer({
+ conversationId,
+ steerId: response.steerId,
+ clientSteerId: localId,
+ generationCreatedAt: targetGenerationCreatedAt,
+ }).then(
+ ({ removed }) => {
+ clearPendingSteerCancel(conversationId, localId);
+ if (removed === true) {
+ /* Cancel won the race against its own POST. The words are
+ off the server now, so they go back to the user through
+ the same boundary as an immediate cancel: whole, and
+ into the queue when the composer will not take them.
+ Clearing the marker without this loses the message. */
+ rehomeSteer(accepted());
+ return;
+ }
+ /* The server kept the steer: it is live and will still
+ reach the agent. The chip the optimistic cancel hid
+ comes back through the ordinary acknowledgement, so it
+ settles like any other accepted steer. */
+ acceptResponse();
+ showToast({
+ message: localize('com_ui_steer_already_applied'),
+ status: 'info',
+ });
+ },
+ () => {
+ clearPendingSteerCancel(conversationId, localId);
+ /* Unknown outcome, but the POST was accepted: treat the
+ steer as live rather than claiming it is gone. */
+ acceptResponse();
+ showToast({
+ message: localize('com_ui_steer_cancel_failed'),
+ status: 'warning',
+ });
+ },
+ );
+ return;
+ }
+ acceptResponse();
+ } finally {
+ settleDispatch();
+ }
+ },
+ onError: (error) => {
+ try {
+ clearPendingSteerCancel(conversationId, localId);
+ if (isSteerAcceptedOrSettled(conversationId, localId)) {
+ replaceSteerChip(conversationId, localId, null);
+ return;
+ }
+ const originStillVisible = visibleConversationRef.current === conversationId;
+ const route = routeSteerFailure(error, generationProtocolVersion);
+ if (route === 'send-after-run') {
+ // The run finished before the steer landed. While the final SSE
+ // is still settling, `ask()`'s in-flight guard would drop a
+ // direct send: queue it so the run-end drain fires it instead.
+ // The explicit empty array stops `ask` from vacuuming composer
+ // files staged for a DIFFERENT draft. A refused send (`false`)
+ // falls back to the queue too: the chip is already gone, so
+ // dropping the text here would lose it silently.
+ replaceSteerChip(conversationId, localId, null);
+ if (!originStillVisible || isSubmittingRef.current) {
+ restoreRejectedSteer();
+ return;
+ }
+ sendOrRestore();
+ return;
+ }
+ if (route === 'send-when-idle') {
+ replaceSteerChip(conversationId, localId, null);
+ // The rejection can land AFTER the final SSE consumed the
+ // run-end signal (common on an unsupported SDK near run end):
+ // queueing then has nothing left to drain it, so mirror the
+ // NO_ACTIVE_RUN fallback and send once submission settled:
+ // queueing the refusal instead of dropping the text.
+ if (originStillVisible && !isSubmittingRef.current) {
+ sendOrRestore();
+ return;
+ }
+ restoreRejectedSteer();
+ showToast({
+ message: localize('com_ui_steer_paused_queued'),
+ status: 'info',
+ });
+ return;
+ }
+ if (route === 'requeue') {
+ /** A different live generation now owns this conversation. A
+ * normal-send fallback would replace that newer run (especially
+ * from a stale tab), so retain the instruction for its run-end
+ * drain regardless of this tab's local submission state. */
+ replaceSteerChip(conversationId, localId, null);
+ restoreRejectedSteer();
+ showToast({
+ message: localize('com_ui_steer_paused_queued'),
+ status: 'info',
+ });
+ return;
+ }
+ // A concrete origin 4xx proves the steer was rejected and keeps
+ // the ordinary failed controls (edit/queue/remove/retry); a
+ // transport or 5xx ambiguity gets the locked "delivery unknown"
+ // surface instead.
+ upsertSteerChip(
+ conversationId,
+ steerAttemptChip(attempt, {
+ steerId: localId,
+ status: 'failed',
+ ...(route === 'uncertain' && { deliveryUncertain: true }),
+ ...(preempt && { preempt: true }),
+ }),
+ );
+ } finally {
+ settleDispatch();
+ }
+ },
+ },
+ );
+ });
+ return true;
+ },
+ [
+ hasRealConvoId,
+ conversationId,
+ upsertSteerChip,
+ replaceSteerChip,
+ acknowledgeSteer,
+ settleReceiptReplay,
+ queueRecoveredSteer,
+ rehomeSteer,
+ reclaimRejectedChipQuotes,
+ steerMessage,
+ sendNow,
+ enqueue,
+ restoreQueued,
+ rewakeDrain,
+ registerQueuedOrigin,
+ isSteerAcceptedOrSettled,
+ hasPendingSteerCancel,
+ clearPendingSteerCancel,
+ cancelSteer,
+ showToast,
+ localize,
+ activeGenerationCreatedAt,
+ activeGenerationProtocolVersion,
+ visibleConversationRef,
+ isSubmittingRef,
+ ],
+ );
+}
diff --git a/client/src/hooks/Chat/useSteering.ts b/client/src/hooks/Chat/useSteering.ts
index 4aded1abcf..46265a76f5 100644
--- a/client/src/hooks/Chat/useSteering.ts
+++ b/client/src/hooks/Chat/useSteering.ts
@@ -1,15 +1,8 @@
import { useCallback, useEffect, useMemo, useRef } from 'react';
-import { v4 } from 'uuid';
import { useRecoilValue } from 'recoil';
import { useAtomValue, useStore } from 'jotai';
-import { useToastContext } from '@librechat/client';
+import { hasLiveRunPause, selectLiveMessageState } from '@librechat/chat';
import { hasQueuedIntent, acquireQueueSendLock, releaseQueueSendLock } from '@librechat/chat';
-import {
- hasLiveRunPause,
- getSteerErrorCode,
- selectLiveMessageState,
- isDefiniteSteerRejection,
-} from '@librechat/chat';
import {
Constants,
isAgentsEndpoint,
@@ -22,11 +15,6 @@ import type { QueuedMessage, QueuedMessageOrigin } from '~/hooks/Chat/queue';
import type { ExtendedFile, FileSetter } from '~/common';
import type { PendingSteer } from '~/hooks/Chat/queue';
import type { DuringRunAction } from './contract';
-import {
- useCancelSteerMutation,
- useSteerMessageMutation,
- supportsGenerationProtocolV2,
-} from '~/data-provider';
import {
getReasoningStateKey,
pendingReasoningOverrideFamily,
@@ -37,16 +25,14 @@ import {
} from '~/components/Chat/Steering/recovery';
import { useChatSettings } from '~/Providers/ChatSettingsContext';
import useCodeApprovalMode from '../Agents/useCodeApprovalMode';
-import { useSteerRehome } from '~/hooks/Chat/useSteerCancel';
-import useSteerConvert from '~/hooks/Chat/useSteerConvert';
import { revealedQueuedTurnFamily } from '~/store/steer';
import useQueuedTurnReceipts from './steering/receipts';
import { useLatestMessage } from '~/hooks/Messages';
import useQueuedRecovery from './steering/recovery';
import useComposerTake from './steering/composer';
import useQueueEnqueue from './steering/enqueue';
+import useSubmitSteer from './steering/submit';
import { carriedSteerContext } from '~/utils';
-import useLocalize from '~/hooks/useLocalize';
import useSteerChips from './steering/chips';
import useQueueRows from './steering/rows';
import store from '~/store';
@@ -121,19 +107,9 @@ export default function useSteering({
sendNow,
stopGenerating,
}: UseSteeringParams) {
- const localize = useLocalize();
const composerDisabledRef = useRef(composerDisabled);
composerDisabledRef.current = composerDisabled;
- const { showToast } = useToastContext();
const jotaiStore = useStore();
- const convertSteersToQueued = useSteerConvert();
- /* The single boundary a steer's words return through, wherever the cancel
- that reclaimed them was decided. */
- const rehomeSteer = useSteerRehome(conversationId);
- /** `mutate` is a stable callback; the mutation result objects are fresh
- * every render and would defeat the memoized return value below. */
- const { mutate: steerMessage } = useSteerMessageMutation();
- const { mutateAsync: cancelSteer } = useCancelSteerMutation();
const {
config,
duringRunDefaultAction: defaultAction,
@@ -177,66 +153,6 @@ export default function useSteering({
* bounded interval submits degrade to the local queue and Stop/steer refuse. */
const canControlGeneration = activeGenerationCreatedAt != null;
const duringRunActive = enabled && (isSubmitting || revealPending) && !answerModeActive;
- /** First-party FIFO admission: validation inside the steer route can await
- * agent ACL and attachment reads, so overlapping POSTs could otherwise reach
- * the durable queue out of submission order. Keep one request in flight per
- * conversation; later optimistic chips retain the epoch/id/time captured at
- * submission and dispatch only after the prior request settles. */
- const steerDispatchQueuesRef = useRef<
- Map<
- string,
- {
- active: boolean;
- pending: Array<(settle: () => void) => void>;
- }
- >
- >(new Map());
- const scheduleSteerDispatch = useCallback(
- (convoId: string, dispatch: (settle: () => void) => void) => {
- const existing = steerDispatchQueuesRef.current.get(convoId);
- const state = existing ?? { active: false, pending: [] };
- if (existing == null) {
- steerDispatchQueuesRef.current.set(convoId, state);
- }
- state.pending.push(dispatch);
-
- const startNext = () => {
- if (state.active) {
- return;
- }
- const next = state.pending[0];
- if (next == null) {
- if (steerDispatchQueuesRef.current.get(convoId) === state) {
- steerDispatchQueuesRef.current.delete(convoId);
- }
- return;
- }
- state.active = true;
- let settled = false;
- const settle = () => {
- if (settled) {
- return;
- }
- settled = true;
- const index = state.pending.indexOf(next);
- if (index >= 0) {
- state.pending.splice(index, 1);
- }
- state.active = false;
- startNext();
- };
- try {
- next(settle);
- } catch (error) {
- settle();
- throw error;
- }
- };
-
- startNext();
- },
- [],
- );
/** `ask()` does not flip `isSubmitting` until the submission effect renders.
* Two queued-row clicks in the same browser task would otherwise both remove
* their items and the second submission could overwrite the first; and the
@@ -261,6 +177,14 @@ export default function useSteering({
[isSubmitting, sendLockKey, queueKey],
);
+ const rows = useQueueRows({
+ index,
+ queueKey,
+ conversationId,
+ isSubmitting,
+ pendingSteers,
+ activeGenerationCreatedAt,
+ });
const {
updateQueuedMessage,
removeQueued,
@@ -271,18 +195,10 @@ export default function useSteering({
restoreQueuedOrder,
takeQueued,
releaseQueuedOrigin,
- registerQueuedOrigin,
restoreQueued,
rewakeDrain,
armDrainAfterAbort,
- } = useQueueRows({
- index,
- queueKey,
- conversationId,
- isSubmitting,
- pendingSteers,
- activeGenerationCreatedAt,
- });
+ } = rows;
/** Capture a durable branch anchor into a server queued turn. Optimistic
* assistant placeholders are siblings of their eventual persisted response,
* so they anchor through their stable user parent. */
@@ -310,16 +226,8 @@ export default function useSteering({
const visibleConversationRef = useRef(conversationId);
visibleConversationRef.current = conversationId;
- const {
- upsertSteerChip,
- replaceSteerChip,
- acknowledgeSteer,
- settleReceiptReplay,
- isSteerAcceptedOrSettled,
- hasPendingSteerCancel,
- clearPendingSteerCancel,
- reclaimRejectedChipQuotes,
- } = useSteerChips({ visibleConversationRef, isSubmittingRef });
+ const chips = useSteerChips({ visibleConversationRef, isSubmittingRef });
+ const { replaceSteerChip } = chips;
const { enqueue } = useQueueEnqueue({
queueKey,
conversationId,
@@ -347,436 +255,18 @@ export default function useSteering({
setFiles,
});
- /** Restore a server-owned steer as the same queued follow-up and wake a
- * drain whose one-shot completion signal may already have been consumed
- * while the recovery request was in flight. Shared by reclaim and durable
- * receipt replay so neither round-trip can strand accepted words. */
- const queueRecoveredSteer = useCallback(
- (steer: PendingSteer) => {
- convertSteersToQueued(
- conversationId,
- [
- {
- steerId: steer.steerId,
- ...(steer.clientSteerId && { clientSteerId: steer.clientSteerId }),
- text: steer.text,
- createdAt: steer.createdAt,
- ...(steer.files && steer.files.length > 0 && { files: steer.files }),
- ...carriedSteerContext(steer),
- ...(steer.queuedOrigin && { queuedOrigin: steer.queuedOrigin }),
- },
- ],
- {
- /** A durable receipt belongs to the generation that produced it. The
- * visible conversation may already advertise a replacement/legacy
- * generation by the time this late ACK lands, but that must not strip
- * the receipt-bound recovery identity from the queued item. */
- generationProtocolVersion: steer.generationProtocolVersion,
- },
- );
- rewakeDrain(conversationId);
- },
- [conversationId, convertSteersToQueued, rewakeDrain],
- );
-
- /** POSTs a steer (text + files + quotes; the server merges the quotes into
- * the model-bound turn at the injection boundary). `context` doubles as the
- * RESTORE payload: every degradation path threads it back into the
- * requeue/send fallback so the item's quotes and manual skills survive.
- * Skill picks never ride the POST — they configure a NEW turn's run, so a
- * queued-origin steer only carries them for restoration. */
- const submitSteer = useCallback(
- (
- text: string,
- steerFiles?: TMessage['files'],
- context?: QueuedMessageContext,
- opts?: SubmitSteerOptions,
- ): boolean => {
- const trimmed = text.trim();
- if (trimmed.length === 0 || !hasRealConvoId) {
- return false;
- }
- const preempt = opts?.preempt === true;
- const targetGenerationCreatedAt =
- opts?.generationCreatedAt ?? activeGenerationCreatedAt ?? undefined;
- if (targetGenerationCreatedAt == null) {
- return false;
- }
- const files = steerFiles && steerFiles.length > 0 ? steerFiles : undefined;
- const targetGenerationProtocolVersion =
- opts?.generationProtocolVersion ?? activeGenerationProtocolVersion;
- /** Rides every chip state so a terminal conversion (late ACK, run-end
- * leftover report) can restore the queued item's full context. */
- const carried = carriedSteerContext(context);
- const localId = opts?.clientSteerId ?? `local-${v4()}`;
- /** The true submission time, carried through the ACK and failure chips so
- * a later conversion sorts this steer by when it was SENT, not when its
- * 202 landed; otherwise a draft queued during the round-trip would drain
- * ahead of a steer submitted before it. */
- const createdAt = opts?.createdAt ?? Date.now();
- /** If the steer loses its race with run finalization, its normal-send
- * fallback must still be tied to the generation it targeted. Otherwise
- * a newer run started by another tab can be replaced by this stale
- * fallback. Every fallback also carries a queue origin: an existing row
- * keeps its exact logical slot, while a composer-origin steer gets a
- * stable synthetic row so a predecessor 409 cannot discard its text or
- * files when the newer run wins. */
- const fallbackOrigin: QueuedMessageOrigin = opts?.queuedOrigin ?? {
- item: {
- id: localId,
- text: trimmed,
- createdAt,
- expectedPredecessorCreatedAt: targetGenerationCreatedAt,
- ...(files && { files }),
- ...carried,
- ...(context?.clientRequestId && {
- clientRequestId: context.clientRequestId,
- }),
- ...(context?.recoverySteerId && {
- recoverySteerId: context.recoverySteerId,
- }),
- },
- beforeIds: [],
- afterIds: [],
- };
- const fallbackContext: QueuedMessageContext = {
- ...context,
- expectedPredecessorCreatedAt: targetGenerationCreatedAt,
- queuedMessageOrigin: fallbackOrigin,
- };
- /** A queued-origin attempt must be reversible as the same queue item,
- * not merely reproducible from its text. This preserves its identity,
- * timestamp, priority, future fields, and original array position. */
- const restoreRejectedSteer = () => {
- if (opts?.queuedOrigin != null) {
- restoreQueued(opts.queuedOrigin);
- } else {
- enqueue(trimmed, { id: localId, createdAt, files, ...context });
- }
- rewakeDrain(conversationId);
- };
- if (opts?.queuedOrigin != null) {
- registerQueuedOrigin(opts.queuedOrigin);
- }
- upsertSteerChip(conversationId, {
- steerId: localId,
- text: trimmed,
- status: 'sending',
- createdAt,
- ...(files && { files }),
- ...(preempt && { preempt: true }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- generationProtocolVersion: targetGenerationProtocolVersion,
- ...(opts?.queuedOrigin && { queuedOrigin: opts.queuedOrigin }),
- ...carried,
- });
- scheduleSteerDispatch(conversationId, (settleDispatch) => {
- steerMessage(
- {
- conversationId,
- clientSteerId: localId,
- text: trimmed,
- ...(files && { files }),
- ...(carried.quotes && { quotes: carried.quotes }),
- ...(preempt && { preempt }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- },
- {
- onSuccess: (response) => {
- try {
- const acceptResponse = () => {
- /** A 202 without the echo means a pre-quotes replica queued
- * the words without their excerpts. The quotes are NOT
- * re-staged here: the steer has not injected yet, so they
- * stay carried on the pending chip: a quote-less applied
- * event re-stages them at the actual loss, and a terminal
- * leftover conversion carries them onto the recovered row
- * instead (its normal send delivers quotes on any server).
- * Only a settled replay (an already-injected steer with no
- * future event to re-home the chip) reclaims immediately. */
- const quotesRejected = carried.quotes != null && response.quotesAccepted !== true;
- const canUseV2Receipt =
- targetGenerationProtocolVersion === 2 && supportsGenerationProtocolV2(response);
- if (canUseV2Receipt && response.settled === true) {
- if (response.leftover === true) {
- queueRecoveredSteer({
- steerId: response.steerId,
- clientSteerId: localId,
- text: trimmed,
- status: 'pending',
- createdAt,
- ...(files && { files }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- generationProtocolVersion: targetGenerationProtocolVersion,
- ...(opts?.queuedOrigin && {
- queuedOrigin: opts.queuedOrigin,
- }),
- ...carried,
- });
- } else {
- if (quotesRejected) {
- reclaimRejectedChipQuotes(conversationId, [localId, response.steerId]);
- }
- settleReceiptReplay(conversationId, localId, response.steerId);
- }
- return;
- }
- /** Unsupported runs retain the words as Steer, but never silently
- * claim to have requested tool cancellation. */
- if (
- preempt &&
- response.preempt !== true &&
- visibleConversationRef.current === conversationId
- ) {
- showToast({
- message: localize('com_ui_steer_preempt_unsupported'),
- status: 'warning',
- });
- }
- const acknowledged = {
- steerId: response.steerId,
- clientSteerId: localId,
- text: trimmed,
- status: 'pending',
- createdAt,
- ...(files && { files }),
- ...(response.preempt === true && { preempt: true }),
- ...(response.preemptRevision != null && {
- preemptRevision: response.preemptRevision,
- }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- generationProtocolVersion: targetGenerationProtocolVersion,
- ...(opts?.queuedOrigin && {
- queuedOrigin: opts.queuedOrigin,
- }),
- ...carried,
- } satisfies PendingSteer;
- if (acknowledgeSteer(conversationId, localId, acknowledged)) {
- /** Terminal conversion re-homes the words as a queued
- * follow-up that sends via `ask`; the carried quotes ride
- * it there, so nothing is re-staged. */
- queueRecoveredSteer(acknowledged);
- }
- };
- if (hasPendingSteerCancel(conversationId, localId)) {
- void cancelSteer({
- conversationId,
- steerId: response.steerId,
- clientSteerId: localId,
- generationCreatedAt:
- targetGenerationCreatedAt ?? activeGenerationCreatedAt ?? undefined,
- }).then(
- ({ removed }) => {
- clearPendingSteerCancel(conversationId, localId);
- if (removed === true) {
- /* Cancel won the race against its own POST. The words are
- off the server now, so they go back to the user through
- the same boundary as an immediate cancel: whole, and
- into the queue when the composer will not take them.
- Clearing the marker without this loses the message. */
- rehomeSteer({
- steerId: response.steerId,
- clientSteerId: localId,
- text: trimmed,
- status: 'pending',
- createdAt,
- ...(files && { files }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- generationProtocolVersion: targetGenerationProtocolVersion,
- ...(opts?.queuedOrigin && { queuedOrigin: opts.queuedOrigin }),
- ...carried,
- });
- return;
- }
- /* The server kept the steer: it is live and will still
- reach the agent. The chip the optimistic cancel hid
- comes back through the ordinary acknowledgement, so it
- settles like any other accepted steer. */
- acceptResponse();
- showToast({
- message: localize('com_ui_steer_already_applied'),
- status: 'info',
- });
- },
- () => {
- clearPendingSteerCancel(conversationId, localId);
- /* Unknown outcome, but the POST was accepted: treat the
- steer as live rather than claiming it is gone. */
- acceptResponse();
- showToast({
- message: localize('com_ui_steer_cancel_failed'),
- status: 'warning',
- });
- },
- );
- return;
- }
- acceptResponse();
- } finally {
- settleDispatch();
- }
- },
- onError: (error) => {
- try {
- clearPendingSteerCancel(conversationId, localId);
- if (isSteerAcceptedOrSettled(conversationId, localId)) {
- replaceSteerChip(conversationId, localId, null);
- return;
- }
- const code = getSteerErrorCode(error);
- const originStillVisible = visibleConversationRef.current === conversationId;
- if (code === 'NO_ACTIVE_RUN') {
- // The run finished before the steer landed. While the final SSE
- // is still settling, `ask()`'s in-flight guard would drop a
- // direct send: queue it so the run-end drain fires it instead.
- // The explicit empty array stops `ask` from vacuuming composer
- // files staged for a DIFFERENT draft. A refused send (`false`)
- // falls back to the queue too: the chip is already gone, so
- // dropping the text here would lose it silently.
- replaceSteerChip(conversationId, localId, null);
- if (
- !originStillVisible ||
- isSubmittingRef.current ||
- sendNow(trimmed, files ?? [], fallbackContext) === false
- ) {
- restoreRejectedSteer();
- }
- return;
- }
- if (
- code === 'RUN_PAUSED' ||
- code === 'STEER_UNSUPPORTED' ||
- code === 'STEER_QUEUE_FULL'
- ) {
- replaceSteerChip(conversationId, localId, null);
- // The rejection can land AFTER the final SSE consumed the
- // run-end signal (common on an unsupported SDK near run end):
- // queueing then has nothing left to drain it, so mirror the
- // NO_ACTIVE_RUN fallback and send once submission settled:
- // queueing the refusal instead of dropping the text.
- if (originStillVisible && !isSubmittingRef.current) {
- if (sendNow(trimmed, files ?? [], fallbackContext) === false) {
- restoreRejectedSteer();
- }
- return;
- }
- restoreRejectedSteer();
- showToast({
- message: localize('com_ui_steer_paused_queued'),
- status: 'info',
- });
- return;
- }
- const errorData = (
- error as {
- response?: {
- data?: { generationProtocolVersion?: unknown };
- };
- }
- )?.response?.data;
- if (
- code === 'RUN_REPLACED' &&
- targetGenerationProtocolVersion === 2 &&
- supportsGenerationProtocolV2(errorData)
- ) {
- /** A different live generation now owns this conversation. A
- * normal-send fallback would replace that newer run (especially
- * from a stale tab), so retain the instruction for its run-end
- * drain regardless of this tab's local submission state. */
- replaceSteerChip(conversationId, localId, null);
- restoreRejectedSteer();
- showToast({
- message: localize('com_ui_steer_paused_queued'),
- status: 'info',
- });
- return;
- }
- if (isDefiniteSteerRejection(error)) {
- // A concrete origin 4xx proves the steer was rejected. Keep the
- // ordinary failed controls (edit/queue/remove/retry) instead of
- // the locked "delivery unknown" surface reserved for transport
- // and 5xx ambiguity.
- upsertSteerChip(conversationId, {
- steerId: localId,
- text: trimmed,
- status: 'failed',
- createdAt,
- ...(files && { files }),
- ...(preempt && { preempt: true }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- generationProtocolVersion: targetGenerationProtocolVersion,
- ...(opts?.queuedOrigin && {
- queuedOrigin: opts.queuedOrigin,
- }),
- ...carried,
- });
- return;
- }
- upsertSteerChip(conversationId, {
- steerId: localId,
- text: trimmed,
- status: 'failed',
- deliveryUncertain: true,
- createdAt,
- ...(files && { files }),
- ...(preempt && { preempt: true }),
- ...(targetGenerationCreatedAt != null && {
- generationCreatedAt: targetGenerationCreatedAt,
- }),
- generationProtocolVersion: targetGenerationProtocolVersion,
- ...(opts?.queuedOrigin && {
- queuedOrigin: opts.queuedOrigin,
- }),
- ...carried,
- });
- } finally {
- settleDispatch();
- }
- },
- },
- );
- });
- return true;
- },
- [
- hasRealConvoId,
- conversationId,
- upsertSteerChip,
- replaceSteerChip,
- acknowledgeSteer,
- settleReceiptReplay,
- queueRecoveredSteer,
- rehomeSteer,
- reclaimRejectedChipQuotes,
- steerMessage,
- sendNow,
- enqueue,
- restoreQueued,
- rewakeDrain,
- registerQueuedOrigin,
- isSteerAcceptedOrSettled,
- hasPendingSteerCancel,
- clearPendingSteerCancel,
- cancelSteer,
- showToast,
- localize,
- activeGenerationCreatedAt,
- activeGenerationProtocolVersion,
- scheduleSteerDispatch,
- ],
- );
+ const submitSteer = useSubmitSteer({
+ conversationId,
+ hasRealConvoId,
+ activeGenerationCreatedAt,
+ activeGenerationProtocolVersion,
+ visibleConversationRef,
+ isSubmittingRef,
+ sendNow,
+ chips,
+ rows,
+ enqueue,
+ });
/** Composer-originated steer: consumes the composer's attachments and quote
* chips so they ride the steer as one unit (the server re-fetches + encodes
diff --git a/packages/chat/src/core/steer/__tests__/attempt.spec.ts b/packages/chat/src/core/steer/__tests__/attempt.spec.ts
new file mode 100644
index 0000000000..3ea4212fdb
--- /dev/null
+++ b/packages/chat/src/core/steer/__tests__/attempt.spec.ts
@@ -0,0 +1,103 @@
+import type { SteerAttempt } from '../attempt';
+import { routeSteerFailure, steerAttemptChip } from '../attempt';
+import { createSteerDispatch } from '../dispatch';
+
+const attempt: SteerAttempt = {
+ localId: 'local-1',
+ text: 'steer',
+ createdAt: 10,
+ files: [{ file_id: 'f1', type: 'text/plain' }],
+ generationCreatedAt: 5,
+ generationProtocolVersion: 2,
+ carried: { quotes: ['q'] },
+};
+
+const failure = (status: number, data?: Record<string, unknown>) => ({
+ response: { status, data },
+});
+
+describe('steerAttemptChip', () => {
+ it('stamps the attempt onto the chip state the caller names', () => {
+ expect(steerAttemptChip(attempt, { steerId: 'local-1', status: 'sending' })).toEqual({
+ steerId: 'local-1',
+ status: 'sending',
+ text: 'steer',
+ createdAt: 10,
+ files: [{ file_id: 'f1', type: 'text/plain' }],
+ generationCreatedAt: 5,
+ generationProtocolVersion: 2,
+ quotes: ['q'],
+ });
+ });
+
+ it('omits absent files, epoch and origin', () => {
+ const chip = steerAttemptChip(
+ { ...attempt, files: undefined, generationCreatedAt: undefined, carried: {} },
+ { steerId: 's', status: 'failed', deliveryUncertain: true },
+ );
+ expect(chip).toEqual({
+ steerId: 's',
+ status: 'failed',
+ deliveryUncertain: true,
+ text: 'steer',
+ createdAt: 10,
+ generationProtocolVersion: 2,
+ });
+ });
+});
+
+describe('routeSteerFailure', () => {
+ it('routes run-state refusals to a send or the queue', () => {
+ expect(routeSteerFailure(failure(409, { code: 'NO_ACTIVE_RUN' }), 2)).toBe('send-after-run');
+ for (const code of ['RUN_PAUSED', 'STEER_UNSUPPORTED', 'STEER_QUEUE_FULL']) {
+ expect(routeSteerFailure(failure(409, { code }), 1)).toBe('send-when-idle');
+ }
+ });
+
+ it('requeues a replaced run only when both sides speak protocol v2', () => {
+ const replaced = failure(409, { code: 'RUN_REPLACED', generationProtocolVersion: 2 });
+ expect(routeSteerFailure(replaced, 2)).toBe('requeue');
+ expect(routeSteerFailure(replaced, 1)).toBe('failed');
+ expect(routeSteerFailure(failure(409, { code: 'RUN_REPLACED' }), 2)).toBe('failed');
+ });
+
+ it('keeps transport and intermediary failures uncertain', () => {
+ expect(routeSteerFailure(failure(400), 2)).toBe('failed');
+ expect(routeSteerFailure(failure(408), 2)).toBe('uncertain');
+ expect(routeSteerFailure(failure(502), 2)).toBe('uncertain');
+ expect(routeSteerFailure(new Error('network'), 2)).toBe('uncertain');
+ });
+});
+
+describe('createSteerDispatch', () => {
+ it('runs one task per key at a time, in order', () => {
+ const dispatch = createSteerDispatch();
+ const log: string[] = [];
+ const settles: Array<() => void> = [];
+ dispatch('a', (settle) => {
+ log.push('a1');
+ settles.push(settle);
+ });
+ dispatch('a', (settle) => {
+ log.push('a2');
+ settles.push(settle);
+ });
+ dispatch('b', () => log.push('b1'));
+ expect(log).toEqual(['a1', 'b1']);
+ settles[0]();
+ settles[0]();
+ expect(log).toEqual(['a1', 'b1', 'a2']);
+ });
+
+ it('releases the key when a task throws', () => {
+ const dispatch = createSteerDispatch();
+ expect(() =>
+ dispatch('a', () => {
+ throw new Error('boom');
+ }),
+ ).toThrow('boom');
+ const ran = jest.fn();
+ dispatch('a', ran);
+ expect(ran).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/chat/src/core/steer/attempt.ts b/packages/chat/src/core/steer/attempt.ts
new file mode 100644
index 0000000000..e1681c70c4
--- /dev/null
+++ b/packages/chat/src/core/steer/attempt.ts
@@ -0,0 +1,79 @@
+import type { TMessage } from 'librechat-data-provider';
+import type { PendingSteer, QueuedMessageOrigin } from './types';
+import type { GenerationProtocolVersion } from '../protocol';
+import type { SteerCarriedContext } from './steer';
+import { getSteerErrorCode, isDefiniteSteerRejection } from './errors';
+import { supportsGenerationProtocolV2 } from '../protocol';
+
+/** Everything one steer submission keeps constant across the chips it mints:
+ * the optimistic one, the acknowledged one, and every failure or recovery
+ * state, so a later conversion restores the same words, files and context. */
+export type SteerAttempt = {
+ localId: string;
+ text: string;
+ createdAt: number;
+ files?: TMessage['files'];
+ generationCreatedAt?: number;
+ generationProtocolVersion: GenerationProtocolVersion;
+ queuedOrigin?: QueuedMessageOrigin;
+ carried: SteerCarriedContext;
+};
+
+/** A chip for this attempt in the given state. Callers add the fields that
+ * differ by state (preempt label, delivery uncertainty, server correlation). */
+export function steerAttemptChip(
+ attempt: SteerAttempt,
+ chip: Pick<PendingSteer, 'steerId' | 'status'> & Partial<PendingSteer>,
+): PendingSteer {
+ return {
+ text: attempt.text,
+ createdAt: attempt.createdAt,
+ ...(attempt.files && { files: attempt.files }),
+ ...(attempt.generationCreatedAt != null && {
+ generationCreatedAt: attempt.generationCreatedAt,
+ }),
+ generationProtocolVersion: attempt.generationProtocolVersion,
+ ...(attempt.queuedOrigin && { queuedOrigin: attempt.queuedOrigin }),
+ ...attempt.carried,
+ ...chip,
+ };
+}
+
+/**
+ * What a failed steer POST means for its words:
+ * - `send-after-run`: the run ended first; send as a new turn once the pane is
+ * free, else put the words back in the queue.
+ * - `send-when-idle`: the run refused steering; send now when idle, otherwise
+ * queue them and say so.
+ * - `requeue`: a newer generation owns the conversation; never replace it.
+ * - `failed`: a definite rejection; the chip keeps its ordinary controls.
+ * - `uncertain`: delivery is unknown; the chip locks until ownership resolves.
+ */
+export type SteerFailureRoute =
+ | 'send-after-run'
+ | 'send-when-idle'
+ | 'requeue'
+ | 'failed'
+ | 'uncertain';
+
+export function routeSteerFailure(
+ error: unknown,
+ generationProtocolVersion: GenerationProtocolVersion,
+): SteerFailureRoute {
+ const code = getSteerErrorCode(error);
+ if (code === 'NO_ACTIVE_RUN') {
+ return 'send-after-run';
+ }
+ if (code === 'RUN_PAUSED' || code === 'STEER_UNSUPPORTED' || code === 'STEER_QUEUE_FULL') {
+ return 'send-when-idle';
+ }
+ const errorData = (error as { response?: { data?: unknown } } | undefined)?.response?.data;
+ if (
+ code === 'RUN_REPLACED' &&
+ generationProtocolVersion === 2 &&
+ supportsGenerationProtocolV2(errorData)
+ ) {
+ return 'requeue';
+ }
+ return isDefiniteSteerRejection(error) ? 'failed' : 'uncertain';
+}
diff --git a/packages/chat/src/core/steer/dispatch.ts b/packages/chat/src/core/steer/dispatch.ts
new file mode 100644
index 0000000000..7485bdb062
--- /dev/null
+++ b/packages/chat/src/core/steer/dispatch.ts
@@ -0,0 +1,62 @@
+/** Runs one keyed task at a time; `settle` releases the key for the next task. */
+export type SteerDispatch = (key: string, dispatch: (settle: () => void) => void) => void;
+
+/**
+ * First-party FIFO admission: validation inside the steer route can await
+ * agent ACL and attachment reads, so overlapping POSTs could otherwise reach
+ * the durable queue out of submission order. Keep one request in flight per
+ * conversation; later optimistic chips retain the epoch/id/time captured at
+ * submission and dispatch only after the prior request settles.
+ */
+export function createSteerDispatch(): SteerDispatch {
+ const queues = new Map<
+ string,
+ {
+ active: boolean;
+ pending: Array<(settle: () => void) => void>;
+ }
+ >();
+ return (key, dispatch) => {
+ const existing = queues.get(key);
+ const state = existing ?? { active: false, pending: [] };
+ if (existing == null) {
+ queues.set(key, state);
+ }
+ state.pending.push(dispatch);
+
+ const startNext = () => {
+ if (state.active) {
+ return;
+ }
+ const next = state.pending[0];
+ if (next == null) {
+ if (queues.get(key) === state) {
+ queues.delete(key);
+ }
+ return;
+ }
+ state.active = true;
+ let settled = false;
+ const settle = () => {
+ if (settled) {
+ return;
+ }
+ settled = true;
+ const index = state.pending.indexOf(next);
+ if (index >= 0) {
+ state.pending.splice(index, 1);
+ }
+ state.active = false;
+ startNext();
+ };
+ try {
+ next(settle);
+ } catch (error) {
+ settle();
+ throw error;
+ }
+ };
+
+ startNext();
+ };
+}
diff --git a/packages/chat/src/core/steer/index.ts b/packages/chat/src/core/steer/index.ts
index 687b8aebff..d79171e093 100644
--- a/packages/chat/src/core/steer/index.ts
+++ b/packages/chat/src/core/steer/index.ts
@@ -1,4 +1,6 @@
export * from './ack';
+export * from './attempt';
+export * from './dispatch';
export * from './errors';
export * from './intent';
export * from './pause';