📦 refactor: Move Steer Queue and Composer State into the Chat Package (#17155)

This commit is contained in:
Marco Beretta 2026-10-15 17:39:34 +02:00 • committed by GitHub
parent 2d1b570c63
commit e693deddb0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 471 additions and 389 deletions

View file

@ -1,81 +1,2 @@
import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
import type { TMessage } from 'librechat-data-provider';
import type { ReactNode } from 'react';
import type { QueuedMessageContext } from '~/hooks/Chat/useSteering';
/** Restores a message's text, attachments and compose-time context into the
* composer, or refuses (false) when the composer is occupied, unmounted, or
* showing another chat. A refusal means the caller must re-home the words
* somewhere else rather than drop them. */
export type RestoreToComposer = (
text: string,
files: TMessage['files'],
context: QueuedMessageContext,
originConversationId: string,
) => boolean;
/** Re-posts a conversation's spent run-end signal so its queue drain wakes. */
export type RewakeDrain = (conversationId: string) => void;
interface ComposerRestoreHost {
/** The composer publishes its guarded restore here while it is mounted. */
publish: (restore: RestoreToComposer | null) => void;
/** Resolved at call time: a recovery round-trip can settle long after the
* composer that started it has gone. */
restore: RestoreToComposer;
/** The composer publishes its drain wake-up here while it is mounted. */
publishRewake: (rewake: RewakeDrain | null) => void;
/** Resolved at call time like `restore`; a no-op with no composer mounted,
* which leaves a queued row for the next run end or an explicit send. */
rewakeDrain: RewakeDrain;
}
const refuse: RestoreToComposer = () => false;
const ComposerRestoreContext = createContext<ComposerRestoreHost>({
publish: () => {},
restore: refuse,
publishRewake: () => {},
rewakeDrain: () => {},
});
/**
* Lets surfaces outside the composer hand a message back to it: into the
* draft, or into the queue with the drain woken to pick it up.
*
* The composer is a sibling of the message list, not its ancestor, so a
* pending steer cancelled from the thread cannot reach the restore the queue
* rail gets as a prop. The pane's host holds the reference instead, and both
* sides read it here: the thread never reaches into composer state, and a
* restore that resolves after the composer unmounted refuses rather than
* writing into a dead form.
*/
export function ComposerRestoreProvider({ children }: { children?: ReactNode }) {
const restoreRef = useRef<RestoreToComposer | null>(null);
const publish = useCallback((restore: RestoreToComposer | null) => {
restoreRef.current = restore;
}, []);
const restore = useCallback<RestoreToComposer>(
(text, files, context, originConversationId) =>
restoreRef.current?.(text, files, context, originConversationId) ?? false,
[],
);
const rewakeRef = useRef<RewakeDrain | null>(null);
const publishRewake = useCallback((rewake: RewakeDrain | null) => {
rewakeRef.current = rewake;
}, []);
const rewakeDrain = useCallback<RewakeDrain>((conversationId) => {
rewakeRef.current?.(conversationId);
}, []);
const value = useMemo(
() => ({ publish, restore, publishRewake, rewakeDrain }),
[publish, restore, publishRewake, rewakeDrain],
);
return (
<ComposerRestoreContext.Provider value={value}>{children}</ComposerRestoreContext.Provider>
);
}
export function useComposerRestoreHost(): ComposerRestoreHost {
return useContext(ComposerRestoreContext);
}
export { ComposerRestoreProvider, useComposerRestoreHost } from '@librechat/chat/react';
export type { RestoreToComposer, RewakeDrain, ComposerRestoreHost } from '@librechat/chat/react';

View file

@ -1,83 +1,14 @@
import { atom } from 'jotai';
import { atomFamily } from 'jotai/utils';
import { Constants } from 'librechat-data-provider';
import type { TMessage } from 'librechat-data-provider';
import type { createStore } from 'jotai';
/** Unsaved split panes share the sentinel conversation id, so include the pane
* index until a durable id exists. Saved conversations keep their stable id. */
export const getReasoningStateKey = (
conversationId: string | null | undefined,
index: string | number,
) =>
conversationId == null || conversationId === '' || conversationId === Constants.NEW_CONVO
? `${Constants.NEW_CONVO}:${index}`
: conversationId;
/** One-shot reasoning selection owned by the composer for its next full turn. */
export const pendingReasoningOverrideFamily = atomFamily((_conversationId: string) =>
atom<TMessage['reasoningOverride']>(undefined),
);
/**
* Per-conversation queue of skill names the user invoked manually via the
* `$` popover for the next submission. Structured channel that the submit
* pipeline (`useChatFunctions.ask`) drains and pins onto the user message's
* `manualSkills` field (also echoed at the top of the payload for the
* runtime resolver), then resets to `[]`. Compose-time chips above the
* textarea read this atom directly so users see (and can dismiss) their
* current selection before hitting send.
*/
export const pendingManualSkillsByConvoId = atomFamily((_conversationId: string) =>
atom<string[]>([]),
);
/**
* Per-conversation queue of verbatim excerpts the user quoted via the
* "Add to chat" selection popup for the next submission. The submit pipeline
* (`useChatFunctions.ask`) drains this onto the user message's `quotes` field
* (which the backend merges into the model-facing text and persists for the
* `MessageQuotes` UI), then resets to `[]`. Compose-time chips above the
* textarea read this atom directly so users can see and dismiss each quote
* before sending.
*/
export const pendingQuotesByConvoId = atomFamily((_conversationId: string) => atom<string[]>([]));
export {
getReasoningStateKey,
pendingQuotesByConvoId,
pendingManualSkillsByConvoId,
clearPendingComposerContext,
pendingReasoningOverrideFamily,
clearPendingReasoningOverrides,
} from '@librechat/chat/react';
/** Landing-page lift is composer-owned UI state, scoped to its split pane. */
export const composerLiftFamily = atomFamily((_index: number) => atom(0));
/** Release every staged reasoning selection except the `keep` keys. A selection
* survives navigation by design, so members of conversations no longer on
* screen still hold one; clearing only the mounted panes would carry them
* across a sign-out. */
export const clearPendingReasoningOverrides = (
jotaiStore: ReturnType<typeof createStore>,
keep: ReadonlySet<string> = new Set(),
) => {
for (const key of Array.from(pendingReasoningOverrideFamily.getParams())) {
if (keep.has(key)) {
continue;
}
jotaiStore.set(pendingReasoningOverrideFamily(key), undefined);
pendingReasoningOverrideFamily.remove(key);
}
};
/** Release every staged quote and manual skill pick except under the `keep`
* keys. Like a reasoning selection, they survive navigation, so conversations
* no longer on screen still hold some; clearing only the mounted panes would
* carry them across a sign-out. */
export const clearPendingComposerContext = (
jotaiStore: ReturnType<typeof createStore>,
keep: ReadonlySet<string> = new Set(),
) => {
for (const family of [pendingQuotesByConvoId, pendingManualSkillsByConvoId]) {
for (const key of Array.from(family.getParams())) {
if (keep.has(key)) {
continue;
}
jotaiStore.set(family(key), []);
family.remove(key);
}
}
};

View file

@ -1,43 +1,3 @@
import { atomFamily, atomWithStorage, createJSONStorage } from 'jotai/utils';
import type { RecoveryDispositions } from '@librechat/chat';
export { blockRecovery, canRestoreRecovery, recoveryDisposition } from '@librechat/chat';
export { recoveryDispositionsFamily } from '@librechat/chat/react';
export type { RecoveryDisposition, RecoveryDispositions } from '@librechat/chat';
/** Receipt-scoped safety decisions survive remounts and reloads in this tab.
* No message content is stored. A crashed cancellation stays held, not sendable. */
export const recoveryDispositionsFamily = atomFamily((conversationId: string) =>
atomWithStorage<RecoveryDispositions>(
`steer-recovery:${conversationId}`,
{},
createJSONStorage(
() => ({
getItem(key) {
try {
return sessionStorage.getItem(key);
} catch {
return null;
}
},
setItem(key, value) {
try {
sessionStorage.setItem(key, value);
} catch {
/* Keep the in-memory safety decision. */
}
},
removeItem(key) {
try {
sessionStorage.removeItem(key);
} catch {
/* Storage may be disabled. */
}
},
}),
{
reviver: (_key, value) => (value === 'cancelling' ? 'blocked' : value),
},
),
{ getOnInit: true },
),
);

View file

@ -1,17 +1,16 @@
import { atom } from 'jotai';
import { isStoppedRun } from '@librechat/chat';
import { atomFamily, RESET } from 'jotai/utils';
import type {
RunEnd,
StoppedRun,
DetachedRun,
QueuedMessage,
DrainAfterAbort,
SettledQueuedTurnReceipt,
} from '@librechat/chat';
import type { PrimitiveAtom, Getter } from 'jotai';
export { isStoppedRun, resolveDetachedRunEnd } from '@librechat/chat';
export {
runEndByIndex,
resetQueueFamilies,
isDetachedRunManual,
detachedRunByConvoId,
drainAfterAbortByIndex,
pendingRunEndByConvoId,
stopRequestedByConvoId,
queuedMessagesByConvoId,
settledQueuedTurnReceiptsByConvoId,
pendingQueuedTurnEnqueueIdsByConvoId,
} from '@librechat/chat/react';
export type {
RunEnd,
StoppedRun,
@ -22,117 +21,3 @@ export type {
QueuedMessageOrigin,
SettledQueuedTurnReceipt,
} from '@librechat/chat';
/**
* Per-conversation client-side queue of follow-up messages. Drained one per
* run completion by `useQueueDrain` (each dequeued message starts a normal
* turn whose own final event drains the next).
*/
export const queuedMessagesByConvoId = atomFamily((_conversationId: string) =>
atom<QueuedMessage[]>([]),
);
/** Monotonic client knowledge of terminal server queue receipts. Admission
* records preserve boundary multiplicity by request identity. Other terminal
* records exist only while their original enqueue callback is outstanding. */
export const settledQueuedTurnReceiptsByConvoId = atomFamily((_conversationId: string) =>
atom<SettledQueuedTurnReceipt[]>([]),
);
/** Enqueue callbacks that can still race newer GET/cancellation evidence.
* Entries retire as soon as that one callback settles. */
export const pendingQueuedTurnEnqueueIdsByConvoId = atomFamily((_conversationId: string) =>
atom<string[]>([]),
);
/** The oldest terminal epoch in a queue of them, behind the nullable one-shot API stream writers
* use: writing a signal appends it, writing `null` consumes only the visible (oldest) one, and
* `RESET` clears them all. */
const runEndQueue = (signals: PrimitiveAtom<RunEnd[]>) =>
atom(
(get) => get(signals)[0] ?? null,
(_get, set, value: RunEnd | null | typeof RESET) => {
if (value === RESET) {
set(signals, []);
return;
}
if (value == null) {
set(signals, (prev) => prev.slice(1));
return;
}
set(signals, (prev) => [...prev, value]);
},
);
/** A pane can receive A's terminal frame after the user has navigated to and
* started B. Keep each terminal epoch until the queue drain has either parked
* or consumed it; a single replaceable slot loses A when B finishes first. */
const runEndsByIndex = atomFamily((_index: string | number) => atom<RunEnd[]>([]));
/** One-shot run-termination signal for a pane, written by the SSE final/error handlers and
* consumed by `useQueueDrain`. */
export const runEndByIndex = atomFamily((index: string | number) =>
runEndQueue(runEndsByIndex(index)),
);
/** Foreign terminal epochs are moved off the shared pane immediately. This
* per-conversation carrier is queued for the same reason as the pane carrier:
* successive epochs cannot overwrite one another while the chat is hidden. */
const pendingRunEndsByConvoId = atomFamily((_conversationId: string) => atom<RunEnd[]>([]));
export const pendingRunEndByConvoId = atomFamily((conversationId: string) =>
runEndQueue(pendingRunEndsByConvoId(conversationId)),
);
/**
* One-shot override armed by "interrupt & send": the next `aborted` run-end
* for the exact conversation generation drains the queue exactly once (a
* plain Stop press leaves queued chips for manual send). `false` remains the
* clear value used by stream reconciliation paths.
*/
export const drainAfterAbortByIndex = atomFamily((_index: string | number) =>
atom<DrainAfterAbort | false>(false),
);
export const detachedRunByConvoId = atomFamily((_conversationId: string) =>
atom<DetachedRun | null>(null),
);
export const stopRequestedByConvoId = atomFamily((_conversationId: string) =>
atom<StoppedRun | null>(null),
);
/** Whether a detached run's end must be left for a manual send instead of read from history, which
* retires its marker: the user stopped it, and a stopped response persists like a completed one
* (a stopped compaction even settles with `unfinished: false`). */
export function isDetachedRunManual(
get: Getter,
conversationId: string,
run: DetachedRun,
): boolean {
return isStoppedRun(get(stopRequestedByConvoId(conversationId)), run.generationCreatedAt);
}
const clearFamily = <Param>(family: {
getParams(): Iterable<Param>;
remove(param: Param): void;
}) => {
for (const param of [...family.getParams()]) {
family.remove(param);
}
};
/** Drops every per-key queue atom, so the next read of any key starts from its default. Isolates
* tests that share the default store. */
export function resetQueueFamilies(): void {
clearFamily(queuedMessagesByConvoId);
clearFamily(settledQueuedTurnReceiptsByConvoId);
clearFamily(pendingQueuedTurnEnqueueIdsByConvoId);
clearFamily(pendingRunEndsByConvoId);
clearFamily(pendingRunEndByConvoId);
clearFamily(drainAfterAbortByIndex);
clearFamily(runEndsByIndex);
clearFamily(runEndByIndex);
clearFamily(detachedRunByConvoId);
clearFamily(stopRequestedByConvoId);
}

View file

@ -1,53 +1 @@
/**
* Composer attachments a during-run submit has already consumed.
*
* Taking files into a steer or a queued message clears them from the composer,
* but an upload for one of them can still have async callbacks in flight
* (`loadImage`'s `onload`, HEIC conversion progress, the resize pass). Those
* callbacks write the file back with a `set`, which resurrects an attachment
* the message already owns: it reappears in the composer and rides the user's
* NEXT message too.
*
* Held outside React state because the decision is synchronous and crosses two
* hooks that never share an instance: `useSteering` consumes, `useUpdateFiles`
* writes. Ids are per-upload UUIDs (or a library file's own id), so an upload
* the user starts AFTER the submit is never confused with a consumed one.
*/
/** Bounded so a long session cannot grow the set without limit; far beyond the
* handful of callbacks that can still be in flight for one submit. */
const TAKEN_LIMIT = 200;
const takenFileIds = new Set<string>();
export function markComposerFilesTaken(fileIds: readonly string[]): void {
for (const id of fileIds) {
if (id.length === 0) {
continue;
}
takenFileIds.delete(id);
takenFileIds.add(id);
}
while (takenFileIds.size > TAKEN_LIMIT) {
const oldest = takenFileIds.values().next();
if (oldest.done === true) {
return;
}
takenFileIds.delete(oldest.value);
}
}
/** Whether a write for this id is a late callback for an already-consumed
* attachment, rather than part of an attachment the composer still holds. */
export function isComposerFileTaken(id: string): boolean {
return takenFileIds.has(id);
}
/**
* Forgets a consumed id, so the SAME file can be attached again on purpose.
* Re-attaching a library file reuses its server id, and a permanent mark would
* make that attachment silently impossible for the rest of the session.
*/
export function releaseComposerFile(id: string): void {
takenFileIds.delete(id);
}
export { markComposerFilesTaken, isComposerFileTaken, releaseComposerFile } from '@librechat/chat';

View file

@ -0,0 +1,53 @@
/**
* Composer attachments a during-run submit has already consumed.
*
* Taking files into a steer or a queued message clears them from the composer,
* but an upload for one of them can still have async callbacks in flight
* (`loadImage`'s `onload`, HEIC conversion progress, the resize pass). Those
* callbacks write the file back with a `set`, which resurrects an attachment
* the message already owns: it reappears in the composer and rides the user's
* NEXT message too.
*
* Held outside React state because the decision is synchronous and crosses two
* hooks that never share an instance: `useSteering` consumes, `useUpdateFiles`
* writes. Ids are per-upload UUIDs (or a library file's own id), so an upload
* the user starts AFTER the submit is never confused with a consumed one.
*/
/** Bounded so a long session cannot grow the set without limit; far beyond the
* handful of callbacks that can still be in flight for one submit. */
const TAKEN_LIMIT = 200;
const takenFileIds = new Set<string>();
export function markComposerFilesTaken(fileIds: readonly string[]): void {
for (const id of fileIds) {
if (id.length === 0) {
continue;
}
takenFileIds.delete(id);
takenFileIds.add(id);
}
while (takenFileIds.size > TAKEN_LIMIT) {
const oldest = takenFileIds.values().next();
if (oldest.done === true) {
return;
}
takenFileIds.delete(oldest.value);
}
}
/** Whether a write for this id is a late callback for an already-consumed
* attachment, rather than part of an attachment the composer still holds. */
export function isComposerFileTaken(id: string): boolean {
return takenFileIds.has(id);
}
/**
* Forgets a consumed id, so the SAME file can be attached again on purpose.
* Re-attaching a library file reuses its server id, and a permanent mark would
* make that attachment silently impossible for the rest of the session.
*/
export function releaseComposerFile(id: string): void {
takenFileIds.delete(id);
}

View file

@ -6,6 +6,7 @@ export * from './steps';
export * from './steer';
export * from './types';
export * from './files';
export * from './composer';
export * from './reducer';
export * from './protocol';
export * from './transport';

View file

@ -27,3 +27,26 @@ export {
activeGenerationProtocolVersionByConvoId,
} from './react/steer/atoms';
export type { RevealedQueuedTurn } from './react/steer/atoms';
export {
runEndByIndex,
resetQueueFamilies,
isDetachedRunManual,
detachedRunByConvoId,
drainAfterAbortByIndex,
pendingRunEndByConvoId,
stopRequestedByConvoId,
queuedMessagesByConvoId,
settledQueuedTurnReceiptsByConvoId,
pendingQueuedTurnEnqueueIdsByConvoId,
} from './react/steer/queue';
export { recoveryDispositionsFamily } from './react/steer/recovery';
export { ComposerRestoreProvider, useComposerRestoreHost } from './react/steer/restore';
export type { RestoreToComposer, RewakeDrain, ComposerRestoreHost } from './react/steer/restore';
export {
getReasoningStateKey,
pendingQuotesByConvoId,
pendingManualSkillsByConvoId,
clearPendingComposerContext,
pendingReasoningOverrideFamily,
clearPendingReasoningOverrides,
} from './react/composer';

View file

@ -0,0 +1,84 @@
import { atom } from 'jotai';
import { atomFamily } from 'jotai/utils';
import { Constants } from 'librechat-data-provider';
import type { TMessage } from 'librechat-data-provider';
import type { PrimitiveAtom, createStore } from 'jotai';
import type { Family } from './steer/family';
/** Unsaved split panes share the sentinel conversation id, so include the pane
* index until a durable id exists. Saved conversations keep their stable id. */
export const getReasoningStateKey = (
conversationId: string | null | undefined,
index: string | number,
): string =>
conversationId == null || conversationId === '' || conversationId === Constants.NEW_CONVO
? `${Constants.NEW_CONVO}:${index}`
: conversationId;
/** One-shot reasoning selection owned by the composer for its next full turn. */
export const pendingReasoningOverrideFamily: Family<
TMessage['reasoningOverride'],
PrimitiveAtom<TMessage['reasoningOverride']>
> = atomFamily((_conversationId: string) => atom<TMessage['reasoningOverride']>(undefined));
/**
* Per-conversation queue of skill names the user invoked manually via the
* `$` popover for the next submission. Structured channel that the submit
* pipeline (`useChatFunctions.ask`) drains and pins onto the user message's
* `manualSkills` field (also echoed at the top of the payload for the
* runtime resolver), then resets to `[]`. Compose-time chips above the
* textarea read this atom directly so users see (and can dismiss) their
* current selection before hitting send.
*/
export const pendingManualSkillsByConvoId: Family<string[]> = atomFamily(
(_conversationId: string) => atom<string[]>([]),
);
/**
* Per-conversation queue of verbatim excerpts the user quoted via the
* "Add to chat" selection popup for the next submission. The submit pipeline
* (`useChatFunctions.ask`) drains this onto the user message's `quotes` field
* (which the backend merges into the model-facing text and persists for the
* `MessageQuotes` UI), then resets to `[]`. Compose-time chips above the
* textarea read this atom directly so users can see and dismiss each quote
* before sending.
*/
export const pendingQuotesByConvoId: Family<string[]> = atomFamily((_conversationId: string) =>
atom<string[]>([]),
);
/** Release every staged reasoning selection except the `keep` keys. A selection
* survives navigation by design, so members of conversations no longer on
* screen still hold one; clearing only the mounted panes would carry them
* across a sign-out. */
export const clearPendingReasoningOverrides = (
jotaiStore: ReturnType<typeof createStore>,
keep: ReadonlySet<string> = new Set(),
): void => {
for (const key of Array.from(pendingReasoningOverrideFamily.getParams())) {
if (keep.has(key)) {
continue;
}
jotaiStore.set(pendingReasoningOverrideFamily(key), undefined);
pendingReasoningOverrideFamily.remove(key);
}
};
/** Release every staged quote and manual skill pick except under the `keep`
* keys. Like a reasoning selection, they survive navigation, so conversations
* no longer on screen still hold some; clearing only the mounted panes would
* carry them across a sign-out. */
export const clearPendingComposerContext = (
jotaiStore: ReturnType<typeof createStore>,
keep: ReadonlySet<string> = new Set(),
): void => {
for (const family of [pendingQuotesByConvoId, pendingManualSkillsByConvoId]) {
for (const key of Array.from(family.getParams())) {
if (keep.has(key)) {
continue;
}
jotaiStore.set(family(key), []);
family.remove(key);
}
}
};

View file

@ -1,15 +1,14 @@
import { createStore } from 'jotai';
import { ContentTypes } from 'librechat-data-provider';
import type { TMessage } from 'librechat-data-provider';
import type { DetachedRun } from '../queue';
import type { DetachedRun } from '../../../core/steer/types';
import {
settledQueuedTurnReceiptsByConvoId,
queuedMessagesByConvoId,
stopRequestedByConvoId,
resolveDetachedRunEnd,
isDetachedRunManual,
isStoppedRun,
} from '../queue';
import { resolveDetachedRunEnd, isStoppedRun } from '../../../core/steer/queue';
const CONVO_ID = 'convo-detached';
const USER_ID = 'user-1';

View file

@ -1,10 +1,11 @@
/** @jest-environment jsdom */
import { createStore } from 'jotai';
import {
blockRecovery,
canRestoreRecovery,
recoveryDisposition,
recoveryDispositionsFamily,
} from './recovery';
} from '../../../core/steer/recovery';
import { recoveryDispositionsFamily } from '../recovery';
const item = { recoverySteerId: 'source' };

View file

@ -4,11 +4,7 @@ import type { TMessage } from 'librechat-data-provider';
import type { Atom, PrimitiveAtom } from 'jotai';
import type { GenerationProtocolVersion } from '../../core/protocol';
import type { PendingSteer } from '../../core/steer/types';
/** One atom per key, created on first read; `getParams`/`remove` let tests and teardown drop them. */
type Family<Value, AtomType extends Atom<Value> = PrimitiveAtom<Value>> = ReturnType<
typeof atomFamily<string, AtomType>
>;
import type { Family } from './family';
/**
* Set synchronously before a bubble's arm request and cleared on settlement.

View file

@ -0,0 +1,9 @@
import type { Atom, PrimitiveAtom } from 'jotai';
import type { atomFamily } from 'jotai/utils';
/** One atom per key, created on first read; `getParams`/`remove` let tests and teardown drop them. */
export type Family<
Value,
AtomType extends Atom<Value> = PrimitiveAtom<Value>,
Param = string,
> = ReturnType<typeof atomFamily<Param, AtomType>>;

View file

@ -0,0 +1,139 @@
import { atom } from 'jotai';
import { atomFamily, RESET } from 'jotai/utils';
import type { Getter, PrimitiveAtom, WritableAtom } from 'jotai';
import type {
RunEnd,
StoppedRun,
DetachedRun,
QueuedMessage,
DrainAfterAbort,
SettledQueuedTurnReceipt,
} from '../../core/steer/types';
import type { Family } from './family';
import { isStoppedRun } from '../../core/steer/queue';
/** A chat pane, keyed by its index (`0` for the main chat). */
type PaneKey = string | number;
/** Reads the oldest queued run end; writes append one, `null` consumes it, `RESET` clears all. */
type RunEndQueue = WritableAtom<RunEnd | null, [RunEnd | null | typeof RESET], void>;
/**
* Per-conversation client-side queue of follow-up messages. Drained one per
* run completion by `useQueueDrain` (each dequeued message starts a normal
* turn whose own final event drains the next).
*/
export const queuedMessagesByConvoId: Family<QueuedMessage[]> = atomFamily(
(_conversationId: string) => atom<QueuedMessage[]>([]),
);
/** Monotonic client knowledge of terminal server queue receipts. Admission
* records preserve boundary multiplicity by request identity. Other terminal
* records exist only while their original enqueue callback is outstanding. */
export const settledQueuedTurnReceiptsByConvoId: Family<SettledQueuedTurnReceipt[]> = atomFamily(
(_conversationId: string) => atom<SettledQueuedTurnReceipt[]>([]),
);
/** Enqueue callbacks that can still race newer GET/cancellation evidence.
* Entries retire as soon as that one callback settles. */
export const pendingQueuedTurnEnqueueIdsByConvoId: Family<string[]> = atomFamily(
(_conversationId: string) => atom<string[]>([]),
);
/** The oldest terminal epoch in a queue of them, behind the nullable one-shot API stream writers
* use: writing a signal appends it, writing `null` consumes only the visible (oldest) one, and
* `RESET` clears them all. */
const runEndQueue = (signals: PrimitiveAtom<RunEnd[]>): RunEndQueue =>
atom(
(get) => get(signals)[0] ?? null,
(_get, set, value: RunEnd | null | typeof RESET) => {
if (value === RESET) {
set(signals, []);
return;
}
if (value == null) {
set(signals, (prev) => prev.slice(1));
return;
}
set(signals, (prev) => [...prev, value]);
},
);
/** A pane can receive A's terminal frame after the user has navigated to and
* started B. Keep each terminal epoch until the queue drain has either parked
* or consumed it; a single replaceable slot loses A when B finishes first. */
const runEndsByIndex: Family<RunEnd[], PrimitiveAtom<RunEnd[]>, PaneKey> = atomFamily(
(_index: string | number) => atom<RunEnd[]>([]),
);
/** One-shot run-termination signal for a pane, written by the SSE final/error handlers and
* consumed by `useQueueDrain`. */
export const runEndByIndex: Family<RunEnd | null, RunEndQueue, PaneKey> = atomFamily(
(index: string | number) => runEndQueue(runEndsByIndex(index)),
);
/** Foreign terminal epochs are moved off the shared pane immediately. This
* per-conversation carrier is queued for the same reason as the pane carrier:
* successive epochs cannot overwrite one another while the chat is hidden. */
const pendingRunEndsByConvoId: Family<RunEnd[]> = atomFamily((_conversationId: string) =>
atom<RunEnd[]>([]),
);
export const pendingRunEndByConvoId: Family<RunEnd | null, RunEndQueue> = atomFamily(
(conversationId: string) => runEndQueue(pendingRunEndsByConvoId(conversationId)),
);
/**
* One-shot override armed by "interrupt & send": the next `aborted` run-end
* for the exact conversation generation drains the queue exactly once (a
* plain Stop press leaves queued chips for manual send). `false` remains the
* clear value used by stream reconciliation paths.
*/
export const drainAfterAbortByIndex: Family<
DrainAfterAbort | false,
PrimitiveAtom<DrainAfterAbort | false>,
PaneKey
> = atomFamily((_index: string | number) => atom<DrainAfterAbort | false>(false));
export const detachedRunByConvoId: Family<DetachedRun | null> = atomFamily(
(_conversationId: string) => atom<DetachedRun | null>(null),
);
export const stopRequestedByConvoId: Family<StoppedRun | null> = atomFamily(
(_conversationId: string) => atom<StoppedRun | null>(null),
);
/** Whether a detached run's end must be left for a manual send instead of read from history, which
* retires its marker: the user stopped it, and a stopped response persists like a completed one
* (a stopped compaction even settles with `unfinished: false`). */
export function isDetachedRunManual(
get: Getter,
conversationId: string,
run: DetachedRun,
): boolean {
return isStoppedRun(get(stopRequestedByConvoId(conversationId)), run.generationCreatedAt);
}
const clearFamily = <Param>(family: {
getParams(): Iterable<Param>;
remove(param: Param): void;
}) => {
for (const param of [...family.getParams()]) {
family.remove(param);
}
};
/** Drops every per-key queue atom, so the next read of any key starts from its default. Isolates
* tests that share the default store. */
export function resetQueueFamilies(): void {
clearFamily(queuedMessagesByConvoId);
clearFamily(settledQueuedTurnReceiptsByConvoId);
clearFamily(pendingQueuedTurnEnqueueIdsByConvoId);
clearFamily(pendingRunEndsByConvoId);
clearFamily(pendingRunEndByConvoId);
clearFamily(drainAfterAbortByIndex);
clearFamily(runEndsByIndex);
clearFamily(runEndByIndex);
clearFamily(detachedRunByConvoId);
clearFamily(stopRequestedByConvoId);
}

View file

@ -0,0 +1,51 @@
import { atomFamily, atomWithStorage, createJSONStorage } from 'jotai/utils';
import type { WritableAtom } from 'jotai';
import type { RESET } from 'jotai/utils';
import type { RecoveryDispositions } from '../../core/steer/recovery';
import type { Family } from './family';
type SetStateActionWithReset<Value> =
| Value
| typeof RESET
| ((prev: Value) => Value | typeof RESET);
/** Receipt-scoped safety decisions survive remounts and reloads in this tab.
* No message content is stored. A crashed cancellation stays held, not sendable. */
export const recoveryDispositionsFamily: Family<
RecoveryDispositions,
WritableAtom<RecoveryDispositions, [SetStateActionWithReset<RecoveryDispositions>], void>
> = atomFamily((conversationId: string) =>
atomWithStorage<RecoveryDispositions>(
`steer-recovery:${conversationId}`,
{},
createJSONStorage(
() => ({
getItem(key) {
try {
return sessionStorage.getItem(key);
} catch {
return null;
}
},
setItem(key, value) {
try {
sessionStorage.setItem(key, value);
} catch {
/* Keep the in-memory safety decision. */
}
},
removeItem(key) {
try {
sessionStorage.removeItem(key);
} catch {
/* Storage may be disabled. */
}
},
}),
{
reviver: (_key, value) => (value === 'cancelling' ? 'blocked' : value),
},
),
{ getOnInit: true },
),
);

View file

@ -0,0 +1,81 @@
import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
import type { TMessage } from 'librechat-data-provider';
import type { ReactNode } from 'react';
import type { QueuedMessageContext } from '../../core/steer/types';
/** Restores a message's text, attachments and compose-time context into the
* composer, or refuses (false) when the composer is occupied, unmounted, or
* showing another chat. A refusal means the caller must re-home the words
* somewhere else rather than drop them. */
export type RestoreToComposer = (
text: string,
files: TMessage['files'],
context: QueuedMessageContext,
originConversationId: string,
) => boolean;
/** Re-posts a conversation's spent run-end signal so its queue drain wakes. */
export type RewakeDrain = (conversationId: string) => void;
export interface ComposerRestoreHost {
/** The composer publishes its guarded restore here while it is mounted. */
publish: (restore: RestoreToComposer | null) => void;
/** Resolved at call time: a recovery round-trip can settle long after the
* composer that started it has gone. */
restore: RestoreToComposer;
/** The composer publishes its drain wake-up here while it is mounted. */
publishRewake: (rewake: RewakeDrain | null) => void;
/** Resolved at call time like `restore`; a no-op with no composer mounted,
* which leaves a queued row for the next run end or an explicit send. */
rewakeDrain: RewakeDrain;
}
const refuse: RestoreToComposer = () => false;
const ComposerRestoreContext = createContext<ComposerRestoreHost>({
publish: () => {},
restore: refuse,
publishRewake: () => {},
rewakeDrain: () => {},
});
/**
* Lets surfaces outside the composer hand a message back to it: into the
* draft, or into the queue with the drain woken to pick it up.
*
* The composer is a sibling of the message list, not its ancestor, so a
* pending steer cancelled from the thread cannot reach the restore the queue
* rail gets as a prop. The pane's host holds the reference instead, and both
* sides read it here: the thread never reaches into composer state, and a
* restore that resolves after the composer unmounted refuses rather than
* writing into a dead form.
*/
export function ComposerRestoreProvider({ children }: { children?: ReactNode }): ReactNode {
const restoreRef = useRef<RestoreToComposer | null>(null);
const publish = useCallback((restore: RestoreToComposer | null) => {
restoreRef.current = restore;
}, []);
const restore = useCallback<RestoreToComposer>(
(text, files, context, originConversationId) =>
restoreRef.current?.(text, files, context, originConversationId) ?? false,
[],
);
const rewakeRef = useRef<RewakeDrain | null>(null);
const publishRewake = useCallback((rewake: RewakeDrain | null) => {
rewakeRef.current = rewake;
}, []);
const rewakeDrain = useCallback<RewakeDrain>((conversationId) => {
rewakeRef.current?.(conversationId);
}, []);
const value = useMemo(
() => ({ publish, restore, publishRewake, rewakeDrain }),
[publish, restore, publishRewake, rewakeDrain],
);
return (
<ComposerRestoreContext.Provider value={value}>{children}</ComposerRestoreContext.Provider>
);
}
export function useComposerRestoreHost(): ComposerRestoreHost {
return useContext(ComposerRestoreContext);
}